AISIX Cloud Admin API

List caller API keys in an environment. Pagination is opt-in: omit page size to get the full key list in one response. page is only meaningful together with page size and is rejected without it.

Create a caller credential for an environment. The plaintext bearer is returned once in the create response and cannot be recovered later.

Deletes the caller credential. Any caller still using the plaintext bearer receives 401 Unauthorized on subsequent gateway requests.

Update selected caller API key fields. Nullable fields can be cleared with an explicit null. Changing the underlying bearer is not part of this operation — use the rotate operation instead.

Replace the key's underlying bearer with a freshly generated value in one operation. The key resource is preserved — name, allowed models, rate limit, bindings, expiry deadline, and disabled state carry over; only the credential changes. The old plaintext stops authenticating...

Return every environment in the authenticated organization. The response is not paginated.

Create an environment in the authenticated organization. Environment names are case-sensitive and must be unique within the organization.

Return one environment in the authenticated organization. An ID that is missing or belongs to another organization returns 404.

Deletes an environment after revoking its active AISIX gateway certificates. If certificate revocation fails, the environment remains intact and the delete operation can be retried.

Update an environment's display name and MCP OAuth discovery settings. Fields that are omitted keep their current value.

Return every direct, routing, ensemble, semantic, and embedding model configured in the environment. The response is not paginated.

Create a model alias in an environment. The AISIX Cloud control plane creates a direct model unless another kind is selected.

Return one model and the configuration block for its model kind. The model must belong to the environment in the request path.

Delete a model. If another model still references it, rebind or delete the dependent model first.

Update selected fields on a model. The model kind is fixed at creation, and editable fields depend on the current kind.

List provider keys in the authenticated organization. Fetch a single key to see its endpoint override. Pagination is opt-in: omit page size to get the full key list in one response. page is only meaningful together with page size and is rejected without it.

Create an upstream provider credential. The plaintext API key is encrypted before storage and is never returned by read endpoints.

Get a provider key, including its endpoint override.

Deletes the provider key from every environment where it was allowed. Models that still reference the key cannot dispatch successfully, so rebind affected models before deleting the key.

Update selected provider key fields, including the upstream secret. Send api key (or config, for a multi-field credential) to rotate the secret in place: every model that references this provider key picks up the new credential, with no model or caller change. Omit those...

List MCP servers in the authenticated organization. Stored bearer secrets are never included in read responses.

Register an upstream MCP server and expose it to the allowed environments.

Get an MCP server. Stored bearer secrets are never returned.

Deletes the MCP server from every environment where it was allowed.

Update selected MCP server fields. A new secret rotates a bearer credential. This caller holds the permission that approves servers, so an approved server keeps serving across the patch and the new configuration is published immediately; the edit is recorded as its review...

List the MCP tools an OpenAPI-backed server generates, derived from its stored OpenAPI document by the same walk that validated it at write time. Only servers of type: openapi can be listed: an upstream MCP server's tool set lives on the upstream, which the control plane never...

Publishes a reviewed MCP server: it is projected to the environments in allowed environments and becomes discoverable and callable by gateway clients. A previously rejected server can be approved. Approving one that is already approved returns 400. On a live server carrying a...

Refuses a submitted MCP server, and is also how an approval is revoked: rejecting an approved server withdraws it from every environment it was serving in, so gateway clients stop seeing it. Rejecting one that is already rejected returns 400. On a live server carrying a...

Proposes an upstream MCP server without publishing it. The server is registered with approval status set to pending review and is not projected to any environment, so it cannot be discovered or called until a reviewer approves it. This is the entry point for roles that may...

The proposer's write path, on a permission that cannot publish. On a server that is not live it corrects the submission in place and leaves it in the review queue — how a rejected server is fixed and resubmitted. On a server that IS live it changes nothing: the patch is stored...

List A2A agents in the authenticated organization. Stored credentials are never included in read responses.

Register an upstream A2A agent and expose it to the allowed environments.

Get an A2A agent. Stored credentials are never returned.

Deletes the A2A agent from every environment where it was allowed.

Update selected A2A agent fields. A new secret rotates the stored credential.

List organization members. Pagination is opt-in: omit page size to get the full member list in one response. page is only meaningful together with page size and is rejected without it.

Create a login-less member directly, bypassing the email-invitation handshake. The created principal can be added to teams and issued caller API keys immediately, but carries no dashboard credentials and can never sign in. The role is fixed to member.

Replace a member's organization-wide role. Only an organization owner can assign roles. Assigning owner clears the member's environment role bindings because owners already have full access. The last owner cannot be demoted.

List the roles granted to one member in individual environments. Each binding adds its role to the member's organization role for resources inside that environment. It does not reduce the member's organization-level access or grant control over the environment object itself.

