REST API

REST API reference

Base URL: https://recallradar-api.vercel.app. OpenAPI schema at /v1/openapi.json.

Authentication

Pass your API key as a Bearer token in the Authorization header. Keys are prefixed recallradar_live_. Unauthenticated requests return a sample-scoped subset and are rate-limited.

Authorization: Bearer recallradar_live_sk_…

Pagination

All list endpoints use keyset pagination (opaque cursor). Pass the next_cursor from one response as the cursor param of the next request.

has_more: true — more pages exist
next_cursor: null — last page
Default page size: 25. Max: 200.

Errors

Errors follow RFC 9457 (Problem+JSON). Content-type: application/problem+json.

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json

{
  "type": "https://recallradar.vercel.app/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Valid Bearer token required."
}

Status	Problem type	Meaning
400	/problems/bad-request	Invalid query parameters
401	/problems/unauthorized	Missing or invalid token
404	/problems/not-found	Recall ID does not exist
429	/problems/rate-limited	Rate limit exceeded
500	/problems/internal	Server error

Conditional GETs (ETag)

Every recall document response includes an ETag header. Pass it as If-None-Match to get a 304 Not Modified when nothing has changed — useful for polling the full dataset efficiently.

Endpoints

GET/v1/recallsoptional — anon returns sample-scoped subset

Search & list recall notices

Returns a paginated list of recall notices. All filters are optional and combinable.

Query parameters

Name	Type	Description
q	string	Full-text search across title, summary, hazard and remedy text.
authority	enum	cpsc \| eu-safety-gate \| health-canada \| gov-uk-opss \| accc
jurisdiction	string	ISO country/region code, e.g. US, DE, CA.
category_code	string	Unified category slug, e.g. toys, electronics, childcare.
hazard	string	Filter on hazard_types[] values.
manufacturer	string	Party name substring match (role=manufacturer or distributor).
published_from	ISO 8601 date	Lower bound on published_at.
published_to	ISO 8601 date	Upper bound on published_at.
limit	integer	Page size. Default 25, max 200.
cursor	string	Opaque keyset cursor from previous response next_cursor.
count	boolean	Set count=true to include total_count in response (costs one extra query).

Example request

curl "https://recallradar-api.vercel.app/v1/recalls?q=tip-over&authority=cpsc&limit=5" \
  -H "Authorization: Bearer recallradar_live_…"

Example response

{
  "data": [
    {
      "id": 1,
      "title": "7-Drawer Dressers Recalled…",
      "authority": "cpsc",
      "jurisdiction": "US",
      "is_recall": true,
      "risk_level": null,
      "category_code": "household",
      "hazard_text": "The dresser can tip over…",
      "remedy_text": "Stop using and contact…",
      "published_at": "2026-05-01",
      "source_record_url": "https://www.cpsc.gov/Recalls/2026/…",
      "_provenance": { "title": { "source": "cpsc", "source_url": "…" } }
    }
  ],
  "next_cursor": "eyJpZCI6NX0",
  "has_more": true
}

GET/v1/recalls/:idoptional

Get a single recall notice

Returns the full recall document for the given numeric ID, including all provenance fields, products, and parties.

Example request

curl "https://recallradar-api.vercel.app/v1/recalls/1" \
  -H "Authorization: Bearer recallradar_live_…"

Example response

{
  "id": 1,
  "title": "7-Drawer Dressers Recalled…",
  "authority": "cpsc",
  "products": [{ "name": "Hasuit 7-Drawer Dressers" }],
  "parties": [{ "name": "Shenzhen DUOMENGDUO…", "role": "distributor" }],
  "source_record_url": "https://www.cpsc.gov/Recalls/2026/…",
  "_provenance": { … }
}

GET/v1/sourcesnone

List ingested source authorities

Returns the five ingested source authorities with their code, description, homepage, and licence.

Example request

curl "https://recallradar-api.vercel.app/v1/sources"

Example response

{
  "data": [
    {
      "code": "cpsc",
      "description": "US CPSC Recalls API",
      "homepage": "https://www.cpsc.gov",
      "license": "us-pd",
      "redistributable": true
    }
    …
  ]
}

GET/v1/coveragerequired — paid tier

Coverage statistics (paid)

Returns per-authority and per-category counts, date ranges, and field-fill rates. Requires a paid API key.

Query parameters

Name	Type	Description
authority	enum	Filter to a single authority.
category_code	string	Filter to a category.

Example request

curl "https://recallradar-api.vercel.app/v1/coverage" \
  -H "Authorization: Bearer recallradar_live_…"

Example response

{
  "authorities": [
    {
      "code": "cpsc",
      "count": 12045,
      "earliest": "1974-01-15",
      "latest": "2026-06-15",
      "field_fill": { "hazard_text": 0.98, "category_code": 0.91 }
    }
    …
  ]
}