openapi: 3.1.0
info:
  title: ConstellationOS Predictions API
  version: v1
  summary: ML-native operations API for satellite fleets — connect telemetry, read fleet topology, run link forecasts.
  description: The ConstellationOS HTTP API lets satellite fleet operators ingest ground telemetry through a single schema, read the live fleet topology graph, and run ML link forecasts on live fleet context. This description is reconstructed by the API Evangelist enrichment pipeline from Constellation Space's public developer documentation (https://docs.constellation.space); it captures only the operations, scopes, and authentication that the provider documents publicly. Request/response bodies are intentionally left open where the provider does not publish a machine-readable schema — this is a discovery artifact, not the provider's authoritative OpenAPI.
  contact:
    name: Constellation Space Corp
    email: contact@constellation.space
    url: https://docs.constellation.space
  x-apievangelist-provenance:
    method: searched
    source: https://docs.constellation.space/connect/api-tokens
    note: Reconstructed from public docs; operations + scopes documented, bodies not published.
servers:
- url: https://api.constellation.space
  description: Production
- url: https://api-staging.constellation.space
  description: Staging
- url: https://api-dev.constellation.space
  description: Development
security:
- bearerAuth: []
tags:
- name: Predictions
  description: Run ML link forecasts on live fleet context.
paths:
  /api/v1/predictions/:
    post:
      operationId: runPredictions
      summary: Run ML link forecasts
      description: Run ML predictions over live fleet context. The same models power the console assistant and this Predictions API — SNR and link fade, traffic, weather, jamming, and conjunction. Requires the predictions:run token scope.
      tags:
      - Predictions
      security:
      - bearerAuth:
        - predictions:run
      responses:
        '200':
          description: Prediction results for the requested node/link/time context.
        '401':
          description: Missing, invalid, or revoked API token.
        '403':
          description: Token lacks the required predictions:run scope.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API token issued from the console (Settings -> API), sent as "Authorization: Bearer <token>". Production tokens are prefixed cos_live_ and non-production tokens cos_dev_. Tokens are scoped, shown once at creation, and can be revoked instantly.'
      x-token-prefixes:
        production: cos_live_
        non_production: cos_dev_
      x-scopes:
        topology:read: Read the fleet topology graph.
        telemetry:write: Ingest telemetry metrics.
        predictions:run: Run ML predictions.