API Documentation

Learn how to integrate with our API to manage your virtual machines and resources.

Sections

Getting Started Secrets Management Instance Creation Instance Management Billing Organization

Instance Creation & Hostnodes

Endpoints for creating new virtual machine instances and listing available hostnodes.

Note on SSH Keys: You must provide either an ssh_key_id (referencing a pre-uploaded key) or the full public key content via the ssh_key attribute. Providing both is not allowed.

Interactive API Examples

Explore the API endpoints with request and response examples.

1. Create Instance (with Port Forward)

Create the instance using a chosen hostnode UUID and one of its available ports.

POST/api/v2/instances

Request Body

{
  "data": {
    "type": "virtualmachine",
    "attributes": {
      "name": "my-port-forward-instance",
      "type": "virtualmachine",
      "image": "ubuntu2404",
      "hostnode_id": "hn-uuid-12345",
      "resources": {
        "vcpu_count": 2,
        "ram_gb": 4,
        "storage_gb": 300,
        "gpus": {
          "geforcertx4090-pcie-24gb": {
            "count": 1
          }
        }
      },
      "port_forwards": [
        {
          "internal_port": 22,
          "external_port": 20000
        },
        {
          "internal_port": 80,
          "external_port": 20001
        }
      ],
      "ssh_key_id": "sshkey-uuid-12345",
      "cloud_init": {
        "runcmd": [
          "echo 'Hello World'",
          "apt-get install -y nginx"
        ],
        "packages": [
          "curl",
          "git"
        ],
        "package_update": true,
        "package_upgrade": false
      }
    }
  }
}

Response

{
  "data": {
    "type": "virtualmachine",
    "id": "instance-uuid",
    "name": "my-port-forward-instance",
    "status": "running"
  }
}

2. List Available Hostnodes

(Optional) Fetch a list of available hostnodes to find a suitable hostnode_id and available ports.

GET/api/v2/hostnodes

Response

{
  "data": {
    "hostnodes": [
      {
        "id": "hostnode-uuid",
        "location_id": "location-uuid",
        "engine": "Narwhal",
        "uptime_percentage": 99.79,
        "available_resources": {
          "gpus": [
            {
              "v0Name": "h100-sxm5-80gb",
              "availableCount": 8,
              "price_per_hr": 2.2
            }
          ],
          "vcpu_count": 208,
          "ram_gb": 990,
          "storage_gb": 14780
        },
        "pricing": {
          "per_vcpu_hr": 0.0015,
          "per_gb_ram_hr": 0.0007,
          "per_gb_storage_hr": 0.00005
        },
        "location": {
          "uuid": "location-uuid",
          "city": "City Name",
          "stateprovince": "State/Province Name",
          "country": "Country Name",
          "has_network_storage": false,
          "network_speed_gbps": 10,
          "network_speed_upload_gbps": 10,
          "organization": "organization-uuid",
          "organizationName": "Organization Name",
          "tier": 3
        }
      }
    ]
  }
}

3. Get Specific Hostnode Details

(Optional) Fetch details for a specific hostnode (e.g., hn-uuid-12345) to confirm resources and available ports.

GET/api/v2/hostnodes/{uuid}

Parameters

uuid - The unique identifier of the hostnode (e.g., hn-uuid-12345).

Response

{
  "data": {
    "id": "hostnode-uuid",
    "location_id": "location-uuid",
    "engine": "Narwhal",
    "uptime_percentage": 99.79,
    "available_resources": {
      "gpus": [
        {
          "v0Name": "h100-sxm5-80gb",
          "availableCount": 8,
          "price_per_hr": 2.2
        }
      ],
      "vcpu_count": 208,
      "ram_gb": 990,
      "storage_gb": 14780,
      "available_ports": [
        20000,
        20001,
        20002,
        20003,
        20004,
        20005,
        20006,
        20007,
        20008
      ]
    },
    "pricing": {
      "per_vcpu_hr": 0.0015,
      "per_gb_ram_hr": 0.0007,
      "per_gb_storage_hr": 0.00005
    },
    "location": {
      "uuid": "location-uuid",
      "city": "City Name",
      "stateprovince": "State/Province Name",
      "country": "Country Name",
      "has_network_storage": false,
      "network_speed_gbps": 10,
      "network_speed_upload_gbps": 10,
      "organization": "organization-uuid",
      "organizationName": "Organization Name",
      "tier": 3
    }
  }
}

Cloud Init Configuration

Configure initial setup and packages for your virtual machine instance

The cloud_init object allows you to configure the initial setup of your virtual machine. It supports the following options:

runcmd

Optional array of commands to run during the first boot. These commands are executed after the system is fully booted.

packages

Optional array of package names to install during the first boot.

package_update

Optional boolean flag to update the package list during first boot. Defaults to false.

package_upgrade

Optional boolean flag to upgrade all installed packages during first boot. Defaults to false.

Example:

{
  "cloud_init": {
    "runcmd": [
      "echo 'Hello World'",
      "apt-get update",
      "apt-get install -y nginx"
    ],
    "packages": [
      "curl",
      "git"
    ],
    "package_update": true,
    "package_upgrade": false
  }
}