DocumentazioneRiferimento API
Conversazioni
Le conversazioni dello spazio di lavoro o di un sito, i loro messaggi e l'invio di un messaggio.
Ogni operazione qui sotto è anche uno strumento MCP, con lo stesso nome. Le operazioni Gratis non costano nulla; quelle A pagamento usano i crediti dello spazio di lavoro, come nell'app (Quanto costa).
| Operazione | Chiamata | |
|---|---|---|
| Modifica una conversazione | PATCH /conversations/{cid} | Gratis |
| Elimina una conversazione | DELETE /conversations/{cid} | Gratis |
| Elenca le conversazioni | GET /conversations | Gratis |
| Crea una conversazione | POST /conversations | Gratis |
| Leggi una conversazione | GET /conversations/{cid} | Gratis |
| Elenca i messaggi | GET /conversations/{cid}/messages | Gratis |
| Invia un messaggio | POST /conversations/{cid}/messages | A pagamento |
| Elenca i documenti di una conversazione | GET /conversations/{cid}/documents | Gratis |
| Elenca le conversazioni del sito | GET /sites/{siteId}/conversations | Gratis |
| Crea una conversazione nel sito | POST /sites/{siteId}/conversations | Gratis |
| Leggi una conversazione del sito | GET /sites/{siteId}/conversations/{cid} | Gratis |
| Elenca i messaggi del sito | GET /sites/{siteId}/conversations/{cid}/messages | Gratis |
| Invia un messaggio nel sito | POST /sites/{siteId}/conversations/{cid}/messages | A pagamento |
Modifica una conversazione
/conversations/{cid}GratisRinomina una conversazione, oppure aggiungila ai preferiti o toglila.
- Agisce su qualsiasi conversazione dello spazio di lavoro, comprese quelle di un sito (basta il suo cid), come fa l'app.
- Cambiano solo i campi indicati. Risponde con la conversazione.
Strumento MCP update_conversation
| Argomento | Tipo | Descrizione |
|---|---|---|
cidnel percorso | string | Il suo id. |
titlefacoltativo | string | Rinomina la conversazione.1–500 caratteri |
starredfacoltativo | boolean | true la mette tra i preferiti (starred_at = adesso), false la toglie. |
curl -X PATCH https://app.semchat.io/api/v1/conversations/{cid} \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"title": "…"}'Risponde 200 con { "data": … }.
Elimina una conversazione
/conversations/{cid}GratisElimina una conversazione.
- Agisce su qualsiasi conversazione dello spazio di lavoro, comprese quelle di un sito (basta il suo cid), come fa l'app.
- Eliminazione logica, come nell'app: esce dagli elenchi e risponde 404; i suoi messaggi e i dati salvati da lì vengono conservati.
Strumento MCP delete_conversation
| Argomento | Tipo | Descrizione |
|---|---|---|
cidnel percorso | string | Il suo id. |
curl -X DELETE https://app.semchat.io/api/v1/conversations/{cid} \
-H "Authorization: Bearer sk_live_…"Risponde 200 con { "data": … }.
Elenca le conversazioni
/conversationsGratisLe conversazioni dello spazio di lavoro (non legate a un sito).
Strumento 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"
}
]
}Crea una conversazione
/conversationsGratisAvvia una conversazione nello spazio di lavoro.
Strumento MCP create_conversation
| Argomento | Tipo | Descrizione |
|---|---|---|
titlefacoltativo | string | Il suo titolo (facoltativo).fino a 500 caratteri |
curl -X POST https://app.semchat.io/api/v1/conversations \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"title": "…"}'Risponde 201 con { "data": … }.
Leggi una conversazione
/conversations/{cid}GratisUna conversazione dello spazio di lavoro (comprese quelle di un sito).
Strumento MCP get_conversation
| Argomento | Tipo | Descrizione |
|---|---|---|
cidnel percorso | string | Il suo 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"
}
}Elenca i messaggi
/conversations/{cid}/messagesGratisI messaggi di una conversazione dello spazio di lavoro, dal più vecchio (testo, chiamate agli strumenti e risultati, grafici, documenti).
Strumento MCP list_messages
| Argomento | Tipo | Descrizione |
|---|---|---|
cidnel percorso | string | Il suo 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"
}
]
}Invia un messaggio
/conversations/{cid}/messagesA pagamentoInvia un messaggio: l'assistente risponde usando i suoi strumenti (dati sulle parole chiave, scansione, concorrenti…), come nell'app.
- Gli allegati vengono salvati come nell'app (qualsiasi membro dello spazio di lavoro; un tipo non supportato o un file oltre i 20 MB dà INVALID_INPUT) e arrivano all'assistente insieme al messaggio. Una richiesta pesa al massimo 25 MB: circa 18 MB di file una volta codificati in base64.
- L'API invia la risposta in streaming come Server-Sent Events («UI message stream» del Vercel AI SDK); quando è finita, leggila per intero con l'elenco dei messaggi. Via MCP, lo strumento aspetta la fine e restituisce la risposta.
- Addebitato in crediti esattamente come un turno di chat nell'app.
Strumento MCP send_message
| Argomento | Tipo | Descrizione |
|---|---|---|
cidnel percorso | string | Il suo id. |
messageobbligatorio | string | Il messaggio dell'utente.almeno 1 carattere |
attachmentsfacoltativo | array | I file allegati al messaggio, come nell'app (gli stessi tipi, al massimo 20 MB ciascuno). |
streamfacoltativo | boolean | Accettato per compatibilità; la risposta dell'API arriva sempre in 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": "…"}'La risposta arriva in streaming come Server-Sent Events; quando è finita, leggila per intero con l'elenco dei messaggi. Via MCP lo strumento aspetta la fine e restituisce la risposta.
Elenca i documenti di una conversazione
/conversations/{cid}/documentsGratisI documenti scritti in una conversazione dello spazio di lavoro.
Strumento MCP list_conversation_documents
| Argomento | Tipo | Descrizione |
|---|---|---|
cidnel percorso | string | Il suo id. |
curl https://app.semchat.io/api/v1/conversations/{cid}/documents \
-H "Authorization: Bearer sk_live_…"Risponde 200 con { "data": … }.
Elenca le conversazioni del sito
/sites/{siteId}/conversationsGratisLe conversazioni di un sito.
Strumento MCP list_site_conversations
| Argomento | Tipo | Descrizione |
|---|---|---|
siteIdnel percorso | string | Il suo id. |
curl https://app.semchat.io/api/v1/sites/{siteId}/conversations \
-H "Authorization: Bearer sk_live_…"Risponde 200 con { "data": … }.
Crea una conversazione nel sito
/sites/{siteId}/conversationsGratisAvvia una conversazione su un sito: l'assistente conosce quel sito.
Strumento MCP create_site_conversation
| Argomento | Tipo | Descrizione |
|---|---|---|
siteIdnel percorso | string | Il suo id. |
titlefacoltativo | string | Il suo titolo (facoltativo).fino a 500 caratteri |
curl -X POST https://app.semchat.io/api/v1/sites/{siteId}/conversations \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{"title": "…"}'Risponde 201 con { "data": … }.
Leggi una conversazione del sito
/sites/{siteId}/conversations/{cid}GratisUna delle conversazioni di un sito.
Strumento MCP get_site_conversation
| Argomento | Tipo | Descrizione |
|---|---|---|
siteIdnel percorso | string | Il suo id. |
cidnel percorso | string | Il suo id. |
curl https://app.semchat.io/api/v1/sites/{siteId}/conversations/{cid} \
-H "Authorization: Bearer sk_live_…"Risponde 200 con { "data": … }.
Elenca i messaggi del sito
/sites/{siteId}/conversations/{cid}/messagesGratisI messaggi di una conversazione di un sito, dal più vecchio.
Strumento MCP list_site_messages
| Argomento | Tipo | Descrizione |
|---|---|---|
siteIdnel percorso | string | Il suo id. |
cidnel percorso | string | Il suo id. |
curl https://app.semchat.io/api/v1/sites/{siteId}/conversations/{cid}/messages \
-H "Authorization: Bearer sk_live_…"Risponde 200 con { "data": … }.
Invia un messaggio nel sito
/sites/{siteId}/conversations/{cid}/messagesA pagamentoInvia un messaggio in una conversazione di un sito: l'assistente risponde tenendo a mente quel sito.
- Gli allegati vengono salvati come nell'app (qualsiasi membro dello spazio di lavoro; un tipo non supportato o un file oltre i 20 MB dà INVALID_INPUT) e arrivano all'assistente insieme al messaggio. Una richiesta pesa al massimo 25 MB: circa 18 MB di file una volta codificati in base64.
- L'API invia la risposta in streaming come Server-Sent Events («UI message stream» del Vercel AI SDK); quando è finita, leggila per intero con l'elenco dei messaggi. Via MCP, lo strumento aspetta la fine e restituisce la risposta.
- Addebitato in crediti esattamente come un turno di chat nell'app.
Strumento MCP send_site_message
| Argomento | Tipo | Descrizione |
|---|---|---|
siteIdnel percorso | string | Il suo id. |
cidnel percorso | string | Il suo id. |
messageobbligatorio | string | Il messaggio dell'utente.almeno 1 carattere |
attachmentsfacoltativo | array | I file allegati al messaggio, come nell'app (gli stessi tipi, al massimo 20 MB ciascuno). |
streamfacoltativo | boolean | Accettato per compatibilità; la risposta dell'API arriva sempre in 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": "…"}'La risposta arriva in streaming come Server-Sent Events; quando è finita, leggila per intero con l'elenco dei messaggi. Via MCP lo strumento aspetta la fine e restituisce la risposta.
Hai una domanda a cui qui non trovi risposta? Scrivici.

