Pagination

List endpoints use cursor-based pagination for efficient traversal of large datasets. Cursors are opaque strings. Do not assume their format or try to construct them manually.

Request Parameters

Paginate by passing optional query parameters:

Name	Type	Required	Description
cursor	string		Cursor from the previous response's nextCursor. Omit for the first page.
limit	integer		Number of items per page (max 100). Default: 20

Example: GET /agents?limit=50 or GET /agents?cursor=cs_abc123&limit=50

Response Format

Paginated responses include:

json

{
  "data": [
    { "id": "ag_1", "name": "Support Bot", ... },
    { "id": "ag_2", "name": "Sales Bot", ... }
  ],
  "nextCursor": "cs_xyz789"
}

If nextCursor is null or absent, you have reached the last page.

Pagination Loop Example

Fetch all agents (or any paginated resource) in JavaScript:

javascript

async function fetchAllAgents() {
  const agents = [];
  let cursor = null;

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

    const res = await fetch(`https://chatspark.io/api/v1/agents?${params}`, {
      headers: {
        "Authorization": "Bearer cs_live_...",
      },
    });

    if (!res.ok) throw new Error(`Request failed: ${res.status}`);

    const { data, nextCursor } = await res.json();
    agents.push(...data);
    cursor = nextCursor;
  } while (cursor);

  return agents;
}

// Usage
const allAgents = await fetchAllAgents();
console.log(`Fetched ${allAgents.length} agents`);

Errors

Streaming