openapi: 3.1.0
info:
  title: Halcyon Platform API
  version: 1.0.0-alpha
  description: >
    Versioned API surface for Halcyon institutional intelligence services.
    Halcyon Terminal is one client of this platform.
servers:
  - url: https://terminal.halcyonterminal.app
paths:
  /api/v1/health:
    get:
      summary: Platform health
      operationId: getHealth
      responses:
        "200":
          description: Halcyon Platform API is operational.
  /api/v1/cloud/health:
    get:
      summary: Halcyon Cloud dependency health
      operationId: getCloudHealth
      description: >
        Returns coarse operational health for Halcyon's cloud dependency layer,
        including Auth/Data probe state and circuit-breaker status. No credentials,
        database connection strings or privileged payloads are exposed.
      responses:
        "200":
          description: Cloud dependency is operational or partially degraded.
        "503":
          description: Core cloud dependencies are temporarily unavailable.
  /api/v1/platform:
    get:
      summary: Platform capabilities and professional areas
      operationId: getPlatform
      responses:
        "200":
          description: Platform metadata.
  /api/v1/domains:
    get:
      summary: Canonical Halcyon platform domains
      operationId: getPlatformDomains
      responses:
        "200":
          description: Domain registry, migration phase and platform status.
  /api/v1/contracts:
    get:
      summary: Canonical Halcyon service contract registry
      operationId: getPlatformContracts
      parameters:
        - name: domain
          in: query
          schema:
            type: string
        - name: family
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Versioned service contracts, access modes and route metadata.
  /api/v1/developer/capabilities:
    get:
      summary: Developer integration surfaces
      operationId: getDeveloperCapabilities
      responses:
        "200":
          description: Integration surfaces and implementation status.
  /api/v1/media/channels:
    get:
      summary: HTV live media source catalogue
      operationId: getLiveMediaChannels
      description: >
        Returns metadata for authorised live television and institutional webcast sources.
        The API returns catalogue/provenance metadata only; it does not proxy or redistribute video bytes.
      parameters:
        - name: category
          in: query
          schema:
            type: string
        - name: language
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Live-media source catalogue, rights mode and official playback metadata.
  /api/v1/finance/instruments:
    get:
      summary: Angola fixed-income master universe
      operationId: getFinanceInstruments
      description: >
        Versioned Finance service for the official RF master. Reads the protected base tables
        server-side and does not depend on the legacy browser-facing SECURITY DEFINER views.
      parameters:
        - name: view
          in: query
          schema:
            type: string
            enum: [master, resolver]
            default: master
        - name: active
          in: query
          schema:
            type: boolean
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 5000
      responses:
        "200":
          description: Official fixed-income master or resolver projection.
        "503":
          description: Finance instrument service temporarily unavailable.
  /api/v1/finance/inplay/snapshot:
    get:
      summary: Schwab-backed Stocks In Play market-intelligence snapshot
      operationId: getFinanceInPlaySnapshot
      description: >
        Authenticated terminal-only US equity radar. Uses Schwab real-time quotes for a broad scan
        and deeper extended-hours intraday history for top candidates to derive time-aligned RVOL,
        premarket participation, volume acceleration, relative strength, VWAP and trend evidence.
      parameters:
        - name: symbols
          in: query
          schema:
            type: string
          description: Optional comma-separated equities to pin into the deep-analysis set.
        - name: deep
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 48
            default: 0
      responses:
        "200":
          description: Schwab market-intelligence snapshot and ranked equity candidates.
        "401":
          description: Terminal session required.
        "503":
          description: Schwab market-data service temporarily unavailable.
  /api/v1/energy/markets:
    get:
      summary: Energy market benchmarks and history
      operationId: getEnergyMarkets
      description: >
        Versioned Energy service backed by the existing Halcyon free-market provider stack.
        The v1 contract is stable while provider internals can evolve independently.
      parameters:
        - name: mode
          in: query
          schema:
            type: string
            enum: [market-snapshot-v1, market-history-v1, health-v1]
            default: market-snapshot-v1
        - name: symbols
          in: query
          schema:
            type: string
          description: Optional comma-separated provider symbols for history filtering.
      responses:
        "200":
          description: Energy market snapshot, historical series or provider health.
        "503":
          description: Energy market service temporarily unavailable.
  /api/v1/energy/fuels/model:
    get:
      summary: Angola downstream fuel sensitivity model
      operationId: getEnergyFuelModel
      description: >
        Versioned access to the Angola fuel-model inputs, including FX, refined-product
        benchmarks, public validation and official PVP reference data.
      responses:
        "200":
          description: Current fuel-model inputs and methodology.
        "502":
          description: Fuel-model providers returned insufficient inputs.
        "503":
          description: Fuel-model service temporarily unavailable.
  /api/v1/energy/concessions:
    get:
      summary: Angola canonical petroleum concession registry
      operationId: getEnergyConcessions
      description: >
        Returns the provenance-aware Angola petroleum concession and block registry used by
        Halcyon Energy, EMAP and HGRF. Production, opportunity and participation states are
        effective-dated. Exact cadastral geometry is never synthesized; official/validated GIS
        is required before concession polygons are exposed as authoritative boundaries.
      parameters:
        - name: q
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
        - name: operator
          in: query
          schema:
            type: string
        - name: sonangol
          in: query
          description: Filter Sonangol positions; accepts true, operator or participant.
          schema:
            type: string
        - name: opportunity
          in: query
          schema:
            type: boolean
        - name: producing
          in: query
          schema:
            type: boolean
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 250
      responses:
        "200":
          description: Canonical Angola concession registry with source and temporal metadata.
        "503":
          description: Concession registry unavailable.
  /api/v1/maritime/ais:
    get:
      summary: Maritime AIS intelligence service
      operationId: getMaritimeAis
      description: >
        Authenticated Maritime service for live AIS, vessel history, replay,
        derived events and feed health. Terminal sessions and entitled platform
        API keys are supported.
      security:
        - HalcyonApiKey: []
        - HalcyonUserToken: []
      parameters:
        - name: mode
          in: query
          required: true
          schema:
            type: string
            enum: [live, history, replay-range, replay-window, events, health]
        - name: mmsi
          in: query
          schema:
            type: string
        - name: days
          in: query
          schema:
            type: integer
        - name: hours
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
        - name: start
          in: query
          schema:
            type: string
            format: date-time
        - name: end
          in: query
          schema:
            type: string
            format: date-time
        - name: south
          in: query
          schema:
            type: number
        - name: north
          in: query
          schema:
            type: number
        - name: west
          in: query
          schema:
            type: number
        - name: east
          in: query
          schema:
            type: number
      responses:
        "200":
          description: AIS data for the requested mode.
        "401":
          description: Terminal session or API key required.
        "403":
          description: Maritime access not authorized.
        "503":
          description: Maritime AIS service unavailable.
  /api/v1/power/grid:
    get:
      summary: Angola public power-grid intelligence
      operationId: getPowerGrid
      parameters:
        - name: mode
          in: query
          schema:
            type: string
            enum: [network-v1, asset-v1]
            default: network-v1
        - name: locale
          in: query
          schema:
            type: string
        - name: wikipedia
          in: query
          schema:
            type: string
        - name: wikidata
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Public grid geometry or public asset enrichment.
        "503":
          description: Power grid service unavailable.
  /api/v1/power/market:
    get:
      summary: Angola and SAPP power-market intelligence
      operationId: getPowerMarket
      responses:
        "200":
          description: Public power-market and regulatory intelligence.
        "503":
          description: Power market service unavailable.
  /api/v1/power/sapp-market:
    get:
      summary: SAPP public market-depth intelligence
      operationId: getPowerSappMarket
      responses:
        "200":
          description: Latest machine-readable public SAPP market metrics.
        "503":
          description: SAPP market service unavailable.
  /api/v1/power/statistics:
    get:
      summary: RNT public system statistics
      operationId: getPowerStatistics
      responses:
        "200":
          description: Validated public RNT system-statistics discovery and series.
        "503":
          description: Power statistics service unavailable.
  /api/v1/power/hydro:
    get:
      summary: Angola hydro-meteorological power context
      operationId: getPowerHydro
      responses:
        "200":
          description: Public hydro-meteorological context for representative basins.
        "503":
          description: Hydro context unavailable.
  /api/v1/power/hazards:
    get:
      summary: Angola public power hazard context
      operationId: getPowerHazards
      responses:
        "200":
          description: Public NASA EONET hazard context near Angola power assets.
        "503":
          description: Hazard context unavailable.
  /api/v1/water/public:
    get:
      summary: Angola Water & Sanitation public intelligence
      operationId: getWaterPublic
      description: >
        Versioned public Water service for national overview, public GIS infrastructure,
        representative-basin hydrology and source/programme metadata. Public and modeled
        context remains explicitly separated from institutional telemetry.
      parameters:
        - name: mode
          in: query
          schema:
            type: string
            enum: [overview-v1, network-v1, hydrology-v1, sources-v1]
            default: overview-v1
      responses:
        "200":
          description: Public Water intelligence for the requested mode.
        "503":
          description: Water public-intelligence service unavailable.
  /api/v1/entities/graph:
    get:
      summary: Canonical Halcyon entity graph
      operationId: getEntityGraph
      description: >
        Returns a canonical entity identity plus evidence-aware relationships,
        reference drivers and instrument identities. Modeled exposure values are
        not promoted into the canonical graph without evidence.
      security:
        - HalcyonApiKey: []
        - HalcyonUserToken: []
      parameters:
        - name: entity
          in: query
          schema:
            type: string
            default: sonangol
      responses:
        "200":
          description: Canonical entity graph.
        "401":
          description: Terminal session or API key required.
        "404":
          description: Entity not found.
        "503":
          description: Entity Fabric unavailable.
  /api/v1/entities/search:
    get:
      summary: Search canonical Halcyon entities
      operationId: searchEntities
      security:
        - HalcyonApiKey: []
        - HalcyonUserToken: []
      parameters:
        - name: q
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        "200":
          description: Matching canonical identities.
        "401":
          description: Terminal session or API key required.
        "503":
          description: Entity Fabric unavailable.
  /api/v1/integration/status:
    get:
      summary: Halcyon Integration Fabric operational status
      operationId: getIntegrationStatus
      description: >
        Returns governed connector state, connector-to-dataset coverage, recent
        ingestion jobs, platform events and production/UAT conformance runs.
      security:
        - HalcyonApiKey: []
        - HalcyonUserToken: []
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 5
            maximum: 100
            default: 30
      responses:
        "200":
          description: Current Integration Fabric operational status.
        "401":
          description: Terminal session or API key required.
        "403":
          description: Integration Fabric access not authorized.
        "503":
          description: Integration Fabric unavailable.
  /api/v1/events/feed:
    get:
      summary: Authenticated Halcyon Platform event feed
      operationId: getPlatformEventFeed
      description: >
        Returns global Event Fabric records using opaque cursor pagination.
        Storage remains server-only; tenant-specific delivery, webhooks and
        streaming are not part of this v1 contract.
      security:
        - HalcyonApiKey: []
        - HalcyonUserToken: []
      parameters:
        - name: cursor
          in: query
          description: Opaque cursor returned by the previous response.
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: topic
          in: query
          schema:
            type: string
        - name: eventType
          in: query
          schema:
            type: string
        - name: entityType
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Cursor-paginated global Platform Event Feed.
        "400":
          description: Invalid cursor or event filter.
        "401":
          description: Terminal session or API key required.
        "403":
          description: Event Fabric access not authorized.
        "429":
          description: API-key rate limit exceeded.
        "503":
          description: Event Fabric unavailable.
  /api/v1/network/overview:
    get:
      summary: Network operational overview
      operationId: getNetworkOverview
      security:
        - {}
        - HalcyonApiKey: []
      responses:
        "200":
          description: Network KPIs. Without credentials, only demonstration data is returned.
  /api/v1/network/sites:
    get:
      summary: Network sites
      operationId: getNetworkSites
      security:
        - {}
        - HalcyonApiKey: []
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 500
      responses:
        "200":
          description: Network sites. Without credentials, only demonstration data is returned.
  /api/v1/network/incidents:
    get:
      summary: Network incidents
      operationId: getNetworkIncidents
      security:
        - {}
        - HalcyonApiKey: []
      parameters:
        - name: status
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Network incidents. Without credentials, only demonstration data is returned.
  /api/v1/network/metrics:
    get:
      summary: Network metrics
      operationId: getNetworkMetrics
      security:
        - {}
        - HalcyonApiKey: []
      parameters:
        - name: metric
          in: query
          schema:
            type: string
        - name: siteId
          in: query
          description: Optional network-site identifier.
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 1000
      responses:
        "200":
          description: Network metrics. Without credentials, only demonstration data is returned.
  /api/v1/network/links:
    get:
      summary: Network links
      operationId: getNetworkLinks
      security:
        - {}
        - HalcyonApiKey: []
      responses:
        "200":
          description: Network links. Without credentials, only demonstration data is returned.
  /api/v1/network/services:
    get:
      summary: Network services
      operationId: getNetworkServices
      security:
        - {}
        - HalcyonApiKey: []
      responses:
        "200":
          description: Network services. Without credentials, only demonstration data is returned.
  /api/v1/network/maintenance:
    get:
      summary: Network maintenance
      operationId: getNetworkMaintenance
      security:
        - {}
        - HalcyonApiKey: []
      responses:
        "200":
          description: Network maintenance. Without credentials, only demonstration data is returned.
  /api/v1/network/dependencies:
    get:
      summary: Service-to-resource dependency graph
      operationId: getNetworkDependencies
      security:
        - {}
        - HalcyonApiKey: []
      parameters:
        - name: serviceId
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Service dependencies for Digital Twin and impact analysis.
  /api/v1/network/alarms:
    get:
      summary: Network alarms
      operationId: getNetworkAlarms
      security:
        - {}
        - HalcyonApiKey: []
      parameters:
        - name: state
          in: query
          schema:
            type: string
        - name: severity
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Alarm events correlated to resources, services and incidents.
  /api/v1/network/incident-events:
    get:
      summary: Incident operational timeline
      operationId: getNetworkIncidentEvents
      security:
        - {}
        - HalcyonApiKey: []
      parameters:
        - name: incidentId
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Detection, correlation, diagnosis, assignment and restoration events.
  /api/v1/network/forecasts:
    get:
      summary: Network capacity forecasts
      operationId: getNetworkForecasts
      security:
        - {}
        - HalcyonApiKey: []
      responses:
        "200":
          description: Capacity projections and saturation-risk indicators.


  /api/v1/telecom/products:
    get:
      summary: Telecom strategic product catalog and interoperability surfaces
      operationId: getTelecomProducts
      security:
        - {}
        - HalcyonApiKey: []
      responses:
        "200":
          description: Strategic Telecom product families and interface readiness.
  /api/v1/telecom/ntn/sessions:
    get:
      summary: LEO / NTN / Direct-to-Device session view
      operationId: getTelecomNtnSessions
      security:
        - {}
        - HalcyonApiKey: []
      responses:
        "200":
          description: Demonstration NTN/D2D sessions until authorized operator feeds are connected.
  /api/v1/telecom/ai-networks/recommendations:
    get:
      summary: AI Networks recommendations
      operationId: getTelecomAiNetworkRecommendations
      security:
        - {}
        - HalcyonApiKey: []
      responses:
        "200":
          description: Capacity and incident recommendations grounded in Network Intelligence data.
  /api/v1/telecom/ai-business/agents:
    get:
      summary: Enterprise AI agent catalog
      operationId: getTelecomAiBusinessAgents
      security:
        - {}
        - HalcyonApiKey: []
      responses:
        "200":
          description: AI Business / AI-as-a-Service agent catalog.
  /api/v1/telecom/ai-business/status:
    get:
      summary: Mercury AI provider and safety status
      operationId: getTelecomAiBusinessStatus
      description: >
        Returns non-secret MAI provider readiness and local cost-control settings.
        It never returns provider credentials.
      security:
        - {}
      responses:
        "200":
          description: Provider readiness and safety policy.
  /api/v1/telecom/ai-business/query:
    post:
      summary: Invoke Mercury AI / Enterprise AI gateway
      operationId: postTelecomAiBusinessQuery
      description: >
        Stable white-label Enterprise AI contract used by Mercury AI in the demonstration tenant.
        Anonymous callers receive the zero-cost Halcyon Grounded demo. Billable OpenAI inference is available
        only when the provider is enabled and a valid signed-in Terminal session is supplied in X-Halcyon-User-Token.
        Guarded v1 performs at most one provider call per message, has no automatic retries, web search is disabled,
        and OpenAI response storage is disabled.
      security:
        - {}
        - HalcyonApiKey: []
        - HalcyonUserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [prompt]
              properties:
                prompt:
                  type: string
                  maxLength: 3000
                agent:
                  type: string
                  default: MERCURY-AI
                mode:
                  type: string
                  enum: [general, deep, network, cyber]
                  default: general
                context:
                  type: array
                  maxItems: 4
                  description: Optional document/context descriptors. Text excerpts are capped server-side.
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      type:
                        type: string
                      size:
                        type: number
                      excerpt:
                        type: string
                        maxLength: 2500
      responses:
        "200":
          description: Structured assistant output with evidence references and engine metadata.
        "400":
          description: Missing prompt.
        "401":
          description: Invalid Terminal user session when billable provider access is attempted.
        "429":
          description: Halcyon local AI rate/concurrency guard or provider spend/rate limit.
        "502":
          description: Provider failed to complete the request.
  /api/v1/telecom/cyber/events:
    get:
      summary: AI Cybersecurity event triage
      operationId: getTelecomCyberEvents
      security:
        - {}
        - HalcyonApiKey: []
      responses:
        "200":
          description: Demonstration cyber signals pending authorized SIEM/XDR/IAM integrations.
  /api/v1/telecom/private-5g/networks:
    get:
      summary: Private 5G / 5G-Advanced network inventory
      operationId: getTelecomPrivate5GNetworks
      security:
        - {}
        - HalcyonApiKey: []
      responses:
        "200":
          description: Demonstration private-network campuses with RAN/Core/slice/Edge context.
  /api/v1/telecom/iot/assets:
    get:
      summary: Industrial IoT and Edge asset registry
      operationId: getTelecomIotAssets
      security:
        - {}
        - HalcyonApiKey: []
      responses:
        "200":
          description: Demonstration IoT/OT assets, protocols, Edge nodes and predictive context.

components:
  securitySchemes:
    HalcyonApiKey:
      type: apiKey
      in: header
      name: X-Halcyon-API-Key
    HalcyonUserToken:
      type: apiKey
      in: header
      name: X-Halcyon-User-Token
    HalcyonUserSession:
      type: apiKey
      in: header
      name: X-Halcyon-User-Token
      description: Short-lived Supabase Auth access token for signed-in Terminal users. Never an OpenAI key.
    HalcyonBearer:
      type: http
      scheme: bearer