The following topics will help you learn how to connect to the REST API and authorize your access, and how to control and sort the data that the REST API returns.

Each Veeam Backup & Replication REST API-exposed entity has a resource representing it. To get a resource representation, request its URL.

The Veeam Backup & Replication REST API requests use the following base URL format:

https://<hostname>:<port>/api/<version>

where:

• <hostname> is a public IPv4 address or DNS hostname of the machine where Veeam Backup & Replication is installed.
• <port> is the REST API port number set during Veeam Backup & Replication installation.

The default port number is 9419.

• <version> is an API version.

The current major version is v1.

To get a collection of Veeam Backup & Replication REST API resources, request the base URL followed by a resource collection endpoint. For example:

https://enterprise01.tech.local:9419/api/v1/sessions

To get a representation of an individual resource, specify a resource identifier after the resource collection endpoint. For example:

https://enterprise01.tech.local:9419/api/v1/sessions/c36824e9-0c3e-4892-8dff-44fd56968506

The resource identifier is represented by the id property of the resource. For example:

[
    {
        ...
        "id": "c36824e9-0c3e-4892-8dff-44fd56968506",
        "name": "Infrastructure",
        ...
        ,
    },
    {
        ...
        "id": "e170b7a4-0375-41b1-b066-d4be19d7b7ce",
        "name": "Backup Job 1",
        ...
    }
]

Veeam Backup & Replication REST API is backward-compatible. This means that, in general, client requests that use an earlier version or revision of the REST API are compatible with further REST API updates. You can find the current Veeam Backup & Replication REST API version and revision in the REST API specification. It is specified in the version field of the info object. For example:

"version": "1.3-rev0"

The table below lists the REST API revisions, their support statuses, and the Veeam Backup & Replication build numbers when the REST API revisions were released.

The Deprecated support status is intermediate. Deprecated REST API revisions are expected to become unsupported. You can still use them but it is recommended that you switch to a newer one.

You must specify the Veeam Backup & Replication REST API version and revision in each request. The requirement lets you minimize changes in your client application with every REST API update.

Veeam Backup & Replication REST API implements a combined approach of versioning:

• Major version is specified in the request path in the following format: v<major_version>. The current major version is v1.

• Version and revision are specified in the request header in the following format: <version>-<revision>. For example, 1.3-rev0.

For example, to obtain current date and time on the backup server, send the HTTP GET request to the api/<major_version>/serverTime path. In the x-api-version header, specify a version and revision in the following format: <version>-<revision>.

Request
GET https://enterprise01.tech.local:9419/api/v1/serverTime

Request Header
x-api-version:1.3-rev0

Communication between the client and Veeam Backup & Replication REST API is established over HTTPS. To ensure data privacy, unencrypted HTTP is not supported. The client verifies the REST API identity with a server TLS certificate. For details on managing certificates, see TLS Certificate.

Authorization in REST API

Authorization process of the REST API is based on the OAuth 2.0 Authorization Framework and involves obtaining an access token and a refresh token.

• Access token is a string that represents authorization issued to the client. It must be specified in all requests during the current logon session.
• Refresh token is a string that represents authorization granted to the client. It is used to obtain a new access token if the current access token expires or becomes lost.

The authorization process involves the following procedures:

1. Requesting authorization
2. Using the refresh token
3. Performing logout

Credentials Lifetime

The access token, refresh token and authorization code have their default lifetime after which they expire. The lifetime starts from the time the authorization response was generated.

To get access to the REST API resources, the client obtains an access token — a string that denotes client access attributes and that must be specified in all requests to the REST API.

The Veeam Backup & Replication REST API accepts password grant type authorization, which allows you to get an access token by providing a user name and password.

Example

To get an access token and a refresh token send the HTTP POST request to the /api/oauth2/token path. In the x-api-version header, specify the current revision of the Veeam Backup & Replication REST API.
In the request body, specify the following parameters:

Request
POST https://enterprise01.tech.local:9419/api/oauth2/token

Request Header
x-api-version:1.3-rev0

Request Body
grant_type=password&username=administrator&password=Password1

A successfully completed operation returns the 200 response code. In the response body, Veeam Backup & Replication returns an access token, its expiration time (in seconds) and a refresh token. Specify the access token in headers of further requests to the Veeam Backup & Replication REST API. The refresh token must be saved locally.

Response
200

Response Body
{
  "access_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJuYmYiOjE1ODY...",
  "token_type": "bearer",
  "refresh_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJ0b2tlbl9pZCI...",
  "expires_in": 900,
  ".issued": "2025-06-10T10:29:39",
  ".expires": "2025-06-10T10:44:39",
  "username": "administrator"
}

Refresh token is a token used to refresh an expired or lost access token.

To refresh an access token, send the HTTP POST request to the /api/oauth2/token path. In the request body, specify the following parameters:

A successfully completed operation returns the 200 response code and a new pair of tokens in the response body.

Example

