Backups
Status, plano, execuções, pontos, verificação e retenção do agente de backup integrado.
Operações deste grupo com a regra de acesso, a regra de repetição, os parâmetros e as respostas. Toda solicitação leva uma chave: Authorization: Bearer <chave> (consulte “Autenticação”).
Operações
Obter o status do backup
GET HEAD /api/v1/backup/status
Acesso: Permissão de sistema backup.read · Repetição: Pode ser repetida com segurança (leitura)
Resume o sistema de backup: o armazenamento de backups (vault) (configured, available, bytes livres e totais), o agente de backup (online, último heartbeat, versão), o plano, o ponto concluído mais recente, a próxima execução agendada, o job em execução e warnings, cada um um código como agent_offline ou backup_stale com severidade warning ou critical. O vault é informado como indisponível enquanto o agente está offline. Não contém caminhos nem segredos.
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
vault | object | sim | — |
vault.configured | boolean | sim | — |
vault.id | string (uuid) | sim | pode ser null |
vault.available | boolean | sim | — |
vault.encrypted | boolean | sim | pode ser null; O cofre está criptografado; null quando desconhecido ou não conectado. |
vault.freeBytes | string | sim | um número inteiro em dígitos decimais, enviado como string; pode ser null |
vault.totalBytes | string | sim | um número inteiro em dígitos decimais, enviado como string; pode ser null |
agent | object | sim | — |
agent.online | boolean | sim | — |
agent.lastSeenAt | string (date-time) | sim | pode ser null |
agent.version | string | sim | até 64 caracteres; pode ser null |
plan | object | sim | — |
plan.enabled | boolean | sim | — |
plan.hour | integer | sim | 0–23 |
plan.minute | integer | sim | 0–59 |
plan.timezone | string | sim | 1–64 caracteres; Fuso horário IANA explícito, por exemplo Europe/Moscow; validado pelo servidor. |
plan.retention | object | sim | — |
plan.retention.daily | integer | sim | 0–366 |
plan.retention.weekly | integer | sim | 0–260 |
plan.retention.monthly | integer | sim | 0–120 |
plan.revision | integer | sim | 0–2147483647 |
lastCompleted | object | sim | pode ser null |
lastCompleted.id | string (uuid) | sim | — |
lastCompleted.snapshotAt | string (date-time) | sim | Horário T do snapshot; a idade de um ponto é contada a partir de T. |
lastCompleted.completedAt | string (date-time) | sim | — |
lastCompleted.blobs | integer | sim | pelo menos 0 |
lastCompleted.contentBytes | string | sim | um número inteiro em dígitos decimais, enviado como string |
lastCompleted.newBytes | string | sim | um número inteiro em dígitos decimais, enviado como string; Bytes que este ponto adicionou ao vault. |
lastCompleted.tables | integer | sim | pelo menos 0 |
lastCompleted.rows | integer | sim | pelo menos 0 |
lastCompleted.pinned | boolean | sim | — |
lastCompleted.verifiedAt | string (date-time) | sim | pode ser null |
lastCompleted.verifyDepth | string | sim | um destes: structural, deep, null; pode ser null |
lastCompleted.verifyError | string | sim | corresponde a ^[a-z][a-z0-9_]{0,63}$; pode ser null |
nextRunAt | string (date-time) | sim | pode ser null |
running | object | sim | pode ser null |
running.id | string (uuid) | sim | — |
running.kind | string | sim | um destes: capture, verify, retention |
running.state | string | sim | um destes: queued, running, committing, completed, failed, interrupted |
running.phase | string | sim | corresponde a ^[a-z][a-z0-9_]{0,63}$; pode ser null |
running.startedAt | string (date-time) | sim | Início da execução ou, enquanto na fila, o horário da solicitação. |
running.finishedAt | string (date-time) | sim | pode ser null |
running.errorCode | string | sim | corresponde a ^[a-z][a-z0-9_]{0,63}$; pode ser null |
running.pointId | string (uuid) | sim | pode ser null |
running.progress | object | sim | — |
running.progress.bytesCopied | string | sim | um número inteiro em dígitos decimais, enviado como string; Bytes processados: copiados ou já presentes no vault. |
running.progress.bytesTotal | string | sim | um número inteiro em dígitos decimais, enviado como string |
running.progress.blobsCopied | integer | sim | pelo menos 0 |
running.progress.blobsTotal | integer | sim | pelo menos 0 |
warnings | array de object | sim | até 10 itens |
warnings[].code | string | sim | um destes: 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 | sim | um destes: warning, critical |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/backup/status" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Obter o plano de backup
GET HEAD /api/v1/backup/plan
Acesso: Permissão de sistema backup.read · Repetição: Pode ser repetida com segurança (leitura)
Retorna o agendamento diário (enabled, hour e minute no timezone IANA) e a política de retenção (pontos daily, weekly, monthly a manter) com a revision a ser enviada de volta a updateBackupPlan. Enquanto não for alterado, o plano está desativado, com agendamento às 02:00 UTC e 7 pontos diários, 4 semanais e 6 mensais.
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
enabled | boolean | sim | — |
hour | integer | sim | 0–23 |
minute | integer | sim | 0–59 |
timezone | string | sim | 1–64 caracteres; Fuso horário IANA explícito, por exemplo Europe/Moscow; validado pelo servidor. |
retention | object | sim | — |
retention.daily | integer | sim | 0–366 |
retention.weekly | integer | sim | 0–260 |
retention.monthly | integer | sim | 0–120 |
revision | integer | sim | 0–2147483647 |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/backup/plan" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Substituir o plano de backup
PUT /api/v1/backup/plan
Acesso: Permissão de sistema backup.manage · Repetição: Repetir somente com a revisão esperada (compare-and-swap)
Substitui o plano inteiro: enabled, hour (0–23), minute (0–59), timezone e retention (no máximo 366 diários, 260 semanais, 120 mensais) devem estar todos presentes. expectedRevision deve ser a revisão atual; caso contrário, 409 revision_mismatch; um campo inválido gera 400 com um JSON Pointer em details. O agente segue o novo agendamento a partir da sua próxima verificação.
Corpo da solicitação (application/json)
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
expectedRevision | integer | sim | 0–2147483647 |
enabled | boolean | sim | — |
hour | integer | sim | 0–23 |
minute | integer | sim | 0–59 |
timezone | string | sim | 1–64 caracteres; Fuso horário IANA explícito, por exemplo Europe/Moscow; validado pelo servidor. |
retention | object | sim | — |
retention.daily | integer | sim | 0–366 |
retention.weekly | integer | sim | 0–260 |
retention.monthly | integer | sim | 0–120 |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
enabled | boolean | sim | — |
hour | integer | sim | 0–23 |
minute | integer | sim | 0–59 |
timezone | string | sim | 1–64 caracteres; Fuso horário IANA explícito, por exemplo Europe/Moscow; validado pelo servidor. |
retention | object | sim | — |
retention.daily | integer | sim | 0–366 |
retention.weekly | integer | sim | 0–260 |
retention.monthly | integer | sim | 0–120 |
revision | integer | sim | 0–2147483647 |
Respostas: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Exemplo
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 um backup agora
POST /api/v1/backup/runs
Acesso: Permissão de sistema backup.manage · Repetição: Pode ser repetida com segurança com a mesma Idempotency-Key
Enfileira uma captura para o agente de backup fora do agendamento e retorna 202 com o job (kind capture); o agente a executa e, em seguida, a verificação e a retenção. Idempotency-Key é obrigatória: repeti-la, pelo mesmo chamador, retorna o mesmo job. Acompanhe o job em listBackupJobs. No máximo 100 solicitações de backup podem estar abertas ao mesmo tempo (507 queue_full); enquanto nenhum agente está online, o job espera.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
Idempotency-Key | cabeçalho | string | sim | corresponde a ^[A-Za-z0-9_.:-]{1,128}$; Repeat returns the same job; per caller and operation kind. |
Resposta 202
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
id | string (uuid) | sim | — |
kind | string | sim | um destes: capture, verify, retention |
state | string | sim | um destes: queued, running, committing, completed, failed, interrupted |
Respostas: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemplo
curl -X POST "$ARKVORY_URL/api/v1/backup/runs" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"Listar os jobs de backup
GET HEAD /api/v1/backup/jobs
Acesso: Permissão de sistema backup.read · Repetição: Pode ser repetida com segurança (leitura)
Lista os jobs de captura, verificação e retenção, do mais recente para o mais antigo, cada um com seu state (queued, running, committing, completed, failed, interrupted), phase, horários, errorCode, o ponto resultante e o progress (bytes e objetos processados). As páginas contêm limit jobs (1–100, padrão 50); continue com after definido como next.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
after | consulta | string | não | corresponde a ^[0-9]{1,17}_[0-9a-f-]{36}$; next of the previous page |
limit | consulta | integer | não | 1–100; padrão 50 |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
items | array de object | sim | até 100 itens |
items[].id | string (uuid) | sim | — |
items[].kind | string | sim | um destes: capture, verify, retention |
items[].state | string | sim | um destes: queued, running, committing, completed, failed, interrupted |
items[].phase | string | sim | corresponde a ^[a-z][a-z0-9_]{0,63}$; pode ser null |
items[].startedAt | string (date-time) | sim | Início da execução ou, enquanto na fila, o horário da solicitação. |
items[].finishedAt | string (date-time) | sim | pode ser null |
items[].errorCode | string | sim | corresponde a ^[a-z][a-z0-9_]{0,63}$; pode ser null |
items[].pointId | string (uuid) | sim | pode ser null |
items[].progress | object | sim | — |
items[].progress.bytesCopied | string | sim | um número inteiro em dígitos decimais, enviado como string; Bytes processados: copiados ou já presentes no vault. |
items[].progress.bytesTotal | string | sim | um número inteiro em dígitos decimais, enviado como string |
items[].progress.blobsCopied | integer | sim | pelo menos 0 |
items[].progress.blobsTotal | integer | sim | pelo menos 0 |
next | string | sim | corresponde a ^[0-9]{1,17}_[0-9a-f-]{36}$; pode ser null |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/backup/jobs" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Listar os pontos de backup
GET HEAD /api/v1/backup/points
Acesso: Permissão de sistema backup.read · Repetição: Pode ser repetida com segurança (leitura)
Lista os pontos de restauração concluídos do vault atual, com o snapshot mais recente primeiro, cada um com o horário T do snapshot, tamanho, bytes adicionados ao vault, se está pinned e sua verificação mais recente (verifiedAt, verifyDepth structural ou deep, verifyError). As páginas contêm limit pontos (1–100, padrão 50); continue com after definido como next. Um vault que foi substituído mostra apenas os seus próprios pontos.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
after | consulta | string | não | corresponde a ^[0-9]{1,17}_[0-9a-f-]{36}$; next of the previous page |
limit | consulta | integer | não | 1–100; padrão 50 |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
items | array de object | sim | até 100 itens |
items[].id | string (uuid) | sim | — |
items[].snapshotAt | string (date-time) | sim | Horário T do snapshot; a idade de um ponto é contada a partir de T. |
items[].completedAt | string (date-time) | sim | — |
items[].blobs | integer | sim | pelo menos 0 |
items[].contentBytes | string | sim | um número inteiro em dígitos decimais, enviado como string |
items[].newBytes | string | sim | um número inteiro em dígitos decimais, enviado como string; Bytes que este ponto adicionou ao vault. |
items[].tables | integer | sim | pelo menos 0 |
items[].rows | integer | sim | pelo menos 0 |
items[].pinned | boolean | sim | — |
items[].verifiedAt | string (date-time) | sim | pode ser null |
items[].verifyDepth | string | sim | um destes: structural, deep, null; pode ser null |
items[].verifyError | string | sim | corresponde a ^[a-z][a-z0-9_]{0,63}$; pode ser null |
next | string | sim | corresponde a ^[0-9]{1,17}_[0-9a-f-]{36}$; pode ser null |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/backup/points" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Solicitar uma verificação profunda de um ponto de backup
POST /api/v1/backup/points/{id}/verify
Acesso: Permissão de sistema backup.manage · Repetição: Pode ser repetida com segurança com a mesma Idempotency-Key
Enfileira uma verificação do ponto id que lê todos os bytes armazenados dele; a resposta é 202 com o job, e o resultado aparece em verifiedAt, verifyDepth e verifyError do ponto. Idempotency-Key é obrigatória, e reutilizá-la para outro ponto gera 409 idempotency_mismatch. Um ponto desconhecido gera 404.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
id | caminho | string (uuid) | sim | — |
Idempotency-Key | cabeçalho | string | sim | corresponde a ^[A-Za-z0-9_.:-]{1,128}$; Repeat returns the same job; per caller and operation kind. |
Resposta 202
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
id | string (uuid) | sim | — |
kind | string | sim | um destes: capture, verify, retention |
state | string | sim | um destes: queued, running, committing, completed, failed, interrupted |
Respostas: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemplo
curl -X POST "$ARKVORY_URL/api/v1/backup/points/$ID/verify" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"Fixar ou desafixar um ponto de backup
PUT /api/v1/backup/points/{id}/pin
Acesso: Permissão de sistema backup.manage · Repetição: Pode ser repetida com segurança: a mesma solicitação tem o mesmo efeito
Define pinned do ponto id; um ponto fixado é mantido pela retenção além da política até ser desafixado. Definir o mesmo valor novamente não altera nada, e a resposta é o ponto atualizado. Um ponto desconhecido ou já descartado gera 404.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
id | caminho | string (uuid) | sim | — |
Corpo da solicitação (application/json)
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
pinned | boolean | sim | — |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
id | string (uuid) | sim | — |
snapshotAt | string (date-time) | sim | Horário T do snapshot; a idade de um ponto é contada a partir de T. |
completedAt | string (date-time) | sim | — |
blobs | integer | sim | pelo menos 0 |
contentBytes | string | sim | um número inteiro em dígitos decimais, enviado como string |
newBytes | string | sim | um número inteiro em dígitos decimais, enviado como string; Bytes que este ponto adicionou ao vault. |
tables | integer | sim | pelo menos 0 |
rows | integer | sim | pelo menos 0 |
pinned | boolean | sim | — |
verifiedAt | string (date-time) | sim | pode ser null |
verifyDepth | string | sim | um destes: structural, deep, null; pode ser null |
verifyError | string | sim | corresponde a ^[a-z][a-z0-9_]{0,63}$; pode ser null |
Respostas: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Exemplo
curl -X PUT "$ARKVORY_URL/api/v1/backup/points/$ID/pin" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"pinned":false}'Pré-visualizar o que a retenção de backups mantém
GET HEAD /api/v1/backup/retention/preview
Acesso: Permissão de sistema backup.read · Repetição: Pode ser repetida com segurança (leitura)
Mostra quais pontos a política de retenção manteria, cada um com os motivos (daily, weekly, monthly, pinned, newest), e quais ela excluiria agora. Pontos que falharam na verificação não são considerados. A pré-visualização é apenas informativa: requestBackupRetention decide novamente a partir do vault quando for executado.
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
keep | array de object | sim | — |
keep[].id | string (uuid) | sim | — |
keep[].reasons | array de string | sim | cada item: um destes: daily, weekly, monthly, pinned, newest |
delete | array de object | sim | — |
delete[].id | string (uuid) | sim | — |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/backup/retention/preview" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Solicitar a retenção de backups
POST /api/v1/backup/retention/apply
Acesso: Permissão de sistema backup.manage · Repetição: Pode ser repetida com segurança com a mesma Idempotency-Key
Enfileira um job de retenção: o agente descarta os pontos fora da política e depois remove o conteúdo que nenhum ponto restante usa, de modo que o espaço só volta ao vault quando o job é concluído. Retorna 202 com o job; Idempotency-Key é obrigatória e repeti-la retorna o mesmo job. Consulte antes previewBackupRetention.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
Idempotency-Key | cabeçalho | string | sim | corresponde a ^[A-Za-z0-9_.:-]{1,128}$; Repeat returns the same job; per caller and operation kind. |
Resposta 202
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
id | string (uuid) | sim | — |
kind | string | sim | um destes: capture, verify, retention |
state | string | sim | um destes: queued, running, committing, completed, failed, interrupted |
Respostas: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemplo
curl -X POST "$ARKVORY_URL/api/v1/backup/retention/apply" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"