Frame Admin API

Introduction

The Frame Admin API service is based on standard REST HTTPS calls. All API endpoints require signed authentication via HTTP headers.

The typical workflow for an API call is as follows:

  1. Authenticate with the Frame REST API to sign the HTTPS API request. You’ll need to create a signature with the client_id, the client_secret, and a timestamp. The client_id and client_secret can be acquired by any Admin on Frame.

  2. Make the HTTPS REST call to the Admin API endpoint using the client_id, timestamp, and the signature in the HTTP header (Created in step 1a).

  3. The Frame REST API verifies the signature of the HTTPS request and will then send the response of the previous call.

Getting Started

Your Frame Admin API endpoint will be unique to your environment and in the following format:

https://api.[frame-environment-domain].com/v1

For Frame’s public environment, this URI is:

https://api.console.nutanix.com/v1

In the next section, we will review how to properly authenticate to be able to use the Frame Admin API.

API Authentication

All REST API calls require authentication for each 3rd party service (individual users are not currently supported) and all API calls require signed requests for authentication.

Each API request must be signed and include the necessary information for proper signature verification. To sign an API request call, a client_id and client_secret are required to generate a signature and are also used for signature verification.

How to Provision API Credentials

  1. Navigate to the admin view of your Frame account.

  2. Locate the desired Account/Organization/Customer entity using the menu on the left. Click ellipsis listed to the right of the entity name and click “Users.”

../_images/generic_usersnav1.png
  1. Enable the “API” option and click “Save.” This will create a new tab entitled “API.”

    ../_images/overview_1.png
  2. Go to the newly created API Authorizations tab and click “Add API.”

    ../_images/overview_2.png
  3. Enter a name for the API Authorization and choose the role(s) you would like to grant the API key at the bottom. Roles determine the permission level of the API. Click “Add.”

    ../_images/overview_3.png
  4. Click the ellipsis next to the API Authorization you just created and select “Manage.”

    ../_images/overview_4.png
  5. Name the API Key and then click the plus symbol to create it.

    ../_images/overview_5.png
  6. Record the client_Id and client_Secret to be used by your API calls.

    Warning

    Make sure to record this information, as it will only appear once. You will not be able to retrieve these details again.

    ../_images/overview_6.png

How to Make API Calls

In the last section, you generated a client_id and a client_secret.

The client_id is a unique string that Frame’s Admin API uses for client/service identification. It is used by the authentication system to identify the proper account and API client permissions.

The client_secret is an HMAC-SHA256 key used to generate the signature and is required by the signature verification process.

A signature is created by applying the HMAC-SHA256 algorithm to a string that is constructed from the client_id and a timestamp. The timestamp is the current time in seconds since epoch.

The proper steps for creating a signature are as follows:

  1. Get the current timestamp.

  2. Create a string by concatenating the timestamp with the client_id (timestamp + client_id).

  3. Apply HMAC-SHA256 on the newly created string using the client_secret

In order to verify the signature, our API requires the newly created signature, the client_id, and the timestamp. The client_secret should NOT be included. This information should be sent in the HTTP request headers.

Below is a simple example of a Python 3 script that can be used to generate the signature needed for the API call and then the HTTPS request.

#!/bin/env python

import hashlib
import hmac
import time
import requests
import base64

# Client credentials
client_id = "<Your API Client ID goes here>"
client_secret = b"<Your API Client Secret goes here>"

# Create signature
timestamp = int(time.time())
to_sign = "%s%s" % (timestamp, client_id)
signature = hmac.new(client_secret, to_sign.encode('utf-8'), hashlib.sha256).hexdigest()

# Prepare http request headers
headers = { "X-Frame-ClientId": client_id, "X-Frame-Timestamp": str(timestamp), "X-Frame-Signature": signature }

# Make request
r = requests.get("https://api.console.nutanix.com/v1/accounts", headers=headers)
accounts = r.json()

# Print accounts
for account in accounts:
  print account

List Accounts

Lists all accounts for a user, based on the user token.

GET /accounts/${id}

Request Parameters

Name

Description

Param Type

Data Type

Required

name

Name or portion of name you would like to use for searching/filtering

query

string

false

id

Frame Account ID

URL

string

False

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts"

Response Example

Status: 200 OK
[
  {
    "website": null,
    "name": "Aca Ivic Local",
    "last_publish": "2018-07-12T11:26:18.879116",
    "id": "b614cb6f-796b-4371-86cb-465d6dfc433b",
    "description": null,
    "active": true
  }
]

