The following topics will help you learn how to connect to Veeam ONE REST API and authorize your access. You will also learn what method-implemented operations you can perform with Veeam ONE entities, and how to control and sort the data that Veeam ONE REST API returns.

Each Veeam ONE REST API-exposed entity has a resource representing it. To get a resource representation, request its URL. Most of Veeam ONE REST API URLs have the following base:

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 you specified during the Veeam ONE Web Services component installation.

  The default port number is 1239.

• <version> is an API version.

  The current version is 2.3.

To get a collection of Veeam ONE REST API resources, request a base URL followed by a resource collection path. For example:

https://one-srv:1239/api/v2.3/sessions

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

https://one-srv:1239/api/v2.3/sessions/1000

In the following example, the resource identifier is represented by the jobSessionId property of the resource from the collection.

{
  "jobSessionId": 1000,
  "name": "Object properties data collection",
  "type": "AggregateProperties",
  "status": "Success",
  "statusPriority": 0,
  "start": "2023-11-15T12:32:02.7Z",
  "end": "2023-11-15T12:32:02.7Z"
}

To start working with Veeam ONE REST API, clients must first authenticate themselves. Veeam ONE 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 must be used in all requests during the current logon session.
• Refresh token is a string that represents authorization granted to the client and can be used to obtain a new access token when the current access token expires.

Veeam ONE REST API authorization process involves the following procedures:

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

To obtain a pair of tokens, the client sends the HTTP POST request to the /api/token path.

A successfully completed operation returns the 200 Success response code and an access and a refresh token in the response body. The client inserts the access token in headers of further requests to Veeam ONE REST API. The refresh token must be saved locally.

To obtain a new pair of tokens in case the access token expires or becomes invalid, the client sends the POST HTTP request with the refresh token in the request body to the /api/token path. A successfully completed operation returns the 200 Success response code and a new pair of tokens in the response body.

When the client finishes working with Veeam ONE REST API, he logs out by sending the POST HTTP request with the access token to the /api/revoke path. A successfully completed operation returns the 200 Success response code.

The following example illustrates how the client and server communicate using requests and responses.

1. To obtain an access and a refresh token, send the HTTP POST request to the /api/token path.

   In the body of the request, specify the following parameters in the application/x-www-form-urlencoded or multipart/form-data format:

   • grant_type — the authorization process requires that the password value must be specified for this parameter.
   • username and password — credentials used to access the server; in this example, one-srv\administrator and Password1 are used.

   Request:
   POST https://one-srv:1239/api/token
   
   Request Header:
   Content-Type: application/x-www-form-urlencoded
   
   Request Body:
   grant_type : password
   username : one-srv\administrator
   password : Password1
   

   The server sends a response in the following format.

   Response Code:
   
   200 Success
   Response Body:
   
   {
      "access_token": "eyJhbGciOiJIUzI1NiIsImtpZCI6IldlYkFwaVNlY3VyaXR5S2V5IiwidHlwIjoiSldUIn0.eyJ1bmlxdWVfbmFtZSI6IklJLVYwMTEtMlxcQWRtaW5pc3RyYXRvciIsInJvbGUiOiJBZG1pbiIsImh0dHA6Ly9zY2hlbWFzLnhtbHNvYXAub3JnL3dzLzIwMDUvMDUvaWRlbnRpdHkvY2xhaW1zL3NpZCI6IlMtMS01LTIxLTQyOTA5MTM0ODQtMTAzNDIyNjA4Ny03MzA0MjcyODQtNTAwIiwiQWNjZXNzVG9rZW5JZCI6IAFhYjkzYjllLWRhMWYtNDQxOC1hOWUzLTJlOGQxZDU4NDJlZiIsIlVzZXJJZCI6IjIiLCJuYmYiOjE2MDgyMTM1NTQsImV4cCI6MTYwODIxNDQ1MywiaWF0IjoxNjA4MjEzNTUzfQ.9ctZVlohJHJXx_XnF7VhzX_lMoZMCKahC_8cRKlYCQc",
      "refresh_token": "523cf7a168ac46b3bc4f884570f7bb5c",
      "token_type": "Bearer",
      "expires_in": 899,
      "user": "ONE-SRV\\Administrator",
      "user_role": "Admin"
   }
   

2. To refresh a pair of tokens, send the HTTP POST request to the /api/token path.

   In the body of the request, specify the following parameters in the application/x-www-form-urlencoded or multipart/form-data format:

   • grant_type — to refresh the token, it is required that the refresh_token value must be specified for this parameter.
   • refresh_token — the previously saved refresh token.

   Request:
   POST https://one-srv:1239/api/token
   
   Request Header:
   Content-Type: application/x-www-form-urlencoded
   
   Request Body:
   grant_type : refresh_token
   refresh_token : 523cf7a168ac46b3bc4f884570f7bb5c
   

