API reference

HTTP reference for the Managed Agents service — base URL, authentication, conventions, and every endpoint.

The Managed Agents API is served at:

https://agents.clusterbase.dev

An OpenAPI 3.1 spec is published at /openapi.json. Point your OpenAPI client or viewer of choice at it to explore the API.

Authentication

Every /v1 endpoint requires a Bearer JWT from Sign in with Cluster — the same accounts.clusterbase.ai identity used across the platform.

Authorization: Bearer <token>

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.

Organization API keys (see 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

List responses are wrapped in a data array:

{ "data": [ { "id": "agt_..." }, { "id": "agt_..." } ] }

Errors use a typed envelope:

{ "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
`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

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.

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

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.

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.

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.

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.

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.

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

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.

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.

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.

Catalog

Method	Path	Description
`GET`	`/v1/tools`	List attachable built-in tools.
`GET`	`/v1/models`	List supported models and their capabilities.

Webhooks

Method	Path	Description
`POST`	`/v1/hooks/github`	GitHub webhook receiver. Called by Cluster infrastructure — not for direct use.

API reference

On this page