recallsapi-com Check API

openapi: 3.2.0
info:
  title: recallsapi.com Check API
  version: 0.1.0
  summary: 'Recall records from 9 US agencies (CPSC, FDA, NHTSA, US Coast Guard, FAA and more), plus 5 early-warning sources, in one API, with product matching and catalog monitoring. USDA FSIS: 2013 to October 6, 2026 loaded; daily updates coming soon.'
  description: Every record links to its agency source with an as-of date. Matches carry a confidence level and the reasons behind it; a match is information to review, not a legal or safety determination. Sold by PrimeZen LLC.
  contact:
    name: recallsapi.com support
    email: hello@recallsapi.com
    url: https://recallsapi.com
  x-guidance: 'recallsapi.com answers whether a product or vehicle is under a US recall, from the records of 9 US agencies (CPSC, FDA, NHTSA, US Coast Guard, FAA and more). Every record carries its agency source and an as-of date.


    Start with GET /v1/check: give any of upc (UPC, EAN or GTIN barcode), model, ndc, lot, brand and name. Each match has a confidence (exact, strong or possible) and the reasons for it. A match is information to review, not a legal or safety determination, and no match does not mean a product is safe.


    GET /v1/vehicles takes vin, or make, model and year, and returns NHTSA campaigns with live NHTSA complaint counts. GET /v1/recalls searches records with q, category, source, since and until, newest first; page with next_cursor.


    Pay per call with x402, no account needed: call a paid route without an API key and it answers 402 with a PAYMENT-REQUIRED header (x402 v2, scheme exact, USDC on Base). Sign the payment and repeat the call with the PAYMENT-SIGNATURE header. Prices per call: GET /v1/check $0.02, GET /v1/recalls $0.01, GET /v1/vehicles $0.01. A call that does not succeed (any answer that is not 2xx) is not charged.


    Prepaid credit: POST /v1/credits/topup?amount=1, 5 or 20 (USD; the $1 top-up when amount is left out) is one x402 payment that returns credit_token, shown once. Send it as the X-Credit-Token header on the paid routes to draw each call from the balance with no further on-chain payment; read the balance at GET /v1/credits (free). Credit is not refundable and does not expire.


    With an API key the routes work within the plan''s limits and no payment is asked: get a free key with POST /v1/keys and an email address (the key is sent to that inbox), then send Authorization: Bearer <key> or X-API-Key: <key>. Catalog monitoring (/v1/catalogs) and the MCP server tools (POST /mcp) need a key. GET /v1/health shows each source''s freshness and is free.


    Docs: recallsapi.com/docs/agents. Contact: hello@recallsapi.com.'
  termsOfService: https://recallsapi.com/terms
