Copias de seguridad

Estado, plan, ejecuciones, puntos, verificación y retención del agente de copias de seguridad integrado.

Operaciones de este grupo con su regla de acceso, su regla de reintento, sus parámetros y sus respuestas. Cada solicitud lleva una clave: Authorization: Bearer <clave> (consulte «Autenticación»).

Operaciones

Obtener el estado de las copias de seguridad

GET HEAD /api/v1/backup/status

Acceso: Permiso del sistema backup.read · Reintento: Se puede repetir (lectura)

Resume el sistema de copias de seguridad: el almacén de copias (configured, available, bytes libres y totales), el agente de copias de seguridad (online, último latido, versión), el plan, el punto completado más reciente, la próxima ejecución programada, el trabajo en curso y warnings, cada uno un código como agent_offline o backup_stale con gravedad warning o critical. El almacén se informa como no disponible mientras el agente no está en línea. No contiene rutas ni secretos.

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
vault	object	sí	—
vault.configured	boolean	sí	—
vault.id	string (uuid)	sí	puede ser null
vault.available	boolean	sí	—
vault.encrypted	boolean	sí	puede ser null; El almacén está cifrado; null si se desconoce o no está conectado.
vault.freeBytes	string	sí	un número entero en dígitos decimales, enviado como cadena; puede ser null
vault.totalBytes	string	sí	un número entero en dígitos decimales, enviado como cadena; puede ser null
agent	object	sí	—
agent.online	boolean	sí	—
agent.lastSeenAt	string (date-time)	sí	puede ser null
agent.version	string	sí	hasta 64 caracteres; puede ser null
plan	object	sí	—
plan.enabled	boolean	sí	—
plan.hour	integer	sí	0–23
plan.minute	integer	sí	0–59
plan.timezone	string	sí	1–64 caracteres; Zona horaria IANA explícita, p. ej. Europe/Moscow; la valida el servidor.
plan.retention	object	sí	—
plan.retention.daily	integer	sí	0–366
plan.retention.weekly	integer	sí	0–260
plan.retention.monthly	integer	sí	0–120
plan.revision	integer	sí	0–2147483647
lastCompleted	object	sí	puede ser null
lastCompleted.id	string (uuid)	sí	—
lastCompleted.snapshotAt	string (date-time)	sí	Hora T de la instantánea; la antigüedad de un punto se cuenta desde T.
lastCompleted.completedAt	string (date-time)	sí	—
lastCompleted.blobs	integer	sí	como mínimo 0
lastCompleted.contentBytes	string	sí	un número entero en dígitos decimales, enviado como cadena
lastCompleted.newBytes	string	sí	un número entero en dígitos decimales, enviado como cadena; Bytes que este punto añadió al almacén.
lastCompleted.tables	integer	sí	como mínimo 0
lastCompleted.rows	integer	sí	como mínimo 0
lastCompleted.pinned	boolean	sí	—
lastCompleted.verifiedAt	string (date-time)	sí	puede ser null
lastCompleted.verifyDepth	string	sí	uno de structural, deep, null; puede ser null
lastCompleted.verifyError	string	sí	coincide con ^[a-z][a-z0-9_]{0,63}$; puede ser null
nextRunAt	string (date-time)	sí	puede ser null
running	object	sí	puede ser null
running.id	string (uuid)	sí	—
running.kind	string	sí	uno de capture, verify, retention
running.state	string	sí	uno de queued, running, committing, completed, failed, interrupted
running.phase	string	sí	coincide con ^[a-z][a-z0-9_]{0,63}$; puede ser null
running.startedAt	string (date-time)	sí	Inicio de la ejecución, o la hora de la solicitud mientras está en cola.
running.finishedAt	string (date-time)	sí	puede ser null
running.errorCode	string	sí	coincide con ^[a-z][a-z0-9_]{0,63}$; puede ser null
running.pointId	string (uuid)	sí	puede ser null
running.progress	object	sí	—
running.progress.bytesCopied	string	sí	un número entero en dígitos decimales, enviado como cadena; Bytes procesados: copiados o ya presentes en el almacén.
running.progress.bytesTotal	string	sí	un número entero en dígitos decimales, enviado como cadena
running.progress.blobsCopied	integer	sí	como mínimo 0
running.progress.blobsTotal	integer	sí	como mínimo 0
warnings	array de object	sí	hasta 10 elementos
warnings[].code	string	sí	uno de 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	sí	uno de warning, critical

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

