APIs and SDKs
Filters, sorting, pagination, and errors
Every list endpoint accepts the same query parameters, and every failed request returns the same error body.
Query parameters
| Parameter | Default | Description |
|---|---|---|
page | 1 | Which page of results to return |
perPage | 30 | How many records per page |
filter | none | A filter expression evaluated server-side |
sort | none | Comma-separated fields; prefix with - for descending |
expand | none | Comma-separated relation fields to include |
fields | all | Limit the fields returned |
Filter operators
| Operator | Meaning |
|---|---|
= | Equal |
!= | Not equal |
> >= | Greater than, greater or equal |
< <= | Less than, less or equal |
~ | Case-insensitive contains |
!~ | Case-insensitive does not contain |
curl -G $PROJECT_URL/api/v1/collections/posts/records \
-H "Authorization: $TOKEN" \
--data-urlencode 'filter=published = true && title ~ "api"' \
--data-urlencode 'sort=-created,title' \
--data-urlencode 'expand=author' \
--data-urlencode 'perPage=50'Only the operators listed above are evaluated by the server. Anything more complex belongs in a view table, an edge function, or the SQL console.
Expanding relations
A relation field stores a record id. Add the field name to expand and the related record is returned under the expand key of each item.
{
"id": "k93jf0s1p2a7b4c",
"title": "Shipping the new API",
"author": "b7s0x1c9k2m4q8f",
"expand": {
"author": { "id": "b7s0x1c9k2m4q8f", "name": "Ada" }
}
}Error format
- 400 for an invalid request body or query
- 401 when no valid token was sent
- 403 when the token is valid but the access rule denies the operation
- 404 when the record, table, or route does not exist
- 429 when the request is rate limited
{
"status": 404,
"message": "The requested resource wasn't found.",
"data": {}
}Pagination guidance
- Keep perPage modest and page through results rather than requesting everything at once.
- Sort by an indexed field so deep pages stay fast.
- Every list response returns totalItems and totalPages, so counts are always available.
The SDKs accept a skipTotal option for compatibility. The Project backend always computes totals, so the option changes nothing today.
Found something wrong on this page?
Fix it yourself. The link below opens this file in GitHub's editor and forks the repository for you if you need one, and your change becomes a pull request without leaving the browser.