Chat

Send a message and receive a streaming AI response.

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"
}