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

> AiOS 对外 API 参考入口。

# API 参考

当前 API 参考入口仍未接入正式 OpenAPI，但以下控制面对外表面已经冻结，可作为实现与联调前的最小依据。

## 当前冻结的最小控制面接口

| 路径                          | 方法     | 作用                      | 当前冻结语义                                                                    |
| --------------------------- | ------ | ----------------------- | ------------------------------------------------------------------------- |
| `/api/v1/system/info`       | `GET`  | 平台聚合状态入口                | 返回平台级状态摘要与 runtime 持久化能力摘要，不替代 `/healthz` / `/readyz`                     |
| `/api/v1/authn/status`      | `GET`  | AuthN wiring/status 可见性 | 只报告认证面状态，不泄露 token 或 session 明细                                           |
| `/api/v1/authz/status`      | `GET`  | AuthZ wiring/status 可见性 | 只报告授权面状态，不暴露原始策略或实时授权结果                                                   |
| `/api/v1/approvals`         | `POST` | approval ticket 创建入口    | repository 已配置且请求有效时返回 `201 Created`；未配置时返回结构化 `503 Service Unavailable`  |
| `/api/v1/compose/import`    | `POST` | Compose 导入预检与报告         | 当前冻结为字段矩阵评估与导入报告入口，不直接承接完整 AppSpec/部署流程                                   |
| `/api/v1/installer/actions` | `POST` | 安装器执行入口                 | 当前冻结为 installer run intent 入口，收敛到 step event 写入，不接管 task/deploy authority |
| `/api/v1/databases`         | `GET`  | 数据库可见性                  | 当前冻结为只读 visibility surface，可返回 `placeholder` 与空列表                         |
| `/api/v1/storage/objects`   | `GET`  | 对象存储可见性                 | 当前冻结为只读 visibility surface，可返回 `placeholder` 与空列表                         |
| `/api/v1/aidb/query`        | `POST` | 历史 AI DB 兼容壳层           | 当前冻结为 legacy-only 迁移提示面，不再扩展新长期能力                                         |

## 当前约束

* 三个 status surface 的目标行为都是 `200 OK` + JSON 状态对象，并显式区分 `placeholder / ready / degraded`。
* `/api/v1/system/info` 可以额外暴露 `runtime` 摘要字段，用于说明当前运行模式与持久化能力边界，但不能泄露 DSN、token 或其它敏感配置。
* `POST /api/v1/approvals` 当前已交付为 approval ticket 创建接口；在 approval repository 已配置时成功返回 `201 Created`，未配置时返回结构化 `503 Service Unavailable`。
* approval binding 语义仍冻结为围绕 `subject_id`、`env`、`resource`、`action` 建立；`command_hash` 继续作为 CLI/Agent 推荐绑定字段保留。
* `POST /api/v1/compose/import` 当前最小输入是归一化后的 Compose `fields` 与可选 `strict`；生成报告成功时即使 `passed=false` 也返回 `200 OK`。
* `POST /api/v1/installer/actions` 当前最小输入包含 `task_id`、`action`、`resource`、`env`；`action` 冻结为 `installer.run.execute`。`correlation_id` 可显式传入，也可缺省为当前请求上下文的 correlation ID。
* `/api/v1/databases` 与 `/api/v1/storage/objects` 当前只承担只读可见性，不执行 query、上传、删除或 provider 管理。
* `/api/v1/aidb/query` 当前应返回结构化 legacy-only / migration-needed 响应，而不是 raw `501`。

## 相关页面

* [参考总览](/reference/index)
* [CLI 参考](/reference/cli-reference)
* [认证与授权模型](/operations/authn-authz)
* [生产环境二次验证与审批](/agent/production-approval)