> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skrmir.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Entry page for AiOS public API reference.

# 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                                                |

## Current Constraints

* 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`.

## Related Pages

* [Reference](/en/reference/index)
* [CLI Reference](/en/reference/cli-reference)
* [Authentication and Authorization Model](/en/operations/authn-authz)
* [Production Step-Up and Approval](/en/agent/production-approval)