openapi: 3.2.0
info:
  title: 2s — the (most) everything Vehicle API
  version: '1'
  summary: The (most) everything API.
  description: 'The (most) everything API for AI agents: 575+ pay-per-call endpoints on one origin.'
  contact:
    name: 2s
    url: https://2s.io
    email: alley@2s.io
  x-logo:
    url: https://2s.io/icon-512.png
    altText: 2s
  x-guidance: 'Pay-per-call REST API for AI agents — hundreds of endpoints returning ground-truth data (US public records, company & legal identifiers, finance/SEC, crypto/web3, security & CVEs, medical codes, weather & geocoding, agriculture, energy, maritime, music, and more). Every endpoint is paid per call in USDC via x402 (Base or Solana) — no API key, no signup. Call any endpoint with no auth to get a 402 PaymentRequirements envelope, sign it (EIP-3009 on Base, partial SPL transfer on Solana), and retry with the PAYMENT-SIGNATURE header. Add ?trial=1 for one free real call per endpoint per hour to test before paying. To discover the right endpoint: GET https://2s.io/api/directory for the full catalog, or GET https://2s.io/api/search/endpoints?q=<natural-language task> for a ranked match. Per-call price is on each operation as x-payment-info (from $0.001). Batch up to 50 calls behind one payment via POST https://2s.io/api/batch/run.'
