Repository Public
1# api-contracts23`openapi.yaml` is the single contract (OpenAPI 3.1.0) of the public API served by `control-api` under `/api/v1`4(`https://clustr.spboucher.ai/api/v1`). Together with the SQL migrations it is the source of truth5(see `docs/DESIGN-BRIEF.md`). The agent protocol (`/agent/v1`, mTLS) is not part of this document.67## Consumers89| Target | Generator | Notes |10|---|---|---|11| Go server (`services/`) | `oapi-codegen` v2, strict server | no `skip-prune` needed: every schema is referenced |12| Web (`apps/web`) | `openapi-typescript` + `openapi-fetch` | `baseUrl: "/api/v1"` |13| Apple (`packages/swift-core`, `MCCCore`) | `swift-openapi-generator` | shared by macOS and iOS |1415Change the contract first, regenerate, then implement. Never edit generated code.1617## Validate1819```sh20npx --yes @redocly/cli@latest lint packages/api-contracts/openapi.yaml21npx --yes openapi-typescript@latest packages/api-contracts/openapi.yaml -o /tmp/mcc-openapi-check.d.ts22```2324Lint must report no error. Five warnings are accepted: the `localhost` development server, three unauthenticated25Meta operations without a 4xx response, and `/agents/enrollment-tokens/{id}` vs `/agents/{id}/revoke`26(different methods, static segment wins).2728## Conventions2930- **Operations**: unique camelCase `operationId`, exactly one tag, `x-permission` on every operation31 (`authenticated` = any session, `none` = no session), `x-step-up: true` when a passkey ceremony younger than32 5 minutes is required. `POST /actions` is the exception: permission and step-up depend on the action type33 (`x-permission-note`, `x-step-up-note`).34- **Schemas**: all named under `components/schemas`; no `oneOf` / `anyOf` / `allOf`; optional fields are omitted,35 never `null`; details are composed (`NodeDetail { node, ... }`, `AlertDetail { alert, timeline }`) instead of36 inherited; free-form JSON (`additionalProperties: true`) only for WebAuthn payloads, JSON Schemas, params,37 results, `meta`, widget `config` and error `details`.38- **Types**: ids `uuid`; timestamps `date-time` in UTC; byte counts `int64`; enums are string enums.39- **Security**: `cookieSession` (`__Host-mcc_session`) or `bearer`. Cookie sessions must send `X-MCC-CSRF` on every40 non-safe method (declared optional in the schema because bearer sessions do not use it). The invitation setup41 transaction uses `setupCookie` (`__Host-mcc_setup`) or `setupHeader` (`X-MCC-Setup-Transaction`).42- **Errors**: every non-2xx is `ErrorResponse { error: { code, message, details?, correlation_id } }`, through the43 reusable responses `BadRequest`, `Unauthenticated`, `Forbidden`, `NotFound`, `Conflict`, `Gone`, `Unprocessable`,44 `RateLimited` (`Retry-After`), `Unavailable`. The code table is in `info.description`; `code` is an open string,45 clients must tolerate unknown values. `500 internal` can be returned by any operation and is not repeated.46- **Correlation**: every response carries `X-Correlation-Id`.47- **Pagination**: `limit` (1-200, default 50) + `cursor`; responses are `{ items, next_cursor? }`.48- **Telemetry**: `Freshness` = `fresh | stale | offline`; `Availability` =49 `available | unavailable | unsupported | permission_denied | stale | offline`. Telemetry-derived resources carry50 `observed_at` and `freshness`. A value that cannot be measured is absent, never zero.51- **Series**: points are `[ts_ms, avg, min, max]` arrays (`MetricPoints`).52- **Idempotency**: `Idempotency-Key` is required on `POST /actions` and `POST /jobs`; a replay answers `200` with53 the original resource, a new request `201`.54- **Events**: `GET /events` is `text/event-stream`. Payload schemas are `NodeStateEvent`, `AlertChangedEvent`, ...55 `EventStreamFrame` / `EventPayloads` only exist so that generators emit every payload type; on the wire `data`56 is directly the payload of the topic.57