API

The Fastify API exposes the /api/v1 contract for authentication, organizations, cloud accounts, resources, provisioning, agents, pipelines, deployments, AI conversations, alerts, incidents, audit records and settings. The direct Fastify process also exposes root operational routes for health and Swagger.

Conventions

Concern	Contract
Auth	Session bearer, HTTP-only web cookies, or X-API-Key
Tenant	Derived from authenticated membership; never client-supplied
Errors	{ "error": { "code", "message", "details?", "requestId" } }
Collections	Cursor/limit pagination where supported; server caps limits
Correlation	x-request-id is generated or propagated through worker jobs
Mutation safety	Idempotency-Key may deduplicate mutating requests
Streaming	SSE (text/event-stream) for progress and assistant streams
Rate limits	429 with retry information
Time	UTC ISO-8601 with Z suffix

OpenAPI and Swagger UI are served at /docs. The reverse proxy exposes the API through /api/; route wiring in a standalone API process may expose the same handlers without the proxy prefix, so use the generated Swagger document as the environment-specific source of truth.

# Direct API process
curl http://localhost:4000/healthz
curl http://localhost:4000/readyz
curl http://localhost:4000/docs

# Docker Compose API port
curl http://localhost:34001/healthz
curl http://localhost:34001/readyz

# Through the Compose gateway
curl http://localhost:8080/api/v1/resources

Authenticated mutation examples and the error/retry behavior are in Flow examples.