How To

To perform complex operations using the Veeam Backup for AWS REST API, refer to this section for specific usage scenarios describing the sequence of HTTP requests that must be sent to achieve a particular result.

Performing EC2 File-Level Recovery

Veeam Backup for AWS provides a set of requests that allow you to recover corrupted or missing files of an EC2 instance to their original location from a cloud-native snapshot or image-level backup.

IMPORTANT

Veeam Backup for AWS does not support downloading files to a local machine using the REST API.
Before you start file-level recovery, consider the limitations and prerequisites described in the Veeam Backup for AWS User Guide, section Before You Begin.

To recover files and folders of a protected EC2 instance, use the following requests:

To start an FLR session, send the HTTP POST request to the /virtualMachines/restorePoints/{vmRestorePointId}/restoreFile endpoint:
1. In the vmRestorePointId path parameter, specify a system ID assigned to a restore point to which you want to restore of files and folders of the EC2 instance.
2. In the request body, specify a reason for the restore operation and the incoming write bandwidth value for Kinesis Data Stream.
```
Request:
POST https://127.0.0.1:11005/api/v1/virtualMachines/restorePoints/{vmRestorePointId}/restoreFile

Request Header:
x-api-version:1.7-rev0

Request Parameters:
vmRestorePointId=7987aa56-a6fe-432b-a513-6af976a6e6

Request Body:
{
    "reason": "restore corrupted items",
    "countShards": 0
}
```
A successfully completed operation returns the 202 response code. In the response body, Veeam Backup for AWS returns the ID assigned to the FLR session that must be saved locally.
To retrieve the result of the FLR session, send the HTTP GET request to the /api/v1/sessions/{sessionId}/flr endpoint and specify a system ID assigned to the FLR session in the sessionId path parameter. Then, verify whether the FLR session is in a Ready state.
To browse files and folders by a specific directory, send the HTTP POST request to the /api/v1/flr/{flrSessionId}/browse endpoint:
1. In the flrSessionId path parameter, specify a system ID assigned to the FLR session whose items you want to browse.
2. In the Offset query parameter, specify the number that must be excluded from a response the first N items of a resource collection. The default value is 0.
3. In the Limit query parameter, specify the maximum number of items of a resource collection that must be returned in a response. The default value is 200.
4. In the request body, specify a path with the necessary directory on the EC2 instance whose items will be returned in the response.
```
Request:
POST https://127.0.0.1:11005/api/v1/flr/{flrSessionId}/browse

Request Header:
x-api-version:1.7-rev0

Request Parameters:
flrSessionId=7857aa56-a6fe-432b-a513-6afc6516a6e6
Limit=10
Offset=2

Request Body:
{
    "path": "/accountingdata"
}
```
A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for AWS returns the detailed information on each item.
```
Response:
200
Response Body:
{
"results": [
    {
        "type": "File",
        "itemPath": "/accountingdata",
        "name": "report_1.txt",
        "modifiedDate": "2024-09-30T08:24:35.742Z",
        "size": 8
    }
],
"count": 1
}
```
To start searching through files and folders by a specific directory and name, send the HTTP POST request to the /api/v1/flr/{flrSessionId}/search/start endpoint:
1. In the flrSessionId path parameter, specify a system ID assigned to the FLR session in which you want to start searching for items.
2. In the Limit path parameter, specify the number of results that must be returned in the response.
3. In the searchPattern query parameter, specify a name of the file or part of the name that will be used as a search template.
4. In the traverse query parameter, specify whether you want the search to be performed through all subdirectories and nested elements.
5. In the request body, specify a path with the necessary directory on the EC2 instance where the items you want to search are located.
```
Request:
POST https://127.0.0.1:11005/api/v1/flr/{flrSessionId}/search/start

Request Header:
x-api-version:1.7-rev0

Request Parameters:
flrSessionId=7857aa56-a6fe-432b-a513-6afc6516a6e6
Limit=10
searchPattern=report_1
traverse=true

Request Body:
{
    "path": "/accountingdata"
}
```
A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for AWS returns the ID assigned to the search task that must be saved locally.
```
Response:
200

Response Body:
{
    "searchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

To retrieve the results of the search task, send the HTTP GET request to the /api/v1/flr/{flrSessionId}/search/{searchTaskId}/results endpoint:

In the flrSessionId path parameter, specify a system ID assigned to the FLR session in which the search for items was performed.
In the searchTaskId path parameter, specify the ID assigned to the search task in the response received as a result of the request performed at step 4.

Request:
GET https://127.0.0.1:11005/api/v1/flr/{flrSessionId}/search/{searchTaskId}/results

Request Header:
x-api-version:1.7-rev0

Request Parameters:
flrSessionId=7857aa56-a6fe-432b-a513-6afc6516a6e6
searchTaskId=3fa85f64-5717-4562-b3fc-2c963f66afa6

A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for AWS returns the state of the search task, the number of found items and information on each item.

Response:
200

Response Body:
{
    "searchState": "Ready",
    "count": 3,
    "results": [
        {
            "type": "File",
            "itemPath": "/accountingdata",
            "name": "report_1.txt",
            "modifiedDate": "2024-06-07T07:22:50",
            "size": 7
        },
        {
            "type": "File",
            "itemPath": "/accountingdata",
            "name": "report_10.txt",
            "modifiedDate": "2024-06-07T07:22:50",
            "size": 10
        },
        {
            "type": "File",
            "itemPath": "/accountingdata",
            "name": "report_11.txt",
            "modifiedDate": "2024-06-07T07:22:50",
            "size": 8
        }
    ]
}

If the number of results exceeds the limit set in the initial search query, continue the search. To do that, send the HTTP POST request to the /api/v1/flr/{flrSessionId}/search/{searchTaskId}/nextPage endpoint:
1. In the flrSessionId path parameter, specify a system ID assigned to the FLR session in which the search for items was performed.
2. In the searchTaskId path parameter, specify the ID assigned to the search task in the response received as a result of the request performed at step 4.
```
Request:
POST https://127.0.0.1:11005/api/v1/flr/{flrSessionId}/search/{searchTaskId}/nextPage

