openapi: "3.1.0"
info:
  title: "PlatPhorm API"
  version: "0.3.0"
  description: "Canonical public API gateway, API catalog, developer portal, OpenAPI registry, schema registry, MCP bridge, route tester, SDK/snippet generator, API governance layer, event/webhook contract registry, and machine-readable API operating layer for PlatPhormNews."
servers:
  - url: "https://api.platphormnews.com"
    description: "PlatPhorm API production"
tags:
  - name: "api"
    description: "PlatPhorm API system of record"
  - name: "public"
    description: "Public-safe read, discovery, validation, and dry-run routes"
  - name: "protected"
    description: "Protected actions requiring PLATPHORM_API_KEY"
paths:
  /api/health:
    get:
      operationId: "get_api_health"
      summary: "Get public API hub health"
      description: "Returns public-safe gateway, registry, discovery, route, MCP, policy, and degraded persistence state."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/services:
    get:
      operationId: "list_api_services"
      summary: "List cataloged API services"
      description: "Lists the API service registry with counts derived from registered operations."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/services/{slug}:
    get:
      operationId: "get_api_service"
      summary: "Get one API service"
      description: "Returns a service entry, operations, policy, OpenAPI artifact, health state, and source artifacts."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/products:
    get:
      operationId: "list_api_products"
      summary: "List API products"
      description: "Groups services, operations, schemas, MCP tools, event contracts, recipes, and platphormctl examples into API products."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/products/{slug}:
    get:
      operationId: "get_api_product"
      summary: "Get one API product"
      description: "Returns one API product with its service and operation memberships."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/operations:
    get:
      operationId: "list_api_operations"
      summary: "List API operations"
      description: "Lists cataloged operations and clearly labels public, protected, validation-only, degraded, and deprecated behavior."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/operations/{id}:
    get:
      operationId: "get_api_operation"
      summary: "Get one API operation"
      description: "Returns one operation and generated snippets for supported clients."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/schemas:
    get:
      operationId: "list_api_schemas"
      summary: "List schemas"
      description: "Lists common response, error, operation, policy, OpenContent, Podcasts, event, webhook, and MCP schemas."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/schemas/{id}:
    get:
      operationId: "get_api_schema"
      summary: "Get one schema"
      description: "Returns one schema artifact from the registry."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/specs:
    get:
      operationId: "list_openapi_specs"
      summary: "List OpenAPI specs"
      description: "Lists OpenAPI artifacts and validation state. Unknown downstream specs are marked degraded until a live sync verifies them."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/specs/{serviceSlug}:
    get:
      operationId: "get_openapi_spec_artifact"
      summary: "Get OpenAPI artifact"
      description: "Returns local API spec for this service, or a catalog/degraded downstream artifact with source links."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/mcp-mappings:
    get:
      operationId: "list_mcp_mappings"
      summary: "List API/MCP mappings"
      description: "Lists real local API hub MCP mappings and candidate downstream mappings that require live registry sync before being exact."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/integrations/status:
    get:
      operationId: "list_integration_status"
      summary: "List integration status"
      description: "Returns public-safe integration state for OpenContent, Podcasts, MCP, Docs, Evals, Sandbox, BrowserOps, AgentUI, Keys, Trace, and related services."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/validate/openapi:
    post:
      operationId: "validate_openapi"
      summary: "Validate an OpenAPI document"
      description: "Validates deterministic OpenAPI structure, auth policy naming, server URLs, operation IDs, response/error schemas, and secret-safe examples."
      tags:
        - "api"
        - "public"
        - "validation_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "validation_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/validate/schema:
    post:
      operationId: "validate_schema"
      summary: "Validate a JSON Schema-like document"
      description: "Performs bounded schema structure validation without calling downstream services."
      tags:
        - "api"
        - "public"
        - "validation_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "validation_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/gateway/call:
    post:
      operationId: "call_gateway"
      summary: "Call or dry-run a gateway route"
      description: "Validates a registered target, auth policy, trace propagation, redaction, and runtime mode. Downstream calls are only allowed for registered public-safe routes."
      tags:
        - "api"
        - "protected"
        - "protected_proxy"
      x-platphorm-auth: "protected"
      x-platphorm-runtime-mode: "protected_proxy"
      x-platphorm-status: "degraded"
      security:
        - PlatPhormApiKey:
