{"openapi":"3.0.3","info":{"title":"RecallGuard","version":"1.0.0","description":"Machine-readable US product-recall feed (CPSC consumer products + FDA food/drug/device enforcement reports, 2023-01-01 to present) and an inventory matcher (UPC exact match, then token-overlap scoring on product name/brand). Dataset: 21812 recalls, 2023-01-04 to 2026-09-24, built 2026-09-28T17:26:11Z from saferproducts.gov and api.fda.gov. Informational only; always confirm against the linked official record. Payment: /api/v1/feed ($0.05 per call) and /api/v1/match ($0.10 per call) are paid per call with the x402 protocol (v1, USDC on Base mainnet). A request without a valid X-PAYMENT header gets HTTP 402 with the payment requirements in the body. /api/v1/health, /openapi.json and /docs are free. There is no free tier and there are no API keys: direct requests to feed or match without a valid payment always get 402.","x-guidance":"Call GET /api/v1/health (free) to see dataset size and build time. POST /api/v1/match with {\"items\":[{\"name\",\"brand\",\"upc\"}]} (1-100 items) or GET /api/v1/feed?since=YYYY-MM-DD. Both paid routes answer HTTP 402 with x402 v1 payment requirements (USDC on Base) until a valid X-PAYMENT header is sent.","contact":{"name":"Nano Empire AI"}},"servers":[{"url":"https://recallguard-api.vercel.app"}],"paths":{"/api/v1/health":{"get":{"operationId":"health","summary":"Service health and dataset info","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"dataset_count":{"type":"integer"},"dataset_built_at":{"type":"string","format":"date-time"},"date_min":{"type":"string","format":"date"},"date_max":{"type":"string","format":"date"},"sources":{"type":"object"}}}}}}}}},"/api/v1/feed":{"get":{"operationId":"feed","summary":"Paginated recall feed (newest first)","x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.05"}},"parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date"},"description":"Only recalls with recall_date >= since (YYYY-MM-DD)."},{"name":"until","in":"query","schema":{"type":"string","format":"date"},"description":"Only recalls with recall_date <= until (YYYY-MM-DD)."},{"name":"source","in":"query","schema":{"type":"string"},"description":"Comma-separated: cpsc, fda-food, fda-drug, fda-device."},{"name":"severity","in":"query","schema":{"type":"string"},"description":"Comma-separated: serious, standard, class-i, class-ii, class-iii (also accepts \"Class I\" etc.)."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from next_cursor of the previous page."},{"name":"X-PAYMENT","in":"header","required":false,"schema":{"type":"string"},"description":"x402 v1 payment payload (base64-encoded JSON, scheme \"exact\", network \"base\"), built from the \"accepts\" entry of the 402 response. Verified and settled through an x402 facilitator; the response is only returned after settlement succeeds."}],"responses":{"200":{"description":"OK","headers":{"X-PAYMENT-RESPONSE":{"schema":{"type":"string"},"description":"Base64-encoded JSON settlement receipt from the facilitator: {success, transaction, network, payer}. Present on paid (x402) requests."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Recall"}},"total":{"type":"integer"},"limit":{"type":"integer"},"next_cursor":{"type":"string","nullable":true},"dataset_built_at":{"type":"string"}}}}}},"400":{"description":"Invalid parameter (payment is not settled)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid X-RapidAPI-Proxy-Secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (x402). Returned when no X-PAYMENT header is sent, or when the payment fails verification or settlement. Price: $0.05 per call = maxAmountRequired \"50000\" USDC (6 decimals) on Base mainnet (network \"base\").","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/api/v1/match":{"post":{"operationId":"match","summary":"Match inventory items against recalls","x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.10"}},"parameters":[{"name":"X-PAYMENT","in":"header","required":false,"schema":{"type":"string"},"description":"x402 v1 payment payload (base64-encoded JSON, scheme \"exact\", network \"base\"), built from the \"accepts\" entry of the 402 response. Verified and settled through an x402 facilitator; the response is only returned after settlement succeeds."}],"description":"Per item: UPC exact match first (GTIN-normalized), then token-overlap scoring on name/brand. Token matches below the score threshold are not returned. Up to 5 matches per item.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","properties":{"name":{"type":"string","example":"Snuga Swing"},"brand":{"type":"string","example":"Fisher-Price"},"upc":{"type":"string","example":"731149654051"}}}}}},"example":{"items":[{"name":"Snuga Swing","brand":"Fisher-Price"},{"name":"Raw Shrimp","upc":"731149654051"}]}}}},"responses":{"200":{"description":"OK","headers":{"X-PAYMENT-RESPONSE":{"schema":{"type":"string"},"description":"Base64-encoded JSON settlement receipt from the facilitator: {success, transaction, network, payer}. Present on paid (x402) requests."}},"content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"input":{"type":"object"},"match_count":{"type":"integer"},"matches":{"type":"array","items":{"$ref":"#/components/schemas/Match"}}}}},"threshold":{"type":"number"},"dataset_built_at":{"type":"string"}}}}}},"400":{"description":"Invalid body (payment is not settled)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid X-RapidAPI-Proxy-Secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (x402). Returned when no X-PAYMENT header is sent, or when the payment fails verification or settlement. Price: $0.10 per call = maxAmountRequired \"100000\" USDC (6 decimals) on Base mainnet (network \"base\").","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"413":{"description":"Too many items (payment is not settled)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Recall":{"type":"object","properties":{"id":{"type":"string","example":"fda-food-F-1671-2024"},"source":{"type":"string","enum":["cpsc","fda-food","fda-drug","fda-device"]},"title":{"type":"string","nullable":true},"product_description":{"type":"string","nullable":true},"product_names":{"type":"array","items":{"type":"string"}},"brand":{"type":"string","nullable":true,"description":"CPSC: parsed from the recall title. FDA: not provided by openFDA (null)."},"firm":{"type":"string","nullable":true,"description":"CPSC manufacturer/importer/distributor; FDA recalling_firm."},"upcs":{"type":"array","items":{"type":"string"},"description":"12-13 digit UPC/EAN/GTIN codes extracted from the official record text."},"hazard":{"type":"string","nullable":true,"description":"CPSC hazard text or FDA reason_for_recall."},"injuries":{"type":"string","nullable":true,"description":"CPSC reported incidents/injuries text."},"classification":{"type":"string","nullable":true,"enum":["Class I","Class II","Class III",null]},"severity":{"type":"string","enum":["serious","standard","class-i","class-ii","class-iii","unclassified"],"description":"FDA: derived from classification. CPSC: \"serious\" if the injuries/incidents text mentions injuries or deaths, else \"standard\"."},"recall_date":{"type":"string","format":"date","description":"CPSC RecallDate; FDA enforcement report_date."},"recall_initiation_date":{"type":"string","format":"date","nullable":true},"status":{"type":"string","nullable":true},"units":{"type":"string","nullable":true},"url":{"type":"string","description":"CPSC recall page, or the openFDA API query for this recall number."},"source_record":{"type":"string"}}},"Match":{"type":"object","properties":{"recall_id":{"type":"string"},"score":{"type":"number","minimum":0,"maximum":1},"match_type":{"type":"string","enum":["upc_exact","token"]},"source":{"type":"string"},"severity":{"type":"string"},"classification":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"firm":{"type":"string","nullable":true},"recall_date":{"type":"string","format":"date"},"hazard":{"type":"string","nullable":true},"url":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"PaymentRequirements":{"type":"object","description":"x402 v1 payment requirements (one entry of \"accepts\").","properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"base"},"maxAmountRequired":{"type":"string","description":"USDC atomic units (6 decimals). feed: \"50000\" ($0.05), match: \"100000\" ($0.10)."},"resource":{"type":"string","format":"uri"},"description":{"type":"string"},"mimeType":{"type":"string","example":"application/json"},"payTo":{"type":"string","description":"Recipient address on Base."},"maxTimeoutSeconds":{"type":"integer","example":60},"asset":{"type":"string","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"USDC contract on Base mainnet."},"outputSchema":{"type":"object","nullable":true},"extra":{"type":"object","example":{"name":"USD Coin","version":"2"},"description":"EIP-712 domain name/version of the USDC contract."}}},"PaymentRequired":{"type":"object","properties":{"x402Version":{"type":"integer","example":1},"error":{"type":"string","example":"X-PAYMENT header is required"},"accepts":{"type":"array","items":{"$ref":"#/components/schemas/PaymentRequirements"}},"payer":{"type":"string","nullable":true}}}}}}