Endpoints d’automatisation

Tous les chemins sont relatifs à l’origine du serveur et exigent un Bearer token stib_ak_… autorisé.

Résumé

Méthode	Chemin	Permission
GET	/api/external/projects/{projectId}/boards	cards.read
GET	/api/external/projects/{projectId}/cards	cards.read
POST	/api/external/projects/{projectId}/cards	cards.create ou pipelines.trigger
GET	/api/external/projects/{projectId}/cards/{cardId}	cards.read
GET	/api/external/projects/{projectId}/stats	cards.read
PATCH	/api/external/projects/{projectId}/cards/{cardId}/move	cards.move
POST	/api/external/projects/{projectId}/cards/{cardId}/archive	agents.archive
POST	/api/external/projects/{projectId}/cards/{cardId}/agent/cancel	agents.cancel

Lister boards et colonnes

GET /api/external/projects/{projectId}/boards

Retourne chaque board avec id, name et ses columns ordonnées. Une colonne contient id, name, columnType et position. Résolvez ainsi un columnId au lieu de recopier un ID d’un autre serveur.

Lister les cartes

GET /api/external/projects/{projectId}/cards

Paramètres optionnels :

Paramètre	Signification
columnId	Filtre sur l’ID de colonne
status	Filtre sur le statut d’exécution exact
label	Filtre les cartes dont les labels sérialisés contiennent la valeur
limit	Taille de page ; 50 par défaut, 100 maximum
cursor	Retourne les cartes dont l’ID est supérieur au curseur

data contient items et nextCursor. nextCursor vaut null sans page suivante. Cartes supprimées, archivées et non-Kanban sont exclues.

Créer une carte

POST /api/external/projects/{projectId}/cards
Content-Type: application/json

{
  "title": "Ajouter des filtres de recherche",
  "prompt": "Ajouter les filtres statut et agent à la recherche globale et les couvrir par des tests.",
  "columnId": 17,
  "useWorktree": true
}

title est obligatoire. prompt, columnId et useWorktree sont optionnels. Sans columnId, Stib utilise la première colonne du board par défaut. La colonne choisie doit appartenir à ce board. useWorktree vaut true par défaut.

Retourne 201 Created et la carte dans data. La création initialise son pipeline mais laisse la carte inactive ; activez-la ensuite par un flux explicitement pris en charge si une exécution est souhaitée.

Lire une carte

GET /api/external/projects/{projectId}/cards/{cardId}

Retourne identité, projet/colonne/groupe, titre et prompt, statut, position, état non lu, branche Git, préférence worktree, dernière action agent, horodatages, verrous et résumés de sessions. La réponse externe omet volontairement le chemin serveur du worktree.

Statistiques projet

GET /api/external/projects/{projectId}/stats

Retourne les totaux de cartes Kanban actives par statut et colonne ainsi que le total des snapshots de tokens disponibles. Cartes archivées, supprimées et non-Kanban sont exclues.

Déplacer une carte

PATCH /api/external/projects/{projectId}/cards/{cardId}/move
Content-Type: application/json

{
  "targetColumnId": 18,
  "position": 0
}

Le déplacement déclenche les webhooks configurés et révoque les tokens de callback en quittant une exécution active. Ce point d’accès ne démarre pas le comportement agent de la colonne cible. Résolvez la colonne dans le même projet avant l’appel.

Archiver une carte

POST /api/external/projects/{projectId}/cards/{cardId}/archive

Archive la carte et révoque ses tokens de callback assistant. data vaut { "ok": true }.

Annuler un agent

POST /api/external/projects/{projectId}/cards/{cardId}/agent/cancel

Demande l’annulation de l’agent actif. data vaut { "ok": true } lorsque le gestionnaire accepte. Vérifiez ensuite carte et Git : l’annulation n’annule pas les fichiers déjà écrits.

Compatibilité

Les anciens endpoints /api/cards existent encore pour compatibilité, mais une nouvelle intégration doit utiliser /api/external/projects/... afin de rendre portée et permissions explicites.

Monitors de carte

Ces endpoints exécutés côté démon sont réservés aux tokens agent éphémères limités à leur propre carte. Les clés API externes longues durées n'y ont pas accès.

Créer un monitor

POST /api/projects/{projectId}/cards/{cardId}/monitors
Content-Type: application/json

{
  "command": "./check-ci",
  "intervalSecs": 45,
  "description": "État CI",
  "cwd": "/chemin/absolu/worktree-carte",
  "allowUnsandboxed": true
}

Crée un monitor persistant et le renvoie avec 201 Created. allowUnsandboxed doit valoir true : la commande tourne hors de la sandbox agent avec les droits système du serveur Stib. L'intervalle doit être compris entre 10 et 86 400 secondes, et cwd doit se résoudre dans le dépôt, le worktree géré ou le worktree attaché de la carte. Une carte peut avoir au plus huit monitors.

Lister les monitors

GET /api/projects/{projectId}/cards/{cardId}/monitors

Renvoie les monitors de la carte dans leur ordre de création, avec leur dernier statut, leurs horodatages, leur code de sortie et leur erreur diagnostique.

Supprimer un monitor

DELETE /api/projects/{projectId}/cards/{cardId}/monitors/{monitorId}

Supprime le monitor limité à la carte et renvoie 204 No Content. La boucle de réconciliation du démon termine une commande en cours et ses descendants.

Les erreurs stables incluent MONITOR_UNSANDBOXED_ACK_REQUIRED, MONITOR_COMMAND_INVALID, MONITOR_INTERVAL_INVALID, MONITOR_DESCRIPTION_INVALID, MONITOR_CWD_INVALID, MONITOR_CWD_OUTSIDE_CARD, MONITOR_LIMIT_REACHED, MONITOR_CARD_INACTIVE, MONITOR_TERMINAL_CARD_UNSUPPORTED et MONITOR_NOT_FOUND.