{"openapi":"3.1.0","info":{"title":"Recall Relay API","version":"1.0.0","description":"Every U.S. product, food, drug, device and vehicle recall from CPSC, FDA, USDA FSIS and NHTSA in one schema. Updated every two hours."},"servers":[{"url":"https://recallrelay.com"}],"security":[{"ApiKey":[]},{"Bearer":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-API-Key"},"Bearer":{"type":"http","scheme":"bearer"}},"schemas":{"Recall":{"type":"object","description":"One recall in the same shape for every agency.","properties":{"id":{"type":"string","description":"Stable id: `<source>-<agency recall number>`","example":"cpsc-27082"},"source":{"type":"string","enum":["cpsc","fda","fsis","nhtsa"]},"agency":{"type":"string","example":"CPSC"},"agency_name":{"type":"string"},"category":{"type":"string","enum":["consumer_product","food","drug","device","meat_poultry_egg","vehicle","vehicle_equipment","tire","child_seat"]},"title":{"type":"string"},"description":{"type":"string","description":"What was recalled."},"hazard":{"type":"string","description":"Why it was recalled."},"remedy":{"type":["string","null"],"description":"What owners should do."},"classification":{"type":["string","null"],"description":"Agency class (Class I, II, III) when the agency assigns one."},"severity":{"type":"string","enum":["low","medium","high"]},"severity_basis":{"type":"string","enum":["agency_class","agency_advisory","estimated"],"description":"`estimated` means Recall Relay inferred severity from the hazard text."},"status":{"type":"string","enum":["ongoing","completed","terminated"]},"recall_date":{"type":"string","format":"date"},"published_date":{"type":["string","null"],"format":"date"},"companies":{"type":"array","items":{"type":"string"}},"products":{"type":"array","items":{"type":"object"}},"upcs":{"type":"array","items":{"type":"string"},"description":"Barcodes named in the recall: labeled UPC, GTIN, EAN or (for medical devices) UDI-DI, check digit verified."},"states":{"type":"array","items":{"type":"string"},"description":"Two-letter codes; `US` means nationwide."},"distribution":{"type":["string","null"]},"units_affected":{"type":["integer","null"]},"url":{"type":"string","description":"The agency's own record."},"images":{"type":"array","items":{"type":"string"}},"extra":{"type":"object","description":"Agency-specific fields (lot codes, injuries, do-not-drive flags...)."},"first_seen":{"type":"string","format":"date-time","description":"When Recall Relay first saw it."}}}}},"paths":{"/v1/recalls":{"get":{"operationId":"searchRecalls","summary":"Search recalls","description":"Full-text search across every agency with filters. Newest first, or `sort=relevance`.","parameters":[{"name":"q","in":"query","required":false,"description":"Words to search for. Every word must match; the last word matches as a prefix.","schema":{"type":"string"},"example":"crib"},{"name":"source","in":"query","required":false,"description":"Comma-separated agencies.","schema":{"type":"string"},"example":"cpsc,fda"},{"name":"category","in":"query","required":false,"description":"Comma-separated categories: consumer_product, food, drug, device, meat_poultry_egg, vehicle, vehicle_equipment, tire, child_seat.","schema":{"type":"string"},"example":"food,drug"},{"name":"min_severity","in":"query","required":false,"description":"Only recalls at or above this severity.","schema":{"type":"string","enum":["low","medium","high"]}},{"name":"since","in":"query","required":false,"description":"Recall date on or after (YYYY-MM-DD).","schema":{"type":"string"},"example":"2026-01-01"},{"name":"until","in":"query","required":false,"description":"Recall date on or before (YYYY-MM-DD).","schema":{"type":"string"}},{"name":"state","in":"query","required":false,"description":"Two-letter state; nationwide recalls always match.","schema":{"type":"string"},"example":"CA"},{"name":"company","in":"query","required":false,"description":"Company name contains this text.","schema":{"type":"string"},"example":"medtronic"},{"name":"status","in":"query","required":false,"description":"ongoing, completed or terminated.","schema":{"type":"string","enum":["ongoing","completed","terminated"]}},{"name":"sort","in":"query","required":false,"description":"recent (default) or relevance.","schema":{"type":"string","enum":["recent","relevance"]}},{"name":"limit","in":"query","required":false,"description":"1 to 100. Default 20.","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"For paging.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Matching recalls","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Recall"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"next":{"type":["string","null"]}}}}}}}}},"/v1/recalls/{id}":{"get":{"operationId":"getRecall","summary":"Get one recall","parameters":[{"name":"id","in":"path","required":true,"description":"Recall id, for example `fda-D-0006-2027`.","schema":{"type":"string"}}],"responses":{"200":{"description":"The recall","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Recall"}}}},"404":{"description":"No recall with that id"}}}},"/v1/upc/{upc}":{"get":{"operationId":"lookupUpc","summary":"Look up a barcode","description":"Recalls that name this UPC, EAN or GTIN. Leading zeros and spaces are ignored.","parameters":[{"name":"upc","in":"path","required":true,"description":"The barcode digits.","schema":{"type":"string"},"example":"867166000004"}],"responses":{"200":{"description":"Recalls naming this barcode","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Recall"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"next":{"type":["string","null"]}}}}}}}}},"/v1/check":{"post":{"operationId":"checkCatalog","summary":"Check a product list","description":"Send your catalog; get back which items match a recall. Barcodes give exact matches; brand and name give possible matches to review. Costs 1 request per 100 items.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Your SKU or row id, echoed back."},"upc":{"type":"string"},"brand":{"type":"string"},"name":{"type":"string"}}}},"since":{"type":"string","format":"date","description":"Ignore recalls before this date. Default: 3 years ago."}}},"example":{"items":[{"id":"sku-1001","upc":"8 67166 00000 4"},{"id":"sku-1002","brand":"Sharper Image","name":"Tabletop Fire Pit, concrete"}]}}}},"responses":{"200":{"description":"One result per item","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/vehicles":{"get":{"operationId":"vehicleRecalls","summary":"Recalls for a vehicle","description":"Recalls for one make, model and model year, straight from NHTSA (cached 24 hours).","parameters":[{"name":"make","in":"query","required":true,"description":"Vehicle make.","schema":{"type":"string"},"example":"honda"},{"name":"model","in":"query","required":true,"description":"Vehicle model.","schema":{"type":"string"},"example":"pilot"},{"name":"year","in":"query","required":true,"description":"Model year.","schema":{"type":"integer"},"example":2023}],"responses":{"200":{"description":"Recalls","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Recall"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"next":{"type":["string","null"]}}}}}}}}},"/v1/watches":{"get":{"operationId":"listWatches","summary":"List alerts","responses":{"200":{"description":"Your alerts"}}},"post":{"operationId":"createWatch","summary":"Create an alert","description":"Get a signed webhook the moment a new recall matches. Set any of `q`, `upcs`, `companies` (a recall matches if any of them match), and narrow with `categories`, `sources`, `min_severity` and `states`. Each list takes up to 200 values; create more alerts for longer lists. The webhook_url must be a public https address. The response includes the signing secret once.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","webhook_url"],"properties":{"name":{"type":"string"},"webhook_url":{"type":"string","format":"uri"},"q":{"type":"string"},"upcs":{"type":"array","maxItems":200,"items":{"type":"string"}},"companies":{"type":"array","maxItems":200,"items":{"type":"string"}},"categories":{"type":"array","maxItems":200,"items":{"type":"string","enum":["consumer_product","food","drug","device","meat_poultry_egg","vehicle","vehicle_equipment","tire","child_seat"]}},"sources":{"type":"array","maxItems":200,"items":{"type":"string","enum":["cpsc","fda","fsis","nhtsa"]}},"min_severity":{"type":"string","enum":["low","medium","high"]},"states":{"type":"array","maxItems":200,"items":{"type":"string"}}}},"example":{"name":"Baby gear we resell","webhook_url":"https://example.com/hooks/recalls","q":"crib","categories":["consumer_product"],"min_severity":"medium"}}}},"responses":{"201":{"description":"Alert created"}}}},"/v1/watches/{id}":{"delete":{"operationId":"deleteWatch","summary":"Delete an alert","parameters":[{"name":"id","in":"path","required":true,"description":"Alert id.","schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"}}}},"/v1/watches/{id}/test":{"post":{"operationId":"testWatch","summary":"Send a test alert","parameters":[{"name":"id","in":"path","required":true,"description":"Alert id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Your endpoint's response code"}}}},"/v1/stats":{"get":{"operationId":"stats","summary":"Coverage and freshness","security":[],"description":"Record counts and the last successful update for each agency. No key needed.","responses":{"200":{"description":"Stats"}}}},"/v1/me":{"get":{"operationId":"me","summary":"Your plan and usage","responses":{"200":{"description":"Plan, limits and usage"}}}}}}