Envelopes & errors

Every list-returning endpoint uses the same envelope, and every error uses the same shape. Once you handle these two patterns, you can consume any endpoint.

The list envelope

List endpoints return a data array plus a meta block:

{
  "data": [
    {
      "syndrome": "UTI",
      "panel": "UTI with AMR",
      "organism": "Escherichia coli",
      "tested": 540,
      "detected": 322,
      "prevalence_rate": 0.5963,
      "sample_size_tier": "A",
      "is_clinically_reportable": true,
      "ci_lower": 0.5539,
      "ci_upper": 0.6374,
      "vendor_id": "AFC",
      "date_range": { "start": "2026-01-01", "end": "2026-03-31" }
    }
  ],
  "meta": {
    "total": 137,
    "limit": 50,
    "offset": 0,
    "query": { "syndrome": "UTI", "min_tested": 100 },
    "generated_at": "2026-05-29T20:11:04.512Z"
  }
}

The meta block

• total — integer — Total rows available before limit/offset were applied — use it to paginate.

• limit — integer — Page size requested. 0 means "all rows" (no limit).

• offset — integer — Row offset of the first item returned.

• query — object — An echo of the non-default query parameters used to produce this page.

• generated_at — string (ISO 8601) — When the response was produced.

Field reference (prevalence row)

Most data rows share these fields:

Field	Type	Notes
syndrome	string	Syndrome bucket.
panel	string	Panel the rate was computed in.
organism	string	Canonical organism name.
tested	integer	Denominator (specimens tested).
detected	integer	Numerator (detections).
prevalence_rate	float	Fraction in [0,1] (0.152 = 15.2%).
sample_size_tier	"A" | "B" | "C"	See tiers.
is_clinically_reportable	boolean	true for A/B, false for C.
ci_lower, ci_upper	float | null	95% Wilson interval bounds (fractions).
vendor_id	string	The laboratory.
date_range	object	{ start, end } ISO dates (may be null).

Errors

Errors return a consistent envelope with the matching HTTP status code:

{
  "error": "Not Found",
  "detail": "No data for vendor 'XYZ'",
  "status": 404
}

• error — string — Human-readable status phrase (e.g. Bad Request, Not Found).
• detail — string | null — Specific explanation of what went wrong.
• status — integer — The HTTP status code, repeated in the body for convenience.

Common status codes

Code	Meaning	Typical cause
200	OK	Success.
400	Bad Request	Invalid parameter (e.g. unknown sort_by, unsupported upload type).
404	Not Found	No rows match (e.g. unknown vendor/syndrome combination).
422	Unprocessable Entity	Request validation failed.
500	Internal Server Error	Unexpected server error — contact OSPRI.

Tip

A 404 from a report endpoint usually means the filters matched no data, not that the endpoint is wrong. Double-check the vendor ID and syndrome spelling.