Docs / Create a watchlist

Create a watchlist

Last updated 2026-11-13

Create a watchlist of makes, models, brands, categories and UPCs.

POST/v1/watchlists · API key required

A watchlist is the list of things you want to hear about. Add at least one of makes, models, brands, categories or upcs (up to 10 values in all on a free key). When a recall that mentions any of them is added or changed, the watchlist's webhook is sent a message.

A match means the notice mentions your value. It never says that your item is or is not affected: your customers should read the official notice and compare lot codes and dates.

Parameters

Name	In	Required	Description
`name`	body	yes	A name for the watchlist, 1 to 60 characters. Example: `My brands`
`makes`	body	no	Vehicle makes, as on checkrecalls.org (for example Honda). Matches recalls that list that make. Example: `["Honda"]`
`models`	body	no	Vehicle models. Matches the model name exactly (Civic matches Civic, not Civic Type R). Example: `["Civic"]`
`brands`	body	no	Brand or company names. Matches whole words in the notice title or the issuing company. Example: `["Graco"]`
`categories`	body	no	Categories as used by /v1/search: vehicle, motorcycle, rv, car_seat, tire, equipment, other_vehicle, consumer_product, food, dietary_supplement, pet_food, cosmetic, drug, medical_device. Example: `["car_seat"]`
`upcs`	body	no	Barcode numbers (UPC-A, EAN-13, GTIN-14, with a correct check digit). Matches notices that list the barcode. Example: `["036000291452"]`
`webhook_id`	body	no	The id of one of your webhooks. Matches are sent there. Example: `wh_3f9a1c07b2d4`

Request

curlJavaScriptPython

curl -X POST https://recalldb.app/v1/watchlists \
  -H "Authorization: Bearer $RECALLDB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My brands", "brands": ["Graco"], "categories": ["car_seat"], "webhook_id": "wh_3f9a1c07b2d4"}'

const res = await fetch('https://recalldb.app/v1/watchlists', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.RECALLDB_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({"name": "My brands", "brands": ["Graco"], "categories": ["car_seat"], "webhook_id": "wh_3f9a1c07b2d4"}),
})
console.log(await res.json())

import os, requests

r = requests.post("https://recalldb.app/v1/watchlists", headers={"Authorization": f"Bearer {os.environ['RECALLDB_KEY']}"}, json={"name": "My brands", "brands": ["Graco"], "categories": ["car_seat"], "webhook_id": "wh_3f9a1c07b2d4"})
r.raise_for_status()
body = r.json()
print(body)

Response

200 OK

{
  "data": {
    "id": "wl_8c1d2e3f4a5b",
    "name": "My brands",
    "makes": [],
    "models": [],
    "brands": [
      "Graco"
    ],
    "categories": [
      "car_seat"
    ],
    "upcs": [],
    "webhook_id": "wh_3f9a1c07b2d4",
    "created_at": "2026-11-13T12:00:00.000Z"
  },
  "note": "Matching recalls will be sent to your webhook."
}

Every response includes source (agency, official ID, official URL, last updated) and attribution. Attribution rules.

Notes

Free keys can have 1 watchlist of up to 10 values and 1 webhook; unlimited watchlists are a planned Pro feature (see pricing). A second watchlist, or too many values, answers 403 plan_limit or 400.
Counts as one request.

Errors: error codes. Limits: rate limits.