Ejemplo

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

Obtener el plan de copias de seguridad

GET HEAD /api/v1/backup/plan

Acceso: Permiso del sistema backup.read · Reintento: Se puede repetir (lectura)

Devuelve la programación diaria (enabled, hour y minute en la zona horaria timezone de IANA) y la política de retención (puntos daily, weekly, monthly que conservar) con la revision que se debe enviar de vuelta a updateBackupPlan. Hasta que se cambie, el plan está desactivado, con una programación a las 02:00 UTC y 7 puntos diarios, 4 semanales y 6 mensuales.

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
enabled	boolean	sí	—
hour	integer	sí	0–23
minute	integer	sí	0–59
timezone	string	sí	1–64 caracteres; Zona horaria IANA explícita, p. ej. Europe/Moscow; la valida el servidor.
retention	object	sí	—
retention.daily	integer	sí	0–366
retention.weekly	integer	sí	0–260
retention.monthly	integer	sí	0–120
revision	integer	sí	0–2147483647

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

Ejemplo

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

Reemplazar el plan de copias de seguridad

PUT /api/v1/backup/plan

Acceso: Permiso del sistema backup.manage · Reintento: Repetir solo con la revisión esperada (compare-and-swap)

Reemplaza el plan completo: enabled, hour (0–23), minute (0–59), timezone y retention (como máximo 366 diarios, 260 semanales, 120 mensuales) deben estar presentes. expectedRevision debe ser la revisión actual; de lo contrario, 409 revision_mismatch; un campo no válido produce un 400 con un JSON Pointer en details. El agente sigue la nueva programación desde su siguiente comprobación.

Cuerpo de la solicitud (application/json)

Campo	Tipo	Obligatorio	Reglas
expectedRevision	integer	sí	0–2147483647
enabled	boolean	sí	—
hour	integer	sí	0–23
minute	integer	sí	0–59
timezone	string	sí	1–64 caracteres; Zona horaria IANA explícita, p. ej. Europe/Moscow; la valida el servidor.
retention	object	sí	—
retention.daily	integer	sí	0–366
retention.weekly	integer	sí	0–260
retention.monthly	integer	sí	0–120

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
enabled	boolean	sí	—
hour	integer	sí	0–23
minute	integer	sí	0–59
timezone	string	sí	1–64 caracteres; Zona horaria IANA explícita, p. ej. Europe/Moscow; la valida el servidor.
retention	object	sí	—
retention.daily	integer	sí	0–366
retention.weekly	integer	sí	0–260
retention.monthly	integer	sí	0–120
revision	integer	sí	0–2147483647

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

Ejemplo

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}}'

Solicitar una copia de seguridad ahora

POST /api/v1/backup/runs

Acceso: Permiso del sistema backup.manage · Reintento: Se puede repetir con el mismo Idempotency-Key

Encola una captura para el agente de copias de seguridad fuera de la programación y devuelve 202 con el trabajo (kind capture); el agente la ejecuta y después la verificación y la retención. Idempotency-Key es obligatorio: repetirlo, desde el mismo solicitante, devuelve el mismo trabajo. Siga el trabajo en listBackupJobs. Puede haber como máximo 100 solicitudes de copia abiertas a la vez (507 queue_full); mientras no haya ningún agente en línea, el trabajo espera.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
Idempotency-Key	encabezado	string	sí	coincide con ^[A-Za-z0-9_.:-]{1,128}$; Repeat returns the same job; per caller and operation kind.

Respuesta 202

Campo	Tipo	Obligatorio	Reglas
id	string (uuid)	sí	—
kind	string	sí	uno de capture, verify, retention
state	string	sí	uno de queued, running, committing, completed, failed, interrupted

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