servers:
- url: https://2s.io
tags:
- name: Vehicle
paths:
  /api/vehicle/canadian-specs:
    get:
      tags:
      - Vehicle
      summary: Canadian-market vehicle dimensions and weights from NHTSA
      description: Canadian-market vehicle dimensions and weights from NHTSA vPIC's Canadian Vehicle Specifications dataset. Pass year + make (required) and optional model to narrow. Returns one entry per matching trim with labeled dimensions — overall length/width/height (cm), wheelbase (cm), curb weight (kg), front/rear track width, interior head/leg/shoulder/hip room, and weight distribution — plus the full raw spec map. Authoritative measured specs (the SAE dimension codes), not estimates. Keyless, public-domain; covers model years 1971+.
      operationId: vehicle_canadian-specs
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = matching vehicles (labeled + raw specs); meta.total = count.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            make:
                              type: string
                              nullable: true
                            model:
                              type: string
                              nullable: true
                            specs:
                              type: object
                              additionalProperties:
                                type: string
                            labeled:
                              type: array
                              items:
                                type: object
                                properties:
                                  code:
                                    type: string
                                  label:
                                    type: string
                                  value:
                                    type: string
                                required:
                                - code
                                - label
                                - value
                                additionalProperties: false
                          required:
                          - make
                          - model
                          - specs
                          - labeled
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              year:
                                type: integer
                              make:
                                type: string
                              model:
                                type: string
                                nullable: true
                            required:
                            - year
                            - make
                            - model
                            additionalProperties: false
                          total:
                            type: integer
                        required:
                        - query
                        - total
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: vehicle.canadian-specs
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: year
        in: query
        required: true
        description: Four-digit calendar year.
        schema:
          type: integer
          minimum: 1971
          maximum: 2100
      - name: make
        in: query
        required: true
        description: Make.
        schema:
          type: string
          minLength: 1
          maxLength: 40
      - name: model
        in: query
        required: false
        description: Model.
        schema:
          type: string
          minLength: 1
          maxLength: 60
      - $ref: '#/components/parameters/TrialMode'
  /api/vehicle/complaints:
    get:
      tags:
      - Vehicle
      summary: NHTSA consumer complaints for a US vehicle by (make, model
      description: NHTSA consumer complaints for a US vehicle by (make, model, modelYear). Returns the top N records (newest-filed first) with ODI number, affected component, plain-English summary, crash/fire flags, injury and death counts, partial VIN, and incident + filing dates. Backed by NHTSA's public complaints database; data is public-domain US government records.
      operationId: vehicle_complaints
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = NHTSA consumer-complaint records for the queried vehicle, newest first (total = all matching complaints upstream). To go straight from a VIN to its complaints (and recalls), see /api/vehicle/profile.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            odiNumber:
                              type: integer
                            manufacturer:
                              type: string
                              nullable: true
                            components:
                              type: string
                              nullable: true
                            summary:
                              type: string
                              nullable: true
                            crash:
                              type: boolean
                            fire:
                              type: boolean
                            numberOfInjuries:
                              type: integer
                            numberOfDeaths:
                              type: integer
                            vin:
                              type: string
                              nullable: true
                            dateOfIncident:
                              type: string
                              nullable: true
                            dateComplaintFiled:
                              type: string
                              nullable: true
                          required:
                          - odiNumber
                          - manufacturer
                          - components
                          - summary
                          - crash
                          - fire
                          - numberOfInjuries
                          - numberOfDeaths
                          - vin
                          - dateOfIncident
                          - dateComplaintFiled
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              make:
                                type: string
                              model:
                                type: string
                              modelYear:
                                type: integer
                              limit:
                                type: integer
                            required:
                            - make
                            - model
                            - modelYear
                            - limit
                            additionalProperties: false
                        required:
                        - query
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: vehicle.complaints
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: make
        in: query
        required: true
        description: 'Vehicle make. Examples: "Honda", "Tesla", "Ford".'
        schema:
          type: string
          minLength: 2
          maxLength: 40
      - name: model
        in: query
        required: true
        description: 'Vehicle model. Examples: "Accord", "Model 3", "F-150".'
        schema:
          type: string
          minLength: 1
          maxLength: 40
      - name: modelYear
        in: query
        required: true
        description: 4-digit model year.
        schema:
          type: integer
          minimum: 1949
          maximum: 2099
      - name: limit
        in: query
        required: false
        description: Max records to return, newest-filed first (1-100). Default 25.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - $ref: '#/components/parameters/TrialMode'
  /api/vehicle/decode-wmi:
    get:
      tags:
      - Vehicle
      summary: Decode a 3-character World Manufacturer Identifier (the
      description: Decode a 3-character World Manufacturer Identifier (the first three characters of a VIN) to the assigning manufacturer. Returns full manufacturer legal name, common short name, make, vehicle type, and the date NHTSA published the assignment. Useful for partial-VIN analysis — crash reports, damaged-vehicle photos, fleet records — where only the WMI is recoverable. Backed by NHTSA.gov vPIC; data is public-domain US government records.
      operationId: vehicle_decode-wmi
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = single manufacturer record decoded from a 3-char WMI prefix.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            wmi:
                              type: string
                            manufacturerName:
                              type: string
                              nullable: true
                            commonName:
                              type: string
                              nullable: true
                            make:
                              type: string
                              nullable: true
                            vehicleType:
                              type: string
                              nullable: true
                            dateAvailableToPublic:
                              type: string
                              nullable: true
                          required:
                          - wmi
                          - manufacturerName
                          - commonName
                          - make
                          - vehicleType
                          - dateAvailableToPublic
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: vehicle.decode-wmi
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: wmi
        in: query
        required: true
        description: '3-character WMI (the first 3 chars of a VIN). Case-insensitive. Examples: 1HG (American Honda), 5YJ (Tesla US), WBA (BMW).'
        schema:
          type: string
          minLength: 3
          maxLength: 3
          pattern: ^[A-HJ-NPR-Z0-9]{3}$
      - $ref: '#/components/parameters/TrialMode'
  /api/vehicle/fuel-economy:
    get:
      tags:
      - Vehicle
      summary: Official US EPA/DOE fuel-economy, fuel-cost, and emissions
      description: 'Official US EPA/DOE fuel-economy, fuel-cost, and emissions data for a vehicle by year + make + model. Because a model-year often has several powertrain configurations (engine/transmission), this returns one entry per configuration, each with: MPG city/highway/combined (or MPGe for EVs), CO2 tailpipe grams/mile, estimated annual fuel cost (USD), annual petroleum use (barrels), EPA greenhouse-gas score (1-10), 5-year savings vs the average new vehicle, plus transmission, drivetrain, cylinders, displacement, fuel type, EPA size class, and electric range for EV/PHEV. Authoritative EPA test figures — the real ratings an agent should not estimate. Keyless, public-domain (FuelEconomy.gov), covers model years 1984+.'
      operationId: vehicle_fuel-economy
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = powertrain configurations (one per engine/transmission); meta.total = count.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            description:
                              type: string
                            year:
                              type: integer
                              nullable: true
                            make:
                              type: string
                              nullable: true
                            model:
                              type: string
                              nullable: true
                            vehicleClass:
                              type: string
                              nullable: true
                            transmission:
                              type: string
                              nullable: true
                            drive:
                              type: string
                              nullable: true
                            cylinders:
                              type: number
                              nullable: true
                            displacementL:
                              type: number
                              nullable: true
                            fuelType:
                              type: string
                              nullable: true
                            mpgCity:
                              type: number
                              nullable: true
                            mpgHighway:
                              type: number
                              nullable: true
                            mpgCombined:
                              type: number
                              nullable: true
                            co2GramsPerMile:
                              type: number
                              nullable: true
                            annualFuelCostUSD:
                              type: number
                              nullable: true
                            annualPetroleumBarrels:
                              type: number
                              nullable: true
                            ghgScore:
                              type: number
                              nullable: true
                            fiveYearSavingsVsAvgUSD:
                              type: number
                              nullable: true
                            electricRangeMi:
                              type: number
                              nullable: true
                          required:
                          - id
                          - description
                          - year
                          - make
                          - model
                          - vehicleClass
                          - transmission
                          - drive
                          - cylinders
                          - displacementL
                          - fuelType
                          - mpgCity
                          - mpgHighway
                          - mpgCombined
                          - co2GramsPerMile
                          - annualFuelCostUSD
                          - annualPetroleumBarrels
                          - ghgScore
                          - fiveYearSavingsVsAvgUSD
                          - electricRangeMi
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              year:
                                type: integer
                              make:
                                type: string
                              model:
                                type: string
                            required:
                            - year
                            - make
                            - model
                            additionalProperties: false
                          total:
                            type: integer
                        required:
                        - query
                        - total
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: vehicle.fuel-economy
      x-2s-version: null
      x-2s-price:
        usd: 0.0045
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004500'
        protocols:
        - x402: {}
      parameters:
      - name: year
        in: query
        required: true
        description: Four-digit calendar year.
        schema:
          type: integer
          minimum: 1984
          maximum: 2100
      - name: make
        in: query
        required: true
        description: Make.
        schema:
          type: string
          minLength: 1
          maxLength: 40
      - name: model
        in: query
        required: true
        description: Model.
        schema:
          type: string
          minLength: 1
          maxLength: 60
      - $ref: '#/components/parameters/TrialMode'
  /api/vehicle/investigations:
    get:
      tags:
      - Vehicle
      summary: Chronological feed of NHTSA ODI (Office of Defects
      description: 'Chronological feed of NHTSA ODI (Office of Defects Investigation) investigations, newest first. Returns preliminary evaluations (PE), engineering analyses (EA), defect petitions (DP), and recall queries (RQ) — each with NHTSA ID, type code, open/close dates, status, subject, and full description (HTML stripped + raw). Useful for tracking what NHTSA is currently investigating (Tesla FSD, autonomous-vehicle crashes, Rivian suspension, etc.). NOTE: NHTSA''s endpoint does NOT support make/model/year filtering — use vehicle.recalls or vehicle.complaints for vehicle-scoped lookups. Public-domain US government records.'
      operationId: vehicle_investigations
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = chronological feed of NHTSA ODI investigations (total = all records upstream; paginate via meta.nextOffset).'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                            nhtsaId:
                              type: string
                            investigationNumber:
                              type: string
                            investigationType:
                              type: string
                            issueYear:
                              type: string
                            openDate:
                              type: string
                              nullable: true
                            latestActivityDate:
                              type: string
                              nullable: true
                            status:
                              type: string
                              nullable: true
                            subject:
                              type: string
                            description:
                              type: string
                            descriptionHtml:
                              type: string
                          required:
                          - id
                          - nhtsaId
                          - investigationNumber
                          - investigationType
                          - issueYear
                          - openDate
                          - latestActivityDate
                          - status
                          - subject
                          - description
                          - descriptionHtml
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              limit:
                                type: integer
                              offset:
                                type: integer
                              status:
                                type: string
                                nullable: true
                            required:
                            - limit
                            - offset
                            - status
                            additionalProperties: false
                          nextOffset:
                            type: integer
                            nullable: true
                          previousOffset:
                            type: integer
                            nullable: true
                        required:
                        - query
                        - nextOffset
                        - previousOffset
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: vehicle.investigations
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: limit
        in: query
        required: false
        description: Max records to return (1-100). Default 25.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: offset
        in: query
        required: false
        description: Offset into the chronological feed for pagination. Default 0.
        schema:
          type: integer
          minimum: 0
          maximum: 10000
          default: 0
      - name: status
        in: query
        required: false
        description: 'Filter by status: "O" (open), "C" (closed). Omit for all.'
        schema:
          type: string
          enum:
          - O
          - C
      - $ref: '#/components/parameters/TrialMode'
  /api/vehicle/manufacturers:
    get:
      tags:
      - Vehicle
      summary: Paginated list of every motor vehicle manufacturer NHTSA
      description: Paginated list of every motor vehicle manufacturer NHTSA tracks via vPIC. Each record includes the canonical Mfr_ID, full legal name, common short name (e.g., "Honda"), country, and the list of vehicle types the manufacturer produces (Passenger Car, Truck, Motorcycle, Bus, MPV, etc.). Pass the optional `manufacturer` param to substring-search Mfr_Name. 100 records per page. Backed by NHTSA.gov; data is public-domain US government records.
      operationId: vehicle_manufacturers
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = manufacturer directory page (100 per page) with canonical NHTSA IDs. total is null — vPIC does not report an overall count; request the next page until items is empty.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            mfrId:
                              type: integer
                            mfrName:
                              type: string
                            commonName:
                              type: string
                              nullable: true
                            country:
                              type: string
                              nullable: true
                            vehicleTypes:
                              type: array
                              items:
                                type: object
                                properties:
                                  name:
                                    type: string
                                  isPrimary:
                                    type: boolean
                                required:
                                - name
                                - isPrimary
                                additionalProperties: false
                          required:
                          - mfrId
                          - mfrName
                          - commonName
                          - country
                          - vehicleTypes
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              page:
                                type: integer
                              manufacturer:
                                type: string
                                nullable: true
                            required:
                            - page
                            - manufacturer
                            additionalProperties: false
                        required:
                        - query
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: vehicle.manufacturers
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: page
        in: query
        required: false
        description: 1-indexed page (100 manufacturers per page). Default 1.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 1
      - name: manufacturer
        in: query
        required: false
        description: 'Optional substring filter on the full Mfr_Name (case-insensitive on NHTSA side). Examples: "honda", "tesla", "general motors".'
        schema:
          type: string
          minLength: 2
          maxLength: 80
      - $ref: '#/components/parameters/TrialMode'
  /api/vehicle/models:
    get:
      tags:
      - Vehicle
      summary: Enumerate every model a manufacturer sold in a given model
      description: Enumerate every model a manufacturer sold in a given model year via NHTSA's vPIC taxonomy database. Returns canonical NHTSA Model IDs + names plus the Make ID + name for reference. Useful as a discovery step before VIN decode (when the agent only knows make + year) or as input validation for vehicle.recalls / vehicle.complaints. Backed by NHTSA.gov; data is public-domain US government records.
      operationId: vehicle_models
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = models sold by the make in the queried year, with canonical NHTSA IDs.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            modelId:
                              type: integer
                            modelName:
                              type: string
                            makeId:
                              type: integer
                            makeName:
                              type: string
                          required:
                          - modelId
                          - modelName
                          - makeId
                          - makeName
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              make:
                                type: string
                              modelYear:
                                type: integer
                            required:
                            - make
                            - modelYear
                            additionalProperties: false
                        required:
                        - query
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: vehicle.models
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: make
        in: query
        required: true
        description: 'Vehicle make. Case-insensitive on NHTSA side. Examples: "Honda", "Tesla", "Ford".'
        schema:
          type: string
          minLength: 2
          maxLength: 40
      - name: modelYear
        in: query
        required: true
        description: 4-digit model year.
        schema:
          type: integer
          minimum: 1949
          maximum: 2099
      - $ref: '#/components/parameters/TrialMode'
  /api/vehicle/profile:
    get:
      tags:
      - Vehicle
      summary: Vehicle 360 - decode a VIN and get its full safety picture
      description: 'Vehicle 360 — decode a VIN and get its full safety picture in one call. Returns the decoded vehicle (make, model, year, trim, engine, plant, body class, drivetrain — NHTSA vPIC) plus that exact make/model/year''s open safety recalls (with park-it / park-outside / over-the-air-update flags) and NHTSA owner complaints (crash/fire/injury/death flags). recalls and complaints are keyed to the decoded make+model+year, so they describe THIS vehicle, not a generic feed. Each section reports found/error independently. Pass vin (17 chars); optional modelYear disambiguates pre-1980 VINs. Used for used-car due diligence, fleet safety, insurance. Individual sources: /api/vehicle/vin-decode, /api/vehicle/recalls, /api/vehicle/complaints.'
      operationId: vehicle_profile
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      vin:
                        type: string
                      vehicle:
                        type: object
                        properties:
                          found:
                            type: boolean
                          error:
                            type: string
                            nullable: true
                        required:
                        - found
                        - error
                        additionalProperties: {}
                      recalls:
                        type: object
                        properties:
                          found:
                            type: boolean
                          error:
                            type: string
                            nullable: true
                          count:
                            type: number
                            nullable: true
                          recalls:
                            type: array
                            items:
                              type: object
                              additionalProperties: {}
                        required:
                        - found
                        - error
                        - count
                        - recalls
                        additionalProperties: false
                      complaints:
                        type: object
                        properties:
                          found:
                            type: boolean
                          error:
                            type: string
                            nullable: true
                          count:
                            type: number
                            nullable: true
                        required:
                        - found
                        - error
                        - count
                        additionalProperties: false
                      sources:
                        type: array
                        items:
                          type: object
                          additionalProperties: {}
                    required:
                    - vin
                    - vehicle
                    - recalls
                    - complaints
                    - sources
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: vehicle.profile
      x-2s-version: null
      x-2s-price:
        usd: 0.0144
      x-2s-accepts:
      - x402
      x-2s-response-shape: legacy
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.014400'
        protocols:
        - x402: {}
      parameters:
      - name: vin
        in: query
        required: true
        description: VIN.
        schema:
          type: string
          minLength: 17
          maxLength: 17
      - name: modelYear
        in: query
        required: false
        description: Model year.
        schema:
          type: integer
          minimum: 1949
          maximum: 2099
      - $ref: '#/components/parameters/TrialMode'
  /api/vehicle/recalls:
    get:
      tags:
      - Vehicle
      summary: NHTSA recall campaigns for a US vehicle by (make, model
      description: NHTSA recall campaigns for a US vehicle by (make, model, modelYear). Returns every open + historical campaign with the NHTSA campaign number, manufacturer, affected component, plain-English summary/consequence/remedy text, and the parkIt / parkOutside fire-risk advisories. Backed by NHTSA's public recalls database; data is public-domain US government records.
      operationId: vehicle_recalls
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = recall campaigns matching the (make, model, modelYear) tuple. To go straight from a VIN to its recalls (and complaints), see /api/vehicle/profile.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            campaignNumber:
                              type: string
                            reportReceivedDate:
                              type: string
                              nullable: true
                            manufacturer:
                              type: string
                              nullable: true
                            component:
                              type: string
                              nullable: true
                            summary:
                              type: string
                              nullable: true
                            consequence:
                              type: string
                              nullable: true
                            remedy:
                              type: string
                              nullable: true
                            notes:
                              type: string
                              nullable: true
                            parkIt:
                              type: boolean
                            parkOutside:
                              type: boolean
                            overTheAirUpdate:
                              type: boolean
                          required:
                          - campaignNumber
                          - reportReceivedDate
                          - manufacturer
                          - component
                          - summary
                          - consequence
                          - remedy
                          - notes
                          - parkIt
                          - parkOutside
                          - overTheAirUpdate
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              make:
                                type: string
                              model:
                                type: string
                              modelYear:
                                type: integer
                            required:
                            - make
                            - model
                            - modelYear
                            additionalProperties: false
                        required:
                        - query
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: vehicle.recalls
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: make
        in: query
        required: true
        description: 'Vehicle make. Examples: "Honda", "Toyota", "Tesla". Case-insensitive on NHTSA side.'
        schema:
          type: string
          minLength: 2
          maxLength: 40
      - name: model
        in: query
        required: true
        description: 'Vehicle model. Examples: "Accord", "Model 3", "F-150".'
        schema:
          type: string
          minLength: 1
          maxLength: 40
      - name: modelYear
        in: query
        required: true
        description: 4-digit model year.
        schema:
          type: integer
          minimum: 1949
          maximum: 2099
      - $ref: '#/components/parameters/TrialMode'
  /api/vehicle/safety-ratings:
    get:
      tags:
      - Vehicle
      summary: NHTSA NCAP 5-Star crash-test ratings for a US vehicle by
      description: NHTSA NCAP 5-Star crash-test ratings for a US vehicle by (make, model, modelYear). Returns one item per crash-tested body style with the overall star rating, front/side/rollover sub-ratings, modeled rollover probability, crash-avoidance tech flags (electronic stability control, forward-collision warning, lane-departure warning), and complaint/recall/investigation counts. A vehicle with no crash testing returns an empty list (a valid result, not an error). Backed by NHTSA's public 5-Star Safety Ratings program; data is public-domain US government records.
      operationId: vehicle_safety-ratings
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = crash-tested body-style variants for the (make, model, modelYear) tuple. Star ratings are 1-5 or null (not rated). For recall campaigns or consumer complaints on the same vehicle, see /api/vehicle/recalls and /api/vehicle/complaints.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            vehicleId:
                              type: integer
                            vehicleDescription:
                              type: string
                            overallRating:
                              type: number
                              nullable: true
                            frontCrash:
                              type: object
                              properties:
                                overall:
                                  type: number
                                  nullable: true
                                driverSide:
                                  type: number
                                  nullable: true
                                passengerSide:
                                  type: number
                                  nullable: true
                              required:
                              - overall
                              - driverSide
                              - passengerSide
                              additionalProperties: false
                            sideCrash:
                              type: object
                              properties:
                                overall:
                                  type: number
                                  nullable: true
                                driverSide:
                                  type: number
                                  nullable: true
                                passengerSide:
                                  type: number
                                  nullable: true
                                barrierOverall:
                                  type: number
                                  nullable: true
                                poleRating:
                                  type: number
                                  nullable: true
                              required:
                              - overall
                              - driverSide
                              - passengerSide
                              - barrierOverall
                              - poleRating
                              additionalProperties: false
                            rollover:
                              type: object
                              properties:
                                rating:
                                  type: number
                                  nullable: true
                                possibility:
                                  type: number
                                  nullable: true
                                dynamicTipResult:
                                  type: string
                                  nullable: true
                              required:
                              - rating
                              - possibility
                              - dynamicTipResult
                              additionalProperties: false
                            driverAssist:
                              type: object
                              properties:
                                electronicStabilityControl:
                                  type: string
                                  nullable: true
                                forwardCollisionWarning:
                                  type: string
                                  nullable: true
                                laneDepartureWarning:
                                  type: string
                                  nullable: true
                              required:
                              - electronicStabilityControl
                              - forwardCollisionWarning
                              - laneDepartureWarning
                              additionalProperties: false
                            complaintsCount:
                              type: integer
                            recallsCount:
                              type: integer
                            investigationCount:
                              type: integer
                          required:
                          - vehicleId
                          - vehicleDescription
                          - overallRating
                          - frontCrash
                          - sideCrash
                          - rollover
                          - driverAssist
                          - complaintsCount
                          - recallsCount
                          - investigationCount
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              make:
                                type: string
                              model:
                                type: string
                              modelYear:
                                type: integer
                            required:
                            - make
                            - model
                            - modelYear
                            additionalProperties: false
                        required:
                        - query
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: vehicle.safety-ratings
      x-2s-version: null
      x-2s-price:
        usd: 0.0075
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.007500'
        protocols:
        - x402: {}
      parameters:
      - name: make
        in: query
        required: true
        description: 'Vehicle make. Examples: "Honda", "Toyota", "Tesla". Case-insensitive on NHTSA side.'
        schema:
          type: string
          minLength: 2
          maxLength: 40
      - name: model
        in: query
        required: true
        description: 'Vehicle model. Examples: "Accord", "Model 3", "F-150".'
        schema:
          type: string
          minLength: 1
          maxLength: 40
      - name: modelYear
        in: query
        required: true
        description: 4-digit model year. NCAP coverage is strongest from ~2011 onward.
        schema:
          type: integer
          minimum: 1949
          maximum: 2099
      - $ref: '#/components/parameters/TrialMode'
  /api/vehicle/vin-decode:
    get:
      tags:
      - Vehicle
      summary: Decode a 17-character VIN to manufacturer-supplied vehicle
      description: Decode a 17-character VIN to manufacturer-supplied vehicle metadata via NHTSA's vPIC database. Returns identity (year, make, model, trim, series, body class, manufacturer), assembly plant (city, state, country), engine (cylinders, displacement, HP, fuel type, configuration, engine model), transmission (style, speeds), and body/weight specs. Curated to the ~30 fields agents actually use from vPIC's ~140-field response. Backed by NHTSA.gov; data is public-domain US government records.
      operationId: vehicle_vin-decode
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = single decoded-VIN record (identity, plant of origin, powertrain, body class). For the decode PLUS this vehicle''s recalls and complaints in one call, see /api/vehicle/profile.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            vin:
                              type: string
                            modelYear:
                              type: string
                              nullable: true
                            make:
                              type: string
                              nullable: true
                            model:
                              type: string
                              nullable: true
                            trim:
                              type: string
                              nullable: true
                            series:
                              type: string
                              nullable: true
                            bodyClass:
                              type: string
                              nullable: true
                            manufacturer:
                              type: string
                              nullable: true
                            plant:
                              type: object
                              properties:
                                city:
                                  type: string
                                  nullable: true
                                state:
                                  type: string
                                  nullable: true
                                country:
                                  type: string
                                  nullable: true
                              required:
                              - city
                              - state
                              - country
                              additionalProperties: false
                            engine:
                              type: object
                              properties:
                                cylinders:
                                  type: string
                                  nullable: true
                                displacementL:
                                  type: string
                                  nullable: true
                                hp:
                                  type: string
                                  nullable: true
                                fuelTypePrimary:
                                  type: string
                                  nullable: true
                                configuration:
                                  type: string
                                  nullable: true
                                model:
                                  type: string
                                  nullable: true
                              required:
                              - cylinders
                              - displacementL
                              - hp
                              - fuelTypePrimary
                              - configuration
                              - model
                              additionalProperties: false
                            transmission:
                              type: object
                              properties:
                                style:
                                  type: string
                                  nullable: true
                                speeds:
                                  type: string
                                  nullable: true
                              required:
                              - style
                              - speeds
                              additionalProperties: false
                            doors:
                              type: string
                              nullable: true
                            driveType:
                              type: string
                              nullable: true
                            vehicleType:
                              type: string
                              nullable: true
                            gvwrClass:
                              type: string
                              nullable: true
                          required:
                          - vin
                          - modelYear
                          - make
                          - model
                          - trim
                          - series
                          - bodyClass
                          - manufacturer
                          - plant
                          - engine
                          - transmission
                          - doors
                          - driveType
                          - vehicleType
                          - gvwrClass
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: vehicle.vin-decode
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: vin
        in: query
        required: true
        description: 17-character VIN. Case-insensitive. Excludes letters I, O, and Q per VIN standard.
        schema:
          type: string
          minLength: 17
          maxLength: 17
          pattern: ^[A-HJ-NPR-Z0-9]{17}$
      - name: modelYear
        in: query
        required: false
        description: Optional model-year hint — disambiguates VINs where the year-digit wraps (A=1980/2010, etc.).
        schema:
          type: integer
          minimum: 1949
          maximum: 2099
      - $ref: '#/components/parameters/TrialMode'
components:
  schemas:
    Source:
      type: object
      description: 'Provenance of the data: upstream provider, source URL, and license.'
      properties:
        provider:
          type: string
          description: Upstream data provider.
        url:
          type: string
          description: Source URL or documentation link.
        license:
          type: string
          description: License / usage terms for the data.
    CallMeta:
      type: object
      description: Per-call meta envelope — endpoint id, cost, caller kind, settlement details.
    X402PaymentRequiredV2:
      type: object
      description: x402 v2 PaymentRequired envelope. Pick any entry from accepts[], sign for that rail, retry with the PAYMENT-SIGNATURE header.
      required:
      - x402Version
      - accepts
      properties:
        x402Version:
          type: integer
          const: 2
        error:
          type: string
          description: Human-readable reason payment is required.
        resource:
          type: string
          description: The resource URL being purchased.
        accepts:
          type: array
          description: Payment requirement options, one per supported network (Base USDC, Solana USDC).
          items:
            type: object
            required:
            - scheme
            - network
            - amount
            - asset
            - payTo
            - maxTimeoutSeconds
            properties:
              scheme:
                type: string
                enum:
                - exact
              network:
                type: string
                description: CAIP-2 network id, e.g. "eip155:8453" (Base) or "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp".
              amount:
                type: string
                description: Price in atomic asset units (USDC has 6 decimals).
              asset:
                type: string
                description: Asset contract address / mint.
              payTo:
                type: string
                description: Treasury address to pay.
              maxTimeoutSeconds:
                type: integer
              extra:
                type: object
                description: 'Rail-specific extras (EVM: EIP-712 domain name/version; Solana: feePayer).'
                additionalProperties: true
        extensions:
          type: object
          description: Optional discovery metadata (e.g. bazaar input/output schemas).
          additionalProperties: true
  responses:
    PaymentRequired:
      description: Payment required. Body contains the x402 PaymentRequirements envelope with a multi-network accepts array; the per-call price is in accepts[].amount (and on the operation as x-2s-price). Sign for whichever rail you hold USDC on (EIP-3009 for Base, partial SPL transfer for Solana) and retry with the PAYMENT-SIGNATURE header (X-PAYMENT also accepted for v1 clients).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/X402PaymentRequiredV2'
    UpstreamError:
      description: Upstream provider error.
    MethodNotAllowed:
      description: Method not allowed — see `Allow` header for the supported method.
    ServerError:
      description: Internal server error.
    BadRequest:
      description: Bad request — invalid parameters.
  parameters:
    TrialMode:
      name: trial
      in: query
      required: false
      description: 'Try before you buy. Set to 1 for one free real call per endpoint per hour — no wallet or payment needed — to verify the endpoint before paying. Equivalent to sending the "X-2s-Trial: 1" request header. Works on every endpoint.'
      schema:
        type: integer
        enum:
        - 1
  securitySchemes:
    x402Payment:
      type: apiKey
      in: header
      name: PAYMENT-SIGNATURE
      description: 'x402 protocol v2: base64-encoded PaymentPayload. Call any paid endpoint without auth to receive a 402 with a multi-network PaymentRequirements envelope. Sign for either rail: EIP-3009 transferWithAuthorization (Base USDC) OR a partial SPL token transfer (Solana USDC). Retry with PAYMENT-SIGNATURE header. X-PAYMENT is also accepted for v1 buyer clients. See https://x402.org.'