apis.vin
v2.0.0
Published
apis.vin — the one programmatic interface to all of Vin.Company: a typed SDK, the vin CLI, and an MCP-ready surface, generated from the v5 catalog (313 nouns, 3912 capabilities, 20 workflows, a typed data model). Vin() anonymous, Vin({apiKey}) keyed; noun
Downloads
319
Maintainers
nathanclevengerReadme
apis.vin
The one programmatic interface to all of Vin.Company. One package, one key —
the same estate rendered as an API, a CLI, an MCP server, and a typed SDK. The
human reads a door in a browser; the agent reads the same record on the wire.
apis.vin is not a separate developer product — it is the machine
representation of the whole model, generated from one catalog so it cannot drift
from the doors it wraps.
This package is generated from catalog.json — the v5 estate catalog
(3932 rows, a projection of apis/catalog.json) — per ruling
sdk-export-shape-2026-08-09 (bead vin-m5t.19). Every namespace, method, workflow, capability name,
answer type, and data-model type is derived from the catalog. The catalog is the
source of truth and the roadmap both.
- 313 noun namespaces · 1620 verbs · 20 workflows · 3892 answer types
- 56 data-model entities · 39 state sets — entity interfaces, state-set unions, and the relationship graph, all typed
- Catalog digest
sha256:ebc1548adbbfd729037a848b256838bfd2d01f779b50603b9df6e65d4f192c0a— pinned; re-published atVin().$catalog
Install
npm i apis.vinThe package ships a vin binary (the CLI face) alongside the SDK. One install
carries the API client, the CLI, and the MCP-ready surface.
vin --help
vin catalog # the pinned catalog manifest
vin vehicle.decode --vin 1HGCM82633A004352Import
import { Vin } from 'apis.vin' // named export — capital V
import Vin from 'apis.vin' // default export — the same factoryThe primary export is Vin with a capital V. This is deliberate: a caller's
own const vin = '1HGCM82633A004352' — a VIN string — never collides with the
client. Vin is both the named and the default export; they are the same value.
Quickstart
Read the record — no account, no key. The free data faces answer anonymously.
import { Vin } from 'apis.vin'
const vin = Vin() // anonymous client
const decoded = await vin.vehicle.decode({ vin: '1HGCM82633A004352' })
if (decoded.type === 'OK') console.log(decoded.value)Key it for more precision. The same client, one key — reads meter under a posted daily ceiling.
const vin = Vin({ apiKey: process.env.VIN_API_KEY })A gated act returns a typed Offer, never a dead end. An act that costs
money answers with the price on the wire.
const answer = await vin.payoff.quote({ vin: '1HGCM82633A004352' })
switch (answer.type) {
case 'OK': return answer.value // the quote
case 'EMPTY': return null // truthfully nothing
case 'BLOCKED': throw new Error(answer.reason)
case 'OFFER': await answer.handoff?.() // price posted; settle to proceed
}A workflow composes leaves under one authority. buy is a workflow method
on the client (and a tree-shakeable top-level export); it returns
Answer<Deal>.
const vin = Vin({ apiKey: process.env.VIN_API_KEY })
const deal = await vin.buy('1HGCM82633A004352', { authority: 'mnd_…' })
// or ambient + tree-shakeable:
import { Vin, buy } from 'apis.vin'
Vin.configure({ apiKey: process.env.VIN_API_KEY })
const deal2 = await buy('1HGCM82633A004352', { authority: 'mnd_…' })The model: noun.facet.verb + Answer<T>
The catalog is spined on the noun — a job a car needs done — and every noun
has three facets: data (know it), services (do it), and commerce
(transact it). The SDK addresses a capability as noun.verb, where the verb
carries its facet:
vin.tires.mount(input) // services — do it
vin.payoff.quote(input) // commerce — transact it
vin.vehicle.decode(input) // data — know itEvery call returns the same four-member answer — the gate law, in the type system:
type Answer<T> = Ok<T> | Empty | Blocked | Offer
// OK — the estate answered; only OK carries the value T
// EMPTY — the estate answered truthfully: nothing here
// BLOCKED — a gate stands (key / mandate / human), typed and named
// OFFER — a way through: a posted price, settled via handoffThe union is exhaustive at exactly four; a fifth discriminant is a compile
error. CapabilityName is a generated union of every capability, so a typo
fails at compile time rather than on the wire. Vin().$catalog re-publishes
the pinned catalog (nouns, verbs, workflows, types, digest).
Tree-shakeable subpath imports
Each noun is reachable at its own subpath, so a build pulls only what it uses:
import { tires } from 'apis.vin/tires'
await tires.mount({ vin: '1HGCM82633A004352' })The named top-level exports (import { tires, payoff, buy } from 'apis.vin')
bind to the ambient client; Vin.configure({ apiKey }) sets its defaults. The
package is sideEffects: false and ships ESM.
The data model — entities, state sets, and the relationship graph
The catalog carries a first-class data model, projected into TypeScript. Each catalog entity becomes an interface (its property-schema, typed), each state set becomes a string-literal union, and the entity relationship graph is re-published as a typed manifest.
import type { Deal, DealLifecycle, EntityModel } from 'apis.vin'
import { DATA_MODEL, ENTITIES, STATE_SETS } from 'apis.vin'
const stage: DealLifecycle = 'FUNDED' // a state-set union member
const model: readonly EntityModel[] = DATA_MODEL // the relationship graph, typedThe SDK ships 56 entity interfaces and 39
state-set unions; ENTITIES and STATE_SETS re-publish them at runtime, and
Vin().$catalog.entities lists them alongside the rest of the manifest.
Honest status — the roadmap is the catalog
The model is validated; most of it is not yet built, and the surface says so.
Every row carries an honest status, so coverage is a count query, never a
surprise:
| status | rows | meaning |
|---|--:|---|
| live | 14 | answering on production |
| sandbox | 65 | answering, simulated (simulated: true, never masqueraded) |
| declared | 3853 | on the record, not yet built — answers BLOCKED { reason: "DECLARED" } |
By facet, the 3912 capability leaves split data 1413
· services 1565 · commerce 934. A
declared row is a typed answer, never a silent 404 and never a faked 200. The
current live count is a query against the catalog, not a number frozen here.
The precision ladder — access is a rung, not a login
Precision deepens by rung over one package and one key. No account wall stands between a reader and the record; the rung is posted as data, never enforced as a lockout.
- anonymous — the free data faces answer with no key;
POST /keysmints a key over the wire, no account. - keyed —
Vin({ apiKey }); reads meter under a posted daily ceiling. - paid — entered per act, not per seat: a priced act returns
OFFERwith a durable intent that executes on settlement.
The gate law — a price or a person, never a dead end
Every gate exits with exactly one of two typed bodies:
OFFER— a posted price and a hard ceiling; settling the durable intent executes the act.BLOCKEDnaming a human step — one of the four human verbs (authorize, notarize, sign, pay) at a named, staffed, priced terminus, delivered as a handoff that degrades gracefully headless.
No "contact sales", no account wall as the only path, no unpriced lead form, no silent 404. A dead lead is a bug, not a funnel.
Noun namespaces
313 nouns, each reachable as Vin().<noun>, as a named export, and
at the subpath apis.vin/<noun>:
abandonedVehicle accessory accessoryInstall adas
adasCalibration adverseAction advisor aftermarketPart
aging ai airbags alignment
allocation apiKey appointment appraisal
approval arbitration arbitrationInspection auction
bankruptcy battery bay beltsHoses
bhphAccount bid body bodywork
bol brakes buffPolish buildSheet
buyback buyersGuide campaign capital
carrier carrierFeed cashPayment catalyticConverter
catastrophe certificateOfDestruction charger chargerHardware
chargerInstall charging collision comms
conditionReport connectedCar connection consignment
consumables consumer contact contractsInTransit
cooling coop core cosigner
courtesyTransport cpo credential credit
creditApplication creditProfile crmEvent damage
deal dealCompliance dealJacket dealer
dealerOfRecord deceasedAccount deposit depreciation
detail diagnostic dimensions disabledPlacard
disbursement disclosureBundle disposition divorceDecree
dnc document documentVault drayage
driveline dtc eContract eTitle
econtract electrical emissions emissionsInspection
engine equity escrow esign
esignature estimate etch evBattery
exhaust extraction facilitator factoryWarranty
features fee feeSchedule fiMenu
fiReserve fieldAction filters financialStatement
financing fleet fleetVehicle floorplan
fluids fni foreignId form8300
frameInspection fraudCase fuel fuelEconomy
fuelSystem fundingPackage gap garage
gatepass gift glass guardianship
hazmatDisposal history holdback hvac
impound incentive infotainment inspection
insurance insuranceClaim insurer interior
interiorRepair interpreter inventory invoice
key keyLocksmith kyc lastmile
lead lease leaseReturnInspection ledger
lemonLaw lender lenderProgram lien
lighting listing load loan
loanServicing loaner longhaul lot
maintenance mandate match mco
mcp mechanicsLien merchandising militaryMove
mobileService mobilityConversion mods moneyInstrument
mpi nmvtis notary odometer
oePart oem ofac offer
oilChange order otd ownership
paint parking part partCatalog
party payment payoff payout
pdi pdr photoMedia photos
plate poa port ppfWrap
ppi preApproval pricing probate
protectionProduct provenance provider psi
qualityCheck rail rdr rebate
recall recalls receipt recon
reconciliation record recycledPart redFlags
refi refinance registration reinsurance
remanPart rental repair repairOrder
repossession reputation review ro
roadside ron roro router
routing safeguards safety safetyInspection
sale salesTax salvage schedule
scra search serviceRecord settlementStatement
signing skipTrace softwareUpdate source
sourcing spec sr22 steering
stips storage subrogation subscription
surplus suspension syndication taxes
tco technician telematics tempTag
testDrive theft tires title
titleBrand titleInsurance titleWashing toll
totalLoss tow tpms tradeIn
translation transmission transport tsb
usage valuation vehicle vin
vinClone vsc warranty warrantyClaim
wash webhook wheels wholesaleParts
wholesaleQuote windowSticker windowTint wipers
workorderVerify
The public contract is executable. Run the acceptance suite locally, or read the hosted suite:
npm run verify # gen:check + typecheck + test + test:types- Acceptance suite — https://apis.vin/verify
- API home — https://apis.vin
- Docs — https://docs.vin
Abstract-model law
No sub-processor, vendor, or data-book name appears on any caller-visible surface — not in a record, an offer, an error, an SDK symbol, or this README. Evidence names the attesting authority at the estate's own level of abstraction. The generator strips vendor tokens and hard-fails if one reaches an emitted symbol; this README is generated under the same guard.
Generated from catalog.json · sdk-export-shape-2026-08-09 · vin-m5t.19. Do not edit by hand;
re-run npm run gen:readme.