List endpoints paginate. Awardee uses two styles depending on the resource: offset for catalog resources, cursor for high-volume streams. Both cap page_size/limit at 100 and default to 25.
Used by catalog resources like /chatbots, /articles, /products, /objects, /qr-groups. Pages are 1-indexed.
Query parameters
| Param | Type | Default | Cap | Notes |
|---|
page | integer | 1 | — | 1-indexed. |
page_size | integer | 25 | 100 | Number of items per page. |
{
"object": "list",
"total": 137,
"page": 1,
"page_size": 25,
"data": [ /* … */ ]
}
total is the filtered count, so it changes when you pass query filters. Use Math.ceil(total / page_size) for the page count.
curl "https://api.awardee.dev/v1/chatbots?page=2&page_size=50" \
-H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e"
Offset pagination is not stable under concurrent inserts. If new resources are created between page fetches, you may see the same item twice (or skip one) at page boundaries. For high-mutation feeds, prefer cursor pagination — it’s stable.
/conversations, /conversations/{id}/messages, /qr-codes/{id}/scans, /submissions, /articles (when sorted by created_at descending), and similar feeds. Cursors are opaque base64url strings — never parse, predict, or hand-construct one.
Query parameters
| Param | Type | Default | Cap | Notes |
|---|
cursor | string | absent | — | Pass next_cursor from the previous response. Omit on the first page. |
limit | integer | 25 | 100 | Number of items in this page. |
{
"object": "list",
"has_more": true,
"next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0yM1QxMDoxNDozM1oiLCJpZCI6IjFiNGM0ZjVkLTllOGEtN2MzYi0yYTFkLTBmOWU4ZjNhOWQyZSJ9",
"data": [ /* … */ ]
}
has_more is false, next_cursor is null and you’re done.
# First page
curl "https://api.awardee.dev/v1/conversations?limit=100" \
-H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e"
# Subsequent page (paste next_cursor verbatim, URL-encoded)
curl "https://api.awardee.dev/v1/conversations?limit=100&cursor=eyJjcmVhdGVkX2F0Ijoi..." \
-H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e"
Invalid cursors
Tampered or corrupted cursors return:
{
"error": "invalid_cursor",
"message": "Pagination cursor is malformed.",
"request_id": "req_8fK2x9aLp0qR"
}
next_cursor string verbatim, including any trailing = characters (URL-encode them — %3D).
Which style does an endpoint use?
The OpenAPI spec is authoritative. As a heuristic: anything that emits webhook events at high volume (conversation.created, qr_code.scanned, page.submission.created, etc.) uses cursor pagination. Everything else uses offset. 
