# Vindex — Full Agent Reference (v0.1.0) > Vehicle Intelligence for AI agents — Canada-aware, per-call, no signup. This is the extended > reference: every endpoint with real-shaped JSON, the payment model, the full error catalogue, and > integration notes. Compact version: https://api.vindexapi.dev/llms.txt · OpenAPI: https://api.vindexapi.dev/openapi.json > Informational data only — NOT professional/purchase advice, and NOT a vehicle-history report. ## 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) · /api (human quickstart) - /.well-known/x402 (+ /.well-known/x402.json) · /.well-known/agent-card.json (+ /agent-card) - /robots.txt · /sitemap.xml · Terms: https://api.vindexapi.dev/terms.txt - Payment: x402 V2 · Networks: eip155:8453 (Base) + solana · Asset: USDC · Scheme: exact Every JSON **object** response carries a top-level `disclaimer` string (arrays/primitives are left untouched). VINs are used only as cache keys (≤90 days), never linked to a person; no owner or registrant data is collected or returned. =============================================================================== FREE ENDPOINTS (no auth, no payment) =============================================================================== ## GET /health Liveness + the configured payment mode. Never touches the database. ```json { "ok": true, "service": "vindex-api", "mode": "live", "ts": "2026-07-04T12:00:00.000Z", "disclaimer": "…" } ``` `mode` is `live` or `mock`. ## GET /v1/sample/* — free fixed-sample endpoints Every /v1/sample/* endpoint ALWAYS serves the same fixed sample vehicle — a 2013 Ford F-150, VIN `1FTFW1ET5DFC10312` (rich complaints + US/CA recalls) — computed live through the normal pipeline (upstream + Postgres caches, NOT baked static JSON), so the samples stay real and fresh. They never touch the payment plane. Each response is the SAME shape as its paid per-VIN twin, plus a top-level `sample: true` and a `note`. Use them to learn every response shape before you pay. | Endpoint | Mirrors | Key fields | |----------|---------|-----------| | GET /v1/sample/decode | paid GET /v1/decode | `vehicle` (2013 FORD F-150), `provenance` | | GET /v1/sample/recalls | paid GET /v1/recalls | `recalls.us` / `recalls.canada`, `counts`, OGL attribution | | GET /v1/sample/reliability | paid GET /v1/reliability | `reliability.complaintCount`, `topComponents`, severity, recall counts | | GET /v1/sample/known-issues | paid GET /v1/known-issues | `status` + (when ok) `knownIssues[]`; served AS-IS with 200 (never 503) | | GET /v1/sample/purchase-costs | paid GET /v1/ca/purchase-costs + /v1/us/purchase-costs | `ca` (Ontario $25,000 private) + `us` (California $25,000 private) — one preview per country | ```json { "sample": true, "note": "Fixed sample vehicle (2013 Ford F-150, VIN 1FTFW1ET5DFC10312). Pay per-call for any VIN — see /discovery.", "vehicle": { "vin": "1FTFW1ET5DFC10312", "year": 2013, "make": "FORD", "model": "F-150", … }, "provenance": { "source": "nhtsa-vpic", "fetchedAt": "…", "cache": "hit" }, "disclaimer": "…" } ``` The purchase-costs sample is the one endpoint that is NOT VIN-based: it returns `{ sample, note, ca, us }` where `ca` is the Ontario $25,000-private result and `us` is the California $25,000-private result — one preview per country, both computed live from the rules engines. Sample endpoints return 502 only if an upstream public-data source is unavailable and uncached. =============================================================================== PAID ENDPOINTS (x402 V2 — USDC on Base or Solana, per-call) =============================================================================== Payment model: strictly pay-per-call (no bundles, no entitlements, no receipts). An unpaid paid-route request returns a 402 challenge whose `accepts[]` lists one entry per rail (Base + Solana). Sign an x402 `exact` USDC authorization for one rail and retry the SAME request with the payment header: standard @x402 V2 clients send `PAYMENT-SIGNATURE`; legacy clients send `X-PAYMENT`. The server is compute-first: it computes the answer, then settles + charges ONLY when the answer is billable — errors and below-threshold refusals are returned UNCHARGED. A mock mode (`x-mock-payment` header) exists for testing; production uses live x402. 402 challenge shape (identical across the three paid routes; price/description vary): ```json { "x402Version": 2, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "asset": "USDC", "price": "$0.25", "payTo": "0x…", "description": "Vindex known-issues for one VIN", "mimeType": "application/json" }, { "scheme": "exact", "network": "solana", "asset": "USDC", "price": "$0.25", "payTo": "…", "description": "Vindex known-issues for one VIN", "mimeType": "application/json" } ], "terms": "https://api.vindexapi.dev/terms.txt" } ``` ## GET /v1/decode?vin=VIN ($0.01) NHTSA vPIC normalized decode. `vin` is a 17-char VIN (chars A–Z0–9, excluding I/O/Q). 90-day cache; stale is served on upstream failure. `provenance.cache` is `hit` or `miss`. (Free preview of this exact shape: GET /v1/sample/decode.) ```json { "vin": "1FA6P8TH5J5100000", "vehicle": { "vin": "1FA6P8TH5J5100000", "year": 2018, "make": "FORD", "model": "Mustang", "trim": "EcoBoost", "series": null, "bodyClass": "Coupe", "vehicleType": "PASSENGER CAR", "driveType": "RWD", "engine": { "model": null, "cylinders": 4, "displacementL": 2.3, "fuelType": "Gasoline" }, "plantCountry": "UNITED STATES (USA)", "vpicErrorCode": "0", "vpicErrorText": null }, "provenance": { "source": "nhtsa-vpic", "fetchedAt": "2026-07-04T12:00:00.000Z", "cache": "miss" }, "charged": true, "payment": { "txHash": "…", "network": "…", "priceUsd": 0.01, "payer": "0x…" }, "disclaimer": "…" } ``` Field notes: string fields are `null` when vPIC returns empty; `engine.cylinders` / `engine.displacementL` are numbers or `null`; `vpicErrorCode` is the raw vPIC ErrorCode and `vpicErrorText` is populated only when the code is not `"0"`. - 400 → invalid VIN (must be 17 chars, no I/O/Q) — UNCHARGED - 422 → vPIC could not resolve make/model/year — UNCHARGED - 502 → upstream unavailable — UNCHARGED ## GET /v1/recalls?vin=VIN ($0.01) The MERGED recall view — the only API combining NHTSA (US) and Transport Canada (CA) recalls in one response. Decodes the VIN first, then queries both sources by make/model/year. 24h cache per source; stale served on failure. `provenance.attribution` carries the OGL–Canada notice. (Free preview of this exact shape: GET /v1/sample/recalls.) ```json { "vin": "1FA6P8TH5J5100000", "vehicle": { "year": 2018, "make": "FORD", "model": "Mustang" }, "recalls": { "us": [ { "campaign": "18V123000", "component": "ELECTRICAL SYSTEM", "summary": "…", "consequence": "…", "remedy": "…", "reportedDate": "2018-03-01" } ], "canada": [ { "recallNumber": "2018-123", "systemType": "Electrical", "summary": "…", "unitsAffected": 4200, "recallDate": "2018-03-15" } ] }, "counts": { "us": 1, "canada": 1 }, "provenance": { "nhtsaFetchedAt": "2026-07-04T12:00:00.000Z", "tcFetchedAt": "2026-07-04T12:00:00.000Z", "attribution": "Contains information licensed under the Open Government Licence – Canada." }, "charged": true, "payment": { "txHash": "…", "network": "…", "priceUsd": 0.01, "payer": "0x…" }, "disclaimer": "…" } ``` US recall fields: `campaign, component, summary, consequence, remedy, reportedDate` (all strings). Canada recall fields: `recallNumber` (string), `systemType` (string|null), `summary` (string|null), `unitsAffected` (number|null), `recallDate` (string|null). Canadian detail is capped at the 25 most recent recall numbers; if both sources are unreachable and uncached → 502 (UNCHARGED). ## GET /v1/reliability?vin=VIN ($0.05) A reliability snapshot for one VIN: aggregate complaint stats and US + Canada recall counts. v0 returns RAW counts, not fleet/segment percentiles (percentiles are on the roadmap). Complaint severity signals are summed from the underlying NHTSA complaint records (each record carries `crash`, `fire`, and `numberOfInjuries`); `topComponents` are the most frequent NHTSA component strings. ```json { "vin": "1FA6P8TH5J5100000", "vehicle": { "year": 2018, "make": "FORD", "model": "Mustang" }, "complaints": { "total": 312, "topComponents": [ { "component": "POWER TRAIN", "count": 74 }, { "component": "ELECTRICAL SYSTEM", "count": 51 } ], "severity": { "crashes": 9, "fires": 3, "injuries": 12 } }, "recalls": { "usCount": 4, "canadaCount": 2, "canadaUnitsAffected": 18400 }, "provenance": { "complaintsFetchedAt": "2026-07-04T12:00:00.000Z", "nhtsaFetchedAt": "2026-07-04T12:00:00.000Z", "tcFetchedAt": "2026-07-04T12:00:00.000Z", "attribution": "Contains information licensed under the Open Government Licence – Canada." }, "disclaimer": "…" } ``` Underlying complaint record fields (NHTSA, from which the stats are derived): `odiNumber` (int), `components` (string), `summary` (string), `dateComplaintFiled` (string), `crash` (bool), `fire` (bool), `numberOfInjuries` (int). `canadaUnitsAffected` is the sum of `unitsAffected` across the vehicle's Canadian recalls. Complaints are fetched from NHTSA's complaints-by-vehicle index and cached 7 days. ## GET /v1/known-issues?vin=VIN ($0.25) LLM-clustered named failure modes derived from NHTSA owner complaints. This is the hallucination-gated product: EVERY cited ODI number is programmatically validated against the input complaint set before it is returned — the model cannot invent citations, and every issue carries at least 2 verified ODI numbers. Severity signals per issue are summed from the CITED complaints only (never trusted from the model). Refuses UNCHARGED below 15 complaints. 90-day cache (`cache: "hit"|"miss"`). Success (`status: "ok"`): ```json { "status": "ok", "issues": [ { "title": "Electric power steering assist failure", "componentTags": ["STEERING", "ELECTRICAL SYSTEM"], "odiNumbers": [11234567, 11245678, 11256789], "count": 3, "severitySignals": { "crashes": 1, "fires": 0, "injuries": 2 }, "trend": "rising", "confidence": 0.82 } ], "complaintCount": 312, "modelVersion": "free-chain-medium/v1", "synthesizedAt": "2026-07-04T12:00:00.000Z", "cache": "miss", "disclaimer": "…" } ``` `trend` is one of `rising | stable | declining | unknown`; `confidence` is 0..1. `componentTags` are NHTSA component taxonomy strings drawn from the citing complaints. Below-threshold (200, UNCHARGED — buyers are never charged): ```json { "status": "insufficient_data", "complaintCount": 8, "minimum": 15, "disclaimer": "…" } ``` Synthesis failure (200, UNCHARGED): `{ "status": "synthesis_unavailable", "reason": "llm_unavailable"|"unparseable"|"no_grounded_issues", "disclaimer": "…" }`. ## GET /v1/ca/purchase-costs?province=BC&price=25000&sale_type=private|dealer ($0.02) Itemized government-imposed closing costs of buying a used passenger vehicle in any of Canada's 10 provinces + 3 territories: `BC, AB, SK, MB, ON, QC, NB, NS, PE, NL, YT, NT, NU` (case-insensitive). Figures verified 2026-07-04 against provincial/territorial sources. `price` is the agreed sale price in CAD (>0, ≤5,000,000). Optional: `buyer_has_plates=true` selects plate-dependent fee lines where a jurisdiction distinguishes them (e.g. Ontario: vehicle permit only $32 instead of permit + new plate $59); `family_gift=true` (private sales only) applies the jurisdiction's family/related-individual gift exemption ($0 tax) where one exists. Tax is FLAT on the whole price at the highest bracket whose threshold the price meets (not marginal). Examples: BC private tiers 12% → 15% (≥ $125,000) → 20% (≥ $150,000); Alberta + the three territories (YT/NT/NU) charge NO tax on private sales; QC private is 9.975% QST; HST provinces (ON/NB/NS/PE/NL) charge a single HST rate; other provinces charge GST (5%) + provincial tax on dealer sales. Where the tax base is the greater of price and a book value (Red Book / Black Book / provincial estimated value), a caveat notes the amount assumes price ≥ book value. ```json { "country": "CA", "province": "BC", "provinceName": "British Columbia", "input": { "province": "BC", "priceCad": 25000, "saleType": "private", "familyGift": false, "buyerHasPlates": false }, "lines": [ { "id": "sales_tax", "label": "PST (12%)", "amountCad": 3000, "rangeCad": null, "kind": "tax", "paidTo": "ICBC Autoplan broker …", "notes": "PST on the GREATER of purchase price and the Canadian Black Book average wholesale value …", "sourceUrl": "https://www2.gov.bc.ca/…/pst-308-vehicles.pdf", "confidence": "high" }, { "id": "bc_transfer_fee", "label": "Transfer of ownership (title/licence) fee", "amountCad": 28, "kind": "fee", "paidTo": "provincial/territorial vehicle registry", "notes": "…", "sourceUrl": "…", "confidence": "medium" }, { "id": "bc_annual_licence", "label": "Annual vehicle licence fee (weight-based)", "amountCad": null, "rangeCad": { "low": 46, "high": 142 }, "kind": "market_estimate", "paidTo": "…", "notes": "Annual … public-insurer bundling — insurance premium EXCLUDED …", "sourceUrl": "…", "confidence": "medium" }, { "id": "inspection", "label": "Safety / mechanical inspection", "amountCad": 0, "rangeCad": null, "kind": "informational", "paidTo": "n/a", "notes": "No safety inspection for used transfers within BC …", "sourceUrl": "…", "confidence": "medium" } ], "totalKnownCad": 3046, "estimatedTotalRangeCad": { "low": 3092, "high": 3188 }, "caveats": [ "Figures verified 2026-07-04 …", "The tax is assessed on the greater of the sale price and the vehicle’s book value …" ], "rulesAsOf": "2026-07-04", "disclaimer": "…" } ``` CostLine fields: `id` (stable machine id), `label` (names the actual tax, e.g. `PST (12%)`, `RST (13%)`, `QST (9.975%)`, `HST (15%)`, or `No tax on private sales`), `amountCad` (number|null — null when only a market range applies), `rangeCad` (`{low,high}` for market estimates, else null), `kind` (`tax|fee|market_estimate|informational`), `paidTo`, `notes`, `sourceUrl`, `confidence` (`high|medium`). `totalKnownCad` sums only the non-null `tax`+`fee` lines; `estimatedTotalRangeCad` widens that known total by each market-estimate / range line (recurring annual registration items are shown as first-year estimates and public-insurer premiums are excluded). Dealer sales (`sale_type=dealer`) replace the private tax line with a GST + provincial (or single HST) line paid to the dealer. `family_gift=true` (private only) zeroes the tax via the jurisdiction's sworn family-gift exemption where one exists. Ontario reproduces its verified legacy figures exactly (ON $25,000 private → `sales_tax` 3250, `uvip` 20, `permit_plus_plate` 59, `totalKnownCad` 3329). - 400 → `{ "error": "unknown province/territory 'XX'. Valid codes: AB, BC, MB, NB, NL, NS, NT, NU, ON, PE, QC, SK, YT." }` and similar validation messages. ## GET /v1/us/purchase-costs?state=CA&price=25000&sale_type=private|dealer ($0.02) Itemized government-imposed closing costs of buying a used passenger vehicle in any of the 50 US states or DC. Figures verified against state sources as of 2026-07-04; `us-data.json` is the single source of every figure. Parameters: - `state` (required) — two-letter code, case-insensitive (e.g. `CA`, `ny`, `DC`). - `price` (required) — agreed sale price in USD (> 0, ≤ 5,000,000). - `sale_type` (required) — `private` or `dealer`. Dealer sales add a `dealer_doc_fee` line and are where a full trade-in credit (if the state grants one) is applied. - `trade_in` (optional) — trade-in value in USD (≥ 0, < price). Deducted from the tax base ONLY for a `dealer` sale in a state whose trade-in credit is `full`; for `partial`-credit states no deduction is applied and a caveat is emitted. - `local_rate` (optional) — exact county/city surtax percentage (0–15). When omitted and the state has a local range, the `sales_tax` line carries a `rangeUsd` up to the state's maximum local rate plus a caveat. Lines returned (each with `id`, `label`, `amountUsd` | `rangeUsd`, `kind`, `paidTo`, `notes`, `sourceUrl`, `confidence`): `sales_tax`, `title`, `registration` (first-year), `inspection`, and `dealer_doc_fee` (dealer only). `kind` is one of `tax | fee | market_estimate | informational`. ```json { "country": "US", "state": "CA", "stateName": "California", "input": { "state": "CA", "priceUsd": 25000, "saleType": "private", "tradeInUsd": 0, "localRatePct": null }, "lines": [ { "id": "sales_tax", "label": "Sales / use / excise tax", "amountUsd": 1812.5, "rangeUsd": { "low": 1812.5, "high": 2687.5 }, "kind": "tax", "paidTo": "state / county tax authority", "notes": "…", "sourceUrl": "https://www.cdtfa.ca.gov/…", "confidence": "high" }, { "id": "title", "label": "Title / certificate of title", "amountUsd": 28, "rangeUsd": null, "kind": "fee", "paidTo": "state DMV", "notes": "…", "sourceUrl": "…", "confidence": "medium" }, { "id": "registration", "label": "Vehicle registration (first year)", "amountUsd": null, "rangeUsd": { "low": …, "high": … }, "kind": "market_estimate", "paidTo": "state DMV", "notes": "Registration basis: mixed. …", "sourceUrl": "…", "confidence": "medium" }, { "id": "inspection", "label": "Safety / emissions inspection", "amountUsd": null, "rangeUsd": { "low": 30, "high": 70 }, "kind": "market_estimate", "paidTo": "licensed inspection station", "notes": "…", "sourceUrl": "…", "confidence": "medium" } ], "totalKnownUsd": 1840.5, "estimatedTotalRangeUsd": { "low": …, "high": … }, "caveats": [ "Figures verified 2026-07-04 …", "California county/city surtax of up to 3.5% may apply — pass local_rate for an exact figure." ], "rulesAsOf": "2026-07-04", "disclaimer": "…" } ``` `totalKnownUsd` sums only the non-null `tax`+`fee` amounts (fixed government costs). `estimatedTotalRangeUsd` starts at that known total and widens by each market-estimate / range line, so `low ≤ high` always. Special regimes (returned automatically): - **DC** — no percentage sales tax; a tiered title EXCISE (FMV × 1.5–11% by weight × MPG) is returned as a `market_estimate` `sales_tax` line with a `rangeUsd` and null `amountUsd`. - **IL** — private-party sales pay a flat RUT-50 fee table (not a %), returned as a null-amount `market_estimate`; the 6.25% + local rate applies to IL **dealer** sales only. - **SC** — 5% Infrastructure Maintenance Fee CAPPED at $500 (`maxTaxUsd`); the cap binds above ~$10k. - **AK, AZ, HI, MT, NV, NH, OR** — no state sales tax on a private-party sale → `sales_tax` `amountUsd: 0`. - 400 → `{ "error": "unknown state 'ZZ'. Valid state codes: AK, AL, …" }`, price/trade_in/local_rate range errors, or a missing/invalid `sale_type` — all UNCHARGED. =============================================================================== INTEGRATION NOTES =============================================================================== - Identity is always the payer recovered from the payment — never a client-claimed field. - Prices are USD, settled as USDC with 6 decimals. No bundles, no receipts: one payment = one call. - Multi-rail: a single 402 advertises Base (`eip155:8453`) and Solana (`solana`) — pay whichever you hold USDC on. `PAYMENT-SIGNATURE` (x402 V2) and `X-PAYMENT` (legacy) are both accepted in live mode. - Caching: decode 90d, recalls 24h/source, complaints 7d, known-issues 90d. Stale data is served when a live upstream fails; failures are never cached. - Vindex is NOT a vehicle-history report: it returns no liens, accident, title, or odometer data, and no owner/registrant identity. VINs are stored only as cache keys and never linked to persons. ## Disclaimer Vindex provides informational vehicle data aggregated from public sources (NHTSA, Transport Canada). It is not professional, legal, or purchasing advice, and is provided as-is without warranty. Recall/complaint data reflects the source databases at fetch time. Contains information licensed under the Open Government Licence – Canada. Terms: https://api.vindexapi.dev/terms.txt