Start a new chat on a site

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.

POST /v1/create_chatScopechat:writeMakes changes

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.

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.

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 header whenever you might retry it. A retry with the same key gets the first answer back instead of running again.

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.

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 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 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 explains every status code a call can answer with.