API reference

Generated from the route definitions in apps/api/src by pnpm --filter @brio/api docs:api; do not edit by hand.

Every request is made as a signed-in person (the session cookie the web app uses) or with an API token (Authorization: Bearer brio_pat_…, bound to one workspace). Requests act in the workspace named by the x-brio-workspace header, else the session's active one. Bodies and responses are JSON; errors are { "error": code, "message": text } with the HTTP status. Live events are Server-Sent Events (GET /v1/missions/:id/events, resumable with Last-Event-ID). Sign-in and OAuth for MCP clients are Better Auth's routes under /api/auth; Brio's MCP server is at /mcp (tools listed in docs/ARCHITECTURE.md).

Who lists the workspace roles a route requires (owner, admin, member, viewer); any member includes viewers. Routes marked signed-in person only refuse API tokens.

#agents

#approvals

Approvals and deliveries (BUILD_PLAN M8, CLAUDE.md rule 6): a person approves or denies an action that waits on them (opening a pull request, pushing a branch); a member can ask again for a mission's delivery after one was denied or failed.

#attempts

#budgets

Budgets (M9, SECURITY_GOVERNANCE §5): the workspace's and each agent's monthly limits, and a mission's own, with what is spent now. Raising a mission's budget lets the tasks a spent budget stopped run again.

#chats

Chat (D-109): conversations with your agents. Each message becomes a task the orchestrator routes to the best agent, or to several working together; the reply streams onto the chat's events (GET /v1/missions/:id/events).

#connectors

#crews

Crews (PRD glossary): a saved set of agents and routing preferences ("my coding crew"). A mission routed to a crew uses only its agents, and the crew's preferred agent for a task type unless the plan pins another.

#evals

Golden-mission eval runs (BUILD_PLAN M5) for the evals dashboard: the harness saves a run (or a person uploads its results file), and the web app lists them with their metrics tables.

#health

#inbox

The approvals inbox (M8): everything in the workspace waiting for a person, across missions — plans to approve, results to review, questions and blockers from agents, and actions that need a yes (a pull request to open).

#ledger

The audit ledger (M9, SECURITY_GOVERNANCE §8): the workspace's hash-chained record of spend, decisions, keys, policies and side effects — read page by page, verified end to end (anyone can check that nothing was changed, removed or inserted), and exported for auditors as JSON Lines or CSV. Owners and admins only.

#mandate

Connecting the workspace's Mandate (D-07): its URL and one mandate's agent token, checked with Mandate and kept in the vault. From then on every paid attempt asks that mandate first (see ../mandate.ts).

#memory

Project memory for people (PRD F32, M9): what Brio remembers about a project — view and search it, add a preference or fact, correct an item, or forget it (its links go with it). Every change by a person is in the ledger. And the brief an agent would get for some files or a topic.

#messages

The mission's mailbox as people see it: agents' questions, blockers and review requests, and the user's answers. Also a person's verdict on a task waiting for review.

#missions

#notifications

Notifications and approvals beyond the web app (M9): each person's preferences, their browsers' push subscriptions, the workspace's Slack app, and Slack's callback when someone presses Approve or Deny.

#plans

Plan editor API (BUILD_PLAN M3): versions, edits (each a new version with lint), approve, and replan with notes.

#policies

Policies (M9, SECURITY_GOVERNANCE §4): data routing by sensitivity, the connector allow-list, network rules and quick-start limits. Owners and admins write them; every change is in the ledger. They take effect at once: the router and every dispatch read them.

#pricing

#projects

Projects: the repository a mission works on. A git URL (https) in the cloud; a local path too when the deployment allows it (self-host, local development), because the runner clones it from its own disk.

#registry

#runners

Local runners (BUILD_PLAN M8): a person registers their machine for a workspace (brio runner register), gets a token shown once, and starts the daemon with it. Host mode — no container — needs the owner's explicit consent, recorded with its words and time. Agents and projects are then bound to the runner.

#scoreboard

The scoreboard (ROUTING §5): who wins at which task type, at what cost and speed, with a trend per row; and people's thumbs up/down on attempts, which feed the same scores.

#templates

Templates (PRD F5): a plan saved as a reusable pipeline ("Research → memo → deck"). Saved from a mission's plan or written directly; a new mission starts from one, adapted to its goal by the planner or proposed as is.

#tokens

API tokens (M7): a person makes one for a workspace in the web app and gives it to the brio CLI, its stdio MCP server or an A2A client. The token is shown once; Brio keeps its sha256. Only a signed-in person (never a token) makes or revokes tokens, and only their own.

#usage

Usage analytics and the public status page (M10, D-105).

#workspaces

#a2a

Brio as an A2A agent (ARCHITECTURE §4.6, PRD F40; docs/vendors/protocols.md §1): an Agent Card at /.well-known/agent-card.json and a JSON-RPC endpoint at /a2a (A2A v1.0, with SSE streaming), built on the official SDK's request handler. Every message an agent sends becomes a mission in the caller's workspace; the A2A task follows the mission (working → input-required for a plan to approve or a question → completed with the report as an artifact) and is kept in Postgres, refreshed from the mission whenever it is read, so it survives restarts. Callers authenticate with a workspace API token.