Conventions

Ce qui vaut pour toutes les routes, et qu'on ne répète pas sur chaque page.

Format des erreurs

Toutes les erreurs partagent la même enveloppe. Discriminez sur code, jamais sur message — le texte peut changer, le code non.

{
  "error": {
    "code": "invalid_request",
    "message": "Parametres invalides.",
    "details": { "title": ["String must contain at least 1 character(s)"] }
  }
}

code	Statut	Signification
unauthorized	401	Clé absente, invalide, révoquée ou expirée
forbidden	403	Clé valide mais action non autorisée
not_found	404	Ressource inexistante ou hors de votre organisation
conflict	409	Conflit d'état
invalid_request	422	Corps ou paramètres invalides ; details liste les champs fautifs
rate_limited	429	Trop de requêtes ; voir l'en-tête Retry-After
internal_error	500	Erreur inattendue côté serveur

not_found est volontairement renvoyé pour une ressource qui existe mais appartient à une autre organisation : distinguer les deux permettrait d'énumérer les identifiants existants.

Nommage

Les champs JSON sont en snake_case (client_id, due_date, created_at), les dates en ISO 8601 UTC. Les identifiants sont opaques ; là où un slug existe, les routes l'acceptent à la place de l'id.

Pagination

Les listes se paginent par curseur, jamais par offset.

GET /api/v1/projects?limit=20&cursor=cmtu15ene00037peh2fy83osx

• limit — 1 à 100 ; défaut 20 pour les projets, 50 pour les clients et les tâches.
• cursor — l'id du dernier élément reçu.
• La réponse porte next_cursor : null quand il n'y a plus rien à lire.

{ "projects": [ "…" ], "next_cursor": "cmtu15…" }

Les étapes de projet ne sont pas paginées : un projet en compte rarement plus d'une dizaine.

Idempotence

Une écriture qui échoue par timeout ne dit pas si elle a abouti. Pour pouvoir retenter sans créer de doublon, envoyez un en-tête Idempotency-Key sur les routes de création :

Idempotency-Key: 8f2b1c4e-7d0a-4c3e-9b1f-2e5d6a7b8c9d

Si la même clé revient sur le même endpoint, la réponse initiale est rejouée à l'identique — même corps, même statut — sans rien recréer. Générez-en une par opération logique (uuidgen fait l'affaire).

Limite de débit

120 requêtes par minute et par clé. Au-delà : 429 avec un en-tête Retry-After indiquant le nombre de secondes à attendre. La limite est partagée avec le serveur MCP quand il est appelé avec la même clé.