List the chats of a site

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.

POST /v1/list_chatsScopechat:readRead only

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.

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.

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.

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