openapi: 3.1.0
info: 
  title: Space News API
  description: "Public SpaceX, Starbase, Boca Chica, South Padre Island, and Cameron County space-news aggregation API."
  version: "1.0.0-phase1"
  contact: 
    name: PlatPhormNews
    url: "https://platphormnews.com"
servers: 
  - 
    url: "https://space.platphormnews.com"
    description: Space News production
tags: 
  - 
    name: News
    description: Public news feed and search
  - 
    name: Sources
    description: Public source registry and freshness
  - 
    name: AI
    description: Backend model scaffolding with honest degraded fallback
  - 
    name: Platform
    description: "Health, discovery, and MCP metadata"
paths: 
  /api/health: 
    get: 
      summary: Platform health summary
      description: "Public-safe endpoint. No API key is required in Phase 1."
      responses: 
        200: 
          description: Standard PlatPhorm response
          content: 
            application/json: 
              schema: 
                type: object
                properties: 
                  ok: 
                    type: boolean
                  data: 
                    type: object
  /api/v1/health: 
    get: 
      summary: Versioned platform health summary
      description: "Public-safe endpoint. No API key is required in Phase 1."
      responses: 
        200: 
          description: Standard PlatPhorm response
          content: 
            application/json: 
              schema: 
                type: object
                properties: 
                  ok: 
                    type: boolean
                  data: 
                    type: object
  /api/v1/news: 
    get: 
      summary: List public Space News feed items
      description: "Public-safe endpoint. No API key is required in Phase 1."
      responses: 
        200: 
          description: Standard PlatPhorm response
          content: 
            application/json: 
              schema: 
                type: object
                properties: 
                  ok: 
                    type: boolean
                  data: 
                    type: object
  /api/v1/news/{id}: 
    get: 
      summary: Read one public Space News feed item
      description: "Public-safe endpoint. No API key is required in Phase 1."
      responses: 
        200: 
          description: Standard PlatPhorm response
          content: 
            application/json: 
              schema: 
                type: object
                properties: 
                  ok: 
                    type: boolean
                  data: 
                    type: object
  /api/v1/search: 
    get: 
      summary: Search public Space News feed items
      description: "Public-safe endpoint. No API key is required in Phase 1."
      responses: 
        200: 
          description: Standard PlatPhorm response
          content: 
            application/json: 
              schema: 
                type: object
                properties: 
                  ok: 
                    type: boolean
                  data: 
                    type: object
  /api/v1/sources: 
    get: 
      summary: List public source registry
      description: "Public-safe endpoint. No API key is required in Phase 1."
      responses: 
        200: 
          description: Standard PlatPhorm response
          content: 
            application/json: 
              schema: 
                type: object
                properties: 
                  ok: 
                    type: boolean
                  data: 
                    type: object
  /api/v1/sources/{id}: 
    get: 
      summary: Read one source registry record
      description: "Public-safe endpoint. No API key is required in Phase 1."
      responses: 
        200: 
          description: Standard PlatPhorm response
          content: 
            application/json: 
              schema: 
                type: object
                properties: 
                  ok: 
                    type: boolean
                  data: 
                    type: object
  /api/v1/categories: 
    get: 
      summary: List Space categories
      description: "Public-safe endpoint. No API key is required in Phase 1."
      responses: 
        200: 
          description: Standard PlatPhorm response
          content: 
            application/json: 
              schema: 
                type: object
                properties: 
                  ok: 
                    type: boolean
                  data: 
                    type: object
  /api/v1/locations: 
    get: 
      summary: List Space locations
      description: "Public-safe endpoint. No API key is required in Phase 1."
      responses: 
        200: 
          description: Standard PlatPhorm response
          content: 
            application/json: 
              schema: 
                type: object
                properties: 
                  ok: 
                    type: boolean
                  data: 
                    type: object
  /api/v1/live-cameras: 
    get: 
      summary: "List public live-camera links with availability labels"
      description: "Public-safe endpoint. No API key is required in Phase 1."
      responses: 
        200: 
          description: Standard PlatPhorm response
          content: 
            application/json: 
              schema: 
                type: object
                properties: 
                  ok: 
                    type: boolean
                  data: 
                    type: object
  /api/v1/sync/status: 
    get: 
      summary: Read public sync and freshness status
      description: "Public-safe endpoint. No API key is required in Phase 1."
      responses: 
        200: 
          description: Standard PlatPhorm response
          content: 
            application/json: 
              schema: 
                type: object
                properties: 
                  ok: 
                    type: boolean
                  data: 
                    type: object
  /api/v1/ai/summary: 
    post: 
      summary: "Generate or degrade latest-news summary"
      description: "Public-safe endpoint. No API key is required in Phase 1."
      tags: 
        - AI
      responses: 
        200: 
          description: Standard PlatPhorm response
          content: 
            application/json: 
              schema: 
                type: object
                properties: 
                  ok: 
                    type: boolean
                  data: 
                    type: object
  /api/v1/ai/ask: 
    post: 
      summary: Answer a Space question using public feed context or degraded fallback
      description: "Public-safe endpoint. No API key is required in Phase 1."
      tags: 
        - AI
      responses: 
        200: 
          description: Standard PlatPhorm response
          content: 
            application/json: 
              schema: 
                type: object
                properties: 
                  ok: 
                    type: boolean
                  data: 
                    type: object
  /api/v1/sync/run: 
    post: 
      summary: Future protected feed sync trigger
      description: "Future protected action. When enabled, this accepts Authorization: Bearer $PLATPHORM_API_KEY or X-PlatPhorm-API-Key: $PLATPHORM_API_KEY."
      tags: 
        - Sources
      security: 
        - 
          PlatPhormApiKey: 

      responses: 
        200: 
          description: Standard PlatPhorm response
          content: 
            application/json: 
              schema: 
                type: object
                properties: 
                  ok: 
                    type: boolean
                  data: 
                    type: object
  /api/mcp: 
    get: 
      summary: Read MCP metadata
      description: "Public-safe endpoint. No API key is required in Phase 1."
      tags: 
        - Platform
      responses: 
        200: 
          description: Standard PlatPhorm response
          content: 
            application/json: 
              schema: 
                type: object
                properties: 
                  ok: 
                    type: boolean
                  data: 
                    type: object
    post: 
      summary: "MCP JSON-RPC 2.0 endpoint"
      description: "Accepts JSON-RPC 2.0 object or batch for read-only public Space News tooling. Protected tools return explicit degraded/future-protected states until integrations are configured."
      tags: 
        - Platform
      responses: 
        200: 
          description: Standard PlatPhorm response
          content: 
            application/json: 
              schema: 
                type: object
                properties: 
                  ok: 
                    type: boolean
                  data: 
                    type: object
components: 
  securitySchemes: 
    PlatPhormApiKey: 
      type: apiKey
      in: header
      name: "X-PlatPhorm-API-Key"
      description: "Future protected actions use PLATPHORM_API_KEY. Public-safe Phase 1 reads do not require a key."
    PlatPhormBearer: 
      type: http
      scheme: bearer
      bearerFormat: PLATPHORM_API_KEY
      description: "Future protected actions also accept Authorization: Bearer $PLATPHORM_API_KEY."