Docs / Watchlists

Watchlists

Last updated 2026-11-13

A watchlist is a set of makes, models, brands, categories, UPCs or words. When a new or changed recall matches it, its webhook gets a message.

POST /v1/watchlists: Create a watchlist of makes, models, brands, categories and UPCs.
GET /v1/watchlists: Your watchlists and your plan limits.
DELETE /v1/watchlists/{id}: Delete a watchlist.

Create a watchlist

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

Notes

Over the plan limit (see pricing) answers 403 plan_limit; too many values answers 400.
Counts as one request.

List your watchlists

GET/v1/watchlists · API key required

Returns your watchlists with their values and webhook, and the limits of your plan.

Request

curlJavaScriptPython

curl https://recalldb.app/v1/watchlists \
  -H "Authorization: Bearer $RECALLDB_KEY"

const res = await fetch('https://recalldb.app/v1/watchlists', {
  headers: { Authorization: `Bearer ${process.env.RECALLDB_KEY}` },
})
console.log(await res.json())

import os, requests

r = requests.get("https://recalldb.app/v1/watchlists", headers={"Authorization": f"Bearer {os.environ['RECALLDB_KEY']}"})
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"
    }
  ],
  "limits": {
    "watchlists": 1,
    "webhooks": 1,
    "values_per_watchlist": 50,
    "plan": "free"
  }
}

Notes

Counts as one request.

Delete a watchlist

DELETE/v1/watchlists/{id} · API key required

Deletes the watchlist and its values. The webhook is kept.

Parameters

Name	In	Required	Description
`id`	path	yes	The watchlist id, such as wl_8c1d2e3f4a5b. Example: `wl_8c1d2e3f4a5b`

Request

curlJavaScriptPython

curl -X DELETE https://recalldb.app/v1/watchlists/wl_8c1d2e3f4a5b \
  -H "Authorization: Bearer $RECALLDB_KEY"

const res = await fetch('https://recalldb.app/v1/watchlists/wl_8c1d2e3f4a5b', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.RECALLDB_KEY}` },
})
console.log(await res.json())

import os, requests

r = requests.delete("https://recalldb.app/v1/watchlists/wl_8c1d2e3f4a5b", headers={"Authorization": f"Bearer {os.environ['RECALLDB_KEY']}"})
r.raise_for_status()
body = r.json()
print(body)

Response

200 OK

{
  "data": {
    "id": "wl_8c1d2e3f4a5b",
    "deleted": true
  }
}

Notes

Counts as one request.

See also: errors · rate limits · attribution