# Vindex API — Canada-aware vehicle intelligence for AI agents — per-call, no signup. (v0.2.1)

> Vehicle Intelligence for AI agents — Canada-aware, per-call, no signup. Pay per call with x402
> (USDC on Base) to read MERGED US (NHTSA) + Canada (Transport Canada) recalls with the
> full decoded 17-char VIN folded in, get LLM-clustered known-issue reports that bundle a
> reliability-aggregates block and the full decode (every issue cites verified ODI complaint numbers),
> and itemized used-car closing costs for all of Canada (10 provinces
> + 3 territories) + all 50 US states & DC. FREE /v1/sample/*
> endpoints return every response shape for one fixed sample vehicle so you can try before you pay.
> Informational data only — NOT professional/purchase advice, and NOT a vehicle-history report.

## Base URL
- API: https://api.vindexapi.dev
- This document: https://api.vindexapi.dev/llms.txt  ·  Extended: https://api.vindexapi.dev/llms-full.txt
- Discovery (JSON): https://api.vindexapi.dev/discovery
- OpenAPI 3.1: https://api.vindexapi.dev/openapi.json
- x402 manifest: https://api.vindexapi.dev/.well-known/x402
- Agent card (A2A): https://api.vindexapi.dev/.well-known/agent-card.json
- Terms: https://api.vindexapi.dev/terms.txt

## Free endpoints (no auth, no payment)

| Method | Path | Description |
|--------|------|-------------|
| GET | /.well-known/hexanon | 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) |
| GET | /v1/sample/decode | 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) |
| GET | /v1/sample/recalls | 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) |
| GET | /v1/sample/known-issues | 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) |
| GET | /v1/sample/purchase-costs | 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) |

## Paid endpoints (x402 V2, USDC on Base, per-call)

| Method | Path | Price | Description |
|--------|------|-------|-------------|
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |

## How to pay (x402)
Each paid call answers a 402 challenge; sign an x402 `exact` USDC authorization for one advertised rail (Base) and retry. Standard @x402 V2 clients send the `PAYMENT-SIGNATURE` header; legacy clients send `X-PAYMENT`. Prices are USD, settled as USDC (6 decimals).

## Links
- Docs: https://api.vindexapi.dev/llms.txt
- Full: https://api.vindexapi.dev/llms-full.txt
- OpenAPI: https://api.vindexapi.dev/openapi.json
- Discovery: https://api.vindexapi.dev/discovery
- Agent card: https://api.vindexapi.dev/.well-known/agent-card.json
- Website: https://vindexapi.dev

## What Vindex is
Vindex aggregates free, public-domain vehicle-safety data and sells thin intelligence layers on top, priced per call. It is the ONLY API that merges US (NHTSA) and Canada (Transport Canada) recalls in one response, with Open Government Licence – Canada attribution. VINs are used only as cache keys (up to 90 days), never linked to a person; no owner/registrant data is collected or returned. Vindex is NOT a vehicle-history report — it makes no liens/accidents/odometer claims.

Every JSON object response also carries a `disclaimer` string.

## Errors
- 400 — invalid VIN (must be 17 chars, no I/O/Q) or bad params (e.g. missing province/price/sale_type)
- 402 — payment required / verification or settlement failed (you were NOT charged)
- 422 — vPIC could not resolve make/model/year for this VIN (`vpicErrorText` explains)
- 502 — an upstream public-data source was unavailable (served stale where possible)
- known-issues below 15 complaints → **200** `{ "status": "insufficient_data", … }` (uncharged, not an error)

## Data sources & attribution
- NHTSA vPIC + api.nhtsa.gov (US federal, public domain) — decode, recalls, complaints
- Transport Canada vehicle-recall-database — Canadian recalls; Contains information licensed under the Open Government Licence – Canada.

## Disclaimer
Informational vehicle data aggregated from public sources; not professional, legal, or purchasing advice; provided as-is without warranty. NOT a vehicle-history report (no liens/accidents/odometer). Recall/complaint data reflects the source databases at fetch time. Terms: https://api.vindexapi.dev/terms.txt