The five primitives
The whole wire is five primitives plus generated resource routes. Learn these and the rest is the catalog.
The entire API is five primitives plus the resource routes the catalog generates. Learn the five and everything else is just another descriptor.
The five
| Primitive | Route | What it is |
|---|---|---|
| The record | GET /{vin} | the composed record for one VIN — every posted fact, negotiated by content type |
| The subject | GET /{subjectId} | any typed subject by its id — a deal, a party, a document, a connection |
| The catalog | GET /catalog | the queryable list of typed capability descriptors — the source of truth |
| The act | POST /act | one dispatcher for every capability: { capability, input } → a typed Answer |
| The events | /webhooks | subscribe to the record's events; signed deliveries, an echo inbox, ordered resend |
Everything a car needs done resolves to one of these. A resource route like
GET /vehicles/decode is a generated spelling of POST /act with
capability: "vehicle.decode" — the two
spellings of one descriptor.
The shape of every answer
Every capability returns a typed Answer. There is no bare 500, no empty
object dressed as success, no "coming soon" masquerading as data:
OK— the value, with an evidence object on every fact.EMPTY— a typed absence with a reason. The three kinds of "nothing" (EMPTY,INVALID_VIN,BLOCKED) never blend.BLOCKED— a gate, or{ reason: "DECLARED" }for a committed capability no rail serves anywhere yet (modes.live: null— the only rows allowed to read as roadmap). Never a silent 404.OFFER— a402with a price and a hard ceiling on the wire, and a durable intent that executes on settlement.
The SDK puts this law in the type system: Answer<T> = Ok | Empty | Blocked | Offer, and CapabilityName is a generated union so a typo fails at compile.
This is the governing voice of every surface. A number is never asserted; it is
posted with its { value, source, timestamp, verification }. A gate never says
"contact sales"; it returns a price or a person. The copy never grades the
capability — its status, its price, and its emitted events do.
Next
- A VIN in 60 seconds — key → decode → deal.
- Money is a decimal string — the one rule that prevents the worst class of bug.
- The id glossary — every typed prefix, read at a glance.
- The record — evidence objects and the twin invariant.
- The catalog — the descriptor and every capability.