Admin API 参考

Admin API 会由网关进程发布一份 OpenAPI 3.1 文档。需要查看精确路由、请求结构、响应结构和状态码细节时，请使用 Admin API 参考。

如果需要确认 API 契约，可以从托管文档打开 OpenAPI 参考，也可以在自托管网关上查看实时文档。部分动态资源不通过 Admin API 的 CRUD 路由管理，下面会单独说明。

打开 Admin API 参考

托管文档中的参考页面位于 /ai-gateway/reference/admin-api。

在自托管网关中，可以通过 Admin 监听端口打开实时 Scalar UI：

http://127.0.0.1:3001/admin/openapi-scalar

该 UI 会从 http://127.0.0.1:3001/admin/openapi.json 加载机器可读的 OpenAPI 文档。你也可以直接导出规范文件：

curl -sS "http://127.0.0.1:3001/admin/openapi.json" \
  -o aisix-admin-openapi.json

OpenAPI 文档覆盖 Admin 路由器挂载的路由，因此路由列表、请求结构和响应结构会与当前运行的网关保持一致。

其中包含公开的 Admin 监听端口路由、需要认证的 Admin CRUD 路由、playground 路由，以及动态网关资源使用的资源结构。

精确的路由、请求、响应和状态码行为请以 Admin API 参考为准。

Admin API 参考不描述代理 API。对于 /v1/chat/completions 等代理端点，请参见代理 API 参考。

公开的 Admin 监听端口路由用于存活检查和 OpenAPI 发现。需要认证的 Admin 路由使用配置中的 Admin Key：

Authorization: Bearer <admin-key>

Admin 认证路径也接受 x-api-key: <admin-key>。

这与调用方 API Key 是两套凭证。POST /playground/chat/completions 会通过代理路由转发，因此需要调用方 API Key。

AISIX Cloud 托管网关不会暴露 Admin API。

在托管模式下，请通过 AISIX Cloud 控制面管理服务提供方密钥、模型、调用方 API Key 和相关配置。托管网关只暴露代理 API 路由，不暴露 Admin 监听端口。

部分动态资源没有对应的 Admin API CRUD 路由。

RateLimitPolicy 记录可以由 AISIX Cloud 控制面投射到网关，但 Admin API 不提供共享限流策略的 CRUD 路由。参见限流。

GuardrailAttachment 记录会把安全护栏定义绑定到 env、model、api_key 或 team 作用域，并从 guardrail_attachments/<id> 加载。