Backing Up and Restoring with the REST API

Overview

groov EPIC and RIO device configurations can be backed up and restored with the groov Manage REST API.

There are several REST API endpoints involved.

Backing up a device
- (Optional) Use the /manage/api/v1/maintenance/backup/prepare endpoint to encrypt and password-protect the backup file.
- Use the /manage/api/v1/maintenance/backup endpoint to generate and download a backup.
Restoring a backup file to a device
- (Optional) Use the /manage/api/v1/maintenance/restore/prepare endpoint to decrypt the password-protected backup file that’s about to be uploaded.
- Use the /manage/api/v1/maintenance/restore endpoint to upload and restore a backup file. Restoring a backup involves shutting down all services and applications, restoring projects and settings, and then restarting the device.
- (Optional) Use the /unprotected/api/v1/maintenance/restore/status endpoint to follow the progress of the restore process.

Back Up

HTTP Request Details

The URL path to get a backup file is /manage/api/v1/maintenance/backup.

To make the HTTP request, we need several pieces of information:

Hostname or IP Address of the groov EPIC or RIO device
The API key of a groov user with System-wide Administrator permissions
The list of items to back up. It can be either:
- A comma-separated list of items to back up. For example, io,network,license.
- Or just ALL_STANDARD_ITEMS to include all items normally included on the Backup page in groov Manage. This option was added in 4.1 firmware.

In the following examples, we’ll use an example hostname opto-01-02-03 for the address, and an example API key of 3KbLb7yZRxnTBP49nEmobDkrpmPkFoBo.

Using cURL

Using cURL, we’ll need to use the -J and -O flags to tell cURL to use the filename in the HTTP response headers, for example “groov-epic-backup.2025-08-21T16_14_09.zip”. Or you may use the --output flag and provide your own name.

-J, --remote-header-name Use the header-provided filename
-O, --remote-name        Write output to a file named as the remote file

The -k flag is used to ignore any SSL errors. By default, groov EPIC and RIO devices use a self-signed SSL certificate, but your computer and cURL likely have no reference to it. To make these examples easier, we just ignore the issue with the -k flag. The requests will still be encrypted, but the certificate itself will not be verified.

The API key is set with the -H flag, which adds a custom HTTP header named “apiKey” to the request.

The list of items to back up is passed in a query parameter named components.

Example 1 - Backing Up All Standard Items

The “ALL_STANDARD_ITEMS” option was added in 4.1 firmware.

Putting all of the above together results in the following cURL command:

curl -k -OJ -H apiKey:3KbLb7yZRxnTBP49nEmobDkrpmPkFoBo https://opto-01-02-03/manage/api/v1/maintenance/backup?components=ALL_STANDARD_ITEMS