Get Account Details

Returns details of an account.

GET /accounts/${id}

Request Parameters

Name

Description

Param Type

Data Type

Required

id

Frame Account ID

URL

String

True

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/31cbf42c-8767-486c-9ed3-d6a804q7cfe1"

Response Example

Status: 200 OK
{
  "active": false,
  "description": null,
  "id": "31cbf42c-8767-486c-9ed3-d6a804q7cfe1",
  "inserted_at": "2020-02-27T19:08:53.892063Z",
  "kind": "frame",
  "last_publish": null,
  "name": "Example Account",
  "notes": null,
  "url_slug": "example-account-slug",
  "website": null
}

Publish a Sandbox

Starts the publish action for an account’s Sandbox and returns the task ID.

POST /accounts/${id}/publish

Request Parameters

Parameter

Description

Param Type

Data Type

Required

id

Frame Account ID

URL

String

True

Request Example

curl -X POST \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${id}/publish"

Response Example

Status: 200 OK
{
  "task": {
    "id": "0c956d69-9700-4e80-b1ee-5179f5b5a3de"
  }
}

List Publish Tasks

Lists publishing tasks for the given account ID.

GET /accounts/${id}/publish/tasks

Request Parameters

Parameter

Description

Param Type

Data Type

Required

id

Frame Account ID

URL

String

True

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${id}/publish/tasks"

Response Example

Status: 200 OK
[
  {
    "status": "provisioning",
    "number_of_instances": 1,
    "last_change": "2018-07-25T04:30:09",
    "id": 391
  }
]

Get Publish Status

Returns the publishing status for a given account ID and publish request ID.

GET /accounts/${id}/publish/${request_id}

Request Parameters

Parameter

Description

Param Type

Data Type

Required

id

Frame Account ID

URL

String

True

request_id

Request the ID of a publish

URL

String

True

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${id}/publish/${request_id}"

Response Example

Status: 200 OK
{
  "status": "in_progress",
  "id": "793db0f3-31f7-4cc1-8cd5-741c80407aba"
}

Cancel Publish

Cancels a publishing request for the given account ID and publish request ID.

DELETE /accounts/${id}/publish/${request_id}

Request Parameters

Parameter

Description

Param Type

Data Type

Required

id

Frame Account ID

URL

String

True

request_id

Request the ID of a publish

URL

String

True

Request Example

curl -X DELETE \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${id}/publish/${request_id}"

Response Example

Status: 202 Accepted
{}

List Applications

Returns a list of applications for the account specified.

GET /accounts/${id}/applications

Request Parameters

Parameter

Description

Param Type

Data Type

Required

id

Frame Account ID

URL

String

True

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${id}/applications"

Response Example

Status: 200 OK
[
  {
    "working_directory": null,
    "path": "C:\\Program Files\\Frame\\FrameExplorer\\FrameExplorer.exe",
    "name": "Frame Explorer",
    "is_updated": false,
    "is_published": true,
    "is_deleted": false,
    "id": "909b74cc-d207-47ed-bd25-2b8088c36912",
    "icon_url": "https://next-cpanel-dev.s3.amazonaws.com/images/apps/frame_explorer.png",
    "arguments": null
  },
  {
    "working_directory": null,
    "path": "C:\\Program Files(x86)\\Google\\Chrome\\Application\\chrome.exe",
    "name": "Google Chrome",
    "is_updated": false,
    "is_published": true,
    "is_deleted": false,
    "id": "e288cac6-87c6-4dcf-bd19-5287f571e774",
    "icon_url": "https://next-cpanel-dev.s3.amazonaws.com/images/apps/google_chrome.png",
    "arguments": null
  },
  {
    "working_directory": null,
    "path": "C:\\Windows\\system32\\notepad.exe",
    "name": "Notepad",
    "is_updated": false,
    "is_published": true,
    "is_deleted": false,
    "id": "547e2eeb-7d6c-4ec8-976e-d0677f23322b",
    "icon_url": "https://next-cpanel-dev.s3.amazonaws.com/images/apps/notepad.png",
    "arguments": null
  }
]

List Session Reports

Returns a list of generated session reports.

GET /accounts/${id}/session_reports

Request Parameters

Parameter

Description

Param Type

Data Type

Required

