The following topics will instruct you 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 Plug-in for Nutanix AHV REST API-exposed entity has a resource representing it. To get a resource representation, request its URL.

Veeam Plug-in for Nutanix AHV 8 REST API requests use the following base URL format:

https://<hostname>/extension/799a5a3e-ae1e-4eaf-86eb-8a9acc2670e2/api/<version>

where:

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

The current version of the Veeam Plug-in for Nutanix AHV REST API is v8.

To get a collection of Veeam Plug-in for Nutanix AHV REST API resources, request the base URL followed by a resource collection endpoint. For example:

https://<hostname>/extension/799a5a3e-ae1e-4eaf-86eb-8a9acc2670e2/api/v8/jobs

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

https://enterprise01.tech.local/extension/799a5a3e-ae1e-4eaf-86eb-8a9acc2670e2/api/v8/jobs/3ad6270a-c42d-4925-aa48-9cbfc80100a6

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

[
  {
    "id": "83238f03-a894-497c-bf4d-7930f328f22a",
    "name": "Mail Server Daily Backup Job",
    ...
  },
  
  {
    "id": "3ad6270a-c42d-4925-aa48-9cbfc80100a6",
    "name": "Media Server Weekly Backup Job",
    ...
  }
]

The Veeam Plug-in for Nutanix AHV REST API is available in multiple versions. However, only Veeam Plug-in for Nutanix AHV REST API version 8 is supported. The API version must be specified in the request URL as described in Resource URLs.

The Veeam Plug-in for Nutanix AHV REST API is NOT backward-compatible with client applications that were created using earlier versions of the REST API specification. This means that you cannot use any of the supported REST API specifications to perform operations with Veeam Plug-in for Nutanix AHV resources if the specification version has been released earlier:

To start working with the Veeam Plug-in for Nutanix AHV REST API, users must first authenticate themselves with the Veeam Backup & Replication server and get authorization to make requests. Veeam Backup & Replication REST API authorization process 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 and that must be used in all requests during the current logon session.
• Refresh token is a string that represents authorization granted to the client and that can be used to obtain a new access token if the current access token expires or becomes lost.

The Veeam Backup & Replication REST API access token expires in 60 minutes, refresh token expires in 14 days.

The authorization process involves the following procedures:

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

To obtain authorization tokens, a user sends the HTTP POST request to the /api/oauth2/token endpoint sent to the Veeam Backup & Replication server in 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 version of the Veeam Backup & Replication REST API .

For authorization, you must also 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 of the Veeam Backup & Replication REST API is v1.

• Version and revision are specified in the request header in the following format: <version>-<revision>.

The current version and revision of the Veeam Backup & Replication REST API is 1.3-rev1.

The request body must contain the grantType parameter with the specified password value and the credentials of a backup server administrator.

A successfully completed operation returns the 200 response code. In the response body, Veeam Backup & Replication returns an access token, a refresh token and expiration time of each token. The user inserts the access token in headers of further requests to the Veeam Plug-in for Nutanix AHV REST API. The refresh token must be saved locally.

To learn how to authorize your access using the Password grant type, see the example below. Alternatively, you can use the Swagger UI.

Example

To obtain an access token, a user sends the HTTP POST request to the api/oauth2/token endpoint.

In the request body, the user specifies the following parameters:

• grantType — the password value must be specified for this parameter.
• userName and password — credentials used to access the server; in this example, administrator and Password1 are used.

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

Request Header
x-api-version:1.3-rev1

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

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 obtain a refresh token, a user sends the HTTP POST request to the api/oauth2/token endpoint. 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-rev1

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, a user sends the HTTP POST request to the api/oauth2/logout endpoint. 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-rev1
Authorization: Bearer YSEoaL6H9EEyJpnrJ9WhLtzbrrBBYWqMQFDBQuLnp13qGQX6MjNfZ_wriPIRHQrbY-8dYtsWcRZQczIHVuSqbnVb00m-yOihPZZHQ48aP1VcgUtgnYTvtAO3WRJ1cJ8VaIXzsV...

You receive a response in the following format.

Response
200

To perform operations with Veeam Plug-in for Nutanix AHV entities using the REST API, you can use the following standard HTTP methods:

• GET — retrieves information about a resource or collection.
• POST — creates a new resource in a collection or activates a resource action.
• PUT — makes changes to a resource.
• DELETE — removes a resource from a collection.

To control the amount and order of data that the Veeam Plug-in for Nutanix AHV REST API returns for a resource or collection, you can use the following query parameters:

• Offset Parameter
• Limit Parameter
• Sort Parameters
• Filter Parameters

Query parameters are part of a URL. The question mark ? separates query parameters from a resource collection endpoint.

The offset query parameter is used to exclude from a response the first N items of a resource collection.

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/extension/799a5a3e-ae1e-4eaf-86eb-8a9acc2670e2/api/v8/sessions?offset=2

You can combine the limit and the offset query parameters to request a particular set of items. Note that the offset 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 Plug-in for Nutanix AHV REST API returns resources in the default order based on its own semantics. To sort or filter a collection before excluding results, use the sort or filter query parameters. Note that the sort and filter parameters are applied before the offset parameter, regardless of their position in the request. That is, a collection is first filtered or sorted, and then the top results are excluded.

The limit query parameter is used to specify the maximum number of items of a resource collection to return in a response.

For example, to return only the first 3 VMs in the /protectedVms collection, send the following request:

GET https://enterprise01.tech.local/extension/799a5a3e-ae1e-4eaf-86eb-8a9acc2670e2/api/v8/protectedVms?limit=3

