openapi: 3.1.0
info:
  title: PlatPhorm Capability Catalog
  version: 1.0.0
  description: Static public catalog artifacts for repositories, capabilities, search, graph, and reuse recommendations.
servers:
  - url: https://catalog.platphormnews.com
paths:
  /api/health:
    get:
      summary: Static catalog health
      responses:
        '200':
          description: Catalog health and generation status
  /api/v1/health:
    get:
      summary: Versioned static catalog health
      responses:
        '200':
          description: Catalog health and generation status
  /api/mcp:
    get:
      summary: MCP server metadata and public read-only capability names
      responses:
        '200':
          description: MCP endpoint metadata
    post:
      summary: Public read-only JSON-RPC MCP transport
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: JSON-RPC response
  /catalog/generated/capabilities.json:
    get:
      summary: Global capability index
      responses:
        '200':
          description: Global capability index JSON
  /catalog/generated/repos.json:
    get:
      summary: Repository index
      responses:
        '200':
          description: Repository index JSON
  /catalog/generated/search-index.json:
    get:
      summary: Search index
      responses:
        '200':
          description: Plain JSON search index
  /catalog/generated/best-implementations.json:
    get:
      summary: Best implementation rankings
      responses:
        '200':
          description: Best reusable implementation candidates
  /catalog/generated/vision-tool-selection.json:
    get:
      summary: Vision tool selection
      responses:
        '200':
          description: Browser, PlatPhorm Content, and PlatPhorm Docs mapped to catalog capabilities
  /api/vision/capabilities:
    get:
      summary: Vision capability selection API
      responses:
        '200':
          description: Standard ok/data wrapper around the public vision selection artifact
  /api/vision/evidence-pack:
    get:
      summary: Vision evidence pack API
      responses:
        '200':
          description: Preview-only JSON and Markdown-ready evidence pack generated from catalog state
  /catalog/generated/vision-evidence-pack.json:
    get:
      summary: Static vision evidence pack
      responses:
        '200':
          description: Public read-only evidence pack artifact
  /rss.xml:
    get:
      summary: Capability update feed
      responses:
        '200':
          description: RSS feed of high-signal catalog capabilities
  /api/v1/catalog/census:
    get:
      summary: Catalog census snapshot
      responses:
        '200':
          description: Repository and dependency census generated by GitHub-native collection
        '404':
          description: Census not ready
  /api/v1/catalog/dependencies:
    get:
      summary: Dependency observations
      parameters:
        - in: query
          name: q
          required: false
          schema: { type: string }
        - in: query
          name: limit
          required: false
          schema: { type: integer, minimum: 1, maximum: 500 }
      responses:
        '200':
          description: Dependency observations with repository impact counts
        '404':
          description: Dependencies not available
  /api/v1/catalog/technologies:
    get:
      summary: Technology observations
      parameters:
        - in: query
          name: q
          required: false
          schema: { type: string }
        - in: query
          name: limit
          required: false
          schema: { type: integer, minimum: 1, maximum: 500 }
      responses:
        '200':
          description: Technology observations with evidence sources
        '404':
          description: Technologies not available
  /api/v1/catalog/publications:
    get:
      summary: Publication summaries
      parameters:
        - in: query
          name: status
          required: false
          schema: { type: string }
        - in: query
          name: limit
          required: false
          schema: { type: integer, minimum: 1, maximum: 500 }
      responses:
        '200':
          description: Publication index from local and remote storage
    post:
      summary: Publish catalog evidence payload
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Publication accepted for persistence
        '201':
          description: Publication persisted in configured GitHub destination
  /api/v1/catalog/publications/{filename}:
    get:
      summary: Fetch a publication by filename
      parameters:
        - in: path
          name: filename
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Publication payload
        '404':
          description: Publication not found
  /api/v1/scans:
    get:
      summary: Scan and publication artifact inventory
      responses:
        '200':
          description: Generated scan and publication artifact listing
  /api/v1/route-compliance:
    get:
      summary: Route compliance and protected-action status
      responses:
        '200':
          description: Route implementation status and contract metadata
components:
  securitySchemes:
    PlatPhormApiKey:
      type: apiKey
      in: header
      name: X-PlatPhorm-API-Key
      description: Protected catalog mutations require PLATPHORM_API_KEY or trusted OIDC bearer tokens. Public reads require no auth.
    PlatPhormBearer:
      type: http
      scheme: bearer
      description: "Protected catalog mutations also accept Authorization: Bearer <PLATPHORM_API_KEY or trusted OIDC token>."