id

Frame Account ID

URL

String

True

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${id}/session_reports"

Response Example

Status: 200 OK
[
  {
    "year": 2018,
    "url": "https://s3-datest.dev.fra.me/datest-session-reports/datest/9rnKxGPdbozby6YA.2018.7.4311c.31.csv.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Credential=QazWsxEdc777%2F20180724%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Date=20180724T101921Z&X-Amz-Signature=b77249805c20ddd45d2c38ffed5af6284ee34c57defb33f46911c10ace82dccf",
    "month": 7
  }
]

List Active Sessions

Returns a list of active sessions for all pools on a specified account.

GET /accounts/${id}/active_sessions

Request Parameters

Parameter

Description

Param Type

Data Type

Required

id

Frame Account ID

URL

String

True

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${id}/active_sessions"

Response Example

Status: 200 OK
[
  {
    "wait_for_instance": false,
    "user_uuid": "00b09249-910f-42f6-9190-7a980a16735b",
    "state": "open",
    "start_time": 1532435960,
    "server_ws_port": "443",
    "server_address": "datest-18-185-108-165.dev.fra.me",
    "pool_id": "gw-prod.7116",
    "location_distance": -1,
    "location_country": null,
    "location_city": null,
    "is_https_connection": true,
    "instance_status": null,
    "id": "gw-prod.xjVbYREPlvZWpvPE",
    "gateway": "gw-prod"
  }
]

List Recent Sessions

Returns a list of sessions for a given period of time.

GET /accounts/${id}/recent_sessions

Request Parameters

Parameter

Description

Param Type

Data Type

Required

id

Frame Account ID

URL

String

True

from_date

Defaults to today, format YYYY-MM-DD

URL

String

False

to_date

Defaults to today, format YYYY-MM-DD

URL

String

False

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${id}/recent_sessions?from_date=2018-01-01&to_date=2018-08-17"

Response Example

Status: 200 OK
[
  {
    "user_uuid": "00b09249-910f-42f6-9190-7a980a16735b",
    "timeouts": {
      "max_duration": 3600,
      "idle": 600,
      "connection": 120
    },
    "state": "failed",
    "start_time": "2018-07-24T03:27:24",
    "session_duration": 3693,
    "server": {
      "wsport": null,
      "pool_group_type": "sandbox",
      "instance_type": null,
      "https": true,
      "address": null
    },
    "location": {
      "distance": -1,
      "country": "",
      "client_ip": "127.0.0.1",
      "city": ""
    },
    "id": "gw-prod.6qn85Z86pk4Pdzla",
    "hash_id": "gkb67zxLRgzAOK4j",
    "end_time": null
  }
]

Get Session

Returns information regarding a specific session.

GET /accounts/${account_id}/sessions/${session_id}

Request Parameters

Parameter

Description

Param Type

Data Type

Required

account_id

Frame Account ID

URL

String

True

session_id

ID of a session

URL

String

True

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${account_id}/sessions/${session_id}"

Response Example

Status: 200 OK
{
  "wait_for_instance": false,
  "user_uuid": "00b09249-910f-42f6-9190-7a980a16735b",
  "state": "failed",
  "start_time": 1532428044,
  "server_ws_port": null,
  "server_address": null,
  "pool_id": "gw-prod.6526",
  "location_distance": -1,
  "location_country": null,
  "location_city": null,
  "is_https_connection": true,
  "instance_status": null,
  "id": "gw-prod.6qn85Z86pk4Pdzla",
  "gateway": "gw-prod"
}

Stop a Session

Stops the specified session.

DELETE /accounts/${account_id}/sessions/${session_id}

Request Parameters

Parameter

Description

Param Type

Data Type

Required

account_id

Frame Account ID

URL

String

True

session_id

ID of a session

URL

String

True

Request Example

curl -X DELETE \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${account_id}/sessions/${session_id}"

Response Example

Status: 200 OK
{
  "wait_for_instance": false,
  "user_uuid": "00b09249-910f-42f6-9190-7a980a16735b",
  "state": "open",
  "start_time": 1532428044,
  "session_request_url": null,
  "server_ws_port": null,
  "server_address": null,
  "pool_id": "gw-prod.6526",
  "location_distance": -1,
  "location_country": null,
  "location_city": null,
  "is_https_connection": true,
  "instance_status": null,
  "id": "gw-prod.6qn85Z86pk4Pdzla",
  "gw_id": 4196,
  "gateway": "gw-prod",
  "cancel_request_url": null,
  "automation_request_id": null
}

