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.2-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.

REST API Revision	Support Status	Veeam Backup & Replication Build
1.3-rev0	Supported	13.0.0.4967
1.2-rev1	Supported	12.3.1.1139
1.2-rev0	Supported	12.3.0.310
1.1-rev2	Supported	12.2.0.334
1.1-rev1	Supported	12.1.0.2131
1.1-rev0	Supported	12.0.0.1420
1.0-rev2	Deprecated	11.0.1.1261
1.0-rev1	Deprecated	11.0.0.837

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.2-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.2-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.

Credential	Lifetime
Access token	60 minutes
Refresh token	14 days
Authorization code	5 minutes

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

To get an access token, send the HTTP POST request to the /api/oauth2/token path.

In the request body, the following parameters must be specified:

• Grant type: password or authorization_code
• Credentials matching the grant type

The Veeam Backup & Replication REST API accepts the following authorization grant types:

• Password grant type — used to get an access token by providing a user name and password.

• Authorization code grant type — used to get an access token by providing an authorization code. To get an authorization code, send the HTTP POST request to the /api/oauth2/authorization_code path.

Using Password Grant Type

To obtain authorization tokens, send the HTTP POST request to the /api/oauth2/token path.

The request body must contain the grant_type parameter with the specified password value and the user credentials of an account created in Veeam Backup & Replication.

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.

Example

To obtain 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:

Parameter	Value	Description
grant_type	password	Authorization grant type
username	<Username>	Account name used to access the server
password	<Password>	Account password

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

Request Header
x-api-version:1.2-rev0

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

You receive a response in the following format.

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"
}

Using Authorization Code Grant Type

You can use the authorization code grant type to delegate data protection operations from Client A to Client B. Authorization code is a temporary code that Client B can exchange for an access token without providing a user name and password. Client B will have the same set of permissions as Client A, which provided the authorization code.

The authorization code expires in 60 seconds.

To get authorization using the Authorization Code grant type, take the following steps:

1. [Client A] Before you request an authorization code, make sure you have a valid access token. For details, see Using Password Grant Type or Using Refresh Token.

2. [Client A] To obtain an authorization code, send the HTTP POST request to the /api/oauth2/authorization_code path.

   A successfully completed operation returns the 200 response code. In the response body, the REST API returns an authorization code, which can be used by Client B for authorization.

3. [Client B] To obtain an access token and refresh token, send the HTTP POST request to the /api/oauth2/token path. The request body must contain the grant_type parameter with the specified authorization_code value and the authorization code itself.

   A successfully completed operation returns the 200 response code. In the response body, REST API returns an access token, its expiration time (in seconds) and a refresh token. You must specify the access token in headers of further requests to the REST API. To use the refresh token for obtaining another access token, save it locally. For more information, see Using Refresh Token.

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:

Parameter	Value	Description
grant_type	refresh_token	Authorization grant type
refresh_token	<Refresh token>	Previously saved refresh token

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.2-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.2-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.

When you are running the Veeam Backup & Replication setup wizard, you can specify a port that must be used for connection with the REST API service. The default port is 9419. During the Veeam Backup & Replication installation, a self-signed TLS certificate is created and bound to the REST API and the specified 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 following command in the command line:

netsh http show sslcert ipport=0.0.0.0:9419

If the existing TLS certificate expires, update it with the netsh command.

Updating TLS Certificate

If the existing TLS certificate expires, you need to remove it, add a new certificate with the Veeam Backup & Replication console or Veeam PowerShell, and bind the new certificate to the 9419 port.

To update the TLS certificate:

1. Remove the current TLS certificate with the following command:

   netsh http delete sslcert ipport=0.0.0.0:9419
   

2. Add a new certificate with 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.

3. Bind the new TLS certificate to the 9419 port and the REST API application ID. Use the following command:

   netsh http add sslcert ipport=0.0.0.0:9419 certhash=<hash> appid="{284175c4-aa3e-4c6f-a2dd-5a4c80552eb9}" certstorename=<storeName>
   

   where:

   • <hash> is an SHA hash of the new certificate. You can view the certificate hash with the Certificate Manager tool. To details, see Microsoft Docs.

   • <storeName> is a certificate store name. The parameter is optional, defaults to MY.

   For example:

   netsh http add sslcert ipport=0.0.0.0:9419 certhash=df43bb1342654f1010b2ab31d682366df2e5697f appid="{284175c4-aa3e-4c6f-a2dd-5a4c80552eb9}" certstorename=WebHosting
   

   For more information on the add sslcert command, see Microsoft Docs.

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

Method	Description	Example
GET	Retrieves information about a resource or collection	Get All Jobs
POST	Creates a new resource in a collection or activates a resource action.	Create Job
PUT	Makes changes to a resource	Edit Job
DELETE	Removes a resource from a collection.	Delete Job

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.

Header	Sample Value	Description
Authorization	Bearer eyJhbGciOi...	Authenticates the client that sends the request to the server. The header must contain an access token in the following format: Bearer <access token>.
x-api-version	1.2-rev0	Specifies the version and revision of the REST API.
Content-Type	application/json	Identifies the media type of the request body. The REST API supports the following media types: application/x-www-form-urlencoded — for the Get Access Token request. application/json — for all other requests that contain a request body.
Accept	application/json	Specifies the media type of the response body. The REST API supports only the application/json media type.

In response, the server passes the following header parameters.

Header	Sample Value	Description
Cache-Control	private	Specifies the private caching type (tied to the client) for requests and responses.
Content-Length	20256	Identifies the length of the response body, in bytes.
Content-Type	application/json; charset=utf-8	Identifies the media type and encoding of the response body. The REST API supports only the application/json media type.
X-Frame-Options	SAMEORIGIN	Blocks clickjacking attacks.
X-XSS-Protection	1; mode=block	Prevents reflected cross-site scripting attacks.
Strict-Transport-Security	max-age=31536000	Identifies that the server should only be accessed over HTTPS and specifies the time, in seconds, that the client should remember this requirement.
X-Content-Type-Options	nosniff	Blocks media type sniffing.
Date	Thu, 13 Apr 2025 14:35:46 GMT	The date and time the response was sent.

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. The default path is %Program Files%\Veeam\Backup and Replication\Backup\RestApiService\specs\latest.

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

1. Navigate to the following URL:

   https://<hostname>:<port>/swagger/ui/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 number 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.