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

POST /api/ai/chat

Request Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Unique chat ID. Reuse to continue conversation
`messages`	array	Yes	Array of message objects
`boxAddress`	string	Yes	Your server URL
`assistantId`	string	No	Assistant ID from List Assistants
`vector`	array	No	Folder IDs from List Folders

Message Object

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

Roles: user, assistant, system

Basic Chat

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

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.

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.

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

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

Chat with Assistant + Folder

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

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:

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

Code	Meaning
401	Invalid or missing API key
404	Assistant or folder not found
500	Server error

{
  "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.

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
List Assistants -- Find assistant IDs to use with the assistantId parameter
List Folders -- Find folder IDs to use with the vector parameter for RAG