The Veeam Plug-in for Nutanix AHV REST API returns resources in the default order based on its own semantics. To sort or filter a collection before excluding results, use the sort or filter query parameters. Note that the 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 excluded.

The sort query parameter is used to sort items of a resource collection in a response. Some resource properties of Veeam Plug-in for Nutanix AHV REST API schemas can be used as parameter values for the sort query parameter.

The parameter accepts the array data type. To sort a resource collection, use the sort query parameter in the following format:

GET https://enterprise01.tech.local/extension/799a5a3e-ae1e-4eaf-86eb-8a9acc2670e2/api/v8/<endpoint>?sort=[{"property":"<property>","direction":"<direction>","collation":"<collation>"}]

where:

• endpoint is a resource collection endpoint.
• property is the searched property name.

• direction is a direction specifier. The following values are available:

  • ascending
  • descending

• collation is the type of rules that determine how sorted values are compared to each other. The following types are available:

  • ordinal — compare strings symbol-by-symbol
  • ignorecase — compare strings symbol-by-symbol ignoring character case
  • lexicographic — compare words with words and numbers with numbers

  The default value is ordinal.

For example, to sort items of the /sessions resource collection by start time where the sessions is located in the descending order, send the following request:

GET https://enterprise01.tech.local/extension/799a5a3e-ae1e-4eaf-86eb-8a9acc2670e2/api/v8/sessions[{"property":"startTimeUtc","direction":"descending","collation":"ordinal"}]

Some resource properties of Veeam Plug-in for Nutanix AHV REST API schemas can be used as filter query parameters. Filter query parameters are used 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.

To filter a resource collection use the filter query parameter in the following format:

GET https://enterprise01.tech.local/extension/799a5a3e-ae1e-4eaf-86eb-8a9acc2670e2/api/v8/<endpoint>?filter=[{"property":"<property>","operation":"<operation>","collation":"<collation>","value":"<value>"}]

where:

• endpoint is a resource collection endpoint.
• property is the searched property name.

• operation is a relational or logical operator.

• collation is the type of rules that determine how specified values are compared with resource property values. The following types are available:

  • ordinal — compare strings symbol-by-symbol
  • ignorecase — compare strings symbol-by-symbol ignoring character case
  • lexicographic — compare words with words and numbers with numbers

  The default value is ordinal.

• value is a resource property value.

The Veeam Plug-in for Nutanix AHV REST API supports the following operators:

To group multiple filter expressions, you can include them into a grouping expression. A grouping expression includes the following elements:

• operation is a relational or logical operator.
• items is an array of filter expressions.

A grouping expression has the following format:

GET https://enterprise01.tech.local/extension/799a5a3e-ae1e-4eaf-86eb-8a9acc2670e2/api/v8/<endpoint>?filter=[{"operation":"<operation>","items":[{"property":"<property>","operation":"<operation>","value":"<value>","collation":"<collation>"},{"property":"<property>","operation":"<operation>","value":"<value>","collation":"<collation>"}]}]

To combine filter expressions you can use the following operators:

Example

For example, to return a list of session of backup jobs with the Success, Failed or Canceling status, send the following the request:

GET https://enterprise01.tech.local/extension/799a5a3e-ae1e-4eaf-86eb-8a9acc2670e2/api/v8/sessions?filter=[{"operation":"and","items":[{"operation":"in","collation":"ordinal","property":"status","value":["Success","Failed","Canceling"]},{"operation":"in","collation":"ordinal","property":"sessionType","value":["BackupVmJob"]}]}]

To start working with the Veeam Plug-in for Nutanix AHV REST API, you can use any client application that supports the HTTPS protocol.

The Veeam Plug-in for Nutanix AHV REST API is additionally available through the Swagger UI, a tool that you can use to evaluate and explore capabilities of the REST API. The Swagger UI visually presents API specification files and allows you to work with resources.

All resources and methods are expandable. When you expand a method, you get a full description of available parameters and an automatically generated example. You can also send requests and see response messages.

To access the Swagger UI for the Veeam Plug-in for Nutanix AHV REST API, in a web browser, navigate to the following URL:

https://<hostname>/extension/799a5a3e-ae1e-4eaf-86eb-8a9acc2670e2/swagger/index.html

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

In the Select a definition field, select the version and revision of the Veeam Plug-in for Nutanix AHV REST API.

Veeam Plug-in for Nutanix AHV 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 public API page, expand the Login resource and click POST api/oauth2/token.

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

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

      

   3. From the grantType drop-down list, select Password.

   4. In the userName and password fields, specify the credentials of a backup server administrator.

   5. Click Execute.

      

      Wait for the response from the server. A successfully completed operation returns the 200 response code. In the response body, Veeam Plug-in for Nutanix AHV returns an access token, a refresh token, and the expiration time of each token.

      

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

2. Authorize your access in the Swagger UI:

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

      https://<hostname>/extension/799a5a3e-ae1e-4eaf-86eb-8a9acc2670e2/swagger/index.html
      

   2. In the Available authorizations window, insert the access token saved locally in the Value field. Use the Bearer <access_token> format.

      

   3. Click Authorize.

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

   1. On the Veeam Plug-in for Nutanix AHV public 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 grantType drop-down list, select RefreshToken.

   4. In the refreshToken field, insert the refresh token saved locally, 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 the Swagger UI, repeat step 2.

4. When you finish working with the Swagger UI:

   1. At the top right corner of the Veeam Plug-in for Nutanix AHV public API page, click Authorize.

   2. In the Available authorizations window, click Logout.

      

After you get authorization, you can send HTTP requests to Veeam Plug-in for Nutanix AHV REST API collections and resources in the Swagger UI.

To send a request:

1. On the Veeam Plug-in for Nutanix AHV public 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. Enter 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.