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

Agents

See Building agents.

Sessions

Events

See Sessions & events.

Groups

See Groups.

Memory

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

Schedules

See Schedules.

Triggers

See Triggers.

Runs

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 (select a saved environment and reuse that deployment's workspace, with optional resources), or ephemeral (provision a fresh workspace per run and tear it down, from either a saved environment_id or a base template_id). A deployment's runs are its sessions filtered by deployment_id.

An ephemeral environment may also set folder_id to bind one organization folder through the existing Sandbox workspace sync. Manual, scheduled, and triggered runs pass the binding into every fresh VM; the folder mounts at /workspace/library-files, and that path is stored on the session and included in the agent's context. A folder_id that fails to mount fails the run before it starts. Removing folder_id only affects future runs — it never deletes the folder itself.

Environments

See Cloud environment setup.

Vaults

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.

Browser passwords

Usernames and passwords are write-only and never echoed back. See Browser passwords.

Peers

See Peer messaging.

Bot templates

See Bot templates.

Message drafts

See Message drafts.

Connectors

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

See Connectors.

Catalog

Skills

A skill is a reusable, versioned instruction resource an organization builds up and pins on agent definitions (see Skills). Cluster-managed global skills are read-only; organization members author their own.

Skills management uses the generated cluster.skills.v1.SkillCatalogService contract over gRPC or binary gRPC-Web. Every request requires organization_id and a Hydra bearer with active membership. The former skills REST routes are removed; use the generated client pinned by your application.

Stale mutations return Aborted. Catalog provenance distinguishes authored records from plugin components; plugin content is managed through package installation. Personal availability remains in the separate SkillLibraryService.

Uploads are bounded to 8 MiB of expanded content and 128 files; paths are normalized and reject links or traversal. SKILL.md's YAML frontmatter (name, description) becomes the skill's metadata, and its body becomes the runtime instructions. Supporting files keep their exact bytes and executable flag, and are copied into a private VM directory only when the agent's session has a workspace — instruction-only skills need no VM.

Webhooks