Getting Started

Making API Requests

The VMS REST API documentation describes many types of resources and
operations you can call.

To call an operation:

• Send a request to an endpoint formed as:

  https://VMS_VIP/api/VERSION/OBJECT/
  

• Specify one of several methods:

  • POST to create a resource of a given type,

  • PATCH to change one or more properties of a given resource,

  • DELETE to delete a specified resource, or

  • GET to return information about one or more resources.

  Most endpoints can be accessed by several methods. For example, you
  can send a POST request to the /views/ endpoint to create a new
  view, a DELETE request to the same endpoint to delete a view, and so
  on.

The endpoint URL includes:

• VMS_VIP, an IP specific to the cluster for accessing VMS. It's
  provided at cluster installation, and it's the same IP that you use to
  browse to the VAST Web UI.

• VERSION, the VMS API Version. This is optional, but important. If
  not specified, the endpoint is requested from the oldest available
  version of the API (not the latest!). When usage changes from one
  version to the next, the older version number enables you to retain
  the functionality of the former version.

  If the cluster does not support the specified version, an error is
  returned. The following expressions are supported for VERSION:

  v1	Requests the last version of the API endpoint that was introduced up to VAST Cluster release 4.3, even if the cluster is running a later version.
  v2	Specifying v2 requests the latest version of the API endpoint that was introduced up to VAST Cluster release 4.4 and is supported on the cluster.
  v3	Specifying v3 requests the latest version of the API endpoint that was introduced up to VAST Cluster release 4.7 and is supported on the cluster.
  v4	Specifying v4 requests the latest version of the API endpoint that was introduced up to VAST Cluster release 5.0 and is supported on the cluster.
  v5	Specifying v5 requests the latest version of the API endpoint that was introduced up to VAST Cluster release 5.1 and is supported on the cluster.
  v6	Specifying v6 requests the latest version of the API endpoint that was introduced up to VAST Cluster release 5.2 and is supported on the cluster.
  v7	Specifying v7 requests the latest version of the API endpoint that was introduced up to VAST Cluster release 5.3 and is supported on the cluster.
  v8	Specifying v8 requests the latest version of the API endpoint that was introduced up to VAST Cluster release 5.5 and is supported on the cluster.

• OBJECT, an object class such as views, quotas or snapshots.

For example, to explicitly request the version of this endpoint from the
current version API, you would use this URL:

https://VMS_VIP/api/v8/snapshots/

This URL would default to the oldest version of the snapshots API
endpoint:

https://VMS_VIP/api/snapshots/

HTTPS Encryption

The VMS API supports requests only over the HTTPS protocol, the secure
version of the HTTP protocol in which requests and responses are
encrypted.

In the above cURL example, the flag --insecure is used to skip
validation of any SSL certificate that VMS may have. In order to benefit
from the secure aspect of HTTPS, you will need to ensure that VMS has a
valid SSL certificate installed and have your clients validate that
certificate in each request.

If an SSL certificate was not yet installed on VMS, you can use the VAST
Web UI to install such a certificate. VMS will present the installed
certificate to all clients during the SSL handshake that takes place to
establish the HTTPS connection.

Controlling the Response

Pagination of lists of objects that are returned in responses is
controlled by optional query parameters. Best practice is to pass
pagination parameters with any code that accesses any endpoint that
returns a list of objects.

For some endpoints in this version that return lists of objects,
pagination is enforced with a default page size. There are also
endpoints for which pagination is not enforced, but requests that do not
request pagination fail if the response size exceeds a threshold. These
include breaking changes in VMS 5.5. For details, be sure to review
Breaking Changes as well as Enforced Pagination on Selected Endpoints

In addition to pagination, you can also use query parameters to limit
the response to specific fields and to limit the response to a specific
page of a paginated response.

How to Append Query Parameters

Query parameters are appended to the URL of a REST API request. To
append one query parameter, append a ? and then the parameter, and its
value, like this:

?parameter=value

Use an ampersand (&) to separate each subsequent query parameter:

?parameter1=value1&parameter2=value2&parameter3=value3

Query Parameters for Pagination

The following query parameters control pagination:

