---
title: "Acquire the maintenance lease (owner-only)"
method: POST
path: "/vaults/v1/{vault_id}/maintenance-leases"
tags: ["vault"]
---

# Acquire the maintenance lease (owner-only)

`POST /vaults/v1/{vault_id}/maintenance-leases`

## Request

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

Owner-only (`gitvault.compact`). One active lease per (vault, base head) AND one per ORGANIZATION, so two compactions can never run against the same pool. Admits while the org's pooled usage plus the reservation fits within the tier limit plus the computed cycle headroom. `holder_token` is returned ONCE — it is the liveness instrument for heartbeat, release, and consumption.

## Path parameters

- `vault_id` string, required

## Headers

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

## Request body

- object
  - `base_head_sha256` string, required: 64 lowercase hex — the head the cycle builds on.
  - `current_checkpoint_hash` string, nullable
  - `r1_size_bytes` string, required: Decimal byte count as a string (values exceed 2^53).
  - `r2_cap_size_bytes` string, required: Decimal byte count as a string (values exceed 2^53).
  - `p_before_c1_size_bytes` string: Decimal byte count as a string (values exceed 2^53).
  - `p_before_c2_size_bytes` string: Decimal byte count as a string (values exceed 2^53).

## Response `201`

Lease acquired; holder_token returned once

- object
  - `maintenance_lease_id` string
  - `repo_id` string
  - `base_head_sha256` string
  - `current_checkpoint_hash` string, nullable
  - `reservation_size_bytes` string: Decimal byte count as a string (values exceed 2^53).
  - `maintenance_headroom_bytes` string: Decimal byte count as a string (values exceed 2^53).
  - `holder_token` string: Returned ONCE.
  - `expires_at` string, date-time, nullable
  - `hard_deadline_at` string, date-time, nullable

## Other responses

- `400`: VALIDATION_FAILED
- `403`: VAULT_ACCESS_DENIED / QUOTA_EXCEEDED
- `409`: MAINTENANCE_LEASE_HELD — this vault's base head or the org slot is already leased

---

[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)