Guides
Conventions de l’API
Adresse et format
Toutes les ressources sont sous /api/v1. Les corps sont en JSON UTF-8, les dates en ISO 8601 (UTC). Ignorez les champs inconnus : de nouveaux champs peuvent apparaître sans changement de version.
Isolation
L’organisation est déduite du jeton. Aucun paramètre ne permet d’en choisir une autre. Un identifiant appartenant à une autre organisation répond 404.
Pagination
Les listes acceptent limit (1 à 100, 25 par défaut) et cursor. La réponse contient pagination.nextCursor, opaque, ou null sur la dernière page. Le tri est stable : les ajouts pendant le parcours n’entraînent ni doublon ni saut. Un curseur modifié répond invalid_cursor.
Erreurs
Les erreurs suivent la RFC 9457 (application/problem+json) :
{
"type": "https://<documentation>/errors/insufficient_scope",
"title": "Forbidden",
"status": 403,
"detail": "This operation requires the scope users:write.",
"code": "insufficient_scope",
"instance": "c8b1f0d2-…"
}
Basez votre logique sur status et code, jamais sur detail. Communiquez instance (identifiant de requête) au support. Les erreurs de validation listent les champs dans errors[]. La liste des codes figure dans Erreurs.
Idempotence
Les créations exigent l’en-tête Idempotency-Key (8 à 128 caractères parmi lettres, chiffres et _ . : -). La clé est conservée 24 heures par client :
- même clé, même requête : la réponse d’origine est renvoyée avec
Idempotent-Replayed: true; - même clé, requête différente :
422idempotency_key_reused; - requête encore en cours :
409idempotency_in_progress.
Une requête en échec libère sa clé : corrigez-la et réessayez avec la même clé.
Limites de débit
Chaque client dispose par défaut de 600 requêtes par minute. Les en-têtes RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset indiquent l’état courant. Au-delà, l’API répond 429 avec Retry-After en secondes.
Une indisponibilité temporaire de la plateforme répond 503 temporarily_unavailable avec Retry-After : votre jeton reste valable, réessayez. Le serveur OAuth répond de même temporarily_unavailable sans révoquer votre autorisation.
Versionnement
La version majeure figure dans l’URL. Une version ne reçoit que des ajouts compatibles. Un changement incompatible crée /api/v2, servie en parallèle au moins douze mois. Une opération dépréciée renvoie les en-têtes Deprecation, Sunset et un lien vers le guide de migration.