pagination

Last updated: 2026-04-28

request parameters

If both canonical and compatibility names are present, the canonical name wins.

Routes using the shared pagination helper return 400 validation_failed for invalid page_size; /api/cortex/conversations and /api/chat currently clamp or default invalid values, so clients should consult the endpoint reference for validation behavior.

response fields

Canonical paginated responses include:

{
  "items": [],
  "next_page_token": ""
}

The collection field name may be resource-specific, such as sites, machines, roosts, versions, deployments, records, webhooks, or deliveries.

next_page_token is an empty string when there are no more pages. Treat null, a missing token, or an empty compatibility token as end-of-list only on endpoints that explicitly document that shape.

During the developer-preview compatibility window, some responses also include camelCase aliases:

{
  "roosts": [],
  "next_page_token": "eyJ...",
  "nextPageToken": "eyJ..."
}

New clients should read next_page_token first and fall back to nextPageToken only for compatibility routes.

traversal

PAGE_TOKEN=""
while true; do
  URL="$OWLETTE_API_URL/api/roosts?siteId=$SITE_ID&page_size=25"
  if [ -n "$PAGE_TOKEN" ]; then
    URL="$URL&page_token=$(printf %s "$PAGE_TOKEN" | jq -sRr @uri)"
  fi

  PAGE="$(curl -fsS "$URL" -H "Authorization: Bearer $OWLETTE_API_KEY")"
  echo "$PAGE" | jq '.roosts[]'

  PAGE_TOKEN="$(echo "$PAGE" | jq -r '.next_page_token // .nextPageToken // ""')"
  [ -z "$PAGE_TOKEN" ] && break
done

Rules:

• Preserve the cursor exactly.
• Do not use cursor values as stable IDs.
• Do not assume offset semantics.
• Reapply the same filters when requesting the next page.
• Stop when the next token is empty.

GET /api/roosts/{roostId}/versions/{versionRef}/files currently uses an integer offset internally, so operators may see numeric-looking page tokens when debugging that route. Client code must still treat those tokens as opaque cursors: store and round-trip the returned token unchanged, and do not calculate, increment, or infer positions from it.

compatibility exceptions

Most public list routes now expose canonical page_size, page_token, and next_page_token. The remaining compatibility shapes are intentional during preview:

The rendered endpoint reference at /docs/api is the source of truth for each operation's request parameters and response envelope.

related errors

Pagination validation failures use the shared problem envelope:

{
  "type": "https://owlette.app/problems/validation-failed",
  "title": "validation failed",
  "status": 400,
  "detail": "page_size must be a positive integer",
  "code": "validation_failed",
  "errors": {
    "query.page_size": ["must be a positive integer <= 100"]
  },
  "docsUrl": "https://owlette.app/docs/api/errors#validation_failed",
  "requestId": "req_01HYCAM5T4P9R1S3U7V8W0X2Y4"
}

See errors.md for the full envelope contract.