[]
        - PlatPhormApiKeyHeader:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/gateway/routes:
    get:
      operationId: "list_gateway_routes"
      summary: "List gateway routes"
      description: "Lists registered gateway candidates and explains which are catalog-only, validation-only, public proxy, or protected proxy."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/test/operation:
    post:
      operationId: "test_operation"
      summary: "Test or dry-run one operation"
      description: "Runs a bounded public-safe validation or returns an honest protected/degraded state; no fake downstream result is created."
      tags:
        - "api"
        - "public"
        - "validation_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "validation_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/test/results:
    get:
      operationId: "list_test_results"
      summary: "List public test results"
      description: "Returns deterministic local validation results and explains that durable result storage is degraded when no database is configured."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/events:
    get:
      operationId: "list_events"
      summary: "List event contracts"
      description: "Lists public-safe event contracts and payload schema references."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/events/{eventType}:
    get:
      operationId: "get_event"
      summary: "Get one event contract"
      description: "Returns one event contract by type."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/webhooks:
    get:
      operationId: "list_webhooks"
      summary: "List webhook contracts"
      description: "Lists webhook endpoint contracts, auth/signing policy, retry policy, and schema references."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/webhooks/schemas:
    get:
      operationId: "list_webhook_schemas"
      summary: "List webhook schemas"
      description: "Lists webhook payload schemas."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/webhooks/test:
    post:
      operationId: "test_webhook"
      summary: "Validate a webhook test request"
      description: "Validates webhook test payload shape. Real delivery is protected and degraded without a delegated WebhookLab run."
      tags:
        - "api"
        - "protected"
        - "validation_only"
      x-platphorm-auth: "protected"
      x-platphorm-runtime-mode: "validation_only"
      x-platphorm-status: "degraded"
      security:
        - PlatPhormApiKey:
[]
        - PlatPhormApiKeyHeader:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/versions:
    get:
      operationId: "list_versions"
      summary: "List versions"
      description: "Lists API service versions and last-known version artifact state."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/deprecations:
    get:
      operationId: "list_deprecations"
      summary: "List deprecations"
      description: "Lists deprecated or sunset operations. Empty means no local deprecation is registered, not that the whole network has none."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/changelog:
    get:
      operationId: "list_changelog"
      summary: "List API changelog"
      description: "Lists public-safe API hub catalog, policy, recipe, and schema changes."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/rate-limits:
    get:
      operationId: "list_rate_limits"
      summary: "List rate limits"
      description: "Lists configured hub rate-limit policy and downstream rate-limit metadata when known."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/rate-limits/{serviceSlug}:
    get:
      operationId: "get_rate_limit"
      summary: "Get service rate-limit policy"
      description: "Returns public-safe rate-limit policy for one service."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/governance:
    get:
      operationId: "list_governance"
      summary: "List governance scores"
      description: "Scores discoverability, OpenAPI validity, schema completeness, MCP parity, docs, policy, route compliance, and no-dead-link readiness from deterministic catalog evidence."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/governance/{serviceSlug}:
    get:
      operationId: "get_governance"
      summary: "Get one governance score"
      description: "Returns one service governance score and missing evidence."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/parity:
    get:
      operationId: "list_parity"
      summary: "List API/MCP parity"
      description: "Shows OpenAPI, MCP, tools, resources, prompts, llms-index, health, sitemap, RSS/feed, policy, trace, and public/protected metadata coverage."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/parity/{serviceSlug}:
    get:
      operationId: "get_parity"
      summary: "Get one parity snapshot"
      description: "Returns one service API/MCP parity snapshot."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/snapshots:
    get:
      operationId: "list_snapshots"
      summary: "List snapshots"
      description: "Lists generated JSON registry snapshots and last-known-good/degraded persistence state."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/snapshots/refresh:
    post:
      operationId: "refresh_snapshots"
      summary: "Refresh snapshots"
      description: "Protected scaffold for refreshing network graph, OpenAPI, schemas, events, governance, parity, sitemap, RSS, and llms files."
      tags:
        - "api"
        - "protected"
        - "degraded"
      x-platphorm-auth: "protected"
      x-platphorm-runtime-mode: "degraded"
      x-platphorm-status: "degraded"
      security:
        - PlatPhormApiKey:
