vault

Find a project's vault by project_id/repo address, or list every vault in an org

THREE mutually-exclusive query forms; exactly one is required. (1) ?project_id= — the cold-restart lookup: an agent with no local state learns its repo_id from a project it is authorized on. (2) ?repo=<org-slug>/<name> (repo-first-onramp D6) — an alternative addressing form, resolved to a project_id before authorization runs so an unauthorized caller gets the same uniform 403 either way (authorize-before-reveal is unchanged); a slug in its release cooldown returns the typed SLUG_RELEASED refusal naming the successor slug, never a redirect. Forms (1) and (2) return the same vault record as GET /vaults/v1/{vault_id} and are never lifecycle-gated. (3) ?org_id=<uuid> (repo-surface-consolidation task 2.4) — the BULK vaults-by-org read: every vault in the org in one call, keyset-paginated over (created_at, repo_id) via ?cursor=&limit=. Kills two recorded gaps in one route: repos list's client-side N+1 (list the org's projects, then read each one's vault status sequentially) and repo-first-onramp 6.1 (no bulk read existed, so repo_name needed a second call per row). Auth is ORG MEMBERSHIP (any active member, viewer role or above; platform admin also passes) rather than the project-scoped gitvault.writer bundle forms (1)/(2) use — a grant key is project-scoped and has no "list every vault in this org" concept, so a grant key is not accepted for this form. A nonexistent org_id and a real org the caller is not a member of return the identical 403 (authorize-before-reveal, unchanged). Response shape: { vaults: [{ repo_id, project_id, project_name, repo_name (address-form from internal.repo_names, null when unclaimed), org_slug (null when unclaimed), vault_policy, newest_generation, source_bytes (the BILLED per-vault figure, VAULT_BILLED_BYTES_SQL — never the raw ledger accumulator), genesis_admitted_at, created_at }], has_more, next_cursor }. Filters to live projects (deleted_at IS NULL AND archived_at IS NULL) — a deleted project's vault still counts against pooled storage forever (see the project-delete response), but does not resurface in this listing surface.

get/vaults/v1

Request

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

Query parameters

project_idstring

Existing-project form. Mutually exclusive with repo and org_id; exactly one of the three is required.

repostring

<org-slug>/<name> addressing form (repo-first-onramp D6). Mutually exclusive with project_id and org_id; exactly one of the three is required.

org_idstring uuid

Bulk vaults-by-org form (repo-surface-consolidation task 2.4). Mutually exclusive with project_id and repo; exactly one of the three is required. Selects the paginated vaults[] response shape below.

limitinteger

Only meaningful with org_id. Page size for the bulk vaults-by-org read.

cursorstring

Only meaningful with org_id. Opaque keyset continuation token from a previous response's next_cursor — store and echo, never parse.

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

With project_id or repo: the vault record (see GET /vaults/v1/{vault_id}). With org_id: { vaults: [{repo_id, project_id, project_name, repo_name, org_slug, vault_policy, newest_generation, source_bytes, genesis_admitted_at, created_at}], has_more, next_cursor }.

object required

project_id / repo form: a vault record.

OR

Changes

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