---
title: "List heads above your pin"
method: GET
path: "/vaults/v1/{vault_id}/heads"
tags: ["vault"]
---

# List heads above your pin

`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

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.

## Path parameters

- `vault_id` string, required

## Query parameters

- `after_generation` string, required
- `limit` string, required
- `cursor` string

## Headers

- `SIGN-IN-WITH-X` string, required

## Response `200`

One page of the head chain

- object
  - `format` string
  - `repo_id` string
  - `after_generation` string
  - `heads` object[]
    - `generation` string
    - `stored_bytes_sha256` string
  - `has_more` boolean
  - `next_cursor` string, nullable
  - `total` string, nullable: Exact on the final page; null while has_more.

## Other responses

- `400`: INVALID_CURSOR / VALIDATION_FAILED
- `403`: Not authorized (VAULT_ACCESS_DENIED)
- `409`: CHAIN_BROKEN — a gap or malformed key in the listing

---

[API](https://skmtc.dev/run402/apis/run402-api.md) · [All operations](https://skmtc.dev/run402/apis/run402-api/llms.txt) · [OpenAPI document](https://skmtc.dev/run402/apis/run402-api/revisions/893607557f50?raw)