Skip to content

Getting started using API

API Token

The procedure is documented in API v3 Authentication

Create an API Key and don’t forget to add IP whitelisting to access the API.

API Key is to be used in HTTP Header as Key = PRIVATE-TOKEN and Value = your_api_key

Server details

The host endpoint provides details on dedicated bare metal servers in your account.

To list all Hosts with full detail on hardware configuration including IP addresses:

GET /v3/host

To list details of a specific Host:

GET /v3/host/{hostId}

Server actions

Basic action for power On/Off/Restart can be performed on each server using below endpoints:

Turn the server On: PUT /v3/host/{hostId}/start

Turn the server Off: PUT /v3/host/{hostId}/stop

Restart the server: PUT /v3/host/{hostId}/restart

Server OS installation

This endpoint allows to install a new operating system onto a server in the customer account.

The {hostId} parameter can be found in GET /v3/host which lists all the servers in your account.

API endpoint

Trigger an OS installation: POST /v3/host/{hostId}/os/install

Check the current status of the installation process: GET /v3/host/{hostId}/os/installLog

You will need to know which Operating System id to use by using below endpoint:

GET /v3/operatingsystem

Request body properties

Property Value type Required Description
hostname string Optional Default is Server{ID} with Unique identifier. NOTE: when installing Talos, the machine name will be derived from the hostname, taking the first part of the hostname.
os.id int Required Desired os.id look up in GET /v3/operatingsystem
os.kernelParams string Optional An advanced option, currently only applies when installing Talos (See talos OS section)
postInstallScript string Optional Optional bash script to be performed after OS installation. Does not apply to Talos.
sshKeyId UUid Required Manage your SSH keys via POST /v3/sshKey. The public key will be installed for the root user.
quickFormat bool Optional Optional parameter indicating whether you want the disks to first be quick-formatted prior to OS installation. We recommend to always perform a quick-format, unless you have a specific case where it is not needed to clear the disk partitions prior to installing a new OS.
Table 1: Install OS element structure

Example request

POST /v3/host/{hostId}/os/install

Request Body 

{
  "hostname": "my.host.name",
  "os": {
    "id": 261
  },
  "postInstallScript": "#!/bin/bash\necho \"Hello world\" > /tmp/test.txt",
  "sshKeyUuid": "62335584-bee9-48a2-xxxx-3561d8cadad1",
  "quickFormat": true
}

Talos OS

Talos can be installed using two methods

  • Talos install vanilla: provide required siderolink.api link
  • Talos install via Factory image: provide required factoryhash

In both cases, additional kernel parameters are required. These will override any defaults injected. Talos default kernel parameters are: 

slab_nomerge
pti=on
vga=normal
locale=en_US
console-keymaps-at/keymap=us
net.ifnames=0
panic=0
initrd=initrd.magic
init_on_alloc=1
consoleblank=0
nvme_core.io_timeout=4294967295
printk.devkmsg=on
ima_template=ima-ng
ima_appraise=fix ima_hash=sha512
talos.platform=metal
talos.events.sink=[fdae:41e4:649b:9303::1]:8091
talos.logging.kernel=tcp://[fdae:41e4:649b:9303::1]:8092

More information about Talos kernel parameters you can find here: https://www.talos.dev/v1.7/reference/kernel/

Network configuration for your server will be automatically injected by our systems.

Example Talos OS 1.7.2 Vanilla Request Body

POST /v3/host/{hostId}/os/install

Request body 

{
  "hostname": "My.Host.Name",
  "os": {
    "id": 294,
    "kernelParams": [
      {
        "key": "siderolink.api",
        "value": "https://path.to/omni?bcwe7r8236r7gwuyiwe"
      },
      {
        "key": "talos.customparam",
        "value": "123456"
      }
    ]
  },
  "postInstallScript": null,
  "sshKeyUuid": "62335584-bee9-48a2-a81d-3561d8cadad1"
}

Example Talos OS 1.7.2 Factory Request Body

POST /v3/host/{hostId}/os/install

Request body 

{
  "hostname": "My.Host.Name",
  "os": {
    "id": 294,
    "kernelParams": [
      {
        "key": "factoryhash",
        "value": "93be9c834b04065cdfb6223049697263586e92471231ed2abdfcc23c2a4551a4"
      },
      {
        "key": "talos.customparam",
        "value": "123456"
      }
    ]
  },
  "postInstallScript": null,
  "sshKeyUuid": "62335584-bee9-48a2-a81d-3561d8cadad1"
}