openapi: 3.1.0
info:
  title: PlatPhorm Contacts public API
  version: 0.5.0
  description: Public health and discovery metadata. Contact values remain browser-local and are never available through this API.
servers:
  - url: https://contacts.platphormnews.com
paths:
  /api/health:
    get:
      summary: Read service health and privacy boundary
      operationId: getHealth
      responses:
        "200":
          description: Standard success envelope
  /api/v1/health:
    get:
      summary: Read versioned service health
      operationId: getHealthV1
      responses:
        "200":
          description: Standard success envelope
  /api/docs:
    get:
      summary: Read the JSON OpenAPI document
      operationId: getApiDocs
      responses:
        "200":
          description: OpenAPI document
  /api/mcp:
    get:
      summary: Read metadata-only MCP usage
      operationId: getMcpMetadata
      responses:
        "200":
          description: Standard success envelope
    post:
      summary: Call metadata-only MCP methods
      description: JSON-RPC 2.0 only. The server cannot access browser-local contacts.
      operationId: callMcp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                - type: array
      responses:
        "200":
          description: JSON-RPC 2.0 response
  /api/v1/connected/publish:
    post:
      summary: Publish one explicitly generated CSV to Files or Sheets
      description: Protected opt-in transfer through Data Studio, capped at 4 MiB. The key and source file are not retained by Contacts.
      operationId: publishConnectedExport
      security:
        - PlatPhormBearer: []
        - PlatPhormHeader: []
      responses:
        "201":
          description: Durable destination receipt
        "401":
          description: PLATPHORM_API_KEY required
        "413":
          description: Generated export exceeds 4 MiB
        "502":
          description: Destination transfer failed
components:
  securitySchemes:
    PlatPhormBearer:
      type: http
      scheme: bearer
      bearerFormat: PLATPHORM_API_KEY
      description: Required for future protected PlatPhorm mutations. No contact-record server mutations are currently exposed.
    PlatPhormHeader:
      type: apiKey
      in: header
      name: X-PlatPhorm-API-Key
      description: Alternate PLATPHORM_API_KEY header for protected PlatPhorm operations.