Get Sandbox Status

Returns the status of a Sandbox pool on a specified account.

GET /accounts/:id/sandbox/status

Request Parameters

Parameter

Description

Param Type

Data Type

Required

id

Frame Account ID

URL

String

True

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${id}/sandbox/status"

Response Example

Status: 200 OK
{
  "user_sessions": {},
  "status": "server_available",
  "running_servers": 0,
  "pool_type": null,
  "pool_group_id": 6449,
  "min_servers": 0,
  "max_servers": 1,
  "maintenance": "none",
  "instance_type": 2,
  "id": "gw-prod.7116",
  "gateway": "gw-prod",
  "buffer_servers": 0,
  "available_servers": 0,
  "active_servers": -3
}

Start a Sandbox

Starts the Sandbox server on a specified account.

POST /accounts/${id}/sandbox/start

Request Parameters

Parameter

Description

Param Type

Data Type

Required

id

Frame Account ID

URL

String

True

Request Example

curl -X POST \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${id}/sandbox/start"

Response Example

Status: 202 Accepted
{}

Stop a Sandbox

Stops the Sandbox server on specified account.

POST /accounts/${id}/sandbox/stop

Request Parameters

Parameter

Description

Param Type

Data Type

Required

id

Frame Account ID

URL

String

True

Request Example

curl -X POST \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${id}/sandbox/stop"

Response Example

Status: 202 Accepted
{}

Reboot a Sandbox

Reboots the Sandbox server on a specified account.

POST /accounts/${id}/sandbox/reboot

Request Parameters

Parameter

Description

Param Type

Data Type

Required

id

Frame Account ID

URL

String

True

Request Example

curl -X POST \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${id}/sandbox/reboot"

Response Example

Status: 200 OK
{
  "server": {
    "ssd": true,
    "private_ip": "10.0.34.88",
    "status": "rebooting",
    "debug": false,
    "name": "Coa Local 1 - 239259",
    "reserved": -1,
    "fault": 0,
    "last_change": "2018-07-25T03:19:08",
    "logging": false,
    "resources_allocated": true,
    "active": false,
    "spot_instance": false,
    "problem": false,
    "maintenance": false,
    "machine_name": "ip-0A002258",
    "local_ip": "18.185.108.165",
    "zone": "eu-central-1b",
    "recovery": false,
    "desired_status": "running",
    "datacenter": 6,
    "has_runs": true,
    "local_wsport": "443",
    "pending_upgrades": 0,
    "domain_joined": false,
    "instance_type": 2,
    "launch_time": "2018-07-24T12:30:08",
    "in_use": false,
    "upgrade_version": 100017,
    "public_port": "8112",
    "creation_time": "2018-07-24T05:30:07",
    "pending_upgrades_with_reboot": 0,
    "aws_instance_id": "i-0008e108ce39940dd",
    "id": 239259
  },
  "task": {
    "id": "439f177b-d89f-4f6a-904f-97f13948e457"
  }
}

List Pools for an Account

Returns all workload pools for an account.

GET /accounts/${account_id}/pools

Request Parameters

Name

Description

Param Type

Data Type

Required

id

Frame Account ID.

URL

string

false

kind

Used to filter pools based on their kind: sandbox, production, utility, and shadow.

query

string

false

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${account_id}/pools"

Response Example

Status: 200 OK
[
  {
      "disk_size": 45,
      "external_id": "gateway-prod.#####",
      "id": "cd5e5067-3f20-49eb-803b-9564eeba7791",
      "image_family": "Frame-AWS-WindowsServer2019-G4",
      "instance_type": "t2.medium",
      "kind": "production",
      "name": "Air 4GB"
  },
  {
      "disk_size": 45,
      "external_id": "gateway-prod.#####",
      "id": "cba63a88-4dad-4725-81b0-d492a6427b00",
      "image_family": "Frame-AWS-WindowsServer2019-G4",
      "instance_type": "t2.medium",
      "kind": "sandbox",
      "name": "sandbox pool"
  }
]

Get Account’s Overall Capacity Settings

Returns the current min, buffer, and max values configured for all pools/instance types in an account.

GET /accounts/${id}/elasticity

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${account_id}/elasticity"

Response Example

