Rate limits, pagination and versioning

Each API key may send a fixed number of requests per minute. The number comes from the account’s plan, and every key gets its own allowance; keys do not share one.

Only the plans marked “Included” can call the REST API, so in practice a REST key has 120 requests a minute. The other rows apply to the same keys used with AI assistants. GET /me reports the figure for the key you are using, in rateLimit.requestsPerMinute.

Headers

Going over

The request is refused with 429. Wait RateLimit-Reset seconds and send it again; nothing was done, so repeating it is safe.

{
  "success": false,
  "message": "API rate limit exceeded. Retry after the window resets — see the RateLimit-Reset header."
}

There are no separate daily or monthly request quotas on the API. Plans do limit how many cards and QR codes an account may hold, which shows up as 403 limit_exhausted_cards or 403 limit_exhausted_products, not as a 429.

List endpoints return one page at a time, newest first, in this envelope:

{
  "object": "list",
  "data": [
    "…"
  ],
  "pagination": {
    "total": 240,
    "limit": 25,
    "offset": 0,
    "hasMore": true
  }
}

To read everything, raise offset by limit until hasMore is false:

// Read every card, one page at a time.
const cards = [];
for (let offset = 0; ; offset += 100) {
  const res = await fetch(`https://api.qrbold.com/api/public/v1/cards?limit=100&offset=${offset}`, {
    headers: { Authorization: `Bearer ${process.env.QRBOLD_API_KEY}` },
  });
  if (!res.ok) throw new Error(`QRBold API ${res.status}`);
  const page = await res.json();
  cards.push(...page.data);
  if (!page.pagination.hasMore) break;
}
console.log(`${cards.length} cards`);

• A limit over 100 answers 422; it is not quietly reduced.
• There are no cursors. Paging is by offset only.
• Because lists are newest first, a record created while you are paging shifts later pages by one. For a full export, de-duplicate by id.
• Archived items are left out of lists unless you ask for status=archived.

The first page of cards:

curl "https://api.qrbold.com/api/public/v1/cards?limit=25&offset=0" \
  -H "Authorization: Bearer $QRBOLD_API_KEY"

An idempotency key lets you repeat a write safely. Send any unique string in the Idempotency-Key header of a POST, PATCH or DELETE:

Idempotency-Key: 6f4e9d3c-7e3c-4b91-a8ab-123456789abc

• The header is optional, and recommended on every write.
• Keys belong to the API key that sent them. Two API keys can use the same value without clashing.
• A UUID is the usual choice.

The version is part of the path: /api/public/v1. v1 is the current and only version. There is no version header and no dated versions.

What can change inside v1

Removing a field, renaming one, changing a type or making an optional field required would be a breaking change and belongs in a new version path.

QRBold does not currently publish an API changelog or a deprecation schedule. These pages were last checked against the API on 2026-10-09. Where the API’s behaviour is irregular today, it is documented as it is; see responses that break the pattern.