> ## Documentation Index > Fetch the complete documentation index at: https://docs.paylead.fr/llms.txt > Use this file to discover all available pages before exploring further. # API conventions > The conventions every Program API endpoint shares: formats, pagination, sorting, filtering, and error responses. The pages in this tab document every endpoint of the [Program](/glossary#program) API at the latest Platform version. They are generated from the Paylead OpenAPI specification, so they describe the contract the API serves today. Endpoints are grouped by domain. Each operation lists its parameters, its request and response schemas, and an interactive **Try it** console. ## Before you call an endpoint Three things apply to every request, and each has its own page. | Concern | Where | | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | A bearer access token, exchanged from your API client credentials (the exchange call itself authenticates with HTTP Basic) | [Authentication](/program/user-journey/authentication) | | The mandatory `X-Api-Version` header | [Versioning](/program/user-journey/versioning) | | The base URL, keyed by the `programRef` issued to your Program | [Environments](/program/user-journey/environments) | ## Request and response conventions These hold across every domain and every operation. | Convention | Rule | Example | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | Property names | `snake_case`, never camelCase | `created_at`, `max_eligible_amount` | | Path parameters | `snake_case` | `/perks/consumers/{consumer_id}/rewards` | | Media type | `application/json` on every request body and on every response that carries a body. Throttling and gateway responses are raised before the application and may not be JSON. | `Content-Type: application/json` | | Timestamps | RFC 3339, in UTC, always `Z`-suffixed | `2026-07-15T10:30:00Z` | | Calendar dates | `YYYY-MM-DD`, no time part | `1990-05-15` | | Identifiers Paylead generates | UUID for the resources the API creates. References Paylead issues (`programRef`, a [Segment](/glossary#segment) reference) and identifiers relayed from the PSP are opaque strings. | `9f1c4a2e-5d3b-4e8a-9c07-1f2b3d4e5f60` | | Identifiers you supply | Opaque strings you choose and keep stable | `bank-user-1234` | ## Listing collections ### Pagination Collection endpoints take the same two query parameters. | Parameter | Type | Default | Range | | ---------- | ------- | ------- | ------------- | | `page` | integer | `1` | `1` and above | | `per_page` | integer | `50` | `1` to `1000` | Every paginated response carries the same envelope: ```json theme={null} { "items": [], "meta": { "page": 1, "per_page": 50, "total": 137 } } ``` `items` and `meta` are always present. `total` counts the records matching your filters, not the records on the page, so the number of pages is `total` divided by `per_page`, rounded up. Walking a collection with a large `per_page` costs fewer requests than many small pages, which is what [Rate limits & Caching](/program/user-journey/rate-limits) asks you to do. ### Sorting Where an endpoint supports ordering, it exposes a single `sort` query parameter. Prefix the field with `-` to sort descending: ```http theme={null} GET /perks/consumers/{consumer_id}/rewards?sort=-executed_at ``` The accepted values are a closed list, different for each endpoint, and some endpoints apply a default order when you omit the parameter. Both are on the operation page. ### Filtering Filters are query parameters named after the field they match. Three patterns recur. | Pattern | Meaning | Example | | -------------------------- | -------------------------------------------------------------------------------- | -------------------------------------- | | `field` | Matches the field directly. String filters are case-insensitive partial matches. | `name=coffee` | | `relation__field` | Reaches a field through a related resource | `brand__name=coffee` | | `field__gte`, `field__lte` | Bounds a range, inclusive | `created_at__gte=2026-07-01T00:00:00Z` | Different filters combine with `AND`. A filter that accepts several values, such as `type` on [Rewards](/glossary#reward), matches any of them. Each operation page lists the ones it accepts. ## Error responses Failures raised by the application return the same problem-details envelope, whatever the endpoint. Throttling and gateway responses can arrive without it, so branch on the HTTP status first. The status codes, the Paylead error codes and the retry rules are on [Errors](/program/user-journey/errors); throttling and caching are on [Rate limits & Caching](/program/user-journey/rate-limits). ## What's next Why Paylead ships no SDK, what the specification is safe to use for, and how to read its sample values. Browse every published version and download the raw OpenAPI specs.