HTTP API status and conventions

Unicity AOS exposes a narrow local health service and a broader authenticated product gateway. The health service answers one readiness question; the gateway provides the customer and integration API documented in the remaining chapters.

Implementation status

Surface	Status	Ownership
GET /v1/runtime/health on 127.0.0.1:8765	implemented in AOS CE	AOS product health projection
/api/*, /healthz, and /metrics gateway	release-coupled AOS API	product gateway
GET /api/openapi.json	generated by the gateway implementation	authoritative only for the running release that serves it

The remaining chapters map the complete gateway surface. The running release’s generated OpenAPI document remains authoritative when website copy and a deployed version differ.

Product health

GET /v1/runtime/health HTTP/1.1
Host: 127.0.0.1:8765

The loopback service returns 200 {"ready":true} when the bundled runtime is ready and 503 {"ready":false} otherwise. It accepts no query parameters, no implicit HEAD, no CORS, and no caller-selected principal, socket, or IPC topic. It does not expose diagnostics, keys, audit records, or arbitrary bus access.

Gateway base and discovery

Examples use http://127.0.0.1:2787. Operators may bind the product gateway elsewhere, but public exposure requires TLS, reverse-proxy policy, and an explicit CORS allowlist.

curl --fail http://127.0.0.1:2787/api/openapi.json

Unauthenticated routes are limited to discovery, onboarding, redemption, and operations probes:

Method	Path	Purpose
GET	/api/distribution	distribution identity and metadata
GET	/api/distribution/onboarding	fields required by onboarding
POST	/api/auth/redeem	exchange a one-time invite for a session
POST	/api/auth/pair-device/redeem	redeem a device-pairing code
GET	/healthz	process liveness for operators
GET	/metrics	Prometheus metrics; restrict by network policy
GET	/api/openapi.json	generated contract for this running build

All other routes require Authorization: Bearer <session-token>.

Wire conventions

• JSON requests send Content-Type: application/json.
• Ordinary responses are JSON unless the OpenAPI content type says otherwise.
• Streaming routes use Server-Sent Events and reconnect semantics documented in Agent and event streams.
• Unknown fields, invalid identifiers, and out-of-range pagination values are client errors; clients must not rely on silent coercion.
• Error bodies and status codes in the deployed OpenAPI document are authoritative for that release.
• CORS is off by default. An empty origin allowlist emits no CORS headers.
• Security headers apply to public, authenticated, preflight, and error responses.

Client rule

Generate clients from the OpenAPI document shipped by the same AOS release you deploy. Do not copy schemas from main, and do not assume a route documented here exists until the running product release advertises it.