Managed Agents

API reference

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

View as Markdown

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.

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 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.

StatusMeaning
200OK
201Created
202Accepted — async work started (e.g. a run)
400Invalid request (bad model, unknown tool, bad cron, …)
401Missing/invalid token, or a stale organization membership snapshot — refresh and retry once
403An organization API key is missing the required agents:use scope
404Not found, or not owned by you
409Conflict (e.g. agent version mismatch on PATCH)

Agents

MethodPathDescription
GET/v1/agentsList agents (optional ?org_id= filter).
POST/v1/agentsCreate 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}/archiveArchive 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}/versionsList version history.
GET/v1/agents/{id}/mcp-toolsDiscover tools from the agent's MCP servers.

See Building agents.

Sessions

MethodPathDescription
GET/v1/sessionsList sessions (optional ?agent_id= and ?deployment_id= filters, AND-combined). Query archived=exclude|include|only selects archive state (default exclude).
POST/v1/sessionsCreate 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}/archiveArchive a session (must not be running).
PUT/v1/sessions/{id}/sharingEnable 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}/seenOwner-only read receipt. Advances the read cursor to { "through_event_id": "..." }; returns the session's activity summary.

Events

MethodPathDescription
GET/v1/sessions/{id}/eventsList events on the session.
POST/v1/sessions/{id}/eventsAppend user events as a batch ({ "events": [...] }).
GET/v1/sessions/{id}/events/streamStream events as Server-Sent Events.

See Sessions & events.

Groups

MethodPathDescription
GET/v1/groupsList your group conversations (?org_id=).
POST/v1/groupsCreate 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}/historyOlder transcript page (?before_sequence=); does not move the live cursor.
POST/v1/groups/{id}/messagesSend a text-only message (202 with the started GroupRuns). 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}/stopCancel an active or queued run (204).
GET/v1/groups/{id}/runs/{run_id}/streamStream 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.

Memory

MethodPathDescription
GET/v1/memoriesList memories (?after=, ?limit=, optional ?organization_id=).
POST/v1/memoriesCreate 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-settingsGet the actor's memory settings.
PATCH/v1/memory-settingsUpdate memory settings ({ "use_memories": bool }).

All memory responses carry Cache-Control: private, no-store. See Memory.

Schedules

MethodPathDescription
GET/v1/schedulesList schedules (optional ?agent_id= filter).
POST/v1/schedulesCreate 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

MethodPathDescription
GET/v1/triggersList triggers (optional ?agent_id= filter).
POST/v1/triggersCreate 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}/firesList fire records for the trigger.

See Triggers.

Runs

MethodPathDescription
POST/v1/runsLaunch 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.

MethodPathDescription
GET/v1/deploymentsList deployments (optional ?agent_id= filter).
POST/v1/deploymentsCreate 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}/runRun the deployment now (202 with the started Session). Runs on-behalf-of the caller.
GET/v1/deployments/{id}/runsList the deployment's runs (its sessions, newest-last).

Environments

MethodPathDescription
GET/v1/environmentsList environments.
POST/v1/environmentsCreate 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}/archiveArchive an environment (tears down the VM).

See Environments.

Vaults

MethodPathDescription
GET/v1/vaultsList vaults (newest first). Query: include_archived (default false), limit (default + max 100).
POST/v1/vaultsCreate 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}/archiveArchive a vault.
GET/v1/vaults/{id}/credentialsList credentials in a vault (newest first). Query: include_archived (default false), limit.
POST/v1/vaults/{id}/credentialsAdd 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}/archiveArchive a credential.
POST/v1/vaults/{id}/credentials/{cid}/mcp_oauth_validateDiagnose 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.

Peers

MethodPathDescription
GET/v1/peer-exchanges/{id}Get a peer exchange (request, answer, state, and nullable attachment).
POST/v1/peer-exchanges/{id}/stopStop that exchange.
GET/v1/peer-exchanges/{id}/attachmentDownload the exchange's retained file bytes, if any.

See Peer messaging.

Connectors

Curated hosted and native integrations (e.g. Gmail), connected per user with OAuth and enabled on agents via mcp_services.

MethodPathDescription
GET/v1/mcp-servicesList the connector catalog, with your per-service connected state.
POST/v1/mcp-services/{id}/connect/startStart an OAuth flow (return_url); returns an authorization_url.
POST/v1/mcp-services/connect/completeComplete an OAuth flow (code, state — the state identifies the service).
DELETE/v1/mcp-services/{id}/connectionDisconnect your account from a service.
GET/v1/mcp-services/{id}/toolsList a service's tools and your disabled set.
PUT/v1/mcp-services/{id}/tool-selectionSet your disabled_tools for a service.

See Connectors.

Catalog

MethodPathDescription
GET/v1/toolsList attachable built-in tools.
GET/v1/modelsList supported models and their capabilities.

Webhooks

MethodPathDescription
POST/v1/hooks/githubGitHub webhook receiver. Called by Cluster infrastructure — not for direct use.

Vaults & MCP

Connect agents to external tools — raw MCP servers, curated connectors, and credentials held in encrypted vaults.

On this page

AuthenticationConventionsAgentsSessionsEventsGroupsMemorySchedulesTriggersRunsDeploymentsEnvironmentsVaultsPeersConnectorsCatalogWebhooks