Backups

Status, plan, runs, points, verification and retention of the built-in backup agent.

Operations of this group with their access rule, retry rule, parameters and answers. Every request carries a key: Authorization: Bearer <key> (see Authentication).

Operations

Get the backup status

GET HEAD /api/v1/backup/status

Access: System permission backup.read · Retry: Safe to repeat (read)

Summarizes the backup system: the vault (configured, available, free and total bytes), the backup agent (online, last heartbeat, version), the plan, the newest completed point, the next scheduled run, the running job and warnings, each a code such as agent_offline or backup_stale with severity warning or critical. The vault is reported unavailable while the agent is offline. It contains no paths or secrets.

Response 200

Field	Type	Required	Rules
vault	object	yes	—
vault.configured	boolean	yes	—
vault.id	string (uuid)	yes	may be null
vault.available	boolean	yes	—
vault.encrypted	boolean	yes	may be null; Vault is encrypted; null when unknown or not connected.
vault.freeBytes	string	yes	a whole number in decimal digits, sent as a string; may be null
vault.totalBytes	string	yes	a whole number in decimal digits, sent as a string; may be null
agent	object	yes	—
agent.online	boolean	yes	—
agent.lastSeenAt	string (date-time)	yes	may be null
agent.version	string	yes	up to 64 characters; may be null
plan	object	yes	—
plan.enabled	boolean	yes	—
plan.hour	integer	yes	0–23
plan.minute	integer	yes	0–59
plan.timezone	string	yes	1–64 characters; Explicit IANA time zone, e.g. Europe/Moscow; validated by the server.
plan.retention	object	yes	—
plan.retention.daily	integer	yes	0–366
plan.retention.weekly	integer	yes	0–260
plan.retention.monthly	integer	yes	0–120
plan.revision	integer	yes	0–2147483647
lastCompleted	object	yes	may be null
lastCompleted.id	string (uuid)	yes	—
lastCompleted.snapshotAt	string (date-time)	yes	Snapshot time T; the age of a point counts from T.
lastCompleted.completedAt	string (date-time)	yes	—
lastCompleted.blobs	integer	yes	at least 0
lastCompleted.contentBytes	string	yes	a whole number in decimal digits, sent as a string
lastCompleted.newBytes	string	yes	a whole number in decimal digits, sent as a string; Bytes this point added to the vault.
lastCompleted.tables	integer	yes	at least 0
lastCompleted.rows	integer	yes	at least 0
lastCompleted.pinned	boolean	yes	—
lastCompleted.verifiedAt	string (date-time)	yes	may be null
lastCompleted.verifyDepth	string	yes	one of structural, deep, null; may be null
lastCompleted.verifyError	string	yes	matches ^[a-z][a-z0-9_]{0,63}$; may be null
nextRunAt	string (date-time)	yes	may be null
running	object	yes	may be null
running.id	string (uuid)	yes	—
running.kind	string	yes	one of capture, verify, retention
running.state	string	yes	one of queued, running, committing, completed, failed, interrupted
running.phase	string	yes	matches ^[a-z][a-z0-9_]{0,63}$; may be null
running.startedAt	string (date-time)	yes	Start of execution, or the request time while queued.
running.finishedAt	string (date-time)	yes	may be null
running.errorCode	string	yes	matches ^[a-z][a-z0-9_]{0,63}$; may be null
running.pointId	string (uuid)	yes	may be null
running.progress	object	yes	—
running.progress.bytesCopied	string	yes	a whole number in decimal digits, sent as a string; Processed bytes: copied or already in the vault.
running.progress.bytesTotal	string	yes	a whole number in decimal digits, sent as a string
running.progress.blobsCopied	integer	yes	at least 0
running.progress.blobsTotal	integer	yes	at least 0
warnings	array of object	yes	up to 10 items
warnings[].code	string	yes	one of vault_not_configured, agent_offline, schedule_disabled, no_backup_yet, backup_stale, last_run_failed, vault_unavailable, vault_low_space, verify_failed, never_deep_verified
warnings[].severity	string	yes	one of warning, critical

Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507

Example

curl -X GET "$ARKVORY_URL/api/v1/backup/status" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Get the backup plan

GET HEAD /api/v1/backup/plan

Access: System permission backup.read · Retry: Safe to repeat (read)

Returns the daily schedule (enabled, hour and minute in the IANA timezone) and the retention policy (daily, weekly, monthly points to keep) with the revision to send back to updateBackupPlan. Until changed the plan is disabled, with a 02:00 UTC schedule and 7 daily, 4 weekly and 6 monthly points.

Response 200

Field	Type	Required	Rules
enabled	boolean	yes	—
hour	integer	yes	0–23
minute	integer	yes	0–59
timezone	string	yes	1–64 characters; Explicit IANA time zone, e.g. Europe/Moscow; validated by the server.
retention	object	yes	—
retention.daily	integer	yes	0–366
retention.weekly	integer	yes	0–260
retention.monthly	integer	yes	0–120
revision	integer	yes	0–2147483647

Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507

Example

curl -X GET "$ARKVORY_URL/api/v1/backup/plan" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Replace the backup plan

