Read the composite pin-current state in one call
The vault record, the newest generation, the newest head's exact stored bytes, and the ref_state/retention_roots carrier ciphertext — inlined under a 256 KiB per-carrier cap, else a presigned URL. Every byte is the stored representation, hash-addressed by the same receipts the per-object reads use; nothing here is server-derived or re-serialized, and no key-envelope material is ever returned. The client verifies the chain link, carrier hashes (against the head's own embedded receipts), and signature exactly as it does walking the paginated heads listing — a caller whose pin is more than one generation behind newest_generation ignores head/carriers here and falls back to that listing walk (unless the optional since delta below covers it). head/carriers are null while the vault has no ordinary admitted generation yet — both the freshly-allocated window (newest_generation null) and the genesis-only window (newest_generation equal to the genesis generation, which is a vault_genesis object and never rides head). Same auth chain as object-reads (gitvault.writer, authorize-before-reveal). Never lifecycle-gated. Cache-Control: private, no-store.
Request
- Base URL: https://api.run402.com
- URL: https://api.run402.com/vaults/v1/{vault_id}/state
- Auth: one of:
- API key in header SIGN-IN-WITH-X
- HTTP bearer
- HTTP bearer
Path parameters
The vault id (src_<32 hex>); the wire field is repo_id (protocol D185).
Query parameters
OPTIONAL — the caller's own materialized generation (16 lowercase hex, vault-delta-fetch). NOT a timestamp despite the name — the protocol-v0 wire vocabulary already calls this quantity since in the change's own design/spec text, and it names a chain position, never an instant; x-run402-wire-semantics marks the one exact exception (see the timestamp-schema audit in test/api-docs-alignment.test.ts). When the span from since to newest_generation is small (a fixed bound, currently 4 generations), crosses no checkpoint- or transition-bearing head, and since is strictly behind newest_generation, the response additionally carries delta. Every disqualification — absent, malformed, too wide, a checkpoint/transition crossing, unrecognized, or at-or-ahead-of newest_generation — OMITS delta silently; this is never a validation error on this parameter, so an older gateway is indistinguishable from a disqualified span.
OPTIONAL, ORTHOGONAL to since — declared restore intent (vault-restore-recipe). The literal string 1 is treated as true; anything else, including absence, is false. When true and the newest checkpoint-bearing generation at or below newest_generation (or genesis, when the whole chain is within a fixed generation bound and carries no checkpoint) can be located, the response additionally carries restore_plan: the heads from that boundary through newest_generation, the boundary checkpoint's claim set + manifest, and every checkpoint + WAL pack the span references. Every disqualification — no locatable boundary within the bound, a transition-bearing head anywhere in the span, an unreadable stored object — OMITS restore_plan silently, never a refusal, so an older gateway is indistinguishable from a disqualified vault. A response may carry delta, restore_plan, both, or neither.
Headers
SIWX auth header — base64-encoded JSON payload containing a signed CAIP-122 (EIP-4361) message. See https://docs.x402.org/extensions/sign-in-with-x.
Response
Composite state
Changes
No recorded changes to this operation across all 1 revision of this API.