IllumiChat - AI-Powered Chat Platform

The IllumiChat API provides two pagination patterns depending on the endpoint and the nature of the data being returned. Offset-based pagination is used for static collections such as workspaces, assistants, and members. Cursor-based pagination is used for streaming or append-heavy data such as messages and webhook deliveries.

Offset-Based Pagination

Offset-based pagination uses limit and offset query parameters to control which slice of results is returned.

Parameter	Type	Default	Description
`limit`	integer	`25`	Number of items to return. Minimum `1`, maximum `100`.
`offset`	integer	`0`	Number of items to skip before starting to return results.

Response Shape

Every offset-paginated response includes the following top-level fields:

{
  "data": [
    { "id": "ws_abc123", "name": "Acme Corp" },
    { "id": "ws_def456", "name": "Globex" }
  ],
  "total": 48,
  "limit": 25,
  "offset": 0
}

Field	Type	Description
`data`	array	The requested items for the current page.
`total`	integer	Total number of items matching the query across all pages.
`limit`	integer	The limit that was applied.
`offset`	integer	The offset that was applied.

Examples

curl -X GET "https://app.illumichat.com/api/workspaces?limit=10&offset=20" \
  -H "Authorization: Bearer <your-api-key>"

const res = await fetch(
  "https://app.illumichat.com/api/workspaces?limit=10&offset=20",
  {
    headers: { Authorization: "Bearer <your-api-key>" },
  }
);

const { data, total, limit, offset } = await res.json();
console.log(`Showing ${data.length} of ${total} workspaces`);

import requests

res = requests.get(
    "https://app.illumichat.com/api/workspaces",
    params={"limit": 10, "offset": 20},
    headers={"Authorization": "Bearer <your-api-key>"},
)

result = res.json()
print(f"Showing {len(result['data'])} of {result['total']} workspaces")

To iterate through all pages, increment offset by limit on each request until offset >= total.

Iterating Through All Pages

async function fetchAll(baseUrl, token) {
  const items = [];
  let offset = 0;
  const limit = 100;

  while (true) {
    const res = await fetch(`${baseUrl}?limit=${limit}&offset=${offset}`, {
      headers: { Authorization: `Bearer ${token}` },
    });
    const { data, total } = await res.json();
    items.push(...data);
    offset += limit;
    if (offset >= total) break;
  }

  return items;
}

def fetch_all(base_url: str, token: str) -> list:
    items = []
    offset = 0
    limit = 100

    while True:
        res = requests.get(
            base_url,
            params={"limit": limit, "offset": offset},
            headers={"Authorization": f"Bearer {token}"},
        )
        result = res.json()
        items.extend(result["data"])
        offset += limit
        if offset >= result["total"]:
            break

    return items

Cursor-Based Pagination

Cursor-based pagination uses an opaque cursor parameter and returns a nextCursor value. This pattern is more efficient for large, frequently changing datasets because it avoids the consistency issues inherent in offset-based pagination.

Parameter	Type	Default	Description
`limit`	integer	`25`	Number of items to return. Minimum `1`, maximum `100`.
`cursor`	string	`null`	Opaque cursor from a previous response. Omit to start from the beginning.

Response Shape

{
  "data": [
    { "id": "msg_aaa111", "content": "Hello" },
    { "id": "msg_bbb222", "content": "Hi there" }
  ],
  "nextCursor": "eyJpZCI6Im1zZ19iYmIyMjIifQ==",
  "hasMore": true
}

Field	Type	Description
`data`	array	The requested items for the current page.
`nextCursor`	string or null	Pass this value as the `cursor` parameter to fetch the next page. `null` when there are no more results.
`hasMore`	boolean	`true` if additional pages exist beyond the current result set.

Examples

# First page
curl -X GET "https://app.illumichat.com/api/conversations/conv_abc/messages?limit=50" \
  -H "Authorization: Bearer <your-api-key>"

# Next page
curl -X GET "https://app.illumichat.com/api/conversations/conv_abc/messages?limit=50&cursor=eyJpZCI6Im1zZ19iYmIyMjIifQ==" \
  -H "Authorization: Bearer <your-api-key>"

async function fetchMessages(conversationId, token) {
  const messages = [];
  let cursor = null;

  do {
    const params = new URLSearchParams({ limit: "50" });
    if (cursor) params.set("cursor", cursor);

    const res = await fetch(
      `https://app.illumichat.com/api/conversations/${conversationId}/messages?${params}`,
      { headers: { Authorization: `Bearer ${token}` } }
    );

    const result = await res.json();
    messages.push(...result.data);
    cursor = result.nextCursor;
  } while (cursor);

  return messages;
}

def fetch_messages(conversation_id: str, token: str) -> list:
    messages = []
    cursor = None

    while True:
        params = {"limit": 50}
        if cursor:
            params["cursor"] = cursor

        res = requests.get(
            f"https://app.illumichat.com/api/conversations/{conversation_id}/messages",
            params=params,
            headers={"Authorization": f"Bearer {token}"},
        )

        result = res.json()
        messages.extend(result["data"])
        cursor = result.get("nextCursor")
        if not cursor:
            break

    return messages

Cursor values are opaque and may change between API versions. Do not parse, construct, or store cursors for long-term use. Always obtain a fresh cursor from the most recent API response.

Choosing a Pattern

Use Case	Pattern	Reason
Listing workspaces, assistants, members	Offset-based	Stable datasets; total count is useful for UI
Browsing messages in a conversation	Cursor-based	Append-heavy data; avoids skipped or duplicated items
Webhook delivery logs	Cursor-based	High-volume, time-ordered data
Search results	Offset-based	Users expect page numbers and total counts

If an endpoint supports pagination, the documentation for that endpoint specifies which pattern is used. When in doubt, check the response shape: the presence of nextCursor indicates cursor-based pagination, while total and offset indicate offset-based pagination.

Getting Started

Endpoints

Pagination

Response Shape

Examples

Iterating Through All Pages

Response Shape

Examples

Choosing a Pattern

​Offset-Based Pagination

​Response Shape

​Examples

​Iterating Through All Pages

​Cursor-Based Pagination

​Response Shape

​Examples

​Choosing a Pattern

Offset-Based Pagination

Response Shape

Examples

Iterating Through All Pages

Cursor-Based Pagination

Response Shape

Examples

Choosing a Pattern