recallsapi-com Credits API

openapi: 3.2.0
info:
  title: recallsapi.com Credits 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: Credits
paths:
  /v1/credits/topup:
    post:
      operationId: creditTopup
      summary: Buy prepaid x402 credit (agents)
      x-payment-info:
        price:
          mode: dynamic
          currency: USD
          min: '1.000000'
          max: '20.000000'
        protocols:
        - x402: {}
      description: Answers 402 with one x402 exact-scheme requirement (USDC on Base) for the chosen amount ($1 when amount is left out); pay it with any x402 client. After the payment settles on-chain the answer carries `credit_token`, shown once and stored only as a hash. Send an existing token as X-Credit-Token to add to its balance instead. Not refundable; does not expire; one balance holds at most $1,000.
      security: []
      parameters:
      - name: amount
        in: query
        required: false
        schema:
          type: string
          enum:
          - '1'
          - '5'
          - '20'
          default: '1'
        description: Top-up in USD; the $1 top-up when left out
      - name: X-Credit-Token
        in: header
        required: false
        schema:
          type: string
        description: Add to this balance instead of creating a new token
      - name: PAYMENT-SIGNATURE
        in: header
        required: false
        schema:
          type: string
        description: x402 v2 payment payload (base64 JSON)
      responses:
        '200':
          description: Paid and credited
          content:
            application/json:
              schema:
                type: object
                properties:
                  credit_token:
                    type: string
                    pattern: ^rcr_[A-Za-z0-9_-]{43}$
                    description: Only when a new token was created
                  added_usd:
                    type: string
                  balance_usd:
                    type: string
                  balance_micro_usd:
                    type: integer
                  prices_usd:
                    type: object
                    additionalProperties:
                      type: string
                  transaction:
                    type: string
                  network:
                    type: string
                  refundable:
                    type: boolean
                  expires:
                    type: boolean
        '400':
          description: amount is not one of the top-up amounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unknown credit token
          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
        '409':
          description: Transaction already credited, or the balance limit would be passed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Facilitator unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Credits
  /v1/credits:
    get:
      operationId: creditBalance
      summary: Read a prepaid x402 credit balance
      description: Free and unmetered. Balance, spend, calls charged, prices and the last 20 top-ups of the token in X-Credit-Token.
      security:
      - credit: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  balance_usd:
                    type: string
                  balance_micro_usd:
                    type: integer
                  funded_usd:
                    type: string
                  spent_usd:
                    type: string
                  calls:
                    type: integer
                  prices_usd:
                    type: object
                    additionalProperties:
                      type: string
                  topup_amounts_usd:
                    type: array
                    items:
                      type: string
                  topups:
                    type: array
                    items:
                      type: object
                      properties:
                        transaction:
                          type: string
                        amount_usd:
                          type: string
                        network:
                          type: string
                        at:
                          type: string
                          format: date-time
        '401':
          description: Missing or unknown credit token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Credits
components:
  schemas:
    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.