Replace the member's complete set of environment-scoped role bindings. Send an empty array to remove every binding. Only an organization owner can change bindings. The target member cannot be an owner, and each environment can appear at most once. Changes can take up to 30...

List the built-in owner, admin, and member roles together with every custom role defined in the authenticated organization.

Create an organization-scoped custom role. Its name is permanent because member and directory-sync assignments reference it by name. A custom role can grant only permission pairs available to the built-in admin role and cannot grant role management.

Delete a custom role. Built-in roles cannot be deleted. A custom role must first be removed from members, pending invitations, directory-sync settings, and environment role bindings. Member assignments and environment bindings can be cleared through this API. Pending...

Update a custom role's description or replace its permissions. The role name cannot change. Built-in roles cannot be updated. Permission changes can take up to 30 seconds to propagate across control-plane replicas.

Return every guardrail definition in the environment. Scope attachments are listed separately through the attachments endpoint.

Create a guardrail in an environment. The per-kind config shape is validated by the server against the guardrail catalog (GET /guardrails/schema); this spec models the stable envelope and treats config as an open object.

Probe a remote-API guardrail provider (Bedrock, Azure Content Safety, Aliyun, Lakera, OpenAI Moderation, …) with the supplied credentials before saving the guardrail. The request mirrors the create body's kind + config; the exact config shape is provider-specific and validated...

Return one guardrail definition in the environment. Provider credentials in the kind-specific configuration are redacted.

Delete a guardrail definition from the environment and remove it from the configuration distributed to connected gateways.

Update selected fields on a guardrail. The kind is fixed at creation; config (when present) is validated by the server against the guardrail catalog for that kind.

Return the scope attachments for one guardrail. Each attachment determines whether the guardrail applies to an environment, model, caller API key, or team.

Attach a guardrail to an env, model, api key, or team scope. scope id is required for every scope except env (which must omit it).

Delete one scope attachment so it no longer makes the guardrail applicable through that scope. Other attachments are unchanged.

Catalog of guardrail providers and their kinds. Read-only metadata used by the dashboard's guardrail form; the response shape is catalog-driven.

Per-kind JSON schema for the guardrail config blob, consumed by the dashboard form. Read-only; the response is catalog-driven. Not every kind publishes a dynamic schema: the ones the dashboard renders with a built-in form (see has schema on GET /guardrails/providers) answer...

Return every prompt-response cache policy configured in the environment. The response is not paginated.

Create a prompt-response cache rule in an environment. Policy names are unique within the environment, and the name and backend cannot be changed after creation.

Return one cache policy. The policy must belong to the environment in the request path.

Deletes the cache policy. The gateway stops serving cached responses for the traffic the policy covered.

Update selected fields on a cache policy. The policy name and backend are fixed at creation — delete and recreate the policy to change them.

Invalidate every entry cached under this policy, across both exact and semantic matching and on every gateway instance. The operation increments the policy's purge generation; gateways pick the new generation up through configuration propagation (typically within seconds) and...

Return every telemetry exporter configured in the environment. Secret header values and credential material are not returned.

Create a telemetry exporter in an environment. The kind value selects which configuration fields apply; fields that belong to other kinds are ignored. Exporter names are unique within the environment. Secrets are never part of this request: aliyun sls, object store, and...

Return one telemetry exporter in the environment. Secret header values and credential material are not returned.

Deletes the exporter. The gateway stops shipping telemetry to the target.

Update selected fields on an exporter. The exporter name and kind are fixed at creation, and a field that does not belong to the exporter's kind is rejected. Configuration changes are validated against the same rules as create; an explicit empty string clears optional fields...

List rate limit policies in an environment. Pagination is opt-in: omit page size to get the full policy list in one response. page is only meaningful together with page size and is rejected without it.

Create a rate limit policy in an environment. Each policy pins one scope and scope ref pair, and a second policy for the same pair is rejected. At least one of max requests or max tokens must be set, and max tokens is only accepted with window: minute or window: day — the...

Return one rate-limit policy. The policy must belong to the environment in the request path.

Deletes the policy. The gateway stops enforcing the limit.

Update selected fields on a rate limit policy. The scope and scope ref pair is fixed at creation. The limit fields are independently clearable: an explicit null clears one limit while keeping the other, and an update that would leave the policy with neither limit is rejected.

List the data plane nodes that have connected to the environment. A node appears after its first status report; a gateway certificate that was issued but never used to connect is not listed. Each entry reflects the node's most recent report, including which configuration...

List configuration resources in the environment that at least one data plane node is currently refusing to apply. A save can succeed at the API and still be rejected at a gateway — for example when an older gateway version does not recognize a newer field. A rejected resource...

Resolve the MCP tool access a caller API key ends up with once the environment layer, the key team's layer, and the key's own mcp access block are intersected. Every allow and deny pattern in the answer carries its source, and layers names the layers that constrain the key —...

