API agent Kanban

Guide pour connecter un agent LLM à un board Kanban Kubiq : authentification par token, endpoints REST, exemples curl et bonnes pratiques.

Vue d'ensemble

Chaque board Kanban peut exposer une API agent dédiée. Un admin génère un token depuis le bouton « Accès agent » sur le board ; l'agent l'utilise ensuite pour lire et écrire les tickets sans compte Firebase utilisateur.

Cas d'usage typiques :

Un agent Cursor / Claude qui prend un bug, ouvre une PR, puis met à jour le ticket (lien PR, checklist, colonne).
Lister les cartes d'une colonne (ex. TODO bugs) filtrées par assignee ou label.
Créer un ticket quand un fix est fait hors board, avec le lien PR dès la création.
Obtenir un résumé markdown prêt pour LLM via format=llm sur une carte.

Authentification

Le token est scoped à un seul board. Il commence par kb_ et ne s'affiche en clair qu'une seule fois à la génération / régénération.

Sur chaque requête agent, envoyez :

x-api-key: kb_…

Dans l'environnement de l'agent, stockez typiquement :

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

communityId & boardId

Le token seul ne suffit pas : chaque appel doit cibler le board avec :

communityId — paramètre community de l'URL Kanban (ou personal pour un board perso).
boardId — paramètre board de l'URL Kanban.

Ils sont dans l'URL du board ouverte dans Kubiq :

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

Endpoints

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

Méthode	Chemin	Rôle
GET	/api/kanban/board	Métadonnées board (colonnes, labels, membres).
GET	/api/kanban/cards	Lister / filtrer les cartes (columnId, assignee, labelId, cardId, cardNumber, unassigned).
POST	/api/kanban/cards	Créer une carte (title, columnId, description, links, labels, assignees, checklists, position, createdBy optionnel).
GET	/api/kanban/card	Lire une carte ; ajoutez format=llm pour un résumé markdown.
PATCH	/api/kanban/card	Mettre à jour titre, description, checklists, links, labelIds, assignedTo, assignedToUsers, color, createdBy.
POST	/api/kanban/move	Déplacer une carte vers une autre colonne (toColumnId). Sans order, la carte est placée en haut.

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

GET /card?…&format=llm renvoie { card, meta, summary } où summary est un markdown compact pour le contexte LLM.

Les links acceptent des URLs string et/ou des objets { url, title? } — l'API normalise en { id, url, title }. position vaut "top" (défaut) ou "bottom".

createdBy est optionnel. S'il est omis, l'API tamponne l'acteur système « agent » — affiché « Agent » sur le board (même traitement que les notifications Kanban). Pour attribuer la carte à un membre du board, passez son UID Firebase en POST ou PATCH. Un UID qui n'est pas membre du board est rejeté (HTTP 400). Passez "agent" (ou null) pour rétablir l'acteur système.

Exemples curl

Charger le board (IDs de colonnes / labels)

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

Lister les cartes d'une colonne

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

Créer une carte

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"

Mettre à jour une carte

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"

Déplacer une carte

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"

Workflow agent recommandé

Charger KANBAN_URL + KANBAN_TOKEN, parser communityId / boardId.
GET /board pour récupérer les columnId et labelIds du board.
Lister ou créer le ticket ; un ticket agent = une PR (mettre le lien dans links).
Pendant le travail : PATCH (checklist, description) + move vers la colonne « En review ».
Une fois déployé : move vers la colonne « déployé / à présenter » — ne pas clôturer dans les colonnes « affaire réglée » réservées aux admins, sauf consigne contraire du board.

Sécurité

Ne jamais committer le token (kb_…) dans git ; uniquement .env.local / secrets CI.
Le token est par board : un agent ne peut pas accéder aux autres boards de la communauté.
Régénérez le token s'il a fuité ; l'ancien est immédiatement invalidé.
Le journal d'accès dans la modale montre les appels récents (méthode, action, HTTP, IP).