View input schema
{
"type": "object",
"properties": {
"q": {
"type": "string",
"maxLength": 200,
"description": "Free-text query over one index of canonical recalls and preliminary press releases: titles, firm, product name/brand/description, agency reason text, AI summary, hazard tags, and identifiers (UPC, NDC, lot codes, recall and campaign numbers; codes match as printed or as bare digits, including typed in spaced or dashed groups). Every word must match, in any order; words of 3+ characters also match as prefixes (a 2-letter word matches itself and its plural), a plural also matches its singular, and a double-quoted run is an exact phrase. The one operator is an uppercase OR between two words, binding tighter than the implicit AND (`salmonella OR listeria cheese` = (salmonella OR listeria) AND cheese); NOT and NEAR are ordinary words. If no record matches every word, the results fall back to records matching SOME of them and the response says `relaxed: true` (with a notice): those are not confirmed matches. A `q` with more than 10 distinct words or codes is refused with a tool error, not searched in part. Results are ranked by relevance by default. A `q` with no searchable word (only symbols, punctuation or the operators OR / AND) is refused with a tool error, not browsed: omit `q` to browse by filters. Zero results is never evidence a product is unaffected: agencies print codes inconsistently, so also search the brand or product name and compare codes on the record."
},
"agency": {
"type": "array",
"maxItems": 10,
"items": {
"type": "string",
"enum": [
"FDA",
"FSIS",
"CPSC",
"NHTSA"
]
},
"description": "Issuing agencies; matches any. Case-insensitive; values are uppercase."
},
"severity": {
"type": "array",
"maxItems": 10,
"items": {
"type": "string",
"enum": [
"CRITICAL",
"MODERATE",
"LOW",
"UNKNOWN"
]
},
"description": "Matches any. The issuing agency's own level (FDA/FSIS class, NHTSA do-not-drive or park-outside warning) on one scale by a fixed rule; null when the agency gave none. A record reporting null can still match MODERATE here. CPSC records are reachable only via UNKNOWN. Preliminary press releases count as UNKNOWN: a filter without UNKNOWN excludes them. Case-insensitive; values are uppercase."
},
"category": {
"type": "string",
"enum": [
"FOOD",
"DRUG",
"BIOLOGIC",
"DEVICE",
"COSMETIC",
"CONSUMER_PRODUCT",
"VEHICLE",
"AUTO_EQUIPMENT"
],
"description": "Single-select product category. Case-insensitive; values are uppercase."
},
"hazard": {
"type": "string",
"enum": [
"undeclared-allergen",
"undeclared-milk",
"undeclared-egg",
"undeclared-peanut",
"undeclared-tree-nut",
"undeclared-wheat",
"undeclared-soy",
"undeclared-sesame",
"undeclared-fish",
"undeclared-shellfish",
"undeclared-additive",
"salmonella",
"listeria",
"e-coli",
"botulism",
"contamination",
"chemical-contamination",
"foreign-material",
"sterility",
"labeling",
"misbranding",
"potency",
"hidden-drug",
"unapproved-product",
"manufacturing-deviation",
"dissolution",
"impurity",
"specification-failure",
"packaging-defect",
"process-deviation",
"nutrient-deficiency",
"quality-defect",
"software-defect",
"device-defect",
"donor-eligibility",
"import-violation",
"no-inspection",
"fire",
"burn",
"explosion",
"carbon-monoxide",
"electric-shock",
"laceration",
"impalement",
"fall",
"tip-over",
"choking",
"ingestion",
"poisoning",
"lead-or-chemical",
"suffocation",
"strangulation",
"entrapment",
"drowning",
"crush",
"impact",
"crash",
"injury",
"do-not-drive",
"fire-risk-parked",
"vehicle-electrical",
"vehicle-equipment",
"vehicle-mobility-equipment",
"vehicle-structure",
"vehicle-power-train",
"vehicle-backup-camera",
"vehicle-lighting",
"vehicle-seat-belts",
"vehicle-suspension",
"vehicle-visibility",
"vehicle-air-bags",
"vehicle-seats",
"vehicle-brakes",
"vehicle-steering",
"vehicle-fuel-system",
"vehicle-engine",
"vehicle-tires",
"vehicle-wheels",
"vehicle-trailer-hitch",
"vehicle-latches",
"vehicle-child-seat",
"vehicle-driver-assistance"
],
"description": "Single-select hazard tag, lowercase and hyphenated, the same filter as the website hazard pages: matches records whose hazard_tags include it, press releases included. Anything else is an error."
},
"firm": {
"type": "string",
"maxLength": 100,
"description": "Firm slug: the firm of one recall, as the `firm.slug` value of a get_recall record, or the last part of a /firm/ page URL (for example \"acme-foods\"). Matches that firm's recalls and press releases. An unknown or malformed slug is an error, not a dropped filter: no search is returned."
},
"state": {
"type": "string",
"pattern": "^[A-Za-z]{2}$",
"description": "Two-letter USPS code for a U.S. state or DC. Matches records distributed there or flagged nationwide. Territories are not filterable. Note the round trip: this takes a bare code such as \"TX\", while `distribution.geos` in the response emits ISO 3166-2 (\"US-TX\")."
},
"date": {
"type": "string",
"enum": [
"7d",
"30d",
"90d",
"year"
],
"description": "Relative window, resolved against the request clock. Ignored when `from` or `to` is set."
},
"from": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Inclusive lower bound, YYYY-MM-DD at 00:00:00 UTC."
},
"to": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Inclusive upper bound, YYYY-MM-DD at 23:59:59 UTC."
},
"sort": {
"type": "string",
"enum": [
"recent",
"severity",
"relevance"
],
"description": "`relevance` (the default when `q` is set) puts the best matches first. `recent` orders by listing date descending (the default without `q`). `severity` puts CRITICAL then MODERATE first, date descending within each band."
},
"page": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"description": "1-based page number, 50 records per page, at most 200: a larger page is refused with a tool error, not clamped; reach deeper archive by narrowing the date window instead. Pass the next page number in this parameter to navigate paginated results."
},
"status": {
"type": "string",
"enum": [
"open",
"ended"
],
"description": "Lifecycle, the same filter as `/data/recalls?status=` (api 2.8.0): `open` excludes ended recalls and FSIS public health alerts and keeps preliminary press releases; `ended` lists ended recalls only. Case-insensitive; values are lowercase. Anything else is an error."
}
},
"additionalProperties": false
}