Common API Usecases

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 https://hq.xelon.ch/api/service/tenants.

curl --location --request GET 'https://hq.xelon.ch/api/service/tenants' \
--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 organization.

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 https://hq.xelon.ch/api/service/<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 'https://hq.xelon.ch/api/service/4sn57783n/devices' \
--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 localvmid – 638e9e393a43. 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 https://vdc.xelon.ch/api/service/vmlist/create endpoint.

Request example

curl --location --request POST 'https://vdc.xelon.ch/api/service/vmlist/create' \
--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": "",
    "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": [
    "10.0.0.4"
  ]
}

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 https://hq.xelon.ch/api/service/vmlist/<LOCALVMID>/updateserver. We will also add two integer parameters to our request: ramvalue and cpuvalue.

curl --location --request PUT 'https://hq.xelon.ch/api/service/vmlist/638e9e393a43/updateserver?ramvalue=12&cpuvalue=6' \
--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 https://vdc.xelon.ch/api/user/tenants/store 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 'https://vdc.xelon.ch/api/service/tenants/store' \
--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.