बैकअप

अंतर्निहित बैकअप एजेंट की स्थिति, योजना, रन, बिंदु, सत्यापन और प्रतिधारण।

इस समूह के ऑपरेशन, उनके एक्सेस नियम, पुनः प्रयास नियम, पैरामीटर और जवाबों के साथ। हर अनुरोध में एक कुंजी होती है: Authorization: Bearer <कुंजी> (“प्रमाणीकरण” देखें)।

ऑपरेशन

बैकअप की स्थिति प्राप्त करें

GET HEAD /api/v1/backup/status

एक्सेस: सिस्टम अनुमति backup.read · पुनः प्रयास: दोहराना सुरक्षित है (पढ़ना)

बैकअप प्रणाली का सारांश देता है: बैकअप स्टोरेज (vault) (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	हाँ	दशमलव अंकों में पूर्णांक, स्ट्रिंग के रूप में भेजा जाता है; null हो सकता है
vault.totalBytes	string	हाँ	दशमलव अंकों में पूर्णांक, स्ट्रिंग के रूप में भेजा जाता है; 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	हाँ	दशमलव अंकों में पूर्णांक, स्ट्रिंग के रूप में भेजा जाता है
lastCompleted.newBytes	string	हाँ	दशमलव अंकों में पूर्णांक, स्ट्रिंग के रूप में भेजा जाता है; इस बिंदु ने बैकअप स्टोरेज (vault) में जितने बाइट जोड़े।
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	हाँ	दशमलव अंकों में पूर्णांक, स्ट्रिंग के रूप में भेजा जाता है; संसाधित बाइट: कॉपी किए गए या पहले से बैकअप स्टोरेज (vault) में मौजूद।
running.progress.bytesTotal	string	हाँ	दशमलव अंकों में पूर्णांक, स्ट्रिंग के रूप में भेजा जाता है
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

उदाहरण

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 बिंदु) उस revision के साथ लौटाता है जिसे updateBackupPlan को वापस भेजना है। बदले जाने तक योजना अक्षम रहती है, शेड्यूल 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

उदाहरण

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

उदाहरण

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

उदाहरण

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	हाँ	दशमलव अंकों में पूर्णांक, स्ट्रिंग के रूप में भेजा जाता है; संसाधित बाइट: कॉपी किए गए या पहले से बैकअप स्टोरेज (vault) में मौजूद।
items[].progress.bytesTotal	string	हाँ	दशमलव अंकों में पूर्णांक, स्ट्रिंग के रूप में भेजा जाता है
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

उदाहरण

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

बैकअप बिंदु सूचीबद्ध करें

GET HEAD /api/v1/backup/points

एक्सेस: सिस्टम अनुमति backup.read · पुनः प्रयास: दोहराना सुरक्षित है (पढ़ना)

वर्तमान बैकअप स्टोरेज (vault) के पूर्ण पुनर्स्थापना बिंदु, सबसे नया स्नैपशॉट पहले, सूचीबद्ध करता है; प्रत्येक के साथ स्नैपशॉट समय 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	हाँ	दशमलव अंकों में पूर्णांक, स्ट्रिंग के रूप में भेजा जाता है
items[].newBytes	string	हाँ	दशमलव अंकों में पूर्णांक, स्ट्रिंग के रूप में भेजा जाता है; इस बिंदु ने बैकअप स्टोरेज (vault) में जितने बाइट जोड़े।
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

उदाहरण

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

उदाहरण

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	हाँ	दशमलव अंकों में पूर्णांक, स्ट्रिंग के रूप में भेजा जाता है
newBytes	string	हाँ	दशमलव अंकों में पूर्णांक, स्ट्रिंग के रूप में भेजा जाता है; इस बिंदु ने बैकअप स्टोरेज (vault) में जितने बाइट जोड़े।
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

उदाहरण

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

उदाहरण

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

उदाहरण

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