IllumiChat - AI-Powered Chat Platform

The IllumiChat API lets you manage assistants, conversations, contacts, tickets, and more. All endpoints follow REST conventions and return JSON responses.

Base URL

https://app.illumichat.com/api

Request Format

Use Content-Type: application/json for request bodies
Include authentication credentials with every request (see Authentication)
URL path parameters are denoted with {paramName} in the endpoint documentation

Example Request

curl -X GET https://app.illumichat.com/api/assistants \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json"

const response = await fetch("https://app.illumichat.com/api/assistants", {
  headers: {
    Authorization: "Bearer <your-token>",
    "Content-Type": "application/json",
  },
});

const data = await response.json();

import requests

response = requests.get(
    "https://app.illumichat.com/api/assistants",
    headers={
        "Authorization": "Bearer <your-token>",
        "Content-Type": "application/json",
    },
)

data = response.json()

Response Format

All successful responses return JSON. The structure depends on the endpoint:

// Single resource
{
  "id": "abc123",
  "name": "My Assistant",
  "createdAt": "2025-01-15T10:30:00Z"
}

// Collection
[
  { "id": "abc123", "name": "Assistant A" },
  { "id": "def456", "name": "Assistant B" }
]

Error responses use a consistent format described in Errors & Status Codes.

Authentication Methods

Method	Use Case	Details
Session cookie	Browser-based apps	Set automatically after Auth0 login
Bearer token	Server-to-server	Pass in `Authorization` header
Public (no auth)	Widget & SMS webhooks	Rate-limited by IP or assistant

See Authentication for full details.

API Sections

Authentication

Session cookies, API keys, and public endpoints.

Errors & Status Codes

Error format, HTTP codes, and handling patterns.

Rate Limiting

Request limits, widget quotas, and backoff strategies.

Endpoint Reference

Browse individual endpoint documentation generated from the OpenAPI spec.

Key Endpoint Groups

Two surfaces exist and they authenticate differently — check which one an endpoint belongs to before writing an integration: API-key surface (/api/v1/*) — the endpoints an external integration can call with Authorization: Bearer <your-api-key>. Write access additionally requires the api_v1_write plan feature.

Group	Base Path	Description
Contacts	`/api/v1/contacts`	Create and manage contacts
Messages	`/api/v1/messages`	Send messages
Tickets	`/api/v1/tickets`	Support ticket lifecycle

Session surface — these require a signed-in browser session, not an API key. They power the IllumiChat app itself; an API key will be rejected.

Group	Base Path	Description
Assistants	`/api/assistants`	Create, update, and manage AI assistants
Inbox	`/api/inbox/conversations`	Read conversations and reply as a human agent
Webhooks	`/api/webhooks`	Manage webhook subscriptions

Public / unauthenticated — no credentials, scoped to one assistant or used by providers.

Group	Base Path	Description
Widget	`/api/widget/{assistantId}`	Public widget endpoints
SMS	`/api/sms/webhook/{assistantId}`	Twilio inbound/status webhooks

The full OpenAPI specification is available and powers the auto-generated endpoint pages in this documentation. You can also download it for use with tools like Postman or code generators.

Getting Started

Endpoints

API Overview

Base URL

Request Format

Example Request

Response Format

Authentication Methods

API Sections

Authentication

Errors & Status Codes

Rate Limiting

Endpoint Reference

Key Endpoint Groups

​Base URL

​Request Format

​Example Request

​Response Format

​Authentication Methods

​API Sections

Authentication

Errors & Status Codes

Rate Limiting

Endpoint Reference

​Key Endpoint Groups

Base URL

Request Format

Example Request

Response Format

Authentication Methods

API Sections

Key Endpoint Groups