[]
        - PlatPhormApiKeyHeader:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/sdk:
    get:
      operationId: "list_sdk"
      summary: "List SDK snippets"
      description: "Lists generated snippet families. It does not claim published SDK packages."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/sdk/typescript:
    get:
      operationId: "get_sdk_typescript"
      summary: "Get TypeScript snippets"
      description: "Returns fetch-based TypeScript snippets for cataloged operations."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/sdk/python:
    get:
      operationId: "get_sdk_python"
      summary: "Get Python snippets"
      description: "Returns requests-based Python snippets for cataloged operations."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/sdk/curl:
    get:
      operationId: "get_sdk_curl"
      summary: "Get curl snippets"
      description: "Returns curl snippets for cataloged operations."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/sdk/postman:
    get:
      operationId: "get_sdk_postman"
      summary: "Get Postman collection status"
      description: "Returns degraded status until a real Postman/Insomnia artifact is generated."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "degraded"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/sdk/platphormctl:
    get:
      operationId: "get_sdk_platphormctl"
      summary: "Get platphormctl snippets"
      description: "Returns platphormctl inspection, OpenContent, Podcasts, MCP, trace, and CI recipes."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/snippets/{operationId}:
    get:
      operationId: "get_snippet"
      summary: "Get one generated snippet set"
      description: "Returns curl, TypeScript, Python, MCP JSON-RPC, and platphormctl snippets for one operation."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/agent-policy:
    get:
      operationId: "get_agent_policy"
      summary: "Get agent policy"
      description: "Returns public-safe agent access policy and protected action boundary."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/agent-policy/platforms:
    get:
      operationId: "list_agent_platforms"
      summary: "List agent platforms"
      description: "Lists agent platform policy entries without hardcoding unverified crawler user-agent strings."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/agent-policy/platforms/{id}:
    get:
      operationId: "get_agent_platform"
      summary: "Get agent platform policy"
      description: "Returns one agent platform policy entry."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/agent-policy/robots:
    get:
      operationId: "get_robots_policy"
      summary: "Get robots policy summary"
      description: "Returns the robots policy used to generate robots.txt."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /api/v1/agent-policy/summary:
    get:
      operationId: "get_agent_policy_summary"
      summary: "Get policy summary"
      description: "Returns public/protected access summary for agents and humans."
      tags:
        - "api"
        - "public"
        - "catalog_only"
      x-platphorm-auth: "public"
      x-platphorm-runtime-mode: "catalog_only"
      x-platphorm-status: "active"
      security:
[]
      responses:
        200:
          description: "Standard PlatPhorm API response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatPhormApiResponse"
        400:
          description: "Validation or policy error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        401:
          description: "Protected action requires PLATPHORM_API_KEY"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
