IllumiChat - AI-Powered Chat Platform

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://app.illumichat.com/api/workspaces/ws_abc123/conversations?assistantId=ast_abc123&limit=20" \
  -H "Authorization: Bearer <your-api-key>"

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

{
  "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://app.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://app.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://app.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
  }'

const res = await fetch(
  "https://app.illumichat.com/api/workspaces/ws_abc123/conversations/conv_aaa111/messages",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <your-api-key>",
      "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;
      }
    }
  }
}

import requests
import json

res = requests.post(
    "https://app.illumichat.com/api/workspaces/ws_abc123/conversations/conv_aaa111/messages",
    headers={
        "Authorization": "Bearer <your-api-key>",
        "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.

curl -X GET "https://app.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://app.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"
    }
  ]
}

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.

{
  "content": "What is the current stock price of ACME?",
  "webSearch": true
}

Getting Started

Endpoints

Chat

List Conversations

Get Conversation

Delete Conversation

Create Message (Streaming)

SSE Event Format

Event Types

List Messages

Get Message

File Attachments

Web Search

​List Conversations

​Get Conversation

​Delete Conversation

​Create Message (Streaming)

​SSE Event Format

​Event Types

​List Messages

​Get Message

​File Attachments

​Web Search

List Conversations

Get Conversation

Delete Conversation

Create Message (Streaming)

SSE Event Format

Event Types

List Messages

Get Message

File Attachments

Web Search