DocumentationAPI reference
Conversations
Conversations in the workspace or in a site, their messages, and sending one.
Every operation below is also an MCP tool, under the same name. Free operations cost nothing; Billed ones use the workspace’s credits, as in the app (What it costs).
| Operation | Call | |
|---|---|---|
| Update conversation | PATCH /conversations/{cid} | Free |
| Delete conversation | DELETE /conversations/{cid} | Free |
| List conversations | GET /conversations | Free |
| Create conversation | POST /conversations | Free |
| Get conversation | GET /conversations/{cid} | Free |
| List messages | GET /conversations/{cid}/messages | Free |
| Send message | POST /conversations/{cid}/messages | Billed |
| List conversation documents | GET /conversations/{cid}/documents | Free |
| List site conversations | GET /sites/{siteId}/conversations | Free |
| Create site conversation | POST /sites/{siteId}/conversations | Free |
| Get site conversation | GET /sites/{siteId}/conversations/{cid} | Free |
| List site messages | GET /sites/{siteId}/conversations/{cid}/messages | Free |
| Send site message | POST /sites/{siteId}/conversations/{cid}/messages | Billed |
Update conversation
/conversations/{cid}FreeRename a conversation, or star / unstar it.
- Acts on any conversation of the workspace, a site’s ones included (its cid is enough), as the app does.
- Only the fields given are changed. Answers the conversation.
MCP tool update_conversation
| Argument | Type | Description |
|---|---|---|
cidin the path | string | Its id. |
titleoptional | string | Rename the conversation.1–500 characters |
starredoptional | boolean | true stars it (starred_at = now), false unstars it. |
curl -X PATCH https://app.semchat.io/api/v1/conversations/{cid} \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"title": "…"}'Answers 200 with { "data": … }.
Delete conversation
/conversations/{cid}FreeDelete a conversation.
- Acts on any conversation of the workspace, a site’s ones included (its cid is enough), as the app does.
- Soft delete, as in the app: it leaves the lists and answers 404; its messages and the data saved from it are kept.
MCP tool delete_conversation
| Argument | Type | Description |
|---|---|---|
cidin the path | string | Its id. |
curl -X DELETE https://app.semchat.io/api/v1/conversations/{cid} \
-H "Authorization: Bearer sk_live_…"Answers 200 with { "data": … }.
List conversations
/conversationsFreeThe workspace conversations (not tied to a site).
MCP tool list_conversations
curl https://app.semchat.io/api/v1/conversations \
-H "Authorization: Bearer sk_live_…"{
"data": [
{
"id": "01a163c9-4920-773f-89fb-75ff608e07fe",
"title": "Audit complet d'alpha",
"site_id": null,
"message_count": 2,
"starred_at": "2026-10-22T13:31:58.000Z",
"last_message_at": "2026-10-22T13:26:58.000Z",
"created_at": "2026-10-22T13:24:58.000Z",
"updated_at": "2026-10-22T13:26:58.000Z"
},
{
"id": "01a15ea2-ed20-7a5d-a415-afcd68358a91",
"title": "Idées de contenu",
"site_id": null,
"message_count": 2,
"starred_at": "2026-10-21T13:31:58.000Z",
"last_message_at": "2026-10-21T13:26:58.000Z",
"created_at": "2026-10-21T13:24:58.000Z",
"updated_at": "2026-10-21T13:26:58.000Z"
}
]
}Create conversation
/conversationsFreeStart a workspace conversation.
MCP tool create_conversation
| Argument | Type | Description |
|---|---|---|
titleoptional | string | Its title (optional).up to 500 characters |
curl -X POST https://app.semchat.io/api/v1/conversations \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"title": "…"}'Answers 201 with { "data": … }.
Get conversation
/conversations/{cid}FreeOne conversation of the workspace (a site’s ones included).
MCP tool get_conversation
| Argument | Type | Description |
|---|---|---|
cidin the path | string | Its id. |
curl https://app.semchat.io/api/v1/conversations/{cid} \
-H "Authorization: Bearer sk_live_…"{
"data": {
"id": "01a163c9-4920-773f-89fb-75ff608e07fe",
"title": "Audit complet d'alpha",
"site_id": null,
"message_count": 2,
"starred_at": "2026-10-22T13:31:58.000Z",
"last_message_at": "2026-10-22T13:26:58.000Z",
"created_at": "2026-10-22T13:24:58.000Z",
"updated_at": "2026-10-22T13:26:58.000Z"
}
}List messages
/conversations/{cid}/messagesFreeA workspace conversation’s messages, oldest first (text, tool calls and results, charts, documents).
MCP tool list_messages
| Argument | Type | Description |
|---|---|---|
cidin the path | string | Its id. |
curl https://app.semchat.io/api/v1/conversations/{cid}/messages \
-H "Authorization: Bearer sk_live_…"{
"data": [
{
"id": "01a15456-3520-7803-9dfd-670569df332f",
"role": "user",
"content": "C'est quoi le SEO ?",
"parts": [
"…"
],
"created_at": "2026-10-19T13:24:58.272Z"
},
{
"id": "01a15456-aa50-78f0-8c72-120a580ca098",
"role": "assistant",
"content": "Le référencement naturel.",
"parts": [
"…",
"…"
],
"created_at": "2026-10-19T13:25:28.272Z"
}
]
}Send message
/conversations/{cid}/messagesBilledSend a message: the assistant answers, using its tools (keyword data, crawl, competitors…) as in the app.
- Attachments are stored like the app’s (any member of the workspace; an unsupported type or a file over 20 MB is INVALID_INPUT) and reach the assistant with the message. A request is 25 MB at most: about 18 MB of files once base64-encoded.
- The API streams the answer as Server-Sent Events (Vercel AI SDK “UI message stream”); once finished, read it in full with the messages list. Over MCP, the tool waits for the end and returns the answer.
- Billed in credits exactly like a chat turn in the app.
MCP tool send_message
| Argument | Type | Description |
|---|---|---|
cidin the path | string | Its id. |
messagerequired | string | The user’s message.at least 1 character |
attachmentsoptional | array | Files attached to the message, as in the app (the same types, 20 MB each at most). |
streamoptional | boolean | Accepted for compatibility; the API answer always streams. |
curl -X POST https://app.semchat.io/api/v1/conversations/{cid}/messages \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"message": "…"}'The answer streams as Server-Sent Events; once finished, read it in full with the messages list. Over MCP the tool waits for the end and returns the answer.
List conversation documents
/conversations/{cid}/documentsFreeThe documents written in a workspace conversation.
MCP tool list_conversation_documents
| Argument | Type | Description |
|---|---|---|
cidin the path | string | Its id. |
curl https://app.semchat.io/api/v1/conversations/{cid}/documents \
-H "Authorization: Bearer sk_live_…"Answers 200 with { "data": … }.
List site conversations
/sites/{siteId}/conversationsFreeA site’s conversations.
MCP tool list_site_conversations
| Argument | Type | Description |
|---|---|---|
siteIdin the path | string | Its id. |
curl https://app.semchat.io/api/v1/sites/{siteId}/conversations \
-H "Authorization: Bearer sk_live_…"Answers 200 with { "data": … }.
Create site conversation
/sites/{siteId}/conversationsFreeStart a conversation on a site: the assistant knows that site.
MCP tool create_site_conversation
| Argument | Type | Description |
|---|---|---|
siteIdin the path | string | Its id. |
titleoptional | string | Its title (optional).up to 500 characters |
curl -X POST https://app.semchat.io/api/v1/sites/{siteId}/conversations \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"title": "…"}'Answers 201 with { "data": … }.
Get site conversation
/sites/{siteId}/conversations/{cid}FreeOne of a site’s conversations.
MCP tool get_site_conversation
| Argument | Type | Description |
|---|---|---|
siteIdin the path | string | Its id. |
cidin the path | string | Its id. |
curl https://app.semchat.io/api/v1/sites/{siteId}/conversations/{cid} \
-H "Authorization: Bearer sk_live_…"Answers 200 with { "data": … }.
List site messages
/sites/{siteId}/conversations/{cid}/messagesFreeA site conversation’s messages, oldest first.
MCP tool list_site_messages
| Argument | Type | Description |
|---|---|---|
siteIdin the path | string | Its id. |
cidin the path | string | Its id. |
curl https://app.semchat.io/api/v1/sites/{siteId}/conversations/{cid}/messages \
-H "Authorization: Bearer sk_live_…"Answers 200 with { "data": … }.
Send site message
/sites/{siteId}/conversations/{cid}/messagesBilledSend a message in a site conversation: the assistant answers with that site in mind.
- Attachments are stored like the app’s (any member of the workspace; an unsupported type or a file over 20 MB is INVALID_INPUT) and reach the assistant with the message. A request is 25 MB at most: about 18 MB of files once base64-encoded.
- The API streams the answer as Server-Sent Events (Vercel AI SDK “UI message stream”); once finished, read it in full with the messages list. Over MCP, the tool waits for the end and returns the answer.
- Billed in credits exactly like a chat turn in the app.
MCP tool send_site_message
| Argument | Type | Description |
|---|---|---|
siteIdin the path | string | Its id. |
cidin the path | string | Its id. |
messagerequired | string | The user’s message.at least 1 character |
attachmentsoptional | array | Files attached to the message, as in the app (the same types, 20 MB each at most). |
streamoptional | boolean | Accepted for compatibility; the API answer always streams. |
curl -X POST https://app.semchat.io/api/v1/sites/{siteId}/conversations/{cid}/messages \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"message": "…"}'The answer streams as Server-Sent Events; once finished, read it in full with the messages list. Over MCP the tool waits for the end and returns the answer.
A question this doesn’t answer? Write to us.

