api.yaml

The machine-readable contract. Source of truth: spec/api.yaml.

openapi: 3.1.0
info:
  title: meshtrap central service API
  version: 0.1.0-skeleton
  description: |
    REST and WebSocket API for the meshtrap central service. This is a
    skeleton placeholder; concrete operations land alongside the central
    service implementation phase (Phase 8b).

    Authoritative companion: ../docs/server/

servers:
  - url: https://api.meshtrap.nz/v1
    description: default public instance (planned, not live)
  - url: https://{self_hosted_domain}/v1
    description: self-hosted instance
    variables:
      self_hosted_domain:
        default: localhost

# This skeleton intentionally omits paths, schemas, and security
# schemes. The structure exists to reserve the namespace and document
# the intent.

paths: {}

components:
  schemas: {}
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    oidcAuth:
      type: openIdConnect
      openIdConnectUrl: "{org-configured}"

# Planned resource model (to be defined):
#
#   /orgs                   - org lifecycle
#   /orgs/{id}/networks     - networks under an org
#   /networks/{id}/regions  - regions in a network
#   /regions/{id}/nodes     - nodes in a region
#   /nodes/{id}/commands    - command queue
#   /nodes/{id}/history     - telemetry history
#   /servicings             - servicing-event ingestion / sync
#   /flashing/manifest      - web flasher manifest
#   /public/networks/{id}   - public read views (no auth)
#
# Plus WebSocket subscriptions for live dashboards.