vault

List heads above your pin

Storage-derived, ascending, from the client's REQUIRED after_generation pin — there is no hint object to trust. limit is REQUIRED. cursor is opaque and bound to (vault, after_generation, position): a malformed, tampered, cross-vault, or anchor-mismatched cursor is a typed retryable INVALID_CURSOR, never a silent restart from the pin. A generation gap or a malformed key fails closed as CHAIN_BROKEN. total is exact on the final page and null while has_more is true. Never lifecycle-gated.

get/vaults/v1/{vault_id}/heads

Request

  • Base URL: https://api.run402.com
  • URL: https://api.run402.com/vaults/v1/{vault_id}/heads
  • 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).

Query parameters

after_generationstring required

16 lowercase hex — the client's verified pin. Results start strictly above it.

limitstring required

Page size, at most MAX_HEADS_PER_LISTING_PAGE.

cursorstring

Echo the previous page's next_cursor unchanged.

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.

Response

One page of the head chain

formatstring
repo_idstring
after_generationstring
has_moreboolean
next_cursorstring nullable
totalstring nullable

Exact on the final page; null while has_more.

Changes

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