handoff

The handoff noun — identity, lifecycle, events, and every capability as an anchored section: 5 capabilities, 0 live, 5 sandbox, 0 declared.

handoff is one of the estate's 317 automotive nouns — a job a car needs done. It carries 5 capabilities: 0 live, 5 sandbox, 0 declared · doors apis.vin.

Identity


Noun	`handoff`
Pillar	Services (facets: 5 services)
Capabilities	5 — 0 live · 5 sandbox · 0 declared
Entities	`Handoff`
Doors	`apis.vin`
SDK	`Vin.handoff.*` from `apis.vin`
Address	`/catalog/handoff#{action}` — the anchor IS the wire name minus `handoff.`

Lifecycle

Handoff — HandoffFSM: 5 states, 4 transitions — Issued · Claimed · Answered · Declined · Expired. Each transition is a past-tense event on the record.

Events

The vocabulary this noun can append to the record — 5 past-tense, versioned event types, each linked to the capability that emits it:

Handoff.answered@1 — emitted by answer
Handoff.claimed@1 — emitted by claim
Handoff.declined@1 — emitted by decline
Handoff.expired@1 — emitted by status
Handoff.issued@1 — emitted by issue

Discover & read

status

handoff.status · GET /handoffs/status · gate none · sandbox · answers HandoffStatus@1

Field	Type	Required	Notes
`handoff`	`string`	no	the handoff record id (the claim-check URL, not this id, is what a human receives)
`vin`	`string`	no	—
`asOf`	`string`	no	observation instant (x-world-as-of twin) — the handoff-expiry clock edge is observable here
`signals`	`string`	no	observed counterparty signals (x-world-signals twin) — present Handoff.claimed@1/answered@1/declined@1 to observe the resolution

