Skip to main content
The Chat API lets you create conversations with assistants, send messages, and receive streamed AI responses in real time via Server-Sent Events (SSE).

​
List Conversations

Returns conversations for the authenticated user within a workspace. Uses offset-based pagination. 
curl -X GET "https://beta.illumichat.com/api/workspaces/ws_abc123/conversations?assistantId=ast_abc123&limit=20" \
  -H "Authorization: Bearer <your-api-key>"
ParameterTypeRequiredDescription
assistantIdstringNoFilter conversations by assistant.
limitintegerNoItems per page. Default 25, max 100.
offsetintegerNoItems to skip. Default 0.
Response 200 OK 
{
  "data": [
    {
      "id": "conv_aaa111",
      "title": "Help with billing",
      "assistantId": "ast_abc123",
      "messageCount": 8,
      "createdAt": "2025-09-10T14:30:00Z",
      "updatedAt": "2025-09-10T14:45:00Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

​
Get Conversation

Retrieves a single conversation with metadata. 
curl -X GET "https://beta.illumichat.com/api/workspaces/ws_abc123/conversations/conv_aaa111" \
  -H "Authorization: Bearer <your-api-key>"

​
Delete Conversation

Permanently deletes a conversation and all its messages. 
curl -X DELETE "https://beta.illumichat.com/api/workspaces/ws_abc123/conversations/conv_aaa111" \
  -H "Authorization: Bearer <your-api-key>"
Response 204 No Content

​
Create Message (Streaming)

Sends a user message and streams the assistant’s response via Server-Sent Events. 
curl -N -X POST "https://beta.illumichat.com/api/workspaces/ws_abc123/conversations/conv_aaa111/messages" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I update my payment method?",
    "attachments": [],
    "webSearch": false
  }'
ParameterTypeRequiredDescription
contentstringYesThe user’s message text.
attachmentsarrayNoList of file attachment objects. See File Attachments below.
webSearchbooleanNoEnable web search for this message. Default false.
If the conversation ID does not exist, the API creates a new conversation automatically.

​
SSE Event Format

The streaming response uses the text/event-stream content type. Each event is a JSON object on a data: line. 
data: {"type":"text-delta","textDelta":"To update"}
data: {"type":"text-delta","textDelta":" your payment"}
data: {"type":"tool-call","toolCallId":"tc_1","toolName":"searchKnowledgeBase","args":{"query":"update payment method"}}
data: {"type":"tool-result","toolCallId":"tc_1","result":{"documents":[{"title":"Billing FAQ"}]}}
data: {"type":"text-delta","textDelta":" method, go to Settings > Billing."}
data: {"type":"finish","messageId":"msg_xyz","usage":{"promptTokens":245,"completionTokens":67}}

​
Event Types

TypeDescriptionFields
text-deltaA chunk of the assistant’s text response.textDelta
tool-callThe assistant is invoking a tool (e.g., knowledge base search).toolCallId, toolName, args
tool-resultThe result returned by the tool.toolCallId, result
finishThe response is complete.messageId, usage
errorAn error occurred during generation.error, code
Always handle the error event type. Errors can occur mid-stream if the model encounters an issue, the context window is exceeded, or a rate limit is reached.

​
List Messages

Returns messages in a conversation. Uses cursor-based pagination, ordered from newest to oldest. 
curl -X GET "https://beta.illumichat.com/api/workspaces/ws_abc123/conversations/conv_aaa111/messages?limit=50" \
  -H "Authorization: Bearer <your-api-key>"
Response 200 OK 
{
  "data": [
    {
      "id": "msg_bbb222",
      "role": "assistant",
      "content": "To update your payment method, go to Settings > Billing.",
      "createdAt": "2025-09-10T14:31:00Z"
    },
    {
      "id": "msg_aaa111",
      "role": "user",
      "content": "How do I update my payment method?",
      "createdAt": "2025-09-10T14:30:30Z"
    }
  ],
  "nextCursor": "eyJpZCI6Im1zZ19hYWExMTEifQ==",
  "hasMore": false
}

​
Get Message

Retrieves a single message by ID. 
curl -X GET "https://beta.illumichat.com/api/workspaces/ws_abc123/conversations/conv_aaa111/messages/msg_bbb222" \
  -H "Authorization: Bearer <your-api-key>"

​
File Attachments

Messages can include file attachments uploaded via Uploadcare. 
{
  "content": "Can you summarize this document?",
  "attachments": [
    {
      "name": "report.pdf",
      "url": "https://ucarecdn.com/abc123-def456/report.pdf",
      "contentType": "application/pdf"
    }
  ]
}
FieldTypeRequiredDescription
namestringYesOriginal file name.
urlstringYesUploadcare CDN URL for the file.
contentTypestringYesMIME type of the file.
Supported file types include PDF, TXT, DOCX, PNG, JPG, and CSV. Maximum file size is 10 MB per attachment and 3 attachments per message.
Set webSearch: true on a message to allow the assistant to search the web for current information. When active, the assistant may emit tool-call and tool-result events for the webSearch tool before generating its response. 
{
  "content": "What is the current stock price of ACME?",
  "webSearch": true
}