REST / OpenAPI reference

The canonical, machine-readable REST contract is the OpenAPI 3 document the api generates from the shared Zod DTOs. It is always available live at:

GET /openapi.json

A committed snapshot lives at docs/reference/openapi.json — load it into any OpenAPI viewer (Swagger UI, Redoc, Stoplight, Insomnia, Postman) or code generator. The snapshot is regenerated from the running api with pnpm docs:openapi:snapshot, and pnpm docs:openapi:check fails if it drifts, so this reference can't silently rot.

For the narrative conventions — authentication, idempotency (clientMutationId), ?since polling, moves, the error envelope, rate limits — see Agents → REST. For DTO shapes, packages/shared (Zod) is the single source of truth.

Endpoints

The complete operation list, grouped by resource, generated from the snapshot:

.well-known

Method	Path	Summary
GET	/.well-known/oauth-authorization-server

actors

Method	Path	Summary
GET	/api/actors/{actorId}/webhooks	List an agent's actor-scoped webhook subscriptions
POST	/api/actors/{actorId}/webhooks	Register an actor-scoped webhook for an agent (the agent's own token, or a human admin of a board it works on). Secret returned once.
DELETE	/api/actors/{actorId}/webhooks/{webhookId}	Delete an agent's actor-scoped webhook subscription

attachments

Method	Path	Summary
PUT	/api/attachments/{id}/content
POST	/api/attachments/{id}/complete	Confirm an attachment upload
GET	/api/attachments/{id}
DELETE	/api/attachments/{id}

auth

Method	Path	Summary
POST	/api/auth/register
POST	/api/auth/login
POST	/api/auth/logout
POST	/api/auth/logout-all
GET	/api/auth/me

automations

Method	Path	Summary
PATCH	/api/automations/{id}	Update an automation rule (admin only)
DELETE	/api/automations/{id}	Delete an automation rule (admin only)
GET	/api/automations/{id}/runs	Per-rule run history (activity-backed, admin only). ?limit= (default 50, max 200).

boards

Method	Path	Summary
GET	/api/boards
POST	/api/boards	Create a board
GET	/api/boards/{id}
PATCH	/api/boards/{id}	Update a board
PUT	/api/boards/{id}/favorite	Star/unstar the board for the calling member
POST	/api/boards/{id}/lists	Create a list
GET	/api/boards/{id}/members	List a board's members
POST	/api/boards/{id}/members	Add a member by email or actorId (admin only)
PATCH	/api/boards/{id}/members/{actorId}	Change a member's role (admin only)
DELETE	/api/boards/{id}/members/{actorId}	Remove a member (admin only)
GET	/api/boards/{id}/agents	Agent roster: agent members + credential metadata (admin only)
PATCH	/api/boards/{id}/members/{actorId}/capabilities	Edit an agent's capability flags (admin only; instance-global effect)
DELETE	/api/boards/{id}/members/{actorId}/credentials/{credentialId}	Revoke one of an agent member's API-token credentials (admin only)
GET	/api/boards/{id}/labels	List a board's label palette
POST	/api/boards/{id}/labels	Create a board label
GET	/api/boards/{id}/fields	List a board's fields
POST	/api/boards/{id}/fields	Create a custom field
PATCH	/api/boards/{id}/fields/{fieldId}	Update a field
DELETE	/api/boards/{id}/fields/{fieldId}	Archive a custom field
POST	/api/boards/{id}/fields/{fieldId}/reorder	Reorder a field between neighbors
GET	/api/boards/{id}/views	List the saved views visible to the caller (board-shared + own personal)
POST	/api/boards/{id}/views	Create a saved view (personal by default; shared:true is admin-gated)
GET	/api/boards/{id}/activity	Board activity feed (?since= poll)
GET	/api/boards/{id}/webhooks	List a board's webhook subscriptions (admin only)
POST	/api/boards/{id}/webhooks	Create a webhook subscription (admin only)
PATCH	/api/boards/{id}/webhooks/{webhookId}	Update a webhook subscription (admin only). Re-activating clears the auto-disable failure streak.
DELETE	/api/boards/{id}/webhooks/{webhookId}	Delete a webhook subscription (admin only)
GET	/api/boards/{id}/integrations	List a board's integrations
POST	/api/boards/{id}/integrations	Install an integration (admin only) — returns token + secret once
GET	/api/boards/{id}/integrations/{integrationId}	Get one integration
PATCH	/api/boards/{id}/integrations/{integrationId}	Update / enable / disable an integration (admin only)
DELETE	/api/boards/{id}/integrations/{integrationId}	Remove an integration (admin only)
PUT	/api/boards/{id}/integrations/{integrationId}/secrets	Set an integration's secrets (admin only; write-only)
GET	/api/boards/{id}/links	List a board's links, optionally filtered by external_id
GET	/api/boards/{id}/sessions	A board's agent sessions, newest first (?state= filters, e.g. state=awaiting_input for everything blocked on a human)
GET	/api/boards/{id}/automations	List a board's automation rules (admin only)
POST	/api/boards/{id}/automations	Create an automation rule (admin only)

cards

Method	Path	Summary
GET	/api/cards/{id}
PATCH	/api/cards/{id}	Edit a card, or move it with
GET	/api/cards/by-key/{key}	Fetch a card by its human-readable key (e.g. TRK-42)
POST	/api/cards/{id}/archive
POST	/api/cards/{id}/labels	Apply a label to a card
DELETE	/api/cards/{id}/labels/{labelId}	Remove a label from a card
PUT	/api/cards/{id}/fields/{fieldId}	Set a custom field value on a card
DELETE	/api/cards/{id}/fields/{fieldId}	Clear a custom field value on a card
POST	/api/cards/{id}/assignees	Assign a member (human or agent) to a card
DELETE	/api/cards/{id}/assignees/{actorId}	Unassign an actor from a card
POST	/api/cards/{id}/delegation	Delegate a card to an agent (replaces any existing delegation)
DELETE	/api/cards/{id}/delegation	Remove a card's delegation
GET	/api/cards/{id}/comments	List a card's comments
POST	/api/cards/{id}/comments	Add a comment to a card
GET	/api/cards/{id}/checklist-items	List a card's checklist items in order
POST	/api/cards/{id}/checklist-items	Add a checklist item to the end of a card's checklist
GET	/api/cards/{id}/attachments
POST	/api/cards/{id}/attachments	Declare an attachment upload on a card
GET	/api/cards/{id}/activity	Card activity feed (?since= poll)
GET	/api/cards/{id}/links	List a card's external links
POST	/api/cards/{id}/links	Link a card to an external object (integration only)
POST	/api/cards/{id}/events	Emit an integration vcs.* event for a card (integration only)
DELETE	/api/cards/{id}/links/{linkId}	Remove a card link (integration only)
PUT	/api/cards/{id}/watch	Watch a card (idempotent; viewer role suffices)
DELETE	/api/cards/{id}/watch	Stop watching a card (idempotent)
POST	/api/cards/{id}/sessions	Open an agent session on a card (api-triggered)

checklist-items

Method	Path	Summary
PATCH	/api/checklist-items/{id}	Update a checklist item (text / done / assignee). done:true stamps doneAt/doneBy
DELETE	/api/checklist-items/{id}	Delete a checklist item (hard delete; activity keeps history)
POST	/api/checklist-items/{id}/reorder	Move a checklist item between the named neighbor items (server derives the rank)

comments

Method	Path	Summary
PATCH	/api/comments/{id}	Edit a comment (author only)
DELETE	/api/comments/{id}	Delete a comment (author only)

deliveries

Method	Path	Summary
POST	/api/deliveries/{id}/redeliver	Manually re-deliver a logged delivery (admin only). One attempt, same stable X-Kanban-Delivery-Id, fresh signature.

lists

Method	Path	Summary
PATCH	/api/lists/{id}	Rename or reorder a list
POST	/api/lists/{id}/archive	Archive (soft-delete) a list
POST	/api/lists/{id}/cards	Create a card

me

Method	Path	Summary
GET	/api/me/preferences	My personal preferences (auto-watch)
PATCH	/api/me/preferences	Update my personal preferences

notifications

Method	Path	Summary
GET	/api/notifications	List my notifications (newest first; ?unread filters, cursor pages)
POST	/api/notifications/{id}/read	Mark one of my notifications read (idempotent)
POST	/api/notifications/read-all	Mark ALL my unread notifications read (idempotent)

oauth

Method	Path	Summary
POST	/api/oauth/register
GET	/api/oauth/authorize
POST	/api/oauth/authorize
POST	/api/oauth/token

openapi.json

Method	Path	Summary
GET	/openapi.json

search

Method	Path	Summary
GET	/api/search/cards	Full-text card search (title + description) with structured filters. Scoped to one board with ?boardId, else to every board the principal can read. Arrays are comma-separated; fieldValues is a JSON-encoded array; a q like TRK-42 resolves that card first.

sessions

Method	Path	Summary
GET	/api/sessions/mine	The caller's own agent sessions across every board (?state= filters). The polling fallback for an endpoint-less agent.
GET	/api/sessions/{id}	Fetch one agent session (state, statusText, trigger, stale)
GET	/api/sessions/{id}/events	A session's event trail. ?since=<event id
POST	/api/sessions/{id}/events	Post one protocol op (update

tokens

Method	Path	Summary
GET	/api/tokens
POST	/api/tokens
DELETE	/api/tokens/{id}

views

Method	Path	Summary
PATCH	/api/views/{id}	Update a saved view (name / filters / shared toggle — sharing is admin-gated)
DELETE	/api/views/{id}	Delete a saved view (hard delete)
POST	/api/views/{id}/reorder	Move a saved view between the named neighbor views (server derives the rank)

webhooks

Method	Path	Summary
GET	/api/webhooks/{id}/deliveries	Delivery log for a subscription, newest attempt first (admin only). ?limit= caps the page (default 50, max 200).

ws

Method	Path	Summary
GET	/ws

ws-ticket

Method	Path	Summary
POST	/api/ws-ticket	Mint a single-use, short-TTL WebSocket handshake ticket for the caller