# Vindex API — Full Agent Reference (v0.2.1)

> Extended reference: every endpoint with full description, parameters, and an example JSON
> body. Compact version: https://api.vindexapi.dev/llms.txt · OpenAPI: https://api.vindexapi.dev/openapi.json

## Base URL & discovery surface
- API base: https://api.vindexapi.dev
- /llms.txt (compact) · /llms-full.txt (this) · /discovery (JSON enumeration)
- /openapi.json (OpenAPI 3.1) · /.well-known/x402 · /.well-known/agent-card.json
- Payment: x402 V2 · Networks: eip155:8453 · Asset: USDC · Scheme: exact

## GET /v1/decode   ($0.01)
Paid ($0.01 USDC via x402). Decodes a 17-char VIN through NHTSA vPIC and returns the normalized decoded vehicle (make/model/year/engine/body/…) with fetch provenance, PLUS a `warranty` block giving the ORIGINAL factory new-vehicle warranty terms (basic/powertrain/corrosion/roadside/EV-battery) keyed off the decoded make + model-year. Warranty terms are the manufacturer's original coverage as sold — NOT warranty-remaining, and NOT extended-warranty campaigns, recalls, or emissions warranties. The cheapest call when you only need the decode — the same `vehicle` object is also folded into /v1/recalls and /v1/known-issues. Compute-first / settle-after. Free fixed-sample preview of this exact shape: GET /v1/sample/decode.

Parameters:
- `vin` (string, query, required) — 17-character VIN (no I/O/Q).

Settlement: compute-first.

Example response:
```json
{
  "vin": "1FA6P8TH5J5100000",
  "vehicle": {
    "year": 2018,
    "make": "FORD",
    "model": "Mustang",
    "bodyClass": "Coupe"
  },
  "provenance": {
    "source": "nhtsa-vpic",
    "cache": "hit"
  },
  "charged": true
}
```

## GET /v1/recalls   ($0.01)
Paid ($0.01 USDC via x402). Decodes the VIN and returns the FULL decoded vehicle (the same payload as /v1/decode is folded in here), then merges NHTSA (US) and Transport Canada (CA) recalls into one response — the only API combining both. 24h cache per source; stale served on failure. Canadian detail capped at the 25 most-recent recalls. OGL–Canada attribution. Compute-first / settle-after. Free fixed-sample preview of this exact shape: GET /v1/sample/recalls.

Parameters:
- `vin` (string, query, required) — 17-character VIN (no I/O/Q).

Settlement: compute-first.

Example response:
```json
{
  "vin": "1FA6P8TH5J5100000",
  "vehicle": {
    "year": 2018,
    "make": "FORD",
    "model": "Mustang"
  },
  "counts": {
    "us": 3,
    "canada": 1
  },
  "charged": true
}
```

## GET /v1/known-issues   ($0.05)
Paid ($0.05 USDC via x402). Clusters NHTSA owner complaints into named failure modes; EVERY cited ODI number is programmatically validated against the input complaint set (hallucination-gated) and every issue carries ≥2 verified citations. Severity signals per issue are summed from the CITED complaints only. The response also bundles a `reliability` aggregates block (top components, severity signals, US/Canada recall counts incl. Canadian units affected — reliability was merged into known-issues on 2026-07-07), the full decoded `vehicle` (same payload as /v1/decode), and `complaintsAnalyzed`, the size of the recent-weighted stratified sample the LLM actually saw (vs `complaintCount`, the total). Refuses UNCHARGED below 15 complaints (returns 200 status:insufficient_data) — but still returns the decode + reliability block for free. 90-day cache. Compute-first / settle-after. Free fixed-sample preview of this exact shape: GET /v1/sample/known-issues.

Parameters:
- `vin` (string, query, required) — 17-character VIN (no I/O/Q).

Settlement: compute-first.

Example response:
```json
{
  "status": "ok",
  "vehicle": {
    "year": 2018,
    "make": "FORD",
    "model": "Mustang"
  },
  "complaintCount": 312,
  "complaintsAnalyzed": 150,
  "knownIssues": [
    {
      "count": 2,
      "title": "Electric power steering assist failure",
      "trend": "rising",
      "confidence": 0.9,
      "odiNumbers": [
        11234567,
        11245678
      ],
      "componentTags": [
        "STEERING",
        "ELECTRICAL SYSTEM"
      ],
      "severitySignals": {
        "fires": 0,
        "crashes": 0,
        "injuries": 0
      }
    }
  ],
  "charged": true
}
```

