Responses and pagination

Parse JSON responses

Successful JSON responses wrap the result in data. Paginated results also include meta:

{
  "data": [],
  "meta": {
    "page": 1,
    "totalPages": 2,
    "nextPage": "/shows/pages/2"
  }
}

Fields use camelCase; kind and enum values use snake_case. Fields vary by resource: consult the endpoint examples. YAML routes return text with Content-Type: application/yaml; charset=utf-8.

Follow pagination

Request meta.nextPage exactly as returned. Stop when it is null; do not add page query parameters.

Results	First page	Page size	Ordering
Entity indexes	Family root, such as /shows	Up to 10,000	Mediux ID ascending
Activity feeds	/feeds/sets or /feeds/assets	Up to 100	Newest activity first

Feed continuation paths belong to a snapshot. On 410 feed_snapshot_expired, restart at the feed root. Each visible Set or Asset has one current entry; Asset replacement entries include the prior ID and ordered replacement chain, without download URLs. Removed content disappears from feeds. Metadata-only edits and removals do not create activity.

Handle errors

Mediux errors contain a stable error.code and a readable message:

{
  "data": null,
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found."
  }
}

Status	What to do
400	Check the path, identifier, and query string.
404	The requested public resource was not found.
405	Use GET or HEAD.
410	Restart an expired feed at its root.
503	Retry later; respect Retry-After when present.

Check the HTTP status before parsing JSON: traffic protection and infrastructure errors may use a different response format. Protected operations use a separate error format and recovery process.

Use cache validators

Keep the opaque ETag and send it in If-None-Match on subsequent requests. An unchanged response returns 304 Not Modified without a body; reuse your stored response.

Response	Browser cache	Edge cache
Entity, Set, group, index, or YAML success	300 seconds	One year
Activity-feed success	60 seconds	60 seconds
Not found or temporarily unavailable	no-store	no-store

These policies do not use stale-while-revalidate. Public data updates asynchronously; follow the response’s cache headers.

Browser requests

Cross-origin GET and HEAD requests are supported without credentials. OPTIONS preflight is handled automatically. Browsers can read ETag and Retry-After response headers.