List endpoints across the API share a common set of query parameters. The exact parameters accepted by any given endpoint are documented on that endpoint — this page explains what they mean and how they interact.
| Parameter | Description |
|---|---|
page | Page number to retrieve. Send it to page the results at all — see below. |
per_page | Records per page. Defaults to 10, capped at 100. Only applies when page is sent. |
Asking for more than 100 records per page is not an error — you get 100.
Pagination is opt-in. A list request that does not carry page returns every matching record as a bare JSON array, and per_page is ignored. Send page and the response becomes a pagination envelope instead:
{
"current_page": 1,
"per_page": 10,
"from": 1,
"to": 10,
"data": [ ... ],
"path": "https://example.rosterfy.com/api/v2/event",
"first_page_url": "https://example.rosterfy.com/api/v2/event?page=1",
"prev_page_url": null,
"next_page_url": "https://example.rosterfy.com/api/v2/event?page=2",
"current_page_url": "https://example.rosterfy.com/api/v2/event?page=1"
}There is no total count and no last-page number: keep requesting pages until next_page_url comes back null.
Each item in data carries an object key with the record's fields and a permissions key describing what the authenticated caller may do with it.
Listings are scoped to what your token may read, silently. A record your token is not entitled to see is simply absent — the list is shorter, and nothing in the response says anything was left out. So a count taken from a listing is a count of what you may read, not of what exists, and two tokens on the same account can legitimately get different totals from the same request. Where a single record would answer 404 (see Errors and status codes), a listing just omits it.
| Parameter | Description |
|---|---|
sort_by | Attribute to sort on. |
sort_order | asc or desc. |
Sortable attributes vary per resource; the endpoint's own documentation lists which are supported.
filter accepts an array of conditions. The filterable attributes differ per resource and are listed on each endpoint.
| Parameter | Description |
|---|---|
with | Include related resources in the response. Relations are not returned unless requested. |
extras | Include computed or derived values that are not stored fields. |
Requesting relations you don't need costs response time on both sides — ask for the narrowest set that satisfies your use case.
_locale returns translatable content in a specific language, e.g. ?_locale=en-US.
A request returns one locale. If your application needs the same records in several languages, make one request per locale and merge client-side. Values that have no translation for the requested locale fall back to the account's default language rather than returning empty.
Some resources are soft-deleted: the record remains retrievable after deletion. By default, deleted records are excluded from responses.
| Parameter | Effect |
|---|---|
with_deleted=1 | Return active and deleted records. |
only_deleted=1 | Return only deleted records. |
only_deleted takes precedence if both are supplied.
Deleted records may carry an is_erased flag. When is_erased is true the record's private fields have been permanently removed under a data-erasure request, and those fields will be empty or null. An erased record cannot be restored to its original state — treat it as a tombstone, not as recoverable data.