{ "openapi": "3.0.1", "info": { "title": "Product & Vehicle Recalls API — CPSC, NHTSA, FDA, USDA", "description": "Every US recall a federal agency publishes, in one schema: consumer products (CPSC), vehicles (NHTSA), drugs, devices and food (FDA), and meat, poultry and egg (USDA FSIS) — plus a VIN decoder that joins each VIN to its model's recalls, complaints and NCAP crash-test ratings. Keyless .gov sources.", "version": "0.1", "x-build-id": "hcZ1Spix2sToiddOS" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/insight.solutions~product-recalls-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-insight.solutions-product-recalls-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/insight.solutions~product-recalls-api/runs": { "post": { "operationId": "runs-sync-insight.solutions-product-recalls-api", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/insight.solutions~product-recalls-api/run-sync": { "post": { "operationId": "run-sync-insight.solutions-product-recalls-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "sources": { "title": "Sources", "type": "array", "description": "Which agencies to read. `cpsc` is consumer products from saferproducts.gov; `nhtsa` is vehicle recalls, owner complaints and NCAP crash-test ratings; `fda` is drug, device and food enforcement reports from openFDA; `fsis` is USDA meat, poultry and egg recalls. All four produce the same columns, so a run over all four is one table. Setting `vehicles` or `vins` switches `nhtsa` on whether or not you list it.", "items": { "type": "string", "enum": [ "cpsc", "nhtsa", "fda", "fsis" ], "enumTitles": [ "CPSC — consumer products", "NHTSA — vehicles, complaints, crash ratings", "FDA — drugs, devices, food", "USDA FSIS — meat, poultry, egg" ] }, "default": [ "cpsc", "nhtsa", "fda", "fsis" ] }, "keywords": { "title": "Keywords", "type": "array", "description": "Only recalls whose title, product name, description, hazard or reason mentions one of these, e.g. `[\"battery\", \"lithium\"]`. Sent to CPSC as one request per keyword per search field, to openFDA as a `search=` clause and to USDA FSIS as a partial-match text filter, then re-checked on every row before it is written. Rows that came back because you named a vehicle or a VIN are not keyword-filtered — you asked for that car by name.", "default": [], "items": { "type": "string" } }, "vehicles": { "title": "Vehicles", "type": "array", "description": "Vehicles to look up at NHTSA, as `\"2020 Honda Civic\"` strings or `{\"make\": \"honda\", \"model\": \"civic\", \"year\": 2020}` objects. A model year is required — NHTSA indexes recalls by year from 1949, and a yearless make and model would be 78 requests. Every entry goes through NHTSA's own make and model lists, so the row carries the agency's spelling; a description matching more than one model returns the candidates free instead of guessing.", "default": [], "items": { "type": "string" } }, "maxRecords": { "title": "Max records per source", "minimum": 0, "maximum": 100000, "type": "integer", "description": "How many recall rows to return from each source. The three FDA enforcement endpoints share one budget rather than getting one each. 0 means every record the filters allow. Owner complaints and VIN rows have their own caps and are not counted here.", "default": 100 }, "includeRatings": { "title": "Include NCAP crash-test ratings", "type": "boolean", "description": "Fetch NHTSA's New Car Assessment Program ratings for each vehicle: overall, front, side, pole and rollover stars, plus the crash-test photographs and videos. Two requests per vehicle, one row per body-style variant. Not every vehicle is tested; an untested one gets a free diagnostic row.", "default": false }, "vins": { "title": "VINs", "type": "array", "description": "VINs to decode with NHTSA's free vPIC decoder, in batches of 50. A partial VIN is written with `*` for the unknown positions. A VIN we cannot decode costs you nothing. Unless `decodeOnly` is on, each decoded VIN is joined to its model's recalls, complaints and ratings — and fifty VINs of one model cost one set of recall rows, not fifty.", "default": [], "items": { "type": "string" } }, "recallIds": { "title": "Recall or campaign numbers", "type": "array", "description": "Fetch specific records. A CPSC `RecallID` (e.g. `10967`) is looked up at saferproducts.gov; an NHTSA campaign number (e.g. `21V215000`) is recognised by its shape and looked up at NHTSA instead.", "default": [], "items": { "type": "string" } }, "manufacturers": { "title": "Manufacturers or recalling firms", "type": "array", "description": "Only recalls whose recalling firm, manufacturer, importer, distributor, retailer or USDA establishment mentions one of these, e.g. `[\"Peloton\"]`. CPSC and openFDA are asked server-side; NHTSA and FSIS are filtered here.", "default": [], "items": { "type": "string" } }, "hazardKeywords": { "title": "Hazard keywords", "type": "array", "description": "Only recalls whose hazard, consequence or reason mentions one of these, e.g. `[\"fire\", \"laceration\"]`. CPSC has no hazard-code taxonomy in practice — it returns the hazard as a sentence — so this is a text match on that sentence.", "default": [], "items": { "type": "string" } }, "remedyKeywords": { "title": "Remedy keywords", "type": "array", "description": "Only recalls whose remedy mentions one of these, e.g. `[\"refund\"]`. CPSC mixes a clean enum (Refund, Replace, Repair) with whole paragraphs of instructions in the same field, so this is a text match rather than a picker.", "default": [], "items": { "type": "string" } }, "states": { "title": "States", "type": "array", "description": "Two-letter state codes, e.g. `[\"CA\", \"TX\"]`. Matched against the firm's state and against the distribution text, which is where FSIS and CPSC put it. Vehicle recalls are national and are not affected.", "default": [], "items": { "type": "string" } }, "classifications": { "title": "Classifications", "type": "array", "description": "Only recalls in these classes. FDA and USDA classify recalls I (reasonable probability of serious harm) to III (unlikely to cause harm); USDA also issues Public Health Alerts. CPSC and NHTSA do not classify recalls and are not affected.", "items": { "type": "string", "enum": [ "Class I", "Class II", "Class III", "Public Health Alert" ], "enumTitles": [ "Class I — serious harm or death", "Class II — temporary or reversible harm", "Class III — unlikely to cause harm", "Public Health Alert (USDA)" ] }, "default": [] }, "dateFrom": { "title": "Published on or after", "type": "string", "description": "ISO date, `YYYY-MM-DD`. Sent server-side to CPSC and openFDA; applied here for NHTSA and USDA FSIS, neither of which offers a recall-date range filter. Leave empty and CPSC defaults to the last 90 days — its API has no paging and no limit, so an unbounded request would download all 11,000 records.", "default": "" }, "dateTo": { "title": "Published on or before", "type": "string", "description": "ISO date, `YYYY-MM-DD`. Leave empty for today.", "default": "" }, "includeComplaints": { "title": "Include owner complaints", "type": "boolean", "description": "Fetch NHTSA owner complaints for each vehicle. Off by default because complaints arrive in bulk and are billed per complaint: one 2021 Tesla Model 3 returns 660 in a single request. `maxComplaintsPerVehicle` bounds it.", "default": false }, "maxComplaintsPerVehicle": { "title": "Max complaints per vehicle", "minimum": 1, "maximum": 5000, "type": "integer", "description": "How many owner complaints to return for one vehicle. NHTSA sends the whole set in one response; this is the cut, and it is what bounds the bill.", "default": 200 }, "decodeOnly": { "title": "Decode VINs only", "type": "boolean", "description": "Decode each VIN and stop there — no recalls, complaints or ratings are fetched for the model it decodes to. The cheapest way to use this Actor as a VIN decoder.", "default": false }, "fdaSearch": { "title": "Raw openFDA search (advanced)", "type": "string", "description": "An openFDA `search=` expression, ANDed with everything else, e.g. `initial_firm_notification:\"Press Release\"`. For people who know the openFDA query language; everyone else should use the filters above.", "default": "" }, "fsisServerSideFilter": { "title": "Try the USDA FSIS text filters first", "type": "boolean", "description": "USDA publishes its whole recall list — about 13 MB — in one response with no date-range filter. When you set keywords, the run first tries USDA's two documented partial-match text parameters, and falls back to the full list if they return nothing, because an empty answer from that API is also what a parameter it ignores looks like. Turn this off to always fetch the full list.", "default": true }, "includeSummary": { "title": "Include summary rows", "type": "boolean", "description": "Add free `summary` rows: one per source, one per vehicle (with the resolved make and model, NHTSA's own recall and complaint totals, and the VIN-range limitation) and one for the run. Never charged.", "default": true }, "vinModelYear": { "title": "VIN model year hint", "type": "string", "description": "A model year to send alongside a partial or short VIN, which is what lets vPIC decode one. Ignored for full 17-character VINs.", "default": "" }, "includeRawVin": { "title": "Include the raw VIN decode", "type": "boolean", "description": "Attach all 154 vPIC fields to each VIN row as `vpicRaw`. The flattened columns cover the ones people use; this is for the rest.", "default": false }, "maxRatingVariantsPerVehicle": { "title": "Max rating variants per vehicle", "minimum": 1, "maximum": 50, "type": "integer", "description": "NHTSA rates body styles separately — a 2020 Honda Civic has a 2-door and a 4-door rating. This caps how many of them are fetched.", "default": 5 }, "includeCampaignDetail": { "title": "Include recall campaign detail", "type": "boolean", "description": "Fill `potentialUnitsAffected` on vehicle recalls. NHTSA publishes that number only on its campaign-number endpoint, so this costs one extra request per distinct campaign.", "default": false }, "maxCampaignLookups": { "title": "Max campaign lookups", "minimum": 0, "maximum": 500, "type": "integer", "description": "Caps the extra requests `includeCampaignDetail` makes.", "default": 25 }, "crashOnly": { "title": "Crashes only", "type": "boolean", "description": "Only owner complaints NHTSA records as involving a crash. The flag is on the record itself, not inferred from the text.", "default": false }, "fireOnly": { "title": "Fires only", "type": "boolean", "description": "Only owner complaints NHTSA records as involving a fire.", "default": false }, "resolveAmbiguous": { "title": "When a vehicle matches more than one model", "enum": [ "diagnostic", "first", "all" ], "type": "string", "description": "`\"2020 Honda Civ\"` matches five NHTSA models. By default that is a free diagnostic row listing all five and nothing is fetched or charged. `first` takes the first candidate; `all` treats every candidate as its own vehicle, each counting against `maxVehicles`.", "default": "diagnostic" }, "cpscSearchFields": { "title": "CPSC search fields", "type": "array", "description": "Which CPSC fields each keyword is searched against. CPSC ANDs everything it is sent, so an OR across fields is one request per field — which is why this is a list and why `maxCpscRequests` exists. Only CPSC's own documented parameter names are accepted.", "items": { "type": "string", "enum": [ "RecallTitle", "ProductName", "RecallDescription", "Hazard", "Remedy", "Injury", "Manufacturer", "Retailer", "Importer", "Distributor" ] }, "default": [ "RecallTitle", "ProductName", "RecallDescription" ] }, "maxCpscRequests": { "title": "Max CPSC requests", "minimum": 1, "maximum": 50, "type": "integer", "description": "How many requests one run may make to saferproducts.gov. Keywords times search fields, plus one per manufacturer, hazard, remedy and recall id.", "default": 12 }, "openFdaApiKey": { "title": "openFDA API key (optional)", "type": "string", "description": "Your own free openFDA key. Without one the API allows 100 records per page and 1,000 requests a day per IP; with one it allows 1,000 per page and a far larger daily quota. Everything here works without it." }, "maxVehicles": { "title": "Max vehicles", "minimum": 1, "maximum": 500, "type": "integer", "description": "How many vehicles to resolve and fetch for.", "default": 25 }, "maxVins": { "title": "Max VINs", "minimum": 1, "maximum": 5000, "type": "integer", "description": "How many VINs to decode. They go out in batches of 50, which is vPIC's documented ceiling.", "default": 500 }, "incremental": { "title": "Incremental mode", "type": "boolean", "description": "Return only records you have not been given before. The run keeps each record's id **and its revision marker** — CPSC's publish date, FDA's status, USDA's last-modified date, NHTSA's report date and star rating — so a recall the agency re-publishes comes back and an unchanged one does not. VIN rows are never suppressed: you asked for that VIN by name.", "default": false }, "stateStoreName": { "title": "State store name", "type": "string", "description": "The named key-value store the incremental cursor lives in. Give two scheduled jobs different names and they will not tread on each other.", "default": "product-recalls-api-state" }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many sources, and how many vehicles within NHTSA, to read at once. Each parallel worker keeps its own proxy session.", "default": 4 }, "maxRunSecs": { "title": "Max run seconds", "minimum": 30, "maximum": 3600, "type": "integer", "description": "Wall-clock budget for the whole run. When it runs out, the rows already written are kept and a free diagnostic row says where the walk stopped.", "default": 240 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify's datacenter proxy is enough for NHTSA, vPIC, openFDA and USDA FSIS — and USDA's firewall actually prefers it. CPSC is the exception: saferproducts.gov answered every datacenter request with a placeholder record in our measurements, so CPSC requests go out on the run's own address first and fall back to this proxy only if that fails.", "default": { "useApifyProxy": true } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }