# List Endpoint Conventions

Every list endpoint (`GET /v1/programs`, `GET /v1/programs/{program_uuid}/entities`, `GET /v1/checks`, etc.) shares the same pagination, filtering and sorting query parameters. The per-operation reference only documents the filters and sort fields specific to that resource.

## Pagination

- `page` selects the page number (1-based; default `1`).
- `per_page` sets the page size (default `30`, maximum `500`).
- The response envelope includes a `meta` block with `current_page`, `per_page`, `total` (total matching rows across all pages) and `last_page`.

```
GET /v1/programs/9c3e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f/entities?per_page=100&page=2
```

Sending `per_page` larger than 500, or `page` smaller than 1, returns `400 Bad Request`.

## Filtering

Filters use the `filter[key]=value` syntax. The supported filter keys are listed per endpoint; unknown keys are ignored.

```
GET /v1/checks?filter[outcome]=warning&filter[program_uuid]=9c3e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f
```

Filters that target a UUID (a program, entity, parent check, user, API key, and so on) return an empty page (`data: []`, `meta.total: 0`) when the UUID is unknown or belongs to a different account - they do not return `404`. This is the same response as a filter that legitimately matches no rows.

Boolean filters such as the top-level `?archived=true` accept any of `true`/`false`, `1`/`0`, or the string forms `"true"`/`"false"` interchangeably.

## Sorting

The `sort` query parameter selects the order. Prefix the field name with `-` for descending order:

```
GET /v1/programs?sort=program_name    # A-Z by name
GET /v1/programs?sort=-created_at     # newest first
```

Each endpoint documents the sort fields it supports. The default sort is the one most useful for the resource - normally `-created_at` or `-checked_at`.

## Date-range filters

List endpoints that accept a date range use a `..._from` / `..._to` pair (or `checked_after` / `checked_before` on the checks endpoints). Both bounds are inclusive and accept ISO 8601 timestamps.