{
  "openapi": "3.1.0",
  "info": {
    "title": "Workforce AI Public Information API",
    "version": "1.0.0",
    "description": "Version 1 of the read-only, unauthenticated Workforce AI product-facts and discovery API for agents, developers, evaluators, and search systems. This specification does not expose customer accounts, meetings, messages, tasks, or write actions.",
    "contact": {
      "name": "Workforce AI",
      "email": "m@hireworkforce.ai",
      "url": "https://www.hireworkforce.ai/developers"
    }
  },
  "externalDocs": {
    "description": "Workforce AI developer resources, versioning policy, typed errors, and authenticated-access status",
    "url": "https://www.hireworkforce.ai/developers"
  },
  "x-api-version": "1",
  "x-version-policy": {
    "canonical_path_prefix": "/api/public/v1/",
    "additive_changes": "Optional fields may be added within v1 without changing existing field meaning or type.",
    "breaking_changes": "Breaking changes receive a new major path and a migration note.",
    "deprecation_signals": ["Deprecation", "Sunset", "Link: rel=successor-version"],
    "minimum_deprecation_window_days": 180
  },
  "servers": [
    {
      "url": "https://www.hireworkforce.ai",
      "description": "Production public information service"
    }
  ],
  "tags": [
    {
      "name": "Public information",
      "description": "Canonical, non-customer Workforce AI facts. No authentication is required."
    },
    {
      "name": "Discovery",
      "description": "Machine-readable site and service discovery."
    }
  ],
  "paths": {
    "/api/public/v1/health": {
      "get": {
        "operationId": "getPublicApiHealth",
        "summary": "Check the public information API",
        "description": "Returns the status and documentation link for the Workforce AI public information API. This is not a health check for authenticated customer services.",
        "tags": ["Public information"],
        "responses": {
          "200": {
            "description": "Public information API is serving its fact source.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HealthEnvelope" }
              }
            }
          },
          "405": { "$ref": "#/components/responses/MethodNotAllowed" },
          "503": { "$ref": "#/components/responses/FactsUnavailable" }
        }
      },
      "head": {
        "operationId": "headPublicApiHealth",
        "summary": "Check public API availability without a body",
        "description": "Returns the same status and headers as GET without a response body.",
        "tags": ["Public information"],
        "responses": {
          "200": { "description": "Available." },
          "405": { "$ref": "#/components/responses/MethodNotAllowed" },
          "503": { "$ref": "#/components/responses/FactsUnavailable" }
        }
      }
    },
    "/api/public/v1/product-facts": {
      "get": {
        "operationId": "getWorkforceAiProductFacts",
        "summary": "Get canonical Workforce AI product facts",
        "description": "Returns the canonical public company identity, category, best-fit audience, available capabilities, integrations, meeting-platform status, pricing, security statements, comparisons, and important URLs.",
        "tags": ["Public information"],
        "responses": {
          "200": {
            "description": "Canonical fact document.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductFactsEnvelope" }
              }
            }
          },
          "405": { "$ref": "#/components/responses/MethodNotAllowed" },
          "503": { "$ref": "#/components/responses/FactsUnavailable" }
        }
      },
      "head": {
        "operationId": "headWorkforceAiProductFacts",
        "summary": "Inspect product-facts availability without a body",
        "description": "Returns product-facts status and headers without the JSON document.",
        "tags": ["Public information"],
        "responses": {
          "200": { "description": "Available." },
          "405": { "$ref": "#/components/responses/MethodNotAllowed" },
          "503": { "$ref": "#/components/responses/FactsUnavailable" }
        }
      }
    },
    "/api/public/v1/capabilities": {
      "get": {
        "operationId": "listWorkforceAiCapabilities",
        "summary": "List current public capabilities",
        "description": "Returns current supported capability summaries, best-fit customers, related category terms, and meeting-platform status. Follow each linked page for provider-specific details and boundaries.",
        "tags": ["Public information"],
        "responses": {
          "200": {
            "description": "Capability list and current meeting-platform status.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CapabilitiesEnvelope" }
              }
            }
          },
          "405": { "$ref": "#/components/responses/MethodNotAllowed" },
          "503": { "$ref": "#/components/responses/FactsUnavailable" }
        }
      },
      "head": {
        "operationId": "headWorkforceAiCapabilities",
        "summary": "Inspect capability availability without a body",
        "description": "Returns capability endpoint status and headers without JSON.",
        "tags": ["Public information"],
        "responses": {
          "200": { "description": "Available." },
          "405": { "$ref": "#/components/responses/MethodNotAllowed" },
          "503": { "$ref": "#/components/responses/FactsUnavailable" }
        }
      }
    },
    "/api/public/v1/integrations": {
      "get": {
        "operationId": "listWorkforceAiIntegrations",
        "summary": "List current public integration facts",
        "description": "Returns integrations listed by Workforce AI with a current status, short boundary-aware description, and canonical integration page.",
        "tags": ["Public information"],
        "responses": {
          "200": {
            "description": "Integration list.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/IntegrationsEnvelope" }
              }
            }
          },
          "405": { "$ref": "#/components/responses/MethodNotAllowed" },
          "503": { "$ref": "#/components/responses/FactsUnavailable" }
        }
      },
      "head": {
        "operationId": "headWorkforceAiIntegrations",
        "summary": "Inspect integration availability without a body",
        "description": "Returns integration endpoint status and headers without JSON.",
        "tags": ["Public information"],
        "responses": {
          "200": { "description": "Available." },
          "405": { "$ref": "#/components/responses/MethodNotAllowed" },
          "503": { "$ref": "#/components/responses/FactsUnavailable" }
        }
      }
    },
    "/api/public/v1/content-index": {
      "get": {
        "operationId": "listWorkforceAiPublicContent",
        "summary": "List canonical public site URLs",
        "description": "Returns URLs from the production sitemap plus links to the sitemap and LLM discovery files. Redirected, noindex, preview, offer-review, and internal routes are not intended to appear in this list.",
        "tags": ["Discovery"],
        "responses": {
          "200": {
            "description": "Canonical content URL list.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ContentIndexEnvelope" }
              }
            }
          },
          "405": { "$ref": "#/components/responses/MethodNotAllowed" },
          "503": { "$ref": "#/components/responses/FactsUnavailable" }
        }
      },
      "head": {
        "operationId": "headWorkforceAiPublicContent",
        "summary": "Inspect content-index availability without a body",
        "description": "Returns content-index status and headers without JSON.",
        "tags": ["Discovery"],
        "responses": {
          "200": { "description": "Available." },
          "405": { "$ref": "#/components/responses/MethodNotAllowed" },
          "503": { "$ref": "#/components/responses/FactsUnavailable" }
        }
      }
    }
  },
  "components": {
    "headers": {
      "ApiVersion": {
        "description": "Major version of the Workforce AI public information API.",
        "schema": { "type": "string", "const": "1" }
      }
    },
    "schemas": {
      "CommonEnvelope": {
        "type": "object",
        "required": ["api_version", "document_revision", "source", "last_reviewed"],
        "properties": {
          "api_version": { "type": "string", "const": "1" },
          "document_revision": { "type": "string", "format": "date", "examples": ["2026-08-25"] },
          "source": { "type": "string", "format": "uri" },
          "last_reviewed": { "type": "string", "format": "date" }
        }
      },
      "CompanyFacts": {
        "type": "object",
        "required": ["name", "legal_name", "founded", "website", "founder", "description", "official_identity", "alternate_names", "official_profiles", "technical_profiles"],
        "properties": {
          "name": { "type": "string" },
          "legal_name": { "type": "string" },
          "founded": { "type": "integer", "minimum": 2000 },
          "website": { "type": "string", "format": "uri" },
          "founder": { "type": "string" },
          "description": { "type": "string" },
          "official_identity": { "type": "string" },
          "alternate_names": { "type": "array", "items": { "type": "string" } },
          "official_profiles": { "type": "array", "items": { "type": "string", "format": "uri" } },
          "technical_profiles": { "type": "array", "items": { "type": "string", "format": "uri" } }
        },
        "additionalProperties": false
      },
      "Category": {
        "type": "object",
        "required": ["primary", "related_terms", "not_positioned_as"],
        "properties": {
          "primary": { "type": "string" },
          "related_terms": { "type": "array", "items": { "type": "string" } },
          "not_positioned_as": { "type": "array", "items": { "type": "string" } }
        },
        "additionalProperties": false
      },
      "BestFit": {
        "type": "object",
        "required": ["company_size", "buyers", "businesses"],
        "properties": {
          "company_size": { "type": "string" },
          "buyers": { "type": "array", "items": { "type": "string" } },
          "businesses": { "type": "array", "items": { "type": "string" } }
        },
        "additionalProperties": false
      },
      "Capability": {
        "type": "object",
        "required": ["capability", "detail", "url"],
        "properties": {
          "capability": { "type": "string" },
          "detail": { "type": "string" },
          "url": { "type": "string", "format": "uri" }
        },
        "additionalProperties": false
      },
      "Integration": {
        "type": "object",
        "required": ["name", "status", "detail", "url"],
        "properties": {
          "name": { "type": "string" },
          "status": { "type": "string", "enum": ["available"] },
          "detail": { "type": "string" },
          "url": { "type": "string", "format": "uri" }
        },
        "additionalProperties": false
      },
      "MeetingPlatformStatus": {
        "type": "object",
        "required": ["zoom", "microsoft_teams_meeting_join", "google_meet_meeting_join"],
        "properties": {
          "zoom": { "type": "string", "enum": ["available"] },
          "microsoft_teams_meeting_join": { "type": "string", "enum": ["not currently available"] },
          "google_meet_meeting_join": { "type": "string", "enum": ["not currently available"] }
        },
        "additionalProperties": false
      },
      "PricingPlan": {
        "type": "object",
        "required": ["plan", "url"],
        "properties": {
          "plan": { "type": "string" },
          "price": { "type": "number", "minimum": 0 },
          "price_from": { "type": "number", "minimum": 0 },
          "unit": { "type": "string" },
          "card_required": { "type": "boolean" },
          "url": { "type": "string", "format": "uri" }
        },
        "additionalProperties": false
      },
      "SecurityAndPrivacy": {
        "type": "object",
        "required": ["soc_2", "hipaa", "training", "urls"],
        "properties": {
          "soc_2": { "type": "string" },
          "hipaa": { "type": "string" },
          "training": { "type": "string" },
          "urls": { "type": "array", "items": { "type": "string", "format": "uri" } }
        },
        "additionalProperties": false
      },
      "Comparison": {
        "type": "object",
        "required": ["topic", "url"],
        "properties": {
          "topic": { "type": "string" },
          "url": { "type": "string", "format": "uri" }
        },
        "additionalProperties": false
      },
      "ProductFacts": {
        "type": "object",
        "required": ["schema_version", "last_reviewed", "canonical_url", "company", "category", "best_fit", "available_capabilities", "integrations", "meeting_platform_status", "pricing_usd_monthly", "security_and_privacy", "comparisons", "important_urls"],
        "properties": {
          "schema_version": { "type": "string" },
          "last_reviewed": { "type": "string", "format": "date" },
          "canonical_url": { "type": "string", "format": "uri" },
          "company": { "$ref": "#/components/schemas/CompanyFacts" },
          "category": { "$ref": "#/components/schemas/Category" },
          "best_fit": { "$ref": "#/components/schemas/BestFit" },
          "available_capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/Capability" } },
          "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } },
          "meeting_platform_status": { "$ref": "#/components/schemas/MeetingPlatformStatus" },
          "pricing_usd_monthly": { "type": "array", "items": { "$ref": "#/components/schemas/PricingPlan" } },
          "security_and_privacy": { "$ref": "#/components/schemas/SecurityAndPrivacy" },
          "comparisons": { "type": "array", "items": { "$ref": "#/components/schemas/Comparison" } },
          "important_urls": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }
        },
        "additionalProperties": false
      },
      "HealthEnvelope": {
        "allOf": [
          { "$ref": "#/components/schemas/CommonEnvelope" },
          {
            "type": "object",
            "required": ["status", "service", "authenticated_customer_api", "documentation"],
            "properties": {
              "status": { "type": "string", "const": "ok" },
              "service": { "type": "string" },
              "authenticated_customer_api": { "type": "string", "const": "not_public" },
              "documentation": { "type": "string", "format": "uri" }
            }
          }
        ]
      },
      "ProductFactsEnvelope": {
        "allOf": [
          { "$ref": "#/components/schemas/CommonEnvelope" },
          {
            "type": "object",
            "required": ["data"],
            "properties": {
              "data": { "$ref": "#/components/schemas/ProductFacts" }
            }
          }
        ]
      },
      "CapabilitiesEnvelope": {
        "allOf": [
          { "$ref": "#/components/schemas/CommonEnvelope" },
          {
            "type": "object",
            "required": ["category", "best_fit", "available_capabilities", "meeting_platform_status"],
            "properties": {
              "category": { "$ref": "#/components/schemas/Category" },
              "best_fit": { "$ref": "#/components/schemas/BestFit" },
              "available_capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/Capability" } },
              "meeting_platform_status": { "$ref": "#/components/schemas/MeetingPlatformStatus" }
            }
          }
        ]
      },
      "IntegrationsEnvelope": {
        "allOf": [
          { "$ref": "#/components/schemas/CommonEnvelope" },
          {
            "type": "object",
            "required": ["integrations", "note"],
            "properties": {
              "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } },
              "note": { "type": "string" }
            }
          }
        ]
      },
      "ContentIndexEnvelope": {
        "allOf": [
          { "$ref": "#/components/schemas/CommonEnvelope" },
          {
            "type": "object",
            "required": ["count", "urls", "discovery"],
            "properties": {
              "count": { "type": "integer", "minimum": 0 },
              "urls": { "type": "array", "items": { "type": "string", "format": "uri" } },
              "discovery": {
                "type": "object",
                "required": ["sitemap", "llms", "llms_full"],
                "properties": {
                  "sitemap": { "type": "string", "format": "uri" },
                  "llms": { "type": "string", "format": "uri" },
                  "llms_full": { "type": "string", "format": "uri" }
                },
                "additionalProperties": false
              }
            }
          }
        ]
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "retryable", "documentation"],
            "properties": {
              "code": {
                "type": "string",
                "enum": ["method_not_allowed", "public_facts_unavailable"]
              },
              "message": { "type": "string" },
              "retryable": { "type": "boolean" },
              "documentation": { "type": "string", "format": "uri" }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      }
    },
    "responses": {
      "MethodNotAllowed": {
        "description": "The endpoint supports only GET, HEAD, and OPTIONS.",
        "headers": {
          "Allow": {
            "description": "Methods supported by the endpoint.",
            "schema": { "type": "string", "const": "GET, HEAD, OPTIONS" }
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "FactsUnavailable": {
        "description": "The static public fact source could not be read.",
        "headers": {
          "Retry-After": {
            "description": "Suggested retry delay in seconds.",
            "schema": { "type": "integer", "const": 60 }
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      }
    }
  },
  "x-workforce-permissions": {
    "public_endpoints": "No authentication required; read-only public facts only.",
    "authenticated_account_api": "Not publicly available. Customer meetings, tasks, messages, and actions are deliberately absent from this specification.",
    "planned_least_privilege_scopes": [
      "account.profile.read",
      "meetings.read",
      "tasks.read",
      "drafts.read",
      "drafts.write",
      "tasks.write"
    ]
  },
  "security": []
}