API Reference

Formal OpenAPI is not linked yet, but the following control-plane surfaces are now frozen as the minimum pre-OpenAPI contract.

Currently Frozen Minimal Control-Plane Surfaces

Path	Method	Purpose	Frozen Semantics
`/api/v1/system/info`	`GET`	platform aggregated status entry	returns a platform summary plus runtime persistence-capability summary and does not replace `/healthz` or `/readyz`
`/api/v1/authn/status`	`GET`	AuthN wiring/status visibility	reports authentication-surface status only; no token or session inventory leakage
`/api/v1/authz/status`	`GET`	AuthZ wiring/status visibility	reports authorization-surface status only; no raw policy dump or live per-subject decision output
`/api/v1/approvals`	`POST`	approval-ticket creation entry	returns `201 Created` when the repository is configured and the request is valid; returns a structured `503 Service Unavailable` when it is not
`/api/v1/compose/import`	`POST`	Compose import preflight/report	currently frozen as matrix evaluation plus reporting, not the full AppSpec/deployment pipeline
`/api/v1/installer/actions`	`POST`	installer execution entrypoint	currently frozen as an installer run intent surface that narrows into step-event writes without taking task/deploy authority
`/api/v1/databases`	`GET`	database visibility	currently frozen as a read-only visibility surface that may return `placeholder` with an empty list
`/api/v1/storage/objects`	`GET`	object-storage visibility	currently frozen as a read-only visibility surface that may return `placeholder` with an empty list
`/api/v1/aidb/query`	`POST`	historical AI DB compatibility shell	currently frozen as a legacy-only migration surface and not a place for new long-term capability

The three status surfaces are intended to return 200 OK with a JSON status object that distinguishes placeholder / ready / degraded.
/api/v1/system/info may additionally expose a runtime summary describing the current runtime mode and persistence-capability boundary, but it must not leak DSN values, tokens, or other sensitive configuration.
POST /api/v1/approvals is now a shipped approval-ticket creation API; it returns 201 Created with the full binding context when the approval repository is configured, and a structured 503 Service Unavailable when it is not.
approval binding semantics remain frozen around at least subject_id, env, resource, and action; command_hash remains the recommended CLI/Agent binding.
POST /api/v1/compose/import currently takes normalized Compose fields plus optional strict; successful report generation returns 200 OK even when passed=false.
POST /api/v1/installer/actions currently requires task_id, action, resource, and env; action is frozen to installer.run.execute. correlation_id may be supplied explicitly or inherited from the current request context correlation ID.
/api/v1/databases and /api/v1/storage/objects are visibility-only surfaces for now; they do not execute queries, upload/delete objects, or expose provider control.
/api/v1/aidb/query should now return a structured legacy-only / migration-needed response instead of raw 501.