{"openapi":"3.1.0","info":{"title":"Product Recall Check API","version":"1.0.0","summary":"Check whether a product matches an official recall.","description":"Product Recall Check routes a product to the responsible US recall authority (CPSC, NHTSA, FDA), queries its official API live, and matches identifiers deterministically. Original authority wording is returned verbatim. NO_MATCH_FOUND means only that no matching recall was found in the checked official sources under the supplied identifiers. It does not mean the product is safe, free of defects, or will never be recalled. Price: 0.018 USDC per charged check via x402 on Base mainnet. Operated by Active Life Hub LLC."},"servers":[{"url":"https://productrecallcheck.online"}],"paths":{"/api/v1/check":{"post":{"operationId":"checkRecall","summary":"Check a product against official recall sources","description":"Without PAYMENT-SIGNATURE: validates and normalises identifiers, routes the category and answers 402 with the x402 requirement, the price and the official sources that would be queried (free, nothing stored, no source queried). With PAYMENT-SIGNATURE and Idempotency-Key: queries the sources live and returns the result. Only RECALL_FOUND, POSSIBLE_MATCH, AMBIGUOUS and NO_MATCH_FOUND are settled; SOURCE_UNAVAILABLE and UNABLE_TO_VERIFY are never charged. The same Idempotency-Key never charges twice and cannot be reused for a different product; one payment authorises exactly one check.","parameters":[{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"schema":{"type":"string"},"description":"Base64 x402 v2 payment payload (exact scheme, USDC)."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$"},"description":"Required with PAYMENT-SIGNATURE. Reuse it for retries."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckRequest"}}}},"responses":{"200":{"description":"Check result. Header PAYMENT-RESPONSE carries the settlement when charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Check"}}}},"400":{"description":"Invalid request or identifier (never charged)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}},"402":{"description":"Payment required (quote), or the payment was invalid/rejected. Header PAYMENT-REQUIRED carries the x402 requirement.","content":{"application/json":{"schema":{"type":"object"}}}},"409":{"description":"Idempotency conflict, in progress, or payment replay","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}},"413":{"description":"Body over 16 KB","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}},"415":{"description":"Content-Type must be application/json","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}},"422":{"description":"Jurisdiction or category not covered (never charged)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}},"503":{"description":"Not configured or payment provider unavailable (nothing charged)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}}}}},"/api/v1/checks/{id}":{"get":{"operationId":"getCheck","summary":"Retrieve a stored check and its evidence (free)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prc_[0-9a-f]{52}$"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Bearer <the Idempotency-Key used for the paid request>"}],"responses":{"200":{"description":"Stored result (cache_status STORED, original checked_at — not re-checked)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Check"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}},"410":{"description":"Evidence retention elapsed","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}}}}},"/api/v1/coverage":{"get":{"operationId":"getCoverage","summary":"Live jurisdictions, categories, authorities and sources (free)","responses":{"200":{"description":"Coverage","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/pricing":{"get":{"operationId":"getPricing","summary":"Price and measured cost basis (free)","responses":{"200":{"description":"Pricing","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/health":{"get":{"operationId":"getHealth","summary":"Liveness and configuration status (free, no database, no source call)","responses":{"200":{"description":"OK"},"503":{"description":"Not configured"}}}}},"components":{"schemas":{"CheckRequest":{"type":"object","additionalProperties":false,"description":"At least one selective identifier is required. Vehicles: vin, or brand/make + model + model_year. Consumer products: brand or product_name (CPSC cannot be searched by UPC alone).","properties":{"category":{"type":"string","description":"Optional. One of consumer_product, vehicle, food, drug, medical_device or \"auto\". Omitted → routed from identifiers (VIN/model_year → vehicle, NDC → drug, UDI → medical_device) or product words; when unclear, all non-vehicle authorities are queried. Not covered (422, never charged): meat_poultry_egg, vehicle_equipment, cosmetics, boats."},"jurisdiction":{"type":"string","description":"Default \"US\" (the only live jurisdiction)."},"brand":{"type":"string","maxLength":120,"description":"Brand, manufacturer or (vehicles) make, as printed."},"make":{"type":"string","maxLength":60,"description":"Vehicles: alias of brand."},"product_name":{"type":"string","maxLength":200,"description":"Product name/description, any language or script."},"model":{"type":"string","maxLength":80,"description":"Model/item number as printed (\"XB-200\"); vehicles: model name (\"Accord\"). Separators are normalised, digits never: XR-10 never equals XR-100."},"model_year":{"type":"string","description":"Vehicles: 4-digit model year."},"upc":{"type":"string","maxLength":20,"description":"UPC-A (12), UPC-E (8), EAN-13, GTIN-14. Leading zeros kept; an invalid check digit is rejected (400), never corrected."},"gtin":{"type":"string","maxLength":20,"description":"Same as upc."},"ean":{"type":"string","maxLength":20,"description":"Same as upc."},"sku":{"type":"string","maxLength":40,"description":"Retailer SKU/item number (matched only when the authority prints it)."},"serial":{"type":"string","maxLength":60,"description":"Serial number; compared against published serial ranges of the same format."},"lot":{"type":"string","maxLength":60,"description":"Lot or batch code."},"batch":{"type":"string","maxLength":60,"description":"Alias of lot."},"date_code":{"type":"string","maxLength":30,"description":"Manufacturer date code as printed (e.g. \"2511\")."},"manufacture_date":{"type":"string","description":"YYYY-MM or YYYY-MM-DD."},"expiration_date":{"type":"string","description":"Best-by / use-by / expiration, YYYY-MM-DD or YYYY-MM."},"best_by":{"type":"string","description":"Alias of expiration_date."},"vin":{"type":"string","maxLength":24,"description":"17-character VIN (check digit validated). Used only to decode make/model/year via NHTSA vPIC; masked in all output."},"ndc":{"type":"string","maxLength":16,"description":"National Drug Code, hyphenated 10-digit (4-4-2, 5-3-2, 5-4-1), 11-digit, or product NDC."},"udi":{"type":"string","maxLength":120,"description":"Medical device UDI (routes to FDA devices)."},"input_language":{"type":"string","description":"Optional BCP 47 language of the supplied names."},"output_language":{"type":"string","description":"Optional BCP 47 preference. Explanations are English today; official wording is never translated or replaced."}}},"Check":{"type":"object","required":["check_id","result","summary","no_match_meaning","recalls","verification","payment"],"properties":{"check_id":{"type":"string"},"result":{"type":"string","enum":["RECALL_FOUND","POSSIBLE_MATCH","AMBIGUOUS","NO_MATCH_FOUND","SOURCE_UNAVAILABLE","UNABLE_TO_VERIFY"]},"confidence":{"type":["string","null"],"enum":["HIGH","MEDIUM","LOW",null],"description":"Evidence-based: HIGH = exact published identifier; MEDIUM = exact model / model family / brand + full name, or a restriction left open; LOW = name-only similarity."},"summary":{"type":"string"},"no_match_meaning":{"type":"string"},"product":{"type":"object","description":"Supplied identity and which identifiers matched the best recall."},"recall":{"type":["object","null"],"description":"The strongest recall (same as recalls[0].recall)."},"source":{"type":["object","null"]},"recalls":{"type":"array","description":"Every materially matching recall, strongest first, then newest.","items":{"type":"object","properties":{"match_state":{"type":"string","enum":["RECALL_FOUND","POSSIBLE_MATCH"]},"confidence":{"type":"string","enum":["HIGH","MEDIUM","LOW"]},"match_explanation":{"type":"object","description":"brand_match, model_match, upc_match, ndc_match, lot_match, serial_range_match, date_code_match, date_range_match… (true / false / null = not established)."},"restrictions":{"type":"array","description":"Lot/serial/date/VIN restrictions read from the official text, with evaluation matched | not_matched | unverified | not_supplied.","items":{"type":"object"}},"recall":{"type":"object","properties":{"recall_id":{"type":"string"},"authority":{"type":"string"},"title":{"type":["string","null"]},"published_at":{"type":["string","null"],"format":"date"},"status":{"type":["string","null"]},"classification":{"type":["string","null"]},"hazard_original":{"type":["string","null"],"description":"Verbatim authority wording."},"hazard_normalized":{"type":"array","items":{"type":"string","enum":["FIRE","BURN","CHOKING","ELECTRIC_SHOCK","CRASH","INJURY","CONTAMINATION","ALLERGEN","OTHER","UNKNOWN"]}},"consumer_action_original":{"type":["string","null"],"description":"Verbatim remedy / consumer instructions; null when the source publishes none (never invented)."},"affected_products":{"type":"array","items":{"type":"object"}},"original_description":{"type":["string","null"]}}},"source":{"type":"object","properties":{"url":{"type":["string","null"]},"api_url":{"type":"string"},"checked_at":{"type":"string","format":"date-time"},"source_type":{"type":"string","enum":["OFFICIAL_RECALL_SOURCE"]}}}}}},"other_candidates":{"type":"array","items":{"type":"object"},"description":"Weak (name-level) similarities, never reported as matches."},"excluded_candidates":{"type":"array","items":{"type":"object"},"description":"Nearby recalls checked and found NOT to cover the supplied identifiers, with the reason."},"routing":{"type":"object"},"verification":{"type":"object","description":"checked_at, cache (cache_used, cache_status LIVE | IDEMPOTENT_REPLAY | STORED, source_version), per-source outcome and exact request URLs."},"next_steps":{"type":"array","items":{"type":"string"}},"unknowns":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"language":{"type":"object"},"evidence_sha256":{"type":"string"},"payment":{"type":"object"}}}}},"x-pricing":{"amount":"0.018","currency":"USDC","unit":"check","version":"prc-cost-plus-2026-09-30-v1"}}