IntelligenceBox

Riferimento API

Conversazioni

Le conversazioni nascono dall’endpoint di chat, che restituisce la risposta in streaming. Questi endpoint servono dopo: rileggere la trascrizione, elencare cosa è stato chiesto, rinominare un thread o fare pulizia.

Da dove arrivano le conversazioni

Una conversazione non si crea direttamente. Manda un messaggio a POST /api/ai/chat con un id scelto da te e il box la crea al primo utilizzo. Riusa lo stesso id per proseguire il thread.

Elencare le conversazioni#

GET/api/public/chatsAPI key

Le conversazioni del proprietario della chiave, dalla più aggiornata di recente.

limitinteger
Quante restituirne, da 1 a 200.Predefinito: 50.
offsetinteger
Righe da saltare, per la paginazione.Predefinito: 0.
origin"API" | "APP"
API restituisce solo le conversazioni avviate da questa API; APP solo quelle che una persona ha avuto nell’app desktop.
searchstring
Filtro sul titolo della conversazione, senza distinzione tra maiuscole e minuscole.
Shell
curl "BOX_URL/api/public/chats?origin=API&limit=20" \
  -H "x-api-key: YOUR_API_KEY"
JSON
{
  "chats": [
    {
      "id": "contract-review-8821",
      "title": "Standard notice period",
      "origin": "API",
      "vectorIds": ["9c8a2b31-7f45-4d10-8e6a-1b3f0d2c4a58"],
      "projectId": null,
      "messageCount": 4,
      "createdAt": "2026-08-02T16:03:11.220Z",
      "updatedAt": "2026-08-02T16:07:48.905Z"
    }
  ],
  "pagination": { "total": 37, "limit": 20, "offset": 0, "hasMore": true }
}

origin è ciò che ti distingue agli occhi dell’app

Le conversazioni create tramite API sono etichettate API e compaiono separatamente nella vista di monitoraggio dell’app desktop. Filtrare su questo campo è il modo più pulito per controllare esattamente cosa ha chiesto la tua integrazione.

Leggere una conversazione#

GET/api/public/chats/:idAPI key

La conversazione con la trascrizione completa in ordine cronologico.

JSON
{
  "chat": {
    "id": "contract-review-8821",
    "title": "Standard notice period",
    "origin": "API",
    "messages": [
      {
        "id": "0a3f…",
        "role": "user",
        "content": "What is our standard notice period?",
        "parts": [{ "type": "text", "text": "What is our standard notice period?" }],
        "attachments": null,
        "finishReason": null,
        "createdAt": "2026-08-02T16:03:11.220Z"
      },
      {
        "id": "5b91…",
        "role": "assistant",
        "content": "Ninety days' written notice, per clause 14.2…",
        "parts": [ /* text, tool calls, reasoning */ ],
        "finishReason": "stop",
        "createdAt": "2026-08-02T16:03:19.741Z"
      }
    ]
  }
}
role"user" | "assistant" | "system"
Chi ha prodotto il messaggio.
contentstring
I segmenti di solo testo uniti insieme — il campo comodo quando ti serve solo leggere la risposta.
partsarray
Il messaggio strutturato completo: testo, chiamate agli strumenti, risultati degli strumenti e passaggi di ragionamento. Usalo se ti serve vedere cosa ha fatto davvero l’assistente.
attachmentsarray | null
File inviati insieme al messaggio.
finishReasonstring | null
Perché la generazione si è fermata — stop, length, tool-calls.

Rinominare una conversazione#

PATCH/api/public/chats/:idAPI key
titlestringobbligatorio
Il nuovo titolo. Massimo 300 caratteri.
Shell
curl -X PATCH BOX_URL/api/public/chats/contract-review-8821 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Acme MSA — notice period" }'

Eliminare una conversazione#

DELETE/api/public/chats/:idAPI key

Rimuove la conversazione e tutti i messaggi che contiene.

  • 200Eliminata.
  • 404Nessuna conversazione con questo id per questo utente.

I messaggi se ne vanno con lei

L’eliminazione si propaga alla trascrizione. Se ti serve il contenuto, recupera prima la conversazione.
Conversazioni | IntelligenceBox