Management API overview

The control plane is served at /api/v1. The generated endpoint pages in this reference come directly from lib/api-spec/openapi.yaml.

Authentication

Automation sends a management key:

Authorization: Bearer sk-cp-your-key

Browser sessions use the airmux_session cookie and must also send X-Requested-With. Inference keys are not accepted by management endpoints.

Scope in URLs

Scope	Path pattern
Instance	`/api/v1/instance/...` or another instance resource
Organization	`/api/v1/organizations/{org_id}/...`
Workspace	`/api/v1/organizations/{org_id}/workspaces/{workspace_ref}/...`

org_id and workspace_ref accept the resource UUID or slug where the endpoint documents that behavior. A scoped management key must cover the target, and its permission ceiling must include the operation.

Response envelope

Every successful management response wraps its result once:

{
  "data": {
    "id": "019...",
    "name": "Production",
    "slug": "production"
  }
}

Growing collections add page metadata:

{
  "data": [{ "id": "019...", "name": "Production" }],
  "page": { "next_cursor": "MDE5Li4u" }
}

Configuration, status, and selection endpoints return the complete set as {"data": [...]}. This includes management keys, provider credentials, data-plane status, invitations, enrollment choices, and candidate pickers. Errors retain FastAPI’s {"detail": ...} shape and are not enveloped.

Example

curl https://llm.example.com/api/v1/organizations/$ORG_ID/workspaces \
  -H "Authorization: Bearer $AIRMUX_MANAGEMENT_KEY" \
  -H 'Accept: application/json'

Permissions

Permission names are closed strings grouped by resource:

organizations.read|create|update|delete
principals.read|manage
members.read|manage
workspaces.read|create|update|delete
catalog.read|manage
provider-credentials.read|manage
inference-keys.read|manage
policies.read|manage
playground.execute
bundles.read
usage.read|ingest
data-planes.read|heartbeat
audit.read
management-keys.read|issue|revoke

One-time secrets

Inference-key creation, management-key creation, invitation issue/reissue, and service-account creation actions can return a one-time secret. Store the returned value immediately; later list and get operations return metadata only.

Pagination

Collections that callers browse incrementally use cursor pagination. Pagination is not added to an endpoint merely because it is scoped or returns a list; consumers of configuration and selection endpoints need the complete set. The paginated collections are organizations, usage events, and audit activity. Usage events are paginated at both organization and workspace scope, and audit activity is paginated at instance and organization scope.

limit is the maximum number of results per page, defaults to 50, and accepts 1 through 200
cursor is the opaque page.next_cursor returned by the preceding request
page.next_cursor is null when no later page exists

Do not decode or edit a cursor. Invalid and oversized cursors return 422 with {"detail":"invalid cursor"}. Cursors identify a sort position, so traversal can continue if the item at the previous page boundary is deleted.

curl 'https://llm.example.com/api/v1/organizations?limit=50' \
  -H "Authorization: Bearer $AIRMUX_MANAGEMENT_KEY"

curl "https://llm.example.com/api/v1/organizations?limit=50&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $AIRMUX_MANAGEMENT_KEY"

Use the endpoint pages that follow this overview for request bodies, response schemas, required permissions, and interactive examples.

Inference

Operations

Control plane endpoints

Management API overview

Authentication

Scope in URLs

Response envelope

Example

Permissions

One-time secrets

​Authentication

​Scope in URLs

​Response envelope

​Example

​Permissions

​One-time secrets

​Pagination

Authentication

Scope in URLs

Response envelope

Example

Permissions

One-time secrets

Pagination