Status: 200 OK
{
  "min_servers": 75,
  "buffer_servers": 20,
  "max_servers": 475,
}

Get Production Pool Capacity Settings

Returns the current min, buffer, and max values configured for a specific pool.

GET /pools/${pool_id}/elasticity_settings

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/pools/${pool_id}/elasticity_settings"

Response Example

Status: 200 OK
{
  "min_servers": 15,
  "buffer_servers": 2,
  "max_servers": 100,
}

Set Production Pool Capacity Settings

Sets new min, buffer, or max values for a specific production pool. Frame immediately sets new values and orchestrates workloads to match these settings. You can the status of this operation using the returned task ID.

Warning

Practice caution and make sure you understand the meanings of minimum, buffer, and maximum server elasticity values before setting them via API. Incorrectly setting these values can be expensive in regards to infrastructure costs and resources.

Please allow these tasks to complete (DONE status) before making another request for the same pool.

POST /pools/${pool_id}/elasticity_settings

Request Parameters

Set Capacity/Elasticity settings Request Parameters

Parameter

Description

Param Type

Data Type

Required

min_servers

Minimum servers value for a production pool

Form Data

String

False

buffer_servers

Buffer servers value for a production pool

Form Data

String

False

max_servers

Maximum server capacity value for a production pool

Form Data

String

True

For more information, reference our documentation about elasticity settings.

Request Example

curl -X POST \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/pools/${pool_id}/elasticity_settings" \
-F min_servers=5 \
-F buffer_servers=0 \
-F max_servers=80 \

Response Example

Status: 200 OK
{
  "account_id": "XXXXXXXX-09cf-44d9-a386-XXXXXXXXXXX",
  "customer_id": "XXXXXXXX-5ab2-47df-9f9c-XXXXXXXXXXX",
  "display_name": "Updating elasticity for Air 4GB",
  "duration_sec": null,
  "external_resource_id": null,
  "finished_at": null,
  "id": "0bf720c4-7729-48aa-95a8-470211aea40f",
  "inserted_at": "2021-08-05T17:50:32.106790Z",
  "kind": "update_pool_elasticity_settings",
  "organization_id": "82ccea89-389f-496a-9c75-XXXXXXXXXXX",
  "pool_id": "cd5e4467-3f20-49eb-803b-9514eeab7711",
  "progress_info": null,
  "result_info": null,
  "stage": "not_started",
  "started_by": {
      "email": "XXXXXXXXXXX.img.frame.nutanix.com_third-party-api",
      "first_name": "X",
      "id": "XXXXXXXX-2f74-4dad-8e55-XXXXXXXXXXX",
      "identity_provider": "third-party-api",
      "last_name": "X"
  },
  "updated_at": "2021-08-05T17:50:32.106790Z"
}

List Servers for an Account

Returns all workload servers for an account.

GET /accounts/${account_id}/servers

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${account_id}/servers"

Response Example

Status: 200 OK
[
  {
    "active": false,
    "cloud_instance_id": "i-04198255723b27d69",
    "creation_time": "2021-07-20 21:22:49.287276Z",
    "debug": false,
    "desired_status": "stopped",
    "domain_joined": false,
    "external_id": "gateway-prod.575XXXX",
    "id": 575XXXX,
    "in_use": false,
    "instance_type_name": "t2.medium",
    "last_change": "2021-08-04 21:13:57.243020Z",
    "launch_time": null,
    "machine_name": "IF-F89A27E05E86",
    "machine_status": null,
    "maintenance": false,
    "name": "Lenticular Cloud Project - 575XXXX",
    "pool_external_id": "gateway-prod.520XXX",
    "pool_name": "sandbox",
    "private_ip": "10.0.4.145",
    "problem": false,
    "public_hostname": null,
    "public_wsport": 443,
    "recovery": false,
    "reserved": -1,
    "server_ip": null,
    "server_version": null,
    "status": "stopped",
    "upgrade_version": 0,
    "user_in_session": null,
    "zone": "us-west-1a"
  },
  // ...
]

Clone Sandbox

This endpoint will clone a Sandbox image from one account to the specified target account. The target account and source account must belong to the same Cloud Provider (e.g. clone from AWS to AWS, GCP to GCP, Azure to Azure). You can check the status of this operation using the returned task ID.

Warning

This process will overwrite the Sandbox image for the target account which means all existing data will be lost. Be sure to perform a backup before continuing.

