--- title: "Aerospike Backup Service REST API usage examples" description: "Aerospike Backup Service (ABS) REST API request and response examples for backups, restores, and configurations." --- # Aerospike Backup Service REST API usage examples > For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt) > > All documentation pages available in markdown. This page provides request and response examples for developers, scripts, and API clients automating Aerospike Backup Service (ABS) over HTTP and HTTPS. For end-to-end administrative procedures and best practices, see the operator guides: [Back up data](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/backup) and [Restore data](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/restore). Full request and response schemas are in the [REST API specification](https://aerospike.github.io/aerospike-backup-service). The examples use `BASE_URL` for the ABS listen address, for example `http://localhost:8080` or `https://localhost:8443`. The REST API does not authenticate requests; restrict network access to the service or place an authenticating proxy in front. See [Secure ABS](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/secure). For HTTPS with a private CA: Terminal window ```shell curl -s --cacert /etc/ssl/certs/abs-ca.pem https://localhost:8443/health ``` ## Trigger and manage backups Use backup endpoints to trigger scheduled or on-demand backup operations for your routines, monitor running backups, and cancel jobs if needed. Routines themselves are defined in your [configuration file](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/configure). ### Trigger an on-demand full backup For API specifications and parameter details, see the [triggerFullBackup API reference](https://aerospike.github.io/aerospike-backup-service/#/Backup/triggerFullBackup). Starts a full backup for the specified routine, ignoring any configured schedule. Request: - `ROUTINE_NAME`: Backup routine name. - `delay` (optional): Delay in milliseconds before the backup starts. ```http POST BASE_URL/v1/backups/full/ROUTINE_NAME?delay=DELAY_MS ``` Response: - `202 Accepted` ### Trigger an on-demand incremental backup For API specifications and parameter details, see the [triggerIncrementalBackup API reference](https://aerospike.github.io/aerospike-backup-service/#/Backup/triggerIncrementalBackup). Starts an incremental backup for the specified routine, ignoring any configured schedule. The routine determines which namespace and optional set filters are backed up. Request: - `ROUTINE_NAME`: Backup routine name. - `delay` (optional): Delay in milliseconds before the backup starts. ```http POST BASE_URL/v1/backups/incremental/ROUTINE_NAME ``` Example with 1000 ms delay: ```http POST BASE_URL/v1/backups/incremental/ROUTINE_NAME?delay=1000 ``` Response: - `202 Accepted` ### Trigger a backup routine (deprecated) For API specifications and parameter details, see the [scheduleFullBackup API reference](https://aerospike.github.io/aerospike-backup-service/#/Backup/scheduleFullBackup). `POST /v1/backups/schedule/ROUTINE_NAME` is deprecated, but still supported for backward compatibility. It triggers a full backup and accepts the same optional `delay` query parameter. ### Cancel all jobs for a backup routine For API specifications and parameter details, see the [cancelCurrentBackup API reference](https://aerospike.github.io/aerospike-backup-service/#/Backup/cancelCurrentBackup). Cancels any running full and incremental backups for the specified routine and deletes any partially created backups. Request: - `ROUTINE_NAME`: Backup routine name. ```http POST BASE_URL/v1/backups/cancel/ROUTINE_NAME ``` Response: - `202 Accepted` ### Get information about a running backup For API specifications and parameter details, see the [getCurrentBackup API reference](https://aerospike.github.io/aerospike-backup-service/#/Backup/getCurrentBackup). Shows information about running backups for a specific backup routine, including number of records completed, start time, progress toward completion, and estimated end time. Request: - `ROUTINE_NAME`: Backup routine name. ```http GET BASE_URL/v1/backups/currentBackup/ROUTINE_NAME ``` Response: Example The following example response shows two backups in progress, one full and one incremental. ```json { "full": { "total-records": 100000, "done-records": 50000, "start-time": "2024-01-01T12:00:00Z", "percentage-done": 50, "estimated-end-time": "2024-01-01T13:00:00Z", "metrics": { "records-per-second": 1000, "kilobytes-per-second": 30000, "pipeline": 0 } }, "incremental": { "total-records": 20000, "done-records": 15000, "start-time": "2024-01-01T12:30:00Z", "percentage-done": 75, "estimated-end-time": "2024-01-01T12:40:00Z", "metrics": { "records-per-second": 1000, "kilobytes-per-second": 30000, "pipeline": 0 } } } ``` ### Retrieve full backup list For API specifications and parameter details, see the [getFullBackups API reference](https://aerospike.github.io/aerospike-backup-service/#/Backup/getFullBackups). Lists backups for each configured routine, including details such as creation time, namespace, and storage location. Request: - `from` (optional): Lower bound timestamp filter in milliseconds since epoch. - `to` (optional): Upper bound timestamp filter in milliseconds since epoch. ```http GET BASE_URL/v1/backups/full ``` Response: Example ```json { "routine1": [ { "created": "2024-01-01T12:00:00Z", "timestamp": 1704110400000, "finished": "2024-01-01T12:05:00Z", "duration": 300, "from": "0001-01-01T00:00:00Z", "namespace": "source-ns1", "record-count": 42, "byte-count": 480000, "file-count": 1, "secondary-index-count": 5, "udf-count": 1, "key": "routine1/backup/1704110400000/source-ns1", "storage": { "s3-storage": { "bucket": "as-backup-bucket", "path": "backups", "s3-region": "eu-central-1" } }, "compression": "ZSTD", "encryption": "NONE" } ] } ``` ::: note This endpoint lists only the backups that reside in the storage location configured for the routine at the moment you call the API. It cannot access historical backups in different storage locations. If you have changed the `storage` field in a routine and there has not yet been a full backup in the new storage location, the response can appear empty. To inspect historical backups, temporarily modify the routine back to its previous storage location or browse the old bucket directly. See [Change backup storage destination](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/change-storage) for more information. ::: ## Run and track restores Use restore endpoints to recover data from a backup. You can restore from a specific backup path or from a point in time, which automatically combines the most recent full backup with any subsequent incremental backups. Restores run asynchronously and return a job ID that you can use to track progress. ### Direct restore using a specific backup For API specifications and parameter details, see the [restoreFull API reference](https://aerospike.github.io/aerospike-backup-service/#/Restore/restoreFull). The `destination` field in the request body defines the cluster to restore data to, with its seed nodes and credentials. It can describe any Aerospike Database cluster. To restore to a cluster that is already in the ABS configuration, set `destination-name` to that cluster’s name instead. [Get cluster configuration](#get-cluster-configuration) lists the configured names. `destination` and `destination-name` are mutually exclusive. This request restores a backup from a specified path to a designated destination. The `no-generation` parameter allows overwriting of existing keys if set to `true`. The `source` section matches the `storage` field of a backup returned from [Retrieve full backup list](#retrieve-full-backup-list). Copy the `key` field from the backup into the `backup-data-path` field. That path is relative to the storage `path` and must be clean (no `..`). Request: ```http POST BASE_URL/v1/restore/full ``` Request body: ```json { "destination": { "seed-nodes": [ { "host-name": "localhost", "port": 3000 } ], "credentials": { "user": "user", "password": "password" } }, "policy": { "no-generation": true, "unique": false }, "source": { "s3-storage": { "bucket": "as-backup-bucket", "path": "backups", "s3-region": "eu-central-1" } }, "backup-data-path": "routine1/backup/1704110400000/source-ns1" } ``` The response is a job ID. You can get the status of this job with the endpoint [`GET BASE_URL/v1/restore/status/:JOB_ID`](https://aerospike.github.io/aerospike-backup-service/#/Restore/restoreStatus). ```json 123456789 ``` ### Restore using routine name and timestamp For API specifications and parameter details, see the [restoreTimestamp API reference](https://aerospike.github.io/aerospike-backup-service/#/Restore/restoreTimestamp). Restores the most recent full backup before the given timestamp and then applies incremental backups up to that timestamp. If the backup policy uses `incr-mode: cumulative`, ABS restores the last full backup plus the latest covering incremental and skips intermediate incrementals in that cycle. `time` is epoch milliseconds (an absolute instant). `schedule-timezone` does not change how it is interpreted. In ABS 3.6.0 and later, you can override storage, destination, and Secret Agent settings in the request body. If an override is omitted, ABS falls back to the matching field from the local routine configuration. #### Required fields - `routine`: Backup routine name. ABS uses this name to locate the backup chain in storage, even when the routine is not configured locally. - `time`: Target epoch timestamp in milliseconds. ABS restores the closest backup state before this time. #### Optional override fields - **Storage**: `source` or `source-name`. Mutually exclusive. - **Destination**: `destination` or `destination-name`. Mutually exclusive. - **Secret Agent**: `secret-agent` or `secret-agent-name` at the top level for backup decryption. Destination credentials can use an inline `secret-agent` block to fetch database passwords from the Secret Agent. - **Password references**: Use the format `secrets:RESOURCE_LABEL:KEY`, where `RESOURCE_LABEL` is an arbitrary label you define when storing secrets in the agent. - **Policy**: `policy` for restore policy overrides. - **Incremental order**: `disable-reordering` set to `true` disables reverse-order optimization for incremental backups. When both storage and destination are provided, the routine does not need to exist in the ABS configuration file. If you override only one side, the routine must exist locally so ABS can resolve the other value. Request: ```http POST BASE_URL/v1/restore/timestamp ``` Standard restore with a locally configured routine: ```json { "routine": "daily-backup", "time": 1739538000000 } ``` Partial override. Read from the routine’s storage, but restore to a different cluster: ```json { "routine": "daily-backup", "time": 1739538000000, "destination-name": "staging-cluster" } ``` Cross-region restore. The DR ABS instance does not define `daily-backup` locally, but both storage and destination are provided: ```json { "routine": "daily-backup", "time": 1739538000000, "source": { "s3-storage": { "bucket": "dr-backup-bucket-us-west", "path": "backups", "s3-region": "us-west-2" } }, "destination-name": "local-dr-cluster" } ``` Cross-region restore with Secret Agents. The top-level `secret-agent-name` decrypts backup files. The inline `secret-agent` under `credentials` fetches the destination database password: ```json { "routine": "cross-region-routine", "time": 1739538000000, "source": { "s3-storage": { "bucket": "dr-backup-bucket-us-west", "path": "backups", "s3-region": "us-west-2" } }, "secret-agent-name": "my-local-decryption-agent", "destination": { "seed-nodes": [ { "host-name": "10.0.0.5", "port": 3000 } ], "credentials": { "user": "admin", "password": "secrets:cluster-creds:password", "secret-agent": { "address": "127.0.0.1", "port": 3005, "connection-type": "TCP" } } } } ``` The response is a job ID. You can get job status with the endpoint [`GET BASE_URL/v1/restore/status/:JOB_ID`](https://aerospike.github.io/aerospike-backup-service/#/Restore/restoreStatus). ```json 123456789 ``` Restore only missing records (`policy.unique`). Do not combine `unique` with `replace` or `no-generation`: ```json { "routine": "daily-backup", "time": 1739538000000, "policy": { "unique": true } } ``` ### Show all restore jobs For API specifications and parameter details, see the [retrieveRestoreJobs API reference](https://aerospike.github.io/aerospike-backup-service/#/Restore/retrieveRestoreJobs). Lists all restore jobs, with optional filtering by time range and status. In ABS 3.6.0 and later, restore job responses use the lowercase status values `running`, `success`, `failure`, and `canceled`. Request: ```http GET BASE_URL/v1/restore/jobs?from=FROM&to=TO&status=STATUS ``` - `from`: Lower bound timestamp filter in milliseconds since epoch. - `to`: Upper bound timestamp filter in milliseconds since epoch. - `status`: Comma-separated status filter. - Canonical statuses are `running`, `success`, `failure`, and `canceled`. - Matching is case-insensitive. The legacy aliases `done` and `failed` map to `success` and `failure`. - Use the `!` prefix to exclude one or more statuses, such as `!failure,canceled`. Response: Example ```json { "12345678": { "read-records": 100000, "total-bytes": 30000000, "expired-records": 0, "skipped-records": 0, "ignored-records": 0, "inserted-records": 50000, "existed-records": 0, "fresher-records": 0, "index-count": 4, "udf-count": 1, "errors-in-doubt": 0, "current-job": { "total-records": 100000, "done-records": 50000, "start-time": "2024-01-01T12:00:00Z", "percentage-done": 50, "estimated-end-time": "2024-01-01T13:00:00Z", "metrics": { "records-per-second": 1000, "kilobytes-per-second": 30000, "pipeline": 0 } }, "status": "running" } } ``` ### Cancel a restore job For API specifications and parameter details, see the [cancelRestore API reference](https://aerospike.github.io/aerospike-backup-service/#/Restore/cancelRestore). Cancels the restore job identified by `JOB_ID`. Data that has already been written to the destination cluster remains intact. Request: - `JOB_ID`: Numeric restore job ID. ```http POST BASE_URL/v1/restore/cancel/JOB_ID ``` Response: - `202 Accepted` ## Read and update configuration Verify settings or debug configuration issues with the following endpoints. They retrieve the service’s current configuration, including cluster definitions, backup routines, and storage destinations. Literal secret fields in GET responses are replaced with `"[secret]"`. Secret Agent references (`secrets:...`) are returned as-is. When you PUT a document you got from GET, leave unchanged secrets as `"[secret]"` so ABS keeps the stored value. Do not send `"[secret]"` on a newly created entity. ### Apply configuration Reloads the configuration from disk after you edit the YAML file. `PUT` and `POST` requests under `/v1/config/...` already persist and apply, so they do not need a follow-up apply call. Running jobs keep the configuration they started with. New jobs and future cron triggers use the applied configuration. When a routine’s schedule changes, ABS reschedules its Quartz jobs and resynchronizes backup history from storage. See [ABS architecture](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/architecture#configuration-sources-and-reload). Request: ```http POST BASE_URL/v1/config/apply ``` Terminal window ```shell curl -X POST BASE_URL/v1/config/apply ``` Response: - `200 OK` See [Configure ABS](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/configure#how-to-apply-configuration). ### Get cluster configuration For API specifications and parameter details, see the [readAllClusters API reference](https://aerospike.github.io/aerospike-backup-service/#/Configuration/readAllClusters). Returns the configuration files of existing clusters, including the default cluster setup with seed nodes and credentials. Request: ```http GET BASE_URL/v1/config/clusters ``` Response: Example ```json { "absDefaultCluster": { "seed-nodes": [ { "host-name": "host.docker.internal", "port": 3000 } ], "credentials": { "user": "tester", "password": "[secret]" } } } ``` To keep the stored password while changing another field, PUT the same document with `"[secret]"` still in `password`. To rotate the password, send the new literal or a `secrets:` reference instead of the sentinel. ### Get routine configuration For API specifications and parameter details, see the [readRoutines API reference](https://aerospike.github.io/aerospike-backup-service/#/Configuration/readRoutines). Retrieves all configured backup routines. Request: ```http GET BASE_URL/v1/config/routines ``` Response: Example ```json { "routine1": { "backup-policy": "defaultPolicy", "source-cluster": "absDefaultCluster", "storage": "local", "interval-cron": "@yearly", "namespaces": ["source-ns7"] }, "routine2": { "backup-policy": "defaultPolicy", "source-cluster": "absDefaultCluster", "storage": "local", "interval-cron": "@yearly", "namespaces": ["source-ns8"], "set-list": ["backupSet"], "bin-list": ["backupBin"] } } ``` ### Get storage configuration For API specifications and parameter details, see the [readAllStorage API reference](https://aerospike.github.io/aerospike-backup-service/#/Configuration/readAllStorage). Returns all the configured storage endpoints, including cloud storage endpoint information such as region and path, if applicable. Request: ```http GET BASE_URL/v1/config/storage ``` Response: Example ```json { "local": { "local-storage": { "path": "localStorage" } }, "minio": { "s3-storage": { "path": "storage1", "bucket": "as-backup-bucket", "s3-region": "eu-central-1", "s3-profile": "minio", "s3-endpoint-override": "http://host.docker.internal:9000" } } } ``` ## Check service health and version Retrieve operational information about the service with the following system endpoints. Use these to perform health probes, check versions, and integrate with monitoring tools like Prometheus. See [Monitoring](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/monitoring) for details on available metrics. These endpoints are at the root path, not under `/v1`. ### Health Returns HTTP 200 and `Ok` if the process is up. It does not verify storage or the Database cluster. ```http GET BASE_URL/health ``` Terminal window ```shell curl -s BASE_URL/health ``` ### Ready Returns HTTP 200 if the process can handle requests. It does not verify storage or the Database cluster. ```http GET BASE_URL/ready ``` Terminal window ```shell curl -s BASE_URL/ready ``` ### Get service version For API specifications and parameter details, see the [version API reference](https://aerospike.github.io/aerospike-backup-service/#/System/version). Returns version information about the running Aerospike Backup Service instance. Request: ```http GET BASE_URL/version ``` ::: note The endpoint is at the root path, not under `/v1`. ::: Response: Example ```json { "version": "3.7.0", "build-time": "BUILD_TIMESTAMP", "commit": "COMMIT_SHA" } ```