Référence API

Stib expose une API REST qui vous permet de construire des intégrations personnalisées, d'automatiser des workflows et d'interagir avec vos boards, cartes et agents de manière programmatique.

URL de base

Par défaut, l'API est disponible à l'adresse :

http://localhost:37100/api/

L'hôte et le port dépendent de la configuration de votre serveur Stib. Tous les chemins d'endpoints dans cette documentation sont relatifs à /api/.

Format de réponse

Toutes les réponses de l'API suivent un format d'enveloppe cohérent.

Réponse en cas de succès :

{
  "data": {
    "id": "abc123",
    "name": "My Project"
  }
}

Réponse en cas d'erreur :

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Project not found"
  }
}

TIP

Tous les champs JSON utilisent la convention camelCase (ex. : projectId, columnType, isAutoMode).

Authentification

L'authentification est optionnelle — elle peut être activée ou désactivée dans les paramètres de Stib. Lorsqu'elle est activée, incluez un Bearer token dans l'en-tête Authorization :

GET /api/projects HTTP/1.1
Authorization: Bearer <token>

Vous pouvez vérifier si l'authentification est active :

GET /api/settings/auth-status

Lorsque l'authentification est désactivée, tous les endpoints sont accessibles sans token.

Rôles serveur

Rôle	Description
user	Accès standard aux projets et organisations de l'utilisateur
admin	Peut gérer les utilisateurs via le panneau d'administration
super_admin	Administration complète du serveur — requis pour la gestion de l'authentification, la configuration OIDC, les sauvegardes et la gestion des utilisateurs

INFO

Les rôles serveur (user, admin, super_admin) sont distincts des rôles de membre d'organisation/projet (admin, member). Un utilisateur peut avoir le rôle serveur user tout en étant admin au sein d'une organisation spécifique.

Contexte d'organisation

Pour les configurations multi-organisations, passez l'identifiant de l'organisation dans un en-tête de requête :

GET /api/projects HTTP/1.1
X-Organization-Id: org_abc123

• Sans authentification : le X-Organization-Id est vérifié dans la base de données.
• Avec authentification : l'appartenance à l'organisation est vérifiée (les super admins contournent cette vérification).

Codes de statut HTTP

Code	Utilisation
200	GET, PATCH ou PUT réussi
201	POST réussi (ressource créée)
204	DELETE ou action réussie sans corps de réponse
400	Erreur de validation (champs manquants ou invalides)
401	Non autorisé (token manquant ou invalide)
403	Interdit (permissions insuffisantes)
404	Ressource non trouvée
409	Conflit (conflit d'état, ex. : doublon)
500	Erreur interne du serveur

Pagination

Certains endpoints de liste supportent la pagination via des paramètres de requête :

Paramètre	Type	Description
limit	number	Nombre maximum d'éléments à retourner
since	string	Retourner les éléments après cette date (ISO 8601)
before	string	Retourner les éléments avant cette date (ISO 8601)

Exemple :

GET /api/projects/{projectId}/cards/{cardId}/agent/messages?limit=50&since=2025-01-01T00:00:00Z

WebSocket

Stib utilise une connexion WebSocket pour les mises à jour en temps réel (déplacements de cartes, progression des agents, notifications).

ws://localhost:37100/api/ws?token=<token>

Lorsque l'authentification est activée, passez le Bearer token en paramètre de requête token. Connectez-vous à cet endpoint pour recevoir les événements envoyés par le serveur. Toutes les mutations de cartes et d'agents émettent des événements WebSocket, de sorte que les clients connectés restent synchronisés automatiquement.

Exemple rapide

Créer une carte via l'API externe :

curl

curl -X POST http://localhost:37100/api/cards \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "projectId": "project_abc123",
    "title": "Fix login bug",
    "prompt": "The login form does not validate email format"
  }'

Réponse — 201

{
  "data": {
    "id": "card_xyz789",
    "title": "Fix login bug",
    "prompt": "The login form does not validate email format",
    "projectId": "project_abc123",
    "columnId": "col_001",
    "position": 0
  }
}

Vérifier le statut de la carte :

curl http://localhost:37100/api/cards/card_xyz789/status \
  -H "Authorization: Bearer <token>"

{
  "data": {
    "id": "card_xyz789",
    "title": "Fix login bug",
    "columnName": "Backlog",
    "hasActiveAgent": false
  }
}

Pour la liste complète des endpoints disponibles, consultez la page Points d'accès.