How To

To perform complex operations using the Veeam Backup for Microsoft Azure 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 File-Level Recovery

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

IMPORTANT

Veeam Backup for Microsoft Azure 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 Microsoft Azure User Guide, section Performing File-Level Recovery.

To recover files and folders of a protected Azure VM, use the following requests:

To start an FLR session, send the HTTP POST request to the /restorePoints/virtualMachines/{restorePointId}/restoreFile endpoint:
1. In the restorePointId path parameter, specify a system ID assigned to a restore point to which you want to restore of files and folders of the Azure VM.
2. In the request body, provide a reason for performing the operation, choose whether you want to restore data to the original location and specify a service account whose permissions will be used to restore data to the original location.
```
Request:
POST https://51.11.247.127/api/v8/restorePoints/virtualMachines/{restorePointId}/restoreFile

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

Request Body:
{
    "reason": "restore corrupted items",
    "serviceAccountId": 45645njn-4jn5-8im6-f345-lknkjn664,
    "flrRto": true,
}
```
A successfully completed operation returns the 202 response code. In the response body, Veeam Backup for Microsoft Azure 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 /jobSessions/{sessionId} endpoint and specify the system ID assigned to the FLR session in the sessionId path parameter. Then, verify whether the value of the isFlrSessionReady parameter is true.
To browse files and folders by a specific directory, send the HTTP POST request to the /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 the absolute path to the necessary directory on Azure VM whose items will be returned in the response.
```
Request:
POST https://51.11.247.127/api/v8/flr/{flrSessionId}/browse

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

Request Body:
{
    "path": "/user1/accountingdata"
}
```
A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for Microsoft Azure returns the detailed information on each item.
```
Response:
200

Response Body:
{
"results": [
    {
        "itemPath": "/accountingdata",
        "name": "report_1.txt",
        "type": "File",
        "size": 8,
        "lastModificationTime": "2025-02-28T11:29:18.898Z"
    }
],
"count": 1
}
```
To start searching through files and folders by a specific directory and name, send the HTTP POST request to the /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 request body, specify the following information:
  1. path — the absolute path to the necessary directory on the Azure VM where the items you want to search are located.
  2. limit — the number of results that must be returned in the response.
  3. traverse — a Boolean value defining whether you want the search to be performed through all subdirectories and nested elements.
  4. searchPattern — a name of the file or part of the name that will be used as a search template.
```
Request:
POST https://51.11.247.127/api/v8/flr/{flrSessionId}/search/start

Request Parameters:
flrSessionId=7857aa56-a6fe-432b-a513-6afc6516a6e6

Request Body:
{
    "path": "/accountingdata",
    "limit": 10,
    "traverse": true,
    "searchPattern": "report_1"
}
```
A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for Microsoft Azure 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 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 2.

Request:
GET https://51.11.247.127/api/v8/flr/{flrSessionId}/search/{searchTaskId}/results

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 Microsoft Azure 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": [
        {
            "itemPath": "/accountingdata",
            "name": "report_1.txt",
            "type": "File",
            "size": 7,
            "lastModificationTime": "2025-02-26T11:29:18.898Z"
        },
        {
            "itemPath": "/accountingdata",
            "name": "report_10.txt",
            "type": "File",
            "size": 10,
            "lastModificationTime": "2025-02-27T11:29:18.898Z"
        },
        {
            "itemPath": "/accountingdata",
            "name": "report_110.txt",
            "type": "File",
            "size": 10,
            "lastModificationTime": "2025-02-28T11:29:18.898Z"
        }
    ]
}

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 /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 2.
```
Request:
POST https://51.11.247.127/api/v8/flr/{flrSessionId}/search/{searchTaskId}/nextPage

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

To retrieve the results of the continued search, send the HTTP GET request to the /flr/{flrSessionId}/search/{searchTaskId}/results endpoint as described at step 3. Note that the results obtained in the previous query will be lost.
To stop the search task, send the HTTP POST request to the /flr/{flrSessionId}/search/{searchTaskId}/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 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 2.
```
Request:
POST https://51.11.247.127/api/v8/flr/{flrSessionId}/search/{searchTaskId}/stop

Request Parameters:
flrSessionId=7857aa56-a6fe-432b-a513-6afc6516a6e6
searchTaskId=3fa85f64-5717-4562-b3fc-2c963f66afa6
```
A successfully completed operation returns the 202 response code.
To restore specific files and folders, send the HTTP POST request to the /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 the absolute paths to the items you want to restore, an alternative absolute path to the directory to which the items will be restored if the original directory no longer exists, 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 Azure VM, 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 Azure VM, enter Overwrite.
IMPORTANT

If the original directory no longer exists and you do not specify an alternative path to the directory on the Azure VM to restore the items, the completed operation will return the 500 response code.
```
Request:
POST https://51.11.247.127/api/v8/flr/{flrSessionId}/restore

Request Parameters:
flrSessionId=7857aa56-a6fe-432b-a513-6afc6516a6e6
Request Body:
{
    "itemPaths": [
        "/accountingdata/report_1.txt", 
        "/var/log/journal/376b1a5b5e8e7064ad8b0edc1ad42/system.journal", 
        "/billingdata/report_15.txt"
    ],
    "restoreType": "Keep",
    "alternativePath": "/auditdata/report_25.txt"
}
```
A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for Microsoft Azure 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 /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 6.
```
Request:
GET https://51.11.247.127/api/v8/flr/{restoreTaskId}/restore/{searchTaskId}/status

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 Microsoft Azure returns the status of the restore task.
```
Response:
200

Response Body:
{
    "restoreTaskId": "791bef75-4e10-40cf-9dcd-f9f627e14854",
    "results": [
        {
            "path": "/accountingdata/report_1.txt",
            "status": "Success"
        }
    ]
}
```

To get a detailed log for each item processed by the restore task, send the HTTP GET request to the /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 6.
In the Offset query parameter, specify the first N items of a resource collection that will be excluded from the response.
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://51.11.247.127:<%PORT%>/api/v8/flr/{flrSessionId}/restore/{restoreTaskId}/logs

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 Microsoft Azure returns the total number of log records and detailed information on the restored items.

Response:
200

Response Body:
{
    "path": "string",
    "pagination": {
        "totalCount": 2,
        "count": 2,
        "offset": 0,
        "limit": 0
    },
    "results": [
        {
            "message": "/accountingdata/report_1.txt has been successfully restored",
            "status": "Success",
            "id": 1,
            "startTime": "2025-02-27T12:05:10.358Z",
            "stopTime": "2025-02-28T12:05:11.367Z"
        },
        {
            "message": "Item File /accpuntingdata/report_1_RESTORED_20241003_095150.txt and its attributes were restored",
            "status": "Success",
            "id": 2,
            "startTime": "2025-02-28T12:05:10.358Z",
            "stopTime": "2025-02-28T12:05:11.367Z"
        }
    ]
}

To stop the restore task, send the HTTP POST request to the /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 6.
```
Request:
POST https://51.11.247.127/api/v8/flr/{flrSessionId}/restore/{restoreTaskId}/stop

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 /jobSessions/{sessionId}/stop endpoint and specify the system ID assigned to the FLR session in the sessionId path parameter. A successfully completed operation returns the 200 response code.