Getting started with FlexVM

Prerequisites

Before you begin, the i3D team has already set up the following for you:

• Tenant (K#): your unique organization identifier.

  • Each Tenant has its own VLAN and IP prefixes already assigned to it.

• FlexVM Cloud: a dedicated resource pool with compute capacity assigned to your Tenant.

  • You can also create and delete Clouds yourself; see Creating a Cloud and Nodes.

Using FlexVM API

API URL prefix is https://api.i3d.net

API Token

Generate an API token, the procedure is documented in API v3 Authentication

• Add IP whitelisting for security (whitelist the IP addresses that will access the API).

• Include your API key in every request using this HTTP header:

HTTP Header Name	HTTP Header Value
PRIVATE-TOKEN	YOUR_API_KEY

Pagination

Use the RANGED-DATA header to control result sets (default: start=0, results=25). All GET endpoints that return collections support this header.

Step 1: Create Your First Cloud and Node

A Cloud is your isolated resource pool, and Nodes are the bare-metal servers that provide its capacity. You need at least one Cloud with one Node before you can create VMs — this is where you start.

If the i3D.net team has already provisioned a Cloud for you (see Prerequisites), you can skip ahead to Step 2: Explore Your Environment.

1. Create a Cloud with POST /v3/flexVM/clouds, specifying its name, site, and the Bare Metal instance type to use.

2. Add a Node with POST /v3/flexVM/clouds/{cloudUuid}/nodes. Nodes are provisioned asynchronously and become available to host VMs once provisioning completes.

For the full request bodies, available instance types, and scaling details, see Creating a Cloud and Nodes.

Step 2: Explore Your Environment

• List your Clouds:

  • GET /v3/flexVM/clouds

  • You should see one Cloud with its UUID, name, and capacity details.

• Get Cloud details:

  • GET /v3/flexVM/clouds/{cloudUuid}

  • Returns the details of one specific Cloud.

• List Nodes in your Cloud:

  • GET /v3/flexVM/clouds/{cloudUuid}/nodes

  • Nodes represent the underlying compute hosts. This lists the physical server Nodes that are enrolled in the Cloud.

• List available Images:

  • GET /v3/flexVM/images

  • Images are templates you can use when creating a VM.

• List available Instance Types:

  • GET /v3/flexVM/instanceTypes

  • Instance Types define a VM's size (vCPU, RAM, disk, PCIe device passthrough).

Step 3: Create Your First VM

Create a VM with the POST /v3/flexVM/clouds/{cloudUuid}/vms endpoint. For the full request body and response, see Creating and Deleting a VM; for a Terraform example, see Using Terraform.

A newly created VM transitions through provisioning → starting → running. You can monitor its status using the GET VM endpoint described below.

Step 4: Manage Your VMs

• List VMs in your Cloud:

  • GET /v3/flexVM/clouds/{cloudUuid}/vms?status=running

  • Optionally filter by status (e.g., running, stopped).

  • Returns the creation or deletion timestamp of each VM alongside its IP address and Node.

• Get a specific VM:

  • GET /v3/flexVM/clouds/{cloudUuid}/vms/{vmUuid}

  • Returns the details of the specified VM only.

• Execute a command on a VM:

  • POST /v3/flexVM/clouds/{cloudUuid}/vms/{vmUuid}/commands

  • Supported commands: start, stop, reboot, reset. See Managing VMs.

• Delete a VM:

  • DELETE /v3/flexVM/clouds/{cloudUuid}/vms/{vmUuid}

  • Immediately wipes the local LVM disk and the passthrough NVMe (if any). See Creating and Deleting a VM.

Step 5: Monitor Monthly Usage

Retrieve usage data across all your Clouds with the GET /v3/flexVM/reports/monthly endpoint. For the full request and a breakdown of the reported aggregates, see Usage and Reporting.

Using FlexVM Terraform Provider

FlexVM can be used through our API or through our Terraform provider. See Using Terraform for setup and an example.