IntelligenceBox

Chat

Send a message and receive a streaming AI response. This is the core endpoint of the IntelligenceBox API. Every interaction with the AI — whether a simple question, a document-grounded query, or a conversation with a specialized assistant — goes through this endpoint. The response is delivered as a Server-Sent Events stream, allowing your application to display tokens in real time as they are generated.

Endpoint

Shell
POST /api/ai/chat

Request Parameters

idstringrequired
Unique chat ID. Reuse to continue conversation
messagesarrayrequired
Array of message objects
boxAddressstringrequired
Your server URL
assistantIdstring
Assistant ID from Assistants
vectorarray
Folder IDs from Folders

Message Object

JSON
{
  "role": "user",
  "content": "Your message here"
}

Roles: user, assistant, system

Basic Chat

No assistant, no folders - just chat with the AI.

Shell
curl -N -X POST BOX_URL/api/ai/chat \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "chat-001",
    "messages": [
      {"role": "user", "content": "What is machine learning?"}
    ],
    "boxAddress": "BOX_URL"
  }'

Chat with Assistant

Use a specific assistant’s personality and instructions.

Shell
curl -N -X POST BOX_URL/api/ai/chat \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "chat-002",
    "messages": [
      {"role": "user", "content": "Help me with my research"}
    ],
    "boxAddress": "BOX_URL",
    "assistantId": "YOUR_ASSISTANT_ID"
  }'

Chat with Folder (RAG)

Search your documents and use them as context.

Shell
curl -N -X POST BOX_URL/api/ai/chat \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "chat-003",
    "messages": [
      {"role": "user", "content": "What do my documents say about pricing?"}
    ],
    "boxAddress": "BOX_URL",
    "vector": ["YOUR_FOLDER_ID"]
  }'

Multiple Folders

JSON
"vector": ["folder-1", "folder-2", "folder-3"]

Chat with Assistant + Folder

Combine both - assistant’s personality + search multiple folders.

Shell
curl -N -X POST BOX_URL/api/ai/chat \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "chat-004",
    "messages": [
      {"role": "user", "content": "Summarize the key points from my documents"}
    ],
    "boxAddress": "BOX_URL",
    "assistantId": "YOUR_ASSISTANT_ID",
    "vector": ["FOLDER_ID_1", "FOLDER_ID_2"]
  }'

Response

The response is a Server-Sent Events (SSE) stream:

Shell
data: {"type":"text-delta","textDelta":"Hello"}
data: {"type":"text-delta","textDelta":"! I"}
data: {"type":"text-delta","textDelta":" can help"}
data: {"type":"finish","finishReason":"stop"}

See Parse Response for how to handle this in code.

Errors

CodeMeaning
401Invalid or missing API key
404Assistant or folder not found
500Server error
JSON
{
  "error": "Unauthorized - Invalid API key"
}

Tips for Effective Use

  • Reuse chat IDs for conversations: Sending the same id with an updated messages array continues the conversation. Include previous messages so the AI retains context across turns.
  • Be specific in prompts: Clear, detailed prompts produce better results. Instead of “Tell me about sales,” try “Summarize Q4 sales trends from my uploaded reports.”
  • Use the -N flag with curl: The -N flag disables output buffering, which is essential for seeing streamed tokens as they arrive rather than waiting for the entire response.

OpenAI-compatible endpoint

The box also exposes the OpenAI wire format, so any OpenAI-compatible client or SDK can talk to it unchanged. Point the client’s base URL at BOX_URL/api/v1 and use your API key as the OpenAI key.

Python
from openai import OpenAI

client = OpenAI(
    base_url="BOX_URL/api/v1",
    api_key="YOUR_API_KEY",
)

stream = client.chat.completions.create(
    model="default",            # the box picks the model; see the note below
    messages=[{"role": "user", "content": "Summarise this quarter's risks."}],
    stream=True,
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

This is the raw model, not the full box

/api/v1/chat/completions is a passthrough to the local model: no document retrieval, no assistants, no tools, no citations, and nothing is saved to your conversation history. The model field is also ignored — the box always serves its configured local model, and GET /api/v1/models reports which one that is. For document-grounded answers with citations, use POST /api/ai/chat above.

Shell
curl BOX_URL/api/v1/models \
  -H "x-api-key: YOUR_API_KEY"

# {"object":"list","data":[{"id":"Qwen/Qwen3-…","object":"model","owned_by":"intelligencebox"}]}

Related Endpoints

  • Parse Response — learn how to consume and parse the SSE stream in different languages
  • Stop Stream — cancel an active stream if the response is taking too long or is no longer needed
  • Assistants — find assistant IDs to use with the assistantId parameter
  • Folders — find folder IDs to use with the vector parameter for RAG
Chat | IntelligenceBox