PUT /api/v1/backup/plan

Access: System permission backup.manage · Retry: Repeat only with the expected revision (compare-and-swap)

Replaces the whole plan: enabled, hour (0–23), minute (0–59), timezone and retention (at most 366 daily, 260 weekly, 120 monthly) must all be present. expectedRevision must be the current revision, otherwise 409 revision_mismatch; an invalid field is a 400 with a JSON Pointer in details. The agent follows the new schedule from its next check.

Request body (application/json)

Field	Type	Required	Rules
expectedRevision	integer	yes	0–2147483647
enabled	boolean	yes	—
hour	integer	yes	0–23
minute	integer	yes	0–59
timezone	string	yes	1–64 characters; Explicit IANA time zone, e.g. Europe/Moscow; validated by the server.
retention	object	yes	—
retention.daily	integer	yes	0–366
retention.weekly	integer	yes	0–260
retention.monthly	integer	yes	0–120

Response 200

Field	Type	Required	Rules
enabled	boolean	yes	—
hour	integer	yes	0–23
minute	integer	yes	0–59
timezone	string	yes	1–64 characters; Explicit IANA time zone, e.g. Europe/Moscow; validated by the server.
retention	object	yes	—
retention.daily	integer	yes	0–366
retention.weekly	integer	yes	0–260
retention.monthly	integer	yes	0–120
revision	integer	yes	0–2147483647

Responses: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Example

curl -X PUT "$ARKVORY_URL/api/v1/backup/plan" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":0,"enabled":false,"hour":0,"minute":0,"timezone":"<timezone>","retention":{"daily":0,"weekly":0,"monthly":0}}'

Request a backup now

POST /api/v1/backup/runs

Access: System permission backup.manage · Retry: Safe to repeat with the same Idempotency-Key

Queues a capture for the backup agent outside the schedule and returns 202 with the job (kind capture); the agent runs it, then verification and retention. Idempotency-Key is required: repeating it, from the same caller, returns the same job. Follow the job in listBackupJobs. At most 100 backup requests may be open at once (507 queue_full); while no agent is online the job waits.

Parameters

Name	In	Type	Required	Rules
Idempotency-Key	header	string	yes	matches ^[A-Za-z0-9_.:-]{1,128}$; Repeat returns the same job; per caller and operation kind.

Response 202

Field	Type	Required	Rules
id	string (uuid)	yes	—
kind	string	yes	one of capture, verify, retention
state	string	yes	one of queued, running, committing, completed, failed, interrupted

Responses: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507

Example

curl -X POST "$ARKVORY_URL/api/v1/backup/runs" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

List backup jobs

GET HEAD /api/v1/backup/jobs

Access: System permission backup.read · Retry: Safe to repeat (read)

Lists capture, verify and retention jobs, newest first, each with its state (queued, running, committing, completed, failed, interrupted), phase, times, errorCode, the resulting point and progress (bytes and objects processed). Pages hold limit jobs (1–100, default 50); continue with after set to next.

Parameters

Name	In	Type	Required	Rules
after	query	string	no	matches ^[0-9]{1,17}_[0-9a-f-]{36}$; next of the previous page
limit	query	integer	no	1–100; default 50

Response 200

Field	Type	Required	Rules
items	array of object	yes	up to 100 items
items[].id	string (uuid)	yes	—
items[].kind	string	yes	one of capture, verify, retention
items[].state	string	yes	one of queued, running, committing, completed, failed, interrupted
items[].phase	string	yes	matches ^[a-z][a-z0-9_]{0,63}$; may be null
items[].startedAt	string (date-time)	yes	Start of execution, or the request time while queued.
items[].finishedAt	string (date-time)	yes	may be null
items[].errorCode	string	yes	matches ^[a-z][a-z0-9_]{0,63}$; may be null
items[].pointId	string (uuid)	yes	may be null
items[].progress	object	yes	—
items[].progress.bytesCopied	string	yes	a whole number in decimal digits, sent as a string; Processed bytes: copied or already in the vault.
items[].progress.bytesTotal	string	yes	a whole number in decimal digits, sent as a string
items[].progress.blobsCopied	integer	yes	at least 0
items[].progress.blobsTotal	integer	yes	at least 0
next	string	yes	matches ^[0-9]{1,17}_[0-9a-f-]{36}$; may be null

Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507

Example

curl -X GET "$ARKVORY_URL/api/v1/backup/jobs" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

List backup points

GET HEAD /api/v1/backup/points

Access: System permission backup.read · Retry: Safe to repeat (read)

Lists the completed restore points of the current vault, newest snapshot first, each with the snapshot time T, size, bytes added to the vault, whether it is pinned and its latest verification (verifiedAt, verifyDepth structural or deep, verifyError). Pages hold limit points (1–100, default 50); continue with after set to next. A vault that was replaced shows only its own points.

Parameters

Name	In	Type	Required	Rules
after	query	string	no	matches ^[0-9]{1,17}_[0-9a-f-]{36}$; next of the previous page
limit	query	integer	no	1–100; default 50

Response 200

