Data Foundry

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. Account reads, dataset discovery and coverage stats are not counted.

Allowance and retries

Successful direct data responses and 429 allowance_exhausted responses include the headers below. Browser clients can read them through CORS. Allowances reset at 00:00 UTC on the first day of each month; there are no overage charges.

HeaderMeaning
X-RateLimit-LimitYour direct monthly request allowance.
X-RateLimit-RemainingRequests left in this UTC calendar month.
X-RateLimit-ResetReset time as Unix seconds, not milliseconds.
Retry-AfterOn an exhausted 429 response only: whole seconds to wait until reset.

On 429, wait for Retry-After before retrying data requests unless your plan changes. GET /v1/account checks usage without spending allowance. RapidAPI has separate plans, keys, allowances and reset rules; these direct headers do not describe your marketplace subscription.

Dataset discovery

GET /v1/datasets

No key required. Lists the currently published datasets with their IDs, source terms, fields, limitations, endpoint paths and documentation links. Read each stats_url for live counts and freshness. A withdrawn dataset disappears from the catalog immediately on the next request.

Cross-dataset identifier lookup

GET /v1/lookup?code=…

Check one code across FDA and North American consumer-product recalls in one request. Uses one unit of your direct monthly allowance. Returns results, one entry per requested dataset, with the same data, matched_on, interpreted_as, total_matches, truncated and attribution as that dataset's lookup. Source notices stay separate.

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

Optional datasets=recalls,product-recalls selects unique dataset IDs. Omitting it requests both, including when one is withdrawn; an unavailable requested dataset returns 503 before any direct usage is spent. Select an available subset explicitly, for example datasets=recalls. include=raw requires exactly one explicit dataset; combined raw requests return 400 before direct metering to preserve the existing response memory limit. Evidence verification and redactions are unchanged; raw results are bounded to 10 FDA or 25 consumer-product notices, or 100 per dataset otherwise. The top-level truncated is true if any dataset has more matches.

An empty result means no exact indexed identifier matched in the requested datasets. It does not prove a product is safe or has never been recalled: source notices and extracted identifiers can be incomplete. A model or lot code can identify different products; verify the notice and matched_on before acting.

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.

Source sync status

Both stats endpoints include source_sync, keyed by FDA category (food, drug, device) or product agency (CPSC, HC). Each source has last_successful_sync and latest_attempt. A newer failed or running attempt does not advance the successful clock.

latest_attempt contains status (RUNNING, SUCCEEDED or FAILED), started_at, nullable finished_at, and the attempted window_from/window_to. The most recently created ledger run wins. A source with no runs has null for both fields; a running attempt has no finish time. Error details and artifact locations stay private.

Stats can be cached for ten minutes. A successful window does not establish complete history, an agency's newest publication or an uptime guarantee. FDA checks can cover a historical rolling window. CPSC subwindows are excluded until the whole agency pass completes. Existing top-level successful clocks keep their meaning. Direct stats require no key and spend no direct allowance; RapidAPI stats follow marketplace allowances.

curl -s "https://api.data.aroqon.com/v1/product-recalls/stats" | jq '.source_sync'

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"

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

ParameterMeaning
gtinUPC, EAN, GTIN or UDI-DI. Any length 8–14 with a valid check digit; matched as GTIN-14.
ndcNational 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, modelExact code as printed (case-insensitive).
stateTwo-letter USPS code. Nationwide recalls always match.
countryISO 3166-1 alpha-2 code.
categoryfood, drug or device.
classificationI, II or III.
statusOngoing, Completed, Terminated or Pending.
reason_classUNDECLARED_ALLERGEN, MICROBIAL_CONTAMINATION, FOREIGN_MATERIAL, CHEMICAL_CONTAMINATION, LABELING, POTENCY, STERILITY, CGMP, SPECIFICATION_FAILURE, PACKAGING, TEMPERATURE_CONTROL, DEVICE_MALFUNCTION, SOFTWARE, UNAPPROVED_PRODUCT.
allergenmilk, egg, fish, crustacean_shellfish, tree_nuts, peanut, wheat, soy, sesame.
pathogenlisteria_monocytogenes, salmonella, e_coli, clostridium_botulinum, cronobacter, hepatitis_a, norovirus, cyclospora, bacillus_cereus, staphylococcus, burkholderia, pseudomonas, mold, yeast.
firmSubstring of the recalling firm name.
qFull-text search over firm, product description and reason.
reported_from, reported_toFDA report date bounds, YYYY-MM-DD.
changed_sinceISO timestamp — records whose FDA text changed since then (for incremental sync).
limit, cursorPage size 1–100 (default 25) and the next_cursor from the previous page.
include=rawAdd 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, last successful refresh and per-category source_sync. See source sync status.

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"

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, successful refresh clocks and per-agency source_sync. No direct allowance charge. See source sync status.

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