Common API Usecases
  • 06 Jun 2022
  • 6 Minutes to read
  • Dark
  • PDF

Common API Usecases

  • Dark
  • PDF

In this page, we will show you how to perform common tasks with the Xelon HQ REST API using some simple examples.

We show code samples for each scenario using cURL. Each request requires a Service Token, so get yours and replace the token value in the samples.

Get Tenant ID

First, let's see how we can get our tenant ID – a very useful parameter across our API ecosystem.

We'll send a GET request to the tenants endpoint at

curl --location --request GET '' \
--header 'Authorization: Bearer 0a1b2c3d4e5f6g7h8aBcDeF012345678'
Authorization note

With every request to the Xelon HQ API we pass an authorization header of type Bearer with our Service Token. In the sample, the token is set to 0a1b2c3d4e5f6g7h8aBcDeF012345678, but you should replace it with your own token.

The API responds with a 200 status, and a JSON response containing an array of all available tenants and their IDs:

        "deleted_at": null,
        "active": true,
        "id": "4sn57783n",
        "name": "Xelon AG",
        "address": "Proreznaya str.\nProreznaya_2 str.\n12345\nKyiv\nUkraine",
        "type": "Reseller",
        "created_at": "2018-01-24 20:36:13",
        "networks": 14,
        "activeDevices": 13,
        "parent": null
        "deleted_at": null,
        "active": true,
        "id": "a84bv00609453x",
        "name": "Andrik",
        "address": "Khreschatik st.879, Kyiv, Ukraine\nKhreschatik st.879, Kyiv, Ukraine\n12345\nKyiv\nSwitzerland",
        "type": "Reseller",
        "created_at": "2020-10-13 18:54:05",
        "networks": 1,
        "activeDevices": 1, 
        "parent": "4sn57783n"

We're looking for a Xelon AG tenant, so our tenant ID is 4sn57783n.

Pro Tip

Within the response, you can see the number of active devices, networks, and whether the tenant has a parent/root organizaiton.

Get list of devices

Now, let's use our tenant ID to fetch a list of devices linked to our organization.

We'll send a GET request to the devices endpoint at<TENANT_ID>/devices. As with the previous request, we send the same authorization header containing the Service Token of type Bearer.

curl --location --request GET '' \
--header 'Authorization: Bearer 0a1b2c3d4e5f6g7h8aBcDeF012345678' 

