Skip to content
Station Zero

Kanban

What it is for

The kanban service keeps boards of cards in columns for your organization. People work on a board in the browser and their agents work on the same board through these tools: a card created by one is moved, edited or commented on by another, and every board shows who did what. Use it to plan work, see what is waiting, in progress and done, and keep each task's working detail on its card.

It offers a trial, a number of days of free use, and it can also be enabled in full. Enabled in full, it is billed as a subscription rather than per call: a monthly fee that includes a number of active users, and a fee for each further person who used it within the active-user window, in the browser or through an agent acting for them.

Every tool works on this system's own boards only; none reaches outside it.

Working agreements

A board's description, and each column's description, are its working agreements: how the people on the board want the work done. They come with every snapshot of the board, ahead of its cards, so read them first and follow them: what a card needs before it moves to the next column, what "done" means, who picks up what. Changing them is a change to the board's setup.

Its tools

Every tool is covered by the subscription: no call is charged on its own, and no tool has a price per call.

Setting a board up (creating, copying, updating or archiving a board, and creating, changing or removing its columns and labels, including moving or archiving a column's cards in bulk) is for the organization's owners and admins. Working on cards, checklists, links and comments is for any member. An organization's API key holds the admin role.

Answers name boards, columns, cards, checklists, items, links and comments by their ids, and a card also by its number on the board (#12). Every board and card answer carries its url, the address that opens it in the browser.

Tools that only read

  • kanban_board_list lists the organization's boards, most recently updated first, each with its id, link, card counts and sequence; archived: true lists archived boards instead.
  • kanban_board_open opens one board: its working agreements, labels, columns and each column's first page of cards as summaries, never card bodies. A filter narrows the cards (by text, assignee, label, priority, due date, status, blocked, or mentioning you) and answers each column's match count; give your own calendar date as its today.
  • kanban_column_cards reads the next page of one column's cards, following that column's cursor, with the same filter.
  • kanban_board_sequence answers only the board's sequence, the cheap check of whether anything changed since you last read it.
  • kanban_board_activity lists what changed on a board, newest first: each write's sequence, who made it, and when. sinceSequence keeps only the writes after a sequence you read, and actor only one member's.
  • kanban_board_standup is a board's stand-up digest: for each assignee, and for cards with none, what was completed since since, and what is in progress, due soon or overdue, and blocked.
  • kanban_card_get reads a card's summary, properties, checklists, links and web links, with its properties etag; never its body.
  • kanban_card_by_number reads a card the same way by its number on the board.
  • kanban_card_body_read reads a card's whole markdown body, with its body etag and size.
  • kanban_card_body_lines reads a card's body as numbered lines, whole or from fromLine to toLine, with the body etag and line count.
  • kanban_card_body_search looks for literal text in card bodies, on one board or on every live board, ignoring case, and answers matching lines (lines, with optional context lines either side), matching cards (cards) or a count of matching lines per card (counts). Archived and deleted cards are not searched.
  • kanban_comment_list lists a card's comments, oldest first, each with its author and etag.
  • kanban_member_list lists the people and agents who can be assigned and mentioned, by display name and handle, and says which one is you.

Tools that add or change things

None of these drops anything a later call cannot set again.

  • kanban_board_create creates boards, several in one call, each with its columns and labels, all or none. A board sent without columns starts with To do, In progress and Done.
  • kanban_board_copy creates a new board with another board's description, columns and labels under a new name. It copies no cards.
  • kanban_board_update renames a board, replaces its description, or archives (archived: true) or restores (archived: false) it. Only the fields sent change.
  • kanban_column_create adds columns at the end of a board. A column may carry a WIP limit, the most cards it may hold, within the board's wipMin and wipMax; one left out starts at the board's wipDefault. A WIP limit of 0 means no limit. A done column (done: true) marks its cards done, with doneStatus as their sub-status, such as shipped.
  • kanban_column_update changes a column's name, description, color, WIP limit, done flag or done sub-status; only the fields sent change.
  • kanban_column_move places a column after another, or first.
  • kanban_column_restore brings back a removed column within the undo window.
  • kanban_column_archive_cards archives every card in a column in one write.
  • kanban_column_move_cards moves every card in a column to the end of another, in order, in one write; it is refused, with no card moved, when the target's WIP limit would be passed.
  • kanban_label_create adds labels to a board, each a name and a palette color. A label's name is its key, unique on the board ignoring case.
  • kanban_label_update renames or recolors a label, found by its current name; a rename follows on every card that carries it.
  • kanban_card_create creates whole cards in one column in one call, all or none: title, summary, markdown body, labels by name, assignees by handle, priority, dates, a blocked reason, checklists and web links. It is refused when the column's WIP limit would be passed.
  • kanban_card_move places a card in a column after another card, or first. It changes the card's position only, needs no etag, and is refused when the target column's WIP limit is full.
  • kanban_card_update changes a card's title, summary, priority, dates, cover color or blocked reason; only the fields sent change.
  • kanban_card_label_add and kanban_card_label_remove put labels on a card and take them off, by name.
  • kanban_card_assign and kanban_card_unassign add and remove a card's assignees, by handle.
  • kanban_card_body_append adds text to the end of a card's body, whatever it holds when the call runs. Nothing is put between, so start the text with a line break to begin a new line.
  • kanban_card_copy creates a copy of a card right after it, on the same board only, with the next number: its properties, body, labels, assignees, checklists and links, never its comments.
  • kanban_card_archive archives a card: the ordinary way to clear a finished card off the board. Until it is restored, an archived card's body can still be read with kanban_card_body_read and kanban_card_body_lines, and the card can be deleted; every other card tool answers it as not found, and a body search skips it.
  • kanban_card_restore brings back an archived card at any time, or a deleted one within the undo window, at the end of its column; it is refused when that column's WIP limit is full.
  • kanban_checklist_create adds checklists to a card, each with its items. To copy a checklist from another card, read that card and send its items.
  • kanban_checklist_rename renames a checklist.
  • kanban_check_item_add adds items to the end of a checklist.
  • kanban_check_item_update changes an item's text, its own due date or its own assignee.
  • kanban_check_item_toggle sets an item done or not done, to the value sent.
  • kanban_card_link_add links a card to other cards on the same board, by number, as blocked-by, blocks or relates-to; a card cannot link to itself.
  • kanban_attachment_link_add attaches web links to a card, each an http or https address with an optional title.
  • kanban_comment_add comments on a card as you, in markdown. An @handle in it records a mention of that member: the card then shows as mentioning them, and a filter with mentionsMe finds it for them. Nothing is sent to them.

Tools that replace or remove content

A deleted card and a removed column can be restored within the undo window, and a deleted card is purged for good once the retention period after it passes. Nothing else these tools replace or remove can be brought back.

  • kanban_card_body_edit replaces exact text in a card's body by a list of edits, each a find copied exactly from the body and the replace that takes its place; an empty replace deletes the text. Each find must occur exactly once, unless that edit's replaceAll is true. Matching is literal and case-sensitive, spacing and line breaks included. The edits apply in order, each to the body the ones before it left, and all or none: if any one is not found, or is found more than once, nothing changes and the refusal names that edit's index and how many matches it had.
  • kanban_card_body_write replaces a card's whole body. To change part of a body, edit it instead.
  • kanban_comment_edit replaces the whole text of a comment you wrote, keeping no earlier version; another member's is refused.
  • kanban_card_delete deletes a card. Archive a card instead to clear it off the board without losing it.
  • kanban_column_remove removes an empty column. A column that holds cards is refused: empty it first by moving or archiving its cards. A board's last column cannot be removed.
  • kanban_label_remove removes a label from a board and from every card that carries it.
  • kanban_checklist_remove removes a checklist and its items from a card.
  • kanban_check_item_remove removes an item from a checklist.
  • kanban_card_link_remove removes a link between cards, by the link's attachmentId.
  • kanban_attachment_link_remove removes a web link from a card, by its attachmentId.
  • kanban_comment_remove removes a comment you wrote; another member's is refused.

Read before you write

A card's properties, its body and each comment carry an etag of their own, which changes whenever that part changes. Updating a card's properties, replacing or editing its body, and editing a comment each need the etag a read returned: the properties etag from reading the card, the body etag from reading the body, a comment's etag from listing the comments. A write given an etag the row has moved on from is refused with the current etag and changes nothing, so a change another person or agent made meanwhile is never overwritten unseen: read again, look at what changed, then retry with the new etag.

Labels, assignees, moves and checklist changes leave the properties etag as it was, so they never stale a read you are about to write from.

Work on a body in a loop of read, edit, re-read: read the lines you mean to change, edit them with the body etag the read returned, and read again before the next edit, because the edit answers a new etag and the text has moved. The line numbers a read shows, as <number><tab><text>, are not part of the body: leave them out of a find, or it will not match.

An append needs no etag: it adds to whatever the body holds when it runs, so calling it twice appends twice.

Working together

Repeating a create safely. The creates of boards, cards, columns, labels, checklists, checklist items, card links and web links, and the board and card copies, take an idempotencyKey: any string unique to that create (on a batch of boards or cards, only the first entry carries it). Repeat the call with the same key and it answers what the first call created, as it stands now, instead of creating again. A key whose first attempt failed, or is still running, is refused as in flight: read the board to see what is there, then retry with a new key if it is still needed. A comment takes no key, so a repeated comment is posted twice.

People and agents by handle. Members are named by opaque handles from the member list, never by id or email: an assignee, a checklist item's assignee, the actor of an activity read, and an @handle mention. me names you, for a person and for an agent the member list shows; for a caller the members do not list, the list's me is null and naming me is refused.

Changes that are safe to repeat. Adding a label a card already carries, assigning a member already assigned, removing what is not there and setting an item to the state it is already in are no change, so these calls are safe to repeat; each one still raises the board's sequence.

Who did what. Every write raises the board's sequence by one and answers the new one. The board's activity names each write's actor by display name and handle and marks a person's change made through an agent "via AI", so people on the board can tell their own edits from their agents'. Check the sequence before re-reading a board; when it has moved, read the activity since the sequence you hold.

Paging

The board list, a column's cards, a board's activity, a card's comments and a body search answer a page at a time. When there is more, the answer carries a cursor: pass it back with every other argument unchanged for the next page, until the cursor comes back null.

A board snapshot holds each column's first page only, with that column's own cursor; read the rest of a column with kanban_column_cards.

A card body read whole is bounded by the read bound in the tool's description. A line range stops at that bound and answers truncated: continue from the line after the last one answered. A body search page likewise stops after a bounded amount of reported text and answers truncated with a cursor.

The activity feed keeps a board's history for the retention period only. Its answer's oldestRetained is the lowest sequence still kept; anything older has been purged, so a gap below it cannot be read.

The stand-up digest is judged against your dates, not the server's: send since (yesterday, for a daily stand-up) and today as your own calendar dates, and the answer states both. Each of its lists shows a bounded number of cards and counts the rest.

Its settings

Your organization's own limits, each capped by a platform ceiling of the same key with -ceiling added (services.kanban.max-boards-ceiling); the smaller of the two is the limit in force:

  • services.kanban.max-boards: the boards the organization may hold, archived boards included;
  • services.kanban.max-open-cards: the open cards one board may hold;
  • services.kanban.max-cards: the cards one board may hold, archived cards included;
  • services.kanban.max-columns: the columns one board may have;
  • services.kanban.max-labels: the labels one board may define;
  • services.kanban.max-checklists: the checklists the cards of one board may hold in all;
  • services.kanban.max-checklists-per-card: the checklists one card may hold;
  • services.kanban.max-items-per-checklist: the items one checklist may hold;
  • services.kanban.max-attachments-per-card: the links one card may carry;
  • services.kanban.max-assignees-per-card: the assignees one card may have;
  • services.kanban.max-comments-per-card: the comments one card may hold;
  • services.kanban.max-body-bytes: the largest card body, in UTF-8 bytes;
  • services.kanban.max-comment-bytes: the largest comment, in UTF-8 bytes.

services.kanban.wip-default is the WIP limit a new column starts with, within the platform's lowest and highest WIP limits, services.kanban.wip-min and services.kanban.wip-max. A WIP limit of 0 means no limit.

The platform's own:

  • services.kanban.undo-window-ms: how long a deleted card or a removed column can still be restored;
  • services.kanban.retention-deleted-days: how long a deleted card or removed column is kept before it is purged;
  • services.kanban.retention-idempotency-hours: how long a create's idempotencyKey is kept, and so how long a repeat with it answers the first result;
  • services.kanban.retention-activity-days: how long a board's activity is kept;
  • services.kanban.trial-days: the days of free use a trial grants;
  • services.kanban.active-user-period-days: the trailing window within which a person or agent who used the service counts as an active user;
  • services.kanban.included-users: the active users the monthly fee covers.

Its limits

Each count and size refuses at its limit. A write that would take a board, a card or the organization past one of the limits above is refused, names the limit it would pass, and changes nothing; nothing already stored is lost. Lowering a limit deletes nothing either: it only refuses the next write past it. There is no warning level before a limit: a write either fits or is refused. The values are settings and can change, so they are not written here.

A WIP limit is a column's own. A card create, move, copy or restore, or a bulk move of a column's cards, that would put more cards in a column than its WIP limit is refused whole. The board in the browser shows each limited column's count against its limit.

One call is bounded. How many boards, cards, columns or checklists one create makes, how many edits one body edit applies and how many replacements it makes, and how much one body read or search page returns are fixed bounds, each stated in its tool's description.

A body search is literal text, matched within one line and ignoring case, so it cannot contain a line break.

Bodies and comments are markdown, and a card or comment names another member with an @handle mention, which is recorded on the card; nothing is sent to that member.

Names, titles and other short text are one line. A board, column, label or checklist name, a card's title and summary, a checklist item's text, a done sub-status, a blocked reason and a web link's title cannot contain a line break. A description, a body and a comment can.

Kanban