REST API · keyset pagination · JSON in, JSON out
Read-only REST access to the full dataset. Bearer-token auth, keyset pagination, RFC 9457 errors, and ETag caching. Paid plans include API access; unauthenticated requests are scoped to the free response fixture.
API response fixture — no purchase
The keyless endpoint and free key use a small response fixture for integration testing. They are not the 150-record evaluation sample delivered by email and should not be searched as if they represented full coverage.
Keyless — call the API fixture endpoints with no token at all. Add ?sample=1 explicitly; a request without a token is scoped to this fixture:
# list records
curl "https://api.recallradar.dev/v1/recalls?sample=1&limit=5"
# fetch one record — use any id from the list above
curl "https://api.recallradar.dev/v1/recalls/{id}?sample=1"Free key — sign in at the portal for a recallradar_live_… token scoped to the API preview fixture with a higher daily limit (5,000/day vs. 2,000/day per IP keyless).
Base URL and versioning
https://api.recallradar.dev/v1URL prefix is versioned. v1 is supported for the lifetime of every snapshot it shipped under, plus the following one. Breaking changes ship under a new prefix; non-breaking additions (new optional fields, new endpoints) remain on the same version.
Authentication
One bearer token per customer, scoped to the organisation. Pass it in the Authorization header:
curl "https://api.recallradar.dev/v1/recalls/{id}" \
-H "Authorization: Bearer recallradar_live_····"Endpoints
GET /v1/recalls
Filtered list, keyset-paginated. The envelope is data, has_more, and an opaque next_cursor — pass it back as ?cursor= for the next page. An exact total is returned only with ?count=true (best-effort, slower).
GET /v1/recalls?limit=2
→ 200 OK
{
"data": [ { "id": 1, ... }, { "id": 2, ... } ],
"has_more": true,
"next_cursor": "eyJhIjoxNjc4fQ"
}GET /v1/recalls/{id}
Full record by ID, including the _provenance subtree for every populated field. No separate call required — every record response carries inline provenance.
Pack examples
These examples reflect the workflows buyers naturally test first, from search and record retrieval to source inspection.
Search strict recalls
Search authenticated production access for strict recall records.
curl "https://api.recallradar.dev/v1/recalls?q=Galmet%20ColdGal%20Brushable%20Paint&is_recall=true&limit=5" \
-H "Authorization: Bearer recallradar_live_····"Fetch one safety notice
Inspect one safety notice with classification, hazards, remedy text, and provenance.
curl "https://api.recallradar.dev/v1/recalls/57500" \
-H "Authorization: Bearer recallradar_live_····"List authorities
Inspect the source authorities and licence facts behind the delivered dataset.
curl "https://api.recallradar.dev/v1/sources" \
-H "Authorization: Bearer recallradar_live_····"Rate limits
Paid tier: 60 requests/second per token, 50,000 requests/day — enterprise agreements lift these. Free key: 2/second, 5,000/day. Keyless sample: 2/second, 2,000/day per IP. Headers on every response:
X-RateLimit-Limit: 2000
X-RateLimit-Remaining: 1997
X-RateLimit-Reset: 1716624000
RateLimit-Policy: "rps";q=60;w=1, "daily";q=50000;w=86400
RateLimit: "rps";r=57;t=1, "daily";r=49873;t=64802Both the legacy X-RateLimit-* headers and the IETF RateLimit / RateLimit-Policy structured fields are emitted. On a breach the response is 429 with Retry-After.
Error semantics
Errors follow RFC 9457 (application/problem+json) with a stable machine-readable code and a request_id on every response. HTML is never returned.
404 → {
"type": "https://recallradar.dev/docs/api#errors/not_found",
"title": "Not found",
"status": 404,
"detail": "Record 99999 does not exist.",
"code": "not_found",
"request_id": "req_····"
}
// codes: unauthenticated 401 · scope_exceeded 403 · not_found 404
// rate_limited 429 (+retry_after_ms) · validation 400 · internal 500Caching & request IDs
Single-resource reads carry a strong ETag and Cache-Control; send If-None-Match to get a 304 Not Modified and save bandwidth. Every response carries X-Request-Id — quote it in support tickets.
OpenAPI
A machine-readable OpenAPI 3.1 description is served (unauthenticated) at https://api.recallradar.dev/v1/openapi.json — generate a typed client, import into Postman, or render interactive docs.
Data freshness
The API serves the live rolling database. Corrections and new coverage are published as they arrive. Snapshot-tier customers receive versioned Parquet/CSV/SQLite bundles when releases ship; the API tier reflects the DB as it stands at query time.
Related evaluation guides
Connect this diligence evidence to the relevant integration decision.