Door — apis.vin serves this noun on its two routes: / (the landing) · /1FMCU0J94JUC73513 (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 — Handoff.expired@1.

the SDK — handoff.status

import { handoff } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await handoff.status({"handoff":"handoff","vin":"1FMCU0J94JUC73513"})

GET /handoffs/status

curl 'https://apis.vin/handoffs/status?handoff=handoff&vin=1FMCU0J94JUC73513'

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.

receipt · executed 2026-08-18T15:47:09.687Z · HTTP 200

{
  "type": "EMPTY",
  "answers": "HandoffStatus@1",
  "message": "no handoff at this address (the stateless sandbox face serves the world’s parked handoffs; durable store: vin-0bfz.18)",
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

Fulfill & operate

issue

handoff.issue · POST /handoffs/issue · gate key · sandbox · answers HandoffIssue@1

Field	Type	Required	Notes
`capability`	`string`	yes	the gated capability the question parks on
`subject`	`string`	no	deal/VIN/document the question is about
`reason`	`string`	no	why a human must answer (required on the record; defaulted from the gate when omitted)
`vin`	`string`	no	—

Door — apis.vin serves this noun on its two routes: / (the landing) · /1FMCU0J94JUC73513 (the VIN lens).

Emits — Handoff.issued@1.

the SDK — handoff.issue

import { handoff } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await handoff.issue({"capability":"capability"})

POST /handoffs/issue

curl -X POST https://apis.vin/handoffs/issue \
  -H 'content-type: application/json' \
  -d '{"capability":"capability"}'

Authorize & resolve

claim

handoff.claim · POST /handoffs/claim · gate key · sandbox · answers HandoffClaim@1

Field	Type	Required	Notes
`handoff`	`string`	no	the handoff record id (the claim-check URL, not this id, is what a human receives)
`vin`	`string`	no	—
`claimedBy`	`string`	no	the terminus operator identity

Door — apis.vin serves this noun on its two routes: / (the landing) · /1FMCU0J94JUC73513 (the VIN lens).

Emits — Handoff.claimed@1.

the SDK — handoff.claim

import { handoff } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await handoff.claim({"handoff":"handoff","vin":"1FMCU0J94JUC73513"})

POST /handoffs/claim

curl -X POST https://apis.vin/handoffs/claim \
  -H 'content-type: application/json' \
  -d '{"handoff":"handoff","vin":"1FMCU0J94JUC73513"}'

receipt · executed 2026-08-18T15:47:09.686Z · HTTP 200

{
  "type": "OK",
  "answers": "HandoffClaim@1",
  "value": {
    "handoff": null,
    "act": "claim",
    "note": "no parked handoff resolves from this input — name one (handoff: handoff_…) or a subject standing on a human-waiting position; the stateless sandbox face serves the world’s parked handoffs (durable ad-hoc store: vin-0bfz.18)"
  },
  "evidence": {
    "handoff": null,
    "act": "claim",
    "note": "no parked handoff resolves from this input — name one (handoff: handoff_…) or a subject standing on a human-waiting position; the stateless sandbox face serves the world’s parked handoffs (durable ad-hoc store: vin-0bfz.18)"
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "handoff-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

decline

handoff.decline · POST /handoffs/decline · gate key · sandbox · answers HandoffDecline@1

Field	Type	Required	Notes
`handoff`	`string`	no	the handoff record id (the claim-check URL, not this id, is what a human receives)
`vin`	`string`	no	—
`declinedBy`	`string`	no	—
`reason`	`string`	no	—

Door — apis.vin serves this noun on its two routes: / (the landing) · /1FMCU0J94JUC73513 (the VIN lens).

Emits — Handoff.declined@1.

the SDK — handoff.decline

import { handoff } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await handoff.decline({"handoff":"handoff","vin":"1FMCU0J94JUC73513"})

POST /handoffs/decline

curl -X POST https://apis.vin/handoffs/decline \
  -H 'content-type: application/json' \
  -d '{"handoff":"handoff","vin":"1FMCU0J94JUC73513"}'

receipt · executed 2026-08-18T15:47:09.686Z · HTTP 200

{
  "type": "OK",
  "answers": "HandoffDecline@1",
  "value": {
    "handoff": null,
    "act": "decline",
    "note": "no parked handoff resolves from this input — name one (handoff: handoff_…) or a subject standing on a human-waiting position; the stateless sandbox face serves the world’s parked handoffs (durable ad-hoc store: vin-0bfz.18)"
  },
  "evidence": {
    "handoff": null,
    "act": "decline",
    "note": "no parked handoff resolves from this input — name one (handoff: handoff_…) or a subject standing on a human-waiting position; the stateless sandbox face serves the world’s parked handoffs (durable ad-hoc store: vin-0bfz.18)"
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "handoff-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

More actions

answer

handoff.answer · POST /handoffs/answer · gate key · sandbox · answers HandoffAnswer@1

Field	Type	Required	Notes
`handoff`	`string`	no	the handoff record id (the claim-check URL, not this id, is what a human receives)
`vin`	`string`	no	—
`answeredBy`	`string`	no	the terminus operator identity (auditability rides signal metadata)
`credential`	`string`	no	the operator’s credential class standing (G-B5)

Door — apis.vin serves this noun on its two routes: / (the landing) · /1FMCU0J94JUC73513 (the VIN lens).

Emits — Handoff.answered@1.

the SDK — handoff.answer

import { handoff } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await handoff.answer({"handoff":"handoff","vin":"1FMCU0J94JUC73513"})

POST /handoffs/answer

curl -X POST https://apis.vin/handoffs/answer \
  -H 'content-type: application/json' \
  -d '{"handoff":"handoff","vin":"1FMCU0J94JUC73513"}'

receipt · executed 2026-08-18T15:47:09.666Z · HTTP 200

{
  "type": "OK",
  "answers": "HandoffAnswer@1",
  "value": {
    "handoff": null,
    "act": "answer",
    "note": "no parked handoff resolves from this input — name one (handoff: handoff_…) or a subject standing on a human-waiting position; the stateless sandbox face serves the world’s parked handoffs (durable ad-hoc store: vin-0bfz.18)"
  },
  "evidence": {
    "handoff": null,
    "act": "answer",
    "note": "no parked handoff resolves from this input — name one (handoff: handoff_…) or a subject standing on a human-waiting position; the stateless sandbox face serves the world’s parked handoffs (durable ad-hoc store: vin-0bfz.18)"
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "handoff-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.

Schema

Property	Type	Notes
`id`	`id`	handoff_ (ID_TYPES registry token; R-a: no abbreviations)
`capability`	`string`	the gated catalog capability this handoff parks
`subject`	`string`	the parked question’s subject (deal/VIN/document)
`reason`	`string`	required by the ratified contract (agent-motions.md item 2)
`terminus`	`object`	HITL function + staffed marketplace + SLA, channel-blind (2026-07-23 amendment): {function, marketplace, sla}
`status`	`enum`	Issued\|Claimed\|Answered\|Declined\|Expired
`expiresAt`	`string`	TTL law: 4h fresh (the connections rail cap)
`answeredBy`	`string`	auditability rides signal metadata, never a fifth drivenBy class (vin-0bfz.16 ruling)

Relationships

From	To	Cardinality	As
`handoff`	`capability`	`1:1`	`parks`

Generated from the catalog. Every capability, answer, gate, and entity on this page is a rendered descriptor — it cannot drift from the wire.

handoff

On this page