バックアップ

組み込みのバックアップエージェントの状態、プラン、実行、復元ポイント、検証、保持。

このグループの操作と、それぞれのアクセスルール、再試行ルール、パラメーター、レスポンスです。すべてのリクエストにはキーを付けます：Authorization: Bearer <key>（「認証」を参照）。

操作

バックアップ状態の取得

GET HEAD /api/v1/backup/status

アクセス: システム権限backup.read · 再試行: 再試行しても安全（読み取り）

バックアップシステムの概要を返します。内容は、保管庫（configured、available、空きバイト数と合計バイト数）、バックアップエージェント（online、最後のハートビート、バージョン）、プラン、完了した最新の復元ポイント、次回のスケジュール実行、実行中のジョブ、そしてwarningsです。warningsはそれぞれagent_offlineやbackup_staleのようなコードと、重大度warningまたはcriticalを持ちます。エージェントがオフラインの間、保管庫は利用不可として報告されます。パスやシークレットは含まれません。

レスポンス 200

フィールド	型	必須	ルール
`vault`	object	はい	—
`vault.configured`	boolean	はい	—
`vault.id`	string (uuid)	はい	nullも可
`vault.available`	boolean	はい	—
`vault.encrypted`	boolean	はい	nullも可; ボールトが暗号化されているか。不明または未接続の場合は null。
`vault.freeBytes`	string	はい	10進数字で表した整数（文字列として送信）; nullも可
`vault.totalBytes`	string	はい	10進数字で表した整数（文字列として送信）; nullも可
`agent`	object	はい	—
`agent.online`	boolean	はい	—
`agent.lastSeenAt`	string (date-time)	はい	nullも可
`agent.version`	string	はい	64文字以内; nullも可
`plan`	object	はい	—
`plan.enabled`	boolean	はい	—
`plan.hour`	integer	はい	0～23
`plan.minute`	integer	はい	0～59
`plan.timezone`	string	はい	1～64文字; 明示的なIANAタイムゾーン（例：Europe/Moscow）。サーバーが検証します。
`plan.retention`	object	はい	—
`plan.retention.daily`	integer	はい	0～366
`plan.retention.weekly`	integer	はい	0～260
`plan.retention.monthly`	integer	はい	0～120
`plan.revision`	integer	はい	0～2147483647
`lastCompleted`	object	はい	nullも可
`lastCompleted.id`	string (uuid)	はい	—
`lastCompleted.snapshotAt`	string (date-time)	はい	スナップショット時刻T。ポイントの経過期間はTから数えます。
`lastCompleted.completedAt`	string (date-time)	はい	—
`lastCompleted.blobs`	integer	はい	0以上
`lastCompleted.contentBytes`	string	はい	10進数字で表した整数（文字列として送信）
`lastCompleted.newBytes`	string	はい	10進数字で表した整数（文字列として送信）; このポイントが保管庫に追加したバイト数。
`lastCompleted.tables`	integer	はい	0以上
`lastCompleted.rows`	integer	はい	0以上
`lastCompleted.pinned`	boolean	はい	—
`lastCompleted.verifiedAt`	string (date-time)	はい	nullも可
`lastCompleted.verifyDepth`	string	はい	次のいずれか：`structural`, `deep`, `null`; nullも可
`lastCompleted.verifyError`	string	はい	`^[a-z][a-z0-9_]{0,63}$`に一致; nullも可
`nextRunAt`	string (date-time)	はい	nullも可
`running`	object	はい	nullも可
`running.id`	string (uuid)	はい	—
`running.kind`	string	はい	次のいずれか：`capture`, `verify`, `retention`
`running.state`	string	はい	次のいずれか：`queued`, `running`, `committing`, `completed`, `failed`, `interrupted`
`running.phase`	string	はい	`^[a-z][a-z0-9_]{0,63}$`に一致; nullも可
`running.startedAt`	string (date-time)	はい	実行の開始時刻。キューで待機している間はリクエスト時刻。
`running.finishedAt`	string (date-time)	はい	nullも可
`running.errorCode`	string	はい	`^[a-z][a-z0-9_]{0,63}$`に一致; nullも可
`running.pointId`	string (uuid)	はい	nullも可
`running.progress`	object	はい	—
`running.progress.bytesCopied`	string	はい	10進数字で表した整数（文字列として送信）; 処理済みのバイト数。コピーしたもの、またはすでに保管庫にあるもの。
`running.progress.bytesTotal`	string	はい	10進数字で表した整数（文字列として送信）
`running.progress.blobsCopied`	integer	はい	0以上
`running.progress.blobsTotal`	integer	はい	0以上
`warnings`	objectの配列	はい	10個以内の要素
`warnings[].code`	string	はい	次のいずれか：`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	はい	次のいずれか：`warning`, `critical`

レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507

例

bash

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

バックアッププランの取得

GET HEAD /api/v1/backup/plan

アクセス: システム権限backup.read · 再試行: 再試行しても安全（読み取り）

毎日のスケジュール（enabled、IANAのtimezoneでのhourとminute）と、保持ポリシー（残すdaily、weekly、monthlyのポイント数）を、updateBackupPlanに送り返すためのrevisionとともに返します。変更するまでプランは無効で、スケジュールは02:00 UTC、保持は日次7件、週次4件、月次6件です。

レスポンス 200

フィールド	型	必須	ルール
`enabled`	boolean	はい	—
`hour`	integer	はい	0～23
`minute`	integer	はい	0～59
`timezone`	string	はい	1～64文字; 明示的なIANAタイムゾーン（例：Europe/Moscow）。サーバーが検証します。
`retention`	object	はい	—
`retention.daily`	integer	はい	0～366
`retention.weekly`	integer	はい	0～260
`retention.monthly`	integer	はい	0～120
`revision`	integer	はい	0～2147483647

レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507

例

bash

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

バックアッププランの置換

PUT /api/v1/backup/plan

アクセス: システム権限backup.manage · 再試行: 想定するリビジョンを指定した場合のみ再試行（compare-and-swap）

プラン全体を置き換えます。enabled、hour（0〜23）、minute（0〜59）、timezone、retention（日次は最大366、週次は最大260、月次は最大120）はすべて必須です。expectedRevisionは現在のリビジョンでなければならず、そうでない場合は409 revision_mismatchになります。無効なフィールドは400で、detailsにJSON Pointerが含まれます。エージェントは、次の確認から新しいスケジュールに従います。

リクエスト本文 (application/json)

フィールド	型	必須	ルール
`expectedRevision`	integer	はい	0～2147483647
`enabled`	boolean	はい	—
`hour`	integer	はい	0～23
`minute`	integer	はい	0～59
`timezone`	string	はい	1～64文字; 明示的なIANAタイムゾーン（例：Europe/Moscow）。サーバーが検証します。
`retention`	object	はい	—
`retention.daily`	integer	はい	0～366
`retention.weekly`	integer	はい	0～260
`retention.monthly`	integer	はい	0～120

レスポンス 200

フィールド	型	必須	ルール
`enabled`	boolean	はい	—
`hour`	integer	はい	0～23
`minute`	integer	はい	0～59
`timezone`	string	はい	1～64文字; 明示的なIANAタイムゾーン（例：Europe/Moscow）。サーバーが検証します。
`retention`	object	はい	—
`retention.daily`	integer	はい	0～366
`retention.weekly`	integer	はい	0～260
`retention.monthly`	integer	はい	0～120
`revision`	integer	はい	0～2147483647

レスポンス: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

例

bash

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

バックアップの即時実行の要求

POST /api/v1/backup/runs

アクセス: システム権限backup.manage · 再試行: 同じIdempotency-Keyを使えば再試行しても安全

スケジュール外で、バックアップエージェント用のキャプチャをキューへ登録し、ジョブ（kindはcapture）とともに202を返します。エージェントがそれを実行し、続いて検証と保持を行います。Idempotency-Keyは必須で、同じ呼び出し元が繰り返すと同じジョブが返ります。ジョブはlistBackupJobsで確認してください。同時に未完了にできるバックアップ要求は最大100件です（507 queue_full）。オンラインのエージェントがない間、ジョブは待機します。

パラメーター

名前	場所	型	必須	ルール
`Idempotency-Key`	ヘッダー	string	はい	`^[A-Za-z0-9_.:-]{1,128}$`に一致; Repeat returns the same job; per caller and operation kind.

レスポンス 202

フィールド	型	必須	ルール
`id`	string (uuid)	はい	—
`kind`	string	はい	次のいずれか：`capture`, `verify`, `retention`
`state`	string	はい	次のいずれか：`queued`, `running`, `committing`, `completed`, `failed`, `interrupted`

レスポンス: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507

例

bash

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

バックアップジョブの一覧表示

GET HEAD /api/v1/backup/jobs

アクセス: システム権限backup.read · 再試行: 再試行しても安全（読み取り）

キャプチャ、検証、保持のジョブを新しい順に列挙します。各ジョブには、state（queued、running、committing、completed、failed、interrupted）、phase、時刻、errorCode、結果のポイント、progress（処理したバイト数とオブジェクト数）が含まれます。ページにはlimit件のジョブ（1〜100、既定は50）が含まれ、続きはafterにnextを設定して取得します。

パラメーター

名前	場所	型	必須	ルール
`after`	クエリ	string	いいえ	`^[0-9]{1,17}_[0-9a-f-]{36}$`に一致; next of the previous page
`limit`	クエリ	integer	いいえ	1～100; 既定値：`50`

レスポンス 200

フィールド	型	必須	ルール
`items`	objectの配列	はい	100個以内の要素
`items[].id`	string (uuid)	はい	—
`items[].kind`	string	はい	次のいずれか：`capture`, `verify`, `retention`
`items[].state`	string	はい	次のいずれか：`queued`, `running`, `committing`, `completed`, `failed`, `interrupted`
`items[].phase`	string	はい	`^[a-z][a-z0-9_]{0,63}$`に一致; nullも可
`items[].startedAt`	string (date-time)	はい	実行の開始時刻。キューで待機している間はリクエスト時刻。
`items[].finishedAt`	string (date-time)	はい	nullも可
`items[].errorCode`	string	はい	`^[a-z][a-z0-9_]{0,63}$`に一致; nullも可
`items[].pointId`	string (uuid)	はい	nullも可
`items[].progress`	object	はい	—
`items[].progress.bytesCopied`	string	はい	10進数字で表した整数（文字列として送信）; 処理済みのバイト数。コピーしたもの、またはすでに保管庫にあるもの。
`items[].progress.bytesTotal`	string	はい	10進数字で表した整数（文字列として送信）
`items[].progress.blobsCopied`	integer	はい	0以上
`items[].progress.blobsTotal`	integer	はい	0以上
`next`	string	はい	`^[0-9]{1,17}_[0-9a-f-]{36}$`に一致; nullも可

レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507

例

bash

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

バックアップポイントの一覧表示

GET HEAD /api/v1/backup/points

アクセス: システム権限backup.read · 再試行: 再試行しても安全（読み取り）

現在の保管庫の完了済みの復元ポイントを、スナップショットが新しい順に列挙します。各ポイントには、スナップショット時刻T、サイズ、保管庫に追加されたバイト数、pinnedかどうか、最新の検証結果（verifiedAt、verifyDepthはstructuralまたはdeep、verifyError）が含まれます。ページにはlimit件のポイント（1〜100、既定は50）が含まれ、続きはafterにnextを設定して取得します。置き換えられた保管庫には、その保管庫自身のポイントのみが表示されます。

パラメーター

名前	場所	型	必須	ルール
`after`	クエリ	string	いいえ	`^[0-9]{1,17}_[0-9a-f-]{36}$`に一致; next of the previous page
`limit`	クエリ	integer	いいえ	1～100; 既定値：`50`

レスポンス 200

フィールド	型	必須	ルール
`items`	objectの配列	はい	100個以内の要素
`items[].id`	string (uuid)	はい	—
`items[].snapshotAt`	string (date-time)	はい	スナップショット時刻T。ポイントの経過期間はTから数えます。
`items[].completedAt`	string (date-time)	はい	—
`items[].blobs`	integer	はい	0以上
`items[].contentBytes`	string	はい	10進数字で表した整数（文字列として送信）
`items[].newBytes`	string	はい	10進数字で表した整数（文字列として送信）; このポイントが保管庫に追加したバイト数。
`items[].tables`	integer	はい	0以上
`items[].rows`	integer	はい	0以上
`items[].pinned`	boolean	はい	—
`items[].verifiedAt`	string (date-time)	はい	nullも可
`items[].verifyDepth`	string	はい	次のいずれか：`structural`, `deep`, `null`; nullも可
`items[].verifyError`	string	はい	`^[a-z][a-z0-9_]{0,63}$`に一致; nullも可
`next`	string	はい	`^[0-9]{1,17}_[0-9a-f-]{36}$`に一致; nullも可

レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507

例

bash

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

バックアップポイントの詳細検証の要求

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

アクセス: システム権限backup.manage · 再試行: 同じIdempotency-Keyを使えば再試行しても安全

ポイントidの保存済みバイトをすべて読み取る検証をキューへ登録します。応答は202とジョブで、結果はポイントのverifiedAt、verifyDepth、verifyErrorに現れます。Idempotency-Keyは必須で、別のポイントに再利用すると409 idempotency_mismatchになります。未知のポイントは404です。

パラメーター

名前	場所	型	必須	ルール
`id`	パス	string (uuid)	はい	—
`Idempotency-Key`	ヘッダー	string	はい	`^[A-Za-z0-9_.:-]{1,128}$`に一致; Repeat returns the same job; per caller and operation kind.

レスポンス 202

フィールド	型	必須	ルール
`id`	string (uuid)	はい	—
`kind`	string	はい	次のいずれか：`capture`, `verify`, `retention`
`state`	string	はい	次のいずれか：`queued`, `running`, `committing`, `completed`, `failed`, `interrupted`

レスポンス: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507

例

bash

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

バックアップポイントの固定と固定解除

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

アクセス: システム権限backup.manage · 再試行: 再試行しても安全：同じリクエストは同じ効果になる

ポイントidのpinnedを設定します。固定されたポイントは、固定を解除するまで、ポリシーを超えて保持ルールによって保持されます。同じ値を再度設定しても何も変わらず、応答は更新後のポイントです。未知のポイント、またはすでに破棄されたポイントは404です。

パラメーター

名前	場所	型	必須	ルール
`id`	パス	string (uuid)	はい	—

リクエスト本文 (application/json)

フィールド	型	必須	ルール
`pinned`	boolean	はい	—

レスポンス 200

フィールド	型	必須	ルール
`id`	string (uuid)	はい	—
`snapshotAt`	string (date-time)	はい	スナップショット時刻T。ポイントの経過期間はTから数えます。
`completedAt`	string (date-time)	はい	—
`blobs`	integer	はい	0以上
`contentBytes`	string	はい	10進数字で表した整数（文字列として送信）
`newBytes`	string	はい	10進数字で表した整数（文字列として送信）; このポイントが保管庫に追加したバイト数。
`tables`	integer	はい	0以上
`rows`	integer	はい	0以上
`pinned`	boolean	はい	—
`verifiedAt`	string (date-time)	はい	nullも可
`verifyDepth`	string	はい	次のいずれか：`structural`, `deep`, `null`; nullも可
`verifyError`	string	はい	`^[a-z][a-z0-9_]{0,63}$`に一致; nullも可

レスポンス: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

例

bash

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

バックアップの保持ルールで残るもののプレビュー

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

アクセス: システム権限backup.read · 再試行: 再試行しても安全（読み取り）

保持ポリシーでどのポイントが残るか（それぞれの理由daily、weekly、monthly、pinned、newest付き）と、現時点でどのポイントが削除されるかを示します。検証に失敗したポイントは考慮されません。プレビューは参考情報です。requestBackupRetentionは実行時に保管庫から改めて判断します。

レスポンス 200

フィールド	型	必須	ルール
`keep`	objectの配列	はい	—
`keep[].id`	string (uuid)	はい	—
`keep[].reasons`	stringの配列	はい	各要素：次のいずれか：`daily`, `weekly`, `monthly`, `pinned`, `newest`
`delete`	objectの配列	はい	—
`delete[].id`	string (uuid)	はい	—

レスポンス: 200, 400, 401, 403, 404, 409, 422, 503, 507

例

bash

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

バックアップの保持ルール適用の要求

POST /api/v1/backup/retention/apply

アクセス: システム権限backup.manage · 再試行: 同じIdempotency-Keyを使えば再試行しても安全

保持ジョブをキューへ登録します。エージェントはポリシー外のポイントを破棄し、残ったどのポイントも使っていないコンテンツを削除するため、保管庫に空き容量が戻るのはジョブが完了してからです。ジョブとともに202を返します。Idempotency-Keyは必須で、繰り返すと同じジョブが返ります。事前にpreviewBackupRetentionを確認してください。

パラメーター

名前	場所	型	必須	ルール
`Idempotency-Key`	ヘッダー	string	はい	`^[A-Za-z0-9_.:-]{1,128}$`に一致; Repeat returns the same job; per caller and operation kind.

レスポンス 202

フィールド	型	必須	ルール
`id`	string (uuid)	はい	—
`kind`	string	はい	次のいずれか：`capture`, `verify`, `retention`
`state`	string	はい	次のいずれか：`queued`, `running`, `committing`, `completed`, `failed`, `interrupted`

レスポンス: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507

例

bash

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

バックアップ ​

操作 ​

バックアップ状態の取得 ​

バックアッププランの取得 ​

バックアッププランの置換 ​

バックアップの即時実行の要求 ​

バックアップジョブの一覧表示 ​

バックアップポイントの一覧表示 ​

バックアップポイントの詳細検証の要求 ​

バックアップポイントの固定と固定解除 ​

バックアップの保持ルールで残るもののプレビュー ​

バックアップの保持ルール適用の要求 ​

バックアップ

操作

バックアップ状態の取得

バックアッププランの取得

バックアッププランの置換

バックアップの即時実行の要求

バックアップジョブの一覧表示

バックアップポイントの一覧表示

バックアップポイントの詳細検証の要求

バックアップポイントの固定と固定解除

バックアップの保持ルールで残るもののプレビュー

バックアップの保持ルール適用の要求