# list_chats

Source: https://modulify.ai/docs/api/chat/list-chats

Lists the open chats of a site with each one's key, title, mode, running generation and unmerged changes, and whether another chat can be started.

- Title: List the chats of a site
- Scope: `chat:read`
- Access: Read only
- Endpoint: `POST /v1/list_chats`

Every site comes with one chat, whose `chatKey` is `main`. It works like any other chat and can be renamed or closed. While it is closed, `chats` leaves it out, and `create_chat`, or `send_message` to `main`, opens it again. A site can have up to 10 open chats, and 4 of them can run at once. Each chat has its own conversation, queue and mode, and its agent works in its own copy of the site, so the changes of a turn are merged into the site when that turn ends. See [Multiple chats](https://modulify.ai/docs/build/multiple-chats).

Each entry in `chats` carries:

- `chatKey`, which you pass as `chatId` to the other site chat tools.
- `title` and `mode`. A chat that was not given a title, when it was created or by a rename, gets a short title of up to 10 words, written from its messages once one of them says what the chat is for, and is called `New chat` until then. Until its title arrives, the chat whose `chatKey` is `main` is named after the start of its first message.
- `runningJobId`, the generation running in it right now, or null.
- `pending`, the changes from it that could not be merged into the site automatically, or null. Merge them with `merge_chat_changes` or drop them with `discard_chat_changes`.
- `unbacked`, the changes that are only in the chat's own copy of the site because they could not be saved yet, with a `reason` and `since`, or null. They become `pending` as soon as the site can save them. When they still cannot be saved a day after `since`, `unbacked` goes back to null, and the changes stay only in the chat's copy until its next turn merges them.

`allowance` says whether another chat can be started, in `canCreate`, and when it cannot, why, in `createBlockedReason`: `plan`, `not-ready`, `limit`, `first-build` or `locked`. `mainOpen` in it says whether the chat whose `chatKey` is `main` is open. While it is closed, `canCreate` is true, because `create_chat` opens it again. `live` names the chat whose unfinished changes the preview shows on top of the merged site, or is null.

## Request

Call it with a `POST` to `https://api.modulify.ai/v1/list_chats`, sending the inputs below as a JSON object. The token needs the `chat:read` scope.

It only reads and changes nothing, so retrying it is safe.

```bash
curl -X POST https://api.modulify.ai/v1/list_chats \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID"}'
```

Over MCP, the same method is the [list_chats tool](https://modulify.ai/docs/mcp/chat/list-chats).

## Inputs

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | Yes | The site id, from `list_sites` or `get_site`. |

## Response

Every call answers with the [JSON envelope](https://modulify.ai/docs/api/requests-and-responses#the-response) of `success`, `message`, `data`, `code` and `version`. `data` holds the result described above, and on a method that returns a total, `count` carries it. The [response headers](https://modulify.ai/docs/api/requests-and-responses#headers-on-every-method-call) carry the call's `X-Request-Id` and what is left of your per-minute budget in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. [Errors](https://modulify.ai/docs/api/errors) explains every status code a call can answer with.