If you’re using Windows PowerShell, you’ll probably need to use c:\windows\system32\curl.exe instead of just curl, which is actually an alias for `Invoke-WebRequest.

If successful, you should see output like this:

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  285k  100  285k    0     0  97402      0  0:00:03  0:00:03 --:--:-- 97446

Example 2 - Backing Up Specific Items

You can specify which items to back up by giving a comma-separated list of system items to the components query parameter.

For example, io,networking,license will back up the I/O settings, network settings, and license files.

The full list of items is in the endpoint’s API Reference.

Example cURL command:

curl -k -OJ -H apiKey:3KbLb7yZRxnTBP49nEmobDkrpmPkFoBo https://opto-01-02-03/manage/api/v1/maintenance/backup?components=io,networking,license

Example 3 - Encrypt the Backup

To encrypt and password-protect the backup file, first use an HTTP POST request to the /manage/api/v1/maintenance/backup/prepare endpoint.

It should be used immediately before the backup request.

The POST request requires a JSON data payload like this:

{
    "encryptBackup": true,
    "password": "my-secret-password",
    "confirmPassword": "my-secret-password"
}

To do that, we use the -d flag and format the object correctly for the command line. The Content-Type is set with -H "Content-Type: application/json".

Example cURL command:

curl -k  -H apiKey:3KbLb7yZRxnTBP49nEmobDkrpmPkFoBo  -H "Content-Type: application/json" --data "{\"encryptBackup\":true,\"password\":\"abc\",\"confirmPassword\":\"abc\"}" https://opto-01-02-03/manage/api/v1/maintenance/backup/prepare

Restore

HTTP Request Details

The URL path to get a backup file is /manage/api/v1/maintenance/restore.

To make the HTTP request, we need several pieces of information:

Hostname or IP Address of the groov EPIC or RIO device
The API key of a groov user with System-wide Administrator permissions
The backup file that is being restored.
The list of items to restore. It can be either:
- A comma-separated list of items to back up. For example, “io,network,license”.
- Or just “ALL_STANDARD_ITEMS” to include all items normally included on the Backup page in groov Manage. This option was added in 4.1 firmware.
If the backup was encrypted and password protected, then the password is needed too.

In the following examples, we’ll use an example hostname opto-01-02-03 for the address, and an example API key of 3KbLb7yZRxnTBP49nEmobDkrpmPkFoBo.

Using cURL

-J, --remote-header-name Use the header-provided filename
-O, --remote-name        Write output to a file named as the remote file

The -k flag is used to ignore any SSL errors. By default, groov EPIC and RIO devices use a self-signed SSL certificate, but your computer and cURL has no reference to it. To make these examples easier, we just ignore the issue with the -k flag. The requests will still be encrypted, but the certificate itself will not be verified.

The API key is set with the -H flag, which adds a custom HTTP header named “apiKey” to the request.

The backup file is specified with the -F flag. The form field is named backup. The @ symbol is used to specifiy the backup to be uploaded. For example, -F backup=@groov-epic-backup.2025-10-10T14_51:13.zip.

The -F flag also sets the Content-Type header to multipart/form-data;

Example 1 - Restoring Up All Standard Items

The “ALL_STANDARD_ITEMS” option was added in 4.1 firmware.

Putting all of the above together results in the following cURL command:

curl -k -X POST  -H apiKey:3KbLb7yZRxnTBP49nEmobDkrpmPkFoBo  -F backup=@groov-epic-backup.2025-10-10T14_51:13.zip  https://opto-01-02-03/manage/api/v1/maintenance/restore?components=ALL_STANDARD_ITEMS

If you’re using Windows PowerShell, you’ll probably need to use c:\windows\system32\curl.exe instead of just curl, which is actually an alias for Invoke-WebRequest.

Example 2 - Restoring Specific Items

You can specify which items to restore by giving a comma-separated list of system items to the components query parameter.

For example, io,networking,license will restore the I/O settings, network settings, and license files.

The full list of items is in the endpoint’s API Reference.

Example cURL command:

curl -k  -X POST  -H apiKey:3KbLb7yZRxnTBP49nEmobDkrpmPkFoBo  -F backup=@groov-epic-backup.2025-10-10T14_51:13.zip  https://opto-01-02-03/manage/api/v1/maintenance/restore?components=io,networking,license

Example 3 - Restore an Encrypted Backup

To decrypt and restore a password-protected backup file, first use an HTTP POST request to the /manage/api/v1/maintenance/restore/prepare endpoint.

It should be used immediately before the restore request.

The POST request requires a JSON data payload like this:

{
  "decryptBackup": true,
  "password": "my-secret-password"
}

To do that, we use the -d flag and format the object correctly for the command line. The Content-Type is set with -H "Content-Type: application/json".

Example cURL command:

curl -k  -H apiKey:3KbLb7yZRxnTBP49nEmobDkrpmPkFoBo  -H "Content-Type: application/json"  --data "{\"decryptBackup\":true,\"password\":\"my-secret-password\"}"  https://opto-01-02-03/manage/api/v1/maintenance/restore/prepare

Restore Status

After uploading the backup file, the /unprotected/api/v1/maintenance/restore/status endpoint to follow the progress of the restore process. endpoint can be used to follow the progress. This is useful, but not required. groov Manage will continue to restore the backup regardless of calls to this endpoint.

Example cURL command:

curl -k https://opto-04-22-f1/manage/unprotected/api/v1/maintenance/restore/status

Here’s an example JSON response:

{
  "upload"          : { "status": "done" },
  "decrypt"         : { "status": "done" },
  "decompress"      : { "status": "done" },
  "deviceModelCheck": { "status": "done" },
  "versionCheck"    : { "status": "done" },
  "upgrade"         : { "status": "done" },
  "validation"      : { "status": "done" },
  "stopServices"    : { "status": "running", "stepCurrent": 3, "stepsRequired": 7 },
  "restore"         : { "status": "pending" },
  "finishAndRestart": { "status": "pending" },
  "active"          : true,
  "failedItems"     : []
}