API conventions

Versioning

The API version is v1, included in every endpoint path. Keep the base URL and version in configuration so you can change environments without changing request code.

When the public API changes, Pulse will record the change in a changelog with any required migration steps.

Pagination

GET /v1/orders uses cursor pagination. The default page size is 20 and the maximum is 100. If you request more than 100, Pulse returns 100 records.

Start without a cursor. For each following page, pass the previous response's meta.next_cursor as cursor. Stop when next_cursor is absent.

Client timeouts

Set finite connection and response timeouts on every API call. A timeout does not mean Pulse rejected the request. For an order create, retry the exact request with the same reference, or look up that reference before you create a new order.

Do not poll an order in a tight loop. Increase the interval after each unchanged response, stop at a terminal status, and use webhooks for lifecycle updates.

Rate limits

Keep API traffic below 60 requests per minute for each API key. Poll an individual order no more than once every five seconds. If the API returns 429 rate_limited, wait 60 seconds before retrying.