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.

Account endpoints

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.

FDA Recall Intelligence endpoints

GET /v1/recalls/lookup?code=…

One code, every exact interpretation: GTIN/UPC/UDI (check-digit verified), NDC, lot, serial and model. Returns up to 100 matching recalls, newest first, with matched_on, plus total_matches and truncated; when truncated, page through every match with the /v1/recalls filters listed in complete_results. Lot, serial and model codes ignore internal spaces.

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. A package code (any hyphenated layout or 11 digits) matches that package or a recall of its whole product; a product code (4-4, 5-3, 5-4) matches the product and all its packages.
`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/recalls/stats

Public coverage counts and last refresh time.

FDA 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": "…" }
}

Derived FDA 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.

Consumer product recall endpoints

CPSC and Health Canada notices in one schema. Same key and allowance. Dataset page: /product-recalls.

GET /v1/product-recalls/lookup?code=…

Every notice that names one model number or UPC/EAN/GTIN (check-digit verified), with matched_on, total_matches, truncated and interpreted_as.

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

GET /v1/product-recalls

Filters (AND): gtin, model, agency (CPSC|HC), hazard, remedy, facet, category, manufacturer_country, firm, q, linked, from, to, changed_since, limit (≤100), cursor, include=raw. Newest first.

GET /v1/product-recalls/{id}

One notice, e.g. /v1/product-recalls/cpsc-25203 or /v1/product-recalls/hc-77184, with linked_notices (declared citations only). With include=raw, raw is the source record without contact text and images, and raw_redaction names the withheld fields and gives the SHA-256 of raw as returned; provenance.raw_sha256 stays the digest of the stored original.

GET /v1/product-recalls/stats

Public notice counts per agency, identifier counts, declared links and the last successful sync per source. Not counted.

Full field and enum reference: llms-full.txt and the OpenAPI description.

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"}}.