Field	Type	Required	Rules
items	array of object	yes	up to 100 items
items[].id	string (uuid)	yes	—
items[].snapshotAt	string (date-time)	yes	Snapshot time T; the age of a point counts from T.
items[].completedAt	string (date-time)	yes	—
items[].blobs	integer	yes	at least 0
items[].contentBytes	string	yes	a whole number in decimal digits, sent as a string
items[].newBytes	string	yes	a whole number in decimal digits, sent as a string; Bytes this point added to the vault.
items[].tables	integer	yes	at least 0
items[].rows	integer	yes	at least 0
items[].pinned	boolean	yes	—
items[].verifiedAt	string (date-time)	yes	may be null
items[].verifyDepth	string	yes	one of structural, deep, null; may be null
items[].verifyError	string	yes	matches ^[a-z][a-z0-9_]{0,63}$; may be null
next	string	yes	matches ^[0-9]{1,17}_[0-9a-f-]{36}$; may be null

Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507

Example

curl -X GET "$ARKVORY_URL/api/v1/backup/points" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Request a deep check of a backup point

POST /api/v1/backup/points/{id}/verify

Access: System permission backup.manage · Retry: Safe to repeat with the same Idempotency-Key

Queues a verification of the point id that reads every stored byte of it; the answer is 202 with the job, and the outcome appears in verifiedAt, verifyDepth and verifyError of the point. Idempotency-Key is required, and reusing it for another point is a 409 idempotency_mismatch. An unknown point is a 404.

Parameters

Name	In	Type	Required	Rules
id	path	string (uuid)	yes	—
Idempotency-Key	header	string	yes	matches ^[A-Za-z0-9_.:-]{1,128}$; Repeat returns the same job; per caller and operation kind.

Response 202

Field	Type	Required	Rules
id	string (uuid)	yes	—
kind	string	yes	one of capture, verify, retention
state	string	yes	one of queued, running, committing, completed, failed, interrupted

Responses: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507

Example

curl -X POST "$ARKVORY_URL/api/v1/backup/points/$ID/verify" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Pin or unpin a backup point

PUT /api/v1/backup/points/{id}/pin

Access: System permission backup.manage · Retry: Safe to repeat: the same request has the same effect

Sets pinned of the point id; a pinned point is kept by retention beyond the policy until it is unpinned. Setting the same value again changes nothing, and the answer is the updated point. An unknown or already forgotten point is a 404.

Parameters

Name	In	Type	Required	Rules
id	path	string (uuid)	yes	—

Request body (application/json)

Field	Type	Required	Rules
pinned	boolean	yes	—

Response 200

Field	Type	Required	Rules
id	string (uuid)	yes	—
snapshotAt	string (date-time)	yes	Snapshot time T; the age of a point counts from T.
completedAt	string (date-time)	yes	—
blobs	integer	yes	at least 0
contentBytes	string	yes	a whole number in decimal digits, sent as a string
newBytes	string	yes	a whole number in decimal digits, sent as a string; Bytes this point added to the vault.
tables	integer	yes	at least 0
rows	integer	yes	at least 0
pinned	boolean	yes	—
verifiedAt	string (date-time)	yes	may be null
verifyDepth	string	yes	one of structural, deep, null; may be null
verifyError	string	yes	matches ^[a-z][a-z0-9_]{0,63}$; may be null

Responses: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Example

curl -X PUT "$ARKVORY_URL/api/v1/backup/points/$ID/pin" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pinned":false}'

Preview what backup retention keeps

GET HEAD /api/v1/backup/retention/preview

Access: System permission backup.read · Retry: Safe to repeat (read)

Shows which points the retention policy would keep, each with the reasons (daily, weekly, monthly, pinned, newest), and which it would delete now. Points that failed verification are not considered. The preview is advisory: requestBackupRetention decides again from the vault when it runs.

Response 200

Field	Type	Required	Rules
keep	array of object	yes	—
keep[].id	string (uuid)	yes	—
keep[].reasons	array of string	yes	each: one of daily, weekly, monthly, pinned, newest
delete	array of object	yes	—
delete[].id	string (uuid)	yes	—

Responses: 200, 400, 401, 403, 404, 409, 422, 503, 507

Example

curl -X GET "$ARKVORY_URL/api/v1/backup/retention/preview" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Request backup retention

POST /api/v1/backup/retention/apply

Access: System permission backup.manage · Retry: Safe to repeat with the same Idempotency-Key

Queues a retention job: the agent forgets the points outside the policy and then removes content no remaining point uses, so space returns to the vault only when the job has completed. Returns 202 with the job; Idempotency-Key is required and repeating it returns the same job. Look at previewBackupRetention first.

Parameters

Name	In	Type	Required	Rules
Idempotency-Key	header	string	yes	matches ^[A-Za-z0-9_.:-]{1,128}$; Repeat returns the same job; per caller and operation kind.

Response 202

Field	Type	Required	Rules
id	string (uuid)	yes	—
kind	string	yes	one of capture, verify, retention
state	string	yes	one of queued, running, committing, completed, failed, interrupted

Responses: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507

Example

curl -X POST "$ARKVORY_URL/api/v1/backup/retention/apply" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"