POST /accounts/${target_account_id}/pools/${source_pool_id}/clone

Request Parameters

Parameter

Description

Param Type

Data Type

Required

target_account_id

This is the target account ID

URL

String

True

source_pool_id

The source account’s Sandbox pool ID

URL

String

True

join_domain

Optional. Can be true or false. Determines whether Frame should attempt to join the domain after the Sandbox has been cloned.

Query

String

False

Request Example

curl -X POST \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${id}/pools/${source_pool_id}/clone"
-F join_domain=false

Response Example

Status: 200 OK
{
  "account": {
    "active": true,
    "description": null,
    "id": "XXXXXXXX-32ef-4ea9-a896-XXXXXXXXXXX",
    "inserted_at": "2021-07-28T20:48:09.614305Z",
    "kind": "frame",
    "last_publish": null,
    "name": "API Clone Tutorial",
    "notes": null,
    "url_slug": "api-clone-tutorial",
    "website": null
  },
  "pending_request": {
    "account_id": "XXXXXXXX-32ef-4ea9-a896-XXXXXXXXXXX",
    "customer_id": "XXXXXXXX-5ab2-47ef-9f9c-XXXXXXXXXXX",
    "display_name": "Cloning system",
    "duration_sec": null,
    "external_resource_id": null,
    "finished_at": null,
    "id": "e7e44ecb-5e8c-342d-8c23-b190b1004e31",
    "inserted_at": "2021-08-05T18:17:20.692055Z",
    "kind": "clone_pool",
    "organization_id": "XXXXXXXX-389f-496a-9c75-XXXXXXXXXXX",
    "pool_id": "cce63a88-4dad-4725-81b0-d492a6427b00",
    "progress_info": null,
    "result_info": null,
    "stage": "not_started",
    "started_by": {
      "email": "XXXXXXXX-3bee-405f-8c28-XXXXXXXXXXX.img.frame.nutanix.com_third-party-api",
      "first_name": "X",
      "id": "XXXXXXXX-2f74-4dad-8e55-XXXXXXXXXXX",
      "identity_provider": "third-party-api",
      "last_name": "X"
    },
    "updated_at": "2021-08-05T18:17:20.692055Z"
  }
}

Get the Status of a Task

Returns the current status of a task ID.

GET /accounts/${id}/task/${task_id}

Request Parameters

Parameter

Description

Param Type

Data Type

Required

id

Frame Account ID

URL

String

True

task_id

Frame Task ID

URL

String

True

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${id}/task/${task_id}"

Response Example

Status: 200 OK
{
  "account_id": "XXXXXXXX-09cf-44d9-a386-XXXXXXXXXXX",
  "customer_id": "XXXXXXXX-5ab2-47ef-9f9c-XXXXXXXXXXX",
  "display_name": "Publishing Sandbox to Production",
  "duration_sec": 1530,
  "external_resource_id": null,
  "finished_at": "2021-07-20T22:16:31.680241Z",
  "id": "57643caa-1700-4938-b6cc-94b8dd5fa7df",
  "inserted_at": "2021-07-20T21:51:01.481733Z",
  "kind": "publish_sandbox_to_production",
  "organization_id": "86ccea89-389f-496a-9c75-5df0ce8d96ce",
  "pool_id": null,
  "progress_info": null,
  "result_info": null,
  "stage": "done",
  "started_by": {
    "email": "68f43670-3bee-405f-8c28-cc5baf354e5f.img.frame.nutanix.com_third-party-api",
    "first_name": "X",
    "id": "d15d3125-2f74-45b2-8e55-1574de5e2b6a",
    "identity_provider": "third-party-api",
    "last_name": "X"
  },
  "updated_at": "2021-07-20T22:16:31.681266Z"
}

Get Account Usage

Returns usage information for an account within a specified time period.

GET /accounts/${id}/usage

Request Parameters

Parameter

Description

Param Type

Data Type

Required

id

Frame Account ID

URL

String

True

from_date

Defaults to today, format YYYY-MM-DD

URL

String

True

to_date

Defaults to today, format YYYY-MM-DD

URL

String

True

resolution_type

Defaults to by_hour, options: by_hour, by_day, by_month, by_year

Header

String

False

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
-H "resolution_type: by_day" \
"https://api.console.nutanix.com/v1/accounts/${id}/usage?from_date=2018-01-01&to_date=2018-08-20"

Response Example