## GET /v1/purchase-costs   ($0.02)
Paid ($0.02 USDC via x402). Government-imposed closing costs of buying a used passenger vehicle, unified across both countries via `country=CA|US`. CA: any of Canada's 10 provinces + 3 territories (BC, AB, SK, MB, ON, QC, NB, NS, PE, NL, YT, NT, NU) — provincial/territorial sales tax (PST/RST/QST/HST or GST-only) plus transfer/registration/plate fees and inspection; tax is flat on the whole price at the highest bracket whose threshold the price meets (BC private 12% → 15% ≥ $125,000 → 20% ≥ $150,000); Alberta + the three territories levy no private-sale tax; dealer sales add 5% GST except in HST provinces (ON/NB/NS/PE/NL). US: any of the 50 states or DC — sales/use/excise tax, title, first-year registration, inspection, and (for dealer sales) a dealer documentation fee; special regimes handled automatically (DC tiered title-excise range, IL flat RUT-50 private-party table, SC 5% IMF capped at $500, and AK/AZ/HI/MT/NV/NH/OR no private-party sales tax). Each line carries a source URL and confidence. Figures verified 2026-07-04. Compute-first / settle-after. Free fixed-sample preview of this exact shape: GET /v1/sample/purchase-costs.

Parameters:
- `country` (string, query, required) — one of CA | US — Country selector (case-insensitive): CA routes to the Canadian per-jurisdiction rules, US to the per-state rules.
- `price` (number, query, required) — Agreed sale price in the country's currency (> 0, ≤ 5,000,000).
- `sale_type` (string, query, required) — one of private | dealer — Private sale or dealer sale.
- `province` (string, query, optional) — one of BC | AB | SK | MB | ON | QC | NB | NS | PE | NL | YT | NT | NU — CANADA ONLY (required when country=CA): two-letter province/territory code (case-insensitive).
- `state` (string, query, optional) — US ONLY (required when country=US): two-letter state code (case-insensitive), one of the 50 states or DC.
- `family_gift` (boolean, query, optional) — CANADA ONLY, private sales only — applies the jurisdiction's family/related-individual gift exemption ($0 tax) where one exists.
- `buyer_has_plates` (boolean, query, optional) — CANADA ONLY — selects plate-dependent fee lines where the jurisdiction distinguishes them (e.g. Ontario: true → vehicle permit only $32; false → permit + new plate $59).
- `trade_in` (number, query, optional) — US ONLY — trade-in value in USD (≥ 0, < price). Deducted from the tax base only for a dealer sale in a state granting a FULL trade-in credit.
- `local_rate` (number, query, optional) — US ONLY — exact county/city surtax percentage (0–15). When omitted, the sales-tax line carries a range up to the state's maximum local rate.

Settlement: compute-first.

Example response:
```json
{
  "country": "CA",
  "province": "ON",
  "provinceName": "Ontario",
  "totalKnownCad": 3287.5,
  "charged": true
}
```

## GET /v1/prepurchase   ($0.25)
Whole-job bundle for agents advising a vehicle purchase. One payment returns the normalized VIN decode, safety recalls, known-issue/reliability summary, and CA/US purchase+ownership cost estimate for the decoded vehicle. Equivalent to 4 separate paid calls. Composed in-process from the same data as /v1/decode, /v1/recalls, /v1/known-issues and /v1/purchase-costs (no extra upstream fan-out beyond those). The decode is computed FIRST — an invalid VIN or decode failure returns UNCHARGED (no settle). The response then settles only if the decode succeeded AND at least 2 of the 3 secondary sections (recalls, known-issues, purchase-costs) are available; otherwise it returns UNCHARGED { error: 'insufficient_sections', sections: {…} }. A section that failed but was still charged appears as sections.<name>:'unavailable' with the rest of the report intact. The cost section is a jurisdiction-level estimate (the bundle takes no price/province/state) — call GET /v1/purchase-costs for an exact itemized figure. Compute-first / settle-after. Each section carries its own fetch provenance.

Parameters:
- `vin` (string, query, required) — 17-char VIN.
- `country` (string, query, optional) — one of CA | US — CA (default) or US — cost section jurisdiction.

Settlement: compute-first.

