Riferimento API · Sessioni e Messaggi

API Sessioni e Messaggi della Chat

Crea, elenca, rinomina, fissa, contrassegna con stella e elimina le sessioni di chat, e gestisci i singoli messaggi al loro interno — inclusa la cronologia delle modifiche tracciata e l'annullamento.

← Torna alla documentazione Vai agli endpoint

Endpoint delle sessioni

POST /api/v1/sessions

GET /api/v1/sessions

GET /api/v1/sessions/{session_id}/messages

PATCH /api/v1/sessions/{session_id}

DELETE /api/v1/sessions/{session_id}

Endpoint dei messaggi

GET /api/v1/messages/{message_id}

PATCH /api/v1/messages/{message_id}

GET /api/v1/messages/{message_id}/history

POST /api/v1/messages/{message_id}/undo

DELETE /api/v1/messages/{message_id}

Crea sessione — Corpo della richiesta

json

{
  "title": "Untitled Chat",
  "kind": "chat",
  "folder_id": null,
  "agent_id": null,
  "metadata": {}
}

workspace_id non è accettato dal client in runtime personale, e deve corrispondere al contesto runtime dello workspace attivo altrimenti — non viene mai considerato come una sovrascrittura arbitraria del client.

Elenco — Parametri di query e risposta

tipoid_agentefissatolimite (predefinito 50, massimo 200)offset (predefinito 0)

json

{
  "items": [ { "id": "...", "title": "...", "pinned": false, "...": "..." } ],
  "total": 12,
  "limit": 50,
  "offset": 0
}

Aggiorna sessione (PATCH)

Almeno un campo deve essere presente nel corpo della richiesta — un PATCH vuoto viene rifiutato.

titolofissatocontrassegnatosegnalato come non letto

json

{
  "pinned": true,
  "starred": false
}

Comportamenti della sessione

Una sessione appartiene esattamente a un proprietario (un utente, opzionalmente limitato a uno workspace) — determinato dal contesto della richiesta autenticata, non dall'input del client.
Eliminare una sessione è una cancellazione logica (deleted_at viene impostato); la sessione e i suoi messaggi rimangono nel database ma sono esclusi da tutte le query standard.
GET /sessions/{session_id}/messages restituisce un conteggio dei messaggi calcolato dal vivo dai messaggi stessi, non un contatore memorizzato.
I parametri di percorso session_id e message_id sono validati come UUID — un ID malformato restituisce un errore di validazione chiaro, non un errore di server.
Le sessioni demo del sito di marketing sono limitate a 3 per utente e restituiscono 403 una volta raggiunto tale limite.

Cronologia delle modifiche del messaggio e annullamento

Ogni modifica al contenuto o al payload di un messaggio viene registrata prima che la modifica sia applicata, preservando la versione precedente.

json

[
  {
    "id": "8f14e...",
    "old_content": "Original message text",
    "old_payload": null,
    "edited_at": "2026-07-30T16:40:00Z"
  }
]

Un messaggio può essere modificato o eliminato solo dal proprietario della sessione a cui appartiene.
Annulla ripristina la versione registrata più recente e rimuove quella voce di cronologia — non torna oltre l'ultima modifica.
La modifica o l'eliminazione di un messaggio attualmente non regola il campo del conteggio messaggi memorizzato nella sessione; esso riflette sempre il conteggio dal vivo.

Modelli di errore

400

Richiesta non valida — incluso un corpo PATCH vuoto o nessuna modifica rilevata.

401

Autenticazione mancante o non valida.

404

Sessione o messaggio non trovato (o non di proprietà del chiamante).

Esempi

Crea una sessione

bash

curl -X POST "/api/v1/sessions" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Chat", "kind": "chat"}'

Fissa una sessione

bash

curl -X PATCH "/api/v1/sessions/[session_id]" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"pinned": true}'

Modifica un messaggio

bash

curl -X PATCH "/api/v1/messages/[message_id]" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"content": "Corrected message text"}'

Annulla l'ultima modifica

bash

curl -X POST "/api/v1/messages/[message_id]/undo" \
  -H "Authorization: Bearer [token]"