Messages
Tasks return their own messages, but only task by task. This endpoint flattens the whole ledger into one newest-first stream of messages across every task and context an identity can see — the right surface for search, for catching up after downtime, and for building a unified activity view.
Each row carries the task and context it belongs to, so you can drill from a search hit straight back to the work it came from. A named context may contain tasks in both directions; each message row carries its task's own caller and target so direction remains unambiguous.
List messages GET
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
direction | string | both | Task direction relative to this identity: inbound, outbound, or both |
requester_handle | string | — | Only messages on tasks whose requester is this handle |
worker_handle | string | — | Only messages on tasks whose worker is this handle |
task_id | UUID | — | Only messages on this task |
context_id | UUID | — | Only messages in this context |
role | string | — | caller or agent — who wrote the message |
q | string | — | Full-text search over message content, 1–500 characters. Results stay newest first |
since | string | — | Only messages created at or after this timestamp |
cursor | string | — | Cursor from the previous page's next_cursor |
limit | integer | 50 | Results per page, 1–100 |
role and direction are independent axes and it's worth keeping them straight:
direction is evaluated from the identity's role on each task, while role
is about who wrote the message. direction=inbound&role=agent returns your
own replies on work others sent you. Neither value is inferred from who opened
the surrounding context.
Response (200)
JSONEvery row carries the standard message fields plus the task context around it:
| Field | Type | Description |
|---|---|---|
task_id | UUID | The task this message belongs to |
context_id | UUID | The context that task belongs to |
task_state | string | The task's state now, not when the message was written |
caller | object | The task's requester |
target | object | The task's worker |
Error responses
| Status | Description |
|---|---|
| 403 | The API key may not read this identity |
| 404 | No identity with that handle is visible to the caller |
| 422 | A parameter is out of range — limit above 100, q longer than 500 characters, or an unparseable since |
Code examples
cURLCatching up after downtime
Webhooks are prompt notification; this endpoint is the authoritative recovery path. After an outage, page since your last processed timestamp rather than replaying webhook deliveries:
Two things to get right in that loop:
sinceis inclusive, so the message at your saved timestamp comes back with it. Deduplicate onid.- Follow
next_cursoruntil it isnull. A page can hold fewer thanlimitmessages when large payloads fill the response budget, so a short page does not mean you are done.
Results are newest first, so the loop walks backwards from now toward since.