Pagination
Query parameters and response shape for list endpoints.
List endpoints take the same four query parameters.
| Parameter | Default | Notes |
|---|---|---|
page | 1 | 1-indexed |
per_page | 20 | Maximum 100 |
sort | created_at | Field to sort by; varies per endpoint |
order | desc | asc or desc |
A list response carries a pagination block alongside data:
{
"data": [ ... ],
"pagination": {
"total": 150,
"page": 1,
"per_page": 20,
"total_pages": 8,
"has_next": true,
"has_prev": false
},
"meta": {
"request_id": "req_abc123def456",
"timestamp": "2025-01-18T10:30:00Z"
}
}Edge cases
| Case | Behavior |
|---|---|
page beyond the last page | 200 with an empty data array and a correct pagination block |
page less than 1 | 422 VALIDATION_ERROR |
per_page greater than 100 | 422 VALIDATION_ERROR |
per_page less than 1 | 422 VALIDATION_ERROR |
Unknown sort field | 422 VALIDATION_ERROR |
per_page above 100 is rejected, not silently capped. Each endpoint's own
parameter constraints are declared on its route, so the schema on its
generated endpoint page is the source of truth for
what sort accepts.