search
The search noun — identity, lifecycle, events, and every capability as an anchored section: 2 capabilities, 0 live, 2 sandbox, 0 declared.
search is one of the estate's 317 automotive nouns — a job a car needs done. It carries 2 capabilities: 0 live, 2 sandbox, 0 declared · doors search.vin.
Identity
| Noun | search |
| Pillar | Commerce (facets: 2 commerce) |
| Capabilities | 2 — 0 live · 2 sandbox · 0 declared |
| Entities | Listing |
| Doors | search.vin |
| SDK | Vin.search.* from apis.vin |
| Address | /catalog/search#{action} — the anchor IS the wire name minus search. |
Lifecycle
Listing — SearchFSM: 4 states, 3 transitions — Active · Matched · Expired · NoMatch. Each transition is a past-tense event on the record.
Events
The vocabulary this noun can append to the record — 6 past-tense, versioned event types, each linked to the capability that emits it:
Search.expired@1— emitted byprovideSearch.fulfilled@1— emitted byfulfillSearch.matched@1— emitted byprovideSearch.provided@1— emitted byprovideSearch.unmatched@1— emitted byprovideVehicle.sourced@1— emitted byfulfill
More actions
fulfill
search.fulfill · POST /searches/fulfill · gate offer · sandbox · answers SearchFulfillment@1
| Field | Type | Required | Notes |
|---|---|---|---|
search | string | yes | saved-search ref srch_… |
vin | string | no | length 11–17 |
The gate is a 402 OFFER — the price and a hard ceiling on the wire, with a durable intent that executes on settlement. Never a wall, never "contact sales". Price: not posted — see /pricing.
Door — search.vin serves this noun on its two routes: / (the landing) · /1G1YA3D44T5102500 (the VIN lens).
Try it — sandbox: every call answers a deterministic, provenance-labeled simulated payload ({ environment, simulated } in the body). Force any documented outcome with the magic triggers. Going live is a connect, never a ballot: submit the credential at integrates.vin (dealer systems) or connects.vin (consumer accounts) — submissions enter the activation queue and rank live rollout.
Emits — Search.fulfilled@1 · Vehicle.sourced@1.
import { search } from 'apis.vin'
// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await search.fulfill({"search":"search"})curl -X POST https://apis.vin/searches/fulfill \
-H 'content-type: application/json' \
-d '{"search":"search"}'Receipt — the sandbox wire answered the request above with this exact body at build time. Captured by the receipts runner (timestamped, provenance in the payload), never authored; it re-executes only when this descriptor changes.
{
"type": "OK",
"answers": "SearchFulfillment@1",
"value": {
"vin": "1HGCM82633A004352",
"noun": "search",
"asOf": "2026-08-10",
"listingId": "LST-e15977c4",
"venue": "estate-storefront",
"price": 499500,
"odometer": 32490,
"photos": [
{
"setId": "PH-8340ca96",
"kind": "exterior",
"shots": 8
},
{
"setId": "PH-8340ca96",
"kind": "interior",
"shots": 4
}
],
"daysOnLot": 0,
"commercialState": "retail",
"fulfillment": {
"search": "srch_b4fbb619",
"status": "not-matched-yet",
"position": "Active",
"windowClosesAt": "2026-09-09T00:00:00.000Z"
}
},
"evidence": {
"vin": "1HGCM82633A004352",
"noun": "search",
"asOf": "2026-08-10",
"listingId": "LST-e15977c4",
"venue": "estate-storefront",
"price": 499500,
"odometer": 32490,
"photos": [
{
"setId": "PH-8340ca96",
"kind": "exterior",
"shots": 8
},
{
"setId": "PH-8340ca96",
"kind": "interior",
"shots": 4
}
],
"daysOnLot": 0,
"commercialState": "retail",
"fulfillment": {
"search": "srch_b4fbb619",
"status": "not-matched-yet",
"position": "Active",
"windowClosesAt": "2026-09-09T00:00:00.000Z"
}
},
"provenance": {
"simulated": true,
"environment": "sandbox",
"source": "window-papers-sandbox"
},
"events": [],
"meter": {
"charged": "0.00",
"posted": false
}
}provide
search.provide · POST /searches/provide · gate key · sandbox · answers SavedSearch@1
| Field | Type | Required | Notes |
|---|---|---|---|
criteria | object | yes | make/model/year/price/geo search criteria |
requester | object | no | party ref pty_… |
vin | string | no | subject VIN — keys the saved search whose SearchFSM position the answer states (the fleet sourcing exemplar is addressed this way) |
asOf | string | no | format date-time; observation instant (≡ the x-world-as-of header); the answer states the world AT this instant — absent, at, or before the fixed as-of answers the unmoved world |
Door — search.vin serves this noun on its two routes: / (the landing) · /1G1YA3D44T5102500 (the VIN lens).
Try it — sandbox: every call answers a deterministic, provenance-labeled simulated payload ({ environment, simulated } in the body). Force any documented outcome with the magic triggers. Going live is a connect, never a ballot: submit the credential at integrates.vin (dealer systems) or connects.vin (consumer accounts) — submissions enter the activation queue and rank live rollout.
Emits — Search.expired@1 · Search.matched@1 · Search.provided@1 · Search.unmatched@1.
import { search } from 'apis.vin'
// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await search.provide({"criteria":{}})curl -X POST https://apis.vin/searches/provide \
-H 'content-type: application/json' \
-d '{"criteria":{}}'Receipt — the sandbox wire answered the request above with this exact body at build time. Captured by the receipts runner (timestamped, provenance in the payload), never authored; it re-executes only when this descriptor changes.
{
"type": "OK",
"answers": "SavedSearch@1",
"value": {
"search": "srch_88c1a55e",
"status": "Active",
"matched": false,
"windowClosesAt": "2026-09-09T00:00:00.000Z",
"asOf": "2026-08-10T00:00:00.000Z"
},
"evidence": {
"search": "srch_88c1a55e",
"status": "Active",
"matched": false,
"windowClosesAt": "2026-09-09T00:00:00.000Z",
"asOf": "2026-08-10T00:00:00.000Z"
},
"provenance": {
"simulated": true,
"environment": "sandbox",
"source": "search-sandbox"
},
"events": [],
"meter": {
"charged": "0.00",
"posted": false
}
}Data model
The record shape behind this noun — one entity, each property an evidence field. See the whole estate model on the data model page.
Listing
Modeled
The noun drawn out — its record shape, its lifecycle, and how it is exercised end to end. 2 diagrams, rendered from the estate model.
Search · Class model
Search · State machine
Generated from the catalog. Every capability, answer, gate, and entity on this page is a rendered descriptor — it cannot drift from the wire.