vault

Admit a signed head (the push)

THE write path. stored_bytes is canonical base64url of the exact signed object as it will be stored; stored_bytes_sha256 is your own hash of those bytes and is checked before the protocol machine sees anything, so a transport corruption reads as a request-shape refusal rather than a signature failure. The generation is won by a create-only compare-and-swap on the admission record: a loser gets 409 HEAD_CAS_CONFLICT carrying details.winner as hashes only — re-read the winner from GET /vaults/v1/{vault_id}/admissions/{generation}, verify it yourself, rebase, and push again. 201 means the generation is yours. 202 means the record write is not yet resolved and the platform reconciler is driving it to completion — poll, never re-push. A head carrying a repair descriptor additionally requires gitvault.repair (owner + step-up), decided from the signed bytes rather than from the URL.

post/vaults/v1/{vault_id}/admissions

Request

  • Base URL: https://api.run402.com
  • URL: https://api.run402.com/vaults/v1/{vault_id}/admissions
  • Auth: one of:
    • API key in header SIGN-IN-WITH-X
    • HTTP bearer
    • HTTP bearer

Path parameters

vault_idstring required

The vault id (src_<32 hex>); the wire field is repo_id (protocol D185).

Headers

SIGN-IN-WITH-Xstring required

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.

Request body

generationstring required

16 lowercase hex. MUST equal the generation inside the signed object.

stored_bytesstring required

Canonical base64url of the exact stored bytes (the signed head or vault_genesis).

stored_bytes_sha256string required

SHA-256 of those bytes, 64 lowercase hex.

allocation_generationinteger

Genesis only: the allocation this genesis was prepared under.

maintenanceobject

Maintenance-kind admissions only: the proposed cycle binding.

Response

The generation is won (the admission record CAS succeeded)

admission_idstring
repo_idstring
generationstring
admitted_object_kind'head' | 'vault_genesis'
admitted_sha256string nullable
statestring
resource_binding_kind'ordinary_push' | 'maintenance_cycle' | 'repair_attempt'
admission_record_sha256string nullable
effective_admitted_atstring date-time nullable
capture_receiptobject nullable

Present when the head declared a capture. Exchange it at POST /vaults/v1/{vault_id}/activation-tokens.

next_actionsobject[]

Changes

No recorded changes to this operation across all 1 revision of this API.