recallsapi-com Catalogs API

openapi: 3.2.0
info:
  title: recallsapi.com Catalogs 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: Catalogs
paths:
  /v1/catalogs:
    get:
      operationId: listCatalogs
      summary: Your monitored catalogs
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  catalogs:
                    type: array
                    items:
                      allOf:
                      - type: object
                        properties:
                          id:
                            type: string
                          name:
                            type: string
                          alert_email:
                            type:
                            - string
                            - 'null'
                          alert_email_unsubscribed_at:
                            type:
                            - string
                            - 'null'
                            format: date-time
                            description: When this address used the unsubscribe link in an alert email of this catalog; no alert emails go to it, even if it is saved again
                          webhook_url:
                            type:
                            - string
                            - 'null'
                          min_confidence:
                            type: string
                            enum:
                            - exact
                            - strong
                            - possible
                          created_at:
                            type: string
                            format: date-time
                          warnings:
                            type: array
                            items:
                              type: string
                      - type: object
                        properties:
                          items:
                            type: integer
                          open_matches:
                            type: integer
                          open_signals:
                            type: integer
        '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:
      - Catalogs
    post:
      operationId: createCatalog
      summary: Create a monitored catalog
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                alert_email:
                  type: string
                  format: email
                webhook_url:
                  type: string
                  format: uri
                min_confidence:
                  type: string
                  enum:
                  - exact
                  - strong
                  - possible
      responses:
        '201':
          description: Created; includes webhook_secret for signature checks, and `warnings` (strings) when alert_email is set on a plan without alerts (Free) or while email alerts are off; the address is saved either way
          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'
        '402':
          description: Plan limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Daily quota reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Catalogs
  /v1/catalogs/{id}/items:
    post:
      operationId: addItems
      summary: Add or replace items (JSON or CSV); returns matches found in recall history and…
      description: 'Up to 5,000 rows per upload: CSV (or a marketplace export as it comes) up to 10 MB, JSON up to 5 MB. Monitored products count across all catalogs on the account. `matches` lists the recall matches found in the recall database; `signals` lists the early-warning signals (not recalls) the items were linked to, at most 50 per item, newest first, each with sku, reasons and the signal''s key facts.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      sku:
                        type: string
                      name:
                        type: string
                      brand:
                        type: string
                      upc:
                        type: string
                      model:
                        type: string
                      ndc:
                        type: string
                      lot:
                        type: string
                      vin:
                        type: string
                      marketplace:
                        type: string
          text/csv:
            schema:
              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:
      - Catalogs
    get:
      operationId: listItems
      summary: Items in a catalog, by SKU, a page at a time
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 5000
          default: 5000
      - name: cursor
        in: query
        schema:
          type: string
        description: next_cursor from the previous page
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                  next_cursor:
                    type:
                    - string
                    - 'null'
        '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:
      - Catalogs
  /v1/catalogs/{id}/matches:
    get:
      operationId: listMatches
      summary: Recall matches for a catalog, newest first, a page at a time
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: status
        in: query
        schema:
          type: string
          enum:
          - open
          - dismissed
          - all
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 5000
          default: 100
      - name: cursor
        in: query
        schema:
          type: string
        description: next_cursor from the previous page
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  matches:
                    type: array
                    items:
                      type: object
                  next_cursor:
                    type:
                    - string
                    - 'null'
        '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:
      - Catalogs
  /v1/catalogs/{id}/signals:
    get:
      operationId: listCatalogSignals
      summary: Early-warning signals for a catalog (not recalls), newest first, a page at a…
      description: Signals (NHTSA investigations, CPSC violation notices, SEC filings, Prop 65 notices, SaferProducts.gov incident reports) whose identifiers carry an item's model, vehicle, campaign or brand key. Items are linked to every stored signal when they are uploaded (at most 50 per item, newest first) and to every new or changed signal by the daily pipeline. New signals ride with the daily alert under a "signals" section labelled as not recalls. Metered like /matches. `status` is open (default), dismissed or all.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: status
        in: query
        schema:
          type: string
          enum:
          - open
          - dismissed
          - all
          default: open
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 5000
          default: 100
      - name: cursor
        in: query
        schema:
          type: string
        description: next_cursor from the previous page
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/CatalogSignal'
                  next_cursor:
                    type:
                    - string
                    - 'null'
        '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'
        '404':
          description: No such catalog on this account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Daily quota reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Catalogs
  /v1/catalogs/{id}/signals/{signalId}/dismiss:
    post:
      operationId: dismissCatalogSignal
      summary: Dismiss an early-warning signal that does not apply
      description: '`signalId` is the catalog signal id (csg_...) from the listing, not the signal''s own id. A dismissed signal drops out of the open list and the alerts and is not linked again.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: signalId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  dismissed:
                    type: boolean
        '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'
        '404':
          description: No open signal with that id on this catalog
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Daily quota reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Catalogs
  /v1/catalogs/{id}:
    patch:
      operationId: updateCatalogAlertEmail
      summary: Change or remove the alert email
      description: 'Send only `alert_email`: an address (trimmed, at most 254 characters) or null (or an empty string) to stop alert emails. A new address gets a new unsubscribe link, so links in emails sent to the old address stop working. An address that used the unsubscribe link stays unsubscribed for this catalog, even when saved again (then `alert_email_unsubscribed_at` is set and a warning says so). The answer is the catalog (no webhook_secret) with `alert_email_unsubscribed_at`, plus `warnings` when the plan sends no alerts (Free) or email alerts are off.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - alert_email
              additionalProperties: false
              properties:
                alert_email:
                  type:
                  - string
                  - 'null'
                  format: email
                  maxLength: 254
      responses:
        '200':
          description: The updated catalog
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  alert_email:
                    type:
                    - string
                    - 'null'
                  alert_email_unsubscribed_at:
                    type:
                    - string
                    - 'null'
                    format: date-time
                    description: When this address used the unsubscribe link in an alert email of this catalog; no alert emails go to it, even if it is saved again
                  webhook_url:
                    type:
                    - string
                    - 'null'
                  min_confidence:
                    type: string
                    enum:
                    - exact
                    - strong
                    - possible
                  created_at:
                    type: string
                    format: date-time
                  warnings:
                    type: array
                    items:
                      type: string
        '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'
        '404':
          description: No such catalog on this account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Daily quota reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Catalogs
    delete:
      operationId: deleteCatalog
      summary: Delete a catalog with its items and matches
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: boolean
        '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'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Daily quota reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Catalogs
  /v1/catalogs/{id}/matches/{itemId}/{recallId}/dismiss:
    post:
      operationId: dismissMatch
      summary: Dismiss a match that does not apply
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: itemId
        in: path
        required: true
        schema:
          type: string
      - name: recallId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  dismissed:
                    type: boolean
        '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'
        '404':
          description: No open match
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Daily quota reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Catalogs
components:
  schemas:
    Signal:
      type: object
      description: 'A public record that precedes or accompanies a recall: an NHTSA defect investigation, a CPSC notice of violation, an SEC 8-K filing, a California Proposition 65 60-day notice or a SaferProducts.gov incident report. Stored signals also include 3 GlobeNewswire recall press releases, kept from a source retired on 2026-10-13. A signal is not a recall and not a finding against the product; a Prop 65 notice is a private party''s allegation, and a SaferProducts report is a submission to CPSC, not a CPSC finding.'
      properties:
        id:
          type: string
          examples:
          - inv-PE26001
          - nov-81af5fc297f5e300
          - gnw-9b64fafe8eb1a0c8
          - sec-0001459839-26-000076
          - p65-2026-04254
          - inc-20260918-420F0-2147309635
        source:
          type: string
          enum:
          - nhtsa_inv
          - cpsc_nov
          - globenewswire
          - sec
          - prop65
          - spdb
          description: 'nhtsa_inv: NHTSA defect investigations; cpsc_nov: CPSC notices of violation; globenewswire: GlobeNewswire recall press releases (retired 2026-10-13; the 3 stored releases are kept); sec: SEC EDGAR 8-K filings; prop65: California Attorney General Proposition 65 60-day notices; spdb: CPSC SaferProducts.gov incident reports'
        kind:
          type: string
          enum:
          - investigation
          - violation
          - press_release
          - filing
          - prop65_notice
          - incident
        title:
          type: string
        summary:
          type:
          - string
          - 'null'
          description: Agency text for investigations and violation notices; for Prop 65 notices the chemicals, the product or source text, the case events, the statement that a notice is a private party's allegation, the AG accuracy disclaimer and the AG notice page; null for press releases and filings, which are stored as facts only (title, date, issuer or filer, link); for SaferProducts incident reports the product, category and incident state, then the CPSC database disclaimer and the statement that a report is a submission to CPSC, not a CPSC finding
        firms:
          type: array
          items:
            type: string
          description: Manufacturer, firm named in the notice, press release issuer, SEC filer or the alleged violators of a Prop 65 notice
        products:
          type: array
          items:
            type: string
          description: 'Investigations: the components under investigation, then the vehicles as make and model; violation notices: the product name; Prop 65 notices: the product or source text as the noticing party wrote it; empty for facts-only sources'
        signal_date:
          type:
          - string
          - 'null'
          format: date
          description: Date the investigation opened, the violation notice is dated, the filing was filed, the Prop 65 notice was filed with the AG or the incident report was submitted (its publication date when the report date is missing); for a stored GlobeNewswire release, the day it was published
        end_date:
          type:
          - string
          - 'null'
          format: date
          description: Date an investigation closed; null while open and for other kinds
        status:
          type:
          - string
          - 'null'
          description: 'Investigations: open or closed. Violation notices: the action CPSC requested (Recall, Seize, Correct Future Production, Stop Sale and Correct Future Production). Prop 65 notices: notice, complaint, withdrawn or settled, from the case events the AG records. Null otherwise.'
        flags:
          type: array
          items:
            type: string
            enum:
            - recall_campaign
            - recall_requested
            - facts_only
            - allegation
            - submission
          description: 'recall_campaign: the investigation led to at least one recall campaign (a campaign identifier names it); recall_requested: CPSC asked for a recall; facts_only: only title, date, issuer or filer and link are stored; allegation: a private party''s notice, not a finding (Prop 65); submission: a SaferProducts.gov report, a submission to CPSC, not a CPSC finding'
        url:
          type: string
          format: uri
          description: Human page at the source
        source_url:
          type: string
          format: uri
          description: Machine-readable file, feed or query we read
        first_seen:
          type: string
          format: date-time
        as_of:
          type: string
          format: date-time
          description: When recallsapi.com last saw this record change
        identifiers:
          type: array
          description: 'Only on /v1/signals/{id}: model, gtin, mmy, mm, campaign, brand (compact firm key), cik'
          items:
            type: object
            properties:
              kind:
                type: string
              value:
                type: string
              raw:
                type: string
    CatalogSignal:
      type: object
      description: 'A signal whose identifiers carry a catalog item''s model, vehicle (make, model, year), campaign or brand key. It is a warning to review next to the catalog''s matches, not a recall and not a match: it has no confidence level and lives apart from the matches list.'
      properties:
        id:
          type: string
          pattern: ^csg_[A-Za-z0-9]{16}$
        item:
          type: object
          properties:
            id:
              type: string
            sku:
              type: string
            title:
              type:
              - string
              - 'null'
              description: The item name as uploaded
            identifiers:
              type: object
              description: The item's brand, upc, model, ndc, lot and vin, those that were uploaded
        signal:
          $ref: '#/components/schemas/Signal'
        reasons:
          type: array
          items:
            type: string
          description: 'The keys the link rests on: "model KDB504B", "mmy HONDA|CIVIC|2016", "campaign 16V218000" or "brand HONDA"'
        first_seen:
          type: string
          format: date-time
          description: When the signal was linked to the item
        dismissed_at:
          type:
          - string
          - 'null'
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details: {}
  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.