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.