Fetch the environment layer of the MCP tool ACL. It applies to every caller API key in the environment, intersected with the key's team layer and the key's own mcp access block. The layer is optional: mcp policy is null when the environment configures none, the same way the...

Create or replace the environment layer of the MCP tool ACL. allow: [" "] covers every tool on every MCP server, including servers and tools registered later — choosing it is always an explicit decision, never a default. The layer narrows what keys can reach but never widens...

Remove the environment layer of the MCP tool ACL. Keys with no team layer and no mcp access block of their own are then left with no layer at all, which means no MCP tool access; keys that configure their own layer keep it.

Fetch the team's entitlements. The mcp block, when present, is the MCP ACL layer caller API keys bound to this team carry in every environment of the organization; it is intersected with the environment layer for those keys and can only narrow it. Absent means the team adds no...

Create, replace, or clear the team's entitlements. Setting the mcp block applies it to the team's caller API keys in every environment of the organization — identity-provider group changes synced to the team propagate automatically, with no per-key edits. Sending "mcp": null...

Return every OIDC provider configured for JWT authentication in the environment. The response is not paginated.

Register an identity provider the gateway trusts for JWT authentication in this environment. Once at least one enabled provider exists, requests may authenticate with a JWT issued by it instead of an API key: the token's issuer selects the provider, its signature and claims...

Return one OIDC provider. The provider must belong to the environment in the request path.

Deletes the OIDC provider. Tokens issued by it stop authenticating as soon as the gateway picks up the change; API keys and their jwt subject bindings are unaffected.

Update selected fields on an OIDC provider. The provider name is fixed at creation — delete and recreate the provider to change it. Changes take effect on new requests without a gateway restart.

Return every claim mapping in the environment. The response is not paginated.

Create a rule that resolves verified JWT claims to an existing caller API key. When a token passes an OIDC provider's verification and no key binds its subject via jwt subject, the enabled mappings naming that provider are evaluated in priority order (lower first, ties broken...

Return one claim mapping. The mapping must belong to the environment in the request path.

Deletes the claim mapping. Identities it admitted stop authenticating as soon as the gateway picks up the change; API keys bound directly via jwt subject are unaffected.

Update selected fields on a claim mapping. The mapping name is fixed at creation — delete and recreate the mapping to change it. Changes take effect on new requests without a gateway restart.

Return every passthrough route in the environment. The response is not paginated.

Create an explicit passthrough route: a binding from a gateway entry — a path prefix on the gateway's own URL space, an inbound hosts allowlist (forward-proxy traffic delivered with its original Host), or both — to one upstream target, forwarded without protocol translation...

Return one passthrough route. The route must belong to the environment in the request path.

Deletes the passthrough route. Traffic it served answers 404 (or the tunnel-namespace 410) as soon as the gateway picks up the change. Guardrail attachments scoped to the route are deleted with it; API keys keep any now-dangling allowed routes patterns, which simply grant...

Update selected fields on a passthrough route. The route name is fixed at creation — delete and recreate the route to change it. The create-time coupling rules apply to the PATCHED result: the route must keep at least one match dimension, exactly one target shape, and each...

List every budget in the organization, across all scopes, each with its current-period spend state. Budgets whose spend is not tracked as a single total (team member) return a zero-seeded state: the limit applies to each member of the team separately.

Create a spending cap. Each target — identified by the scope + scope ref pair — can hold at most one budget; creating a second one for the same target is rejected with 409. A hard stop budget makes the gateway reject matching traffic with 429 budget exceeded once the period's...

Return one budget together with its current-period spend state. The state starts as a zero seed at creation and updates as spend is aggregated.

Remove a budget. Spend tracking continues; only the cap is removed. Enforcement stops within a few seconds — in-flight traffic checked against a cached decision may still be rejected briefly.

Update a budget's name, limit, period, or enforcement mode. Fields left out keep their current values. The budget's scope and scope ref are fixed at creation — to cap a different target, create a new budget.

List the organization's outbound notification channels. Channel URLs are masked — the full URL is write-only.

Create an outbound notification channel. webhook channels receive alert events as JSON POSTs; slack channels expect a Slack incoming-webhook URL and receive a rendered text message. Enabled channels receive every alert raised in the organization (budget threshold alerts...

Return one notification channel in the authenticated organization. The destination URL is masked in the response.

Remove a channel. Its delivery history is kept as an audit trail; pending deliveries to it are marked failed.

Update a channel's name, type, URL, or enabled state. Fields left out keep their current values. Disabling a channel stops future deliveries; already-queued deliveries to it are marked failed rather than parked. Reads mask url, so a read-modify-write sends the mask back under...

Synchronously send a clearly-labeled test notification through the channel and report the outcome. Always returns 200; the body carries the verdict.