Pagination

List endpoints return paginated results. Use page and limit parameters to navigate.

Parameters

Parameter	Type	Default	Max
page	integer	1	-
limit	integer	20	100

Response Format

All list endpoints return data in a data array with pagination info in meta:

{
  "data": [
    { "id": 1, "title": "Software Engineer", ... },
    { "id": 2, "title": "Product Manager", ... }
  ],
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "req_abc123",
    "total": 87,
    "page": 1,
    "limit": 20,
    "total_pages": 5
  }
}

Field	Description
total	Total records across all pages
page	Current page number (1-indexed)
limit	Items per page (max 100)
total_pages	Total pages available

Fetching Pages

# First page (default)
curl "https://api.kula.ai/v1/job-boards/job-posts"

# Specific page with custom limit
curl "https://api.kula.ai/v1/job-boards/job-posts?page=2&limit=50"

Fetching All Pages

async function fetchAllPages(token) {
  const allItems = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://api.kula.ai/v1/job-boards/job-posts?page=${page}`,
      { headers: { 'Authorization': `Bearer ${token}` } }
    );

    const result = await response.json();
    allItems.push(...result.data);

    hasMore = page < result.meta.total_pages;
    page++;
  }

  return allItems;
}

Cursor-Based Pagination

The POST /v1/candidates/search endpoint uses cursor-based pagination instead of page numbers. This is more efficient for deep pagination over large result sets.

When results are available beyond the current page, the response meta includes a next_cursor token:

{
  "data": [...],
  "meta": {
    "total": 500,
    "limit": 20,
    "next_cursor": "eyJpZCI6MTIzfQ==",
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "req_abc123"
  }
}

Pass the cursor in your next request to get the following page:

curl -X POST "https://api.kula.ai/v1/candidates/search" \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{"cursor": "eyJpZCI6MTIzfQ=="}'

Important rules for cursor pagination:

• A cursor is tied to a specific search context. If you change any filter parameter, omit the cursor and start a new search.
• cursor and page are mutually exclusive — do not send both in the same request.
• When next_cursor is absent from meta, you have reached the last page.

Best Practices

• Request only the pages you need
• Use larger page sizes (50-100) to reduce API calls
• Cache frequently accessed pages
• Check total_pages before requesting beyond available data
• For candidate search, use cursor-based pagination for deep traversal