vault

Open a bounded compaction headroom grant

vault-checkpoint-cadence (design D3/D4). A compaction transiently needs roughly 2x a vault's source_bytes — the new checkpoint must land durably before the superseded history is pruned — which the org-pooled quota otherwise refuses for a vault already near its limit. Opens a bounded, TTL'd (~1 hour, hard-coded) grant that raises the org's EFFECTIVE storage limit by exactly granted_bytes while active — never the reported usage. The server measures and caps granted_bytes at the vault's OWN current billed source_bytes; requested_bytes, if given, can only narrow it, never widen it. At most one active grant per project (a partial unique index enforces it); a second open while one is active refuses 409 VAULT_COMPACTION_GRANT_ACTIVE. An expired-but-unswept grant releases its slot on this SAME call rather than waiting on the hourly sweep. Granted bytes are never billed and can never become standing storage.

post/vaults/v1/{vault_id}/compaction-grant

Request

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

requested_bytesnumber

Optional client-requested cap. The server never grants MORE than the vault's own measured billed source_bytes regardless of this value.

Response

Grant opened

granted_bytesstring

Decimal byte count as a string (values exceed 2^53).

expires_atstring date-time
pool_used_bytesstring

Decimal byte count as a string (values exceed 2^53).

pool_limit_bytesstring

Decimal byte count as a string (values exceed 2^53) — the bare tier limit, unaffected by the grant.

effective_pool_limit_bytesstring

Decimal byte count as a string (values exceed 2^53) — pool_limit_bytes plus every currently active compaction-grant headroom on the org, including this one.

Changes

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