api-contracts
openapi.yaml is the single contract (OpenAPI 3.1.0) of the public API served by control-api under /api/v1
(https://clustr.spboucher.ai/api/v1). Together with the SQL migrations it is the source of truth
(see docs/DESIGN-BRIEF.md). The agent protocol (/agent/v1, mTLS) is not part of this document.
Consumers
| Target | Generator | Notes |
|---|---|---|
Go server (services/) |
oapi-codegen v2, strict server |
no skip-prune needed: every schema is referenced |
Web (apps/web) |
openapi-typescript + openapi-fetch |
baseUrl: "/api/v1" |
Apple (packages/swift-core, MCCCore) |
swift-openapi-generator |
shared by macOS and iOS |
Change the contract first, regenerate, then implement. Never edit generated code.
Validate
sh
npx --yes @redocly/cli@latest lint packages/api-contracts/openapi.yaml
npx --yes openapi-typescript@latest packages/api-contracts/openapi.yaml -o /tmp/mcc-openapi-check.d.tsLint must report no error. Five warnings are accepted: the localhost development server, three unauthenticated
Meta operations without a 4xx response, and /agents/enrollment-tokens/{id} vs /agents/{id}/revoke
(different methods, static segment wins).
Conventions
- Operations: unique camelCase
operationId, exactly one tag,x-permissionon every operation (authenticated= any session,none= no session),x-step-up: truewhen a passkey ceremony younger than 5 minutes is required.POST /actionsis the exception: permission and step-up depend on the action type (x-permission-note,x-step-up-note). - Schemas: all named under
components/schemas; nooneOf/anyOf/allOf; optional fields are omitted, nevernull; details are composed (NodeDetail { node, ... },AlertDetail { alert, timeline }) instead of inherited; free-form JSON (additionalProperties: true) only for WebAuthn payloads, JSON Schemas, params, results,meta, widgetconfigand errordetails. - Types: ids
uuid; timestampsdate-timein UTC; byte countsint64; enums are string enums. - Security:
cookieSession(__Host-mcc_session) orbearer. Cookie sessions must sendX-MCC-CSRFon every non-safe method (declared optional in the schema because bearer sessions do not use it). The invitation setup transaction usessetupCookie(__Host-mcc_setup) orsetupHeader(X-MCC-Setup-Transaction). - Errors: every non-2xx is
ErrorResponse { error: { code, message, details?, correlation_id } }, through the reusable responsesBadRequest,Unauthenticated,Forbidden,NotFound,Conflict,Gone,Unprocessable,RateLimited(Retry-After),Unavailable. The code table is ininfo.description;codeis an open string, clients must tolerate unknown values.500 internalcan be returned by any operation and is not repeated. - Correlation: every response carries
X-Correlation-Id. - Pagination:
limit(1-200, default 50) +cursor; responses are{ items, next_cursor? }. - Telemetry:
Freshness=fresh | stale | offline;Availability=available | unavailable | unsupported | permission_denied | stale | offline. Telemetry-derived resources carryobserved_atandfreshness. A value that cannot be measured is absent, never zero. - Series: points are
[ts_ms, avg, min, max]arrays (MetricPoints). - Idempotency:
Idempotency-Keyis required onPOST /actionsandPOST /jobs; a replay answers200with the original resource, a new request201. - Events:
GET /eventsistext/event-stream. Payload schemas areNodeStateEvent,AlertChangedEvent, ...EventStreamFrame/EventPayloadsonly exist so that generators emit every payload type; on the wiredatais directly the payload of the topic.