API reference
This interactive reference is generated from the control plane's OpenAPI 3.1 specification — the same document served at runtime from GET /api/v1/openapi.json and attached to each release. CI re-emits the spec and fails on drift, so this page cannot fall behind the routers it documents.
Read the API overview first for authentication, error envelopes, and pagination conventions. For the maintained TypeScript package, see the Contracts SDK.
Generating a client
Generate against the instance you intend to integrate with, not against this page. Download /api/v1/openapi.json from that deployment, check its server URL and authentication requirements, then run a contract test against it before you ship — a deployment can run an older release than this site documents.
Request samples omit the base path
Every path below is relative to the /api/v1 prefix. Because OpenCrane declares a relative server URL — it is self-hosted and has no canonical host — the generated samples fall back to a bare host and drop that prefix. Prepend your own base URL: GET /mcp-servers is really GET https://<your-host>/api/v1/mcp-servers.
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. - In-cluster workloads use short-lived, audience-bound projected service-account tokens at their dedicated internal trust boundaries.
- Endpoints tagged Auth and Meta (
/auth/*,/openapi.json) require no credentials.
Servers
List all MCP servers with grants and credentials
Create a new MCP server
Request Body
Responses
MCP server created.
Get a single MCP server by identifier
Update an MCP server and fully replace grants and credentials
Parameters
Path Parameters
Request Body
Responses
MCP server updated.
Delete an MCP server and its linked grant rows
List the brokered credentials of an MCP server
Add a brokered credential to an MCP server (does not touch grants)
Remove a single brokered credential from an MCP server
MCP Operator
Operations
List the published MCP servers the calling user is entitled to
Responses
Entitlement-scoped catalogue.
List the servers the calling user has installed
Install a catalogue server for the calling user
Uninstall a server for the calling user (clears the stored credential)
Author a per-user credential (write-only) and mark the install connected
The submitted values are write-only: stored server-side as an opaque custody handle and NEVER returned by any response.
Parameters
Path Parameters
Request Body
Responses
Credential connected.
Clear a per-user credential, returning the install to needs-credential
Mark a remote-OAuth install connected after a successful handshake
Disconnect a remote-OAuth install, returning it to needs-credential
List every catalogue server regardless of status (org-admin governance view)
Responses
All catalogue servers.
Approve a server (pending-review → approved). Org-admin only
Parameters
Path Parameters
Responses
Server approved.
Publish a server (approved → published). Org-admin only
Parameters
Path Parameters
Responses
Server published.
Reject a server (→ disabled). Org-admin only
Parameters
Path Parameters
Responses
Server rejected.
Toggle a server's availability (true → published, false → disabled). Org-admin only
Parameters
Path Parameters
Request Body
Responses
Server availability updated.
Read a server's access policy. Org-admin only
Replace a server's access policy wholesale. Org-admin only
Parameters
Path Parameters
Request Body
Responses
Access policy updated.
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)
Revoke a recipient from a resource share
List the shares the authenticated caller has created
Responses
Shares created by the caller.
Share an entitlement you hold with another user or group (least-privilege bounded)
Request Body
Responses
An identical share already existed (idempotent).
Revoke a share you created
List all groups with member counts and awareness grants
Create a new group and optional awareness grants
Get a single group by identifier
Update a group and replace awareness grants
Delete a group and its awareness grants
List all third-party sources
Register a new third-party source
Get a single third-party source
Update a third-party source
Delete a third-party source and its linked items
Provider Keys
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)
Parameters
Path Parameters
"openai""anthropic""gemini""mistral""deepseek""glm"Request Body
Responses
Key set; returns the provider's status.
Remove a provider's key (deletes the Secret, LiteLLM credential, and record)
List provider credentials (references only — never the key value)
Parameters
Query Parameters
Filter to one owning ClusterTenant.
Responses
Provider credential list.
Create a provider credential reference (rejects any raw-key field)
Request Body
Responses
Provider credential created.
Get a single provider credential by id
Parameters
Path Parameters
Responses
Provider credential detail.
Update a provider credential reference (rejects any raw-key field)
Parameters
Path Parameters
Request Body
Responses
Provider credential updated.
Delete a provider credential
List model definitions
Parameters
Query Parameters
Filter to one owning ClusterTenant.
Responses
Model definition list.
Create a model definition and register it best-effort with LiteLLM
Request Body
Responses
Model definition created.
Get a single model definition by id
Parameters
Path Parameters
Responses
Model definition detail.
Update a model definition
Parameters
Path Parameters
Request Body
Responses
Model definition updated.
Delete a model definition
List model-routing defaults
Parameters
Query Parameters
Filter to one owning ClusterTenant.
Responses
Model-routing default list.
Upsert the model-routing default for a (scope, clusterTenant) pair
Request Body
Responses
Model-routing default upserted.
Get a single model-routing default by id
Parameters
Path Parameters
Responses
Model-routing default detail.
Delete a model-routing default
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
Remove the per-account budget ceiling
Query audit log entries with cursor pagination
Parameters
Query Parameters
Maximum entries to return.
10011000Opaque cursor from a previous response for keyset pagination.
Responses
Paginated audit entries.
List the signed-in owner's pending tool approvals
The server derives the owner and silo from the browser session and host. It returns at most fifty actionable approvals and never returns arguments, proof data, policy digests, or resume credentials.
Responses
Pending owner-bound tool approvals.
Approve or deny one pending tool action owned by the signed-in user
The server derives the owner and silo from the browser session. The body can contain only the terminal decision; it cannot choose another run, subject, tool result, or resume credential.
Parameters
Path Parameters
Opaque identifier for the pending approval.
Request Body
Responses
Decision recorded or identical terminal decision replayed.
Queue one signed-in owner's instruction for a running agent
The server derives the owner, silo, and current attempt. The instruction is queued durably and is consumed only at the runtime's fenced safe boundary.
Parameters
Path Parameters
Opaque run identifier.
Request Body
Responses
Steering request queued for the current run attempt.
List a signed-in owner's fifty most recent personal runs
The server derives the owner and silo from session and host, then returns at most fifty canonical lifecycle summaries ordered newest first.
Responses
Recent canonical lifecycle views for the owned runs.
Start a signed-in user's personal run from an existing conversation
The body may name only a thread and idempotency key. The server derives the session subject, host silo, personal AgentService, signed personal membership assertion, organization, scope, dataset, and immutable run input snapshot.
Request Body
Responses
A duplicate idempotency key returned the already-admitted run.
Return one signed-in owner's personal run status
The server derives the owner and silo from session and host. It never accepts owner coordinates from the request.
Parameters
Path Parameters
Opaque run identifier.
Responses
Current canonical lifecycle view for the owned run.
Return the signed-in owner's resumable persona onboarding state
Replay the signed-in participant's canonical conversation events
The server derives the participant and silo from the browser session. It streams display-safe canonical events only when that participant belongs to the selected thread.
Parameters
Header Parameters
Opaque canonical event cursor. It must match cursor when both are supplied.
Path Parameters
Opaque conversation-thread identifier.
Query Parameters
Opaque canonical event cursor. The Last-Event-ID header is an equivalent resume mechanism.
Responses
A bounded text/event-stream replay. An empty stream does not disclose whether the thread exists or belongs to another participant.
List managed agent services in the signed-in caller's silo
The server derives the silo from the browser session and request host. It returns at most two hundred managed-service summaries, ordered by most recently updated first.
Responses
Managed agent services in the selected silo.
Apply one accepted personal model selection to future runs
The server derives the owner, silo, trusted time, active personal revision, and registered model definition. It creates and activates a new immutable AgentRevision; it never rewrites an active run snapshot. Accepted persona refreshes remain in their proposal-bound interview flow.
Parameters
Path Parameters
Request Body
Responses
Model selection applied, or the accepted proposal belongs to the persona-refresh workflow.
Accept or reject one signed-in owner's configuration proposal
The server derives the owner, silo, and decision time. A decision records consent only; it never applies a patch to an existing run snapshot.
Parameters
Path Parameters
Request Body
Responses
Owner decision recorded.
List the signed-in owner's personal configuration proposals
The server derives the owner and silo from session and host. It returns at most fifty durable future-session proposals, never a mutable run snapshot.
Responses
Owner-bound configuration proposal history.
List governed skills in the signed-in caller's silo
The server derives the silo from the browser session and request host. It returns at most two hundred catalogue summaries, never skill bundles, artifact addresses, manifests, review evidence, signatures, or workload coordinates.
Responses
Browser-safe governed skill catalogue.
List the signed-in owner's assets
The server derives the owner and silo from the browser session and request host. It returns at most fifty non-deleted asset metadata records, never bytes, content addresses, provenance, leases, receipts, or outbox data.
Responses
Owner-bound personal asset metadata.
Return current auth mode and authenticated user identity (if any)
No authentication required. Returns 200 with the current session or an anonymous identity when no session is established.
Responses
Auth status.
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
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.