List all boards.

Get one board (includes its columns and label registry).

Create a board. Omit id to have one generated; columns/labels may be inlined.

Send an idempotency_key (any unique string, REUSED on retry) so a retried call returns the original board instead of creating a duplicate.

Partially update a board — only the fields set in patch are applied.

Delete a board permanently. Refused while live cards remain — move/archive first.

List a board's columns (name, order, semantic category, wip_limit).

Add a column to a board. category gives it portable semantics (e.g. 'done'). idempotency_key (reused on retry) prevents duplicate creation.

Partially update a column (rename, reorder via order, set wip_limit...).

Delete a column permanently. Refused while live cards sit in it — move/archive first.

List a board's cards. Archived cards are hidden unless include_archived=true (that's how you find unarchive/purge targets).

Get one card (works for archived cards too).

Create a card. placements must have >=1 entry (board_id, column_id, position). Send an idempotency_key (any unique string, REUSED on retry) so retries return the original card instead of duplicating it.

Partially update a card — only the fields set in patch are applied.

Update one structured work_report section/item on a card.

Current state lives in card.ext["work_report"]; every successful call also emits a work_report.updated changelog event. Use this instead of rewriting the whole ext blob. List sections require item.id and are upserted by that id; singleton sections are replaced.

Answer one work_report question and mirror the answer as a normal comment.

Move a card within a board it's already on (re-column / re-position).

Errors if the card has no placement on to_board_id (use add_placement), or if the card's workflow scheme forbids the transition — check list_transitions first. force=true deliberately overrides scheme + WIP validation; the override is always recorded in the change-log, never silent.

What moves are legal for this card right now, and under which resolved scheme.

Sources: the card's flow scheme (flow.yaml; 'free-roam' = unrestricted), the backend's own workflow (e.g. hermes), or free movement when nothing is configured.

Available workflow schemes: every flow.yaml scheme (+ built-in 'free-roam'), with states, allowed transitions, and which scheme is the default.

Put a card on an additional board (one placement per board; errors if already on it).

Take a card off one board (its other placements stay). The last placement can't be removed — archive_card instead.

Archive a card (soft, recoverable — the default way to remove one).

Restore an archived card.

Permanently purge a card. Only allowed on an ARCHIVED card — archive_card first.

List a card's comments.

Add a comment to a card (card_id, author = User id, body). idempotency_key (reused on retry) prevents duplicate comments.

Delete a comment permanently.

List a card's typed relations (blocks, parent/child, duplicates, ...).

Link two cards with a typed relation. Subtask = kind 'child' from parent card. idempotency_key (reused on retry) prevents duplicate relations.

Delete a relation permanently.

What should I work on? Workable cards for assignee (default: YOU, this connection's actor) — assigned to you or unassigned, in backlog/ready/started columns, cards leased to others excluded. Each item carries its legal transitions, so one call gives you the whole plan.

Atomically lease a card so no other agent picks it up (visible in list_work). The lease expires after ttl_seconds unless renewed via heartbeat_claim — a crashed agent's card becomes claimable again automatically. owner overrides the actor (claim on behalf of a specific worker); defaults to the connection's own actor. Convention: after claiming, assign yourself and move the card to a started column.

Renew your live lease on a card while still working it. owner must match the one the claim was taken with (claims held on a worker's behalf renew on that worker's behalf); defaults to the connection's own actor.

Release your lease (done or giving up). owner overrides the actor (release on behalf of the claimed worker); defaults to the connection's own actor.

Flag a card as needing a decision or input (e.g. a question only a human or a specific agent can answer). Routable: the change-log event carries the reason and the target actor, so notifier agents DM the right party. Put the actual question in a comment; this flag is the signal, not the discussion.

Clear a card's attention flag (question answered / decision made). Put the answer in a comment; resolution is a one-liner for the event stream.

Change feed: every recorded write after cursor since (audit trail + sync).

Each event carries seq (the cursor — pass the last seq back as since), ts, actor (who did it), entity/op (e.g. card.moved), and a slim data payload.

Long-poll change feed: returns AS SOON AS events exist after cursor since (instant for writes through this server; other processes within ~2s), or empty after timeout_seconds. since=-1 probes the current cursor without replaying history — call that once, then loop with the returned cursor. Push semantics without polling loops.