백업

기본 제공 백업 에이전트의 상태, 계획, 실행, 복원 지점, 검증, 보존.

이 그룹의 작업과 각 작업의 액세스 규칙, 재시도 규칙, 매개 변수, 응답입니다. 모든 요청에는 키가 포함됩니다: Authorization: Bearer <키>(“인증” 참조).

작업

백업 상태 조회

GET HEAD /api/v1/backup/status

액세스: 시스템 권한 backup.read · 재시도: 반복해도 안전함(읽기)

백업 시스템을 요약해 반환합니다. 구성 요소는 백업 보관소(configured, available, 여유 및 전체 바이트), 백업 에이전트(online, 마지막 하트비트, 버전), 계획, 가장 최근에 완료된 복원 지점, 다음 예약 실행, 실행 중인 작업, 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을 반환합니다. 변경하기 전의 계획은 비활성이며, UTC 02:00 일정과 일간 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이고, 올바르지 않은 필드는 details에 JSON Pointer를 담은 400입니다. 에이전트는 다음 확인부터 새 일정을 따릅니다.

요청 본문 (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)"

백업 ​

작업 ​

백업 상태 조회 ​

백업 계획 조회 ​

백업 계획 교체 ​

지금 백업 요청 ​

백업 작업 목록 ​

백업 지점 목록 ​

백업 지점의 심층 검사 요청 ​

백업 지점 고정 또는 고정 해제 ​

백업 보존 규칙이 유지하는 대상 미리 보기 ​

백업 보존 작업 요청 ​

백업

작업

백업 상태 조회

백업 계획 조회

백업 계획 교체

지금 백업 요청

백업 작업 목록

백업 지점 목록

백업 지점의 심층 검사 요청

백업 지점 고정 또는 고정 해제

백업 보존 규칙이 유지하는 대상 미리 보기

백업 보존 작업 요청