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

OperazioneChiamata
Modifica una conversazionePATCH /conversations/{cid}Gratis
Elimina una conversazioneDELETE /conversations/{cid}Gratis
Elenca le conversazioniGET /conversationsGratis
Crea una conversazionePOST /conversationsGratis
Leggi una conversazioneGET /conversations/{cid}Gratis
Elenca i messaggiGET /conversations/{cid}/messagesGratis
Invia un messaggioPOST /conversations/{cid}/messagesA pagamento
Elenca i documenti di una conversazioneGET /conversations/{cid}/documentsGratis
Elenca le conversazioni del sitoGET /sites/{siteId}/conversationsGratis
Crea una conversazione nel sitoPOST /sites/{siteId}/conversationsGratis
Leggi una conversazione del sitoGET /sites/{siteId}/conversations/{cid}Gratis
Elenca i messaggi del sitoGET /sites/{siteId}/conversations/{cid}/messagesGratis
Invia un messaggio nel sitoPOST /sites/{siteId}/conversations/{cid}/messagesA pagamento

Modifica una conversazione

PATCH/conversations/{cid}Gratis

Rinomina 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

ArgomentoTipoDescrizione
cidnel percorsostringIl suo id.
titlefacoltativostringRinomina la conversazione.1–500 caratteri
starredfacoltativobooleantrue la mette tra i preferiti (starred_at = adesso), false la toglie.
Richiesta
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

DELETE/conversations/{cid}Gratis

Elimina 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

ArgomentoTipoDescrizione
cidnel percorsostringIl suo id.
Richiesta
curl -X DELETE https://app.semchat.io/api/v1/conversations/{cid} \
  -H "Authorization: Bearer sk_live_…"

Risponde 200 con { "data": … }.

Elenca le conversazioni

GET/conversationsGratis

Le conversazioni dello spazio di lavoro (non legate a un sito).

Strumento MCP list_conversations

Richiesta
curl https://app.semchat.io/api/v1/conversations \
  -H "Authorization: Bearer sk_live_…"
Risposta · 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"
    }
  ]
}

Crea una conversazione

POST/conversationsGratis

Avvia una conversazione nello spazio di lavoro.

Strumento MCP create_conversation

ArgomentoTipoDescrizione
titlefacoltativostringIl suo titolo (facoltativo).fino a 500 caratteri
Richiesta
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

GET/conversations/{cid}Gratis

Una conversazione dello spazio di lavoro (comprese quelle di un sito).

Strumento MCP get_conversation

ArgomentoTipoDescrizione
cidnel percorsostringIl suo id.
Richiesta
curl https://app.semchat.io/api/v1/conversations/{cid} \
  -H "Authorization: Bearer sk_live_…"
Risposta · 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"
  }
}

Elenca i messaggi

GET/conversations/{cid}/messagesGratis

I messaggi di una conversazione dello spazio di lavoro, dal più vecchio (testo, chiamate agli strumenti e risultati, grafici, documenti).

Strumento MCP list_messages

ArgomentoTipoDescrizione
cidnel percorsostringIl suo id.
Richiesta
curl https://app.semchat.io/api/v1/conversations/{cid}/messages \
  -H "Authorization: Bearer sk_live_…"
Risposta · 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"
    }
  ]
}

Invia un messaggio

POST/conversations/{cid}/messagesA pagamento

Invia 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

ArgomentoTipoDescrizione
cidnel percorsostringIl suo id.
messageobbligatoriostringIl messaggio dell'utente.almeno 1 carattere
attachmentsfacoltativoarrayI file allegati al messaggio, come nell'app (gli stessi tipi, al massimo 20 MB ciascuno).
streamfacoltativobooleanAccettato per compatibilità; la risposta dell'API arriva sempre in streaming.
Richiesta
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

GET/conversations/{cid}/documentsGratis

I documenti scritti in una conversazione dello spazio di lavoro.

Strumento MCP list_conversation_documents

ArgomentoTipoDescrizione
cidnel percorsostringIl suo id.
Richiesta
curl https://app.semchat.io/api/v1/conversations/{cid}/documents \
  -H "Authorization: Bearer sk_live_…"

Risponde 200 con { "data": … }.

Elenca le conversazioni del sito

GET/sites/{siteId}/conversationsGratis

Le conversazioni di un sito.

Strumento MCP list_site_conversations

ArgomentoTipoDescrizione
siteIdnel percorsostringIl suo id.
Richiesta
curl https://app.semchat.io/api/v1/sites/{siteId}/conversations \
  -H "Authorization: Bearer sk_live_…"

Risponde 200 con { "data": … }.

Crea una conversazione nel sito

POST/sites/{siteId}/conversationsGratis

Avvia una conversazione su un sito: l'assistente conosce quel sito.

Strumento MCP create_site_conversation

ArgomentoTipoDescrizione
siteIdnel percorsostringIl suo id.
titlefacoltativostringIl suo titolo (facoltativo).fino a 500 caratteri
Richiesta
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

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

Una delle conversazioni di un sito.

Strumento MCP get_site_conversation

ArgomentoTipoDescrizione
siteIdnel percorsostringIl suo id.
cidnel percorsostringIl suo id.
Richiesta
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

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

I messaggi di una conversazione di un sito, dal più vecchio.

Strumento MCP list_site_messages

ArgomentoTipoDescrizione
siteIdnel percorsostringIl suo id.
cidnel percorsostringIl suo id.
Richiesta
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

POST/sites/{siteId}/conversations/{cid}/messagesA pagamento

Invia 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

ArgomentoTipoDescrizione
siteIdnel percorsostringIl suo id.
cidnel percorsostringIl suo id.
messageobbligatoriostringIl messaggio dell'utente.almeno 1 carattere
attachmentsfacoltativoarrayI file allegati al messaggio, come nell'app (gli stessi tipi, al massimo 20 MB ciascuno).
streamfacoltativobooleanAccettato per compatibilità; la risposta dell'API arriva sempre in streaming.
Richiesta
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.

Pronto a far decollare il tuo sito?

Fai la tua prima domanda - semchat ti risponde con un piano d'azione chiaro in pochi secondi.

Gratis · senza registrazione · in 5 secondi