servers:
- url: https://api.recallsapi.com
security:
- bearer: []
- apiKey: []
tags:
- name: Check
paths:
  /v1/check:
    get:
      operationId: checkProduct
      security:
      - bearer: []
      - apiKey: []
      - credit: []
      - {}
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.020000'
        protocols:
        - x402: {}
      summary: Is this product recalled?
      description: 'Give any mix of name, brand, barcode, model, NDC and lot. Identifiers are normalized (UPC to GTIN-14, NDC to 11 digits) before matching. `signals` lists up to 10 early-warning signals (NHTSA investigations, CPSC violation notices, SEC filings, Prop 65 notices, SaferProducts.gov incident reports) whose identifiers carry the product''s model, vehicle, campaign or brand key; a signal is not a recall and has no confidence level. `adverse_events` (only when both brand and model are given) holds live FDA MAUDE medical device report counts for that brand and model from openFDA: total, last 12 months, by event type, last report date and the openFDA link; null when openFDA holds nothing. A count is not a safety determination. `receipt=1` adds a signed receipt of the check (see the Receipt schema).'
      parameters:
      - name: name
        in: query
        schema:
          type: string
        description: Product name or description
      - name: brand
        in: query
        schema:
          type: string
        description: Brand or manufacturer
      - name: upc
        in: query
        schema:
          type: string
        description: UPC, EAN or GTIN barcode
      - name: model
        in: query
        schema:
          type: string
        description: Model or part number
      - name: ndc
        in: query
        schema:
          type: string
        description: National Drug Code (any layout)
      - name: lot
        in: query
        schema:
          type: string
        description: Lot or batch code
      - name: receipt
        in: query
        schema:
          type: string
          enum:
          - '1'
          - 'true'
        description: 'Adds a signed receipt (`receipt`): a dated record of what recallsapi.com held for this check, stored for 400 days and fetchable at its verify_url without a key. Not a safety certification.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  resolved:
                    type: object
                  matches:
                    type: array
                    items:
                      $ref: '#/components/schemas/Match'
                  signals:
                    type: array
                    maxItems: 10
                    items:
                      $ref: '#/components/schemas/SignalHit'
                  adverse_events:
                    type: object
                    nullable: true
                    properties:
                      source:
                        type: string
                      brand:
                        type: string
                      model:
                        type: string
                      reports_total:
                        type: integer
                      reports_last_12_months:
                        type: integer
                      last_report_date:
                        type: string
                        nullable: true
                      by_event_type:
                        type: object
                        properties:
                          malfunction:
                            type: integer
                          injury:
                            type: integer
                          death:
                            type: integer
                      url:
                        type: string
                      note:
                        type: string
                  receipt:
                    $ref: '#/components/schemas/Receipt'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: 'Payment Required: x402 v2 payment requirements (scheme exact, USDC on Base, amount in base units, payTo) in the PAYMENT-REQUIRED header as base64 JSON, and the same object as the body'
          headers:
            PAYMENT-REQUIRED:
              description: base64 JSON of the x402 v2 PaymentRequired object
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  x402Version:
                    type: integer
                    const: 2
                  error:
                    type: string
                  resource:
                    type: object
                  accepts:
                    type: array
                    items:
                      type: object
                  extensions:
                    type: object
        '429':
          description: Daily quota reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Check
  /v1/check/batch:
    post:
      operationId: checkProducts
      summary: Check up to 100 products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                items:
                  type: array
                  maxItems: 100
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      brand:
                        type: string
                      upc:
                        type: string
                      model:
                        type: string
                      ndc:
                        type: string
                      lot:
                        type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Daily quota reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Check