Request Header:
x-api-version:1.7-rev0

Request Parameters:
flrSessionId=7857aa56-a6fe-432b-a513-6afc6516a6e6
searchTaskId=3fa85f64-5717-4562-b3fc-2c963f66afa6
```
A successfully completed operation returns the 202 response code.

NOTE

To retrieve the results of the continued search, send the HTTP GET request to the /api/v1/flr/{flrSessionId}/search/{searchTaskId}/results endpoint, as described at step 5. Note that the results obtained in the previous query will be lost.

To stop the search task, send the HTTP POST request to the /api/v1/flr/{flrSessionId}/search/{searchTaskId}/stop endpoint:

In the flrSessionId path parameter, specify a system ID assigned to the FLR session in which the items were searched.
In the searchTaskId path parameter, specify the ID assigned to the search task from the response that was received as a result of the request made at step 4.

Request:
POST https://127.0.0.1:11005/api/v1/flr/{flrSessionId}/search/{searchTaskId}/stop
Request Header:
x-api-version:1.7-rev0

Request Parameters:
flrSessionId=7857aa56-a6fe-432b-a513-6afc6516a6e6
searchTaskId=3fa85f64-5717-4562-b3fc-2c963f66afa6

A successfully completed operation returns the 202 response code.

Response:
202

Response Body:
{
    "sessionId": "7857aa56-a6fe-432b-a513-6afc6516a6e6",
    "_links": [
        {
            "method": "GET",
            "rel": "self",
            "href": "https://127.0.0.1:11005/api/v1/sessions/7857aa56-a6fe-432b-a513-6afc6516a6e6"
        }
    ]
}

To restore specific files and folders, send the HTTP POST request to the /api/v1/flr/{flrSessionId}/restore endpoint:
1. In the flrSessionId path parameter, specify a system ID assigned to the FLR session from which you want to restore items.
2. In the request body, specify a path to the items you want to restore, and choose whether you want to download a copy of items or restore the original items:
  - To download the selected files and folders to the source EC2 instance, enter Keep. The files will be saved with the restored- prefix to the same directory where the source files are located.
  - To restore the selected files and folders to the source EC2 instance, enter Overwrite.
IMPORTANT

If the original EBS volume attached to the EC2 instance no longer exists, the completed operation will return the 500 response code. In this case, you must specify an alternative path to the directory on the EC2 instance to restore the items.
```
Request:
POST https://127.0.0.1:11005/api/v1/flr/{flrSessionId}/restore
Request Header:
x-api-version:1.7-rev0

