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	updatedAt	Sort field. Only on /applications — 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.

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

The other endpoints (/notes, /tasks, /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
GET /notes	✓	createdAt
GET /tasks	✓	createdAt
GET /documents	✓	createdAt
GET /audit-logs	✓	createdAt
GET /webhooks	no — bare array	—
GET /webhooks/{id}/deliveries	no — bare array	—
GET /screening/hits	no — categorized	—

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