Status: 200 OK
{
  "usage_data": {
    "vendor_id": 1338,
    "usage": [
      {
        "time": 1532217600000,
        "server_type_id": "sandbox",
        "instance_type": {
          "name": "t2.medium",
          "id": 4
        },
        "hours_used": 1,
        "datacenter": {
          "name": "aws-de",
          "id": 6,
          "geo_long": 8.683333,
          "geo_lat": 50.116667
        }
      },
      {
        "time": 1532253600000,
        "server_type_id": "sandbox",
        "instance_type": {
          "name": "t2.medium",
          "id": 4
        },
        "hours_used": 1,
        "datacenter": {
          "name": "aws-de",
          "id": 6,
          "geo_long": 8.683333,
          "geo_lat": 50.116667
        }
      }
    ],
    "gateway_id": "gateway-web-datest.dev.fra.me"
  },
  "status_message": "Success.",
  "status": 0,
  "resolution": "by_hour",
  "credited_data": {
    "vendor_id": 1338,
    "gateway_id": "gateway-web-datest.dev.fra.me",
    "credit": [
      {
        "time": 1532253600000,
        "server_type_id": null,
        "instance_type": {
          "name": "t2.medium",
          "id": 4
        },
        "datacenter": {
          "name": "aws-de",
          "id": 6,
          "geo_long": 8.683333,
          "geo_lat": 50.116667
        },
        "credited_hours": 2
      }
    ]
  }
}

Get Disk Volume Usage

Returns the disk volume usage for a specified account in a specified time period.

GET /accounts/${id}/disk_volume_usage?from_date=${from_date}&to_date=${to_date}&resolution_type=${resolution_type}

Request Parameters

Parameter

Description

Param Type

Data Type

Required

id

Frame Account ID

URL

String

True

from_date

Format YYYY-MM-DD

URL Param

String

True

to_date

Format YYYY-MM-DD

URL Param

String

True

resolution_type

Defaults to by_hour, options: by_hour, by_day, by_month, by_year

URL Param

String

False

Request Example

curl -X GET \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${id}/disk_volume_usage?from_date=2020-01-01&to_date=2020-06-30&resolution_type=by_month"

Response Example

Status: 200 OK
{
  "data": [
    {
      "account_external_id": "gateway-prod.1337",
      "usage": [
        {
          "datacenter_id": "gateway-prod.3",
          "hours_used": 1488,
          "disk_volume_size_used": 223200,
          "disk_volume_type_id": "gp2",
          "time": 1577836800000
        },
        {
          "datacenter_id": "gateway-prod.3",
          "hours_used": 1392,
          "disk_volume_size_used": 208800,
          "disk_volume_type_id": "gp2",
          "time": 1580515200000
        },
        {
          "datacenter_id": "gateway-prod.3",
          "hours_used": 1488,
          "disk_volume_size_used": 223200,
          "disk_volume_type_id": "gp2",
          "time": 1583020800000
        },
        {
          "datacenter_id": "gateway-prod.3",
          "hours_used": 1443,
          "disk_volume_size_used": 247779,
          "disk_volume_type_id": "gp2",
          "time": 1585699200000
        },
        {
          "datacenter_id": "gateway-prod.3",
          "hours_used": 1539,
          "disk_volume_size_used": 299343,
          "disk_volume_type_id": "gp2",
          "time": 1588291200000
        },
        {
          "datacenter_id": "gateway-prod.3",
          "hours_used": 2344,
          "disk_volume_size_used": 295136,
          "disk_volume_type_id": "gp2",
          "time": 1590969600000
        },
        {
          "datacenter_id": "gateway-prod.3",
          "hours_used": 10311,
          "disk_volume_size_used": 334187,
          "disk_volume_type_id": "gp2",
          "time": 1593561600000
        }
      ]
    }
  ],
  "total": 1831645
}

Get API Authorization Rules

Returns authorization rules for the account, organization, and customers, respectively.

GET /accounts/${id}/api_authorization_rules
GET /organizations/${id}/api_authorization_rules
GET /customers/${id}/api_authorization_rules

Request Parameters

Parameter

Description

Param Type

Data Type

Required

id

Frame Account ID

URL

String

True

Request Example

curl -X POST \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${id}/api_authorization_rules"

Response Example

