apis.vin

The .vin family API

Every capability, addressed by VIN.

Decode and listings reads, the buy pillar’s deal lifecycle, F&I rating and contracts, credit prequalification — one API behind the family’s doors, one key doctrine, agents welcome.

OK EMPTY BLOCKED OFFER Typed envelopes on every door. Three emptinesses never blend, and no address answers 406.
the zero-friction proof POST /keys 
# mint a sandbox key — no email, no approval, no CAPTCHA$ curl -X POST https://apis.vin/keys{"type":"OK","key":"vk_sandbox_…","account":"agent_anon_…","environment":"sandbox",…} # first decode — this door also answers keyless$ curl https://apis.vin/decode/JM3KFBXY1S0597748{"type":"OK","decode":{"vin":"JM3KFBXY1S0597748","year":2025,"make":"Mazda","model":"CX-5 2.5 Turbo",…$

The key is returned exactly once; the server stores only a sha256 hash. It adds account context and never unlocks licensed data tiers.

01 / 04 · the record face

GET /{VIN} · seventeen characters, decoded

A VIN is a structured address: every position reserves a meaning, and position 9 certifies the other sixteen. Ask this door for one and the record answers. Everything else at the root is a namespace.

world manufacturerJM3Mazdavehicle attributesKFBXYCX-5check digit1model yearS2025plant0serial597748this one car

the whole surface, projected from the catalog

One catalog, addressed by VIN

313nouns3,912capabilities4,426events20workflows 14 / 3,912live

Every figure here is read from the catalog, not typed onto the page — 3,912 capabilities across 313 nouns, and 14 of them answer in production today. The rest are not hidden; they are on the record.

Five pillars

  • Dataknow it8 live · 1,405 sandbox · 0 declared1,413
  • Servicesdo it1 live · 1,563 sandbox · 0 declared1,564
  • Commercetransact it4 live · 929 sandbox · 0 declared933
  • Workflowscompose it0 live · 20 sandbox · 0 declared20
  • AIapply it1 live · 1 sandbox · 0 declared2

The busiest nouns

Each noun is a job a car needs done; the number is how many capabilities already name it.

  • transport41
  • part37
  • tires36
  • carrier35
  • provider34
  • inspection32
  • recall31
  • telematics31
  • driveline29
  • insurance28
  • recon28
  • brakes27

The precision ladder

Coverage is graded honestly — from what answers in production, down to the declared roadmap.

  1. 14

    live

    Answering in production today — real fulfilment, on the record.

  2. 3,898

    sandbox

    Deterministic behind real wire shapes; every simulated payload says so machinably.

  3. 0

    declared

    The queryable roadmap — a declared address answers BLOCKED {reason:"DECLARED"}, never a silent 404.

02 / 04 · the ways in

Four ways in

The same surface table drives every one of them — the HTTP doors, the SDK, the CLI, and the MCP server state one truth.

HTTP — the doors themselves

Plain HTTP, keyless-first, a typed envelope from every address. The contract is posted at /openapi.json.

  • GET/decode/{vin}the decode read
  • GET/listingsthe listings query
  • POST/buy/dealsopen a deal
  • POST/fi/quotesrate a quote
  • POST/credit/prequalprequalify
  • POST/keysmint the sandbox key
typescript vin.data.decode() 
import { createVinClient, originFetcher } from 'apis.vin'

const vin = createVinClient(originFetcher('https://apis.vin'), {
  authorization: 'Bearer vk_sandbox_…',
})
const record = await vin.data.decode('JM3KFBXY1S0597748')
// the typed envelope verbatim —
// record.type: 'OK' | 'EMPTY' | 'BLOCKED' | 'OFFER'

SDK — typed client, pillar namespaces

Namespaces: data / buy / fi / credit / keys — pillars are namespaces of the one package, never separate packages.

apis.vin is not yet published to npm; every HTTP door on this page answers today.

CLI — vin, sandbox-first

Every answer is a typed envelope; --json prints it verbatim for agents, --no-browser is for CI. Ships inside the same not-yet-published package.

shell vin decode 
# not yet on npm — publish lands in Wave 4
# after that: npm i -g apis.vin
$ vin keys create   # mints + stores the anonymous sandbox key
$ vin decode JM3KFBXY1S0597748
$ vin buy JM3KFBXY1S0597748

MCP — for agent runtimes

The one estate MCP server: POST https://apis.vin/mcp — JSON-RPC 2.0 over streamable HTTP, keyless. tools/list names exactly what this deployment answers: search finds a capability, fetch dereferences an address and returns the typed envelope verbatim.

The same surface table drives the SDK, the CLI, and this server — zero drift, test-enforced.

03 / 04 · keyless to metered

The ladder

Keyless works. A key is one anonymous POST. Prices are posted so nothing is ever an ask.

  1. Keyless

    Every read door answers in full with no key — the quartet, /listings, /decode/{vin}, the record face. VIN decode is posted at $0.00 — the anonymous rung.

  2. Sandbox key

    POST /keys mints vk_sandbox_… instantly — fully self-service, no email, no approval, no CAPTCHA. It adds account context (GET /keys/me) and never unlocks licensed or premium data tiers.

  3. Metered

    Posted v0 unit prices: listings query $0.01, F&I rate quote $0.05, hard ceiling $25.00 per caller per day. No terms document binds them yet; the pricing face says so machinably.

The sandbox is deterministic behind real wire shapes: the same input always answers the same way, refusals are named, and every simulated payload carries "environment":"sandbox", "simulated":true.

04 / 04 · the attestations

Read it yourself

Every claim on this page has a machine face you can dereference.

The published suite pins to sha256:b56b0313d237cf5797f08ad833c846f75bb9d15f5379f29409b325cda39af0e3 — the verifier refuses to run a drifted copy.