Request Parameters:
flrSessionId=7857aa56-a6fe-432b-a513-6afc6516a6e6
Request Body:
{
"itemPaths": [
    "/accountingdata/report_1.txt", 
    "/var/log/journal/ec2376b1a5b5e8e7064ad8b0edc1ad42/system.journal", 
    "/billingdata/report_15.txt", 
    "/auditdata/report_25.txt"
],
"restoreType": "Keep"
}
```
A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for AWS returns the ID assigned to the restore task that must be saved locally.
```
Response:
200

Response Body:
{
    "restoreTaskId": "2044e84c-768a-47ce-8bf8-69aaa6f8540d"
}
```
To retrieve the results of the restore task, send the HTTP GET request to the /api/v1/flr/{flrSessionId}/restore/{restoreTaskId}/status endpoint:
1. In the flrSessionId path parameter, specify a system ID assigned to the FLR session from which you restored the items.
2. In the restoreTaskId path parameter, specify the ID assigned to the restore task in the response received as a result of the request performed at step 8.
```
Request:
GET https://127.0.0.1:11005/api/v1/flr/{restoreTaskId}/restore/{searchTaskId}/status

Request Header:
x-api-version:1.7-rev0

Request Parameters:
flrSessionId=7857aa56-a6fe-432b-a513-6afc6516a6e6
restoreTaskId=791bef75-4e10-40cf-9dcd-f9f627e14854
```
A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for AWS returns the status of the restore task.
```
Response:
200
Response Body:
{
    "restoreTaskId": "791bef75-4e10-40cf-9dcd-f9f627e14854",
    "results": [
        {
            "status": "Success",
            "path": "/accountingdata/report_1.txt"
        }
    ]
}
```

To get a detailed log for each item processed by the restore task, send the HTTP GET request to the /api/v1/flr/{flrSessionId}/restore/{restoreTaskId}/logs endpoint:

In the flrSessionId path parameter, specify a system ID assigned to the FLR session from which you restored the items.
In the restoreTaskId path parameter, specify the ID assigned to the restore task in the response received as a result of the request performed at step 8.
In the Limit query parameter, specify the maximum number of items to return in the response.
In the request body, specify a path to the item you have restored.

Request:
POST https://127.0.0.1:11005/api/v1/flr/{flrSessionId}/restore/{restoreTaskId}/logs

Request Header:
x-api-version:1.7-rev0

Request Parameters:
flrSessionId=7857aa56-a6fe-432b-a513-6afc6516a6e6
restoreTaskId=791bef75-4e10-40cf-9dcd-f9f627e14854

Request Body:
{
    "path": "/accountingdata/report_1.txt"
}

A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for AWS returns the total number of log records and detailed information on the restored items.

Response:
200

Response Body:
{
    "totalCount": 2,
    "logs": [
        {
            "status": "Success",
            "message": "/accountingdata/report_1.txt has been successfully restored",
            "id": 1,
            "startTime": "2024-10-03T09:51:50.519806",
            "stopTime": "2024-10-03T09:51:56.2525671"
        },
        {
            "status": "Success",
            "message": "Item File /accpuntingdata/report_1_RESTORED_20241003_095150.txt and its attributes were restored",
            "id": 2,
            "startTime": "2024-10-03T09:51:50.90262",
            "stopTime": "2024-10-03T09:51:56.2170634"
        }
    ]
}

To stop the restore task, send the HTTP POST request to the /api/v1/flr/{flrSessionId}/restore/{restoreTaskId}/stop endpoint:
1. In the flrSessionId path parameter, specify a system ID assigned to the FLR session in which the items were searched.
2. In the restoreTaskId path parameter, specify the ID assigned to the restore task from the response that was received as a result of the request made at step 8.
```
Request:
POST https://127.0.0.1:11005/api/v1/flr/{flrSessionId}/restore/{restoreTaskId}/stop
Request Header:
x-api-version:1.7-rev0

Request Parameters:
flrSessionId=7857aa56-a6fe-432b-a513-6afc6516a6e6
restoreTaskId=2044e84c-768a-47ce-8bf8-69aaa6f8540d
```
A successfully completed operation returns the 202 response code.
To stop the FLR session, send the HTTP POST request to the api/v1sessions/{sessionId}/stop endpoint and specify a system ID assigned to the FLR session in the sessionId path parameter. A successfully completed operation returns the 200 response code.