Conventions

Formats

• Requêtes et réponses en JSON, champs en snake_case.
• Identifiants ULID (26 caractères).
• Dates ISO 8601 en UTC.
• Téléversements de fichiers en multipart/form-data.

Enveloppe des réponses

Une réponse rend la ressource, ou la liste, dans data. Les listes paginées ajoutent meta avec les curseurs.

{
    "data": [
        {
            "id": "01JABCDEFGHJKMNPQRSTVWXYZ0",
            "name": "…",
            "created_at": "2026-10-11T09:00:00Z"
        }
    ],
    "meta": {
        "next_cursor": "eyJpZCI6IjAxSkFCQyJ9",
        "prev_cursor": null,
        "limit": 50
    }
}

Pagination par curseur

Les longues listes se lisent page par page : passez ?limit= (50 par défaut, 200 au plus) puis, pour la page suivante, ?cursor= avec la valeur de meta.next_cursor.

curl "https://{votre-espace}.tellmehow.io/api/v1/engagements?limit=50&cursor=eyJpZCI6IjAxSkFCQyJ9" \
  -H "Authorization: Bearer pat_…"

meta.next_cursor vaut null sur la dernière page. Le curseur est opaque : ne le construisez pas vous-même.

Limites de débit

120 requêtes par minute et par jeton (ou par application OAuth et par membre), en plus des limites propres à certaines opérations. Au-delà, l’API répond 429 avec l’en-tête Retry-After.

HTTP/1.1 429 Too Many Requests
Retry-After: 21
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0

{
    "code": "rate.limited",
    "message": "Trop de requêtes. Réessayez plus tard.",
    "details": {}
}

Attendez le délai indiqué avant de réessayer, et étalez les traitements en lot. Chaque refus est compté dans la consommation de l’espace.

Langue des messages

Les messages d’erreur suivent l’en-tête Accept-Language (fr, en). Les codes, eux, ne changent jamais de langue.