Pagination and success shapes

Most of this API answers a list as { "data": [...], "next_cursor": ... }, but not all of it does, and this page says which is which rather than describing a uniformity that is not there. The table below is generated from the specification, so it cannot describe a shape the API does not return.

The three success shapes

A paged list

{ "data": [ ... ], "next_cursor": "..." | null }

Walk it: pass next_cursor back as cursor and stop when it is null.

22 of the 215 operations answer it: GET /v1/pages, GET /v1/inquiries, GET /v1/posts, GET /v1/inbox, GET /v1/leads, GET /v1/referrals/programs, GET /v1/referrals/programs/{id}/partners, GET /v1/referrals/programs/{id}/commissions, GET /v1/referrals/programs/{id}/payouts, GET /v1/referrals/programs/{id}/tax-forms, GET /v1/referrals/broadcasts/{id}/referrers, GET /v1/referrals/imports/{id}/invites, GET /v1/referrals/programs/{id}/entries, GET /v1/referrals/programs/{id}/codes, GET /v1/referrals/programs/{id}/invites, GET /v1/referrals/programs/{id}/privacy-requests, GET /v1/referrals/programs/{id}/links, GET /v1/referrals/programs/{id}/referrers, GET /v1/referrals/programs/{id}/grants, GET /v1/auth/key/workspaces, GET /v1/logs/agent-calls, GET /v1/logs/audit.

A whole list

{ "data": [ ... ] }, or { "data": [ ... ], "next_cursor": null }

Short by nature, and never paged. There is nothing to walk; next_cursor, where it appears at all, is always null.

20 of the 215 operations answer it: GET /v1/keys, GET /v1/pages/{slug}/links, GET /v1/inquiries/{id}/messages, GET /v1/webhooks/events, GET /v1/webhooks, GET /v1/webhooks/{id}/deliveries, GET /v1/accounts, GET /v1/automations, GET /v1/referrals/programs/{id}/payout-providers, GET /v1/referrals/payouts/{id}/invoices, GET /v1/referrals/domains, GET /v1/referrals/programs/{id}/broadcasts, GET /v1/referrals/programs/{id}/imports, GET /v1/referrals/programs/{id}/library, GET /v1/referrals/programs/{id}/link-hosts, POST /v1/referrals/programs/{id}/link-hosts/check, GET /v1/referrals/programs/{id}/contests, GET /v1/referrals/programs/{id}/rewards, GET /v1/referrals/programs/{id}/groups, GET /v1/referrals/programs/{id}/flags.

A single object

The resource itself, unwrapped.

Creates, reads, updates and deletes all answer the object. Nothing in this API answers 204, so a delete has a body too.

Everything else: 173 of the 215 operations.

Cursors

GET /v1/pages, GET /v1/inquiries, GET /v1/posts, GET /v1/inbox, GET /v1/leads and the referral lists (programs, partners, commissions, payouts) are cursor-paginated, newest first — /v1/pages by created_at, /v1/inquiries by last_message_at, /v1/posts by when the post is scheduled, /v1/inbox by when the item arrived, a program's partners by when they applied. Each endpoint's cursor belongs to that endpoint and encodes a position in its own ordering; passing one to the other is not meaningful and its result is not defined.

GET /v1/inquiries?limit=100
  → { "data": [...100 items...], "next_cursor": "MjAyNi0wMy0w..." }

GET /v1/inquiries?limit=100&cursor=MjAyNi0wMy0w...
  → { "data": [...41 items...], "next_cursor": null }

next_cursor is null when you have reached the end. Treat the cursor as opaque and pass it back unmodified.

The first page of a list — answers 200

limit is clamped rather than refused. Pass next_cursor back as cursor for the next page, and stop when it is null.

curl "https://api.boltclaw.ai/v1/pages?limit=50" \
  -H "Authorization: Bearer bc_live_EXAMPLExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

const res = await fetch("https://api.boltclaw.ai/v1/pages?limit=50", {
  headers: {
    Authorization: `Bearer ${process.env.BOLTCLAW_KEY}`,
  },
});

// 200
const data = await res.json();

Cursors, not page numbers, and this matters if you are reading messages. With numbered pages, a message arriving while you are on page 2 pushes every older message down one place — so page 3 repeats one row and drops one off the end without telling you. A cursor names the exact row you stopped at, so the next page starts precisely where the last one ended, whatever arrived in the meantime. New messages are not missed; they are simply newer than your walk, and you collect them on the next poll with since.