Example response:
```json
{
  "vin": "1FTFW1ET5DFC10312",
  "vehicle": {
    "make": "FORD",
    "model": "F-150",
    "modelYear": 2013,
    "trim": "XLT",
    "bodyClass": "Pickup",
    "engine": {
      "model": "V8",
      "cylinders": 8,
      "displacementL": 5,
      "fuelType": "Gasoline"
    }
  },
  "recalls": {
    "count": 6,
    "items": [
      {
        "campaign": "18V123000",
        "component": "ELECTRICAL SYSTEM",
        "summary": "Wiring may short and cause a fire."
      }
    ]
  },
  "knownIssues": {
    "reliabilitySummary": "842 NHTSA complaints; 3 named failure mode(s) clustered from 150 analyzed.",
    "topIssues": [
      {
        "title": "Cam phaser failure (5.0L)",
        "componentTags": [
          "ENGINE"
        ],
        "odiNumbers": [
          11234567,
          11245678
        ],
        "count": 2
      }
    ]
  },
  "purchaseCosts": {
    "country": "CA",
    "estimatedFees": {
      "totalKnownCad": 3287.5,
      "estimatedTotalRangeCad": {
        "low": 3287.5,
        "high": 3402.5
      }
    },
    "notes": "Representative jurisdiction-level estimate; call /v1/purchase-costs for exact per-jurisdiction figures."
  },
  "sections": {
    "decode": "ok",
    "recalls": "ok",
    "knownIssues": "ok",
    "purchaseCosts": "ok"
  },
  "charged": true
}
```

## GET /.well-known/hexanon   (FREE)
Catalog of all products in the Hexanon family (x402 data & intelligence APIs for AI agents) — names, taglines, API base URLs, docs, MCP packages. Same catalog on every Hexanon product; canonical copy at https://api.moltalyzer.xyz/.well-known/hexanon.

Rate limit: 5/min.

Example response:
```json
{
  "family": "Hexanon",
  "products": [
    {
      "slug": "vindex",
      "name": "Vindex",
      "api": "https://api.vindexapi.dev",
      "mcp": "vindex-mcp"
    }
  ]
}
```

## GET /v1/sample/decode   (FREE)
Free, no payment. Normalized NHTSA vPIC decode for the fixed sample vehicle. Same shape as paid GET /v1/decode plus `sample: true` and `note`.

Rate limit: 5/min.

Example response:
```json
{
  "sample": true,
  "vin": "1FTFW1ET5DFC10312",
  "vehicle": {
    "year": 2013,
    "make": "FORD",
    "model": "F-150"
  }
}
```

## GET /v1/sample/recalls   (FREE)
Free, no payment. Merged NHTSA (US) + Transport Canada (CA) recalls + full decoded vehicle for the fixed sample vehicle. Same shape as paid GET /v1/recalls plus `sample: true` and `note`.

Rate limit: 5/min.

Example response:
```json
{
  "sample": true,
  "vin": "1FTFW1ET5DFC10312",
  "counts": {
    "us": 3,
    "canada": 3
  }
}
```

## GET /v1/sample/known-issues   (FREE)
Free, no payment. LLM-clustered known-issues + reliability-aggregates block + full decoded vehicle for the fixed sample vehicle. Same shape as paid GET /v1/known-issues plus `sample: true` and `note`. A non-'ok' synthesis status is served as-is with 200 (samples never 503), still carrying the decode + reliability block.

Rate limit: 2/min.

Example response:
```json
{
  "sample": true,
  "status": "ok",
  "vin": "1FTFW1ET5DFC10312",
  "complaintCount": 287
}
```

## GET /v1/sample/purchase-costs   (FREE)
Free, no payment. Returns `{ sample: true, note, ca, us }`: `ca` is the Ontario $25,000-private result (same shape as paid GET /v1/purchase-costs?country=CA) and `us` is the California $25,000-private result (same shape as paid GET /v1/purchase-costs?country=US).

Rate limit: 10/min.

Example response:
```json
{
  "sample": true,
  "ca": {
    "country": "CA",
    "province": "ON"
  },
  "us": {
    "country": "US",
    "state": "CA"
  }
}
```

## Payment
Strictly pay-per-call. An unpaid paid-route request returns a 402 challenge whose accepts[] lists one exact USDC rail per network (Base). Sign one rail and retry with PAYMENT-SIGNATURE (x402 V2) or X-PAYMENT (legacy).