The API responds with a 200 status, and a JSON response containing list of devices assigned to our tenant:

    "current_page": 1,
    "data": [
            "localvmid": "638e9e393a43",
            "created_at": "2022-01-28T14:30:53+01:00",
            "updated_at": "2022-01-28T14:32:03+01:00",
            "deleted_at": null,
            "vmdisplayname": "Andrii Device",
            "template_id": 10027,
            "vmhostname": "andrii-test-device",
            "state": 1,
            "iso_mounted": null,
            "serviceuser_status": 0,
            "serviceuser_lastchecked": null,
            "hv_system_id": 4,
            "user_id": 3258,
            "vdc_service_type": 1,
            "service_id": null,
            "monitoring": 1,
            "notes": null,
            "service_cluster_type": null,
            "backup_status": false,
            "power_state": "poweredOn",
            "memory": 7,
            "cpu": 7,
            "hv_type": "public",
            "template": {
                "id": 10027,
                "category": "Server",
                "type": "Linux",
                "instructions": null,
                "hv_type": null
            "tenant": {
                "tenantname": "Xelon AG",
                "tenant_identifier": "2sn54783n"
            "hv_system": {
                "id": 4,
                "created_at": "2022-02-02T13:49:54+01:00",
                "updated_at": "2020-12-03T22:42:42+01:00",
                "custom_template_folder": "group-v127",
                "datacenterName": "datacenter-2",
                "type": 2,
                "tenant_id": 1,
                "main_cloud": 1,
                "display_name": "Test Public",
                "default_lan": null,
                "hv_type": "public"

Within the request, we can spot our localvmid638e9e393a43. Now, let's play with the device configuration.

Create a device

To create a device through the API request, we should send its configuration as a JSON body request. We'll use a POST method and a endpoint.

Request example

curl --location --request POST '' \
--header 'Content-Type: application/json' \
--data-raw '{
	"backupId": 1,
	"cloudId": 1,
	"cpucores": 1,
	"disksize": 32,
	"displayname": "test",
	"hostname": "test",
	"ipaddr1": 415,
	"memory": 1,
	"monitoring": false,
	"networkid1": 35,
	"niccontrollerkey1": 100,
	"nickey1": 4000,
	"nicnumber": 1,
	"nicunit1": 7,
	"password": "q3nR5E3;zP",
	"password_confirmation": "q3nR5E3;zP",
	"scriptid": null,
	"sendEmail": false,
	"swapdisksize": 1,
	"template": 1,
	"tenant_identifier": "75c7cf02b782"

Request fields

Parameter Type Description
backupId integer Specific backup frequency. See the Backups folder for more info.
cloudId integer An ID of a selected cloud.
cpucores integer Number of CPU cores. Min: 1; Max: 12.
disksize integer Number of disk size gigabytes. Min: 32; Max: 4000.
ipaddr1 integer An ID of a selected IP address.
memory integer Amount of RAM GB. Min: 1; Max: 64
monitoring boolean Becomes true or false depending on whether the Monitoring Service toggle is switched on/off.
networkid1 integer An ID of a selected network.
password string Must contain uppercase and lowercase letters, numbers, and have 6 characters minimum length.
scriptid integer An ID of a selected script to run after a device setup (optional. For more info, see the Templates, ISOs, and Scripts folder.
sendEmail boolean If true, will email a user when provisioning has been completed
swapdisksize integer Size of a SWAP disk, GB. Min: 1; Max: 20.
template integer Selected OS. Explore the Device creation info endpoint above for more details.

Within a 200 response, endpoint displays a created device's info including the parameters listed below.

Response example

  "device": {
    "localvmid": "{{LOCALVMID}}",
    "hv_system_id": 1,
    "template_id": 1,
    "vmdisplayname": "test",
    "iso_mounted": null,
    "vmhostname": "test",
    "state": 0,
    "user_id": 1695,
    "updated_at": "2022-03-17T15:52:34+01:00",
    "created_at": "2022-03-17T15:52:34+01:00",
    "monitoring": false,
    "vdc_service_type": 1,
    "hv_type": "public"
  "ips": [

Response fields

Parameter Type Description
localvmid integer An ID of your device.
vmdisplayname string A name of your device which will be displayed within the interface.
iso_mounted integer An ID of a connected ISO, if available.
monitoring boolean If true, the Monitoring Service is enabled.
ips array An array of the network's IP addresses linked to this device.
state integer 1 – provisioning finished, the device is ready; 0 – provisioning in progress or failed
hv_system_id integer Hypervisor's ID (learn more in a Get list of organization's clouds endpoint)
service_id string ID of a cluster (if it's related to Kubernetes cluster)

That's it, your device is created and will be in provisioning for abount 15 minutes. After that, you can start configuring it.

Add CPU and RAM to a device

Let's add some RAM and CPU cores to our very own device.

This time we are sending a PUT request, to the vmlist endpoint at<LOCALVMID>/updateserver. We will also add two integer parameters to our request: ramvalue and cpuvalue.

curl --location --request PUT '' \
--header 'Authorization: Bearer 0a1b2c3d4e5f6g7h8aBcDeF012345678'
Hold on, cowboy

RAM, CPU, and other values have their limitations. Learn more about them in our API reference documentation.

The API responds with a 200 status, and a JSON response containing a corresponding message:

	"message": "Server is upgrading"

Create a Reseller organization

To create a Reseller-type organization, we'll need to send a POST request to the endpoint. Here's what should be included in its body:

	"2factor": <true OR false>, 
	"address": "<ADDRESS>",
	"city": "<CITY>",
	"country": "<COUNTRY>",
	"financeemail": "<EMAIL>",
	"phone": "<PHONE>",
	"postcode": "<ZIPCODE>",
	"supportemail": "<EMAIL>",
	"tenantname": "<RESELLER_ORG_NAME>",
	"trial": false,
	"type": "1"
Parameter Description Type
2factor If true, will enable a 2-factor authentication for all organization's users. boolean
address Organization's address. string
city Organization's city name. string
country A string value with the country name. string
financeemail Organization's finance email. string
phone Organization's phone number. string
postcode Organization's ZIP/post code. string
supportemail Organization's support email. string
tenantname Display name of your organization. string
trial Set to false. boolean
type Set 1 for Reseller, and 2 for End customer organization type. string

Within a 200 response, we'll get a "message" that "The organization was successfully created.". Within the tenant parameter or the response, you'll get the info on your new child organization.

Here's how the curl request will look:

curl --location --request POST '' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9kZXYtdmVyLTFcL1wvYXBpXC91c2VyXC9sb2dpbiIsImlhdCI6MTU4MjEwMzA1OSwiZXhwIjoxNTgyMTA0MjU5LCJuYmYiOjE1ODIxMDMwNTksImp0aSI6IkNhNlJZNFc3RDc0M3dwVHEiLCJzdWIiOjMwMywicHJ2IjoiODdlMGFmMWVmOWZkMTU4MTJmZGVjOTcxNTNhMTRlMGIwNDc1NDZhYSJ9.dehIFqzjOMi6nexVGjngO-co0EUXTav4TqPJtjvGW7g' \
--header 'Content-Type: application/json' \
--data-raw '{
	"2factor": false,
	"address": "Test Address",
	"city": "Zug",
	"country": "Switzerland",
	"financeemail": "<EMAIL>",
	"phone": "<PHONE_NUMBER>",
	"postcode": "<ZIP>",
	"supportemail": "<EMAIL>",
	"tenantname": "<ORGANIZATION_NAME>",
	"trial": false,
	"type": "1" 

That's all! We've covered the basic concepts of interacting with the Xelon HQ REST API. As we've said earlier, you can find details of all the available endpoints and parameters for the various Xelon HQ instances in the API reference documentation.

Was this article helpful?

What's Next