S3 Replication, Backup and Recovery via REST API
Start with REST API – Getting Started and Automation for authentication and client setup. API usage is at your own responsibility and is not covered by support.
Use the administrative REST API to configure eEKAS-to-eEKAS synchronization, external S3 mirrors, backup and recovery. Requests require an API key; mutating object-storage requests require admin or s3-admin. These endpoints are not a customer self-service portal.
Requests and job handling
Use HTTPS and the X-API-Key header. Send credentials, passphrases, invitation bundles and encoded credentials in an application/json body. Base64 values are not encrypted. URL secrets are rejected. Use an Idempotency-Key to replay identical mutating requests safely. A 202 response contains an API job ID and status URL; poll GET /api/v1/jobs?job_id=... until complete or failed. Cancellation uses DELETE /api/v1/jobs?job_id=....
An API job ID differs from a restore-worker job ID. Setup and recovery-bundle export/import run as API jobs. Restore previews return a restore-worker job ID; use backup status and backup control for that job. Configuration apply queues an API job which submits configuration recovery to the restore worker; then monitor backup status.
eEKAS-to-eEKAS sync
GET /api/v1/object-storage/replication lists relationships. Add relationship_id for status. Views are invitations, audit, buckets, backfill and destinations. Bucket metrics accept marker, query and limit (1–50); follow the backend continuation marker rather than loading every bucket into a browser. The destinations view discovers local service instances.
POST /api/v1/object-storage/replication accepts the following actions and their OpenAPI parameters: enable; pause/resume; set_mode; set_policy; set_advanced_policy; refresh_topology; promote; dr_test; recover_gateway; remove_site; decommission_local; credential rotation/adoption/activation/finalization; backfill start/pause/resume/cancel; recovery_validate; compliance_report; orchestrate_recovery; run_archive; revoke_invitation; purge_invitations. Selected native buckets and backfill buckets accept JSON arrays or semicolon-separated strings. Existing fencing, conflict acknowledgements and deletion confirmations are enforced by the backend.
{"action":"set_policy","relationship_id":"RELATIONSHIP_ID","bucket_scope":"all","rpo_seconds":300,"allow_untrusted":false}
Invitation endpoints are /replication/invitations and /replication/invitations/redeem. Joining uses POST /replication/join; validate_only:true performs preflight. Supply a public ca_pem certificate, a server-local ca_file, or an explicitly chosen allow_untrusted exception. Uploaded certificates are validated and held in private temporary files until the request finishes. Invitation and passphrase values preserve commas and Unicode.
Sync and backup to other S3 instances
A scheduled external mirror is configured by set_advanced_policy using config_b64 and started by run_archive. This workflow follows the mirror/deletion policy. A generation-preserving backup has its own catalogue, checkpoints and recovery bundle; use the backup endpoints below when independent disaster recovery is required. Direct mode reads completed object generations from the source. History mode uses an intermediate archive zone to retain generations. Direct mode cannot retrieve a generation overwritten or deleted before capture.
All backup operations are exposed at /api/v1/object-storage/replication/backups. POST bodies contain action and a structured request. The worker retains the same validation and protection rules as the GUI. Successful synchronous responses contain status and data.
| Action | Request / behaviour |
|---|---|
| backup_discover | {}; discovers local realms, zones and worker hosts. |
| backup_bucket_search | realm, source_zone, query, cursor, limit. Maximum 100 results per page; follow next_cursor. An index may initially report building. |
| backup_list | {}; returns saved configurations with credentials removed. |
| backup_save | id; new configurations also require mode, realm, zonegroup, source_zone, host, source_endpoint, endpoint, bucket and destination access_key/secret_key. Whole-zone scope uses bucket_scope=zone and includes future buckets. Individual scope uses bucket_scope=selected and a buckets array. History mode additionally needs archive_zone, archive_endpoint, gateway_certificate and gateway_private_key. Editing retains omitted settings and secrets; changing storage identity requires a new ID. |
| backup_setup | id. Queued API job; applies settings on the selected worker host and starts the worker. |
| backup_status | id. Includes worker activity, progress, scans, jobs, checkpoint, event queue and protection-check state. |
| backup_checkpoints | id and optional continuation_token. Returns bounded items, display_name (UTC date plus original ID in brackets), and another continuation_token when present. |
| backup_preview | id, checkpoint, target_endpoint, target_access_key/target_secret_key. Optional source_bucket, object_key, prefix or object_id narrows selection. target_prefix defaults to recovery-. target_bucket requires a source_bucket. Returns a worker job_id; wait for preview_ready and review the preview. |
| backup_control | id and control. Without job_id: pause/resume backup. With job_id: start/pause/resume/cancel recovery. Starting recovery requires confirm=job_id after review. |
| backup_bundle_export | id, bundle_password (at least 16 characters). Queued API job. Download the encrypted result from /replication/backups/bundle?job_id=API_JOB_ID after completion. |
| backup_bundle_import | id, bundle_b64, bundle_password. Queued API job. Use an unused archive ID on a replacement node; imports a recovery-only configuration. |
| backup_configuration_preview | id, job_id. Reviews owner and bucket configuration recovery from the imported bundle. |
| backup_configuration_apply | id, job_id, confirm=job_id, target_realm, target_zone. Queued API job; monitor the restore worker for configuration_complete. |
Optional backup settings include concurrency (1–8), interval (10–3600 seconds), catalog_interval (minimum 60 seconds, default 3600), staging_limit, recall_timeout, scale_enabled, protection_concurrency and lock_check_interval. source_ca_pem supplies the source CA; destination_ca_pem supplies a private destination CA without disabling certificate verification. target_ca_pem supplies a recovery-destination CA. Passphrases and all private keys stay in JSON bodies.
{
"action": "backup_save",
"request": {
"id": "offsite-backup", "mode": "direct",
"realm": "REALM", "zonegroup": "ZONEGROUP", "source_zone": "SOURCE_ZONE",
"host": "WORKER_HOST", "source_endpoint": "https://source.example:8443",
"endpoint": "https://backup.example", "bucket": "archive-target",
"access_key": "DESTINATION_ACCESS_KEY", "secret_key": "DESTINATION_SECRET_KEY",
"bucket_scope": "zone", "catalog_interval": 3600, "scale_enabled": true
}
}
The worker host is the server running transfer, catalogue and recovery jobs. Send configuration/start requests to that host. The backups route accepts a bounded 24 MiB JSON body, enough for the worker's 16 MiB encrypted recovery-bundle limit after base64 encoding. Ordinary routes retain the configured body limit, normally 1 MiB. Bundle export uses background work and a separate download endpoint, so job output truncation cannot corrupt the downloaded bundle.
WORM sources remain protected. A WORM or unclassified backup cannot overwrite an existing recovery bucket; verified protection metadata is required and protected content uses new recovery buckets. Recovery retains active retention and legal holds according to backend checks. Configuration recovery needs a separate reviewed confirmation, and automatic lifecycle expiration stays disabled. External target tape completion remains unknown to eEKAS.
Operational prerequisites and reference
Follow S3 replication and recovery for destination preparation, fencing and verification. Consult the complete API reference and your installation’s OpenAPI specification for action-specific required fields.