components:
  schemas:
    Receipt:
      type: object
      description: 'A dated, verifiable record of what recallsapi.com held when a product was checked: the normalized input, match counts, the state of every source and a plain statement, signed with Ed25519. It is not a safety certification and absence of a match does not mean a product is safe. Stored for 400 days.'
      properties:
        id:
          type: string
          pattern: ^rcpt_[A-Za-z0-9]{24}$
        issued_at:
          type: string
          format: date-time
        issuer:
          type: string
          const: recallsapi.com (PrimeZen LLC)
        input:
          type: object
          description: 'The normalized input: the resolved block of the check'
        result:
          type: object
          properties:
            matches:
              type: object
              properties:
                exact:
                  type: integer
                strong:
                  type: integer
                possible:
                  type: integer
            signals:
              type: integer
              description: Early-warning signals in the answer
            adverse_events:
              type:
              - boolean
              - 'null'
              description: true when FDA MAUDE held reports for the brand and model; false when both were given and the live lookup answered nothing; null when the check did not look
        sources:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              status:
                type: string
                enum:
                - ok
                - stale
                - pending
                - coming_soon
              last_success:
                type:
                - string
                - 'null'
                format: date-time
              records:
                type: integer
              newest_record:
                type:
                - string
                - 'null'
          description: Every recall source, as /v1/health reported it at issue time
        signal_sources:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              status:
                type: string
                enum:
                - ok
                - stale
                - pending
                - coming_soon
              last_success:
                type:
                - string
                - 'null'
                format: date-time
              records:
                type: integer
              newest_record:
                type:
                - string
                - 'null'
          description: Every early-warning signal source at issue time
        statement:
          type: string
          description: What was or was not found, as of issued_at, and what the receipt is not
        signature:
          type:
          - object
          - 'null'
          description: null while signing is not enabled (then note says so)
          properties:
            alg:
              type: string
              const: Ed25519
            kid:
              type: string
              description: First 8 hex characters of the SHA-256 of the SPKI public key; look it up in /.well-known/recallsapi-keys.json
            value:
              type: string
              description: base64url Ed25519 signature over the canonical JSON (object keys sorted recursively, arrays in order, no whitespace) of the receipt without the signature field
        note:
          type: string
          description: Only when signature is null
        verify_url:
          type: string
          format: uri
          description: GET returns the stored receipt without a key
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details: {}
    Match:
      type: object
      properties:
        confidence:
          type: string
          enum:
          - exact
          - strong
          - possible
          description: 'exact: barcode or NDC package code; strong: identifier confirmed by brand or a distinctive model; possible: brand and name overlap or a weak identifier'
        reasons:
          type: array
          items:
            type: string
        recall:
          $ref: '#/components/schemas/Recall'
    SignalHit:
      type: object
      properties:
        id:
          type: string
        source:
          type: string
          enum:
          - nhtsa_inv
          - cpsc_nov
          - globenewswire
          - sec
          - prop65
          - spdb
        kind:
          type: string
          enum:
          - investigation
          - violation
          - press_release
          - filing
          - prop65_notice
          - incident
        title:
          type: string
        signal_date:
          type:
          - string
          - 'null'
          format: date
        end_date:
          type:
          - string
          - 'null'
          format: date
        status:
          type:
          - string
          - 'null'
        url:
          type: string
          format: uri
        reasons:
          type: array
          items:
            type: string
          description: 'The identifier each match rests on: "model KDB504B", "mmy HONDA|CIVIC|2016", "mm HONDA|CIVIC", "campaign 16V218000" or "brand HONDA"'
    Recall:
      type: object
      properties:
        id:
          type: string
          examples:
          - fda-H-1339-2026
        agency:
          type: string
          enum:
          - CPSC
          - FDA
          - NHTSA
          - USDA FSIS
          - US Coast Guard
          - FAA
          - HUD
          - NIOSH
          - MSHA
        source:
          type: string
          enum:
          - cpsc
          - fda_food
          - fda_drug
          - fda_device
          - nhtsa
          - fsis
          - uscg
          - faa
          - hud
          - niosh
          - msha
          - fda_press
          - fda_hfcs
          - fda_ires
        source_id:
          type: string
          description: The agency recall number, Federal Register document number, or a stable slug for notices without a number
        category:
          type: string
          enum:
          - consumer_product
          - food
          - drug
          - device
          - vehicle
          - vehicle_equipment
          - tire
          - child_seat
          - meat_poultry
          - boat
          - aircraft
          - manufactured_home
          - respirator
          - mine_equipment
          - unclassified
          - cosmetic
          - tobacco
          - biologic
          - veterinary
        title:
          type: string
        description:
          type:
          - string
          - 'null'
        hazard:
          type:
          - string
          - 'null'
        remedy:
          type:
          - string
          - 'null'
        classification:
          type:
          - string
          - 'null'
          description: FDA and FSIS class (Class I, II, III), NHTSA recall type, Coast Guard recall type (Boat, Engine or equipment), Federal Register document type, or notice type
        status:
          type:
          - string
          - 'null'
        firms:
          type: array
          items:
            type: string
        products:
          type: array
          items:
            type: string
        distribution:
          type:
          - string
          - 'null'
        units:
          type:
          - string
          - 'null'
        flags:
          type: array
          items:
            type: string
            enum:
            - do_not_drive
            - park_outside
            - public_health_alert
            - outbreak
            - fda_mandated
            - lots_truncated
            - press_release
            - medwatch
            - detail_pending
            - health_fraud
        recall_date:
          type:
          - string
          - 'null'
          format: date
        report_date:
          type:
          - string
          - 'null'
          format: date
        url:
          type: string
          format: uri
          description: Agency notice
        source_url:
          type: string
          format: uri
          description: Machine-readable source record
        first_seen:
          type: string
          format: date-time
          description: When recallsapi.com first stored this record
        as_of:
          type: string
          format: date-time
          description: When recallsapi.com last saw this record change
        identifiers:
          type: array
          items:
            type: object
            properties:
              kind:
                type: string
              value:
                type: string
              raw:
                type: string
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: API key from POST /v1/keys
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'The same API key from POST /v1/keys, sent as the X-API-Key header instead of Authorization: Bearer'
    credit:
      type: apiKey
      in: header
      name: X-Credit-Token
      description: x402 prepaid credit token from POST /v1/credits/topup (shown once). Pays /v1/check, /v1/recalls and /v1/vehicles from its balance, only while x402 payments are switched on.