carstat-app Recalls API

openapi: 3.2.0
info:
  title: REST API Reference Recalls API
  version: v1
  description: 'API for accessing vehicle specifications, NHTSA recalls, and NHTSA safety ratings. All three data verticals share the same discoverable browsing pattern: list available years → list makes for a year → list models for a year + make → fetch data.'
  x-rate-limit:
    requests: 120
    period: minute
    description: shared by REST and MCP across all account credentials
  x-logo:
    url: logo.svg
    backgroundColor: '#FFFFFF'
    href: /
  contact:
    name: Carstat API Support
    email: support@carstat.app
servers:
- url: https://api.carstat.app
  description: Production server
security:
- bearer_auth: []
tags:
- name: Recalls
  description: Browse and retrieve NHTSA recall campaigns. Use the discovery endpoints (years → makes → models) to navigate available data, then fetch all recall campaigns for a specific vehicle.
paths:
  /v1/recalls/years:
    get:
      summary: List available recall years
      tags:
      - Recalls
      description: Returns a list of distinct years for which recall data is available, ordered most recent first.
      operationId: getRecallYears
      security:
      - bearer_auth: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
                example:
                - 2024
                - 2023
                - 2022
                description: Array of years in descending order
        '402':
          description: Insufficient prepaid credits; the query is not charged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/insufficient_credits_error'
        '503':
          description: Query pricing is temporarily unavailable; the query is not charged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: No activated prepaid credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /v1/recalls/makes/{year}:
    get:
      summary: List available recall makes for a year
      tags:
      - Recalls
      description: Returns a list of distinct vehicle makes for which recall data is available for the specified year.
      operationId: getRecallMakesByYear
      security:
      - bearer_auth: []
      parameters:
      - name: year
        in: path
        description: Model year (e.g., 2023)
        required: true
        example: 2023
        schema:
          type: integer
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example:
                - Ford
                - Honda
                - Toyota
                description: Array of make names in alphabetical order
        '402':
          description: Insufficient prepaid credits; the query is not charged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/insufficient_credits_error'
        '503':
          description: Query pricing is temporarily unavailable; the query is not charged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: No activated prepaid credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /v1/recalls/models/{year}/{make}:
    get:
      summary: List recall models for a year and make
      tags:
      - Recalls
      description: Returns a list of distinct model names for which recall data is available for the given year and make.
      operationId: getRecallModelsByYearMake
      security:
      - bearer_auth: []
      parameters:
      - name: year
        in: path
        description: Model year (e.g., 2024)
        required: true
        example: 2024
        schema:
          type: integer
      - name: make
        in: path
        description: Vehicle manufacturer name (e.g., Toyota)
        required: true
        example: Toyota
        schema:
          type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example:
                - Camry
                - Corolla
                - RAV4
                description: Array of model names in alphabetical order
        '402':
          description: Insufficient prepaid credits; the query is not charged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/insufficient_credits_error'
        '503':
          description: Query pricing is temporarily unavailable; the query is not charged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: No activated prepaid credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /v1/recalls/{year}/{make}/{model}:
    get:
      summary: Get recalls for a vehicle
      tags:
      - Recalls
      description: Returns a list of recalls for the specified vehicle. Each recall includes details such as the recall ID, summary, consequence, remedy, and the date it was issued.
      operationId: getRecallsByVehicle
      security:
      - bearer_auth: []
      parameters:
      - name: year
        in: path
        description: Model year (e.g., 2024)
        required: true
        example: 2024
        schema:
          type: integer
      - name: make
        in: path
        description: Vehicle manufacturer name (e.g., Toyota)
        required: true
        example: Toyota
        schema:
          type: string
      - name: model
        in: path
        description: Vehicle model name (e.g., Camry). The specifications catalog's name and other market names for the same car also match (e.g., F-Series F-100/F-150, Cerato), as do NHTSA's body, cab and drive variants of the model.
        required: true
        example: Camry
        schema:
          type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/recall'
                description: Array of recall objects for the specified vehicle
        '402':
          description: Insufficient prepaid credits; the query is not charged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/insufficient_credits_error'
        '503':
          description: Query pricing is temporarily unavailable; the query is not charged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: No activated prepaid credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
components:
  schemas:
    recall:
      type: object
      properties:
        rcdate:
          type: string
          description: Recall date
          example: '2024-01-15'
        campno:
          type: string
          description: Campaign number
          example: 24V123000
        mfgname:
          type: string
          description: Manufacturer name
          example: Toyota
        compname:
          type: string
          description: Component name
          example: Air Bags
        desc_defect:
          type: string
          description: Defect description
        consequence_defect:
          type: string
          description: Consequence of defect
        corrective_action:
          type: string
          description: Corrective action
    error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      required:
      - error
    insufficient_credits_error:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: Insufficient credits. Please top up your balance.
        code:
          type: string
          enum:
          - insufficient_credits
          description: Top up your prepaid balance to continue querying
      required:
      - error
      - code
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: API Token
      description: API token authentication. Get your token from the dashboard.