---
title: "Provision or replace this node's recovery repository"
method: POST
path: "/api/recovery/repository"
tags: ["Recovery"]
---

# Provision or replace this node's recovery repository

`POST /api/recovery/repository`

## Request

- Base URL: `https://localhost:1852`
- URL: `https://localhost:1852/api/recovery/repository`
- Auth: HTTP bearer

Provisions the repository, or continues a provisioning attempt a crash left half
done. Idempotent: the same key answers the operation it already created. With
`replace: true`, registers a new repository volume generation and moves the
active pointer to it; the previous repository and its points are kept. A request that
builds or replaces the repository takes the node's repository lock, the lock every
capture, verification, and restore holds, so it answers `409` and is not recorded
while one of them (or another replacement) runs, or while a stale repository lock
awaits a reviewed release. A repeated request on a working repository changes nothing
and takes no lock. Requires permission to change system settings.
Only a Full Admin API token may call it; any other scope is refused with `403 SCOPE_DENIED`.

## Headers

- `x-node-id` integer

## Request body

- object
  - `idempotencyKey` string, required
  - `replace` boolean: Provision a new repository and keep the previous one and its points.

## Response `200`

Replay of an earlier request with the same idempotency key.

- RecoveryAcceptedOperation
  - `operation` RecoveryOperation, required
    - `id` string, uuid, required
    - `idempotencyKey` string, required: Caller-supplied key. A replay of the same key answers the same operation.
    - `kind` 'create_point' | 'verify_point' | 'restore' | 'repository_init', required
    - `storageId` string, nullable, required
    - `pointId` string, nullable, required
    - `actor` string, required
    - `transport` 'local' | 'node_proxy' | 'pilot_tunnel', required
    - `state` 'queued' | 'running' | 'succeeded' | 'partial' | 'failed' | 'cancelled' | 'completion_unknown', required: `completion_unknown` means the process was lost mid-operation. It is never success and is never retried silently.
    - `errorClass` 'invalid_request' | 'permission_denied' | 'capability_unavailable' | 'update_required' | 'schema_unsupported' | 'identity_unknown' | 'lock_held' | 'lock_stale' | 'repository_unavailable' | 'repository_key_unavailable' | 'source_unreadable' | 'integrity_mismatch' | 'attributes_not_restored' | 'interrupted' | 'transport_unreachable' | 'node_refused' | 'node_error' | 'internal' | 'null', nullable, required
    - `errorDetail` string, nullable, required
    - `processEpoch` string, required
    - `createdAt` integer, required
    - `updatedAt` integer, required
    - `completedAt` integer, nullable, required
  - `failureDomain` 'same_failure_domain', required
  - `warning` string, required: States that the repository shares this node's failure domain and is not an off-host copy.

## Other responses

- `202`: Provisioning admitted.
- `400`: The request is not valid for this storage.
- `401`: Authentication required. Provide a valid Bearer token.
- `403`: The caller lacks the access this recovery action needs. An API token whose scope does not allow the call is refused before the route runs, with `code: SCOPE_DENIED` and no `errorClass`.
- `409`: A live lock is held, an interrupted operation left a stale lock, the storage identity is unknown, a check found a mismatch, an operation was interrupted, or a remote node needs an update.
- `500`: The recovery operation failed.
- `503`: Volume protection is not available on this node, the repository is not reachable or its key is unavailable, the schema is unsupported, or the node could not be reached. A node that is still starting answers with `"reason": "engine_starting"`.

## Changes

- **2026-11-02** `1f7572eb735f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/studio-saelix/apis/sencho-api/changes/api/recovery/repository/post.md)

---

[API](https://skmtc.dev/studio-saelix/apis/sencho-api.md) - [All operations](https://skmtc.dev/studio-saelix/apis/sencho-api/llms.txt) - [OpenAPI document](https://skmtc.dev/studio-saelix/apis/sencho-api/revisions/1f7572eb735f?raw)