To refresh an access token, send the HTTP POST request to the api/oauth2/token path. In the x-api-version header, specify the current revision of the Veeam Backup & Replication REST API.

In the body of the request, specify the refresh_token grant type and the refresh token itself.

Request
POST https://enterprise01.tech.local:9419/api/oauth2/token

Request Header
x-api-version:1.3-rev0

Request Body
grant_type=refresh_token&refresh_token=eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJ0b2tlbl9pZCI6ImQ5ZDhiN2RlLWIwYjUtNDc1Yi04ZTE4LTU4ZGMzMzVmOWIzNSIsInNob3J0X3Rl...

You receive a response in the following format.

Response
200

Response Body
{
  "access_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJuYmYiOjE1ODYyNTU3ODMsImV4cCI6MTU4NjI1NjY4MywiaWF0IjoxNTg2MjU1NzgzLCJhdWQiO...",
  "token_type": "bearer",
  "refresh_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJ0b2tlbl9pZCI6ImI5MjJhNGJiLTJmY2YtNGMwZi1hZGMxLTg2M2I4YzY1MzkxMiIsInNob3J0X3...",
  "expires_in": 900,
  ".issued": "2025-04-07T10:36:23",
  ".expires": "2025-04-07T10:51:23"
}

To log out, send the HTTP POST request to the api/oauth2/logout path. After you log out, access and refresh tokens are expired. A successfully completed operation returns the 200 response code.

Example

To log out, send the HTTP POST request to the api/oauth2/logout path. In the x-api-version header, specify the current revision of the Veeam Backup & Replication REST API, in the Authorization header — currently valid access token in the Bearer <access_token> format.

Request
POST https://enterprise01.tech.local:9419/api/oauth2/logout

Request Header
x-api-version:1.3-rev0
Authorization: Bearer YSEoaL6H9EEyJpnrJ9WhLtzbrrBBYWqMQFDBQuLnp13qGQX6MjNfZ_wriPIRHQrbY-8dYtsWcRZQczIHVuSqbnVb00m-yOihPZZHQ48aP1VcgUtgnYTvtAO3WRJ1cJ8VaIXzsV...

You receive a response in the following format.

Response
200

Communication between the client and Veeam Backup & Replication REST API is established over HTTPS. To ensure data privacy, unencrypted HTTP is not supported. The client verifies the REST API identity with a server TLS certificate. The REST API uses the certificate of Veeam Backup & Replication.

During the Veeam Backup & Replication installation, a self-signed TLS certificate is created and bound to the REST API and the 9419 port.

If the existing TLS certificate expires, or if you want to use another certificate (for example, the one obtained from a Certificate Authority), you can add a new certificate. For details, see Updating TLS Certificate.

To view the TLS certificate, use the Get Backup Server Certificate request.

Updating TLS Certificate

If the existing TLS certificate expires, you need to install a new one using the Veeam Backup & Replication console or Veeam PowerShell. For details, see the Backup Server Certificate section of the Veeam Backup & Replication User Guide and the Add-VBRBackupServerCertificate section of the Veeam PowerShell Reference.

To perform REST API operations, use the following standard HTTP methods:

HTTP headers let the client and the server pass additional information with HTTP requests or responses. An HTTP header consists of a case-insensitive name and header value. The colon : separates the name and the value of the header.

When you send HTTP requests to the REST API, specify the following header parameters. All headers are required except the Content-Type header, which is required only if you specify a request body.

In response, the server passes the following header parameters.

Query parameters help you control the amount and order of data that the Veeam Backup & Replication REST API returns for a resource or collection. Query parameters are part of the URL that you specify in the request. The question mark ? separates query parameters from a resource collection path.

You can use the following query parameters:

• skip
• limit
• Sort Parameters
• Filter Parameters

You can use the skip query parameter to exclude the first N collection items from a response body.

For example, to return a list of sessions starting from the third one in the /sessions collection, send the following request:

GET https://enterprise01.tech.local:9419/api/v1/sessions?skip=2

You can combine the limit and the skip query parameters to request a particular set of items. Note that the skip parameter is applied before the limit parameter, regardless of the parameter position in the request. That is, top results are selected from a collection where a set of items is already excluded.

The Veeam Backup & Replication REST API returns resources in the default order based on its own semantics. To sort or filter a collection before excluding results, use sort and filter parameters. Note that sort and filter parameters are applied before the skip parameter, regardless of their position in the request. That is, a collection is first filtered or sorted, and then the top results are excluded.

You can use the limit query parameter to specify the maximum number of items of a resource collection to return in a response.

For example, to return only the first 3 sessions, send the following request:

GET https://enterprise01.tech.local:9419/api/v1/sessions?limit=3

The Veeam Backup & Replication REST API returns resources in the default order based on its own semantics. To sort or filter a collection before excluding results, use sort and filter parameters. Note that sort and filter parameters are applied before the limit parameter, regardless of their position in the request. That is, a collection is first filtered or sorted, and then the top results are selected.

