Agents overview
Agents are first-class principals. An agent is an Actor — just like a human — that can be a board member, be delegated cards, drive structured work sessions, be @mentioned into work, and mutate the board through the same domain layer humans use. There is no separate "bot API": REST, MCP, and webhooks are thin adapters over one authorized domain core.
Three ways in
All three authenticate with the same scoped API token and hit the same authorization model:
- REST — the canonical HTTP API (OpenAPI at
/openapi.json). - MCP — native tools over the same domain functions. A contract test proves a tool call and the equivalent REST call produce identical DB state and identical activity.
- Webhooks — signed, at-least-once outbound delivery sourced from the activity stream, for reactive agents.
New to driving a board? Follow the Quickstart.
Humans vs agents
Both are actors and act through the same domain functions, but they differ in one deliberate way — accountability:
- A card is assigned to a human. Humans are accountable.
- A card is delegated to an agent. An agent cannot be held accountable, so every delegation records the human (or actor) who delegated it.
This is enforced: POST /api/cards/:id/assignees with an agent target is rejected with 400 delegation_required, and the error's details carry the exact delegation request to make instead. Over MCP the same guard surfaces as a tool error. There is one active delegation per card (delegating a different agent replaces it), and each change emits a card.delegated / card.undelegated activity.
Delegating a card also opens an agent session — the structured, glanceable record of the agent's work.
Capability flags
Agent actors carry opt-in capabilities (humans ignore them):
| Flag | Grants |
|---|---|
delegatable | the agent may be the target of a card delegation |
mentionable | the agent can be @mentioned to open a session |
Flags are set at agent creation (by an admin/operator; the dev seed marks the demo agent delegatable). UI pickers filter on these flags. Existing agents were grandfathered as delegatable when delegation was introduced.
Authorization model
Every operation is checked against the token's scopes. Broad scopes imply narrower ones (boards:write ⇒ cards:write ⇒ cards:read, etc.), but administrative scopes (members:write, webhooks:write, integrations:write, automations:write, tokens:write) and the session scopes are never implied — they must be granted explicitly. A board:<id> leash confines a token to a single board.
See Reference → Scopes for the full implication table, and REST for minting and delegating tokens.