API conventions

Versioning

Every endpoint path starts with /v1. Keep the base URL and version in configuration so an environment change does not require code changes.

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 confirm failure. See Errors and retries before you retry an order create.

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.