Control-plane API

This is the surface the Brainbase CLI itself talks to. It is documented here so you can read a CLI failure, reproduce a command with curl, or wire the same operations into CI — not as a public API contract.

Host and prefix

Every path below is relative to https://api.brainbaselabs.com/v2/cli. Point the CLI elsewhere with BRAINBASE_CONTROL_PLANE_URL; it appends the /v2/cli prefix itself.

curl "https://api.brainbaselabs.com/v2/cli/orgs" \
  -H "Authorization: Bearer $BRAINBASE_TOKEN"

MAS also serves this same router under /api/cli, so calling https://api.brainbaselabs.com/api/cli/… directly hits the same handlers with the same scope checks — one implementation, two prefixes.

Authentication

Send a bearer token: either a PAT (bbpat_…) or the access token from a browser login session. Both are accepted on every endpoint here.

Every write requires the publish scope; no read requires any scope. Each table below names the requirement per endpoint. A session token carries no scope list and is never scope-checked. See PAT scopes for the full model.

Organizations and teams

A team is a group inside an organization, and every agent lives in a team. These four endpoints back brainbase team list and the --team values the agent commands take. The two GETs have a long list of callers because every command that needs a team resolves one first — whether you passed --org / --team or are picking interactively.

GET /orgs returns every organization the caller is a member of, with the caller's role in each. The agents listing returns everything granted to the team — including agents owned by other members, matching the team view in the web app — newest grant first, capped by limit (default 200, no cursor). Group membership is checked on top of organization membership, so an organization member cannot enumerate a team they do not belong to.

POST /orgs/{org_id}/teams is reached from one place in the CLI: the "+ Create a new team" option in agent create's interactive team picker. No other command offers it.

Agents

PUT /agents/{agent_id} updates agent metadata and the two writable capability toggles — name, tagline, entrypoint, default_model, memory_enabled, browser_enabled. Omitted fields are left alone. The integration flags (slack_connected, meeting_connected, github_connected) are deliberately not writable here; they are changed through the connection endpoints below.

Manifest and revision

GET .../manifest returns the agent's whole content as a list of components — instructions, skills, MCP servers, playbooks, evals — each with its files and a content hash, plus the current revision. It may also return warnings describing content the server could not represent.

PUT .../manifest is a whole-manifest replacement, reconciled per component type: components present are created or updated, and components absent are unlinked or archived. Pass base_revision so the server can refuse the push with a conflict when the cloud has moved since you last read the manifest.

GET .../revision returns just {"revision": <n>} — a hash over the agent's content, not a counter. It is the cheap drift check. It covers instructions, skills, MCP servers, active playbooks, active evals, and secret key names — adding or removing a key moves it, changing a value does not. It does not cover integrations, so connecting or disconnecting Slack leaves the revision unchanged.

reconcile_evals requires base_revision in the same request. Without it the server refuses with 400 rather than let a client that never pulled the evals archive them.

Secrets

Both carry {"secrets": {"KEY": "value"}}. The GET returns values in plaintext. The PUT is a whole-map replace: keys you omit are removed, so read before you write. Keys must be valid environment-variable names; anything else is rejected with 400.

Agent keys

Agent keys (bb_live_…) are a third credential class, distinct from PATs and sessions. link mints one so an agent's sandbox can call back to Brainbase; unlink revokes it.

The POST returns the plaintext key once, with its id and prefix; only a hash is stored. The GET lists an agent's keys by prefix, never the secret. DELETE takes the key id and is idempotent from the caller's point of view — a key that is already gone answers 404.

Connections and MCP

GET .../connections reports every integration on the agent and, per integration, whether the CLI can change it — manageable_from_cli, with an unmanageable_reason when it cannot. Slack and meeting are manageable from the terminal; GitHub and phone need the web app.

Both PUTs are idempotent: re-running with fresh credentials rotates them in place. Slack takes bot_token and signing_secret (plus optional app_id and app_name); meeting takes bot_name and an optional bot_image_url. DELETE removes the install rather than deactivating it, matching what the console's disconnect leaves behind.

GET .../mcp-servers returns each server's transport, enabled state, authorization state (none, oauth_required, oauth_connected, oauth_expired) and last connectivity result. Tokens are never returned — only whether one exists and when it lapses.

Evals

Read-only by design: eval definitions are managed declaratively through the manifest, so these exist to answer "what does the cloud think?" from a terminal. evals takes include_archived (default false) to include definitions a push has archived. eval-runs returns verdicts newest first, optionally narrowed with task_id, and limit (default 50, max 200).

Orchestrations

The bare GET returns the orchestration with its members and edges but no per-member manifests. The /manifest variant inlines every member's full agent manifest under members[].manifest, which is what orchestration pull consumes in a single round trip.

PUT is a partial update, with one exception: members and edges are whole-replace. Omit them to leave them unchanged; send [] to clear them. Pass base_revision for the same conflict protection the agent manifest has. Every declared member must already have access to the parent team, or the request is refused with 400.

Errors

Errors are JSON with a detail field, either a string or an object carrying code and message.