Référence API

Cette référence couvre l’API d’automatisation limitée au projet sous /api/external/projects/.... Les clients web et bureau appellent beaucoup d’autres routes /api/..., mais ce sont des contrats internes client/serveur et non une API tierce stable documentée.

URL de base

Utilisez l’origine du serveur, sans suffixe /api :

text

https://stib.example.com

Pour un serveur natif local, l’origine préférée est http://localhost:50505 ; utilisez le port réel s’il a changé.

Clés API

Créez une clé dédiée dans la portée Clés API adaptée : serveur, organisation ou projet. Choisissez son expiration et uniquement les permissions nécessaires. Utilisez un propriétaire et une clé distincts pour chaque frontière de confiance plutôt que de réemployer une clé d’administrateur.

La clé complète commence par stib_ak_ et n’est affichée qu’une fois. Envoyez-la comme Bearer token :

http

Authorization: Bearer stib_ak_…

Ne placez pas la clé dans une URL et ne la commitez pas. Les clés sont limitées à 100 requêtes par minute par clé, peuvent expirer et sont contrôlées selon les permissions de route et les accès de leur compte propriétaire.

Permissions

Les endpoints externes utilisent :

Permission	Autorise
`cards.read`	Lister/lire cartes, boards et statistiques projet
`cards.create` ou `pipelines.trigger`	Créer une carte et initialiser sa configuration de pipeline ; la création n’active pas l’agent
`cards.move`	Déplacer une carte vers une colonne
`agents.cancel`	Annuler l’agent actif d’une carte
`agents.archive`	Archiver une carte

D’autres permissions existent pour les routes client limitées au projet, mais les accorder ne transforme pas une route interne non documentée en contrat stable.

Format des réponses

Les succès sont enveloppés dans data :

json

{
  "data": {
    "id": 42,
    "status": "idle"
  }
}

Les erreurs ont une enveloppe et un code exploitable :

json

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "API key does not have the required permission"
  }
}

Les codes courants sont 400, 401, 403, 404, 409, 429, 500 et 503. Appliquez un backoff et respectez Retry-After lorsqu’il est fourni pour une limite de débit ou une contention de base.

Exemple rapide

bash

export STIB_ORIGIN='https://stib.example.com'
export STIB_API_KEY='stib_ak_…'
export STIB_PROJECT_ID='12'

curl --fail-with-body \
  -H "Authorization: Bearer $STIB_API_KEY" \
  "$STIB_ORIGIN/api/external/projects/$STIB_PROJECT_ID/cards?limit=20"

Pour une automatisation réelle, utilisez un gestionnaire de secrets plutôt qu’une variable de shell interactive.

Suite : Endpoints.

Référence API ​

URL de base ​

Clés API ​

Permissions ​