Ejemplo

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

Listar trabajos de copia de seguridad

GET HEAD /api/v1/backup/jobs

Acceso: Permiso del sistema backup.read · Reintento: Se puede repetir (lectura)

Enumera los trabajos de captura, verificación y retención, del más reciente al más antiguo, cada uno con su state (queued, running, committing, completed, failed, interrupted), phase, horas, errorCode, el punto resultante y progress (bytes y objetos procesados). Las páginas contienen limit trabajos (1–100, 50 por defecto); continúe pasando next como after.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
after	consulta	string	no	coincide con ^[0-9]{1,17}_[0-9a-f-]{36}$; next of the previous page
limit	consulta	integer	no	1–100; predeterminado: 50

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
items	array de object	sí	hasta 100 elementos
items[].id	string (uuid)	sí	—
items[].kind	string	sí	uno de capture, verify, retention
items[].state	string	sí	uno de queued, running, committing, completed, failed, interrupted
items[].phase	string	sí	coincide con ^[a-z][a-z0-9_]{0,63}$; puede ser null
items[].startedAt	string (date-time)	sí	Inicio de la ejecución, o la hora de la solicitud mientras está en cola.
items[].finishedAt	string (date-time)	sí	puede ser null
items[].errorCode	string	sí	coincide con ^[a-z][a-z0-9_]{0,63}$; puede ser null
items[].pointId	string (uuid)	sí	puede ser null
items[].progress	object	sí	—
items[].progress.bytesCopied	string	sí	un número entero en dígitos decimales, enviado como cadena; Bytes procesados: copiados o ya presentes en el almacén.
items[].progress.bytesTotal	string	sí	un número entero en dígitos decimales, enviado como cadena
items[].progress.blobsCopied	integer	sí	como mínimo 0
items[].progress.blobsTotal	integer	sí	como mínimo 0
next	string	sí	coincide con ^[0-9]{1,17}_[0-9a-f-]{36}$; puede ser null

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

Ejemplo

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

Listar puntos de copia de seguridad

GET HEAD /api/v1/backup/points

Acceso: Permiso del sistema backup.read · Reintento: Se puede repetir (lectura)

Enumera los puntos de restauración completados del almacén actual, con la instantánea más reciente primero, cada uno con la hora T de la instantánea, el tamaño, los bytes añadidos al almacén, si está fijado (pinned) y su última verificación (verifiedAt, verifyDepth structural o deep, verifyError). Las páginas contienen limit puntos (1–100, 50 por defecto); continúe pasando next como after. Un almacén que se sustituyó muestra solo sus propios puntos.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
after	consulta	string	no	coincide con ^[0-9]{1,17}_[0-9a-f-]{36}$; next of the previous page
limit	consulta	integer	no	1–100; predeterminado: 50

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
items	array de object	sí	hasta 100 elementos
items[].id	string (uuid)	sí	—
items[].snapshotAt	string (date-time)	sí	Hora T de la instantánea; la antigüedad de un punto se cuenta desde T.
items[].completedAt	string (date-time)	sí	—
items[].blobs	integer	sí	como mínimo 0
items[].contentBytes	string	sí	un número entero en dígitos decimales, enviado como cadena
items[].newBytes	string	sí	un número entero en dígitos decimales, enviado como cadena; Bytes que este punto añadió al almacén.
items[].tables	integer	sí	como mínimo 0
items[].rows	integer	sí	como mínimo 0
items[].pinned	boolean	sí	—
items[].verifiedAt	string (date-time)	sí	puede ser null
items[].verifyDepth	string	sí	uno de structural, deep, null; puede ser null
items[].verifyError	string	sí	coincide con ^[a-z][a-z0-9_]{0,63}$; puede ser null
next	string	sí	coincide con ^[0-9]{1,17}_[0-9a-f-]{36}$; puede ser null

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

Ejemplo

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

Solicitar una comprobación profunda de un punto de copia

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

Acceso: Permiso del sistema backup.manage · Reintento: Se puede repetir con el mismo Idempotency-Key

