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

OperationCall
Update conversationPATCH /conversations/{cid}Free
Delete conversationDELETE /conversations/{cid}Free
List conversationsGET /conversationsFree
Create conversationPOST /conversationsFree
Get conversationGET /conversations/{cid}Free
List messagesGET /conversations/{cid}/messagesFree
Send messagePOST /conversations/{cid}/messagesBilled
List conversation documentsGET /conversations/{cid}/documentsFree
List site conversationsGET /sites/{siteId}/conversationsFree
Create site conversationPOST /sites/{siteId}/conversationsFree
Get site conversationGET /sites/{siteId}/conversations/{cid}Free
List site messagesGET /sites/{siteId}/conversations/{cid}/messagesFree
Send site messagePOST /sites/{siteId}/conversations/{cid}/messagesBilled

Update conversation

PATCH/conversations/{cid}Free

Rename 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

ArgumentTypeDescription
cidin the pathstringIts id.
titleoptionalstringRename the conversation.1–500 characters
starredoptionalbooleantrue stars it (starred_at = now), false unstars it.
Request
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

DELETE/conversations/{cid}Free

Delete 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

ArgumentTypeDescription
cidin the pathstringIts id.
Request
curl -X DELETE https://app.semchat.io/api/v1/conversations/{cid} \
  -H "Authorization: Bearer sk_live_…"

Answers 200 with { "data": … }.

List conversations

GET/conversationsFree

The workspace conversations (not tied to a site).

MCP tool list_conversations

Request
curl https://app.semchat.io/api/v1/conversations \
  -H "Authorization: Bearer sk_live_…"
Response · 200
{
  "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

POST/conversationsFree

Start a workspace conversation.

MCP tool create_conversation

ArgumentTypeDescription
titleoptionalstringIts title (optional).up to 500 characters
Request
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

GET/conversations/{cid}Free

One conversation of the workspace (a site’s ones included).

MCP tool get_conversation

ArgumentTypeDescription
cidin the pathstringIts id.
Request
curl https://app.semchat.io/api/v1/conversations/{cid} \
  -H "Authorization: Bearer sk_live_…"
Response · 200
{
  "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

GET/conversations/{cid}/messagesFree

A workspace conversation’s messages, oldest first (text, tool calls and results, charts, documents).

MCP tool list_messages

ArgumentTypeDescription
cidin the pathstringIts id.
Request
curl https://app.semchat.io/api/v1/conversations/{cid}/messages \
  -H "Authorization: Bearer sk_live_…"
Response · 200
{
  "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

POST/conversations/{cid}/messagesBilled

Send 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

ArgumentTypeDescription
cidin the pathstringIts id.
messagerequiredstringThe user’s message.at least 1 character
attachmentsoptionalarrayFiles attached to the message, as in the app (the same types, 20 MB each at most).
streamoptionalbooleanAccepted for compatibility; the API answer always streams.
Request
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

GET/conversations/{cid}/documentsFree

The documents written in a workspace conversation.

MCP tool list_conversation_documents

ArgumentTypeDescription
cidin the pathstringIts id.
Request
curl https://app.semchat.io/api/v1/conversations/{cid}/documents \
  -H "Authorization: Bearer sk_live_…"

Answers 200 with { "data": … }.

List site conversations

GET/sites/{siteId}/conversationsFree

A site’s conversations.

MCP tool list_site_conversations

ArgumentTypeDescription
siteIdin the pathstringIts id.
Request
curl https://app.semchat.io/api/v1/sites/{siteId}/conversations \
  -H "Authorization: Bearer sk_live_…"

Answers 200 with { "data": … }.

Create site conversation

POST/sites/{siteId}/conversationsFree

Start a conversation on a site: the assistant knows that site.

MCP tool create_site_conversation

ArgumentTypeDescription
siteIdin the pathstringIts id.
titleoptionalstringIts title (optional).up to 500 characters
Request
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

GET/sites/{siteId}/conversations/{cid}Free

One of a site’s conversations.

MCP tool get_site_conversation

ArgumentTypeDescription
siteIdin the pathstringIts id.
cidin the pathstringIts id.
Request
curl https://app.semchat.io/api/v1/sites/{siteId}/conversations/{cid} \
  -H "Authorization: Bearer sk_live_…"

Answers 200 with { "data": … }.

List site messages

GET/sites/{siteId}/conversations/{cid}/messagesFree

A site conversation’s messages, oldest first.

MCP tool list_site_messages

ArgumentTypeDescription
siteIdin the pathstringIts id.
cidin the pathstringIts id.
Request
curl https://app.semchat.io/api/v1/sites/{siteId}/conversations/{cid}/messages \
  -H "Authorization: Bearer sk_live_…"

Answers 200 with { "data": … }.

Send site message

POST/sites/{siteId}/conversations/{cid}/messagesBilled

Send 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

ArgumentTypeDescription
siteIdin the pathstringIts id.
cidin the pathstringIts id.
messagerequiredstringThe user’s message.at least 1 character
attachmentsoptionalarrayFiles attached to the message, as in the app (the same types, 20 MB each at most).
streamoptionalbooleanAccepted for compatibility; the API answer always streams.
Request
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.

Ready to get your site off the ground?

Ask your first question - semchat replies with a clear action plan in seconds.

Free · no sign-up · takes 5 seconds