components:
  securitySchemes:
    PlatPhormApiKey:
      type: "http"
      scheme: "bearer"
      description: "Use Authorization: Bearer $PLATPHORM_API_KEY for protected PlatPhorm actions."
    PlatPhormApiKeyHeader:
      type: "apiKey"
      in: "header"
      name: "X-PlatPhorm-API-Key"
      description: "Alternative protected-action header carrying PLATPHORM_API_KEY."
  schemas:
    PlatPhormApiResponse:
      type: "object"
      required:
        - "ok"
      properties:
        ok:
          type: "boolean"
        data:

        error:
          $ref: "#/components/schemas/ApiError"
    ApiError:
      type: "object"
      required:
        - "code"
        - "message"
      properties:
        code:
          type: "string"
          enum:
            - "validation_error"
            - "auth_required"
            - "forbidden"
            - "not_found"
            - "rate_limited"
            - "upstream_unavailable"
            - "upstream_timeout"
            - "schema_invalid"
            - "policy_violation"
            - "degraded"
            - "unknown"
        message:
          type: "string"
        details:
          type: "object"
          additionalProperties: true
        traceId:
          type: "string"
        remediation:
          type: "string"
    TraceMetadata:
      type: "object"
      properties:
        traceparent:
          type: "string"
        tracestate:
          type: "string"
        X-PlatPhorm-Trace-Id:
          type: "string"
        X-PlatPhorm-Span-Id:
          type: "string"
        X-PlatPhorm-Request-Id:
          type: "string"
        x-vercel-ja4-digest:
          type: "string"
          description: "Fingerprint-adjacent metadata. Raw value is never exposed publicly."
    ApiService:
      type: "object"
      required:
        - "slug"
        - "name"
        - "baseUrl"
        - "runtimeMode"
        - "status"
      properties:
        slug:
          type: "string"
        name:
          type: "string"
        baseUrl:
          type: "string"
          format: "uri"
        runtimeMode:
          type: "string"
        status:
          type: "string"
    ApiProduct:
      type: "object"
      required:
        - "slug"
        - "name"
        - "services"
        - "operations"
        - "status"
      properties:
        slug:
          type: "string"
        name:
          type: "string"
        services:
          type: "array"
          items:
            type: "string"
        operations:
          type: "array"
          items:
            type: "string"
        status:
          type: "string"
    ApiOperation:
      type: "object"
      required:
        - "id"
        - "serviceSlug"
        - "method"
        - "path"
        - "authPolicy"
        - "runtimeMode"
        - "status"
      properties:
        id:
          type: "string"
        serviceSlug:
          type: "string"
        method:
          type: "string"
        path:
          type: "string"
        authPolicy:
          type: "string"
        runtimeMode:
          type: "string"
        status:
          type: "string"
    ApiSchema:
      type: "object"
      required:
        - "id"
        - "name"
        - "kind"
        - "serviceSlug"
        - "status"
        - "schema"
      properties:
        id:
          type: "string"
        name:
          type: "string"
        kind:
          type: "string"
        serviceSlug:
          type: "string"
        status:
          type: "string"
        schema:
          type: "object"
    ApiSpecArtifact:
      type: "object"
      properties:
        serviceSlug:
          type: "string"
        url:
          type: "string"
        status:
          type: "string"
        validation:
          type: "object"
        sourceArtifacts:
          type: "array"
          items:
            type: "string"
    ApiSpecValidation:
      type: "object"
      required:
        - "valid"
        - "checks"
      properties:
        valid:
          type: "boolean"
        checks:
          type: "array"
          items:
            type: "object"
    ApiGatewayCall:
      type: "object"
      properties:
        serviceSlug:
          type: "string"
        operationId:
          type: "string"
        method:
          type: "string"
        path:
          type: "string"
        execute:
          type: "boolean"
        dryRun:
          type: "boolean"
    ApiCallTest:
      type: "object"
      properties:
        operationId:
          type: "string"
        status:
          type: "string"
        runtimeMode:
          type: "string"
        result:
          type: "object"
    ApiAgentPolicy:
      type: "object"
      properties:
        publicReadAllowed:
          type: "boolean"
        protectedActionsRequire:
          type: "string"
        platforms:
          type: "array"
    EchoContentAnalysis:
      type: "object"
      required:
        - "id"
        - "contentItemId"
        - "canonicalUrl"
        - "runtimeMode"
        - "policy"
        - "findings"
        - "revenue"
      properties:
        id:
          type: "string"
        contentItemId:
          type: "string"
        canonicalUrl:
          type: "string"
          format: "uri"
        runtimeMode:
          type: "string"
          enum:
            - "validation_only"
        urlProfile:
          type: "object"
        localSignals:
          type: "object"
        fingerprint:
          type: "object"
        policy:
          type: "object"
          properties:
            externalFetchExecuted:
              const: false
            providerCallsExecuted:
              const: false
            findingsGenerated:
              const: false
            revenueEstimated:
              const: false
        findings:
          type: "array"
          maxItems: 0
        revenue:
          type: "object"
          properties:
            status:
              const: "not_evaluated"
    OpenContentSubmissionRequest:
      type: "object"
      required:
        - "url"
      properties:
        url:
          type: "string"
          format: "uri"
        dryRun:
          type: "boolean"
        trace:
          $ref: "#/components/schemas/TraceMetadata"
    PodcastFeedIngestRequest:
      type: "object"
      required:
        - "feedUrl"
      properties:
        feedUrl:
          type: "string"
          format: "uri"
        dryRun:
          type: "boolean"
        validateOnly:
          type: "boolean"
    WebhookDeliveryPayload:
      type: "object"
      required:
        - "eventType"
        - "payload"
      properties:
        eventType:
          type: "string"
        payload:
          type: "object"
        signature:
          type: "string"
    ApiEventContract:
      type: "object"
      required:
        - "eventType"
        - "schemaId"
      properties:
        eventType:
          type: "string"
        schemaId:
          type: "string"
        producerServices:
          type: "array"
          items:
            type: "string"
x-platphorm:
  service: "api"
  publicRead: true
  protectedActionsRequire: "PLATPHORM_API_KEY"
  runtimeModes:
    - "catalog_only"
    - "public_proxy"
    - "protected_proxy"
    - "validation_only"
    - "degraded"
    - "maintenance"
  noFakeData: true