Status: 200 OK
[
  {
    "roles": [
      {
        "role": {
          "permissions": [
            "..."
          ],
          "name": "Account Administrator",
          "description": null,
          "applicable_on": "account"
        },
        "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
      }
    ],
    "name": "example2",
    "id": 8,
    "credentials": [
      {
        "name": "example2_key",
        "client_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.img-external-api-nfstg.frame-publicsector.com"
      }
    ],
    "api_authorization_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  },
  {
    "roles": [
      {
        "role": {
          "permissions": [
            "..."
          ],
          "name": "Account Administrator",
          "description": null,
          "applicable_on": "account"
        },
        "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
      }
    ],
    "name": "example",
    "id": 7,
    "credentials": [
      {
        "name": "example_key",
        "client_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.img-external-api-nfstg.frame-publicsector.com"
      }
    ],
    "api_authorization_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  }
]

Create an Account

Accounts can be created within an organization with the following endpoint and parameters. Initiating an account creation will give you a task_id. You can check the status of the account creation via the task id.

Creating an account via our API requires a few parameters that are difficult to obtain: cloud_service_external_id, data_center_external_id, image_family, disk_size, and sandbox_instance_type_id. Please reach out to your Nutanix representative to gather these parameters for you.

POST /accounts/

Request Parameters

Create Account Request Parameters

Parameter

Description

Param Type

Data Type

Required

organization_id

ID of the Org the account will be created under

Data

String

True

name

Name of the new account

Data

String

True

url_slug

A URL-friendly slug that will be used in URLs to access the account

Data

String

True

cloud_service_external_id

This represents which cloud service the account will be created with

Data

String

True

data_center_external_id

This is the ID of a datacenter or “region” that will be used for the account

Data

String

True

sandbox_instance_type_id

This ID is used to specify the instance type of the sandbox

Data

String

True

image_family

This references the name of an OS image that is supported by Frame

Data

String

True

disk_size

Optional. Desired size of the sandbox image (in GiB). If this value is not provided, our system uses a default of 45 GiB. However, some operating systems images have different disk size requirements (e.g. Windows 2016 on AWS has a minimum of 64 GiB)

Data

String

False

Request Example

curl -X POST \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/"
-F organization_id=d63caa09-5723-4ab9-a1ea-6659b349aabe \
-F 'name=API Example Account on AWS' \
-F url_slug=example-account \
-F cloud_service_external_id=gw-prod.55 \
-F data_center_external_id=gw-prod.15 \
-F image_family=FrameAWSWindows2016 \
-F sandbox_instance_type_id=gw-prod.33 \
-F disk_size=64

Response Example

Status: 200 OK
{
  "account": {
    "id": "c4d7b4ed-c342-400b-3503-76de4fffa833",
    "name": "API Example Account on AWS",
    "website": null,
    "description": null,
    "active": false,
    "last_publish": null
  },
  "task": {
    "id": "466414c9-071c-4822-842d-854a6137a821"
  }
}

Create an Account Launchpad

Launchpads can be created within an account with the following endpoint and parameters:

POST /accounts/${id}/launchpad

Request Parameters

Create Launchpad request parameters

Parameter

Description

Param Type

Data Type

Required

account_id

ID of the account the Launchpad will be created under.

URL

String

True

name

Name of the new Launchpad.

Data

String

True

url_slug

A URL-friendly slug that will be used in URLs to access the Launchpad

Data

String

True

kind

This determines the kind of Launchpad you want to create. You can create two kinds: application and desktop

Data

String

True

Note

Creating “application” Launchpads via API would require you to install and onboard your own applications manually in the Sandbox to add applications to the account which doesn’t really make sense. After applications are added, they can be easily toggled on/off for a Launchpad via our Dashboard UI. This process via API would be overly complicated. If you need to automate application workflows, please reach out to your Nutanix representative to discuss this with us.

Request Example

curl -X POST \
-H "X-Frame-ClientId: ${client_id}" \
-H "X-Frame-Timestamp: ${timestamp}" \
-H "X-Frame-Signature: ${signature}" \
"https://api.console.nutanix.com/v1/accounts/${id}/launchpad"
-F 'name=Windows 2016 Desktop' \
-F url_slug=w2016-desktop \
-F kind=desktop \

Response Example

Status: 200 OK
{
  "id": "b9daaad8-83e2-4c71-b977-741bd2edc1d4",
  "name": "Windows 2016 Desktop",
  "url_slug": "w2016-desktop",
  "active": true
}