Admin API Reference

The Admin API publishes an OpenAPI 3.1 document from the gateway process. Use the Admin API Reference for exact routes, request schemas, response schemas, and status-code details.

Open the OpenAPI reference from the hosted documentation or from a self-hosted gateway when you need the exact route contract. Some dynamic resources sit outside Admin API CRUD and are noted below.

Open the Admin API Reference

Open the hosted reference at /ai-gateway/reference/admin-api.

On a self-hosted gateway, open the live Scalar UI on the admin listener:

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

The UI loads the machine-readable OpenAPI document from http://127.0.0.1:3001/admin/openapi.json. You can also export the spec directly:

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

Coverage

The OpenAPI document covers the routes mounted by the admin router, so the route list, request schemas, and response schemas stay aligned with the running gateway.

It includes public admin-listener routes, authenticated admin CRUD routes, playground routes, and the resource schemas used by dynamic gateway resources.

For exact route, request, response, and status-code behavior, use the Admin API Reference.

The Admin API reference does not describe the proxy API. For proxy endpoints such as /v1/chat/completions, see Proxy API Reference.

Authentication

The public admin-listener routes are liveness, metrics, and OpenAPI discovery. Authenticated admin routes use the configured admin key:

Authorization: Bearer <admin-key>

x-api-key: <admin-key> is also accepted on admin auth paths.

This is separate from caller API keys. POST /playground/chat/completions expects a caller API key because it forwards through the proxy router.

Managed Gateways

The Admin API is not exposed on AISIX Cloud managed gateways.

In managed mode, use the AISIX Cloud control plane for provider keys, models, caller API keys, and related configuration. The managed gateway exposes proxy API routes, not the admin listener.

Resources Outside Admin API CRUD

Some dynamic resources do not have Admin API CRUD routes.

RateLimitPolicy rows can be projected by the AISIX Cloud control plane, but the Admin API does not expose CRUD routes for shared rate-limit policies. See Rate Limits.

GuardrailAttachment rows bind guardrail definitions to env, model, api_key, or team scopes and are loaded from guardrail_attachments/<id>. See Guardrails.