Pagination and filtering
How BuildBase lists page with page and limit, the filters each list takes, and the filter, sort and projection syntax of the organization API.
In short
A list can be long, so BuildBase answers it a page at a time. You ask for a page number and how many items you want on it, and the answer says whether there is another page. Most lists also take filters, such as status=active, that narrow what comes back.
Paging a list in the app API
The examples call the cloud, https://api.console.buildbase.app; a self-hosted install uses its own base URL. App API lists that page take two query parameters:
| Parameter | Type | Allowed | What it does |
|---|---|---|---|
page | integer | 1 or more; at most 10000 on most lists | Which page, starting at 1 |
limit | integer | 1 to 100 | How many items on the page |
curl -s "https://api.console.buildbase.app/api/v1/public/me/orders?page=2&limit=25" \
-H "x-session-id: $BUILDBASE_SESSION_ID"The answer carries the page's items and how to reach the next one; /me/orders, for one, answers docs with page, limit and hasNextPage. Read until the answer says there is no next page:
const base = 'https://api.console.buildbase.app/api/v1/public/me/orders';
let page = 1;
let more = true;
while (more) {
const res = await fetch(`${base}?page=${page}&limit=100`, {
headers: { 'x-session-id': process.env.BUILDBASE_SESSION_ID! },
});
const body = await res.json();
console.log(body);
more = Boolean(body.hasNextPage);
page += 1;
}Each list's reference page says which parameters it takes, their limits, and the names of the fields in its answer. Some lists take neither parameter and answer every row, and a list that did not page before never starts paging by default, so code written against it keeps working (Versioning and changes).
Filtering in the app API
App API lists filter with named query parameters, each listed with its allowed values on the operation's reference page and in the OpenAPI spec. The common ones:
| Parameter | Example | Seen on |
|---|---|---|
status | status=active | Affiliates, subscriptions, bookings, credit holds |
q or search | q=lamp | Items |
from, to | from=2026-11-01&to=2026-11-30 | Bookings, usage logs |
sort | sort=-start | Bookings: start or -start (newest first) |
An id: itemId, programId, orderId... | programId=665f1c2e9b1d4a0012ab34cd | Lists inside a program, an order or an item |
A value outside the allowed set is a 400 that names the field in path.
Paging and filtering the organization API
Organization API lists (/api/blogs, /api/users and their siblings, called with an API key) share one list handler with a richer syntax:
| Parameter | Example | What it does |
|---|---|---|
$page | $page=2 | The page, from 1 |
$limit | $limit=50 | Items per page. Default 10 unless the list sets its own; at most 500 (a larger value is capped) |
filter | filter[published]=true | Match fields. Also accepted as JSON text: filter={"published":true} |
sort | sort[createdAt]=-1 or sort=-createdAt | Order by a field, -1 or - for descending |
projection | projection[title]=1 | Only these fields, 1 to include or 0 to leave out. At most 50 fields |
pagination | pagination=false | Asks for every row: answered with the largest page, 500, and hasNextPage says when there is more |
curl -s -G "https://api.console.buildbase.app/api/blogs" \
-H "Authorization: Bearer $BUILDBASE_API_TOKEN" \
--data-urlencode 'filter[published]=true' \
--data-urlencode 'sort[createdAt]=-1' \
--data-urlencode '$limit=20'The answer is a page object:
{
"docs": [],
"totalDocs": 0,
"limit": 20,
"page": 1,
"totalPages": 1,
"hasPrevPage": false,
"hasNextPage": false,
"prevPage": null,
"nextPage": null
}A filter may use these operators and no others: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $and, $or, $nor, $not, $exists, $type, $all, $elemMatch, $size, $regex (at most 200 characters) and $options. Another operator, text that is not a JSON object, or a projection that names a hidden field is a 400.
curl -s -G "https://api.console.buildbase.app/api/blogs" \
-H "Authorization: Bearer $BUILDBASE_API_TOKEN" \
--data-urlencode 'filter={"createdAt":{"$gte":"2026-11-01"}}'Next steps
- Rate limits - read a long list without hitting one.
- HTTP API errors - what a refused filter answers.
- Delivering content - read and cache content lists with a key.