3. To log out, send the HTTP POST request to the /api/revoke path.

   In the Authorization header, specify currently valid access token in the Bearer <access_token> format.

   In the body of the request, specify either of the following parameters in the application/x-www-form-urlencoded or multipart/form-data format:

   • token — currently valid access token.
   • UserSid — SID assigned to your user.

Note that if you choose to log out using the token parameter, only the specified token will be revoked. If you have obtained other tokens, they remain active.

Request:
POST https://localhost:1239/api/revoke

Request Header:
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer

Request Body:
token : eyJhbGciOiJIUzI1NiIsImtpZCI6IldlYkFwaVNlY3VyaXR5S2V5IiwidHlwIjoiSldUIn0.eyJ1bmlxdWVfbmFtZSI6IklJLVYwMTEtMlxcQWRtaW5pc3RyYXRvciIsInJvbGUiOiJBZG1pbiIsImh0dHA6Ly9zY2hlbWFzLnhtbHNvYXAub3JnL3dzLzIwMDUvMDUvaWRlbnRpdHkvY2xhaW1zL3NpZCI6IlMtMS01LTIxLTQyOTA5MTM0ODQtMTAzNDIyNjA4Ny03MzA0MjcyODQtNTAwIiwiQWNjZXNzVG9rZW5JZCI6IAFhYjkzYjllLWRhMWYtNDQxOC1hOWUzLTJlOGQxZDU4NDJlZiIsIlVzZXJJZCI6IjIiLCJuYmYiOjE2MDgyMTM1NTQsImV4cCI6MTYwODIxNDQ1MywiaWF0IjoxNjA4MjEzNTUzfQ.9ctZVlohJHJXx_XnF7VhzX_lMoZMCKahC_8cRKlYCQc

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.
• PATCH — makes changes to a resource.

The HTTP PATCH method can be used in two different ways:

• To change resource property values, for example, modify a data collection schedule.
• To perform an operation, for example, update a license file.

Modify a Resource

Each HTTP PATCH request that modifies a resource requires a request body. The body must contain properties with modified values. For example, to modify a data collection schedule, send the following request:

Request:
PATCH https://one-srv:1239/api/v2.2/dataCollection/schedule

Request Body:
{
  "startTime": "2023-11-18T21:00:00Z",
  "timeZoneId": "",
  "scheduleType": "Daily",
  "disabled": false,
  "periodically": {
    "period": 1,
    "interval": "Hours"
  },
  "daily": {
    "daysOfWeek": [
      "Monday",
      "Tuesday",
      "Wednesday",
      "Thursday",
      "Friday"
    ]
  },
  "monthlyDays": {
    "months": [],
    "days": []
  },
  "monthlyWeekDays": {
    "months": [],
    "dayOfWeekAppearance": [],
    "daysOfWeek": [
      "Monday",
      "Tuesday",
      "Wednesday",
      "Thursday",
      "Friday"
    ]
  }
}

Post an Action

For example, to update a license, send the following request:

Request:
PATCH https://one-srv:1239/api/v2.2/license/update

In case of success, the HTTP PATCH method returns the 200 Success response code.

The Veeam ONE REST API supports query string parameters that you can specify to control the amount and order of data that the Veeam ONE REST API returns for a resource or collection.

The Veeam ONE REST API supports the following query parameters:

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

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

For example, to show in a response all data collection tasks starting from the forth one, send the following request:

GET https://one-srv:1239/api/v2.3/dataCollection/tasks?Offset=3

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

For example, to return the second and the third data collection tasks configured in Veeam ONE, send the following request:

GET https://one-srv:1239/api/v2.3/dataCollection/tasks?Offset=1&Limit=2

The Veeam ONE REST API returns resources in the default order based on its own semantics.

The Limit query parameter is used to include in a response only the first N items of a resource collection.

For example, to show in a response only the first three task sessions from the /sessions collection, send the following request:

GET https://one-srv:1239/api/v2.3/sessions?Limit=3

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

To return 4 task sessions that follow the first 5 task sessions available in Veeam ONE, send the following request:

GET https://one-srv:1239/api/v2.3/sessions?Offset=5&Limit=4

The Veeam ONE REST API returns resources in the default order based on its own semantics.

The Sort query parameter is used to sort items in a resource collection returned in a response.

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

GET https://one-srv:1239/api/v2.3/<endpoint>?sort={"property":"<property>","direction":"<direction>","collation":"<collation>"}

where:

