Pagination

The Chainabit API supports two pagination strategies: offset-based and cursor-based. Most list endpoints use offset-based pagination. Cursor-based pagination is used by specific endpoints where consistent ordering across pages is critical (e.g., notification history, audit logs).

Offset-Based Pagination

Query Parameters

Parameter	Type	Default	Range	Description
limit	integer	20	1 -- 50	Number of records to return per page.
offset	integer	0	0+	Number of records to skip before returning results.

Example Request

GET /api/v1/chains?limit=10&offset=20
Authorization: Bearer <accessToken>

Example Response

{
  "data": [
    { "id": "chain_001", "name": "Morning Run" },
    { "id": "chain_002", "name": "Read 20 Pages" }
  ],
  "meta": {
    "requestId": "req_abc123",
    "durationMs": 15,
    "limit": 10,
    "offset": 20,
    "total": 47,
    "hasNextPage": true
  }
}

Iterating Through Pages

Use offset and limit to walk through the full result set:

Page 1: GET /chains?limit=20&offset=0   → records 1-20
Page 2: GET /chains?limit=20&offset=20  → records 21-40
Page 3: GET /chains?limit=20&offset=40  → records 41-47

Stop iterating when hasNextPage is false or when offset + limit >= total.

Cursor-Based Pagination

Cursor-based pagination uses an opaque token to mark the position in the result set. This ensures stable pagination even when records are added or removed between requests.

Query Parameters

Parameter	Type	Default	Description
limit	integer	25	Number of records to return per page.
cursor	string	(none)	Opaque pagination token from a previous response. Omit for the first page.

GET /api/v1/notifications?limit=10
Authorization: Bearer <accessToken>

Example Response

{
  "data": [
    { "id": "ntf_001", "type": "ai_run_completed", "read": false },
    { "id": "ntf_002", "type": "workspace_invite", "read": true }
  ],
  "meta": {
    "requestId": "req_def456",
    "durationMs": 22,
    "limit": 10,
    "hasNextPage": true,
    "nextCursor": "eyJpZCI6Im50Zl8wMDIifQ=="
  }
}

Example Request (Next Page)

GET /api/v1/notifications?limit=10&cursor=eyJpZCI6Im50Zl8wMDIifQ==
Authorization: Bearer <accessToken>

Iterating Through Pages

1. Make the initial request without a cursor.
2. If hasNextPage is true, make another request with cursor set to nextCursor from the previous response.
3. Repeat until hasNextPage is false.

let cursor = undefined;

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

  const response = await fetch(
    `https://api.chainabit.com/api/v1/notifications?${params}`,
    { headers: { Authorization: `Bearer ${token}` } }
  );
  const { data, meta } = await response.json();

  // Process data...

  cursor = meta.hasNextPage ? meta.nextCursor : undefined;
} while (cursor);

Response Meta Fields

Both pagination strategies include metadata in the response meta object:

Field	Type	Present In	Description
limit	integer	Both	The page size used for this request.
offset	integer	Offset only	The number of records skipped.
total	integer	Offset only	Total number of records matching the query.
hasNextPage	boolean	Both	Whether more records exist beyond this page.
nextCursor	string	Cursor only	The token to pass as cursor for the next page.

Which Endpoints Use Which Strategy

Strategy	Endpoints
Offset-based	Most list endpoints: chains, chainies, bits, boards, cards, agents, workflows, etc.
Cursor-based	Notification history, audit logs, and other ordered list endpoints.

The pagination strategy for each endpoint is documented in the individual endpoint reference.