{
 "openapi": "3.0.3",
 "info": {
  "title": "RecallHound API",
  "version": "0.1.0",
  "description": "Checks used products and vehicles against official United States federal recall records (CPSC, NHTSA, FDA) plus EPA fuel economy data. No authentication. Informational only: never tell a user an item is safe based on these results, and always share the official notice link and the limits text.",
  "contact": {
   "name": "RecallHound",
   "email": "r@agran.co",
   "url": "https://recallhound.app"
  },
  "termsOfService": "https://recallhound.app/terms"
 },
 "servers": [
  {
   "url": "https://recallhound.app/api"
  }
 ],
 "paths": {
  "/check-product": {
   "get": {
    "operationId": "checkProduct",
    "summary": "Check a consumer product, food, drug, or medical device for a known US federal recall",
    "description": "Use before a user buys, sells, lists, or keeps using a used item. Accepts messy text such as a marketplace listing title. Include brand and model number when the user has them, since that is the only way to reach a likely_match.",
    "parameters": [
     {
      "name": "description",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "maxLength": 300
      },
      "description": "Product name or listing title, for example: boppy newborn lounger pillow."
     },
     {
      "name": "brand",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Brand or manufacturer, if known."
     },
     {
      "name": "model_number",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Model number from the product label, if known."
     },
     {
      "name": "category",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "consumer",
        "food",
        "drug",
        "device"
       ],
       "default": "consumer"
      },
      "description": "consumer searches CPSC (household goods, baby gear, furniture, electronics, toys, appliances). food, drug, and device search FDA enforcement reports. Car seats and tires are regulated by NHTSA and are not covered by this endpoint yet."
     }
    ],
    "responses": {
     "200": {
      "description": "Check completed",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "result": {
           "type": "string",
           "enum": [
            "likely_match",
            "possible_match",
            "none_found"
           ]
          },
          "message": {
           "type": "string",
           "description": "Plain language summary suitable to relay."
          },
          "matches": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "confidence": {
              "type": "string",
              "enum": [
               "likely_match",
               "possible_match"
              ],
              "description": "likely_match: model number or several distinctive terms matched. possible_match: brand or product type matched, the user must compare the model number."
             },
             "score": {
              "type": "number"
             },
             "model_number_matched": {
              "type": "boolean"
             },
             "recall_id": {
              "type": "integer",
              "description": "Pass to getRecallDetails for remedy steps."
             },
             "recall_number": {
              "type": "string"
             },
             "recall_date": {
              "type": "string",
              "format": "date"
             },
             "title": {
              "type": "string"
             },
             "products": {
              "type": "array",
              "items": {
               "type": "string"
              }
             },
             "hazard": {
              "type": "string"
             },
             "remedy": {
              "type": "string"
             },
             "remedy_type": {
              "type": "array",
              "items": {
               "type": "string"
              },
              "description": "Refund, Repair, Replace, or other. Never promise a refund unless listed here."
             },
             "official_url": {
              "type": "string",
              "format": "uri"
             }
            }
           }
          },
          "total_candidates": {
           "type": "integer"
          },
          "searched_terms": {
           "type": "array",
           "items": {
            "type": "string"
           }
          },
          "data_source": {
           "type": "string"
          },
          "limits": {
           "type": "string",
           "description": "Always relay this to the user."
          },
          "source": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Problem with the request",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          },
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "429": {
      "description": "Problem with the request",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          },
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "502": {
      "description": "Problem with the request",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          },
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/check-vehicle": {
   "get": {
    "operationId": "checkVehicle",
    "summary": "Check a vehicle: recalls issued, owner complaints, crash ratings, fuel cost",
    "description": "Use when a user is considering a used car, truck, SUV, or motorcycle. Provide a VIN, or make, model, and year. Returns recalls issued for that make, model, and year. It cannot tell whether a specific vehicle already had the recall repair, so direct the user to nhtsa.gov/recalls with the VIN for that. Does not include accident, title, lien, flood, or theft history.",
    "parameters": [
     {
      "name": "vin",
      "in": "query",
      "schema": {
       "type": "string",
       "minLength": 17,
       "maxLength": 17
      },
      "description": "17 character VIN. Used only to decode the vehicle, never stored."
     },
     {
      "name": "make",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "model",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "year",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1981,
       "maximum": 2030
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Check completed. Sections that could not be fetched are listed in sections_unavailable.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "vehicle": {
           "type": "object"
          },
          "message": {
           "type": "string"
          },
          "warning": {
           "type": "string"
          },
          "recalls": {
           "type": "object",
           "nullable": true,
           "properties": {
            "count": {
             "type": "integer"
            },
            "items": {
             "type": "array",
             "items": {
              "type": "object",
              "properties": {
               "campaign_number": {
                "type": "string"
               },
               "date": {
                "type": "string"
               },
               "component": {
                "type": "string"
               },
               "summary": {
                "type": "string"
               },
               "consequence": {
                "type": "string"
               },
               "remedy": {
                "type": "string"
               },
               "do_not_drive": {
                "type": "boolean"
               },
               "park_outside": {
                "type": "boolean"
               },
               "official_url": {
                "type": "string"
               }
              }
             }
            }
           }
          },
          "complaints": {
           "type": "object",
           "nullable": true
          },
          "crash_ratings": {
           "description": "Array of variants with 1 to 5 star ratings, or a note when not rated."
          },
          "fuel_economy": {
           "description": "EPA combined MPG and annual fuel cost ranges, or a note when no record matched."
          },
          "sections_unavailable": {
           "type": "array",
           "items": {
            "type": "string"
           }
          },
          "limits": {
           "type": "string",
           "description": "Always relay this to the user."
          },
          "source": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Problem with the request",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          },
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "429": {
      "description": "Problem with the request",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          },
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "502": {
      "description": "Problem with the request",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          },
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/scan-purchases": {
   "post": {
    "operationId": "scanPurchases",
    "summary": "Check a list of things the user already owns for recalls",
    "description": "Use only with the user's approval. Send item NAMES ONLY, taken from order history or receipts. Do not send order numbers, prices, dates, addresses, payment details, or anything that identifies the user. Up to 25 items per request. Consumer products only.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "items"
        ],
        "properties": {
         "items": {
          "type": "array",
          "maxItems": 25,
          "items": {
           "type": "string",
           "maxLength": 200
          },
          "example": [
           "Boppy Newborn Lounger",
           "Anker power bank"
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Scan completed",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "summary": {
           "type": "object"
          },
          "message": {
           "type": "string"
          },
          "items": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "item": {
              "type": "string"
             },
             "result": {
              "type": "string",
              "enum": [
               "likely_match",
               "possible_match",
               "none_found",
               "not_checked"
              ]
             },
             "recall_id": {
              "type": "integer"
             },
             "title": {
              "type": "string"
             },
             "recall_date": {
              "type": "string"
             },
             "hazard": {
              "type": "string"
             },
             "remedy_type": {
              "type": "array",
              "items": {
               "type": "string"
              }
             },
             "official_url": {
              "type": "string"
             }
            }
           }
          },
          "limits": {
           "type": "string",
           "description": "Always relay this to the user."
          },
          "source": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Problem with the request",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          },
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "429": {
      "description": "Problem with the request",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          },
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/recall-details": {
   "get": {
    "operationId": "getRecallDetails",
    "summary": "Full details and remedy steps for one CPSC recall",
    "description": "Use after checkProduct or scanPurchases when the user wants to know what to do next: the hazard, the remedy, and how to contact the company.",
    "parameters": [
     {
      "name": "recall_id",
      "in": "query",
      "required": true,
      "schema": {
       "type": "integer"
      },
      "description": "The recall_id from a match."
     }
    ],
    "responses": {
     "200": {
      "description": "Recall found",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "recall_id": {
           "type": "integer"
          },
          "title": {
           "type": "string"
          },
          "description": {
           "type": "string"
          },
          "products": {
           "type": "array",
           "items": {
            "type": "object"
           }
          },
          "hazard": {
           "type": "string"
          },
          "injuries": {
           "type": "string"
          },
          "remedy": {
           "type": "string"
          },
          "remedy_type": {
           "type": "array",
           "items": {
            "type": "string"
           }
          },
          "how_to_get_the_remedy": {
           "type": "string"
          },
          "sold_at": {
           "type": "string"
          },
          "official_url": {
           "type": "string"
          },
          "limits": {
           "type": "string",
           "description": "Always relay this to the user."
          },
          "source": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Problem with the request",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          },
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Problem with the request",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          },
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "502": {
      "description": "Problem with the request",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          },
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  }
 }
}