You can use the orderColumn and orderAsc query parameters to sort items of a resource collection in a response.

Some resource properties of Veeam Backup & Replication REST API schemas can be used as parameter values for the orderColumn query parameter.

If the value of the orderAsc parameter is true, items are sorted in the ascending order by the orderColumn parameter. If the value is false, the items are sorted in the descending order.

For example, to sort sessions by session type in the ascending order, send the following request:

GET https://enterprise01.tech.local:9419/api/v1/sessions?orderColumn=SessionType&orderAsc=true

You can use filter query parameters to filter items of a resource collection to return a subset of resources in a response. The subset includes only those resources that satisfy parameter value specified in the query.

nameFilter

The nameFilter query parameter is used to filter items by the substring specified as the nameFilter value. The substring can be a part of any resource parameter.

To filter items, use the following methods:

• In the nameFilter parameter, specify a full string that must match one of the item parameters.
• In the nameFilter parameter, specify a substring that one of the item parameters must contain. To do this, use the asterisk * character at the beginning of the nameFilter value, at the end or both.

For example, to return a list of sessions that contain the Working substring in any of their parameters, send the following request:

GET https://enterprise01.tech.local:9419/api/v1/sessions?nameFilter=*Working*

Other Filter Parameters

Some resource properties of Veeam Backup & Replication REST API schemas can be used as filter query parameters.

For example, to return a list of job sessions, specify the Job value of the typeFilter parameter in the following request:

GET https://enterprise01.tech.local:9419/api/v1/sessions?typeFilter=Job

To start working with the Veeam Backup & Replication REST API, you can use any client application that supports the HTTPS protocol. In addition, the REST API is available through Swagger UI, a web-based tool that you can use to evaluate and explore the REST API capabilities. Swagger UI visually represents the API specification file and enables you to interact with API endpoints directly from the browser.

The Veeam Backup & Replication REST API is defined in the swagger.json file. You can find the file in the Veeam Backup & Replication installation folder.

To access the REST API Swagger UI, use a web browser:

1. Navigate to the following URL:

   https://<hostname>:<port>/swagger/index.html
   

   where:

   • <hostname> is a public IPv4 address or DNS hostname of the machine where Veeam Backup & Replication is installed.

   • <port> is the REST API port number set during Veeam Backup & Replication installation.

     The default port is 9419.

2. From the Select a definition list, select the REST API version you need.

Veeam Backup & Replication REST API authorization with the Swagger UI involves the following procedures:

1. Obtain an access token and a refresh token:

   1. On the Veeam Backup & Replication REST API page, expand the Login section and click POST api/oauth2/token.

   2. In the expanded method window, click Try it out.

   3. From the grant_type drop-down list, select password.

   4. In the username and password fields, specify the credentials of a user created in Veeam Backup & Replication.

   5. Click Execute.

      

      Wait for the response from the server. A successfully completed operation returns the 200 response code. In the response body, Veeam Backup & Replication returns an access token, its expiration time and a refresh token.

      

   6. Save the access and refresh tokens locally for further use.

      TIP
      

      You can download a server response in the JSON format. To do that, in the expanded method window, click Download at the lower right corner of the Response body field.

2. Authorize your access in the Swagger UI:

   1. At the top right corner of the Veeam Backup & Replication REST API page, click Authorize.

   2. In the Available authorizations window, insert the access token saved locally in the Value field.

      • If you use revision 1.2-rev1 or later, provide only the token itself.
      • For all earlier revisions, use the Bearer <access_token> format.

   3. Click Authorize.

      

3. When the access token expires, use the refresh token:

   1. On the Veeam Backup & Replication REST API page, expand the Login resource and click POST api/oauth2/token.

   2. In the expanded method window, click Try it out.

   3. From the grant_type drop-down list, select refresh_token.

   4. In the refresh_token field, insert the saved refresh token and click Execute.

      

      Wait for the response from the server. A successfully completed operation returns the 200 response code and a new pair of tokens in the response body.

      

   5. Save the access and refresh token locally for further use. To authorize your access in Swagger UI, repeat step 2.

4. When you finish working with the Swagger UI:

   1. At the top right corner of the Veeam Backup & Replication REST API page, click Authorize.
   2. In the Available authorizations window, click Logout.
   

After you get authorization, you can send HTTP requests to Veeam Backup & Replication REST API collections and resources in the Swagger UI.

To send a request:

1. On the Veeam Backup & Replication REST API page, expand a resource to which you want to perform an operation.

2. In the list of request methods, click the required method.

3. In the expanded method window, click Try it out.

4. Specify parameter values if required.

5. Click Execute.

   

   The Swagger UI returns a response body as well as a response code and response headers. Additionally the Swagger UI generates a curl command and a URL for your request.

   TIP
   

   You can download a server response in the JSON format. To do that, in the expanded method window, click Download at the lower right corner of the Response body field.