Skip to main content

AISIX Enterprise / Cloud Admin API

AISIX Enterprise and AISIX Cloud use the same public, organization-scoped Admin API for automation. Most operations work with both products. When an operation is available in only one product, its...

Caller API Keys

Environments

Models

Provider Keys

MCP Servers

A2A Agents

Members

  • GET List Members /members

    List organization members. Pagination is opt-in: omit page size to get every match in one response. page is only meaningful together with page size and is rejected without it. q, team id, exclude team id and status combine, and total counts what they leave across all pages.

  • POST Create Member /members

    Product availability: AISIX Enterprise only. AISIX Cloud returns 404. 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...

  • POST Look Up Members /members/lookup

    Resolve members by membership id, by user id, or by both, up to 500 ids in total. Deactivated members are returned with their status. An id with no row in the response names no member of this organization: the member was removed, or never belonged to it. This request only...

  • GET Get Own Member /members/me

    The caller's own membership in the active organization. An admin token answers for the member who created it. Every member may call it, whatever roles it holds.

  • DELETE Remove Organization Member /members/{user_id}

    Remove a member from the organization. Only an organization owner can do this, and the last owner cannot be removed. The member's role assignments and team memberships go with them. Caller API keys they own are disabled and no longer name an owner; they are not deleted, and...

  • PATCH Update Member Tags /members/{user_id}

    Replace a member's cost-attribution tags. Every tag key must be declared in the organization. Roles are assigned with POST /members/{user id}/roles and removed with DELETE /members/{user id}/roles/{role name}.

  • POST Create Member Set-Password Link /members/{user_id}/set_password_link

    Product availability: AISIX Enterprise only. AISIX Cloud returns 404. Issue a one-time link with which the member sets their own dashboard password. For a member without a password (created with POST /members, by SCIM, by restoring a redacted backup, or signing in only through...

  • GET List Pending Directory Members /pending_members

    List the people the organization's directory provisioned over SCIM who have not joined yet. On AISIX Cloud, a directory user whose email is not on one of the organization's verified domains is recorded here instead of being attached to an account. The person joins by accepting...

Invitations

  • GET List Invitations /invitations

    List the organization's invitations. By default only invitations that can still be redeemed are returned; pass include stale=true to also see accepted, revoked and expired ones.

  • POST Create Invitation /invitations

    Invite an email address to join the organization with the given roles (restricted member when roles is omitted). The response carries the invitation token in clear text, once. plaintext and the invite url built from it are never recoverable afterwards — anyone holding either...

  • DELETE Revoke Invitation /invitations/{invitation_id}

    Revoke a pending invitation so its link can no longer be redeemed. An invitation that is already accepted, revoked or expired is reported as 404 — there is nothing left to revoke.

  • POST Resend Invitation /invitations/{invitation_id}/resend

    Issue a pending or expired invitation again. It gets a new token, so the link issued before stops working, and it expires after the deployment default counted from now. When the deployment has an SMTP relay configured the invitation email is sent again. The response carries...

Roles

  • GET Get My Effective Permissions /members/me/permissions

    The caller's effective permissions in the organization: the merged rules of every role it holds, directly or through a team, each with the sources that grant it. It also returns what the assigned to selector compares against: the caller's membership ID, the IDs of its teams...

  • GET Get Member Effective Permissions /members/{member_id}/permissions

    One member's effective permissions, in the shape of GET /members/me/permissions. Requires read access to members and to roles.

  • POST Add Member Role /members/{user_id}/roles

    Assign a role to the member by hand (source manual). Requires the role assignments permission; assigning owner also requires the owner role. Assigning a role the member already holds by hand changes nothing.

  • DELETE Remove Member Role /members/{user_id}/roles/{role_name}

    Remove the member's manual assignment of a role. Requires the role assignments permission; removing owner also requires the owner role, and the last owner cannot lose it. A role assigned by single sign-on or directory sync is changed in the identity provider instead.

  • GET List Roles /roles

    List the built-in owner, admin, member, and restricted member roles together with every custom role defined in the authenticated organization, and the resource types a rule can name. AISIX Enterprise has no billing resource because billing is operated by API7 in AISIX Cloud...

  • POST Create Custom Role /roles

    Create an organization-scoped custom role: a list of rules. Its name is permanent because role assignments reference it by name. A custom role cannot create, update, or delete role definitions, and a resource unavailable in the active product is rejected.

  • DELETE Delete Custom Role /roles/{role_name}

    Delete a custom role. Built-in roles cannot be deleted. A custom role must first be removed from the members and teams holding it (GET /roles/{role name}/holders lists them), from pending invitations, and from the SCIM default role and the SSO connection.

  • PATCH Update Custom Role /roles/{role_name}

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

  • GET List Role Holders /roles/{role_name}/holders

    The members holding the role directly, each with its assignment source, and the teams holding it.

  • GET List Team Roles /teams/{team_id}/roles

    The roles of the team. Every member of the team holds them.

  • POST Add Team Role /teams/{team_id}/roles

    Give the team a role, which every member of the team then holds. Requires the role assignments permission. The owner role cannot be given to a team.

  • DELETE Remove Team Role /teams/{team_id}/roles/{role_name}

    Take a role away from the team. Requires the role assignments permission.

Teams

  • GET List Teams /teams

    List the organization's teams, each with its current member count. Pagination is opt-in: omit page size to get every team in one response. page is only meaningful together with page size and is rejected without it.

  • POST Create Team /teams

    Create a team. Teams group organization members so a limit, budget or MCP entitlement can be written once and apply to everyone on the team. display name must be unique within the organization.

  • GET Get Team /teams/{team_id}

    Return one team with its current member count.

  • DELETE Delete Team /teams/{team_id}

    Delete the team. Its entitlements are cleared first, so caller API keys bound to it stop carrying the team's MCP layer; the keys themselves are not deleted. Budgets scoped to the team (scope: team and the per-member scope: team member), and rate limit policies whose scope is...

  • PATCH Update Team /teams/{team_id}

    Update the team's name or description. Omitted fields are left unchanged.

  • GET List Team Members /teams/{team_id}/members

    List everyone on the team, with the organization email and display name resolved alongside the team role, oldest addition first. Pagination is opt-in: omit page size to get every match in one response, with no total, page or page size. page is only meaningful together with...

  • POST Add Team Member /teams/{team_id}/members

    Put an existing organization member on the team. The user must already belong to the organization — this endpoint does not invite anyone. role defaults to member.

  • DELETE Remove Team Member /teams/{team_id}/members/{user_id}

    Take a member off the team. The organization membership is untouched. A team must keep at least one lead, so removing the last one is refused.

  • PATCH Update Team Member Role /teams/{team_id}/members/{user_id}

    Change a member's role within the team. A team must keep at least one lead: demoting the last one is refused, so promote another member first.

Guardrails

Cache Policies

Observability Exporters

Rate Limit Policies

Data Plane Nodes

  • GET List Data Plane Nodes /environments/{env_id}/dp_nodes

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

Rejected Resources

  • GET List Rejected Resources /environments/{env_id}/rejected_resources

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

MCP Access Policies

  • GET Get Effective Permissions /environments/{env_id}/api_keys/{api_key_id}/effective_permissions

    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 —...

  • GET Get MCP Access Policy /environments/{env_id}/mcp_policy

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

  • PUT Set MCP Access Policy /environments/{env_id}/mcp_policy

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

  • DELETE Delete MCP Access Policy /environments/{env_id}/mcp_policy

    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.

  • GET Get Team Entitlements /teams/{team_id}/entitlements

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

  • PUT Set Team Entitlements /teams/{team_id}/entitlements

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

OIDC Providers

Claim Mappings

Passthrough Routes

Budgets

  • GET List Budgets /budgets

    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.

  • POST Create Budget /budgets

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

  • GET Get Budget /budgets/{budget_id}

    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.

  • DELETE Delete Budget /budgets/{budget_id}

    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.

  • PATCH Update Budget /budgets/{budget_id}

    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.

Model Pricing

  • GET List Model Prices /model_pricing

    List the prices this organization is billed at: one row per (provider, model), with the organization's own override taking the place of the catalog default where one exists. source says which you are looking at — user for an override, models.dev or snapshot for the catalog...

  • PUT Set Model Price Override /model_pricing

    Set this organization's price for one (provider, model) pair, creating the override or replacing the existing one. Rates are in the organization's currency. Each per 1m rate may instead be sent under its deprecated usd per 1m name; sending both names for one rate with...

  • PUT Set Precise Model Price Override /model_pricing/precise

    Set this organization's price for one (provider, model) pair using exact rates per 1,000,000 tokens, in the organization's currency. This is a distinct write path: clients that require exact pricing must not fall back to PUT /model pricing when this endpoint is unavailable...

  • DELETE Delete Model Price Override /model_pricing/{id}

    Drop the organization's override so the catalog price takes over again — or, in an organization whose currency is not USD, so the pair is unpriced. Catalog rows are not deletable and report 404, the same as an id that does not exist.

Usage

  • GET List Usage Events /environments/{env_id}/usage_events

    Page through the environment's request telemetry, newest first. One row is one upstream attempt , not one request: a request that retried or failed over emits several rows sharing a request id, ordered by attempt index. Aggregate by request id when you need per-request...

  • GET Export Usage Events /environments/{env_id}/usage_events/export

    Download the rows listUsageEvents would return for the same filters, as one file. Takes the identical filter set; limit and page are ignored — an export is the whole match, capped at 50,000 rows. Each row carries the model, caller API key and member names alongside their ids...

  • GET Get Usage Summary /environments/{env_id}/usage_summary

    Roll the environment's usage up into one bucket per day, model or caller API key over the given window. Counts are request-level: request count is the number of requests in the bucket, not the number of upstream attempts, so a request that retried or failed over counts once...

  • GET Get Usage Metrics /environments/{env_id}/usage_metrics

    Request-level counters and approximate latency percentiles for the window. These are the figures to use for success rate and latency over a whole window. Latency is what the caller waited for, not per-attempt upstream time. A request is counted once, in the hour its first...

  • GET Analyze Organization Usage /usage_analysis

    Group the organization's usage across every environment by one dimension — a cost-attribution tag, team, member, caller API key, model, environment or day — and report each group's cost, tokens and request counts, largest first. Each figure includes the model calls the gateway...

  • GET Break Down Organization Cost /usage_analysis/breakdown

    Show how the cost of the usage the usage analysis selects was made up. Each group is one pricing condition: the model the caller addressed (model), the model the attempt was dispatched to (target model), the input-token price tier and the service tier it was billed at, whether...

  • GET List Tag Keys in Usage /usage_analysis/tag_keys

    List the distinct cost-attribution tag keys the organization's usage was attributed with in the window, across every environment, ordered by key. This includes keys that have since been deleted, which group by=tag: and tag filters on the usage analysis still accept. The window...

Cost Attribution Tags

  • GET List Tag Keys /tag_keys

    List the cost-attribution tag keys the organization declared, ordered by key. Not paginated: an organization declares at most 32.

  • POST Declare Tag Key /tag_keys

    Declare a tag key that caller API keys, teams and members may then carry. The key cannot be changed afterwards. An organization declares at most 32 keys.

  • GET Get Tag Key /tag_keys/{key}

    Return one declared tag key.

  • DELETE Delete Tag Key /tag_keys/{key}

    Delete a tag key and remove it from every caller API key, team and member that carries it; requests made afterwards are no longer attributed to it. Usage already recorded keeps the tags it was attributed with. Refused with 409 TAG KEY IN USE while a budget, a rate limit policy...

  • PATCH Update Tag Key /tag_keys/{key}

    Change a tag key's display name or description. The key itself cannot be changed.

  • GET List Tag Values /tag_keys/{key}/values

    List the distinct values of one declared tag key, ordered by value — at most 500: what the organization's caller API keys, teams and members currently carry, and what its usage of the last 30 days was attributed with, which includes values read from a token's claim through an...

Notification Channels

Notification Deliveries

  • GET List Notification Deliveries /notification_deliveries

    Read the delivery log for the organization's notification channels, newest first — what was sent, to which channel, and whether it landed. Paginate with the cursor rather than an offset: pass the next before id from the previous response as before id. A response whose next...

  • GET Get Notification Delivery /notification_deliveries/{delivery_id}

    Read one delivery with the destination's complete response body. The list cuts last response body at 8192 bytes; this returns all of it, up to the 1 MiB that was captured. Use it when a listed delivery reports last response body truncated.

Organization Data

  • GET Export Organization Data /data_export

    Product availability: AISIX Enterprise only. AISIX Cloud returns 404. Download everything this organization owns as one gzip-compressed SQL file: every environment, model, credential, policy, team, member and the projected configuration the gateways read, plus a window of the...

  • POST Import Organization Data /data_import

    Product availability: AISIX Enterprise only. AISIX Cloud returns 404. Restore a bundle produced by exportOrganizationData onto a freshly installed AISIX Enterprise control plane. The caller is the first administrator the installation created, signed in to the dashboard (an...