API reference
This interactive reference is generated directly from the control plane's OpenAPI 3.1 specification (dist/apps/opencrane/openapi.json) — the same spec served at runtime from GET /api/v1/openapi.json and published as a release asset. It is always in sync with the implementation (a CI drift gate enforces it).
For authentication, error envelopes, and pagination conventions, read the API overview first.
Multi-tenant AI agent platform management API.
Authentication
- Human operators — OIDC browser flow via
GET /auth/login→/auth/callback. Session cookie is set server-side. - CLI operators — Device authorization grant via
POST /auth/device. The CLI opens the returnedverificationUriin the operator's browser, pollsGET /auth/device/token, and persists the issued token in~/.config/opencrane/credentials.json. - Automation / CI — Bearer token via the
OPENCRANE_TOKENenvironment variable, validated against theOPENCRANE_API_TOKENserver-side env var. - Endpoints tagged Auth and Meta (
/auth/*,/openapi.json) require no credentials.
Servers
/api/v1Versioned API prefix
Show the fleet awareness contract rollout state
GET
/awareness/rollout
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Responses
Current rollout state.
application/json
JSON "targetVersion": "string", "stableVersion": "string", "waves": [ "string" ], "promotedWaves": [ "string" ], "shadowMode": true, "nextWave": "string"
{
}
Define (or redefine) the awareness rollout; resets the frontier
PUT
/awareness/rollout
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Request Body
application/json
JSON "targetVersion": "string", "stableVersion": "string", "waves": [ "string" ], "shadowMode": true
{
}
Responses
Rollout defined.
application/json
JSON "targetVersion": "string", "stableVersion": "string", "waves": [ "string" ], "promotedWaves": [ "string" ], "shadowMode": true, "nextWave": "string"
{
}
Advance the rollout frontier (one wave, or up to a named wave)
POST
/awareness/rollout/promote
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Request Body
application/json
JSON "wave": "string"
{
}
Responses
Frontier advanced.
application/json
JSON "targetVersion": "string", "stableVersion": "string", "waves": [ "string" ], "promotedWaves": [ "string" ], "shadowMode": true, "nextWave": "string"
{
}
One-step rollback: return every wave to the stable version
POST
/awareness/rollout/rollback
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Responses
Rolled back.
application/json
JSON "targetVersion": "string", "stableVersion": "string", "waves": [ "string" ], "promotedWaves": [ "string" ], "shadowMode": true, "nextWave": "string"
{
}
Resolve the awareness contract version a tenant runs
GET
/awareness/rollout/resolve/{tenant}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
tenant*
Type
Requiredstring
Responses
Resolved version.
application/json
JSON "tenant": "string", "version": "string", "promoted": true, "shadow": true, "wave": "string"
{
}
Fleet participation, drift, and policy-violation monitoring
GET
/awareness/participation
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Query Parameters
severity
Type
string
Valid values
"critical""warning"Responses
Fleet participation report.
application/json
JSON "total": 0, "participating": 0, "drifted": 0, "critical": 0, "warning": 0, "tenants": [ { "tenant": "string", "lastSeenAt": "string", "runningContractVersion": "string", "expectedContractVersion": "string", "participating": true, "drifted": true, "policyViolations": 0, "severity": "string" } ]
{
}
Inspect a chat-window session's awareness scope binding
GET
/sessions/{sessionKey}/scope
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
sessionKey*
Type
Requiredstring
Responses
Current session scope binding.
application/json
JSON "sessionKey": "string", "principal": "string", "scopes": [ { "scope": "string", "payloadId": "string" } ], "createdAt": "string", "updatedAt": "string"
{
}
Bind a session scope (CP intersects with the principal's entitlements)
PUT
/sessions/{sessionKey}/scope
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
sessionKey*
Type
Requiredstring
Request Body
application/json
JSON "principal": "string", "scopes": [ { "scope": "string", "payloadId": "string" } ]
{
}
Responses
Authorised binding; rejected lists any over-scope dropped.
application/json
JSON "sessionKey": "string", "principal": "string", "scopes": [ { "scope": "string", "payloadId": "string" } ], "createdAt": "string", "updatedAt": "string", "rejected": [ { "scope": "string", "payloadId": "string" } ]
{
}
Clear a session's scope binding
List all tenants
GET
/tenants
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Query Parameters
clusterTenantRef
Return only tenants attached to this parent ClusterTenant (customer).
Type
string
Responses
Tenant list.
application/json
JSON { "name": "string", "displayName": "string", "email": "string", "subject": "string", "team": "string", "clusterTenantRef": "string", "phase": "string", "ingressHost": "string", "createdAt": "string" }
[
]
Create a new tenant (admin/import path; dual-write: K8s CRD + database)
POST
/tenants
Internal seeding (owner-default on org create; member workspace on first login) is the production funnel — this route is the admin/import path. Every workspace it creates must be routable (email) and subject-bound; when a parent clusterTenantRef is given the subject must be a member of that org.
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Request Body
application/json
JSON "name": "string", "displayName": "string", "email": "string", "subject": "string", "team": "string", "clusterTenantRef": "string", "monthlyBudgetUsd": 0, "resources": { }, "policyRef": "string"
{
}
Responses
Tenant created.
application/json
JSON "name": "string", "status": "string"
{
}
Get a single tenant by name
GET
/tenants/{name}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
name*
Type
Requiredstring
Responses
Tenant detail.
application/json
JSON "name": "string", "displayName": "string", "email": "string", "subject": "string", "team": "string", "clusterTenantRef": "string", "phase": "string", "ingressHost": "string", "createdAt": "string"
{
}
Update a tenant (dual-write: K8s CRD + database)
PUT
/tenants/{name}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
name*
Type
Requiredstring
Request Body
application/json
JSON "displayName": "string", "email": "string", "subject": "string", "team": "string", "clusterTenantRef": "string", "monthlyBudgetUsd": 0, "resources": { }, "policyRef": "string"
{
}
Responses
Tenant updated.
application/json
JSON "name": "string", "status": "string"
{
}
Delete a tenant (offboarding teardown: cut sessions/devices, delete the LiteLLM key, remove CRD + DB row — retains Cognee datasets)
Suspend a tenant (scale deployment to zero)
Resume a suspended tenant
Get dataset memberships for a tenant
GET
/tenants/{name}/datasets
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
name*
Type
Requiredstring
Responses
Dataset memberships.
application/json
JSON "org": [ "string" ], "team": [ "string" ], "department": [ "string" ], "project": [ "string" ], "personal": [ "string" ]
{
}
Update dataset memberships for a tenant
PUT
/tenants/{name}/datasets
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
name*
Type
Requiredstring
Request Body
application/json
JSON "org": [ "string" ], "team": [ "string" ], "department": [ "string" ], "project": [ "string" ], "personal": [ "string" ]
{
}
Responses
Dataset memberships updated.
application/json
JSON "org": [ "string" ], "team": [ "string" ], "department": [ "string" ], "project": [ "string" ], "personal": [ "string" ]
{
}
Compile the effective awareness, MCP, and skill contract for a tenant
GET
/tenants/{name}/effective-contract
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
name*
Type
Requiredstring
Responses
Effective contract.
application/json
JSON "contractId": "string", "contractVersion": "string", "tenant": { }, "awareness": { }, "mcp": { }, "skills": { }
{
}
Detect drift between Tenant CRDs and PostgreSQL projection rows
Repair Tenant projection rows from CRD source of truth
Detect drift between AccessPolicy CRDs and PostgreSQL projection rows
Repair AccessPolicy projection rows from CRD source of truth
List all access policies
GET
/policies
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Responses
Policy list.
application/json
JSON { "name": "string", "namespace": "string", "tenantSelector": { }, "domains": [ "string" ], "egressRules": [ { } ], "mcpServers": { }, "createdAt": "string" }
[
]
Create an access policy (dual-write: K8s CRD + database)
Get a single access policy by name
GET
/policies/{name}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
name*
Type
Requiredstring
Responses
Policy detail.
application/json
JSON "name": "string", "namespace": "string", "tenantSelector": { }, "domains": [ "string" ], "egressRules": [ { } ], "mcpServers": { }, "createdAt": "string"
{
}
Update an access policy
Delete an access policy
List all MCP servers with grants and credentials
GET
/mcp-servers
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Responses
MCP server list.
application/json
JSON { "id": "string", "name": "string", "endpoint": "string", "transport": "string", "grants": [ { } ], "credentials": [ { "id": "string", "displayName": "string", "brokeringMode": "string", "secretRef": "string" } ] }
[
]
Create a new MCP server
POST
/mcp-servers
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Request Body
application/json
JSON "name": "string", "endpoint": "string", "transport": "string", "grants": [ { } ], "credentials": [ { } ]
{
}
Responses
MCP server created.
application/json
JSON "id": "string", "name": "string", "endpoint": "string", "transport": "string", "grants": [ { } ], "credentials": [ { "id": "string", "displayName": "string", "brokeringMode": "string", "secretRef": "string" } ]
{
}
Get a single MCP server by identifier
GET
/mcp-servers/{id}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Responses
MCP server detail.
application/json
JSON "id": "string", "name": "string", "endpoint": "string", "transport": "string", "grants": [ { } ], "credentials": [ { "id": "string", "displayName": "string", "brokeringMode": "string", "secretRef": "string" } ]
{
}
Update an MCP server and fully replace grants and credentials
PUT
/mcp-servers/{id}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Request Body
application/json
JSON
{
}
Responses
MCP server updated.
application/json
JSON "id": "string", "name": "string", "endpoint": "string", "transport": "string", "grants": [ { } ], "credentials": [ { "id": "string", "displayName": "string", "brokeringMode": "string", "secretRef": "string" } ]
{
}
Delete an MCP server and its linked grant rows
List the brokered credentials of an MCP server
GET
/mcp-servers/{id}/credentials
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Responses
Credential list.
application/json
JSON { "id": "string", "displayName": "string", "brokeringMode": "string", "secretRef": "string" }
[
]
Add a brokered credential to an MCP server (does not touch grants)
POST
/mcp-servers/{id}/credentials
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Request Body
application/json
JSON "displayName": "string", "brokeringMode": "string", "secretRef": "string"
{
}
Responses
Credential added.
application/json
JSON "id": "string", "displayName": "string", "brokeringMode": "string", "secretRef": "string"
{
}
Remove a single brokered credential from an MCP server
DELETE
/mcp-servers/{id}/credentials/{credentialId}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
credentialId*
Type
Requiredstring
Responses
Credential deleted.
application/json
JSON "id": "string", "status": "string"
{
}
MCP Operator
Operations
GET/mcp/catalogGET/mcp/installedPOST/mcp/installedDELETE/mcp/installed/{serverId}PUT/mcp/installed/{serverId}/credentialDELETE/mcp/installed/{serverId}/credentialPOST/mcp/installed/{serverId}/oauthDELETE/mcp/installed/{serverId}/oauthGET/mcp/serversPOST/mcp/servers/{id}/approvePOST/mcp/servers/{id}/publishPOST/mcp/servers/{id}/rejectPOST/mcp/servers/{id}/enabledGET/mcp/servers/{id}/accessPUT/mcp/servers/{id}/accessGET/mcp/directory
List the published MCP servers the calling user is entitled to
GET
/mcp/catalog
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Responses
Entitlement-scoped catalogue.
application/json
JSON { "id": "string", "name": "string", "description": "string", "publisher": "string", "glyph": "string", "type": "string", "approvalStatus": "string", "credentialSchema": [ { "key": "string", "label": "string", "required": true, "sensitive": true, "placeholder": "string", "hint": "string" } ], "entitlementSummary": "string" }
[
]
List the servers the calling user has installed
Install a catalogue server for the calling user
POST
/mcp/installed
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Request Body
application/json
JSON "serverId": "string"
{
}
Responses
Server installed.
application/json
JSON "serverId": "string", "connectionStatus": "string", "lastUsed": "string", "connectedAccount": "string"
{
}
Uninstall a server for the calling user (clears the stored credential)
Author a per-user credential (write-only) and mark the install connected
PUT
/mcp/installed/{serverId}/credential
The submitted values are write-only: stored server-side as an opaque custody handle and NEVER returned by any response.
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
serverId*
Type
Requiredstring
Request Body
application/json
JSON "values": { "additionalProperties": "string" }
{
}
Responses
Credential connected.
application/json
JSON "serverId": "string", "connectionStatus": "string", "lastUsed": "string", "connectedAccount": "string"
{
}
Clear a per-user credential, returning the install to needs-credential
DELETE
/mcp/installed/{serverId}/credential
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
serverId*
Type
Requiredstring
Responses
Credential cleared.
application/json
JSON "serverId": "string", "connectionStatus": "string", "lastUsed": "string", "connectedAccount": "string"
{
}
Mark a remote-OAuth install connected after a successful handshake
POST
/mcp/installed/{serverId}/oauth
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
serverId*
Type
Requiredstring
Responses
OAuth connected.
application/json
JSON "serverId": "string", "connectionStatus": "string", "lastUsed": "string", "connectedAccount": "string"
{
}
Disconnect a remote-OAuth install, returning it to needs-credential
DELETE
/mcp/installed/{serverId}/oauth
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
serverId*
Type
Requiredstring
Responses
OAuth disconnected.
application/json
JSON "serverId": "string", "connectionStatus": "string", "lastUsed": "string", "connectedAccount": "string"
{
}
List every catalogue server regardless of status (org-admin governance view)
GET
/mcp/servers
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Responses
All catalogue servers.
application/json
JSON { "id": "string", "name": "string", "description": "string", "publisher": "string", "glyph": "string", "type": "string", "approvalStatus": "string", "credentialSchema": [ { "key": "string", "label": "string", "required": true, "sensitive": true, "placeholder": "string", "hint": "string" } ], "entitlementSummary": "string" }
[
]
Approve a server (pending-review → approved). Org-admin only
POST
/mcp/servers/{id}/approve
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Responses
Server approved.
application/json
JSON "id": "string", "name": "string", "description": "string", "publisher": "string", "glyph": "string", "type": "string", "approvalStatus": "string", "credentialSchema": [ { "key": "string", "label": "string", "required": true, "sensitive": true, "placeholder": "string", "hint": "string" } ], "entitlementSummary": "string"
{
}
Publish a server (approved → published). Org-admin only
POST
/mcp/servers/{id}/publish
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Responses
Server published.
application/json
JSON "id": "string", "name": "string", "description": "string", "publisher": "string", "glyph": "string", "type": "string", "approvalStatus": "string", "credentialSchema": [ { "key": "string", "label": "string", "required": true, "sensitive": true, "placeholder": "string", "hint": "string" } ], "entitlementSummary": "string"
{
}
Reject a server (→ disabled). Org-admin only
POST
/mcp/servers/{id}/reject
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Responses
Server rejected.
application/json
JSON "id": "string", "name": "string", "description": "string", "publisher": "string", "glyph": "string", "type": "string", "approvalStatus": "string", "credentialSchema": [ { "key": "string", "label": "string", "required": true, "sensitive": true, "placeholder": "string", "hint": "string" } ], "entitlementSummary": "string"
{
}
Toggle a server's availability (true → published, false → disabled). Org-admin only
POST
/mcp/servers/{id}/enabled
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Request Body
application/json
JSON "enabled": true
{
}
Responses
Server availability updated.
application/json
JSON "id": "string", "name": "string", "description": "string", "publisher": "string", "glyph": "string", "type": "string", "approvalStatus": "string", "credentialSchema": [ { "key": "string", "label": "string", "required": true, "sensitive": true, "placeholder": "string", "hint": "string" } ], "entitlementSummary": "string"
{
}
Read a server's access policy. Org-admin only
GET
/mcp/servers/{id}/access
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Responses
Access policy.
application/json
JSON "serverId": "string", "everyoneInOrg": true, "groups": [ "string" ], "users": [ { "id": "string", "name": "string", "initials": "string", "color": "string" } ]
{
}
Replace a server's access policy wholesale. Org-admin only
PUT
/mcp/servers/{id}/access
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Request Body
application/json
JSON "everyoneInOrg": true, "groups": [ "string" ], "users": [ "string" ]
{
}
Responses
Access policy updated.
application/json
JSON "serverId": "string", "everyoneInOrg": true, "groups": [ "string" ], "users": [ { "id": "string", "name": "string", "initials": "string", "color": "string" } ]
{
}
List the selectable users and groups for the access editor. Org-admin only
List the file/chat resource shares the caller is a member of
Share a file/chat with a user (creates/extends the resource's share group)
POST
/resource-shares
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Request Body
application/json
JSON "resourceType": "string", "resourceId": "string", "recipientSubject": "string"
{
}
Responses
Recipient added (or already present).
application/json
JSON "groupId": "string", "resourceType": "string", "resourceId": "string", "members": [ "string" ]
{
}
Revoke a recipient from a resource share
DELETE
/resource-shares/{groupId}/recipients/{subject}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
groupId*
Type
Requiredstring
subject*
Type
Requiredstring
Responses
Recipient revoked.
application/json
JSON "groupId": "string", "resourceType": "string", "resourceId": "string", "members": [ "string" ]
{
}
List the shares the authenticated caller has created
GET
/shares
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Responses
Shares created by the caller.
application/json
JSON { "id": "string", "payloadType": "string", "payloadId": "string", "recipientType": "string", "recipientId": "string", "scope": "string", "note": "string", "sharedBy": "string", "createdAt": "string" }
[
]
Share an entitlement you hold with another user or group (least-privilege bounded)
POST
/shares
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Request Body
application/json
JSON "payloadType": "string", "payloadId": "string", "recipientType": "string", "recipientId": "string", "scope": "personal", "note": "string"
{
}
Responses
An identical share already existed (idempotent).
application/json
JSON "id": "string", "payloadType": "string", "payloadId": "string", "recipientType": "string", "recipientId": "string", "scope": "string", "note": "string", "sharedBy": "string", "createdAt": "string"
{
}
Revoke a share you created
List all groups with member counts and awareness grants
Create a new group and optional awareness grants
POST
/groups
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Request Body
application/json
JSON "name": "string", "description": "string"
{
}
Responses
Group created.
application/json
JSON "id": "string", "name": "string", "description": "string", "memberCount": 0, "awarenessGrants": [ { } ]
{
}
Get a single group by identifier
GET
/groups/{id}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Responses
Group detail.
application/json
JSON "id": "string", "name": "string", "description": "string", "memberCount": 0, "awarenessGrants": [ { } ]
{
}
Update a group and replace awareness grants
PUT
/groups/{id}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Request Body
application/json
JSON
{
}
Responses
Group updated.
application/json
JSON "id": "string", "name": "string", "description": "string", "memberCount": 0, "awarenessGrants": [ { } ]
{
}
Delete a group and its awareness grants
List all skill bundles with entitlements and promotion history
GET
/skills/catalog
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Responses
Skill bundle list.
application/json
JSON { "id": "string", "name": "string", "description": "string", "version": "string", "digest": "string", "scope": "string", "status": "string", "tags": [ "string" ], "sourceName": "string", "publishedAt": "string", "grants": [ { } ], "promotions": [ { } ] }
[
]
Create a new skill bundle
Backfill all published bundles' content into the OCI store (P4D.2)
POST
/skills/catalog/backfill
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Responses
Backfill summary with per-bundle outcomes.
application/json
JSON "total": 0, "pushed": 0, "skipped": 0, "failed": 0, "results": [ { "id": "string", "name": "string", "digest": "string", "outcome": "string", "reason": "string" } ]
{
}
Get a single skill bundle by identifier
GET
/skills/catalog/{id}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Responses
Skill bundle detail.
application/json
JSON "id": "string", "name": "string", "description": "string", "version": "string", "digest": "string", "scope": "string", "status": "string", "tags": [ "string" ], "sourceName": "string", "publishedAt": "string", "grants": [ { } ], "promotions": [ { } ]
{
}
Update a skill bundle and fully replace entitlements and promotions
Delete a skill bundle and its linked entitlement grants
List all skills with their model posture
GET
/skills/posture
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Responses
Skill posture list.
application/json
JSON { "name": "string", "scope": "string", "team": "string", "path": "string", "modelMode": "string", "pinnedModel": "string", "autoConfig": { "objective": "string", "costQualitySlider": 0, "qualityFloor": 0, "maxBudgetUsd": 0, "allowedModels": [ "string" ], "latencyCeilingMs": 0, "fallbacks": [ "string" ], "sessionPin": true, "explorationRate": 0 }, "createdAt": "string", "updatedAt": "string" }
[
]
Get a single skill's model posture by its compound key
GET
/skills/posture/skill
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Query Parameters
name*
Skill name.
Type
Requiredstring
scope*
Skill scope.
Type
Requiredstring
team
Owning team; empty string when not team-scoped.
Type
string
Responses
Skill posture detail.
application/json
JSON "name": "string", "scope": "string", "team": "string", "path": "string", "modelMode": "string", "pinnedModel": "string", "autoConfig": { "objective": "string", "costQualitySlider": 0, "qualityFloor": 0, "maxBudgetUsd": 0, "allowedModels": [ "string" ], "latencyCeilingMs": 0, "fallbacks": [ "string" ], "sessionPin": true, "explorationRate": 0 }, "createdAt": "string", "updatedAt": "string"
{
}
Set (or clear) a skill's model posture
PUT
/skills/posture/skill
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Query Parameters
name*
Skill name.
Type
Requiredstring
scope*
Skill scope.
Type
Requiredstring
team
Owning team; empty string when not team-scoped.
Type
string
Request Body
application/json
JSON "modelMode": "string", "pinnedModel": "string", "autoConfig": { "objective": "string", "costQualitySlider": 0, "qualityFloor": 0, "maxBudgetUsd": 0, "allowedModels": [ "string" ], "latencyCeilingMs": 0, "fallbacks": [ "string" ], "sessionPin": true, "explorationRate": 0 }
{
}
Responses
Skill posture updated.
application/json
JSON "name": "string", "scope": "string", "team": "string", "path": "string", "modelMode": "string", "pinnedModel": "string", "autoConfig": { "objective": "string", "costQualitySlider": 0, "qualityFloor": 0, "maxBudgetUsd": 0, "allowedModels": [ "string" ], "latencyCeilingMs": 0, "fallbacks": [ "string" ], "sessionPin": true, "explorationRate": 0 }, "createdAt": "string", "updatedAt": "string"
{
}
List all third-party sources
Register a new third-party source
Get a single third-party source
GET
/third-party-sources/{id}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Responses
Source detail.
application/json
JSON "id": "string", "name": "string", "type": "string", "url": "string", "syncStatus": "string", "lastSyncedAt": "string"
{
}
Update a third-party source
Delete a third-party source and its linked items
List all issued access tokens (hashes only, never plaintext)
Create a new access token. Returns plaintext token once — store it securely.
POST
/access-tokens
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Request Body
application/json
JSON "name": "string", "owner": "string", "expiresAt": "string"
{
}
Responses
Token created. The plainTextToken field will not be returned again.
application/json
JSON "id": "string", "plainTextToken": "string"
{
}
Revoke and delete an access token
List configured provider API keys (configured status only, never the key value)
Create or update a provider API key
PUT
/providers/keys/{provider}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
provider*
Type
Requiredstring
Request Body
application/json
JSON "apiKey": "string"
{
}
Responses
Key updated.
application/json
JSON "provider": "string", "configured": true, "updatedAt": "string"
{
}
Delete a configured provider API key
List BYOK provider key status for every supported provider (never the key value)
Set or refresh a provider's raw key (writes a k8s Secret + LiteLLM credential)
PUT
/providers/byok/{provider}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
provider*
Type
Requiredstring
Valid values
"openai""anthropic""gemini""mistral""deepseek""glm"Request Body
application/json
JSON "apiKey": "string"
{
}
Responses
Key set; returns the provider's status.
application/json
JSON "provider": "string", "configured": true, "litellmRegistered": true, "updatedAt": "string"
{
}
Remove a provider's key (deletes the Secret, LiteLLM credential, and record)
DELETE
/providers/byok/{provider}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
provider*
Type
Requiredstring
Valid values
"openai""anthropic""gemini""mistral""deepseek""glm"Responses
Key removed (idempotent — 204 even when no key was set).
List provider credentials (references only — never the key value)
GET
/providers/credentials
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Query Parameters
clusterTenant
Filter to one owning ClusterTenant.
Type
string
Responses
Provider credential list.
application/json
JSON { "id": "string", "scope": "string", "clusterTenant": "string", "provider": "string", "secretRef": "string", "litellmCredentialName": "string", "createdAt": "string", "updatedAt": "string" }
[
]
Create a provider credential reference (rejects any raw-key field)
POST
/providers/credentials
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Request Body
application/json
JSON "scope": "string", "clusterTenant": "string", "provider": "string", "secretRef": "string", "litellmCredentialName": "string"
{
}
Responses
Provider credential created.
application/json
JSON "id": "string", "scope": "string", "clusterTenant": "string", "provider": "string", "secretRef": "string", "litellmCredentialName": "string", "createdAt": "string", "updatedAt": "string"
{
}
Get a single provider credential by id
GET
/providers/credentials/{id}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Responses
Provider credential detail.
application/json
JSON "id": "string", "scope": "string", "clusterTenant": "string", "provider": "string", "secretRef": "string", "litellmCredentialName": "string", "createdAt": "string", "updatedAt": "string"
{
}
Update a provider credential reference (rejects any raw-key field)
PUT
/providers/credentials/{id}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Request Body
application/json
JSON "scope": "string", "clusterTenant": "string", "provider": "string", "secretRef": "string", "litellmCredentialName": "string"
{
}
Responses
Provider credential updated.
application/json
JSON "id": "string", "scope": "string", "clusterTenant": "string", "provider": "string", "secretRef": "string", "litellmCredentialName": "string", "createdAt": "string", "updatedAt": "string"
{
}
Delete a provider credential
Model Registry
Operations
GET/modelsPOST/modelsGET/models/{id}PUT/models/{id}DELETE/models/{id}GET/model-routing/defaultsPUT/model-routing/defaultsGET/model-routing/defaults/{id}DELETE/model-routing/defaults/{id}GET/model-routing/eval-casesPOST/model-routing/eval-casesGET/model-routing/eval-cases/{id}PUT/model-routing/eval-cases/{id}DELETE/model-routing/eval-cases/{id}GET/model-routing/measurementsPOST/model-routing/measurements/runGET/model-routing/measurements/{id}GET/model-routing/proposalsGET/model-routing/proposals/{id}POST/model-routing/proposals/{id}/approvePOST/model-routing/proposals/{id}/rejectGET/model-routing/recommendationsGET/model-routing/metrics
List model definitions
GET
/models
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Query Parameters
clusterTenant
Filter to one owning ClusterTenant.
Type
string
Responses
Model definition list.
application/json
JSON { "id": "string", "scope": "string", "clusterTenant": "string", "publicModelName": "string", "litellmModelId": "string", "upstreamModel": "string", "apiBase": "string", "isDefault": true, "providerCredentialId": "string", "createdAt": "string", "updatedAt": "string" }
[
]
Create a model definition and register it best-effort with LiteLLM
POST
/models
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Request Body
application/json
JSON "scope": "string", "clusterTenant": "string", "publicModelName": "string", "upstreamModel": "string", "apiBase": "string", "isDefault": true, "providerCredentialId": "string"
{
}
Responses
Model definition created.
application/json
JSON "id": "string", "scope": "string", "clusterTenant": "string", "publicModelName": "string", "litellmModelId": "string", "upstreamModel": "string", "apiBase": "string", "isDefault": true, "providerCredentialId": "string", "createdAt": "string", "updatedAt": "string"
{
}
Get a single model definition by id
GET
/models/{id}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Responses
Model definition detail.
application/json
JSON "id": "string", "scope": "string", "clusterTenant": "string", "publicModelName": "string", "litellmModelId": "string", "upstreamModel": "string", "apiBase": "string", "isDefault": true, "providerCredentialId": "string", "createdAt": "string", "updatedAt": "string"
{
}
Update a model definition
PUT
/models/{id}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Request Body
application/json
JSON "scope": "string", "clusterTenant": "string", "publicModelName": "string", "upstreamModel": "string", "apiBase": "string", "isDefault": true, "providerCredentialId": "string"
{
}
Responses
Model definition updated.
application/json
JSON "id": "string", "scope": "string", "clusterTenant": "string", "publicModelName": "string", "litellmModelId": "string", "upstreamModel": "string", "apiBase": "string", "isDefault": true, "providerCredentialId": "string", "createdAt": "string", "updatedAt": "string"
{
}
Delete a model definition
List model-routing defaults
GET
/model-routing/defaults
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Query Parameters
clusterTenant
Filter to one owning ClusterTenant.
Type
string
Responses
Model-routing default list.
application/json
JSON { "id": "string", "scope": "string", "clusterTenant": "string", "defaultModel": "string", "autoConfig": { "objective": "string", "costQualitySlider": 0, "qualityFloor": 0, "maxBudgetUsd": 0, "allowedModels": [ "string" ], "latencyCeilingMs": 0, "fallbacks": [ "string" ], "sessionPin": true, "explorationRate": 0 }, "createdAt": "string", "updatedAt": "string" }
[
]
Upsert the model-routing default for a (scope, clusterTenant) pair
PUT
/model-routing/defaults
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Request Body
application/json
JSON "scope": "string", "clusterTenant": "string", "defaultModel": "string", "autoConfig": { "objective": "string", "costQualitySlider": 0, "qualityFloor": 0, "maxBudgetUsd": 0, "allowedModels": [ "string" ], "latencyCeilingMs": 0, "fallbacks": [ "string" ], "sessionPin": true, "explorationRate": 0 }
{
}
Responses
Model-routing default upserted.
application/json
JSON "id": "string", "scope": "string", "clusterTenant": "string", "defaultModel": "string", "autoConfig": { "objective": "string", "costQualitySlider": 0, "qualityFloor": 0, "maxBudgetUsd": 0, "allowedModels": [ "string" ], "latencyCeilingMs": 0, "fallbacks": [ "string" ], "sessionPin": true, "explorationRate": 0 }, "createdAt": "string", "updatedAt": "string"
{
}
Get a single model-routing default by id
GET
/model-routing/defaults/{id}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Responses
Model-routing default detail.
application/json
JSON "id": "string", "scope": "string", "clusterTenant": "string", "defaultModel": "string", "autoConfig": { "objective": "string", "costQualitySlider": 0, "qualityFloor": 0, "maxBudgetUsd": 0, "allowedModels": [ "string" ], "latencyCeilingMs": 0, "fallbacks": [ "string" ], "sessionPin": true, "explorationRate": 0 }, "createdAt": "string", "updatedAt": "string"
{
}
Delete a model-routing default
List routing eval cases
GET
/model-routing/eval-cases
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Query Parameters
skillName
Filter to one owning skill name.
Type
string
skillScope
Filter to one owning skill scope.
Type
string
skillTeam
Filter to one owning skill team.
Type
string
Responses
Routing eval-case list.
application/json
JSON { "id": "string", "skillName": "string", "skillScope": "string", "skillTeam": "string", "input": "string", "expected": "string", "qualityBar": 0, "createdAt": "string", "updatedAt": "string" }
[
]
Create a routing eval case for a skill
POST
/model-routing/eval-cases
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Request Body
application/json
JSON "skillName": "string", "skillScope": "string", "skillTeam": "string", "input": "string", "expected": "string", "qualityBar": 0
{
}
Responses
Eval case created.
application/json
JSON "id": "string", "skillName": "string", "skillScope": "string", "skillTeam": "string", "input": "string", "expected": "string", "qualityBar": 0, "createdAt": "string", "updatedAt": "string"
{
}
Get a single routing eval case by id
GET
/model-routing/eval-cases/{id}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Responses
Eval case detail.
application/json
JSON "id": "string", "skillName": "string", "skillScope": "string", "skillTeam": "string", "input": "string", "expected": "string", "qualityBar": 0, "createdAt": "string", "updatedAt": "string"
{
}
Update a routing eval case by id
PUT
/model-routing/eval-cases/{id}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Request Body
application/json
JSON "skillName": "string", "skillScope": "string", "skillTeam": "string", "input": "string", "expected": "string", "qualityBar": 0
{
}
Responses
Eval case updated.
application/json
JSON "id": "string", "skillName": "string", "skillScope": "string", "skillTeam": "string", "input": "string", "expected": "string", "qualityBar": 0, "createdAt": "string", "updatedAt": "string"
{
}
Delete a routing eval case by id
List shadow-savings measurements
GET
/model-routing/measurements
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Query Parameters
skillName
Filter to one owning skill name.
Type
string
skillScope
Filter to one owning skill scope.
Type
string
skillTeam
Filter to one owning skill team.
Type
string
Responses
Measurement list.
application/json
JSON { "id": "string", "skillName": "string", "skillScope": "string", "skillTeam": "string", "candidateModel": "string", "sampledCalls": 0, "atBarCheapFraction": 0, "projectedSavingsPct": 0, "ciLowPct": 0, "ciHighPct": 0, "overheadPct": 0, "skillContentHash": "string", "skillDigest": "string", "candidateModelId": "string", "candidateUpstreamModel": "string", "runAt": "string" }
[
]
Trigger a shadow-savings measurement for a skill + candidate (operator-gated, best-effort)
POST
/model-routing/measurements/run
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Request Body
application/json
JSON "skillName": "string", "skillScope": "string", "skillTeam": "string", "candidateModel": "string", "currentModel": "string"
{
}
Responses
Seams unconfigured — no-op; nothing recorded.
application/json
JSON "status": "string", "note": "string"
{
}
Get a single measurement by id
GET
/model-routing/measurements/{id}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Responses
Measurement detail.
application/json
JSON "id": "string", "skillName": "string", "skillScope": "string", "skillTeam": "string", "candidateModel": "string", "sampledCalls": 0, "atBarCheapFraction": 0, "projectedSavingsPct": 0, "ciLowPct": 0, "ciHighPct": 0, "overheadPct": 0, "skillContentHash": "string", "skillDigest": "string", "candidateModelId": "string", "candidateUpstreamModel": "string", "runAt": "string"
{
}
List routing-change proposals
GET
/model-routing/proposals
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Query Parameters
status
Filter by lifecycle status.
Type
string
Valid values
"pending""approved""rejected""applied"Responses
Proposal list.
application/json
JSON { "id": "string", "skillName": "string", "skillScope": "string", "skillTeam": "string", "fromModel": "string", "proposedModel": "string", "projectedSavingsPct": 0, "ciLowPct": 0, "ciHighPct": 0, "skillContentHash": "string", "skillDigest": "string", "proposedModelId": "string", "measurementId": "string", "status": "string", "decidedBy": "string", "decidedAt": "string", "createdAt": "string" }
[
]
Get a single proposal by id
GET
/model-routing/proposals/{id}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Responses
Proposal detail.
application/json
JSON "id": "string", "skillName": "string", "skillScope": "string", "skillTeam": "string", "fromModel": "string", "proposedModel": "string", "projectedSavingsPct": 0, "ciLowPct": 0, "ciHighPct": 0, "skillContentHash": "string", "skillDigest": "string", "proposedModelId": "string", "measurementId": "string", "status": "string", "decidedBy": "string", "decidedAt": "string", "createdAt": "string"
{
}
Approve a proposal — pin the skill to the proposed model and mark it Applied
Reject a proposal — flip status to Rejected; the skill posture is untouched
List savings recommendations (latest measurement + any open proposal, per skill)
GET
/model-routing/recommendations
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Query Parameters
clusterTenant
Filter to skills owned by this ClusterTenant (the skill's team).
Type
string
skillScope
Filter to one owning skill scope.
Type
string
onlyOpen
When 'true', return only skills with an open Pending proposal.
Type
string
Valid values
"true"Responses
Recommendations sorted by projected savings desc; scope-filtered to the caller's ClusterTenant for non-operators.
application/json
JSON { "skillName": "string", "skillScope": "string", "skillTeam": "string", "modelMode": "string", "currentModel": "string", "recommendedModel": "string", "recommendedModelId": "string", "skillContentHash": "string", "skillDigest": "string", "projectedSavingsPct": 0, "ciLowPct": 0, "ciHighPct": 0, "hasOpenProposal": true, "proposalId": "string", "measurementId": "string", "runAt": "string" }
[
]
Proxy a metrics query to the self-hosted Langfuse backend (server-side auth; non-operators scoped to their tenant)
GET
/model-routing/metrics
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Query Parameters
query
Langfuse v1 metrics query JSON, forwarded verbatim (a tenant filter is injected for non-operators).
Type
string
Responses
Upstream Langfuse metrics JSON (loosely-typed passthrough).
application/json
JSON "additionalProperties": "string"
{
}
Get global monthly spend ceiling
Update the global monthly spend ceiling
List all per-account monthly spend ceilings
Create or update the budget ceiling for a specific account
PUT
/ai-budget/accounts/{userId}
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Path Parameters
userId*
Type
Requiredstring
Request Body
application/json
JSON "monthlyLimitUsd": 0
{
}
Responses
Account budget updated.
application/json
JSON "monthlyLimitUsd": 0, "currentSpendUsd": 0, "budgetAlertState": "string"
{
}
Remove the per-account budget ceiling
Get current spend and budget state for a tenant
Get LiteLLM virtual key metadata for a tenant (never the key value)
Revoke the LiteLLM virtual key for a tenant
Query audit log entries with optional tenant filter and cursor pagination
GET
/audit
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Query Parameters
tenant
Filter to a specific tenant.
Type
string
limit
Maximum entries to return.
Type
integer
Default
100Minimum
1Maximum
1000cursor
Opaque cursor from a previous response for keyset pagination.
Type
string
Responses
Paginated audit entries.
application/json
JSON "data": [ { "timestamp": "string", "tenant": "string", "action": "string", "resource": "string", "message": "string" } ], "pagination": { "limit": 0, "nextCursor": "string", "hasMore": true }
{
}
Get latest server utilisation snapshot (CPU, memory, storage, active tenants)
GET
/metrics/server
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Responses
Server utilisation snapshot.
application/json
JSON "cpuPercent": 0, "memoryUsedBytes": 0, "memoryTotalBytes": 0, "storageUsedBytes": 0, "storageTotalBytes": 0, "activeTenants": 0, "sampledAt": "string"
{
}
Get projection drift metrics with threshold evaluation and alert state
List token usage records
GET
/token-usage
Authorizations
bearerAuth
Static bearer token. Pass as Authorization: Bearer
Type
HTTP (bearer)
Parameters
Query Parameters
tenant
Type
string
limit
Type
integer
Default
100Responses
Token usage records.
application/json
JSON { "tenant": "string", "model": "string", "inputTokens": 0, "outputTokens": 0, "totalCostUsd": 0, "recordedAt": "string" }
[
]
Return current auth mode and authenticated user identity (if any)
GET
/auth/me
No authentication required. Returns 200 with the current session or an anonymous identity when no session is established.
Responses
Auth status.
application/json
JSON "mode": "string", "authenticated": true, "user": { "sub": "string", "issuer": "string", "groups": [ "string" ], "isPlatformOperator": true, "isOrgAdmin": true, "clusterTenant": "string", "ownedOrgs": [ { "clusterTenant": "string", "role": "string" } ], "email": "string", "emailVerified": true, "name": "string", "picture": "string", "authenticatedAt": "string" }
{
}
Resolve the caller's OpenClaw pod gateway connection coordinates from their OIDC session
POST
/auth/pod-token
Single sign-on across the control plane and the tenant pod: requires an established OIDC session (cookie) and returns the wss:// gateway URL for the caller's own pod. Under trusted-proxy gateway auth the browser holds no credential — the gateway socket is authorised at the ingress against the live session (/auth/gateway-verify), so no token is returned. The tenant is resolved solely from the session's verified email, so a caller cannot obtain another user's pod connection. Returns 401 without a session, 403 when no tenant matches the session email, 409 when the pod has no gateway URL / ingress host yet or when the email maps to more than one tenant.
Responses
The caller's OpenClaw pod gateway connection coordinates.
application/json
JSON "gatewayUrl": "string", "tenant": "string", "ingressHost": "string"
{
}
Redirect the browser to the configured OIDC identity provider to start login
OIDC authorization callback — validates the response and establishes a session
Destroy the current session and return the IdP RP-initiated logout URL
POST
/auth/logout
Invalidates the server-side session. When OIDC is enabled and the identity provider advertises an end_session_endpoint, returns the URL the browser should navigate to so the upstream IdP session is also terminated (OIDC RP-Initiated Logout). The local session is always destroyed; endSessionUrl is null when no upstream logout is possible (OIDC disabled, IdP exposes no end-session endpoint, or the session captured no id_token). Non-browser callers may ignore the URL.
Responses
Session destroyed; optional IdP logout URL returned.
application/json
JSON "endSessionUrl": "string"
{
}
Initiate a CLI device authorization grant
POST
/auth/device
Returns a device code and short user code. The CLI prints the verificationUri for the operator to open in a browser. No credentials required.
Responses
Device grant created.
application/json
JSON "deviceCode": "string", "userCode": "string", "verificationUri": "string", "expiresIn": 0, "interval": 0
{
}
Activate a device grant in the browser (requires OIDC session)
GET
/auth/device/activate
The operator opens this URL after a CLI login prompt. If no OIDC session is present the user is redirected to the identity provider first. On success an access token is created and the CLI poll endpoint unblocks.
Parameters
Query Parameters
userCode*
Short user code from the CLI prompt (e.g. ABCD-1234).
Type
Requiredstring
Responses
Grant activated. HTML confirmation page returned.
Poll for the access token after browser activation
GET
/auth/device/token
Returns 202 while pending, 200 with token when authorized, 410 when the grant has expired. The token is delivered exactly once.
Parameters
Query Parameters
deviceCode*
Secret device code returned by POST /auth/device.
Type
Requiredstring
Responses
Grant authorized — token ready.
application/json
JSON "status": "string", "token": "string"
{
}