API documentation

Base URL https://api.data.aroqon.com. JSON over HTTPS. OpenAPI: https://api.data.aroqon.com/openapi.json.

Authentication

Send your key as Authorization: Bearer rcl_live_… (or X-API-Key). Every authenticated data request counts toward your monthly allowance; when it is spent, requests return 429 until the next UTC month or an upgrade. /v1/account and /v1/recalls/stats are not counted.

Endpoints

GET /v1/recalls/lookup?code=…

One code, every exact interpretation: GTIN/UPC/UDI (check-digit verified), NDC, lot, serial and model. Returns matching recalls with matched_on.

curl "https://api.data.aroqon.com/v1/recalls/lookup?code=05708932072526" -H "Authorization: Bearer $KEY"

GET /v1/recalls

Filter and page through recalls, newest report first. Filters combine with AND.

Parameter	Meaning
`gtin`	UPC, EAN, GTIN or UDI-DI. Any length 8–14 with a valid check digit; matched as GTIN-14.
`ndc`	National Drug Code, hyphenated in any standard layout or as 11 digits; matched as 5-4-2.
`lot, serial, model`	Exact code as printed (case-insensitive).
`state`	Two-letter USPS code. Nationwide recalls always match.
`country`	ISO 3166-1 alpha-2 code.
`category`	`food`, `drug` or `device`.
`classification`	`I`, `II` or `III`.
`status`	`Ongoing`, `Completed`, `Terminated` or `Pending`.
`reason_class`	UNDECLARED_ALLERGEN, MICROBIAL_CONTAMINATION, FOREIGN_MATERIAL, CHEMICAL_CONTAMINATION, LABELING, POTENCY, STERILITY, CGMP, SPECIFICATION_FAILURE, PACKAGING, TEMPERATURE_CONTROL, DEVICE_MALFUNCTION, SOFTWARE, UNAPPROVED_PRODUCT.
`allergen`	milk, egg, fish, crustacean_shellfish, tree_nuts, peanut, wheat, soy, sesame.
`pathogen`	listeria_monocytogenes, salmonella, e_coli, clostridium_botulinum, cronobacter, hepatitis_a, norovirus, cyclospora, bacillus_cereus, staphylococcus, burkholderia, pseudomonas, mold, yeast.
`firm`	Substring of the recalling firm name.
`q`	Full-text search over firm, product description and reason.
`reported_from, reported_to`	FDA report date bounds, YYYY-MM-DD.
`changed_since`	ISO timestamp — records whose FDA text changed since then (for incremental sync).
`limit, cursor`	Page size 1–100 (default 25) and the `next_cursor` from the previous page.
`include=raw`	Add the verbatim FDA record to each result.

curl "https://api.data.aroqon.com/v1/recalls?state=TX&category=food&allergen=peanut&status=Ongoing" -H "Authorization: Bearer $KEY"

GET /v1/recalls/{recall_number}

One recall, e.g. /v1/recalls/H-1331-2026?include=raw.

GET /v1/account

Your plan, this month's usage and allowance.

POST /v1/account/rotate-key

Revokes the presented key and returns a new one.

POST /v1/account/billing-portal

Returns a Stripe billing-portal URL to upgrade, downgrade or cancel.

GET /v1/recalls/stats

Public coverage counts and last refresh time.

Record shape

{
  "recall_number": "D-0123-2026", "category": "drug", "classification": "II", "status": "Ongoing",
  "firm": { "name": "…", "city": "…", "state": "NJ", "postal_code": "…", "country": "United States" },
  "dates": { "initiated": "2026-08-01", "classified": "2026-09-04", "reported": "2026-09-16", "terminated": null },
  "distribution": { "nationwide_us": true, "international": true, "us_states": ["FL","GA"], "countries": ["PA"], … },
  "quantity": { "items": [{ "value": 403200, "unit": "tablets" }], "total": 403200, "unit": "tablets" },
  "codes": { "gtins": [], "ndcs": ["12345-0678-90"], "lots": ["DJ23254"], "expiration_dates": ["2026-11-30"], … },
  "reason": { "classes": ["SPECIFICATION_FAILURE"], "allergens": [], "pathogens": [] },
  "provenance": { "source_url": "https://api.fda.gov/…", "parser_version": "recall-structuring@1", "raw_sha256": "…", "changed_at": "…" }
}

Accuracy

Derived fields come from deterministic parsers over FDA prose. They are conservative — a code is only reported when an explicit marker or a valid check digit supports it — but they can be incomplete. The verbatim FDA text is always included for verification. This is not medical or legal advice; do not rely on it for decisions about medical care.

Errors

400 invalid parameter · 401 missing/unknown key · 403 subscription inactive · 404 not found · 429 monthly allowance spent · 503 temporarily unavailable. Errors are {"error": {"code", "message"}}.