Pagination & response headers

Navigate large catalog collections predictably and retain the metadata needed for caching, support, and reproducibility.

Offset pagination

Collection endpoints accept limit and offset. Results use a stable envelope with data and meta.

limit

integer

Maximum number of records to return (1–500).Default: 100

offset

integer

Zero-based number of matching records to skip.Default: 0

cURL

curl "https://api.use-allm.com/v1/deployments?provider=openai&limit=2&offset=0" \
  -H "Authorization: Bearer $ALLM_API_KEY"

Pagination metadata

JSON

{
  "data": [/* deployments */],
  "meta": {
    "total": 38,
    "limit": 2,
    "offset": 0,
    "has_more": true
  }
}

To request the next page, set offset to the current offset + limit. Stop when has_more is false.

Response headers

x-request-id: Unique request identifier. Include it in logs and support requests.
x-allm-catalog-release: Immutable identifier of the catalog snapshot used to answer the request.
ETag: Content fingerprint used for cache validation.
Retry-After: Seconds to wait before retrying a rate-limited request; present on 429 responses.

Conditional requests

Store the ETag with cached catalog responses and send it back through If-None-Match. Treat a new catalog release as a signal to re-evaluate persisted decisions, not as proof that every record changed.