IntelligenceBox

API reference

Conversations

Conversations are created by the chat endpoint, which streams the answer. These endpoints are what you use afterwards: read the transcript back, list what has been asked, rename a thread, or clean up.

Where conversations come from

You do not create a conversation directly. Send a message to POST /api/ai/chat with an id of your choosing and the box creates it on first use. Reuse the same id to continue the thread.

List conversations#

GET/api/public/chatsAPI key

The key owner's conversations, most recently updated first.

limitinteger
How many to return, 1–200.Default: 50.
offsetinteger
Rows to skip, for paging.Default: 0.
origin"API" | "APP"
API returns only conversations started through this API; APP only those a person had in the desktop app.
searchstring
Case-insensitive filter on the conversation title.
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 is how the app tells you apart

Conversations created through the API are tagged API and surface separately in the desktop app’s monitoring view. Filtering on it is the cleanest way to audit exactly what your integration has been asking.

Get a conversation#

GET/api/public/chats/:idAPI key

The conversation with its full transcript in chronological order.

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"
Who produced the message.
contentstring
The plain-text segments joined together — the convenient field when you just want to read the answer.
partsarray
The full structured message: text, tool calls, tool results and reasoning steps. Use this if you need to see what the assistant actually did.
attachmentsarray | null
Files sent with the message.
finishReasonstring | null
Why generation stopped — stop, length, tool-calls.

Rename a conversation#

PATCH/api/public/chats/:idAPI key
titlestringrequired
The new title. Max 300 characters.
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" }'

Delete a conversation#

DELETE/api/public/chats/:idAPI key

Removes the conversation and every message in it.

  • 200Deleted.
  • 404No such conversation for this user.

Messages go with it

Deletion cascades to the transcript. If you need the content, fetch the conversation first.
Conversations | IntelligenceBox