A paginated response returns the count of results, an indication of
whether there is a next and a previous page in the response, and the
actual results are encapsulated in a results field:

{
count: 15,
next: null,
previous: null,
results: [{id: 4, guid: "588fec4a-aaf7-4296-b43f-4db288469d4e", name: "export-4"}]
},

Without pagination (not recommended), the response is returned in the
plainer format:

[{id: 4, guid: "588fec4a-aaf7-4296-b43f-4db288469d4e", name: "export-4",…

Enforced Pagination on Selected Endpoints

Pagination is enforced, with a default page size of 1000 objects, on the
following endpoints:

• /openfilesqueries

• /openfiles

• /openfilehandles

• /quotagroups/

• /tenants/{id}/metric_label_values

• /tenants/metric_labels/

Endpoints that Cap Page Size Only When Pagination is Requested

The following endpoints, when version 8 is specified, limit the page
size to 1000 objects when page_size is sent with a value greater than
1000. This is version-dependent, per endpoint:

• GET /volumes/ (v8 only)

• GET /blockhosts/ (v8 only)

• GET /blockmappings/ (v8 only)

The following endpoints also limit the page size to 1000 objects when
page_size is sent with a value greater than 1000, only in versions
earlier than version 5:

• GET /userquotas/ (v1-4 only)

• GET /s3lifecyclerules/ (v1-4 only)

• GET /snapshots/  (v2–4 only. On v1, page_size is not capped; an unpaginated list is truncated to 1000 instead.)

Limiting Response by Field

To limit the fields in the response to a specified set, use the fields
query parameter with a comma-separated list of field names that you want
to include in the response.

For example, to return only the name and id fields: fields=name,id

Example

For example, suppose the VMS VIP is 192.0.2.1, and we want to send a
GET request to the /vippools/ endpoint to return information about
VIP pools. We could send the request to:

https://192.0.2.1/api/vippools/

This would return a detailed response with the following fields for each
VIP pool:

[
    {
        "id": 6,
        "guid": "3a9858a9-df03-48bb-81b2-99b97e7ece69",
        "name": "REPLICATION",
        "url": "https://192.0.2.1/api/vippools/6/",
        "title": "172.21.100.180 - 172.21.100.184",
        "start_ip": "172.21.100.180",
        "end_ip": "172.21.100.184",
        "vlan": 0,
        "subnet_cidr": 24,
        "gw_ip": "",
        "cluster": "My Cluster",
        "cluster_id": 1,
        "tenant_id": 1,
        "cnode_ids": [
            1,
            2
        ],
        "cnodes": [
            "cnode-1-21",
            "cnode-1-23"
        ],
        "domain_name": "",
        "role": "REPLICATION",
        "ip_ranges": [
            [
                "172.21.100.180",
                "172.21.100.184"
            ]
        ],
        "ranges_summary": "172.21.100.[180-184]",
        "sync": "SYNCED",
        "sync_time": "2021-06-12T14:20:16.662630Z",
        "vms_preferred": false
    },

Using query parameters, we can limit the response to the name, role,
start IP and end IP of each VIP pool, set the page size to three results
and ask for the second page:

https://192.0.2.1/api/vippools/?fields=name,role,start_ip,end_ip&page=2&page_size=3

Now, we get:

{
    "count": 5,
    "next": null,
    "previous": "https://192.0.2.1/api/vippools/?fields=name%2Crole%2Cstart_ip%2Cend_ip&page_size=3",
    "results": [
        {
            "name": "user_a",
            "start_ip": "172.21.111.20",
            "end_ip": "172.21.111.32",
            "role": "PROTOCOLS"
        },
        {
            "name": "plan_4000",
            "start_ip": "172.66.66.1",
            "end_ip": "172.66.66.200",
            "role": "PROTOCOLS"
        }
    ]
}

Permissions

Requests are authorized according to the permissions of the VMS user
that you use to generate the access token.

VMS controls user permissions using an RBAC (role-based access control)
mechanism. See Managers and
Roles. As a
security best practice, consider having your script authenticate to the
API with the most RBAC-restricted user that can access the range of
functionality that you wish to implement.

Error Response Codes

The VMS API uses conventional HTTP response codes to indicate the
success or failure of an API request.

Authenticating API Requests

Almost all VMS API requests require authentication. The VMS API
supports authentication secured by API tokens over HTTPS. This is
referred to as ApiToken authentication in the reference documentation
per endpoint.

Obtaining an API Token

Creating API tokens requires create permission for the Security RBAC
realm. Tenant admin users can create tokens only for users on the same
tenant.

To create an API token, do one of the following:

• Send a POST request to the /apitokens/ endpoint.

  If you do not have a token (such as the first time you do this, to
  create a token for yourself), you can use basic authentication,
  supplying your own VMS username and password to authenticate the
  request.

  For example:

  curl https://11.22.33.44/api/apitokens/ \
    -X POST -u <user>:<password> --insecure \
    -H "Content-Type: application/json" \
    -d '{"name": "By_Curl_for_admin", "expiry_date": "30D", "owner": "admin"}'
  

  If you are authenticating to a specific tenant, add the
  X-Tenant-Name: <tenant name> header. For example, for user
  tenantadmin1 authenticating to the tenant t1 with password
  mypassword, creating a token for tenant admin user joe on the same
  tenant:

  curl https://11.22.33.44/api/apitokens/ \
    -X POST -u tenantadmin1:mypassword --insecure \
    -H "Content-Type: application/json" \
    -H 'X-Tenant-Name: t1' \
    -d '{"name": "JoeToken", "expiry_date": "60D", "owner": "joe"}'
  

  The following similar example authenticates to the same tenant t1
  using an existing token for the requesting user (see Authenticating a Request with an API Token)
  and creates a token for the tenant admin user joe:

  curl https://11.22.33.44/api/apitokens/ \
  --header 'accept: application/json, text/plain, */*' \
  --header 'Authorization: Api-Token 0MivCn7o.hYveqY36ZMKJhr8VRYyO8UDXCtPVUje7' \
  -d '{"name": "JoeToken", "expiry_date": "60D", "owner": "joe"}'
  

  The response returns the token ID and the token:

  {"id":"0GuvCn7o", "token":"0GuvCn7o.gYertY36ZMKJhr8VRYyO8FGKCqPRUre7"}
  

  The token cannot be retrieved again.

• Connect to the VAST CLI and use the apitoken create VAST CLI
  command.

Authenticating a Request with an API Token

To authenticate each request, send a current valid API token in an
Authorization header with the following format:

Authorization: Api-Token <token>

For example, this call to change the expiration period of an API token
is itself authenticated with an API token in an authentication header:

curl https://<MGMT_VIP>/api/apitokens/0MivCn7o/ \
  -X PATCH --insecure \
  -H "Authorization: Api-Token 0MivCn7o.hYveqY36ZMKJhr8VRYyO8UDXCtPVUje7" \
  -H "Content-Type: application/json" \
  -d '{"name": "Modified_by_rest_with_auth", "expiry_date": "1D"}'

"API token 0MivCn7o has been modified"

More about Working with API Tokens

• The default and maximum expiration period of a token is the password
  expiration period, if enabled. If disabled, tokens do not expire
  unless an expiration date is set. You can change the expiration period
  of a token with a PATCH request to the ~/apitokens/{id}/ endpoint.

  For example:

  curl https://examplevms.com/api/apitokens/swpkos3d/ \
    -X PATCH --insecure \
    -H "AUTHORIZATION: Api-Token swpkos3d.ei9XbTD7vIWpxhnkFT0GF4Hxf2I34KyS" \
    -H "Content-Type: application/json" \
    -d '{"name": "Modified_by_rest_with_auth", "expiry_date": "1D"}'
  
  "API token swpkos3d has been modified"
  

• The default naming convention for API tokens is You can customize this
  in the POST call. You can also change the name with a PATCH request
  to the ~/apitokens/{id}/ endpoint.

• To revoke an API token, send a PATCH request to the
  ~/apitokens/{id}/revoke endpoint, where id is the API token ID.
  (requires delete permission for the Security RBAC realm. )

  For example:

  curl https://examplevms.com/api/apitokens/swpkos3d/revoke \
    -X PATCH --insecure \
    -H "AUTHORIZATION: Api-Token swpkos3d.ei9XbTD7vIWpxhnkFT0GF4Hxf2I34KyS" \
    -H "Content-Type: application/json"
  
  "API token swpkos3d has been revoked"
  

  The API token is archived and becomes invalid.

• To list API tokens, send a GET request to the ~/apitokens/ endpoint.
  It is possible to do this for a revoked token.

  [!NOTE]
  Listing other users' API tokens requires view permission for the
  Security realm.

  For example, listing for a specific owner (userX) and including
  archived (revoked) tokens:

  curl https://examplevms.com/api/apitokens?owner=userX\&archived \
     -X GET --insecure \
     -H "AUTHORIZATION: Api-Token RWDLanfS.9sYRGMD8tbzjhICbU9oeAXKcolsiDIs1" \
     -H "Content-Type: application/json"
  

• To get details of a specific API token by its ID, send a GET request
  to the endpoint. You can choose whether to filter by a specific owner
  and whether to include revoked tokens in the listing. (Listing other
  users' tokens requires view permission to the Security RBAC realm.)

  For example:

  curl https://examplevms.com/api/apitokens/swpkos3d/ \
   -X GET --insecure \
   -H "AUTHORIZATION: Api-Token v3tGcvW2.SnoAXYrNHHpyapAcl84xO6zHeISMROkK" \
   -H "Content-Type: application/json"
  

  Example response:

  {"id":"JlcAkevs",
  "hashed_key":"sha512$$2f04a83e525dc54641a7fbd883040cd927ee277945a3df968f185ce03428049b7b07c5463f86e38b9edb487038007772c4783f1d71a0b53162afb3b3a83a5eae",
  "created":"2025-02-23T14:14:07.194696Z",
  "name":"admin_api_token",
  "revoked":True,
  "expiry_date":"2024-10-15T12:40:41.477484Z",
  "revocation_time":"2025-02-23T14:22:59.971748Z",
  "owner":"admin",
  "last_used":null}
  

• The maximum number of tokens per VMS manager user is five, by default.
  The limit is configurable with a request to the
  /vms/{id}/set_max_api_tokens_per_user endpoint, specifying
  max_api_tokens_per_user.

  For example:

  curl https://examplevms.com/api/vms/1/set_max_api_tokens_per_user \
   -X PATCH \
   -u <user>:<password> \
   --insecure \
   -H "Content-Type: application/json" \ 
   -d '{"max_api_tokens_per_user": 8}' \
  

Using JSON Web Tokens for Authentication

The VMS API supports authentication secured by JSON Web Tokens (JWTs)
over HTTPS.

To establish authentication, your script calls an endpoint via HTTPS to
generate a pair of tokens. The request supplies a VMS user name and
password in the request body. The response returns a pair of tokens: an
access token and a refresh token.

The access token is a digitally encoded signature used to authenticate
requests and authorize access to the requested endpoint. It is designed
to have a minimal lifetime, to ensure minimal time for the requesting
user's identity to be exploited. The refresh token must have a longer
lifetime than the access token. You can use it to request new tokens.
You can then use the new access token to authenticate further requests.

Authenticating Requests with JWT Access Tokens

The VMS API also supports authentication secured by JSON Web Tokens
(JWTs) over HTTPS. To authenticate a request with a JWT access token,
send a current valid access token (<token>) in an authentication
header with the following format:

Authorization: Bearer <token>

For example, the following request to the /dashboard/status endpoint
is authenticated with an access token yJ0eXAiOiJKV1Q...:

curl 'https://192.0.2.1/api/dashboard/status/' \
  -H 'authority: 192.0.2.1' \
  -H 'pragma: no-cache' \
  -H 'cache-control: no-cache' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNjI0ODg2NTA5LCJqdGkiOiI0ODZiZjIwNDVkMjY0ODllODhiZmNiYzhkZTM0Yzk5MCIsInVzZXJfaWQiOjJ9.OPhNseLkVr7uY3Rv5FZ5T4GsOj8bfW4ai-OOPSjIb6Y' \
  -H 'content-type: application/json' \
  -H 'referer: https://192.0.2.1/' \
  --compressed \
  --insecure

Generating Tokens

To generate the initial access token, make a POST request to the api/token/​ endpoint.

You need to pass a VMS username and password as the required body
parameters.

For a new VAST Cluster installation, you can find the default VMS user
credentials here: Managing VAST Cluster
Passwords.
If user credentials have been changed via VMS GUI or CLI, you'll need to
supply an existing set of user credentials. Requests will be authorized
according to the requesting user's VMS permissions.

The response returns two tokens:

• The access token to use for authentication on protected API endpoints.

• The refresh token, which you can use to obtain a new access token and
  refresh token.

cURL Example

Using cURL, with ABC resolving to your cluster's VMS VIP, your user
name is admin and the password for admin is XXXXYX:

curl 'https://192.0.2.1/api/token/' \
  -H 'authority: 192.0.2.1' \
  -H 'pragma: no-cache' \
  -H 'cache-control: no-cache' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'content-type: application/json' \
  -H 'origin: https://192.0.2.1' \
  -H 'referer: https://192.0.2.1/' \
  -H 'accept-language: en-US,en;q=0.9,he;q=0.8' \
  --data-binary '{"username":"admin","password":"XXXXYX"}' \
  --compressed \
  --insecure

Using the Token in a Request

To authenticate each request, send a current access token in an
authentication header in the following format:

Authorization: Bearer <token>

See also Making API Requests for more details about making requests.

Keeping Tokens Valid

If the access token expires while the refresh token is still valid, the
refresh token can be used to generate new tokens without supplying the
VMS user credentials. If the refresh token expires, requests require
re-authentication with the VMS user credentials.

In order to avoid the need to re-authenticate with a VMS user, your
script needs to refresh the tokens periodically, at least once in the
lifespan of each refresh token. Since the access token has a shorter
lifespan, refresh is also needed more frequently in order to continue
making requests.

One suggestion is to send a refresh request on receiving a 401 failed
request error and retrying the request with the newly returned access
token.

The token lifespans are configurable with the following defaults:

• The access token has a default lifespan of 1 h.

• The refresh token has a default lifespan of 24 h

Refreshing Tokens

To refresh the tokens, make a POST request to ​api/token/refresh. Pass
the last refresh token returned by the last refresh request as
data.

The response is a new access token and a new refresh token. Save them and use
the new access token to access API endpoints, and the new refresh token
to refresh tokens again.

cURL example:

curl 'https://192.0.2.1/api/token/refresh/' \
  -H 'authority: 192.0.2.1' \
  -H 'pragma: no-cache' \
  -H 'cache-control: no-cache' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'content-type: application/json' \
  -H 'origin: https://192.0.2.1' \
  -H 'referer: https://192.0.2.1/' \
  -H 'accept-language: en-US,en;q=0.9,he;q=0.8' \
  --data-binary ‘{“refresh”:“eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTYyNDk2OTMwOSwianRpIjoiZGVhNzlkOTI1ZjBmNDQyNTg4MDgyMTg4ZDZlZjY2OTUiLCJ1c2VyX2lkIjoyfQ.gTOhjyfGsN7ebBgEiPa94_rjESUFGCEvFMObAkisyDI”}’ \
  --compressed \
  --insecure

Changing the Token Life Spans

To change the lifespans for access tokens and refresh tokens, send a
PATCH request to the /vms/{id}/ endpoint. For the access token
lifetime, pass the access_token_lifetime parameter. For the refresh
token lifetime, pass the refresh_token_lifetime parameter.

mTLS Client Certificate Validation

VMS can be configured to require clients invoking the VMS REST API to
present a client certificate. The requirement applies to any client
connections used to make REST API calls to the VMS, including those used
for accessing the VAST Web UI.

To configure client certificate validation for VMS REST API calls,
obtain a CA certificate (and a key) and upload it to VMS as the VMS mTLS
certificate. You can do this through the VMS REST API by sending a PATCH
request to the /vms/{id}/set_client_certificate/ endpoint. After the
VMS mTLS certificate is uploaded, the clients are expected to present
the same certificate as the one uploaded to the VMS, or a certificate
signed by the uploaded root certificate.