Encola una verificación del punto id que lee cada byte almacenado de él; la respuesta es 202 con el trabajo, y el resultado aparece en verifiedAt, verifyDepth y verifyError del punto. Idempotency-Key es obligatorio, y reutilizarlo para otro punto produce un 409 idempotency_mismatch. Un punto desconocido es un 404.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
id	ruta	string (uuid)	sí	—
Idempotency-Key	encabezado	string	sí	coincide con ^[A-Za-z0-9_.:-]{1,128}$; Repeat returns the same job; per caller and operation kind.

Respuesta 202

Campo	Tipo	Obligatorio	Reglas
id	string (uuid)	sí	—
kind	string	sí	uno de capture, verify, retention
state	string	sí	uno de queued, running, committing, completed, failed, interrupted

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

Ejemplo

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

Fijar o desfijar un punto de copia de seguridad

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

Acceso: Permiso del sistema backup.manage · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto

Establece pinned del punto id; la retención conserva un punto fijado más allá de la política hasta que se desfije. Establecer de nuevo el mismo valor no cambia nada, y la respuesta es el punto actualizado. Un punto desconocido o ya descartado es un 404.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
id	ruta	string (uuid)	sí	—

Cuerpo de la solicitud (application/json)

Campo	Tipo	Obligatorio	Reglas
pinned	boolean	sí	—

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
id	string (uuid)	sí	—
snapshotAt	string (date-time)	sí	Hora T de la instantánea; la antigüedad de un punto se cuenta desde T.
completedAt	string (date-time)	sí	—
blobs	integer	sí	como mínimo 0
contentBytes	string	sí	un número entero en dígitos decimales, enviado como cadena
newBytes	string	sí	un número entero en dígitos decimales, enviado como cadena; Bytes que este punto añadió al almacén.
tables	integer	sí	como mínimo 0
rows	integer	sí	como mínimo 0
pinned	boolean	sí	—
verifiedAt	string (date-time)	sí	puede ser null
verifyDepth	string	sí	uno de structural, deep, null; puede ser null
verifyError	string	sí	coincide con ^[a-z][a-z0-9_]{0,63}$; puede ser null

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

Ejemplo

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

Previsualizar lo que conserva la retención de copias

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

Acceso: Permiso del sistema backup.read · Reintento: Se puede repetir (lectura)

Muestra qué puntos conservaría la política de retención, cada uno con los motivos (daily, weekly, monthly, pinned, newest), y cuáles eliminaría ahora. Los puntos que no superaron la verificación no se consideran. La vista previa es orientativa: requestBackupRetention vuelve a decidir a partir del almacén cuando se ejecuta.

Respuesta 200

Campo	Tipo	Obligatorio	Reglas
keep	array de object	sí	—
keep[].id	string (uuid)	sí	—
keep[].reasons	array de string	sí	cada elemento: uno de daily, weekly, monthly, pinned, newest
delete	array de object	sí	—
delete[].id	string (uuid)	sí	—

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

Ejemplo

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

Solicitar la retención de copias de seguridad

POST /api/v1/backup/retention/apply

Acceso: Permiso del sistema backup.manage · Reintento: Se puede repetir con el mismo Idempotency-Key

Encola un trabajo de retención: el agente descarta los puntos que quedan fuera de la política y después elimina el contenido que ningún punto restante usa, por lo que el espacio vuelve al almacén solo cuando el trabajo ha terminado. Devuelve 202 con el trabajo; Idempotency-Key es obligatorio y repetirlo devuelve el mismo trabajo. Consulte antes previewBackupRetention.

Parámetros

Nombre	Ubicación	Tipo	Obligatorio	Reglas
Idempotency-Key	encabezado	string	sí	coincide con ^[A-Za-z0-9_.:-]{1,128}$; Repeat returns the same job; per caller and operation kind.

Respuesta 202

Campo	Tipo	Obligatorio	Reglas
id	string (uuid)	sí	—
kind	string	sí	uno de capture, verify, retention
state	string	sí	uno de queued, running, committing, completed, failed, interrupted

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

Ejemplo

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