Conventions

Formats

• JSON requests and responses, snake_case fields.
• ULID identifiers (26 characters).
• ISO 8601 dates in UTC.
• File uploads as multipart/form-data.

Response envelope

A response returns the resource, or the list, in data. Paginated lists add meta with the cursors.

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

Cursor pagination

Long lists are read page by page: pass ?limit= (50 by default, 200 at most) then, for the next page, ?cursor= with the value of meta.next_cursor.

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

meta.next_cursor is null on the last page. The cursor is opaque: do not build it yourself.

Rate limits

120 requests per minute per token (or per OAuth application and member), on top of the limits of some operations. Beyond that, the API answers 429 with a Retry-After header.

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

{
    "code": "rate.limited",
    "message": "Too many requests. Please try again later.",
    "details": {}
}

Wait for the given delay before retrying, and spread batch jobs. Every refusal is counted in the workspace usage.

Message language

Error messages follow the Accept-Language header (fr, en). Codes never change language.