# API reference The Managed Agents API is served at: ``` https://agents.clusterbase.dev ``` An OpenAPI 3.1 spec is published at [`/openapi.json`](https://agents.clusterbase.dev/openapi.json). Point your OpenAPI client or viewer of choice at it to explore the API. ## Authentication [#authentication] Every `/v1` endpoint requires a **Bearer JWT** from [Sign in with Cluster](/docs/ccp/oidc) — the same `accounts.clusterbase.ai` identity used across the platform. ``` Authorization: Bearer ``` All resources are **owner-scoped** to the token's identity: list endpoints return only your own resources, and fetching or modifying something you don't own returns `404`. A missing or invalid token returns `401`. If an organization membership embedded in your token has been deactivated (for example, the organization was deleted or you were removed from it), every request returns `401 authentication_invalid` instead of `403` — even for routes scoped to a different, still-valid organization. This is a stale authentication snapshot, not a permission denial: refresh your token and retry once to regain access to your remaining organizations. Do not retry a `403`, and don't replay an in-progress stream. **Organization API keys** (see [LLM Gateway API keys](/docs/llm-gateway/api-keys) for how to create one — they're shared across Cluster products) are also accepted, bearer-style, on the core agent-definition routes: `GET`/`POST /v1/agents`, `GET`/`PATCH /v1/agents/{id}`, `GET /v1/agents/{id}/versions`, and `POST /v1/agents/{id}/archive`. The key must carry the `agents:use` scope; a key without it gets `403`. Deleting an agent, discovering its MCP tools, and every other resource here (sessions, runs, schedules, triggers, deployments, connectors, vaults) remain **human-only** — they still require a Bearer JWT. ## Conventions [#conventions] * **List responses are wrapped** in a `data` array: ```json { "data": [ { "id": "agt_..." }, { "id": "agt_..." } ] } ``` * **Errors** use a typed envelope: ```json { "error": { "type": "invalid_request_error", "message": "invalid cron expression" } } ``` * **Archive vs delete** — most resources support a soft `POST .../archive` (hides it; existing work persists) alongside a hard `DELETE`. * **JSON everywhere** — send `Content-Type: application/json` on requests with a body. | Status | Meaning | | ------ | ------------------------------------------------------------------------------------------- | | `200` | OK | | `201` | Created | | `202` | Accepted — async work started (e.g. a run) | | `400` | Invalid request (bad model, unknown tool, bad cron, …) | | `401` | Missing/invalid token, or a stale organization membership snapshot — refresh and retry once | | `403` | An organization API key is missing the required `agents:use` scope | | `404` | Not found, or not owned by you | | `409` | Conflict (e.g. agent `version` mismatch on `PATCH`) | ## Agents [#agents] | Method | Path | Description | | -------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/v1/agents` | List agents (optional `?org_id=` filter). | | `POST` | `/v1/agents` | Create an agent. | | `GET` | `/v1/agents/{id}` | Get the latest agent version. | | `PATCH` | `/v1/agents/{id}` | Update an agent (new version; `version` required, `409` on mismatch). | | `POST` | `/v1/agents/{id}/archive` | Archive an agent. | | `DELETE` | `/v1/agents/{id}` | Permanently delete the agent and everything under it — versions, sessions/events, runs, schedules, triggers, deployments. `409` while work is active. | | `GET` | `/v1/agents/{id}/versions` | List version history. | | `GET` | `/v1/agents/{id}/mcp-tools` | Discover tools from the agent's MCP servers. | See [Building agents](/docs/agents/agents). ## Sessions [#sessions] | Method | Path | Description | | -------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/v1/sessions` | List sessions (optional `?agent_id=` and `?deployment_id=` filters, AND-combined). Query `archived=exclude\|include\|only` selects archive state (default `exclude`). | | `POST` | `/v1/sessions` | Create a session (optional `environment_id`, `vault_ids`). | | `GET` | `/v1/sessions/{id}` | Get a session (status + cumulative usage + sharing state). | | `DELETE` | `/v1/sessions/{id}` | Delete a session. | | `POST` | `/v1/sessions/{id}/archive` | Archive a session (must not be running). | | `PUT` | `/v1/sessions/{id}/sharing` | Enable or disable a public, revocable transcript view (`{ "shared": bool }`). Enabling a session whose history holds a URL-only attachment fails with `400`. | | `GET` | `/v1/shared-sessions/{id}` | Fetch a shared session's public transcript. No authentication required; `404` once sharing is off. | | `PUT` | `/v1/sessions/{id}/seen` | Owner-only read receipt. Advances the read cursor to `{ "through_event_id": "..." }`; returns the session's `activity` summary. | ## Events [#events] | Method | Path | Description | | ------ | --------------------------------- | ------------------------------------------------------ | | `GET` | `/v1/sessions/{id}/events` | List events on the session. | | `POST` | `/v1/sessions/{id}/events` | Append user events as a batch (`{ "events": [...] }`). | | `GET` | `/v1/sessions/{id}/events/stream` | Stream events as Server-Sent Events. | See [Sessions & events](/docs/agents/sessions-and-events). ## Groups [#groups] | Method | Path | Description | | -------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `GET` | `/v1/groups` | List your group conversations (`?org_id=`). | | `POST` | `/v1/groups` | Create a group (`org_id`, optional `name`, `member_ids` — two to eight distinct owned Computer sessions). Returns `201`. | | `GET` | `/v1/groups/{id}` | Get a group's snapshot: transcript, revision, and each member's runs. | | `PATCH` | `/v1/groups/{id}` | Replace a group's details; `name` and `description` are both required. Advances its revision. | | `DELETE` | `/v1/groups/{id}` | Delete a group and its isolated histories. `409` while a member run is active. | | `GET` | `/v1/groups/{id}/history` | Older transcript page (`?before_sequence=`); does not move the live cursor. | | `POST` | `/v1/groups/{id}/messages` | Send a text-only message (`202` with the started `GroupRun`s). Unaddressed selects every member; `recipient_ids`/`@mentions` select respondents. | | `GET` | `/v1/groups/{id}/runs/{run_id}` | Get one run and its reply at a consistent revision. | | `POST` | `/v1/groups/{id}/runs/{run_id}/stop` | Cancel an active or queued run (`204`). | | `GET` | `/v1/groups/{id}/runs/{run_id}/stream` | Stream or resume a run's reply as Server-Sent Events; `204` once inactive, `409` past replay retention. | | `POST` | `/v1/groups/{id}/runs/{run_id}/approvals/{approval_id}` | Respond to a pending tool approval. | | `POST` | `/v1/groups/{id}/runs/{run_id}/questions/{tool_call_id}` | Answer a pending clarifying question. | See [Groups](/docs/agents/groups). ## Memory [#memory] | Method | Path | Description | | -------- | --------------------- | ------------------------------------------------------------------------------- | | `GET` | `/v1/memories` | List memories (`?after=`, `?limit=`, optional `?organization_id=`). | | `POST` | `/v1/memories` | Create a memory (`body`, optional `category`, required `idempotency_key`). | | `GET` | `/v1/memories/{id}` | Get a memory. | | `PATCH` | `/v1/memories/{id}` | Edit a memory's `body` (`{ "body", "revision" }`); `409` on a stale `revision`. | | `DELETE` | `/v1/memories/{id}` | Forget a memory. Requires `?revision=`; `409` on a stale value. | | `GET` | `/v1/memory-settings` | Get the actor's memory settings. | | `PATCH` | `/v1/memory-settings` | Update memory settings (`{ "use_memories": bool }`). | All memory responses carry `Cache-Control: private, no-store`. See [Memory](/docs/agents/memory). ## Schedules [#schedules] | Method | Path | Description | | -------- | -------------------- | ------------------------------------------------------------------------------------------------------- | | `GET` | `/v1/schedules` | List schedules (optional `?agent_id=` filter). | | `POST` | `/v1/schedules` | Create a schedule (`cron`, `timezone`, plus `agent` + `kickoff` — or a `deployment` that carries both). | | `GET` | `/v1/schedules/{id}` | Get a schedule. | | `PATCH` | `/v1/schedules/{id}` | Update (`enabled`, `cron`, `timezone`, `kickoff`). | | `DELETE` | `/v1/schedules/{id}` | Delete a schedule. | See [Schedules](/docs/agents/schedules). ## Triggers [#triggers] | Method | Path | Description | | -------- | ------------------------- | ---------------------------------------------------------------------------------------------------------- | | `GET` | `/v1/triggers` | List triggers (optional `?agent_id=` filter). | | `POST` | `/v1/triggers` | Create a trigger (`agent`, `repo`, `events`; optional `deployment` supplying the fire-time VM and vaults). | | `GET` | `/v1/triggers/{id}` | Get a trigger. | | `PATCH` | `/v1/triggers/{id}` | Update a trigger. | | `DELETE` | `/v1/triggers/{id}` | Delete a trigger. | | `GET` | `/v1/triggers/{id}/fires` | List fire records for the trigger. | See [Triggers](/docs/agents/triggers). ## Runs [#runs] | Method | Path | Description | | ------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `POST` | `/v1/runs` | Launch a Sandbox-backed run (`202` with `session_id` and `sandbox_id`). One of `agent`, `builtin`, or `mode`. Optional `vault_ids` (`environment_variable` credentials inject as Sandbox env vars at provision). | See [On-demand runs](/docs/agents/runs). ## Deployments [#deployments] A **deployment** is a named, reusable run-config — `agent` (with an optional version pin), `environment`, `vault_ids`, and `kickoff` — that you run by hand. The `environment` is one of `none` (HTTP-only, no VM), `existing` (bind a pre-made environment's reused VM), or `ephemeral` (provision a fresh VM per run and tear it down). A deployment's runs are its sessions filtered by `deployment_id`. | Method | Path | Description | | -------- | --------------------------- | ---------------------------------------------------------------------------------------- | | `GET` | `/v1/deployments` | List deployments (optional `?agent_id=` filter). | | `POST` | `/v1/deployments` | Create a deployment (`name`, `agent`, `kickoff`, optional `environment`, `vault_ids`). | | `GET` | `/v1/deployments/{id}` | Get a deployment. | | `PATCH` | `/v1/deployments/{id}` | Update a deployment (`name`, `status`, `environment`, `vault_ids`, `kickoff`). | | `DELETE` | `/v1/deployments/{id}` | Delete a deployment (its sessions' run history survives). | | `POST` | `/v1/deployments/{id}/run` | Run the deployment now (`202` with the started `Session`). Runs on-behalf-of the caller. | | `GET` | `/v1/deployments/{id}/runs` | List the deployment's runs (its sessions, newest-last). | ## Environments [#environments] | Method | Path | Description | | -------- | ------------------------------- | ------------------------------------------- | | `GET` | `/v1/environments` | List environments. | | `POST` | `/v1/environments` | Create an environment (`name`, `config`). | | `GET` | `/v1/environments/{id}` | Get an environment. | | `DELETE` | `/v1/environments/{id}` | Delete an environment (tears down the VM). | | `POST` | `/v1/environments/{id}/archive` | Archive an environment (tears down the VM). | See [Environments](/docs/agents/environments). ## Vaults [#vaults] | Method | Path | Description | | -------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/v1/vaults` | List vaults (newest first). Query: `include_archived` (default `false`), `limit` (default + max `100`). | | `POST` | `/v1/vaults` | Create a vault (`display_name`). | | `GET` | `/v1/vaults/{id}` | Get a vault. | | `PUT` | `/v1/vaults/{id}` | Update a vault's `display_name` and/or `metadata`; archived vaults return `409`. | | `DELETE` | `/v1/vaults/{id}` | Delete a vault. | | `POST` | `/v1/vaults/{id}/archive` | Archive a vault. | | `GET` | `/v1/vaults/{id}/credentials` | List credentials in a vault (newest first). Query: `include_archived` (default `false`), `limit`. | | `POST` | `/v1/vaults/{id}/credentials` | Add a credential (`display_name`, `auth`). `auth.type` is `static_bearer`, `mcp_oauth`, or `environment_variable`. | | `PUT` | `/v1/vaults/{id}/credentials/{cid}` | Rotate a `static_bearer` secret and/or rename. Structural keys (`mcp_server_url` / `secret_name`) are immutable; changing `mcp_server_url` returns `400`. Rotate an `mcp_oauth` or `environment_variable` credential by archive + recreate. | | `DELETE` | `/v1/vaults/{id}/credentials/{cid}` | Delete a credential. | | `POST` | `/v1/vaults/{id}/credentials/{cid}/archive` | Archive a credential. | | `POST` | `/v1/vaults/{id}/credentials/{cid}/mcp_oauth_validate` | Diagnose an `mcp_oauth` credential's refresh (status `valid`/`invalid`/`unknown`). May rotate + persist the refresh token. | List responses are `{ "data": [...], "has_more": bool }`; archived records are excluded unless `include_archived=true`. Secret values are write-only and never returned. See [Vaults & MCP](/docs/agents/vaults-and-mcp). ## Peers [#peers] | Method | Path | Description | | ------ | ------------------------------------ | ------------------------------------------------------------------------ | | `GET` | `/v1/peer-exchanges/{id}` | Get a peer exchange (request, answer, state, and nullable `attachment`). | | `POST` | `/v1/peer-exchanges/{id}/stop` | Stop that exchange. | | `GET` | `/v1/peer-exchanges/{id}/attachment` | Download the exchange's retained file bytes, if any. | See [Peer messaging](/docs/agents/peer-messaging). ## Connectors [#connectors] Curated hosted and native integrations (e.g. Gmail), connected per user with OAuth and enabled on agents via `mcp_services`. | Method | Path | Description | | -------- | -------------------------------------- | ------------------------------------------------------------------------------ | | `GET` | `/v1/mcp-services` | List the connector catalog, with your per-service `connected` state. | | `POST` | `/v1/mcp-services/{id}/connect/start` | Start an OAuth flow (`return_url`); returns an `authorization_url`. | | `POST` | `/v1/mcp-services/connect/complete` | Complete an OAuth flow (`code`, `state` — the `state` identifies the service). | | `DELETE` | `/v1/mcp-services/{id}/connection` | Disconnect your account from a service. | | `GET` | `/v1/mcp-services/{id}/tools` | List a service's tools and your disabled set. | | `PUT` | `/v1/mcp-services/{id}/tool-selection` | Set your `disabled_tools` for a service. | See [Connectors](/docs/agents/vaults-and-mcp#connectors). ## Catalog [#catalog] | Method | Path | Description | | ------ | ------------ | --------------------------------------------- | | `GET` | `/v1/tools` | List attachable built-in tools. | | `GET` | `/v1/models` | List supported models and their capabilities. | ## Webhooks [#webhooks] | Method | Path | Description | | ------ | ------------------ | ------------------------------------------------------------------------------- | | `POST` | `/v1/hooks/github` | GitHub webhook receiver. Called by Cluster infrastructure — not for direct use. |