• endpoint is a resource collection endpoint.

• property is the searched property name.

  NOTE
  To sort a resource collection based on a property of a resource subschema, use the <subschema>.<property> format to specify the resource property name where <subschema> is the subschema 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 (only for case-sensitive databases)
  • ignorecase — compare strings symbol-by-symbol ignoring character case
  • lexicographic — compare words with words and numbers with numbers

  The default value is ignorecase.

Example

To sort task sessions by status, send the following request:

GET https://one-srv:1239/api/v2.3/sessions?sort={"property":"status","direction":"descending","collation":"lexicographic"}

The Filter query parameter is used to filter items in 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://one-srv:1239/api/v2.3/<endpoint>?filter={"property":"<property>","operation":"<operation>","collation":"<collation>","value":"<value>"}

where:

• endpoint is a resource collection endpoint.

• property is the searched property name.

  NOTE
  To filter a resource collection based on a property of a resource subschema, use the <subschema>.<property> format to specify the resource property name where <subschema> is the subschema 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 (only for case-sensitive databases)
    • ignorecase — compare strings symbol-by-symbol ignoring character case
    • lexicographic — compare words with words and numbers with numbers

  The default value is ignorecase.

  • value is a resource property value.

The Veeam ONE REST API supports the following operators:

Example

To group multiple filter expressions, you can include them into the item property in the following format:

GET https://one-srv:1239/api/v2.3/<endpoint>?filter={"operation":"<operation>","items":[{"property":"<property>","operation":"<operation>","collation":"<collation>","value":"<value>"},{"property":"<property>","operation":"<operation>","collation":"<collation>","value":"<value>"}]}

To combine expressions you can use the following operators:

Example

To get all data collection tasks with the Failed status, send the following request:

GET https://one-srv:1239/api/v2.3/dataCollection/tasks?Filter={"property":"status","operation":"equals","collation":"ignorecase","value":"failed"}

The Select parameter is used to return only selected resource properties in a response.

To return selected properties, use the select parameter in the following format:

GET https://one-srv:1239/api/v2.3/<endpoint>?Select=<property>

where:

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

To get multiple properties, specify their names separated with ASCII-encoded commas.

Example

To return the /sessions collection with only task session UID, name and status displayed, send the following request:

GET https://one-srv:1239/api/v2.3/<endpoint>?Select=jobSessionId%2Cname%2Cstatus

To start working with Veeam ONE REST API, you can use any client application that supports the HTTPS protocol.

Veeam ONE REST API is additionally available through Swagger UI, a tool that you can use to evaluate and explore capabilities of Veeam ONE REST API. Swagger UI visually presents API specification files and allows you to work with resources.

All methods are grouped into tags. You can filter methods by tag name using the Filter by tag field. Note, that the field is case-sensitive.

All tags 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 Swagger UI for Veeam ONE REST API, in the web browser, navigate to the following URL:

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

where:

• <hostname> is the DNS name or IP address of the machine on which the Veeam ONE Web Services component is installed.

• <port> is the REST API port number you specified during Veeam ONE Web Services installation.

  The default port number is 1239.

Alternatively, you can access Swagger UI using the REST API section of Veeam ONE Web Client.

From the the Select a definition drop-down list, select the version of the Veeam ONE REST API.

Veeam ONE REST API authorization with Swagger UI involves the following procedures:

1. Obtain a pair of tokens:

   1. On the Veeam ONE REST API page, expand the Authentication tag and click POST /api/token.

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

   3. In the username and password fields, specify the user credentials.

   4. Click Execute.

      Wait for the response from the server. A successfully completed operation returns the 200 Success response code and an access and a refresh token in the response body.

   5. Save the refresh token locally for further use.

   

2. Validate the access token:

   1. At the top right corner of the page, click Authorize.

      The Available authorizations window will open.

   2. In the Value field, provide the access token in the Bearer <access_token> format.

   3. Click Authorize.

   

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

   1. On the Veeam ONE REST API page, expand the Authentication tag and click POST /api/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 refresh token saved locally.

   5. Click Execute.

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

   

4. When you finish working with Veeam ONE REST API:

   1. At the top right corner of the page, click Authorize.

      The Available authorizations window will open.

   2. Click Logout.

After you get and validate an access token, you can send HTTPS requests to Veeam ONE REST API collections and resources in Swagger UI.

To send a request:

1. On the Veeam ONE REST API page, select a tag.
2. In the list of request methods, click the required method.
3. Click Try it out.
4. In the expanded method window, enter parameter values and click Execute.

Swagger UI returns a response body as well as a response code and response headers. Additionally, Swagger UI generates a cURL command and a URL for your request.