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

API reference

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

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
`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.
`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).
`POST`	`/v1/sessions`	Create a session (optional `environment_id`, `vault_ids`).
`GET`	`/v1/sessions/{id}`	Get a session (status + cumulative usage).
`DELETE`	`/v1/sessions/{id}`	Delete a session.
`POST`	`/v1/sessions/{id}/archive`	Archive a session (must not be running).

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.

Schedules

Method	Path	Description
`GET`	`/v1/schedules`	List schedules (optional `?agent_id=` filter).
`POST`	`/v1/schedules`	Create a schedule (`agent`, `cron`, `timezone`, `kickoff`).
`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`).
`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 VM-backed run (`202` with `session_id`). One of `agent`, `builtin`, or `mode`. Optional `vault_ids` (`environment_variable` credentials inject as VM 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.

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