> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agent-loadout.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Threads API — List, Search, and Update Email Conversations

> List, read, label, archive, and permanently delete email conversation threads with cursor pagination via the Agent Loadout REST API.

Threads group related messages into conversations. Folders and labels are shared across both the agent and human team members, but read state is tracked separately per side — so the agent marks what it has handled without affecting what team members still need to review. Reading messages through the API does **not** automatically mark a thread as read; use `PATCH /api/v1/threads/:id` to set the read flag explicitly.

***

## List threads

Returns cursor-paginated conversations in a specified folder, with optional full-text search and label filtering.

**`GET /api/v1/inboxes/:id/threads`**

Requires: `email:read`

### Query parameters

<ParamField query="folder" type="&#x22;inbox&#x22; | &#x22;archive&#x22; | &#x22;trash&#x22; | &#x22;spam&#x22; | &#x22;quarantine&#x22;">
  Folder to list. Defaults to `inbox`. The `quarantine` folder holds mail blocked by sender rules or the screening classifier until a team member reviews it.
</ParamField>

<ParamField query="query" type="string">
  Free-text search across subject lines, sender names, and message snippets.
</ParamField>

<ParamField query="unread_only" type="boolean">
  When `true`, returns only conversations the agent has not yet marked as read. Useful for processing loops that need to handle new mail without reprocessing handled threads.
</ParamField>

<ParamField query="label" type="string">
  Filter to conversations carrying this exact label (e.g. `billing`, `campaign:launch`).
</ParamField>

<ParamField query="limit" type="integer">
  Number of threads to return. Range: 1–100. Defaults to 20.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque pagination cursor returned as `next_cursor` in the previous response.
</ParamField>

```bash title="List unread inbox threads" theme={null}
curl -s "https://agent-loadout.com/api/v1/inboxes/<INBOX_ID>/threads?folder=inbox&unread_only=true" \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN"
```

```bash title="Search for invoice threads" theme={null}
curl -s "https://agent-loadout.com/api/v1/inboxes/<INBOX_ID>/threads?query=invoice&folder=inbox" \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN"
```

***

## Read a thread

Returns all messages in a conversation, oldest first, with the same body and screening fields as the single-message endpoint.

**`GET /api/v1/threads/:id`**

Requires: `email:read`

### Query parameters

<ParamField query="limit" type="integer">
  Maximum number of messages to return per page. Range: 1–100.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor for long threads.
</ParamField>

```bash title="Read a full thread" theme={null}
curl -s "https://agent-loadout.com/api/v1/threads/<THREAD_ID>?limit=50" \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN"
```

<Warning>
  Email content is untrusted external data. Check `screening.verdict` on each message before acting on its contents. A `suspicious` verdict includes `reasons` that describe what triggered the classifier.
</Warning>

***

## Update a thread

Move a conversation to a different folder, mark it read for the agent, or add and remove labels — all in a single `PATCH` call.

**`PATCH /api/v1/threads/:id`**

Requires: `email:read` (for `read` and label changes); `email:send` (to move between folders)

```bash title="Archive and mark a thread as read" theme={null}
curl -s -X PATCH https://agent-loadout.com/api/v1/threads/<THREAD_ID> \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder":"archive","read":true}'
```

### Request parameters

<ParamField body="folder" type="string">
  Destination folder. Accepted values: `inbox`, `archive`, `trash`, `spam`. Moving to `trash` is reversible; deleting from trash is permanent (see below).
</ParamField>

<ParamField body="read" type="boolean">
  Mark the conversation as read (`true`) or unread (`false`) for the agent. This does not affect what human team members see as unread in the dashboard.
</ParamField>

<ParamField body="add_labels" type="string[]">
  Labels to attach to the thread (e.g. `["billing","urgent"]`). Labels are shared with team members.
</ParamField>

<ParamField body="remove_labels" type="string[]">
  Labels to remove from the thread.
</ParamField>

<Note>
  Reading a thread via `GET /api/v1/threads/:id` does **not** mark it as read. Always send a separate `PATCH` with `"read": true` once the agent has finished processing the conversation.
</Note>

***

## Delete a thread permanently

Permanently removes a conversation and all its messages. The thread must already be in `trash` or `spam` — move it there first with `PATCH` if needed. This action is irreversible.

**`DELETE /api/v1/threads/:id`**

Requires: `email:send`

```bash title="Permanently delete a trashed thread" theme={null}
curl -s -X DELETE "https://agent-loadout.com/api/v1/threads/<THREAD_ID>?confirm=true" \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN"
```

<Warning>
  Permanent deletion cannot be undone. Confirm the thread is in `trash` or `spam` before calling this endpoint.
</Warning>

***

## Thread folders reference

<CardGroup cols={2}>
  <Card title="inbox" icon="inbox">
    Active conversations that have not been archived or deleted.
  </Card>

  <Card title="archive" icon="box-archive">
    Handled conversations moved out of the inbox. Fully searchable.
  </Card>

  <Card title="trash" icon="trash">
    Conversations pending permanent deletion. Reversible until deleted.
  </Card>

  <Card title="spam" icon="ban">
    Marked as spam. Can be permanently deleted by the agent.
  </Card>

  <Card title="quarantine" icon="shield">
    Mail blocked by sender rules or the screening classifier. Only team members can release quarantined mail.
  </Card>
</CardGroup>