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

# Managing threads

> List, find, update and delete conversations

A thread is a conversation between one of your account links and one profile. Threads are never created directly: one appears when the first message is sent or received.

## List threads

```bash theme={null}
curl "https://inboxapp.com/api/v2/threads?folder=inbox&limit=20&expand=profile" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"
```

```json theme={null}
{
  "data": [
    {
      "id": "l44e15irdq4db30i77cgphhx",
      "platform": "twitter",
      "platformId": "1566123362161725440:1876543210987654321",
      "accountLinkId": "df6jbw4h36qm5d9iu2sgn7kx",
      "profileId": "n7kxqm5d9iu2sgdf6jbw4h36",
      "contactId": "nq2r8v5ycx1t7m4hj6kd3wzb",
      "assigneeId": "r3km7xj9wq5p2bvnhfdteoly",
      "isRequest": false,
      "acceptanceState": "notRequired",
      "archived": false,
      "unread": true,
      "restrictions": [],
      "syncing": false,
      "typingIndicators": "teamDefault",
      "lastMessage": {
        "id": "p8rvk2m5j0xn4wq7ybftcael",
        "direction": "inbound",
        "createdAt": "2026-09-14T10:32:00.000Z"
      },
      "activity": {
        "preview": "Sounds good, send it over.",
        "direction": "inbound",
        "at": "2026-09-14T10:32:00.000Z"
      },
      "createdAt": "2026-09-01T09:00:00.000Z",
      "profile": { "id": "n7kxqm5d9iu2sgdf6jbw4h36", "username": "sarahchen" }
    }
  ],
  "nextCursor": "eyJhdCI6IjIwMjYtMDktMTRUMTA6MzI6MDAuMDAwWiJ9"
}
```

### Folders

| `folder` | Threads |
| - | - |
| `inbox` | Not archived, and not a request. The default |
| `noReply` | In `inbox`, with the latest activity from the other side |
| `requests` | Incoming requests the account hasn't accepted or answered |
| `archived` | Archived, including archived requests |
| `all` | Every folder |

### Filters

Every filter narrows the folder. Repeat a key to match any of several values.

| Parameter | Matches threads |
| - | - |
| `accountLinkId` | Of these account links |
| `platform` | On these platforms |
| `contactId` | With these contacts |
| `tag` | Whose contact has one of these tags, by ID or name |
| `status` | Whose contact has one of these statuses, by ID or name |
| `assigneeId` | Assigned to these members, directly or through the contact |
| `unassigned` | `true` for threads with no assignee |
| `campaignId` | These campaigns sent a message in |
| `q` | Matching display names, usernames and the activity preview |

```bash theme={null}
curl "https://inboxapp.com/api/v2/threads?folder=noReply&tag=hot-lead&tag=demo-requested&assigneeId=r3km7xj9wq5p2bvnhfdteoly" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"
```

## Find a thread with someone

Filter by account link and contact:

```bash theme={null}
curl "https://inboxapp.com/api/v2/threads?accountLinkId=df6jbw4h36qm5d9iu2sgn7kx&contactId=nq2r8v5ycx1t7m4hj6kd3wzb&folder=all" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"
```

An empty `data` array means there is no conversation yet. You don't need one to send: see [Working with messages](/v2/guides/messages#targets).

## Update a thread

`PATCH` only the fields you want to change.

```typescript update.ts theme={null}
async function archive(threadId: string) {
  const response = await fetch(
    `https://inboxapp.com/api/v2/threads/${threadId}`,
    {
      method: "PATCH",
      headers: {
        Authorization: `Bearer ${process.env.INBOX_API_TOKEN}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ archived: true }),
    },
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`${error.code}: ${error.message} (${error.requestId})`);
  }

  return response.json();
}
```

| Field | Effect |
| - | - |
| `archived` | Moves the thread in or out of the archive |
| `unread` | Marks it read or unread |
| `assigneeId` | Sets this thread's assignee. `null` falls back to the contact's |
| `typingIndicators` | `enabled`, `disabled` or `teamDefault` |

`archived` and `unread` also change on the platform when the account link has `thread:archive:mutate` or `thread:read:mutate`. Otherwise they change in Inboxapp only.

### Assignment

A thread's `assigneeId` is its own assignee, or else its contact's default. To assign every conversation with a person, set `assigneeId` on the [contact](/v2/guides/contacts#update-a-contact) instead.

## Requests

`isRequest` is true while a conversation is an incoming request the account hasn't replied to or accepted. Requests live in the `requests` folder. Replying moves the thread to `inbox`.

## Send a typing indicator

```bash theme={null}
curl -X POST "https://inboxapp.com/api/v2/threads/l44e15irdq4db30i77cgphhx/typing" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"
```

```json theme={null}
{ "status": "sent", "reason": null }
```

At most one per thread every 2.5 seconds: extra calls return `skipped` with `reason: "rateLimited"`. Needs `thread:typing:send`.

## Delete a thread

```bash theme={null}
curl -X DELETE "https://inboxapp.com/api/v2/threads/l44e15irdq4db30i77cgphhx" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"
```

```json theme={null}
{ "scope": "remoteAndLocal" }
```

`remoteAndLocal` means the conversation was also deleted on the platform. `local` means only Inboxapp's copy was, because the platform doesn't allow it.

<Warning>Deleting a thread can't be undone.</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.