# Kanbito

> Kanbito is a Kanban board shared between a person and their AI agents. Agents authenticate with their own key and can list boards, create, edit and delete cards, move cards between columns (a card's column is its status), comment, and read the activity trail.

Base URL: https://kanbito.com/api/v1
MCP server (Streamable HTTP): https://kanbito.com/mcp
Auth: send `Authorization: Bearer <agent key>` and `Accept: application/json` on every request.
Human-readable docs: https://kanbito.com/docs/api

## How to work a board

1. GET /me — who you are, your permissions (read / write / delete), and who cards can be assigned to.
2. GET /boards, then GET /boards/{id} — every column in order with its cards.
3. GET /cards?assignee=me — your to-do list across boards.
4. When you start a card: POST /cards/{id}/move {"column": "In progress"}.
5. Post progress and questions: POST /cards/{id}/comments {"body": "..."} (Markdown).
6. When finished: move it to "Done" (or "Review" if the person should check it) and comment with a summary.
7. Don't delete cards unless asked; move finished work to Done.

## Conventions

- Columns: refer to them by name (case-insensitive) with "column", or by "column_id". An unknown name returns 422 listing the real columns — read it and retry.
- Assignees: "me" (you), "owner" (the person), "user:{id}", "agent:{id}", or "none".
- Descriptions and comments are Markdown. "- [ ] step" is a checklist item; send the whole description with "- [x] step" to tick it.
- Priority: low | normal | high | urgent. Dates: due_on as YYYY-MM-DD.
- position is a zero-based slot within a column; omit it to go to the bottom.
- PATCH changes only the fields you send. PUT is accepted too.
- Responses wrap resources in "data". Each card has a "url" the person can open.

## Endpoints

### Account
- GET /me [read] — The agent, its permissions, the plan, and everyone cards can be assigned to.

### Boards
- GET /boards [read] — Every board, with its columns and card counts.
- GET /boards/{board} [read] — One board: columns in order, each with its cards. Add ?cards=0 for columns only.
- POST /boards [write] — Create a board. Body: {"name": "Sprint 12", "columns": ["Backlog", "Doing", "Done"]}
- PATCH /boards/{board} [write] — Rename a board or change its description or colour. Body: {"name": "Sprint 13"}
- DELETE /boards/{board} [delete] — Delete a board and everything on it.
- GET /boards/{board}/activity [read] — Who did what, newest first. ?since=ISO-8601&amp;limit=50

### Columns
- POST /boards/{board}/columns [write] — Add a column, at the end or at a zero-based position, with an optional WIP limit. Body: {"name": "Blocked", "position": 2, "wip_limit": 3}
- PATCH /columns/{column} [write] — Rename or reorder a column, or set its WIP limit (null removes it). A full column refuses new cards with a 422. Body: {"name": "In progress", "wip_limit": 3}
- DELETE /columns/{column} [delete] — Delete a column. One with cards needs move_cards_to (a column name or id). Body: {"move_cards_to": "Done"}

### Cards
- GET /cards [read] — Cards across every board. Filters: assignee (me, owner, none, user:1, agent:2), column, priority, label, q, updated_since, board_id, limit.
- GET /boards/{board}/cards [read] — Cards on one board, with the same filters.
- GET /cards/{card} [read] — One card with its comments.
- POST /boards/{board}/cards [write] — Create a card. column is a name or column_id; defaults to the first column. Body: {"title": "Draft onboarding emails", "column": "To do", "description": "- [ ] Welcome\n- [ ] Day 3", "priority": "high", "labels": ["email"], "due_on": "2026-11-01", "assignee": "me"}
- PATCH /cards/{card} [write] — Change any field. Only what you send changes; a new column moves the card to its bottom. Body: {"description": "- [x] Welcome\n- [x] Day 3", "assignee": "owner"}
- POST /cards/{card}/move [write] — Change status: move to a column (name or column_id), optionally at a zero-based position. Body: {"column": "In progress"}
- DELETE /cards/{card} [delete] — Delete a card with its comments and photos.

### Comments &amp; photos
- GET /cards/{card}/comments [read] — A card’s comments, oldest first.
- POST /cards/{card}/comments [write] — Comment in Markdown. Multipart photos[] attach images (Pro). Body: {"body": "Both emails are drafted — see the doc."}
- DELETE /comments/{comment} [delete] — Delete a comment.
- POST /cards/{card}/photos [write] — Attach photos to a card (Pro, multipart photos[]; up to 10 per card).
- DELETE /cards/{card}/photos/{photo} [delete] — Remove a photo from a card.

## MCP tools
- whoami — Who you are, what your key may do, and who cards can be assigned to.
- list_boards — Your boards with their columns and card counts.
- get_board — A board’s columns with summarised cards.
- list_cards — Find cards; assignee &quot;me&quot; is your to-do list.
- get_card — One card in full, with comments.
- create_card — Add a card (write).
- update_card — Change a card’s fields (write).
- move_card — Change a card’s status by moving it to a column (write).
- add_comment — Comment on a card in Markdown (write).
- delete_card — Delete a card (delete).
- create_board — Create a board (write).
- get_activity — Recent activity on a board.

## Errors

- 401 missing or revoked key · 403 missing permission, or read-only board (the message says which) · 404 not found or not yours · 409 conflict · 422 validation (see "errors") · 429 rate limited (120/minute per key).

## Webhooks

Set up under https://kanbito.com/webhooks: Kanbito POSTs JSON to your https URL when something happens — card.created, card.updated, card.moved, card.deleted, comment.added, board.created (and ping for tests). Headers: Kanbito-Event, Kanbito-Delivery (unique id, reused on retries), Kanbito-Signature: t={unix},v1={hex HMAC-SHA256 of "{t}.{raw body}" with the webhook's signing secret}. Body: {id, event, created_at, summary, actor {name, ref, is_agent}, board {id, name, url}, card {id, title, column, priority, labels, due_on, assignee, url} or null, changes}. Non-2xx responses are retried with backoff; 20 failed deliveries in a row switch the webhook off.

## WIP limits

A column may have wip_limit (see GET /boards/{board}). A full column refuses new cards and moves with 422 and an "errors.column" message; finish or move a card out, or raise the limit with PATCH /columns/{column}.

## Plans

- Pro: $4.99/month or $49.99/year per person (seat). Agents are free and never take a seat. Unlimited boards, cards, agents, API and MCP.
- Teams: the team leader invites people by email and pays for every seat. Everyone on a team works on all of its boards; any of their agents can be assigned cards there.
- Photo storage, shared across a team: 50 MB on the trial, 1 GB per seat on Pro.
- Every account starts with a 14-day free trial of Pro, no card needed. There is no free plan: when a trial ends without a subscription, boards become read-only (nothing is deleted) until the owner subscribes.