Documentation

Getting started with RecallStream

From sign-up to your first API call — everything you need to start monitoring recalls from 31 live government sources.

Getting started

Create a free account — no credit card required — and verify your email address (alert emails only go to verified addresses).
Create your first watchlist: a brand name, supplier name, or keyword. Every incoming recall is matched against it — optionally scoped to a single source. The Free plan includes 1 watchlist (5 on Starter, 50 on Pro).
Matches land in your in-app alerts feed and inbox within minutes of detection. On Starter and above, register a webhook endpoint to receive a signed watchlist.match JSON payload the moment a match fires.
Need the raw feed? Issue an API key from Account settings (Starter and above) and query the REST API below.

API quickstart

The data API lives at https://api.recallstream.com. Authenticate every request with your API key in the X-Api-Key header (or as Authorization: ApiKey rr_…). Keys are shown once at creation — store them like passwords.

Your first request

curl -H "X-Api-Key: rr_your_api_key" \
  "https://api.recallstream.com/recalls?source=cpsc&q=battery&limit=5"

Response

List endpoints return a data array plus a meta envelope for offset pagination:

{
  "data": [
    {
      "id": "…",
      "sourceCode": "cpsc",
      "title": "SureFit Appliances battery packs recalled…",
      "hazard": "Fire",
      "recallDate": "2026-06-28T00:00:00.000Z",
      "brands": ["SureFit"]
    }
  ],
  "meta": { "total": 128, "limit": 5, "offset": 0 }
}

Endpoints

Endpoint	What it returns
GET /recalls	The normalized cross-agency recall feed. Filters: `source`, `q` (free-text), `brand`, `category`, `classification`, `identifier` / `identifierKind` (UPC/NDC/VIN/UDI), `from` / `to` (recall-date range), `limit` (max 100) / `offset`.
GET /recalls/:id	One recall with full detail (hazard, classification, identifiers, source attribution).
GET /recalls/filters	Distinct filter options (sources, brands, categories, classifications) for building UIs.
GET /recalls/vin/:vin	VIN lookup — decodes the vehicle and returns matching NHTSA recalls.
GET /events	Your watchlist-match event log (newest first, cursor pagination) — the same events your webhooks receive.
GET /incidents/:id	Cross-source incident cluster for a recall (“also reported by” siblings). Pro plan and above.

Rate limits & plan quotas

API requests are rate-limited per minute by plan. Exceeding a limit returns HTTP 429 — back off and retry. Creating a resource over your plan’s cap is blocked with an upgrade prompt; nothing you already have is deleted.

Plan	API rate limit	Watchlists	Webhooks & API keys
Free	—	1	—
Starter	120 req/min	5	Included
Pro	300 req/min	50	Included
Business	600 req/min	Unlimited	Included
Enterprise	1,200 req/min	Unlimited	Included

Full plan details are on the pricing page.

Need help?

Check the FAQ, review our data sources & licensing, or contact support — we aim to respond within one business day.

Start free →Contact support