Sauvegardes
État, plan, exécutions, points, vérification et rétention de l’agent de sauvegarde intégré.
Opérations de ce groupe, avec leur règle d’accès, leur règle de nouvelle tentative, leurs paramètres et leurs réponses. Chaque requête porte une clé : Authorization: Bearer <clé> (voir « Authentification »).
Opérations
Obtenir l’état de la sauvegarde
GET HEAD /api/v1/backup/status
Accès: Autorisation système backup.read · Nouvelle tentative: Peut être répétée sans risque (lecture)
Résume le système de sauvegarde : le stockage des sauvegardes (configured, available, octets libres et totaux), l’agent de sauvegarde (online, dernier signal de vie, version), le plan, le dernier point terminé, la prochaine exécution planifiée, la tâche en cours et les warnings, chacun étant un code comme agent_offline ou backup_stale avec la gravité warning ou critical. Le stockage des sauvegardes est signalé indisponible tant que l’agent est hors ligne. La réponse ne contient ni chemins ni secrets.
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
vault | object | oui | — |
vault.configured | boolean | oui | — |
vault.id | string (uuid) | oui | peut être null |
vault.available | boolean | oui | — |
vault.encrypted | boolean | oui | peut être null; Le coffre est chiffré ; null si inconnu ou non connecté. |
vault.freeBytes | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne; peut être null |
vault.totalBytes | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne; peut être null |
agent | object | oui | — |
agent.online | boolean | oui | — |
agent.lastSeenAt | string (date-time) | oui | peut être null |
agent.version | string | oui | jusqu’à 64 caractères; peut être null |
plan | object | oui | — |
plan.enabled | boolean | oui | — |
plan.hour | integer | oui | 0–23 |
plan.minute | integer | oui | 0–59 |
plan.timezone | string | oui | 1–64 caractères; Fuseau horaire IANA explicite, par exemple Europe/Moscow ; validé par le serveur. |
plan.retention | object | oui | — |
plan.retention.daily | integer | oui | 0–366 |
plan.retention.weekly | integer | oui | 0–260 |
plan.retention.monthly | integer | oui | 0–120 |
plan.revision | integer | oui | 0–2147483647 |
lastCompleted | object | oui | peut être null |
lastCompleted.id | string (uuid) | oui | — |
lastCompleted.snapshotAt | string (date-time) | oui | Heure d’instantané T ; l’âge d’un point se compte à partir de T. |
lastCompleted.completedAt | string (date-time) | oui | — |
lastCompleted.blobs | integer | oui | au moins 0 |
lastCompleted.contentBytes | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne |
lastCompleted.newBytes | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne; Octets que ce point a ajoutés au stockage des sauvegardes. |
lastCompleted.tables | integer | oui | au moins 0 |
lastCompleted.rows | integer | oui | au moins 0 |
lastCompleted.pinned | boolean | oui | — |
lastCompleted.verifiedAt | string (date-time) | oui | peut être null |
lastCompleted.verifyDepth | string | oui | une valeur parmi structural, deep, null; peut être null |
lastCompleted.verifyError | string | oui | correspond à ^[a-z][a-z0-9_]{0,63}$; peut être null |
nextRunAt | string (date-time) | oui | peut être null |
running | object | oui | peut être null |
running.id | string (uuid) | oui | — |
running.kind | string | oui | une valeur parmi capture, verify, retention |
running.state | string | oui | une valeur parmi queued, running, committing, completed, failed, interrupted |
running.phase | string | oui | correspond à ^[a-z][a-z0-9_]{0,63}$; peut être null |
running.startedAt | string (date-time) | oui | Début de l’exécution, ou heure de la demande tant qu’elle est en file. |
running.finishedAt | string (date-time) | oui | peut être null |
running.errorCode | string | oui | correspond à ^[a-z][a-z0-9_]{0,63}$; peut être null |
running.pointId | string (uuid) | oui | peut être null |
running.progress | object | oui | — |
running.progress.bytesCopied | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne; Octets traités : copiés ou déjà présents dans le stockage des sauvegardes. |
running.progress.bytesTotal | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne |
running.progress.blobsCopied | integer | oui | au moins 0 |
running.progress.blobsTotal | integer | oui | au moins 0 |
warnings | tableau de object | oui | jusqu’à 10 éléments |
warnings[].code | string | oui | une valeur parmi 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 | oui | une valeur parmi warning, critical |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/backup/status" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Obtenir le plan de sauvegarde
GET HEAD /api/v1/backup/plan
Accès: Autorisation système backup.read · Nouvelle tentative: Peut être répétée sans risque (lecture)
Renvoie la planification quotidienne (enabled, hour et minute dans le fuseau IANA timezone) et la politique de rétention (points daily, weekly, monthly à conserver) avec la revision à renvoyer à updateBackupPlan. Tant qu’il n’est pas modifié, le plan est désactivé, avec une planification à 02:00 UTC et 7 points quotidiens, 4 hebdomadaires et 6 mensuels.
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
enabled | boolean | oui | — |
hour | integer | oui | 0–23 |
minute | integer | oui | 0–59 |
timezone | string | oui | 1–64 caractères; Fuseau horaire IANA explicite, par exemple Europe/Moscow ; validé par le serveur. |
retention | object | oui | — |
retention.daily | integer | oui | 0–366 |
retention.weekly | integer | oui | 0–260 |
retention.monthly | integer | oui | 0–120 |
revision | integer | oui | 0–2147483647 |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/backup/plan" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Remplacer le plan de sauvegarde
PUT /api/v1/backup/plan
Accès: Autorisation système backup.manage · Nouvelle tentative: Répéter uniquement avec la révision attendue (compare-and-swap)
Remplace tout le plan : enabled, hour (0–23), minute (0–59), timezone et retention (366 quotidiens, 260 hebdomadaires et 120 mensuels au plus) doivent tous être présents. expectedRevision doit être la révision actuelle, sinon 409 revision_mismatch ; un champ invalide donne 400 avec un JSON Pointer dans details. L’agent suit la nouvelle planification dès sa prochaine vérification.
Corps de la requête (application/json)
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
expectedRevision | integer | oui | 0–2147483647 |
enabled | boolean | oui | — |
hour | integer | oui | 0–23 |
minute | integer | oui | 0–59 |
timezone | string | oui | 1–64 caractères; Fuseau horaire IANA explicite, par exemple Europe/Moscow ; validé par le serveur. |
retention | object | oui | — |
retention.daily | integer | oui | 0–366 |
retention.weekly | integer | oui | 0–260 |
retention.monthly | integer | oui | 0–120 |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
enabled | boolean | oui | — |
hour | integer | oui | 0–23 |
minute | integer | oui | 0–59 |
timezone | string | oui | 1–64 caractères; Fuseau horaire IANA explicite, par exemple Europe/Moscow ; validé par le serveur. |
retention | object | oui | — |
retention.daily | integer | oui | 0–366 |
retention.weekly | integer | oui | 0–260 |
retention.monthly | integer | oui | 0–120 |
revision | integer | oui | 0–2147483647 |
Réponses: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Exemple
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}}'Demander une sauvegarde maintenant
POST /api/v1/backup/runs
Accès: Autorisation système backup.manage · Nouvelle tentative: Peut être répétée sans risque avec la même Idempotency-Key
Met en file une capture pour l’agent de sauvegarde en dehors de la planification et renvoie 202 avec la tâche (kind capture) ; l’agent l’exécute, puis effectue la vérification et la rétention. Idempotency-Key est obligatoire : la répéter, depuis le même appelant, renvoie la même tâche. Suivez la tâche dans listBackupJobs. Au plus 100 demandes de sauvegarde peuvent être ouvertes à la fois (507 queue_full) ; tant qu’aucun agent n’est en ligne, la tâche attend.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
Idempotency-Key | en-tête | string | oui | correspond à ^[A-Za-z0-9_.:-]{1,128}$; Repeat returns the same job; per caller and operation kind. |
Réponse 202
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
id | string (uuid) | oui | — |
kind | string | oui | une valeur parmi capture, verify, retention |
state | string | oui | une valeur parmi queued, running, committing, completed, failed, interrupted |
Réponses: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemple
curl -X POST "$ARKVORY_URL/api/v1/backup/runs" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"Lister les tâches de sauvegarde
GET HEAD /api/v1/backup/jobs
Accès: Autorisation système backup.read · Nouvelle tentative: Peut être répétée sans risque (lecture)
Liste les tâches de capture, de vérification et de rétention, de la plus récente à la plus ancienne, chacune avec son state (queued, running, committing, completed, failed, interrupted), sa phase, ses heures, son errorCode, le point obtenu et progress (octets et objets traités). Les pages contiennent limit tâches (1–100, 50 par défaut) ; poursuivez avec after défini sur next.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
after | requête | string | non | correspond à ^[0-9]{1,17}_[0-9a-f-]{36}$; next of the previous page |
limit | requête | integer | non | 1–100; par défaut 50 |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
items | tableau de object | oui | jusqu’à 100 éléments |
items[].id | string (uuid) | oui | — |
items[].kind | string | oui | une valeur parmi capture, verify, retention |
items[].state | string | oui | une valeur parmi queued, running, committing, completed, failed, interrupted |
items[].phase | string | oui | correspond à ^[a-z][a-z0-9_]{0,63}$; peut être null |
items[].startedAt | string (date-time) | oui | Début de l’exécution, ou heure de la demande tant qu’elle est en file. |
items[].finishedAt | string (date-time) | oui | peut être null |
items[].errorCode | string | oui | correspond à ^[a-z][a-z0-9_]{0,63}$; peut être null |
items[].pointId | string (uuid) | oui | peut être null |
items[].progress | object | oui | — |
items[].progress.bytesCopied | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne; Octets traités : copiés ou déjà présents dans le stockage des sauvegardes. |
items[].progress.bytesTotal | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne |
items[].progress.blobsCopied | integer | oui | au moins 0 |
items[].progress.blobsTotal | integer | oui | au moins 0 |
next | string | oui | correspond à ^[0-9]{1,17}_[0-9a-f-]{36}$; peut être null |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/backup/jobs" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Lister les points de sauvegarde
GET HEAD /api/v1/backup/points
Accès: Autorisation système backup.read · Nouvelle tentative: Peut être répétée sans risque (lecture)
Liste les points de restauration terminés du stockage des sauvegardes actuel, l’instantané le plus récent en premier, chacun avec l’heure d’instantané T, la taille, les octets ajoutés au stockage, son état épinglé (pinned) et sa dernière vérification (verifiedAt, verifyDepth structural ou deep, verifyError). Les pages contiennent limit points (1–100, 50 par défaut) ; poursuivez avec after défini sur next. Un stockage des sauvegardes remplacé n’affiche que ses propres points.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
after | requête | string | non | correspond à ^[0-9]{1,17}_[0-9a-f-]{36}$; next of the previous page |
limit | requête | integer | non | 1–100; par défaut 50 |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
items | tableau de object | oui | jusqu’à 100 éléments |
items[].id | string (uuid) | oui | — |
items[].snapshotAt | string (date-time) | oui | Heure d’instantané T ; l’âge d’un point se compte à partir de T. |
items[].completedAt | string (date-time) | oui | — |
items[].blobs | integer | oui | au moins 0 |
items[].contentBytes | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne |
items[].newBytes | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne; Octets que ce point a ajoutés au stockage des sauvegardes. |
items[].tables | integer | oui | au moins 0 |
items[].rows | integer | oui | au moins 0 |
items[].pinned | boolean | oui | — |
items[].verifiedAt | string (date-time) | oui | peut être null |
items[].verifyDepth | string | oui | une valeur parmi structural, deep, null; peut être null |
items[].verifyError | string | oui | correspond à ^[a-z][a-z0-9_]{0,63}$; peut être null |
next | string | oui | correspond à ^[0-9]{1,17}_[0-9a-f-]{36}$; peut être null |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/backup/points" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Demander une vérification approfondie d’un point de sauvegarde
POST /api/v1/backup/points/{id}/verify
Accès: Autorisation système backup.manage · Nouvelle tentative: Peut être répétée sans risque avec la même Idempotency-Key
Met en file une vérification du point id qui lit chaque octet stocké de ce point ; la réponse est 202 avec la tâche, et le résultat apparaît dans verifiedAt, verifyDepth et verifyError du point. Idempotency-Key est obligatoire, et la réutiliser pour un autre point donne 409 idempotency_mismatch. Un point inconnu donne 404.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
id | chemin | string (uuid) | oui | — |
Idempotency-Key | en-tête | string | oui | correspond à ^[A-Za-z0-9_.:-]{1,128}$; Repeat returns the same job; per caller and operation kind. |
Réponse 202
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
id | string (uuid) | oui | — |
kind | string | oui | une valeur parmi capture, verify, retention |
state | string | oui | une valeur parmi queued, running, committing, completed, failed, interrupted |
Réponses: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemple
curl -X POST "$ARKVORY_URL/api/v1/backup/points/$ID/verify" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"Épingler ou désépingler un point de sauvegarde
PUT /api/v1/backup/points/{id}/pin
Accès: Autorisation système backup.manage · Nouvelle tentative: Peut être répétée sans risque : la même requête a le même effet
Définit pinned du point id ; un point épinglé est conservé par la rétention au-delà de la politique jusqu’à ce qu’il soit désépinglé. Définir de nouveau la même valeur ne change rien, et la réponse est le point mis à jour. Un point inconnu ou déjà oublié donne 404.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
id | chemin | string (uuid) | oui | — |
Corps de la requête (application/json)
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
pinned | boolean | oui | — |
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
id | string (uuid) | oui | — |
snapshotAt | string (date-time) | oui | Heure d’instantané T ; l’âge d’un point se compte à partir de T. |
completedAt | string (date-time) | oui | — |
blobs | integer | oui | au moins 0 |
contentBytes | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne |
newBytes | string | oui | un nombre entier en chiffres décimaux, transmis sous forme de chaîne; Octets que ce point a ajoutés au stockage des sauvegardes. |
tables | integer | oui | au moins 0 |
rows | integer | oui | au moins 0 |
pinned | boolean | oui | — |
verifiedAt | string (date-time) | oui | peut être null |
verifyDepth | string | oui | une valeur parmi structural, deep, null; peut être null |
verifyError | string | oui | correspond à ^[a-z][a-z0-9_]{0,63}$; peut être null |
Réponses: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Exemple
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évisualiser ce que la rétention des sauvegardes conserve
GET HEAD /api/v1/backup/retention/preview
Accès: Autorisation système backup.read · Nouvelle tentative: Peut être répétée sans risque (lecture)
Montre quels points la politique de rétention conserverait, chacun avec ses raisons (daily, weekly, monthly, pinned, newest), et lesquels elle supprimerait maintenant. Les points dont la vérification a échoué ne sont pas pris en compte. L’aperçu est indicatif : requestBackupRetention décide de nouveau à partir du stockage des sauvegardes lors de son exécution.
Réponse 200
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
keep | tableau de object | oui | — |
keep[].id | string (uuid) | oui | — |
keep[].reasons | tableau de string | oui | chaque élément : une valeur parmi daily, weekly, monthly, pinned, newest |
delete | tableau de object | oui | — |
delete[].id | string (uuid) | oui | — |
Réponses: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemple
curl -X GET "$ARKVORY_URL/api/v1/backup/retention/preview" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Demander la rétention des sauvegardes
POST /api/v1/backup/retention/apply
Accès: Autorisation système backup.manage · Nouvelle tentative: Peut être répétée sans risque avec la même Idempotency-Key
Met en file une tâche de rétention : l’agent oublie les points hors de la politique, puis supprime le contenu qu’aucun point restant n’utilise ; l’espace ne revient donc au stockage des sauvegardes qu’une fois la tâche terminée. Renvoie 202 avec la tâche ; Idempotency-Key est obligatoire et la répéter renvoie la même tâche. Consultez d’abord previewBackupRetention.
Paramètres
| Nom | Emplacement | Type | Obligatoire | Règles |
|---|---|---|---|---|
Idempotency-Key | en-tête | string | oui | correspond à ^[A-Za-z0-9_.:-]{1,128}$; Repeat returns the same job; per caller and operation kind. |
Réponse 202
| Champ | Type | Obligatoire | Règles |
|---|---|---|---|
id | string (uuid) | oui | — |
kind | string | oui | une valeur parmi capture, verify, retention |
state | string | oui | une valeur parmi queued, running, committing, completed, failed, interrupted |
Réponses: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemple
curl -X POST "$ARKVORY_URL/api/v1/backup/retention/apply" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"