openapi: 3.1.0
info:
  title: Spec Workbench API
  description: Canonical specification validation, repair, diff, import,
    generation, schema, contract, and spec-to-MCP tooling for PlatPhormNews.
  version: 0.1.0
  contact:
    name: PlatPhormNews
    url: https://platphormnews.com
servers:
  - url: https://spec.platphormnews.com
    description: Canonical production domain
security:
  - PlatPhormApiKey: []
  - PlatPhormBearer: []
tags:
  - name: health
    description: Health and compliance checks
  - name: specs
    description: Spec parsing, validation, repair, and storage
  - name: diff
    description: Spec diffing and breaking-change detection
  - name: generate
    description: Generation from real specs
  - name: network
    description: PlatPhorm network discovery and spec sources
  - name: mcp
    description: JSON-RPC MCP endpoint
  - name: webhooks
    description: Webhook and event contract validation and artifact generation
  - name: sandbox
    description: Sandbox test generation and protected execution handoff
  - name: agentui
    description: AgentUI form generation and compatibility previews
  - name: monitor
    description: Monitor status and health-check generation
  - name: integrations
    description: PlatPhorm network integration matrix
  - name: policy
    description: Agent, trust, public/protected, and robots policies
  - name: jobs
    description: Bounded async job API
paths:
  /api/health:
    get:
      tags:
        - health
      summary: Service health summary
      operationId: getApiHealth
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/health:
    get:
      tags:
        - health
      summary: Versioned service health summary
      operationId: getApiV1Health
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/docs:
    get:
      tags:
        - specs
      summary: OpenAPI document as JSON
      operationId: getApiDocs
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/docs:
    get:
      tags:
        - specs
      summary: Versioned OpenAPI document alias
      operationId: getApiV1Docs
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/network/graph:
    get:
      tags:
        - network
      summary: Compatibility alias for discovered network graph projection
      operationId: getApiNetworkGraph
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /openapi.yaml:
    get:
      tags:
        - specs
      summary: OpenAPI document as YAML
      operationId: getOpenapiYaml
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/specs:
    post:
      tags:
        - specs
      summary: Save a parsed spec document
      operationId: postApiV1Specs
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/specs/{id}:
    delete:
      tags:
        - specs
      summary: Archive a saved spec
      operationId: deleteApiV1SpecsId}
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/specs/{id}/versions:
    post:
      tags:
        - specs
      summary: Create a saved spec version
      operationId: postApiV1SpecsIdVersions
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/validate:
    post:
      tags:
        - specs
      summary: Validate pasted spec content
      operationId: postApiV1Validate
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/detect:
    post:
      tags:
        - specs
      summary: Detect contract type from pasted content
      operationId: postApiV1Detect
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/format:
    post:
      tags:
        - specs
      summary: Format parsed JSON or YAML contract content
      operationId: postApiV1Format
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/normalize:
    post:
      tags:
        - specs
      summary: Normalize contract content into JSON
      operationId: postApiV1Normalize
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/specs/validate:
    post:
      tags:
        - specs
      summary: Compatibility validation endpoint
      operationId: postApiV1SpecsValidate
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/specs/{id}/validate:
    post:
      tags:
        - specs
      summary: Validate a saved spec by id
      operationId: postApiV1SpecsIdValidate
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/validation-runs:
    get:
      tags:
        - specs
      summary: List validation runs when persistence is configured
      operationId: getApiV1ValidationRuns
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/validation-runs/{id}:
    get:
      tags:
        - specs
      summary: Read a validation run when persistence is configured
      operationId: getApiV1ValidationRunsId}
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/validation/runs:
    get:
      tags:
        - specs
      summary: List validation runs with Phase 4 slash-style routing
      operationId: getApiV1ValidationRuns
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/validation/runs/{id}:
    get:
      tags:
        - specs
      summary: Read a validation run with Phase 4 slash-style routing
      operationId: getApiV1ValidationRunsId}
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/validation/runs/{id}/issues:
    get:
      tags:
        - specs
      summary: Read validation issues for a run
      operationId: getApiV1ValidationRunsIdIssues
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/validation/runs/{id}/export:
    post:
      tags:
        - specs
      summary: Export validation run evidence when storage is configured
      operationId: postApiV1ValidationRunsIdExport
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/repair:
    post:
      tags:
        - specs
      summary: Suggest or apply safe repairs to pasted spec content
      operationId: postApiV1Repair
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/specs/repair:
    post:
      tags:
        - specs
      summary: Compatibility repair endpoint
      operationId: postApiV1SpecsRepair
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/specs/{id}/repair:
    post:
      tags:
        - specs
      summary: Repair a saved spec by id
      operationId: postApiV1SpecsIdRepair
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/repair-runs/{id}:
    get:
      tags:
        - specs
      summary: Read a repair run when persistence is configured
      operationId: getApiV1RepairRunsId}
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/diff:
    post:
      tags:
        - diff
      summary: Diff two pasted specs
      operationId: postApiV1Diff
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/specs/diff:
    post:
      tags:
        - diff
      summary: Compatibility diff endpoint
      operationId: postApiV1SpecsDiff
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/diff-runs:
    get:
      tags:
        - diff
      summary: List diff runs when persistence is configured
      operationId: getApiV1DiffRuns
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/diff-runs/{id}:
    get:
      tags:
        - diff
      summary: Read a diff run when persistence is configured
      operationId: getApiV1DiffRunsId}
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/diff/runs:
    get:
      tags:
        - diff
      summary: List diff runs with Phase 4 slash-style routing
      operationId: getApiV1DiffRuns
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/diff/runs/{id}:
    get:
      tags:
        - diff
      summary: Read a diff run with Phase 4 slash-style routing
      operationId: getApiV1DiffRunsId}
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/diff/runs/{id}/changes:
    get:
      tags:
        - diff
      summary: Read diff changes for a run
      operationId: getApiV1DiffRunsIdChanges
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/diff/runs/{id}/export:
    post:
      tags:
        - diff
      summary: Export diff run evidence when storage is configured
      operationId: postApiV1DiffRunsIdExport
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/contracts:
    post:
      tags:
        - specs
      summary: Create a browser-local draft descriptor or protected persistent contract
      operationId: postApiV1Contracts
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/contracts/{id}:
    delete:
      tags:
        - specs
      summary: Protected persistent contract deletion
      operationId: deleteApiV1ContractsId}
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/contracts/{id}/versions:
    post:
      tags:
        - specs
      summary: Create a local draft version descriptor or protected persistent version
      operationId: postApiV1ContractsIdVersions
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/contracts/{id}/lineage:
    get:
      tags:
        - specs
      summary: Read source-to-artifact lineage graph
      operationId: getApiV1ContractsIdLineage
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/contracts/{id}/compare/{versionId}:
    post:
      tags:
        - specs
      summary: Compare two supplied contract version payloads
      operationId: postApiV1ContractsIdCompareVersionId}
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/import:
    post:
      tags:
        - specs
      summary: Import a public trusted spec URL
      operationId: postApiV1Import
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/import/sources:
    get:
      tags:
        - specs
      summary: List PlatPhorm contract import sources
      operationId: getApiV1ImportSources
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/import/url:
    post:
      tags:
        - specs
      summary: Import a trusted public contract URL
      operationId: postApiV1ImportUrl
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/import/service:
    post:
      tags:
        - specs
      summary: Import a discovered service contract
      operationId: postApiV1ImportService
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/import/mcp-tool:
    post:
      tags:
        - mcp
      summary: Import an MCP tool schema
      operationId: postApiV1ImportMcpTool
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/import/openapi-operation:
    post:
      tags:
        - specs
      summary: Import one OpenAPI operation as a contract source
      operationId: postApiV1ImportOpenapiOperation
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/import/webhook-contract:
    post:
      tags:
        - specs
      summary: Import a webhook contract
      operationId: postApiV1ImportWebhookContract
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/import/monitor-service:
    post:
      tags:
        - monitor
      summary: Import public Monitor service metadata
      operationId: postApiV1ImportMonitorService
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/import/network:
    post:
      tags:
        - network
      summary: Import current public network contract source index
      operationId: postApiV1ImportNetwork
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/discovery:
    get:
      tags:
        - specs
      summary: Read Spec route, API, registry, gate, source, integration, and
        machine-readable discovery summary
      operationId: getApiV1Discovery
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/discovery/routes:
    get:
      tags:
        - specs
      summary: Read declared public route inventory
      operationId: getApiV1DiscoveryRoutes
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/discovery/endpoints:
    get:
      tags:
        - specs
      summary: Read declared API endpoint inventory
      operationId: getApiV1DiscoveryEndpoints
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/discovery/sources:
    get:
      tags:
        - specs
      summary: Read discovered PlatPhorm contract import sources
      operationId: getApiV1DiscoverySources
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/discovery/machine-readable:
    get:
      tags:
        - specs
      summary: Read machine-readable discovery file inventory
      operationId: getApiV1DiscoveryMachineReadable
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/demo/handoffs:
    get:
      tags:
        - specs
      summary: Read the public-safe Spec cross-tool demo handoff runway
      operationId: getApiV1DemoHandoffs
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/handoffs/prepare:
    post:
      tags:
        - specs
      summary: Prepare target-specific handoff artifacts for Spec, Root, MCP, AgentUI,
        Sandbox, and Evals
      operationId: postApiV1HandoffsPrepare
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/handoffs/dispatch:
    post:
      tags:
        - specs
      summary: Protected remote handoff dispatch preview for configured downstream
        clients
      operationId: postApiV1HandoffsDispatch
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/import/runs:
    get:
      tags:
        - specs
      summary: List import runs when persistence is configured
      operationId: getApiV1ImportRuns
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/import/runs/{id}:
    get:
      tags:
        - specs
      summary: Read an import run when persistence is configured
      operationId: getApiV1ImportRunsId}
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/import/probe:
    post:
      tags:
        - specs
      summary: Probe trusted spec URLs and return the first importable contract
      operationId: postApiV1ImportProbe
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/imports/{id}:
    get:
      tags:
        - specs
      summary: Read an import job when persistence is configured
      operationId: getApiV1ImportsId}
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/templates:
    get:
      tags:
        - specs
      summary: List public spec templates
      operationId: getApiV1Templates
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/templates/{id}:
    get:
      tags:
        - specs
      summary: Read a public spec template
      operationId: getApiV1TemplatesId}
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/templates/{id}/instantiate:
    post:
      tags:
        - specs
      summary: Instantiate a public spec template
      operationId: postApiV1TemplatesIdInstantiate
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/generate/mcp:
    post:
      tags:
        - generate
      summary: Generate MCP server scaffold files from a spec
      operationId: postApiV1GenerateMcp
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/generate:
    post:
      tags:
        - generate
      summary: Generate deterministic artifacts from a contract
      operationId: postApiV1Generate
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/generate/client:
    post:
      tags:
        - generate
      summary: Generate clients, examples, tests, and action manifests
      operationId: postApiV1GenerateClient
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/generate/tests:
    post:
      tags:
        - generate
      summary: Generate test files from a spec
      operationId: postApiV1GenerateTests
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/generate/examples:
    post:
      tags:
        - generate
      summary: Generate examples from a spec
      operationId: postApiV1GenerateExamples
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/generation-runs/{id}:
    get:
      tags:
        - specs
      summary: Read a generation run when persistence is configured
      operationId: getApiV1GenerationRunsId}
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/generation-runs/{id}/artifacts:
    get:
      tags:
        - specs
      summary: Read generation artifacts when persistence is configured
      operationId: getApiV1GenerationRunsIdArtifacts
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/generation/runs:
    get:
      tags:
        - specs
      summary: List generation runs with Phase 4 slash-style routing
      operationId: getApiV1GenerationRuns
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/generation/runs/{id}:
    get:
      tags:
        - specs
      summary: Read a generation run with Phase 4 slash-style routing
      operationId: getApiV1GenerationRunsId}
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/generation/runs/{id}/artifacts:
    get:
      tags:
        - specs
      summary: Read generation artifacts for a run
      operationId: getApiV1GenerationRunsIdArtifacts
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/artifacts/{id}:
    get:
      tags:
        - specs
      summary: Read a generated public-safe artifact when available
      operationId: getApiV1ArtifactsId}
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/artifacts/{id}/send-to/{service}:
    post:
      tags:
        - specs
      summary: Protected publish/export handoff for a generated artifact
      operationId: postApiV1ArtifactsIdSendToService}
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/jobs:
    post:
      tags:
        - jobs
      summary: Create a bounded local async job record
      operationId: postApiV1Jobs
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/jobs/{id}:
    get:
      tags:
        - jobs
      summary: Read async job status
      operationId: getApiV1JobsId}
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/jobs/{id}/events:
    get:
      tags:
        - jobs
      summary: Read async job events
      operationId: getApiV1JobsIdEvents
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/jobs/{id}/stream:
    get:
      tags:
        - jobs
      summary: Read async job event stream
      operationId: getApiV1JobsIdStream
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/jobs/{id}/cancel:
    post:
      tags:
        - jobs
      summary: Cancel an async job
      operationId: postApiV1JobsIdCancel
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/conformance/check:
    post:
      tags:
        - specs
      summary: Run bounded public-safe live conformance checks or skipped plan
      operationId: postApiV1ConformanceCheck
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/conformance/runs:
    get:
      tags:
        - specs
      summary: List conformance runs when durable storage is configured
      operationId: getApiV1ConformanceRuns
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/conformance/runs/{id}:
    get:
      tags:
        - specs
      summary: Read a conformance run when durable storage is configured
      operationId: getApiV1ConformanceRunsId}
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/conformance/runs/{id}/evidence:
    get:
      tags:
        - specs
      summary: Read conformance evidence when durable storage is configured
      operationId: getApiV1ConformanceRunsIdEvidence
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/release-gates:
    post:
      tags:
        - specs
      summary: Protected custom release gate definition
      operationId: postApiV1ReleaseGates
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/release-gates/{id}/evaluate:
    post:
      tags:
        - specs
      summary: Evaluate a contract release gate from supplied evidence
      operationId: postApiV1ReleaseGatesIdEvaluate
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/release-gates/{id}/latest:
    get:
      tags:
        - specs
      summary: Read latest release gate decision when persistence is configured
      operationId: getApiV1ReleaseGatesIdLatest
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/webhooks/contracts:
    get:
      tags:
        - webhooks
      summary: List webhook contract support and discovered public contracts
      operationId: getApiV1WebhooksContracts
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/webhooks/validate-contract:
    post:
      tags:
        - webhooks
      summary: Validate webhook contract structure
      operationId: postApiV1WebhooksValidateContract
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/webhooks/generate-payload:
    post:
      tags:
        - webhooks
      summary: Generate a webhook payload example from schema
      operationId: postApiV1WebhooksGeneratePayload
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/webhooks/generate-receiver:
    post:
      tags:
        - webhooks
      summary: Generate a webhook receiver example
      operationId: postApiV1WebhooksGenerateReceiver
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/webhooks/send-to-evals:
    post:
      tags:
        - webhooks
      summary: Protected webhook Evals handoff
      operationId: postApiV1WebhooksSendToEvals
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/webhooks/send-to-sandbox:
    post:
      tags:
        - webhooks
      summary: Protected webhook Sandbox handoff
      operationId: postApiV1WebhooksSendToSandbox
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/mcp/generate-tool:
    post:
      tags:
        - generate
      summary: Generate an MCP tool candidate from a contract
      operationId: postApiV1McpGenerateTool
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/mcp/publish-tool:
    post:
      tags:
        - mcp
      summary: Protected MCP Gateway tool candidate dispatch
      operationId: postApiV1McpPublishTool
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/agentui/generate-form:
    post:
      tags:
        - agentui
      summary: Generate AgentUI form schema from a contract
      operationId: postApiV1AgentuiGenerateForm
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/agentui/preview-form:
    post:
      tags:
        - agentui
      summary: Preview AgentUI render payload locally
      operationId: postApiV1AgentuiPreviewForm
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/agentui/send-form:
    post:
      tags:
        - agentui
      summary: Protected AgentUI form handoff
      operationId: postApiV1AgentuiSendForm
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/agentui/validate-compatibility:
    post:
      tags:
        - agentui
      summary: Validate AgentUI compatibility
      operationId: postApiV1AgentuiValidateCompatibility
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/sandbox/generate-test:
    post:
      tags:
        - sandbox
      summary: Generate a Sandbox test script
      operationId: postApiV1SandboxGenerateTest
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/sandbox/run-test:
    post:
      tags:
        - sandbox
      summary: Protected Sandbox execution handoff
      operationId: postApiV1SandboxRunTest
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/sandbox/runs/{id}:
    get:
      tags:
        - sandbox
      summary: Read Sandbox handoff run status when available
      operationId: getApiV1SandboxRunsId}
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/evals/generate-suite:
    post:
      tags:
        - generate
      summary: Generate an Evals suite draft from a contract
      operationId: postApiV1EvalsGenerateSuite
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/evals/trigger:
    post:
      tags:
        - specs
      summary: Protected Evals suite trigger handoff
      operationId: postApiV1EvalsTrigger
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/monitor/status:
    get:
      tags:
        - monitor
      summary: Read public Monitor integration status
      operationId: getApiV1MonitorStatus
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/monitor/generate-health-check:
    post:
      tags:
        - monitor
      summary: Generate Monitor health check definition
      operationId: postApiV1MonitorGenerateHealthCheck
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/monitor/publish-validation-summary:
    post:
      tags:
        - monitor
      summary: Protected Monitor validation summary publish
      operationId: postApiV1MonitorPublishValidationSummary
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/integrations:
    get:
      tags:
        - integrations
      summary: List first-class PlatPhorm integrations
      operationId: getApiV1Integrations
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/integrations/status:
    get:
      tags:
        - integrations
      summary: Read public integration matrix status
      operationId: getApiV1IntegrationsStatus
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/integrations/{service}:
    get:
      tags:
        - integrations
      summary: Read one integration status
      operationId: getApiV1IntegrationsService}
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/agent-policy:
    get:
      tags:
        - policy
      summary: Read public agent policy
      operationId: getApiV1AgentPolicy
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/agent-policy/platforms:
    get:
      tags:
        - policy
      summary: List agent platform policy records
      operationId: getApiV1AgentPolicyPlatforms
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/agent-policy/platforms/{id}:
    get:
      tags:
        - policy
      summary: Read one agent platform policy record
      operationId: getApiV1AgentPolicyPlatformsId}
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/agent-policy/robots:
    get:
      tags:
        - policy
      summary: Read robots policy summary
      operationId: getApiV1AgentPolicyRobots
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/agent-policy/summary:
    get:
      tags:
        - policy
      summary: Read public agent access summary
      operationId: getApiV1AgentPolicySummary
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/network:
    get:
      tags:
        - network
      summary: Network status and discovered sites
      operationId: getApiV1Network
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/network/graph:
    get:
      tags:
        - network
      summary: Discovered network graph projection
      operationId: getApiV1NetworkGraph
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/network/spec-sources:
    get:
      tags:
        - network
      summary: Discovered PlatPhorm spec sources
      operationId: getApiV1NetworkSpecSources
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/network/spec-sources/sync:
    post:
      tags:
        - network
      summary: Protected network spec source sync
      operationId: postApiV1NetworkSpecSourcesSync
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/network/sites:
    get:
      tags:
        - network
      summary: Discovered PlatPhorm sites
      operationId: getApiV1NetworkSites
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/network/trusted-domains:
    get:
      tags:
        - network
      summary: Trusted and pending PlatPhorm domains
      operationId: getApiV1NetworkTrustedDomains
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/network/route-compliance:
    get:
      tags:
        - network
      summary: Route compliance summary
      operationId: getApiV1NetworkRouteCompliance
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/network/spec-coverage:
    get:
      tags:
        - network
      summary: Network spec coverage summary
      operationId: getApiV1NetworkSpecCoverage
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/sitemaps/sync:
    post:
      tags:
        - specs
      summary: Protected sitemap sync
      operationId: postApiV1SitemapsSync
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/sitemaps/coverage:
    get:
      tags:
        - specs
      summary: Sitemap coverage summary
      operationId: getApiV1SitemapsCoverage
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/feeds/sync:
    post:
      tags:
        - specs
      summary: Protected feed sync
      operationId: postApiV1FeedsSync
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/feeds:
    get:
      tags:
        - specs
      summary: Public feed summary
      operationId: getApiV1Feeds
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/reports/docs:
    post:
      tags:
        - specs
      summary: Protected docs report generation
      operationId: postApiV1ReportsDocs
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/reports/sheets:
    post:
      tags:
        - specs
      summary: Protected Sheets report generation
      operationId: postApiV1ReportsSheets
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/reports/decks:
    post:
      tags:
        - specs
      summary: Protected Deck summary generation
      operationId: postApiV1ReportsDecks
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/traces:
    get:
      tags:
        - specs
      summary: Public-safe trace summaries from Trace
      operationId: getApiV1Traces
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/mcp:
    post:
      tags:
        - mcp
      summary: Spec Workbench JSON-RPC MCP endpoint
      operationId: postApiMcp
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
  /api/v1/mcp:
    post:
      tags:
        - mcp
      summary: Versioned JSON-RPC MCP endpoint alias
      operationId: postApiV1Mcp
      security: []
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestOk"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
        "401":
          description: PLATPHORM_API_KEY required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestError"
components:
  securitySchemes:
    PlatPhormApiKey:
      type: apiKey
      in: header
      name: X-PlatPhorm-API-Key
    PlatPhormBearer:
      type: http
      scheme: bearer
      bearerFormat: PLATPHORM_API_KEY
  schemas:
    RestOk:
      type: object
      required:
        - ok
        - data
      properties:
        ok:
          const: true
        data: {}
    RestError:
      type: object
      required:
        - ok
        - error
      properties:
        ok:
          const: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
