# Statuses

Each workspace has one ordered list of thread statuses. It starts as `Active`, `Waiting` and `Done`. The workspace’s owner sets the list. The order is all a status means: the first is what a new thread starts with.

## Read the list

Each status has an `id`, the key a thread holds in `status`; a `name`, its word; and an `icon`. `active`, `waiting` and `done` keep those keys when they are renamed, and an unrenamed one is named in English. This takes **Edit and organize**, the level that may set a status.

### List the workspace's statuses

`GET /api/integrations/v1/statuses`

The MCP tool list_statuses: what a Thread may be set to, in order; the first is the default. The list changes in the app, not here; thread.statuses_changed says when. Edit and organize.

**Requirements**

| Requirement | Value |
|---|---|
| Levels | Edit and organize |
| Plan | Pro with Sync. On Free, add to the Inbox instead (`POST /inbox/notes`). |
| MCP | `list_statuses` |

Answer `200`.

**Answer fields**

| Field | Type | Description |
|---|---|---|
| `items` | array of object, required | In the workspace's order; the first is the default. |

```bash
curl -m 30 "https://thread.page/api/integrations/v1/statuses" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN"
```

Errors: `organize_not_allowed` 403.

Also [the errors of every call](https://thread.page/help/connections/errors.md#errors-every-call-can-get), and `pro_required` or `cloud_required` without Pro and Sync.

## Set a thread’s status

`PATCH /threads/{thread_id}` with `{"status": "<id>"}`. See [Threads and folders](https://thread.page/help/connections/api/threads.md).

- A key that has been deleted lands on its replacement, and the receipt says the final value.
- Anything else is `invalid_request` with `details.statuses`, the list you may use, so you can correct yourself in one step.

## When the list changes

A connection can read the list and set a status from it, and can’t change it. The list changes in the app, in **Settings → Statuses**, and `thread.statuses_changed` says when. It has no words and no thread IDs.

Deleting a status moves its threads, and you hear this one event, not one `thread.updated` per thread. `replaced: {"from": "<id>", "to": "<id>"}` says where they went: rewrite `from` to `to` in anything you keep, then read `GET /statuses` for the names.

## Related

- [Threads and folders](https://thread.page/help/connections/api/threads.md)
- [Events and subscriptions](https://thread.page/help/connections/events.md)