List conversations
Returns one page of the workspace’s active conversations across every text channel.
Closed conversations are not listed. Fetch a closed one directly with
GET /api/conversations/{conversationId}. Each row carries the conversation columns plus
the contact’s name, phone and lead status, the agent’s name, a 160-character preview of the
last message and a lead qualification score.
Ordering and filtering. By default rows are ordered by updated_at descending (most
recent activity first). With needsHuman=waiting only threads where the agent asked for a
person and nobody has resolved it yet are returned, ordered by needs_human_at
ascending, so the person who has waited longest comes first.
Pagination. Page-number pagination with page and limit. total is the number of
matching conversations across all pages. needsHumanWaiting is the workspace-wide count of
threads waiting for a person, whatever page or filter you asked for. Invalid values are
never rejected: a non-numeric or zero page becomes 1, a non-numeric or zero limit
becomes 50, and a limit above 100 is clamped to 100.
Consistency. Pages are cached for up to 30 seconds. An operator reply sent through
POST /api/conversations/{conversationId}/messages clears the cache immediately.
needsHumanWaiting is never cached.
Access
- Required scope:
read(orwrite). - Rate limit: General API — 120 requests/min per workspace (Starter), 200 (Growth), 300 (Business), 600 (Enterprise). See Rate limits.
- Plan: Available on every plan.
Authentication
Workspace API key: jl_ followed by 64 lowercase hex characters, created by the workspace owner in the
dashboard (Settings → API Keys) and sent as Authorization: Bearer jl_.... The plaintext is shown once,
at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys.
Operations restricted to admins or owners reject keys without the full scope with 403, and say so in
their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret —
that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds.
See Authentication.
Query parameters
1-indexed page number. Non-numeric or values below 1 are treated as 1.
Conversations per page. Values above 100 are clamped to 100; non-numeric or values below 1 fall back to 50.
Pass waiting to list only threads where the agent asked for a person and it is not
resolved yet, oldest wait first. Any other value is ignored and the normal list is returned.
Pass closed to list the closed conversations instead of the inbox, newest activity first.
The inbox (no status) returns the active threads plus any closed thread still waiting for
a person. Ignored when needsHuman=waiting is also sent. Any other value is ignored.