Pagination, Filtering & Sorting

Overview

Endpoints that return a list of records (for example GET /public/v1/participants) return results in pages and accept query parameters to filter, sort and expand the data. This page explains the conventions shared across those endpoints. For the filters, sorts and includes available on a specific endpoint, check the interactive reference.

Response shape

List responses wrap the records in a data array and include a meta object describing the current page:

{
  "data": [
    { "id": "9ee9dc30-c869-4fb5-9871-b32850e68cad", "name": "Edd Romaguera" }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 94,
    "allowed_sorts": ["name", "created_at"]
  }
}

• current_page / last_page — the page you're on and the total number of pages.
• per_page — how many records are returned per page.
• total — the total number of matching records.
• allowed_sorts — the fields you're allowed to sort this endpoint by.

Pagination

Control paging with the page query parameters:

# Second page, 50 records per page
curl "https://api.app.astalty.com.au/public/v1/participants?page[number]=2&page[size]=50" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

To page through everything, keep requesting page[number] until it reaches meta.last_page.

Filtering

Narrow a list with filter[...] parameters. The available filters differ per endpoint — the interactive reference lists them for each one. Some filters accept multiple comma-separated values.

# Active participants only
curl "https://api.app.astalty.com.au/public/v1/participants?filter[status]=active" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Sorting

Sort a list with the sort parameter, using a field name from meta.allowed_sorts. Prefix the field with a minus sign (-) to sort in descending order, and comma-separate multiple fields.

# Newest first
curl "https://api.app.astalty.com.au/public/v1/participants?sort=-created_at" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"