Kanban agent API

Guide to connect an LLM agent to a Kubiq Kanban board: token auth, REST endpoints, curl examples, and recommended workflow.

Overview

Each Kanban board can expose a dedicated agent API. An admin generates a token from the board's « Agent access » button; the agent then reads and writes tickets without a Firebase user session.

Typical uses:

A Cursor / Claude agent picks up a bug, opens a PR, then updates the ticket (PR link, checklist, column).
List cards in a column (e.g. TODO bugs) filtered by assignee or label.
Create a ticket when a fix is done off-board, with the PR link at creation time.
Fetch an LLM-ready markdown summary via format=llm on a card.

Authentication

The token is scoped to a single board. It starts with kb_ and is shown in cleartext only once at generation / regeneration.

On every agent request, send:

x-api-key: kb_…

In the agent environment, typically store:

KANBAN_URL=https://www.kubiq.net/kanban?community=COMMUNITY_ID&board=BOARD_ID
KANBAN_TOKEN=kb_YOUR_TOKEN_HERE

communityId & boardId

The token alone is not enough — every call must target the board with:

communityId — the community query param from the Kanban URL (or personal for a personal board).
boardId — the board query param from the Kanban URL.

They appear in the board URL opened in Kubiq:

https://www.kubiq.net/kanban?community=…&board=…

Endpoints

Base URL = Kubiq origin (prod: https://kubiq.net). Auth: x-api-key header.

Method	Path	Purpose
GET	/api/kanban/board	Board metadata (columns, labels, members).
GET	/api/kanban/cards	List / filter cards (columnId, assignee, labelId, cardId, cardNumber, unassigned).
POST	/api/kanban/cards	Create a card (title, columnId, description, links, labels, assignees, checklists, position, optional createdBy).
GET	/api/kanban/card	Read a card; add format=llm for a markdown summary.
PATCH	/api/kanban/card	Update title, description, checklists, links, labelIds, assignedTo, assignedToUsers, color, createdBy.
POST	/api/kanban/move	Move a card to another column (toColumnId). Without order, the card is placed at the top.

Useful GET /cards filters: columnId, assignee (Firebase UID), labelId, cardNumber, unassigned=1, cardId.

GET /card?…&format=llm returns { card, meta, summary } where summary is compact markdown for LLM context.

links accept URL strings and/or { url, title? } objects — the API normalizes to { id, url, title }. position is "top" (default) or "bottom".

createdBy is optional. If omitted, the API stamps the system actor "agent" — shown as Agent on the board (same treatment as Kanban notifications). To attribute a card to a board member, pass their Firebase UID on POST or PATCH. A UID that is not a member of the board is rejected (HTTP 400). Pass "agent" (or null) to reset the creator to the system actor.

Curl examples

Load the board (column / label IDs)

curl -s -H "x-api-key: $KANBAN_TOKEN" \
  "https://www.kubiq.net/api/kanban/board?communityId=COMMUNITY_ID&boardId=BOARD_ID"

List cards in a column

curl -s -H "x-api-key: $KANBAN_TOKEN" \
  "https://www.kubiq.net/api/kanban/cards?communityId=COMMUNITY_ID&boardId=BOARD_ID&columnId=COLUMN_ID"

Create a card

curl -s -X POST -H "x-api-key: $KANBAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "communityId": "COMMUNITY_ID",
    "boardId": "BOARD_ID",
    "columnId": "COLUMN_ID",
    "title": "Bug: …",
    "description": "…",
    "position": "top",
    "links": ["https://github.com/org/repo/pull/123"],
    "assignedTo": "FIREBASE_UID",
    "assignedToUsers": ["FIREBASE_UID"],
    "labelIds": ["label_0"]
  }' \
  "https://www.kubiq.net/api/kanban/cards"

Update a card

curl -s -X PATCH -H "x-api-key: $KANBAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Bug: corrigé",
    "links": ["https://github.com/org/repo/pull/123"],
    "checklists": [],
    "createdBy": "FIREBASE_UID"
  }' \
  "https://www.kubiq.net/api/kanban/card?communityId=COMMUNITY_ID&boardId=BOARD_ID&cardId=CARD_ID"

Move a card

curl -s -X POST -H "x-api-key: $KANBAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "communityId": "COMMUNITY_ID",
    "boardId": "BOARD_ID",
    "cardId": "CARD_ID",
    "toColumnId": "COLUMN_ID"
  }' \
  "https://www.kubiq.net/api/kanban/move"

Recommended agent workflow

Load KANBAN_URL + KANBAN_TOKEN, parse communityId / boardId.
GET /board to recover columnId and labelIds for the board.
List or create the ticket; one agent ticket = one PR (put the link in links).
While working: PATCH (checklist, description) + move to the « In review » column.
Once deployed: move to the « deployed / present to team » column — do not close into admin-only « done » columns unless the board says otherwise.

Security

Never commit the token (kb_…) to git; only .env.local / CI secrets.
The token is per board: an agent cannot access other boards in the community.
Regenerate the token if it leaked; the old one is invalidated immediately.
The access log in the modal shows recent calls (method, action, HTTP, IP).