# create_chat

Source: https://modulify.ai/docs/api/chat/create-chat

Starts a new chat on a site and returns its chatId, or opens the chat every site comes with again when it is closed.

- Title: Start a new chat on a site
- Scope: `chat:write`
- Access: Makes changes
- Endpoint: `POST /v1/create_chat`

When the chat whose `chatKey` is `main`, the one every site comes with, is closed, this opens it again instead of starting another chat. It comes back empty, called `New chat` unless you pass a `title`, keeps the mode it had, so `mode` is ignored, and the answer carries `chatId` `main`. See [Close a chat](https://modulify.ai/docs/build/multiple-chats#close-a-chat).

Otherwise it starts a new chat, on every plan. A site can have up to 10 open chats, and up to 4 of them run at once, each in its own copy of the site, and their changes are merged into the site when each turn ends. See [Multiple chats](https://modulify.ai/docs/build/multiple-chats).

A new chat is called `New chat` until a message names it, unless you pass a `title`, and it starts in build mode unless you pass `mode`. Creating it spends nothing: send the first message with `send_message` and the `chatId` you get back. The response also carries the chat's summary in `chat`, in the same shape as an entry of `list_chats`.

## Request

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

It makes changes, so send an [Idempotency-Key](https://modulify.ai/docs/api/idempotency) header whenever you might retry it. A retry with the same key gets the first answer back instead of running again.

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

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

## When it is refused

| Status | When | The message |
| --- | --- | --- |
| `409` | Multiple chats are still being switched on, for example straight after an update | `Multiple chats are not switched on yet. Try again in a little while!` |
| `403` | The site already has the most open chats it allows, 10 | `This site already has the most chats your plan allows!` |
| `409` | The site's first build is still running | `Wait for the first build to finish before starting another chat!` |
| `409` | The site has not been built yet, for example because its first build was stopped or failed | `Send a message to build the site before starting another chat!` |
| `403` | The site is locked for going over the plan's site limit | `This site is locked because it goes over the plan's site limit, so "create_chat" changed nothing. Upgrade the plan or add an extra site to unlock it, or archive, move or delete a site to free a slot!` |
| `400` | `title` is longer than 80 characters | "A chat title must be 1 to 80 characters!" |
| `409` | Another chat is being created on the same site at that moment | `Another chat is being created on this site. Try again in a moment!` |
| `409` | The site's `main` chat is closed and somebody is still closing it at that moment | `Wait for this chat to finish first!` |

The last two are safe to try again in a moment. When the call opens the site's closed `main` chat again, only a locked site, a `title` that is too long and that last `409` can refuse it. When two calls open it at the same moment, both get `chatId` `main`.

## Inputs

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | Yes | The site id, from `list_sites` or `get_site`. |
| `title` | string | No | The title of the chat, at most 80 characters. Leave it out to have the chat named from its messages. |
| `mode` | string | No | `build`, where the agent makes the change, or `plan`, where it proposes a plan for you to approve first. Defaults to `build`, and is ignored when the call opens `main` again. |

## 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.