Limits

What the API bounds today, what it does not, and how fresh its data is.

Page size#

A collection returns 1 to 200 items per page. limit defaults to 50, and a larger value than 200 is capped at 200 rather than refused. Every page is bounded, so no single request reads a whole ledger. Pagination covers the rest.

Rate limits#

Reads have no rate limit. Writes are limited to 30 a minute for each key, counted on each server instance, so a burst can now and then get a little past it. Over the limit, a write answers 429 rate_limited with Retry-After: 60. No endpoint returns 503 today, but unavailable is a defined error code: write your client to back off on both, and it keeps working if a limit is added to reads.

• On a 429, wait at least as long as the Retry-After header says, in seconds, before you try again.
• On a 503, retry with exponential backoff.

Poll no more often than you need to. To react to each new ledger entry, webhooks push it to you, so you do not need to poll the ledger quickly.

Request bodies#

A write's body is one JSON object of at most 64 KB. A body that is larger, is not JSON, or has a field the operation does not take answers 400 invalid_request, and nothing is written. To make a retry safe, send an Idempotency-Key: Retrying safely explains it. A payee link takes none: a repeat makes a new link, which replaces the first.

Keys and endpoints per workspace#

Freshness#

Data is read live on each request: responses are not cached, so an invoice, a decision or a payment is visible on the next request after it is recorded.

Two endpoints report on the latest cycle rather than on this moment:

• Treasury's obligations come from the latest completed cycle snapshot, and are null until one exists.
• Insights reports the telemetry of recent cycles, transfers and screenings.

Response shapes#

Every endpoint answers with the documented envelope: data, plus page for a collection, or error. New fields can be added to v1 responses, so ignore fields you do not know rather than rejecting the response. A field is not removed from, or changed in, v1 without an entry in the changelog.