Pagination

List endpoints return cursor-paginated results. Walk through pages by passing each response’s nextCursor back as the cursor query parameter on the next request.

Environment: Examples use Production (https://api.getsteward.ai) with an stw_live_… key. For Sandbox, use https://api.steward-sandbox.com with an stw_test_… key.

Response Envelope

Every paginated endpoint returns the same shape:

{
  "items": [...],
  "nextCursor": "ZGVzY3x1cGRhdGVkQXR8MjAyNi0wNS0xM1QxNjowOToxMi4wMDBafDUwN2Yx..."
}

Field	Type	Description
items	array	Results for the current page.
nextCursor	string | null	Opaque token to fetch the next page. null when there are no more results.

Query Parameters

Parameter	Type	Default	Description
cursor	string	(none)	Opaque token from a previous response’s nextCursor. Omit on the first request.
limit	integer	50	Results per page, 1–100.
order	string	desc	Sort direction: asc (oldest first) or desc (newest first).
orderBy	string	endpoint-specific	Sort field on /applications and /tasks (see Sort Field below). Other endpoints fix the sort field.

Walking All Pages

#!/bin/bash
URL="https://api.getsteward.ai/api/v1/applications?limit=50"
AUTH="Authorization: Bearer stw_live_your_api_key_here"

while [ -n "$URL" ]; do
  RESPONSE=$(curl -sS "$URL" -H "$AUTH")
  echo "$RESPONSE" | jq '.items[]'

  CURSOR=$(echo "$RESPONSE" | jq -r '.nextCursor // empty')
  if [ -z "$CURSOR" ]; then
    URL=""
  else
    URL="https://api.getsteward.ai/api/v1/applications?limit=50&cursor=${CURSOR}"
  fi
done

In JavaScript:

async function fetchAll(endpoint) {
  const items = []
  let cursor

  do {
    const url = new URL(`https://api.getsteward.ai/api/v1/${endpoint}`)
    url.searchParams.set('limit', '50')
    if (cursor) url.searchParams.set('cursor', cursor)

    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.STEWARD_API_KEY}` }
    })
    const page = await response.json()

    items.push(...page.items)
    cursor = page.nextCursor
  } while (cursor)

  return items
}

Sort Field

/applications accepts an orderBy parameter:

Value	Sorts by	Use when
updatedAt	Most recent activity (default)	You want the freshest data first: most apps recently touched on top.
createdAt	When the application was created	You want a stable insertion-order view that doesn’t shift as apps update.
name	Investor name (A–Z)	You want an alphabetical list; businesses and individuals interleave.

curl "https://api.getsteward.ai/api/v1/applications?orderBy=createdAt&order=desc" \
  -H "Authorization: Bearer stw_live_..."

/tasks also accepts orderBy=createdAt (default) or orderBy=updatedAt for task activity. The other endpoints (/notes, /documents, /audit-logs) always sort by createdAt.

Cursor Lifecycle

Cursors are tied to the sort direction and sort field they were issued under. If you change order or orderBy mid-pagination, the cursor is rejected. Reset by omitting the cursor and starting over.

GET /applications?order=desc                  → nextCursor: A
GET /applications?cursor=A&order=desc                ✓ ok
GET /applications?cursor=A&order=asc                 ✗ 400: direction does not match
GET /applications?cursor=A&orderBy=createdAt         ✗ 400: sort field does not match

Possible 400 responses when using cursors:

Message	Cause
Invalid pagination cursor	Token is malformed or wasn’t issued by this API.
Pagination cursor direction does not match sort order	The order you passed differs from the one the cursor was issued with.
Pagination cursor sort field does not match requested orderBy	The orderBy you passed differs from the one the cursor was issued with.

To switch sort direction or field mid-traversal, drop the cursor parameter and start from page 1.

Which Endpoints Are Paginated

Endpoint	Paginated	Sort field
GET /applications	✓	createdAt/updatedAt/name
GET /notes	✓	createdAt
GET /tasks	✓	createdAt/updatedAt
GET /documents	✓	createdAt
GET /audit-logs	✓	createdAt
GET /webhooks	no, bare array	none
GET /webhooks/{id}/deliveries	no, bare array	none
GET /screening/hits	no, categorized	none
GET /platform/search	offset, not cursor	none

The unpaginated endpoints are naturally bounded (a handful of webhooks per account; screening hits are grouped by hit type rather than listed flat).

Search pages differently

GET /platform/search is the one list endpoint that does not use cursors. It takes limit and offset, and returns each result category with its own total rather than a nextCursor:

curl "https://api.getsteward.ai/api/v1/platform/search?q=acme&limit=20&offset=20" \
  -H "Authorization: Bearer stw_live_your_api_key_here"

Page it by advancing offset, and stop when you have consumed a category’s total. None of the cursor rules above apply. There is no token to invalidate, so you can change sort or filters between requests freely. Results are a ranked snapshot, so a record created mid-traversal can shift rows between pages; for exhaustive extraction prefer the cursor-paginated resource endpoints.