DocumentaçãoReferência da API
Conversas
As conversas no espaço de trabalho ou em um site, as mensagens delas, e como enviar uma.
Cada operação abaixo também é uma ferramenta MCP, com o mesmo nome. As operações marcadas Grátis não custam nada; as marcadas Cobrado usam os créditos do espaço de trabalho, como no aplicativo (Quanto custa).
| Operação | Chamada | |
|---|---|---|
| Atualizar uma conversa | PATCH /conversations/{cid} | Grátis |
| Excluir uma conversa | DELETE /conversations/{cid} | Grátis |
| Listar as conversas | GET /conversations | Grátis |
| Criar uma conversa | POST /conversations | Grátis |
| Obter uma conversa | GET /conversations/{cid} | Grátis |
| Listar as mensagens | GET /conversations/{cid}/messages | Grátis |
| Enviar uma mensagem | POST /conversations/{cid}/messages | Cobrado |
| Listar os documentos de uma conversa | GET /conversations/{cid}/documents | Grátis |
| Listar as conversas de um site | GET /sites/{siteId}/conversations | Grátis |
| Criar uma conversa em um site | POST /sites/{siteId}/conversations | Grátis |
| Obter uma conversa de um site | GET /sites/{siteId}/conversations/{cid} | Grátis |
| Listar as mensagens de uma conversa de site | GET /sites/{siteId}/conversations/{cid}/messages | Grátis |
| Enviar uma mensagem em um site | POST /sites/{siteId}/conversations/{cid}/messages | Cobrado |
Atualizar uma conversa
/conversations/{cid}GrátisRenomeia uma conversa, ou marca / desmarca a conversa com estrela.
- Age sobre qualquer conversa do espaço de trabalho, inclusive as de um site (o cid dela basta), como o aplicativo.
- Só os campos enviados mudam. Responde com a conversa.
Ferramenta MCP update_conversation
| Argumento | Tipo | Descrição |
|---|---|---|
cidno caminho | string | O id dele. |
titleopcional | string | Renomeia a conversa.1–500 caracteres |
starredopcional | boolean | true marca com estrela (starred_at = agora), false desmarca. |
curl -X PATCH https://app.semchat.io/api/v1/conversations/{cid} \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"title": "…"}'Responde 200 com { "data": … }.
Excluir uma conversa
/conversations/{cid}GrátisExclui uma conversa.
- Age sobre qualquer conversa do espaço de trabalho, inclusive as de um site (o cid dela basta), como o aplicativo.
- Exclusão lógica, como no aplicativo: ela sai das listas e responde 404; as mensagens dela e os dados salvos a partir dela continuam.
Ferramenta MCP delete_conversation
| Argumento | Tipo | Descrição |
|---|---|---|
cidno caminho | string | O id dele. |
curl -X DELETE https://app.semchat.io/api/v1/conversations/{cid} \
-H "Authorization: Bearer sk_live_…"Responde 200 com { "data": … }.
Listar as conversas
/conversationsGrátisAs conversas do espaço de trabalho (não vinculadas a um site).
Ferramenta MCP 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"
}
]
}Criar uma conversa
/conversationsGrátisInicia uma conversa no espaço de trabalho.
Ferramenta MCP create_conversation
| Argumento | Tipo | Descrição |
|---|---|---|
titleopcional | string | O título dela (opcional).até 500 caracteres |
curl -X POST https://app.semchat.io/api/v1/conversations \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"title": "…"}'Responde 201 com { "data": … }.
Obter uma conversa
/conversations/{cid}GrátisUma conversa do espaço de trabalho (inclusive as de um site).
Ferramenta MCP get_conversation
| Argumento | Tipo | Descrição |
|---|---|---|
cidno caminho | string | O id dele. |
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"
}
}Listar as mensagens
/conversations/{cid}/messagesGrátisAs mensagens de uma conversa do espaço de trabalho, da mais antiga para a mais recente (texto, chamadas de ferramentas e resultados, gráficos, documentos).
Ferramenta MCP list_messages
| Argumento | Tipo | Descrição |
|---|---|---|
cidno caminho | string | O id dele. |
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"
}
]
}Enviar uma mensagem
/conversations/{cid}/messagesCobradoEnvia uma mensagem: o assistente responde usando as ferramentas dele (dados de palavras-chave, rastreamento, concorrentes…) como no aplicativo.
- Os anexos são salvos como os do aplicativo (qualquer membro do espaço de trabalho; um tipo não suportado ou um arquivo acima de 20 MB dá INVALID_INPUT) e chegam ao assistente com a mensagem. Uma requisição tem no máximo 25 MB: cerca de 18 MB de arquivos depois de codificados em base64.
- A API envia a resposta em streaming, como Server-Sent Events (o “UI message stream” do Vercel AI SDK); quando ela terminar, leia a resposta completa na lista de mensagens. Pelo MCP, a ferramenta espera o fim e devolve a resposta.
- Cobrado em créditos exatamente como uma mensagem do chat no aplicativo.
Ferramenta MCP send_message
| Argumento | Tipo | Descrição |
|---|---|---|
cidno caminho | string | O id dele. |
messageobrigatório | string | A mensagem do usuário.pelo menos 1 caractere |
attachmentsopcional | array | Arquivos anexados à mensagem, como no aplicativo (os mesmos tipos, no máximo 20 MB cada). |
streamopcional | boolean | Aceito por compatibilidade; a resposta da API sempre chega em streaming. |
curl -X POST https://app.semchat.io/api/v1/conversations/{cid}/messages \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"message": "…"}'A resposta chega em streaming, como Server-Sent Events; quando ela terminar, leia a resposta completa na lista de mensagens. Pelo MCP, a ferramenta espera o fim e devolve a resposta.
Listar os documentos de uma conversa
/conversations/{cid}/documentsGrátisOs documentos escritos em uma conversa do espaço de trabalho.
Ferramenta MCP list_conversation_documents
| Argumento | Tipo | Descrição |
|---|---|---|
cidno caminho | string | O id dele. |
curl https://app.semchat.io/api/v1/conversations/{cid}/documents \
-H "Authorization: Bearer sk_live_…"Responde 200 com { "data": … }.
Listar as conversas de um site
/sites/{siteId}/conversationsGrátisAs conversas de um site.
Ferramenta MCP list_site_conversations
| Argumento | Tipo | Descrição |
|---|---|---|
siteIdno caminho | string | O id dele. |
curl https://app.semchat.io/api/v1/sites/{siteId}/conversations \
-H "Authorization: Bearer sk_live_…"Responde 200 com { "data": … }.
Criar uma conversa em um site
/sites/{siteId}/conversationsGrátisInicia uma conversa em um site: o assistente conhece esse site.
Ferramenta MCP create_site_conversation
| Argumento | Tipo | Descrição |
|---|---|---|
siteIdno caminho | string | O id dele. |
titleopcional | string | O título dela (opcional).até 500 caracteres |
curl -X POST https://app.semchat.io/api/v1/sites/{siteId}/conversations \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"title": "…"}'Responde 201 com { "data": … }.
Obter uma conversa de um site
/sites/{siteId}/conversations/{cid}GrátisUma das conversas de um site.
Ferramenta MCP get_site_conversation
| Argumento | Tipo | Descrição |
|---|---|---|
siteIdno caminho | string | O id dele. |
cidno caminho | string | O id dele. |
curl https://app.semchat.io/api/v1/sites/{siteId}/conversations/{cid} \
-H "Authorization: Bearer sk_live_…"Responde 200 com { "data": … }.
Listar as mensagens de uma conversa de site
/sites/{siteId}/conversations/{cid}/messagesGrátisAs mensagens de uma conversa de site, da mais antiga para a mais recente.
Ferramenta MCP list_site_messages
| Argumento | Tipo | Descrição |
|---|---|---|
siteIdno caminho | string | O id dele. |
cidno caminho | string | O id dele. |
curl https://app.semchat.io/api/v1/sites/{siteId}/conversations/{cid}/messages \
-H "Authorization: Bearer sk_live_…"Responde 200 com { "data": … }.
Enviar uma mensagem em um site
/sites/{siteId}/conversations/{cid}/messagesCobradoEnvia uma mensagem em uma conversa de site: o assistente responde levando esse site em conta.
- Os anexos são salvos como os do aplicativo (qualquer membro do espaço de trabalho; um tipo não suportado ou um arquivo acima de 20 MB dá INVALID_INPUT) e chegam ao assistente com a mensagem. Uma requisição tem no máximo 25 MB: cerca de 18 MB de arquivos depois de codificados em base64.
- A API envia a resposta em streaming, como Server-Sent Events (o “UI message stream” do Vercel AI SDK); quando ela terminar, leia a resposta completa na lista de mensagens. Pelo MCP, a ferramenta espera o fim e devolve a resposta.
- Cobrado em créditos exatamente como uma mensagem do chat no aplicativo.
Ferramenta MCP send_site_message
| Argumento | Tipo | Descrição |
|---|---|---|
siteIdno caminho | string | O id dele. |
cidno caminho | string | O id dele. |
messageobrigatório | string | A mensagem do usuário.pelo menos 1 caractere |
attachmentsopcional | array | Arquivos anexados à mensagem, como no aplicativo (os mesmos tipos, no máximo 20 MB cada). |
streamopcional | boolean | Aceito por compatibilidade; a resposta da API sempre chega em streaming. |
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": "…"}'A resposta chega em streaming, como Server-Sent Events; quando ela terminar, leia a resposta completa na lista de mensagens. Pelo MCP, a ferramenta espera o fim e devolve a resposta.
Não encontrou a resposta? Fale com a gente.

