DocumentationRéférence de l'API
Conversations
Les conversations de l'espace ou d'un site, leurs messages, et l'envoi d'un message.
Chaque opération ci-dessous est aussi un outil MCP, sous le même nom. Les opérations marquées Gratuit ne coûtent rien ; celles marquées Facturé utilisent les crédits de l'espace, comme dans l'app (Ce que ça coûte).
| Opération | Appel | |
|---|---|---|
| Modifier une conversation | PATCH /conversations/{cid} | Gratuit |
| Supprimer une conversation | DELETE /conversations/{cid} | Gratuit |
| Lister les conversations | GET /conversations | Gratuit |
| Créer une conversation | POST /conversations | Gratuit |
| Récupérer une conversation | GET /conversations/{cid} | Gratuit |
| Lister les messages | GET /conversations/{cid}/messages | Gratuit |
| Envoyer un message | POST /conversations/{cid}/messages | Facturé |
| Lister les documents d'une conversation | GET /conversations/{cid}/documents | Gratuit |
| Lister les conversations du site | GET /sites/{siteId}/conversations | Gratuit |
| Créer une conversation dans un site | POST /sites/{siteId}/conversations | Gratuit |
| Récupérer une conversation du site | GET /sites/{siteId}/conversations/{cid} | Gratuit |
| Lister les messages d'une conversation du site | GET /sites/{siteId}/conversations/{cid}/messages | Gratuit |
| Envoyer un message dans un site | POST /sites/{siteId}/conversations/{cid}/messages | Facturé |
Modifier une conversation
/conversations/{cid}GratuitRenommer une conversation, ou la mettre en favori / l'en retirer.
- Agit sur n'importe quelle conversation de l'espace, y compris celles d'un site (son cid suffit), comme le fait l'app.
- Seuls les champs fournis changent. Renvoie la conversation.
Outil MCP update_conversation
| Argument | Type | Description |
|---|---|---|
ciddans le chemin | string | Son identifiant. |
titlefacultatif | string | Renommer la conversation.1–500 caractères |
starredfacultatif | boolean | true la met en favori (starred_at = maintenant), false l'en retire. |
curl -X PATCH https://app.semchat.io/api/v1/conversations/{cid} \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"title": "…"}'Répond 200 avec { "data": … }.
Supprimer une conversation
/conversations/{cid}GratuitSupprimer une conversation.
- Agit sur n'importe quelle conversation de l'espace, y compris celles d'un site (son cid suffit), comme le fait l'app.
- Suppression douce, comme dans l'app : elle quitte les listes et répond 404 ; ses messages et les données enregistrées depuis elle sont conservés.
Outil MCP delete_conversation
| Argument | Type | Description |
|---|---|---|
ciddans le chemin | string | Son identifiant. |
curl -X DELETE https://app.semchat.io/api/v1/conversations/{cid} \
-H "Authorization: Bearer sk_live_…"Répond 200 avec { "data": … }.
Lister les conversations
/conversationsGratuitLes conversations de l'espace (non rattachées à un site).
Outil 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"
}
]
}Créer une conversation
/conversationsGratuitDémarrer une conversation dans l'espace.
Outil MCP create_conversation
| Argument | Type | Description |
|---|---|---|
titlefacultatif | string | Son titre (facultatif).jusqu'à 500 caractères |
curl -X POST https://app.semchat.io/api/v1/conversations \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"title": "…"}'Répond 201 avec { "data": … }.
Récupérer une conversation
/conversations/{cid}GratuitUne conversation de l'espace (celles des sites comprises).
Outil MCP get_conversation
| Argument | Type | Description |
|---|---|---|
ciddans le chemin | string | Son identifiant. |
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"
}
}Lister les messages
/conversations/{cid}/messagesGratuitLes messages d'une conversation de l'espace, du plus ancien au plus récent (texte, appels d'outils et leurs résultats, graphiques, documents).
Outil MCP list_messages
| Argument | Type | Description |
|---|---|---|
ciddans le chemin | string | Son identifiant. |
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"
}
]
}Envoyer un message
/conversations/{cid}/messagesFacturéEnvoyer un message : l'assistant répond en utilisant ses outils (données de mots-clés, exploration, concurrents…) comme dans l'app.
- Les pièces jointes sont enregistrées comme dans l'app (tout membre de l'espace ; un type non pris en charge ou un fichier de plus de 20 Mo donne INVALID_INPUT) et parviennent à l'assistant avec le message. Une requête fait 25 Mo au plus : environ 18 Mo de fichiers une fois encodés en base64.
- L'API envoie la réponse en flux, en Server-Sent Events (« UI message stream » du Vercel AI SDK) ; une fois terminée, lisez-la en entier avec la liste des messages. Via MCP, l'outil attend la fin et renvoie la réponse.
- Facturé en crédits exactement comme un tour de chat dans l'app.
Outil MCP send_message
| Argument | Type | Description |
|---|---|---|
ciddans le chemin | string | Son identifiant. |
messageobligatoire | string | Le message de l'utilisateur.au moins 1 caractère |
attachmentsfacultatif | array | Les fichiers joints au message, comme dans l'app (les mêmes types, 20 Mo chacun au plus). |
streamfacultatif | boolean | Accepté pour compatibilité ; la réponse de l'API arrive toujours en flux. |
curl -X POST https://app.semchat.io/api/v1/conversations/{cid}/messages \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"message": "…"}'La réponse arrive en flux (Server-Sent Events) ; une fois terminée, lisez-la en entier avec la liste des messages. Via MCP, l'outil attend la fin et renvoie la réponse.
Lister les documents d'une conversation
/conversations/{cid}/documentsGratuitLes documents écrits dans une conversation de l'espace.
Outil MCP list_conversation_documents
| Argument | Type | Description |
|---|---|---|
ciddans le chemin | string | Son identifiant. |
curl https://app.semchat.io/api/v1/conversations/{cid}/documents \
-H "Authorization: Bearer sk_live_…"Répond 200 avec { "data": … }.
Lister les conversations du site
/sites/{siteId}/conversationsGratuitLes conversations d'un site.
Outil MCP list_site_conversations
| Argument | Type | Description |
|---|---|---|
siteIddans le chemin | string | Son identifiant. |
curl https://app.semchat.io/api/v1/sites/{siteId}/conversations \
-H "Authorization: Bearer sk_live_…"Répond 200 avec { "data": … }.
Créer une conversation dans un site
/sites/{siteId}/conversationsGratuitDémarrer une conversation sur un site : l'assistant connaît ce site.
Outil MCP create_site_conversation
| Argument | Type | Description |
|---|---|---|
siteIddans le chemin | string | Son identifiant. |
titlefacultatif | string | Son titre (facultatif).jusqu'à 500 caractères |
curl -X POST https://app.semchat.io/api/v1/sites/{siteId}/conversations \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"title": "…"}'Répond 201 avec { "data": … }.
Récupérer une conversation du site
/sites/{siteId}/conversations/{cid}GratuitL'une des conversations d'un site.
Outil MCP get_site_conversation
| Argument | Type | Description |
|---|---|---|
siteIddans le chemin | string | Son identifiant. |
ciddans le chemin | string | Son identifiant. |
curl https://app.semchat.io/api/v1/sites/{siteId}/conversations/{cid} \
-H "Authorization: Bearer sk_live_…"Répond 200 avec { "data": … }.
Lister les messages d'une conversation du site
/sites/{siteId}/conversations/{cid}/messagesGratuitLes messages d'une conversation de site, du plus ancien au plus récent.
Outil MCP list_site_messages
| Argument | Type | Description |
|---|---|---|
siteIddans le chemin | string | Son identifiant. |
ciddans le chemin | string | Son identifiant. |
curl https://app.semchat.io/api/v1/sites/{siteId}/conversations/{cid}/messages \
-H "Authorization: Bearer sk_live_…"Répond 200 avec { "data": … }.
Envoyer un message dans un site
/sites/{siteId}/conversations/{cid}/messagesFacturéEnvoyer un message dans une conversation de site : l'assistant répond en gardant ce site en tête.
- Les pièces jointes sont enregistrées comme dans l'app (tout membre de l'espace ; un type non pris en charge ou un fichier de plus de 20 Mo donne INVALID_INPUT) et parviennent à l'assistant avec le message. Une requête fait 25 Mo au plus : environ 18 Mo de fichiers une fois encodés en base64.
- L'API envoie la réponse en flux, en Server-Sent Events (« UI message stream » du Vercel AI SDK) ; une fois terminée, lisez-la en entier avec la liste des messages. Via MCP, l'outil attend la fin et renvoie la réponse.
- Facturé en crédits exactement comme un tour de chat dans l'app.
Outil MCP send_site_message
| Argument | Type | Description |
|---|---|---|
siteIddans le chemin | string | Son identifiant. |
ciddans le chemin | string | Son identifiant. |
messageobligatoire | string | Le message de l'utilisateur.au moins 1 caractère |
attachmentsfacultatif | array | Les fichiers joints au message, comme dans l'app (les mêmes types, 20 Mo chacun au plus). |
streamfacultatif | boolean | Accepté pour compatibilité ; la réponse de l'API arrive toujours en flux. |
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": "…"}'La réponse arrive en flux (Server-Sent Events) ; une fois terminée, lisez-la en entier avec la liste des messages. Via MCP, l'outil attend la fin et renvoie la réponse.
Une question sans réponse ici ? Écrivez-nous.

