> ## Documentation Index > Fetch the complete documentation index at: https://docs.illumichat.com/llms.txt > Use this file to discover all available pages before exploring further. # Chat > Send messages, stream AI responses via SSE, manage conversations, and work with file attachments. 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. ```bash theme={null} curl -X GET "https://app.illumichat.com/api/workspaces/ws_abc123/conversations?assistantId=ast_abc123&limit=20" \ -H "Authorization: Bearer " ``` | Parameter | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------------------- | | `assistantId` | string | No | Filter conversations by assistant. | | `limit` | integer | No | Items per page. Default `25`, max `100`. | | `offset` | integer | No | Items to skip. Default `0`. | **Response** `200 OK` ```json theme={null} { "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. ```bash theme={null} curl -X GET "https://app.illumichat.com/api/workspaces/ws_abc123/conversations/conv_aaa111" \ -H "Authorization: Bearer " ``` *** ## Delete Conversation Permanently deletes a conversation and all its messages. ```bash theme={null} curl -X DELETE "https://app.illumichat.com/api/workspaces/ws_abc123/conversations/conv_aaa111" \ -H "Authorization: Bearer " ``` **Response** `204 No Content` *** ## Create Message (Streaming) Sends a user message and streams the assistant's response via Server-Sent Events. ```bash cURL theme={null} curl -N -X POST "https://app.illumichat.com/api/workspaces/ws_abc123/conversations/conv_aaa111/messages" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "content": "How do I update my payment method?", "attachments": [], "webSearch": false }' ``` ```javascript JavaScript theme={null} const res = await fetch( "https://app.illumichat.com/api/workspaces/ws_abc123/conversations/conv_aaa111/messages", { method: "POST", headers: { Authorization: "Bearer ", "Content-Type": "application/json", }, body: JSON.stringify({ content: "How do I update my payment method?", }), } ); const reader = res.body.getReader(); const decoder = new TextDecoder(); while (true) { const { value, done } = await reader.read(); if (done) break; const chunk = decoder.decode(value); const lines = chunk.split("\n").filter(Boolean); for (const line of lines) { if (line.startsWith("data: ")) { const event = JSON.parse(line.slice(6)); switch (event.type) { case "text-delta": process.stdout.write(event.textDelta); break; case "finish": console.log("\n\nDone.", event.usage); break; case "error": console.error("Error:", event.error); break; } } } } ``` ```python Python theme={null} import requests import json res = requests.post( "https://app.illumichat.com/api/workspaces/ws_abc123/conversations/conv_aaa111/messages", headers={ "Authorization": "Bearer ", "Content-Type": "application/json", }, json={"content": "How do I update my payment method?"}, stream=True, ) for line in res.iter_lines(): if line and line.startswith(b"data: "): event = json.loads(line[6:]) if event["type"] == "text-delta": print(event["textDelta"], end="", flush=True) elif event["type"] == "finish": print(f"\n\nDone. Tokens: {event['usage']}") elif event["type"] == "error": print(f"Error: {event['error']}") ``` | Parameter | Type | Required | Description | | ------------- | ------- | -------- | ------------------------------------------------------------ | | `content` | string | Yes | The user's message text. | | `attachments` | array | No | List of file attachment objects. See File Attachments below. | | `webSearch` | boolean | No | Enable 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 | Type | Description | Fields | | ------------- | --------------------------------------------------------------- | -------------------------------- | | `text-delta` | A chunk of the assistant's text response. | `textDelta` | | `tool-call` | The assistant is invoking a tool (e.g., knowledge base search). | `toolCallId`, `toolName`, `args` | | `tool-result` | The result returned by the tool. | `toolCallId`, `result` | | `finish` | The response is complete. | `messageId`, `usage` | | `error` | An 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. ```bash theme={null} curl -X GET "https://app.illumichat.com/api/workspaces/ws_abc123/conversations/conv_aaa111/messages?limit=50" \ -H "Authorization: Bearer " ``` **Response** `200 OK` ```json theme={null} { "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. ```bash theme={null} curl -X GET "https://app.illumichat.com/api/workspaces/ws_abc123/conversations/conv_aaa111/messages/msg_bbb222" \ -H "Authorization: Bearer " ``` *** ## File Attachments Messages can include file attachments uploaded via Uploadcare. ```json theme={null} { "content": "Can you summarize this document?", "attachments": [ { "name": "report.pdf", "url": "https://ucarecdn.com/abc123-def456/report.pdf", "contentType": "application/pdf" } ] } ``` | Field | Type | Required | Description | | ------------- | ------ | -------- | -------------------------------- | | `name` | string | Yes | Original file name. | | `url` | string | Yes | Uploadcare CDN URL for the file. | | `contentType` | string | Yes | MIME 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. *** ## Web Search 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. ```json theme={null} { "content": "What is the current stock price of ACME?", "webSearch": true } ```