The Xelon HQ API is a RESTful interface that provides predictable URLs for accessing resources and retrieving HTTP responses. Our API accepts JSON-formatted content for both requests and responses, including errors.
\nEach request must be authenticated and should not exceed the rate limit. Learn more about our API fundamentals here.
\n\n\nPlease note that folders and endpoints marked with a [-] prefix may not work correctly. We're doing our best to fix that asap.
\n
Base URL of all API requests is https://hq.xelon.ch.
Within Xelon HQ API, to make authorized calls, you must provide an authorization header with the Bearer token, which stands for Service Token within the platform. You can learn how to obtain it here.
\nXelon HQ permissions array consists of three parameters:
\nid – a unique ID of a permission.
Technical name – a more jargon name of a permission (name).
General name – a more plain and clear name of a permission (label).
500 API calls per minute for POST requests. Need extension? Contact our support, we're happy to help!
All date entries should follow the ISO8601 format: YYYY-MM-DD.
\"startDate\": \"2022-12-24\"2025-11-25
\n2025-10-06
\nRemoved: monitoring property deprecated across VM endpoints:
GET /api/service/device response no longer includes monitoring under device.localvmdetails
POST /api/service/vmlist/create request body no longer accepts monitoring parameter
POST /api/service/vmlist/create response no longer includes monitoring under device object
2025-03-27
\nGET /api/service/device endpoint now includes a labels array.2025-02-20
\nFor tenants/{tenantIdentifier}/networksToShare, added new optional parameter owner_tenant_id
The GET /user/device now includes a new boolean property isConnected under each network listed in the device.networks array.
Endpoint for deleting a script has changed:
\nOld: DELETE /{tenantIdentifier}/templates/deletescript
New: DELETE /{tenantIdentifier}/scripts/{scriptId}
2024-12-05
\nGET /service/device now returns a new property under the device array:
cpuCoresPerSocket (integer)2024-09-28
\nThe GET /services/device now includes the following new boolean properties in the request:
cpuHotAdd
cpuHotRemove
ramHotAdd
The PUT /service/{tenantIdentifier}/vmlist/{vmId}/update/{networkId}/{unit} now supports two new boolean properties in the request body:
connectOnPowerOn
isConnected
For the Create LAN network and Create WAN network endpoints added new integer type property called \"networkSpeed\"
/user/vmlist/create request payload has two new boolean fields: connectOnPowerOn (connect VM to network on power-on) and hostnameVM name.
The GET /service/{tenantIdentifier}/vmlist/{vmId}/editserver response now includes two new boolean properties under each networkInterface.network object:
isConnected
startConnected
2024-09-03
\nFor api/service/{tenantIdentifier}/networks/{networkId}/show endpoint, added optional response property hvSystemId
For the Get firewall info endpoint, added a new string type property called \"state\" that can be either \"ready\" or \"provisioning\".
2024-06-17
\n/service/{tenantIdentifier}/users/restore now requires an allow_delete_users permission
Added new /tenants/{tenantIdentifier}/children-with-parent and /tenants/{tenantIdentifier}/users/permissions endpoints.
/service/tenants/{tenantIdentifier}/users/rolesendpoint is split into 3 separate endpoints: /roles, /children-with-parent, and /permissions
2023-12-9
\nGET List of subtenants endpoint can now retrieve deleted subtenants as well. To see them, add the ?isDeleted=true query to the request.2023-08-6
\nWe’re streamlining the Get list of networks endpoint by removing the stretched_network parameter.
Renamed the hv_system array to hv_systems.
In instances where a network is stretched and connected to multiple clouds, now the list of clouds goes in a numbered array called hv_systems.
We’ve also introduced improved security with Client ID: To ensure the utmost security and authenticity of your requests, we highly recommend including the Client ID in the header of your API requests.
- Simply go to My Organization > Service Tokens block > Client ID button. For all your API requests, please remember to include the following header: X-User-Id: .
Bonus: we added more flexibility for Service Tokens. From now on, one IP address can have multiple Service Tokens associated with it. This enhancement offers greater flexibility and control over token management. Additionally, we now support IPv4/IPv6 ranges in pattern format (e.g., 192.168..) and CIDR/subnet format (e.g., 192.168.0.0/16), giving you more options to work with.
\n2022-09-1
\nWithin the POST Usage report [Tenant view], the total parameter now represents the total resource hours.
The GET Get list of devices endpoint response now has the following parameters removed:
updated_at\ndeleted_at\niso_mounted\nserviceuser_status\nserviceuser_lastchecked\nuser_id\nservice_id\nmonitoring\nnotes\nservice_cluster_type\n\n2022-07-11
\nfinanceemail parameter is now an array. Example: \"financeemail\": [\"address1@xelon.ch\",\"address2@xelon.ch\"]Use this endpoint to update organiation's fields by entering them in the request body. Common use cases are:
\nToggle 2FA
\nmanage 2-factor authentication (2FA) for all users within your organization.
\nvalue to 1 to enable and 0 to disable the 2FA.pk parameter should equal your tenant_id.Change organization type
\nSet type parameter (string) to 1 for Reseller, and 2 for End customer organization type.
This endpoint allows you to change the email frequency of the auto reporting service within your organization.
\nThe value parameter can be either null, weekly, bi-weekly, or monthly.
To toggle auto reporting off, please set the value to null.
\n\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"You can access this option from your Device's page, by going to Options > Edit > Email frequency block.
\n
This endpoint allows you to manage the list of recipients for Auto Reporting. Within the request body userIds array, insert or remove a user's id to add or remove them from the recipient list.
\n\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"User's IDs should be integer values, not string ones.
\n
This endpoint retrieves an array of all organizations and sub-organizations, available for you.
\nApply the parent query parameter to view all child tenants for resellers.
Tenant ID of a specific organiation.
\n","type":"text/plain"},"key":"parent","value":"75c7cf02b782"}],"variable":[]}},"response":[{"id":"c33979ed-71d4-4d35-a4c2-c40e2b0df9f7","name":"List of all organizations","originalRequest":{"method":"GET","header":[],"url":"https://vdc.xelon.ch/api/service/tenants"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.14.0 (Ubuntu)"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"X-StackifyID","value":"V1|6ca8fada-b82f-4934-81f0-887e9f8df0f3|C85225|CD1|"},{"key":"Set-Cookie","value":".Stackify.Rum=6ca8fada-b82f-4934-81f0-887e9f8df0f3"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Wed, 23 Feb 2022 16:59:32 GMT"},{"key":"X-RateLimit-Limit","value":"500"},{"key":"X-RateLimit-Remaining","value":"498"},{"key":"Access-Control-Allow-Origin","value":"*"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"[\n {\n \"deleted_at\": null,\n \"active\": true,\n \"id\": \"Use this endpoint to create a tenant/organization. The configurations below can be set within the body request.
\nUse this endpoint to retrieve complete information about the specific organization.
\nvat rates\n\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Please note that your
\nvatparameter should have a string country value. Example:\"vat\": \"Greece\".
This endpoint allows you to get the list of all clouds available within a specific organization.
\nDisplays the list of subtenants using a specific sorting sort parameter and optional filter for subtenant type.
sort (required)filter (optional)\n\nMaking a request without the
\nfilterquery will display both subtenant types.
isDeleted (optional)Required parameter for item sorting order.
\n","type":"text/plain"},"key":"sort","value":"name-asc"},{"key":"filter","value":"1"},{"description":{"content":"Set to true to display deleted subtenants as well.
Use this endpoint to change your organization's finance/support email or phone number.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"This endpoint retrieves a list of networks available within a specified organization/tenant, as well as their count and a subnets (if available).
Use this endpoint to rename the specific organization or change its address information.
\nA 200 OK response retireves the updated info of your organization.
Use this endpoint to delete a specific organization.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Organization (tenant for technical jargon) is a top-level instance that identifies the owner in charge of one or many sub-organizations within the platform. Organization can either represent a single business, or an IT services provider who manages multiple sub-organizations on behalf of their clients' businesses.
\n\nPlease note that Tenants and Organizations are different names of the same product concept.
\n
tenant_id — a unique identifier for any organization.
userId — a unique identifier for any user within the organization.
token — a unique 'password' for accessing our API which can be generated only once.
\n\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Learn more about organization management here.
\n
Use this endpoint to add a new user within the specific organization. Response retrieves a user's id which can be used for managing users across your organization.
Among the required fields, there are:
\nWhen creating a user, you can also:
\ntrue for welcomeEmail if you want to send a welcome email and Username/Password to the new usertrue for passwordShouldBeChanged if you want the user to change the password after the first login\n\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Learn more about user's
\npermissionsat the top of this page.
Use this endpoint to change the user's name, phone numbers, or password.
\n\n\nAll values should be in a string format. All fields are required.
\n
Learn more about the user's permissions at the top of this page.
\n\n\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"The password must be 6 to 128 characters long and include a number, a lower & upper case letters.
\n
Delete a specific user. Requires tenantIdentifier and userId values.
No user in Xelon HQ can be manually deleted, but deactivated. This endpoint allows you to restore a user by their userId in the request body.
Use this endpoint to change your account password.
\n\n\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"If you want to change an other user's password, use the Update user endpoint above.
\n
Use this endpoint to retrieve a list of roles available within your tenant.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Use this endpoint to retrieve a list of permissions available within your tenant.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Use this endpoint to unfold a list of tenants hierarchy within your organization.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Each user has its own id by which it can be managed. Learn more about user management here.
Retrieves an HTML web console of a specific device.
\n\n\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"You can not use this API call on powered off devices.
\n
Retrieves a list of devices that can be sorted, displayed, and ordered in multiple ways.
\n\n\nReplicated devices have a
\nservice_idthat equals9, while other devices have a1value.
Number of devices displayed per page and per response. Can be 5, 10, 25.
\n","type":"text/plain"},"key":"per_page","value":"5"},{"description":{"content":"Descending created date order. Put 'asc' for ascending.
\n","type":"text/plain"},"key":"order","value":"desc"},{"description":{"content":"A parameter to sort devices by. Can be 'created_at', 'vmdisplayname', and 'power_state'.
\n","type":"text/plain"},"key":"sort_by","value":"created_at"},{"description":{"content":"A number of the page you want to get listed.
\n","type":"text/plain"},"key":"page","value":"1"}],"variable":[]}},"response":[{"id":"f5eb711f-ed5c-440c-a1dc-09f96d15e518","name":"Get list of devices","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"url":{"raw":"https://vdc.xelon.ch/api/service/This endpoint retrieves a list of available templates, NICs, and scripts when creating a new device.
\nThe request itself consists of three variables: TENANT_ID, SERVER, and NUMBER. See the explanation in the table below.
\nRequest scheme:
\nhttps://hq.xelon.ch/api/service/TENANT_ID/vmlist/create/Server/SERVER/NUMBER
Example:
\nhttps://hq.xelon.ch/api/service/2sn54783n/vmlist/create/Server/Linux/7 - corresponds to a Debian 9 64 bit EN device.
An essential endpoint for creating a new device. Check user guide for more details about this process.
\nTo create a device, you send its configuration as a JSON body request.
\n\n\nYou need to either manually specify IP address as a string, i.e. \"196.16.55.12\", using the
\n\"ip1\"field or send your IP's ID within the\"ipaddr1\"parameter.
Within a 200 response, endpoint displays a created device's info listed below.
Retrieves a general info on a specific device, such as:
\nRunning tools - toolsStatus
CPU usage - currentcpuusage
Device health - systemstatus
Storage - storage
id - retrieves unique storage ID for this VMNetworks - networks
General configuration info (including ISOs (device_isos), Templates, and Backups) - localvmdetails
Response body
\nlabels color IDsAn ID of a tenant
\n","type":"text/plain"},"key":"tenant","value":"An ID of a specific device
\n","type":"text/plain"},"key":"localvmid","value":"This endpoint retrieves an array of all available device templates.
\nRetrieves an array of device's data usage divided by CPU and Network usage. Statistics PERIOD can be either 6, 12, 24, or 48 hours correspondingly.
You can interpret this chart by correlating data and labels arrays.
\n\nThis endpoint works even when you haven't connected a Monitoring Service.
\n
A 200 OK response retrieves an array of usage stats from VMware in the following format:
{\n cpu_chart: \n data: [],\n labels: [],\n network_chart: data: [],\n labels: []\n}\n\nRetrieves a comprehensive list of device's Edit panel settings:
\navailableDevices array)