recallsapi-com Signals API

openapi: 3.2.0
info:
  title: recallsapi.com Signals 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: Signals
paths:
  /v1/signals:
    get:
      operationId: searchSignals
      summary: 'Early-warning signals: investigations, violation notices, filings, Prop 65…'
      description: Public records that precede or accompany recalls, newest first. `q` words are matched against the title. A signal is not a recall.
      parameters:
      - name: q
        in: query
        schema:
          type: string
        description: Words that must all appear in the title
      - name: kind
        in: query
        schema:
          type: string
          enum:
          - investigation
          - violation
          - press_release
          - filing
          - prop65_notice
          - incident
      - name: source
        in: query
        schema:
          type: string
          enum:
          - nhtsa_inv
          - cpsc_nov
          - globenewswire
          - sec
          - prop65
          - spdb
      - name: since
        in: query
        schema:
          type: string
          format: date
        description: Earliest signal_date
      - name: until
        in: query
        schema:
          type: string
          format: date
        description: Latest signal_date
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - 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/Signal'
                  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:
      - Signals
  /v1/signals/{id}:
    get:
      operationId: getSignal
      summary: One early-warning signal with identifiers
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Signal'
        '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:
      - Signals
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
    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.