API docs by Redocly

Xelon HQ API (1.3.1)

Download OpenAPI specification:

Xelon API Team: [email protected] License: Apache License 2.0

Introduction

The Xelon HQ API allows you to manage resources withing Xelon Cloud in a simple and programmatic way using conventional HTTP requests.

Base URL of all API requests is https://hq.xelon.ch/api/v2/.

Authorization

Within Xelon HQ API v2, to make authorized calls, you must provide an authorization header with the Bearer token and X-User-Id. You can obtain a token by creating a service user on hq.xelon.ch.

Tenants

Tenants are the top-level entities in the Xelon Cloud. They are used to group resources and manage access.

List Tenants

Retrieve a paginated list of tenants.

Authorizations:
service_token
query Parameters
perPage
integer
Example: perPage=10

The numbers of items to return

sort
string
Example: sort=name

Sorting parameter

search
string
Example: search=digital

Searching string

order
string
Enum: "acs" "desc"
Example: order=asc

Order parameter

page
integer
Example: page=10

Page number

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "abc123abc456",
      • "name": "Company Inc.",
      • "type": "Reseller",
      • "status": "Active",
      • "parent": "abc123abc456",
      • "breadcrumbs": "Xelon AG / Company Inc.",
      • "createdAt": "2024-08-15 12:19:37",
      • "deletedAt": "2024-08-18 17:10:54"
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "from": 1,
    • "lastPage": 13,
    • "perPage": 5,
    • "to": 5,
    • "total": 64
    }
}

Create Tenant

Create a new tenant (organization) underneath the authenticated user's tenant or under an explicit parent tenant.

Requires the allow_create_organizations permission. End-customer accounts cannot create tenants. When cloudIdentifier is provided, the new tenant is attached to that cloud only; otherwise it is attached to every cloud of the authenticated user's tenant.

Pass defaultBackupSlug to seed the new tenant's tenant_settings with a default backup job (the legacy implicit inheritance from the parent tenant has been removed in V2 — be explicit).

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
required
string <= 80 characters

Organization name.

address
required
string <= 90 characters

Primary address line.

address2
string or null <= 90 characters

Secondary address line.

postcode
required
string [ 4 .. 8 ] characters

Postal code.

city
required
string <= 90 characters

City name.

country
required
string = 2 characters

ISO 3166-1 alpha-2 country code (e.g. CH, DE, AT). Must match a country_code configured in the taxes table.

region
string or null

Region or state.

phone
required
string

Contact phone number in international format.

supportEmail
required
Array of strings <email> non-empty [ items <email > ]

Support email addresses. Must be a non-empty array.

financeEmail
required
Array of strings <email> non-empty [ items <email > ]

Finance email addresses. Must be a non-empty array.

parentIdentifier
string or null

Identifier of the parent tenant. Defaults to the authenticated user's tenant. Parent must be a reseller.

cloudIdentifier
string or null

Restrict the tenant to a single cloud (HV system) by identifier. Must belong to the authenticated user's tenant.

trial
required
boolean

Whether the new tenant is created in trial mode. Honored only if the authenticated user's tenant has allow_trial_creation and the user has allow_manage_trial_end_date.

trialEnd
string or null <date>

Trial end date (Y-m-d). Required when trial is true and trial creation is permitted.

otpType
string or null
Enum: "" "sms" "totp" "totp_with_sms" null

Two-factor authentication type to enforce for users of this tenant.

type
required
integer
Enum: 1 2

Tenant type — 1 = reseller, 2 = end customer.

customerType
string or null

Optional customer type classifier.

billingPlanId
integer or null

Billing plan ID. If provided, the plan must be owned by the authenticated user's tenant. Defaults to the configured default billing plan.

defaultBackupSlug
string or null

Slug of the backup job to use as the new tenant's default (tenant_settings.default_backup_job_slug). Must match an existing row in vm_backup_jobs.slug. If omitted, no tenant_settings row is created for the new tenant.

Responses

Request samples

Content type
application/json
{
  • "name": "Acme AG",
  • "address": "Bahnhofstrasse 1",
  • "address2": null,
  • "postcode": "8001",
  • "city": "Zürich",
  • "country": "CH",
  • "region": "ZH",
  • "phone": "+41 44 000 00 00",
  • "supportEmail": [],
  • "financeEmail": [],
  • "parentIdentifier": null,
  • "cloudIdentifier": null,
  • "trial": false,
  • "trialEnd": null,
  • "otpType": null,
  • "type": 1,
  • "customerType": null,
  • "billingPlanId": null,
  • "defaultBackupSlug": null
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123def456",
    • "name": "Acme AG",
    • "active": true,
    • "type": "Reseller",
    • "status": "Active",
    • "parent": "parent12345",
    • "address": "Bahnhofstrasse 1",
    • "address2": null,
    • "phone": "+41 44 000 00 00",
    • "city": "Zürich",
    • "postcode": "8001",
    • "country": "Switzerland",
    • "financeEmail": [],
    • "supportEmail": "[email protected]",
    • "trial": false,
    • "trialStart": null,
    • "trialEnd": null,
    • "allowTrialCreation": false,
    • "customerType": null,
    • "deactivationDate": null,
    • "createdAt": "2024-01-15 10:30:00",
    • "deletedAt": null
    },
  • "message": "The organization has been successfully created."
}

Get Tenant

Retrieve a single tenant info. Soft-deleted tenants are also returned (with deletedAt set); 404 is returned only when no tenant with the given identifier has ever existed.

Authorizations:
service_token
path Parameters
tenant_identifier
string
Example: a1b2c3d4e5f6

tenant identifier

Responses

Response samples

Content type
application/json
{
  • "identifier": "abc123abc456",
  • "name": "Company Inc.",
  • "active": true,
  • "type": "Reseller",
  • "status": "Active",
  • "parent": "abc123abc456",
  • "address": "Poststrasse 15",
  • "address2": "Poststrasse 15",
  • "phone": "+41 41 552 28 50",
  • "city": "Zug",
  • "postcode": "6300",
  • "country": "Switzerland",
  • "financeEmail": [],
  • "supportEmail": "[email protected]",
  • "trial": false,
  • "trialStart": "2023-06-01T23:59:59+02:00",
  • "trialEnd": "2023-09-01T23:59:59+02:00",
  • "allowTrialCreation": false,
  • "customerType": "developer-saas",
  • "deactivationDate": "2023-10-27 00:00:00",
  • "createdAt": "2024-08-15 12:19:37",
  • "deletedAt": "2024-08-18 17:10:54"
}

Update Tenant

Partial update of a tenant (organization). Only the fields present in the request body are touched; everything else stays as it was.

Requires the allow_create_organizations permission and hasAccess to the target tenant.

billingPlanId on your own tenant additionally requires the allow_manage_billing_plans permission — passing it while {identifier} matches your own tenant without that permission returns 403. On sub-tenants no extra permission is needed.

This is the single endpoint for updating tenant fields — the previously separate address, contact, notes and field endpoints have been consolidated here. The propagation-aware POST /tenants/{tenant_identifier}/default-backup remains separate because it can cascade the default backup slug to all sub-tenants in one call.

Authorizations:
service_token
path Parameters
tenant_identifier
string
Example: a1b2c3d4e5f6

tenant identifier

Request Body schema: application/json

Partial update. All fields are optional — include only the ones you want to change. An empty object is a no-op.

name
string <= 80 characters

New organization name.

type
integer
Enum: 1 2

Tenant type — 1 = reseller, 2 = end customer.

otpType
string or null
Enum: "" "sms" "totp" "totp_with_sms" null

Two-factor authentication type to enforce for users of this tenant.

address
string <= 90 characters
address2
string or null <= 90 characters
postcode
string [ 4 .. 8 ] characters
city
string <= 90 characters
country
string = 2 characters

ISO 3166-1 alpha-2 country code. Must match a country_code configured in the taxes table. The stored value is resolved to the full country name.

region
string or null
phone
string

Contact phone number in international format.

supportEmail
Array of strings <email> non-empty [ items <email > ]

Support email addresses. Non-empty array.

financeEmail
Array of strings <email> non-empty [ items <email > ]

Finance email addresses. Non-empty array.

billingPlanId
integer

Billing plan ID. Must be a plan owned by the caller's tenant. Changing it on the caller's own tenant requires the allow_manage_billing_plans permission, otherwise the request returns 403.

customerType
string

Customer type classifier.

notes
string or null

Internal free-form notes about the tenant. Pass null to clear.

Responses

Request samples

Content type
application/json
{
  • "name": "Acme AG (rebrand)",
  • "address": "Bahnhofstrasse 2",
  • "city": "Bern",
  • "country": "CH",
  • "supportEmail": []
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123def456",
    • "name": "Acme AG (rebrand)",
    • "active": true,
    • "type": "Reseller",
    • "status": "Active",
    • "parent": "parent12345",
    • "address": "Bahnhofstrasse 2",
    • "address2": null,
    • "phone": "+41 44 000 00 00",
    • "city": "Bern",
    • "postcode": "8001",
    • "country": "Switzerland",
    • "financeEmail": [],
    • "supportEmail": "[email protected]",
    • "trial": false,
    • "trialStart": null,
    • "trialEnd": null,
    • "allowTrialCreation": false,
    • "customerType": null,
    • "deactivationDate": null,
    • "createdAt": "2024-01-15 10:30:00",
    • "deletedAt": null
    },
  • "message": "The organization has been successfully updated."
}

Delete Tenant

Permanently soft-deletes a tenant (organization).

Requires the allow_delete_organizations permission. The caller must be a parent of the target tenant — you cannot delete your own tenant or a sibling tenant.

Before the tenant is deleted, all of the following must be empty:

  • Child organizations
  • Active users
  • Active devices (VMs)
  • Assigned networks (main_tenant)
  • Shared networks (network_tenants)
  • Object storage users (S3 users with buckets must be deleted first)

Human accounts must confirm the action by providing their current password in the request body.

Authorizations:
service_token
path Parameters
tenant_identifier
string
Example: a1b2c3d4e5f6

tenant identifier

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

password
string

The current password of the authenticated user. Required for password-based accounts; omit or leave empty for service accounts (is_service = true) or Microsoft SSO-authenticated users.

Responses

Request samples

Content type
application/json
{
  • "password": "MySecret123"
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Get Current Tenant

Retrieve a single tenant info.

Authorizations:
service_token

Responses

Response samples

Content type
application/json
{
  • "identifier": "abc123abc456",
  • "name": "Company Inc.",
  • "active": true,
  • "type": "Reseller",
  • "status": "Active",
  • "parent": "abc123abc456",
  • "address": "Poststrasse 15",
  • "address2": "Poststrasse 15",
  • "phone": "+41 41 552 28 50",
  • "city": "Zug",
  • "postcode": "6300",
  • "country": "Switzerland",
  • "financeEmail": [],
  • "supportEmail": "[email protected]",
  • "trial": false,
  • "trialStart": "2023-06-01T23:59:59+02:00",
  • "trialEnd": "2023-09-01T23:59:59+02:00",
  • "allowTrialCreation": false,
  • "customerType": "developer-saas",
  • "deactivationDate": "2023-10-27 00:00:00",
  • "createdAt": "2024-08-15 12:19:37",
  • "deletedAt": "2024-08-18 17:10:54"
}

List Subtenants

Retrieve a paginated list of subtenants.

Authorizations:
service_token
path Parameters
tenant_identifier
string
Example: a1b2c3d4e5f6

tenant identifier

query Parameters
sort
string
Enum: "name-asc" "name-desc" "created-asc" "created-desc"
Example: sort=name-asc

Sorting parameter

filter
integer
Enum: 1 2
Example: filter=1

Filter by customer type 1 - "Reseller" or 2 - "End customer"

isDeleted
boolean
Example: isDeleted=true

Show deleted tenants

Responses

Response samples

Content type
application/json
[
  • {
    • "identifier": "abc123abc456",
    • "active": true,
    • "name": "Company Inc.",
    • "createdAt": "2024-08-15 12:19:37",
    • "deletedAt": "2024-08-18 17:10:54",
    • "children": [ ]
    }
]

Get Cloud Children Tenants

Get a list of child tenants that have access to a specific cloud.

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

cloudIdentifier
required
string

The identifier of the cloud to filter tenants by.

Responses

Request samples

Content type
application/json
{
  • "cloudIdentifier": "abc123def456"
}

Response samples

Content type
application/json
[
  • {
    • "tenantIdentifier": "abc123def456",
    • "tenantName": "Child Tenant"
    }
]

Update Tenant Default Backup Plan

Update the default backup plan for a tenant.

Authorizations:
service_token
path Parameters
tenant_identifier
string
Example: a1b2c3d4e5f6

tenant identifier

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

slug
required
string

The slug of the backup job to set as default.

applyToAllSubtenants
required
boolean

Whether to apply this default backup to all sub-tenants.

Responses

Request samples

Content type
application/json
{
  • "slug": "daily-backup",
  • "applyToAllSubtenants": true
}

Response samples

Content type
application/json
{
  • "defaultBackupJobSlug": "daily_7_days",
  • "message": "Default backup saved"
}

Get Tenant Clouds

Get a list of clouds accessible by a specific tenant.

Authorizations:
service_token
path Parameters
tenant_identifier
string
Example: a1b2c3d4e5f6

tenant identifier

Responses

Response samples

Content type
application/json
[
  • {
    • "identifier": "abc123abc456",
    • "name": "CH-GVA-1"
    }
]

Tenant Users

Manage users that belong to a tenant.

Each tenant has its own set of users with roles and permissions scoped to that tenant. Endpoints in this section let you:

  • List all users within a tenant (GET /tenants/{tenant_identifier}/users), with optional search and pagination.
  • Retrieve a single user (GET /tenants/{tenant_identifier}/users/{user_identifier}).
  • Create, update, soft-delete and restore tenant users.
  • List available roles and permissions that can be assigned to users within a given tenant (GET /tenants/{tenant_identifier}/users/roles, GET /tenants/{tenant_identifier}/users/permissions).
  • Update a user's permission set (POST /tenants/{tenant_identifier}/users/{user_identifier}/permissions).
  • Change a user's password (POST /tenants/{tenant_identifier}/users/{user_identifier}/password).
  • Switch a user between password and SSO authentication (POST /tenants/{tenant_identifier}/users/{user_identifier}/auth-source).
  • Fetch the static list of selectable job titles used in user profile / registration forms (GET /users/job-titles).

All endpoints under this section require the allow_manage_users permission, except GET /users/job-titles, which only requires authentication.

List Tenant Users

List all users within a tenant, with optional search and pagination. The list always includes soft-deleted users alongside active ones — use the isActive/deletedAt fields on each entry to tell them apart.

Authorizations:
service_token
path Parameters
tenant_identifier
required
string
Example: abc123def456

A unique identifier for a Tenant.

query Parameters
search
string
Example: search=john

Filter users by name, surname, or email.

perPage
integer [ 1 .. 100 ]
Example: perPage=15

Number of items to return per page.

page
integer >= 1
Example: page=1

Page number to retrieve.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "abc123def456",
      • "name": "John",
      • "surname": "Doe",
      • "email": "[email protected]",
      • "phone": "+41791234567",
      • "businessPhone": null,
      • "jobTitle": "developer",
      • "tenantIdentifier": "abc123def456",
      • "isActive": true,
      • "deletedAt": null
      },
    • {
      • "identifier": "def456ghi789",
      • "name": "Jane",
      • "surname": "Smith",
      • "email": "[email protected]",
      • "phone": null,
      • "businessPhone": null,
      • "jobTitle": null,
      • "tenantIdentifier": "abc123def456",
      • "isActive": false,
      • "deletedAt": "2026-06-01T10:15:00+00:00"
      }
    ],
  • "meta": {
    • "total": 2,
    • "lastPage": 1,
    • "perPage": 15,
    • "currentPage": 1,
    • "from": 1,
    • "to": 2
    }
}

Create Tenant User

Create a new user within a tenant.

Authorizations:
service_token
path Parameters
tenant_identifier
required
string
Example: abc123def456

A unique identifier for a Tenant.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
required
string [ 2 .. 30 ] characters
surname
required
string [ 1 .. 30 ] characters
email
required
string <email>
password
required
string >= 6 characters

Must meet password complexity requirements.

passwordConfirmation
required
string
phone
string or null

Mobile phone number in international format.

businessPhone
string or null
jobTitle
string or null
Enum: "" "ceo" "cto" "ciso_compliance" "sysadmin_devops" "developer" "finance" "other" null

One of the values returned by GET /users/job-titles.

passwordShouldBeChanged
required
boolean

Whether the user must change their password on next login.

welcomeEmail
required
boolean

Whether to send a welcome email to the new user.

onboardingCompleted
boolean or null
roles
required
Array of strings

List of role names to assign to the user. Available roles can be retrieved via Get Tenant User Roles.

permissions
required
Array of strings

List of permission names to assign to the user. Available permissions can be retrieved via Get Tenant User Permissions.

childTenants
Array of strings

List of child tenant identifiers the user should be granted management permissions on. Only applied when roles includes hq_organization_admin.

Responses

Request samples

Content type
application/json
{
  • "name": "John",
  • "surname": "Doe",
  • "email": "[email protected]",
  • "password": "SecurePass123!",
  • "passwordConfirmation": "SecurePass123!",
  • "phone": "+41791234567",
  • "jobTitle": "developer",
  • "passwordShouldBeChanged": false,
  • "welcomeEmail": true,
  • "roles": [
    • "user"
    ],
  • "permissions": [ ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123def456",
    • "name": "John",
    • "surname": "Doe",
    • "email": "[email protected]",
    • "phone": "+41791234567",
    • "businessPhone": null,
    • "jobTitle": "developer",
    • "tenantIdentifier": "abc123def456",
    • "isActive": true,
    • "deletedAt": null
    },
  • "message": "User successfully added."
}

Get Tenant User

Retrieve a single user within a tenant by their identifier.

Authorizations:
service_token
path Parameters
tenant_identifier
required
string
Example: abc123def456

A unique identifier for a Tenant.

user_identifier
required
string
Example: abc123def456

A unique identifier for a User.

Responses

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123def456",
    • "name": "John",
    • "surname": "Doe",
    • "email": "[email protected]",
    • "phone": "+41791234567",
    • "businessPhone": null,
    • "jobTitle": "developer",
    • "tenantIdentifier": "abc123def456",
    • "isActive": true,
    • "roles": [
      • {
        • "id": 1,
        • "name": "hq_organization_admin",
        • "friendlyName": "Organization Admin",
        • "type": "organization"
        }
      ],
    • "permissions": [
      • {
        • "id": 1,
        • "name": "allow_manage_users",
        • "friendlyName": "Manage Users",
        • "type": "users"
        },
      • {
        • "id": 2,
        • "name": "allow_create_vm",
        • "friendlyName": "Create Virtual Machine",
        • "type": "virtual_machines"
        }
      ]
    }
}

Update Tenant User

Update an existing user's information within a tenant.

Authorizations:
service_token
path Parameters
tenant_identifier
required
string
Example: abc123def456

A unique identifier for a Tenant.

user_identifier
required
string
Example: abc123def456

A unique identifier for a User.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
string or null [ 2 .. 30 ] characters

Omit the field to leave the current value unchanged.

surname
string or null [ 1 .. 30 ] characters

Omit the field to leave the current value unchanged.

phone
string or null

Mobile phone number in international format. Omit the field to leave the current value unchanged; send null to clear it.

businessPhone
string or null

Omit the field to leave the current value unchanged; send null to clear it.

jobTitle
string or null
Enum: "" "ceo" "cto" "ciso_compliance" "sysadmin_devops" "developer" "finance" "other" null

One of the values returned by GET /users/job-titles. Omit the field to leave the current value unchanged; send null to clear it.

Responses

Request samples

Content type
application/json
{
  • "name": "John",
  • "surname": "Doe",
  • "phone": "+41791234567",
  • "jobTitle": "developer"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123def456",
    • "name": "John",
    • "surname": "Doe",
    • "email": "[email protected]",
    • "phone": "+41791234567",
    • "businessPhone": null,
    • "jobTitle": "developer",
    • "tenantIdentifier": "abc123def456",
    • "isActive": true,
    • "deletedAt": null
    },
  • "message": "User updated successfully."
}

Delete Tenant User

Soft-delete a user within a tenant.

Authorizations:
service_token
path Parameters
tenant_identifier
required
string
Example: abc123def456

A unique identifier for a Tenant.

user_identifier
required
string
Example: abc123def456

A unique identifier for a User.

Responses

Response samples

Content type
application/json
{
  • "message": "User has been deactivated."
}

Restore Tenant User

Restore a previously deleted user within a tenant.

Authorizations:
service_token
path Parameters
tenant_identifier
required
string
Example: abc123def456

A unique identifier for a Tenant.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

userIdentifier
required
string

The identifier of the deleted user to restore.

Responses

Request samples

Content type
application/json
{
  • "userIdentifier": "abc123def456"
}

Response samples

Content type
application/json
{
  • "message": "User has been restored."
}

Change Tenant User Password

Change the password for a user.

Authorizations:
service_token
path Parameters
tenant_identifier
required
string
Example: abc123def456

A unique identifier for a Tenant.

user_identifier
required
string
Example: abc123def456

A unique identifier for a User.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

password
required
string >= 6 characters

The new password. Must meet complexity requirements.

password_confirmation
required
string

Must match the password field.

Responses

Request samples

Content type
application/json
{
  • "password": "NewSecurePass123!",
  • "password_confirmation": "NewSecurePass123!"
}

Response samples

Content type
application/json
{
  • "message": "Password has been changed."
}

Get Tenant User Roles

Get available roles that can be assigned to users within a tenant.

Authorizations:
service_token
path Parameters
tenant_identifier
required
string
Example: abc123def456

A unique identifier for a Tenant.

Responses

Response samples

Content type
application/json
[
  • {
    • "id": 1,
    • "name": "hq_organization_admin",
    • "friendlyName": "Organization Admin",
    • "type": "organization",
    • "permissions": [
      • {
        • "id": 1,
        • "name": "allow_view_virtual_machines",
        • "guard_name": "api"
        }
      ],
    • "organizations": [
      • {
        • "id": 3,
        • "tenantIdentifier": "def456def789",
        • "tenantName": "Child Org Inc."
        }
      ]
    },
  • {
    • "id": 2,
    • "name": "hq_organization_member",
    • "friendlyName": "Organization Member",
    • "type": "organization",
    • "permissions": [ ],
    • "organizations": null
    }
]

Get Tenant User Permissions

Get available permissions that can be assigned to users within a tenant.

Authorizations:
service_token
path Parameters
tenant_identifier
required
string
Example: abc123def456

A unique identifier for a Tenant.

Responses

Response samples

Content type
application/json
[
  • {
    • "id": 1,
    • "name": "allow_view_virtual_machines",
    • "friendlyName": "View Virtual Machines",
    • "type": "virtual_machines"
    },
  • {
    • "id": 2,
    • "name": "allow_manage_users",
    • "friendlyName": "Manage Users",
    • "type": "users"
    },
  • {
    • "id": 3,
    • "name": "allow_create_vm",
    • "friendlyName": "Create Virtual Machine",
    • "type": "virtual_machines"
    }
]

Update Tenant User Permissions

Update roles and permissions for a user within a tenant.

Authorizations:
service_token
path Parameters
tenant_identifier
required
string
Example: abc123def456

A unique identifier for a Tenant.

user_identifier
required
string
Example: abc123def456

A unique identifier for a User.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

roles
required
Array of strings

List of role names to assign to the user. Available roles can be retrieved via Get Tenant User Roles.

permissions
required
Array of strings

List of permission names to assign to the user. Available permissions can be retrieved via Get Tenant User Permissions.

childTenants
Array of strings or null

List of child tenant identifiers for cascading permissions.

Responses

Request samples

Content type
application/json
{
  • "roles": [
    • "admin"
    ],
  • "permissions": [
    • "allow_view_virtual_machines",
    • "allow_manage_virtual_machine_info"
    ],
  • "childTenants": null
}

Response samples

Content type
application/json
{
  • "message": "User permissions successfully updated."
}

Switch User Auth Source

Switch a user between password and SSO authentication.

Two supported transitions:

  • password → sso: SSO must be enabled for the tenant. The user will no longer be able to log in with their password.
  • sso → password: SSO must be disabled for the tenant. The user will need to go through the "Forgot password" flow to set a new password, since the password created during JIT-provisioning was a random unrecoverable hash.

The following users cannot have their auth source changed:

  • Service accounts (is_service = true)
  • Soft-deleted users (restore the user first)
  • Breaking-glass (SSO bypass) users

The opposite transitions (e.g. sso → password while SSO is still enabled) are rejected to prevent users from being locked out of both auth paths.

Authorizations:
service_token
path Parameters
tenant_identifier
required
string
Example: abc123def456

A unique identifier for a Tenant.

user_identifier
required
string
Example: abc123def456

A unique identifier for a User.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

auth_source
required
string
Enum: "password" "sso"

The authentication source to switch the user to.

Responses

Request samples

Content type
application/json
{
  • "auth_source": "sso"
}

Response samples

Content type
application/json
{
  • "message": "User auth source has been updated."
}

Get User Job Titles

Returns the list of selectable user job titles. The list is static and intended for populating UI selects (e.g. profile / registration forms).

Authorizations:
service_token

Responses

Response samples

Content type
application/json
[
  • {
    • "label": "Not selected",
    • "value": ""
    },
  • {
    • "label": "CEO",
    • "value": "ceo"
    },
  • {
    • "label": "CTO",
    • "value": "cto"
    },
  • {
    • "label": "CISO / Compliance",
    • "value": "ciso_compliance"
    },
  • {
    • "label": "SysAdmin / DevOps",
    • "value": "sysadmin_devops"
    },
  • {
    • "label": "Developer",
    • "value": "developer"
    },
  • {
    • "label": "Finance",
    • "value": "finance"
    },
  • {
    • "label": "Other",
    • "value": "other"
    }
]

Clouds

Clouds are the data centers where your resources are hosted.

List Clouds

List all clouds of current user.

Authorizations:
service_token
query Parameters
tenantIdentifier
string
Example: tenantIdentifier=a1b2c3d4e5f6

tenant identifier

Responses

Response samples

Content type
application/json
[
  • {
    • "identifier": "abc123abc456",
    • "name": "9. Public test cloud",
    • "type": "public"
    }
]

Devices

Devices are the virtual machines that run your applications.

Get Device

Get Device by ID.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Responses

Response samples

Content type
application/json
{
  • "identifier": "abc123abc456",
  • "displayName": "New VM",
  • "hostName": "vm-hostname",
  • "createdBy": "John Doe",
  • "createdAt": "2024-01-01T12:00:00Z",
  • "guestOs": "Windows 10",
  • "monitoring": true,
  • "state": 1,
  • "vmWareTools": {
    • "runningStatus": "guestToolsRunning",
    • "version": "guestToolsUnmanaged",
    • "toolsStatus": false
    },
  • "serviceUser": {
    • "status": true,
    • "lastCheckedAt": "2024-01-01T10:00:00Z"
    },
  • "cpu": 4,
  • "ram": 8,
  • "cpuHotAddEnabled": true,
  • "ramHotAddEnabled": true,
  • "cpuHotRemoveEnabled": false,
  • "cpuCoresPerSocket": 2,
  • "notes": "This is a test VM.",
  • "isDraas": false,
  • "isSetInfluxCredentials": true,
  • "isRestoring": false,
  • "snapshotsCount": 3,
  • "isPoweredOn": true,
  • "cdRom": {
    • "label": "CD/DVD Drive 1",
    • "isoName": "Ubuntu.iso",
    • "key": 3000,
    • "controllerKey": 200
    },
  • "cdRoms": [
    • {
      • "label": "CD/DVD Drive 1",
      • "isoName": "Ubuntu.iso",
      • "key": 3000,
      • "controllerKey": 200
      }
    ],
  • "storages": [
    • {
      • "id": "663-2000",
      • "type": "ssd",
      • "name": "Hard disk 1",
      • "size": 100,
      • "unitNumber": 0
      }
    ],
  • "networks": [
    • {
      • "unitNumber": 7,
      • "controllerKey": 100
      }
    ],
  • "uptime": 48,
  • "systemStatusColor": "green",
  • "deletedAt": "2024-01-01T12:00:00Z",
  • "tenant": {
    • "identifier": "abc123def456",
    • "name": "Tenant Name"
    },
  • "template": {
    • "identifier": "abc123def456",
    • "type": "Linux",
    • "editNetworkAllowed": true,
    • "extendPartitionAllowed": true,
    • "hasServiceUser": true,
    • "instructions": "Follow the installation steps provided in the documentation."
    },
  • "user": {
    • "identifier": "user123",
    • "fullName": "John Doe",
    • "name": "John",
    • "surname": "Doe"
    },
  • "cloud": {
    • "id": 5,
    • "identifier": "cloud123",
    • "name": "My Cloud",
    • "type": "public"
    },
  • "labels": [
    • {
      • "id": 1,
      • "name": "Production",
      • "tenantName": "Tenant Name",
      • "textColor": "#FFFFFF",
      • "backgroundColor": "#000000",
      • "colorId": 1
      }
    ],
  • "autoShutdown": {
    • "id": 123,
    • "status": true,
    • "mondayOn": "18:00:00",
    • "mondayOff": "08:00:00",
    • "tuesdayOn": "18:00:00",
    • "tuesdayOff": "08:00:00",
    • "wednesdayOn": "18:00:00",
    • "wednesdayOff": "08:00:00",
    • "thursdayOn": "18:00:00",
    • "thursdayOff": "08:00:00",
    • "fridayOn": "18:00:00",
    • "fridayOff": "08:00:00",
    • "saturdayOn": "18:00:00",
    • "saturdayOff": "08:00:00",
    • "sundayOn": "18:00:00",
    • "sundayOff": "08:00:00"
    }
}

Delete Device

Delete Device.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Responses

Response samples

Content type
application/json
{
  • "message": "Server has been deleted."
}

Update Device

Update Device.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

displayName
required
string <= 100 characters

The name of the device.

Responses

Request samples

Content type
application/json
{
  • "displayName": "Development VM"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "displayName": "my-device",
    • "hostName": "my-device",
    • "createdAt": "2024-03-19T17:24:26+01:00"
    },
  • "message": "Device name is updated"
}

Get list of Devices

Get list of Devices.

Authorizations:
service_token
query Parameters
tenantIds[]
string
Example: tenantIds[]=a1b2c3d4e5f6&tenantIds[]=asd123zxc456&tenantIds[]=qwerty123455

An set of tenant IDs to filter the results.

search
string
Example: search=example search

Search query to filter results based on keywords.

sort
string
Example: sort=created_at

The field by which the results should be sorted.

order
string
Enum: "asc" "desc"
Example: order=asc

The sorting order (asc or desc).

perPage
integer
Example: perPage=10

The number of items to display per page.

page
integer
Example: page=1

The page number to retrieve.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "abc123abc456",
      • "displayName": "New VM",
      • "hostName": "vm-hostname",
      • "createdBy": "John Doe",
      • "createdAt": "2024-01-01T12:00:00Z",
      • "guestOs": "Ubuntu 20.04 LTS",
      • "cpu": 4,
      • "ram": 8,
      • "isPoweredOn": true,
      • "tenant": {
        • "identifier": "abc123def456",
        • "name": "Tenant A"
        },
      • "cloud": {
        • "identifier": "abc123abc456",
        • "name": "Cloud name",
        • "type": "private"
        },
      • "template": {
        • "type": "Linux"
        },
      • "backup": "Daily 7 days backup"
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "from": 1,
    • "lastPage": 13,
    • "perPage": 5,
    • "to": 5,
    • "total": 64
    }
}

Create Device

Create a new Device.

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

displayName
required
string <= 100 characters

The name of the device.

hostName
required
string <= 100 characters

The hostname of the device.

isHostnameVmName
boolean

If true, the remote name will have hostname prefix (for private clouds only)

cpu
required
integer [ 1 .. 16 ]

Number of CPU cores to allocate to the virtual machine (1-16).

ram
required
integer [ 1 .. 64 ]

Amount of RAM in GB to allocate to the virtual machine (1-64 GB).

tenantIdentifier
required
string

Identifier for the tenant to whom the virtual machine belongs.

templateId
string or null

ID of the template used to create the virtual machine. Required unless 'isoId' is provided.

isoId
string or null

ID of the ISO file used to create the virtual machine. Required unless 'templateId' is provided.

unattendedInstall
boolean or null

Create the device for an unattended (automated) ISO installation. Requires 'isoId', at least one network, and 'password'; cannot be combined with 'templateId' or 'cloudInit'.

When enabled, the device is created powered off with a second, empty CD-ROM drive attached, and the interactive-install provisioning steps (automatic shutdown and guest OS identifier change) are skipped. The caller is expected to mount auto-install media (e.g. an OEMDRV-labelled Kickstart CD for RHEL-family distributions) on the second CD-ROM drive via PUT /devices/{device_id}/iso and then power the device on.

The unattended installer must set the device's assigned static IP address (there is no DHCP), configure the root password to the same value as 'password', and install open-vm-tools so the platform can manage the guest after installation.

Array of objects or null

Array of network configurations for the virtual machine.

diskSize
required
integer

Size of the primary disk in GB.

swapDiskSize
integer

Size of the swap disk in GB. Required without cloudInit.

password
string

Password for the virtual machine's root or administrator user. Must meet specific complexity rules. Required without cloudInit.

passwordConfirmation
string

Password confirmation. Must match the 'password' field.

sendEmail
boolean or null

Option to send an email notification upon successful virtual machine creation.

backupJobId
integer or null

Optional ID for the backup job, if applicable.

scriptId
string or null

Optional ID of the script to be executed during the virtual machine setup.

sshKeyId
string or null

Optional SSH key identifier (from the SSH key endpoints, not a numeric ID). The key is installed for the template's default user. On cloud-init templates it is delivered via the cloud-init metadata (public-keys-data); the user data is not modified. Not supported on Ignition templates: returns 422, add the key to passwd.users in the Ignition config instead.

isMonitoring
boolean or null

Whether monitoring should be enabled for the virtual machine.

object or null

Cloud-init configuration for the virtual machine.

cpuHotAdd
boolean or null

Enable CPU hot-add for the virtual machine during creation. Disabled by default.

ramHotAdd
boolean or null

Enable RAM hot-add for the virtual machine during creation. Disabled by default.

Responses

Request samples

Content type
application/json
{
  • "displayName": "Development VM",
  • "hostName": "dev-vm1",
  • "isHostnameVmName": false,
  • "cpu": 4,
  • "ram": 8,
  • "tenantIdentifier": "abs123abs456",
  • "templateId": "abc456abc789",
  • "isoId": null,
  • "networks": [
    • {
      • "networkId": "zxy123zxy456",
      • "connectOnPowerOn": true,
      • "ip": "192.168.1.100",
      • "ipId": null
      }
    ],
  • "diskSize": 100,
  • "swapDiskSize": 10,
  • "password": "ComplexP@ssw0rd",
  • "passwordConfirmation": "ComplexP@ssw0rd",
  • "sendEmail": false,
  • "backupJobId": 45,
  • "scriptId": "301",
  • "sshKeyId": "otf123abc"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "displayName": "my-device",
    • "hostName": "my-device",
    • "createdAt": "2024-03-19T17:24:26+01:00"
    },
  • "message": "Device is creating..."
}

Clone Device

Clone existing Device.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

tenantId
required
string

The identifier of the tenant.

displayName
required
string <= 100 characters

The display name of the virtual machine, up to 100 characters.

hostName
required
string <= 100 characters

The hostname of the virtual machine, up to 100 characters.

snapshot
string or null

The identifier of the snapshot to clone from. If omitted or null, the device is cloned from its current state.

withoutNics
boolean

Flag indicating if the VM should be configured without network interfaces (NICs).

withoutCustomization
boolean
Default: false

Clone as an exact copy, skipping guest customization entirely. The clone keeps the source's hostname, in-guest IP configuration, SID and all passwords, and no post-clone guest configuration runs (so no source credential is required). The platform still reserves the requested networks IPs; the guest keeps using the source's IP until it is changed inside the VM — do not run the source and the clone simultaneously on the same network.

password
string or null

New guest password applied by the clone customization. Required for Windows devices unless withoutCustomization is true: Sysprep always writes the Administrator password (omitting it would blank the account), so a customized Windows clone must be given one explicitly. Optional for Linux devices: when set, root is changed to this password; when omitted, the clone keeps the source's root password. Must be 6-128 characters and include a number, a lowercase and an uppercase letter.

Array of objects

Array of network configurations. Required if 'withoutNics' is false.

Responses

Request samples

Content type
application/json
{
  • "tenantId": "cde123cde456",
  • "displayName": "Cloned VM",
  • "hostName": "cloned-vm-host",
  • "withoutNics": false,
  • "networks": [
    • {
      • "networkId": "zxy123zxy456",
      • "ip": "192.168.0.101"
      }
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "displayName": "my-device",
    • "hostName": "my-device",
    • "createdAt": "2024-03-19T17:24:26+01:00"
    },
  • "message": "Device is cloning..."
}

Start Device

Start Device.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Responses

Response samples

Content type
application/json
{
  • "message": "Server is starting."
}

Stop Device

Stop Device.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Responses

Response samples

Content type
application/json
{
  • "message": "Server is being stopped."
}

Restart Device

Restart Device.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Responses

Response samples

Content type
application/json
{
  • "message": "Server is rebooting."
}

Shutdown Device

Shutdown Device.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Responses

Response samples

Content type
application/json
{
  • "message": "Server is shutting down."
}

Update Device Hardware

Update Device Hardware.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

cpu
integer [ 1 .. 16 ]

Number of CPU cores to allocate to the virtual machine (1-16). Required unless 'ram' is provided.

ram
integer [ 1 .. 64 ]

Amount of RAM in GB to allocate to the virtual machine (1-128 GB). Required unless 'cpu' is provided.

Responses

Request samples

Content type
application/json
{
  • "cpu": 2,
  • "ram": 4
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "displayName": "my-device",
    • "hostName": "my-device",
    • "createdAt": "2024-03-19T17:24:26+01:00"
    },
  • "message": "Server is upgrading..."
}

Add Device Disk

Add Device Disk.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

size
required
integer >= 1

The new size of the disk in GB. Must be greater than or equal to 1.

isHdd
boolean or null

Specifies if the disk is an HDD.

Responses

Request samples

Content type
application/json
{
  • "size": 10,
  • "isHdd": true
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "displayName": "my-device",
    • "hostName": "my-device",
    • "createdAt": "2024-03-19T17:24:26+01:00"
    },
  • "message": "Server is adding the new disk. VM reboot may be needed to see new disk."
}

Update Device Disk

Update Device Disk.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

diskId
required
string

The unique identifier of the disk to be extended.

size
required
integer >= 1

The new size of the disk in GB. Must be greater than or equal to 1.

extendPartition
required
boolean

Flag indicating if the partition should be extended.

createSnapshot
boolean

Flag indicating if a snapshot should be created. Required if extendPartition is true.

Responses

Request samples

Content type
application/json
{
  • "diskId": "2441-2001",
  • "size": 10,
  • "extendPartition": true,
  • "createSnapshot": true
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "displayName": "my-device",
    • "hostName": "my-device",
    • "createdAt": "2024-03-19T17:24:26+01:00"
    },
  • "message": "Server is being upgraded."
}

Delete Device Disk

Delete Device Disk.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

diskId
required
string

The unique identifier of the disk to be deleted.

Responses

Request samples

Content type
application/json
{
  • "diskId": "2441-2001"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "displayName": "my-device",
    • "hostName": "my-device",
    • "createdAt": "2024-03-19T17:24:26+01:00"
    },
  • "message": "Server is deleting the disk. VM reboot may be needed to see the changes."
}

Add Device Network

Add Device Network.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

networkId
required
string

The unique ID of the network to which the virtual machine will connect.

Responses

Request samples

Content type
application/json
{
  • "networkId": "zxy123zxy456"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "displayName": "my-device",
    • "hostName": "my-device",
    • "createdAt": "2024-03-19T17:24:26+01:00"
    },
  • "message": "Server is adding the new NIC..."
}

Update Device Network

Update Device Network.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

One of
networkId
required
string

The unique identifier of the network.

unitNumber
required
integer

The unit number associated with this network.

primaryIp
required
string <ipv4>

The primary IPv4 address. Required if 'primaryIpId' is not provided.

primaryIpId
string

The identifier for the primary IP. Required if 'primaryIp' is not provided.

secondaryIps
Array of strings <ipv4> [ items <ipv4 > ]

An optional list of secondary IPv4 addresses.

isDefault
required
boolean

Indicates if this is the default network.

isConnected
required
boolean

Indicates if the network is currently connected.

isConnectedOnPowerOn
required
boolean

Indicates if the network should connect on power-on.

editNetwork
required
boolean

Indicates if the network configuration is being edited.

isWithReboot
required
boolean

Indicates if the device should be rebooted.

Responses

Request samples

Content type
application/json
{
  • "networkId": "zxy123zxy456",
  • "unitNumber": 1,
  • "primaryIp": "192.168.1.10",
  • "secondaryIps": [
    • "192.168.1.11",
    • "192.168.1.12"
    ],
  • "isDefault": true,
  • "isConnected": true,
  • "isConnectedOnPowerOn": true,
  • "editNetwork": false,
  • "isWithReboot": true
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "displayName": "my-device",
    • "hostName": "my-device",
    • "createdAt": "2024-03-19T17:24:26+01:00"
    },
  • "message": "Network has been changed successfully. New IP configuration will appear on the device."
}

Delete Device Network

Delete Device Network.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

key
required
integer

The unique identifier of the network interface to be deleted.

Responses

Request samples

Content type
application/json
{
  • "key": 4001
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "displayName": "my-device",
    • "hostName": "my-device",
    • "createdAt": "2024-03-19T17:24:26+01:00"
    },
  • "message": "Server is deleting the NIC..."
}

Mount Device ISO

Mount an ISO on the device. The backend automatically selects the first empty CD-ROM drive; returns 422 if every drive is occupied.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

isoId
required
string

The unique identifier of the ISO.

Responses

Request samples

Content type
application/json
{
  • "isoId": "otf123abc"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "displayName": "my-device",
    • "hostName": "my-device",
    • "createdAt": "2024-03-19T17:24:26+01:00"
    },
  • "message": "ISO successfully mounted."
}

Unmount Device ISO

Unmount the ISO from the device. The backend detaches every CD-ROM drive that currently has an ISO mounted; no request body is required. Returns 422 if no ISO is mounted.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Responses

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "displayName": "my-device",
    • "hostName": "my-device",
    • "createdAt": "2024-03-19T17:24:26+01:00"
    },
  • "message": "ISO has been unmounted."
}

Get Device SSH keys

Get Device SSH keys.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Responses

Response samples

Content type
application/json
[
  • {
    • "identifier": "abc123abc456",
    • "name": "my-ssh-key",
    • "createdAt": "2024-03-19T17:24:26+01:00",
    • "sshKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDVnEqbeTlrb8jLFyzsKtXfGGnM2P4Ey1bksBDeWxdKdFOV4xGzUgT4CbC7BQOhrH/QqmbmB1Vd6uALDziULfFKu5oLgEBt5wMGECmYQHqBMR9Eb8IqBp0Y5WbsUqF8GLmUgbzALr+fXpP9YEFNSq3xj7G7cF4WmX8D/NzKMH6+1JxFlzpzGgLe8FS3Ycjk+j0YLeJ+7vV4tSfyk+It8kplbJeDKV1RqPhIWjmrAbHX/cw7glN5vLWejCWJr8DpPbJXv5OhtFOfaD4t5Gj4zM63+UQ45QnyA33WJwN2CqHFzR6Dkw",
    • "createdBy": "John Doe"
    }
]

Add Device SSH Key

Add Device SSH key.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

sshKeyId
required
string

The unique identifier of the SSH key.

Responses

Request samples

Content type
application/json
{
  • "sshKeyId": "otf123abc"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "displayName": "my-device",
    • "hostName": "my-device",
    • "createdAt": "2024-03-19T17:24:26+01:00"
    },
  • "message": "Key successfully added."
}

Get Device Extra config

Get Device Extra config.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

query Parameters
key
required
string
Example: key=guestinfo.data

The key of the device to retrieve the extra configuration.

Responses

Response samples

Content type
application/json
{
  • "guestinfo.data": true
}

Update Device Extra Config

Update Device Extra Config.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

key
string

The key of the device to update the extra configuration. Should start with 'guestinfo' or 'test'.

value
string

The new value of the key.

Responses

Request samples

Content type
application/json
{
  • "key": "guestinfo.data",
  • "value": "FALSE"
}

Response samples

Content type
application/json
{
  • "message": "guestinfo.data:test is updated"
}

Change Device Owner

Changes the owner of a device to a new tenant. Optionally reassigns IP addresses within the target tenant's networks. If networks is not provided, the new tenant must already have access to all networks the device is currently connected to.

For Linux devices where the template allows direct IP updates, the IP configuration will be applied automatically. Otherwise, a manual IP update on the server will be required.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

newTenantIdentifier
required
string

The identifier of the new tenant that will become the device owner.

Array of objects

Optional array of network/IP assignments for the device after tenant change. Must include all device networks. If omitted, the new tenant must already have access to all existing device networks.

Responses

Request samples

Content type
application/json
{
  • "newTenantIdentifier": "abc123abc456",
  • "networks": [
    • {
      • "identifier": "abc123abc456",
      • "ip": "10.0.1.100"
      }
    ]
}

Response samples

Content type
application/json
{
  • "message": "Device owner has been changed."
}

Edit Hotplug Options

Updates the CPU and RAM hot-add (hotplug) settings for a device. Hot-add allows adding CPU or RAM resources to a running virtual machine without requiring a restart.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json. At least one of cpuHotAdd or ramHotAdd must be provided.

cpuHotAdd
boolean

Enable CPU hot-add for the device. Required if ramHotAdd is not provided.

ramHotAdd
boolean

Enable RAM hot-add for the device. Required if cpuHotAdd is not provided.

Responses

Request samples

Content type
application/json
{
  • "cpuHotAdd": true,
  • "ramHotAdd": false
}

Response samples

Content type
application/json
{
  • "message": "Hotplug options is updating..."
}

Update Device Notes

Update notes for a device.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

notes
string or null <= 512 characters

Notes for the device. Set to null to leave unchanged.

Responses

Request samples

Content type
application/json
{
  • "notes": "This is a production server."
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Update Device Remote Name Prefix

Update the remote name prefix of a device.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

displayName
required
string <= 100 characters

The new display name for the device.

Responses

Request samples

Content type
application/json
{
  • "displayName": "my-device-prefix"
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Update Device Service User

Update service user credentials for a device.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

user
string

The service user username.

password
string <password>

The service user password.

Responses

Request samples

Content type
application/json
{
  • "user": "serviceuser",
  • "password": "secretpassword"
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Mount VMware Tools

Mount VMware Tools ISO on a device.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Responses

Response samples

Content type
application/json
{
  • "message": "Success"
}

Unmount device tools

Unmount device tools from a device. Unmounting tools is only supported for Windows VMs; for any other OS type the request fails with a 400 response.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Responses

Response samples

Content type
application/json
{
  • "message": "Success"
}

Attach Label to Device

Attach a label to a device.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

labelId
integer or null

The ID of the label to attach.

Responses

Request samples

Content type
application/json
{
  • "labelId": 5
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Detach Label from Device

Detach a label from a device.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

labelId
integer or null

The ID of the label to detach.

Responses

Request samples

Content type
application/json
{
  • "labelId": 5
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Change Device Disk Type

Change the disk type of a device disk.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

diskId
required
string

The identifier of the disk to change type for.

Responses

Request samples

Content type
application/json
{
  • "diskId": "disk-001"
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Update Device Default Gateway

Update the default gateway for a device network interface.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

ipAddr
required
string <ipv4>

The IP address of the new default gateway.

nicunit
required
integer

The network interface unit number.

Responses

Request samples

Content type
application/json
{
  • "ipAddr": "192.168.1.1",
  • "nicunit": 0
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Check Device Service User

Check if a service user is installed and accessible on the device.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Responses

Response samples

Content type
application/json
true

Install Device Service User

Install a service user on the device using provided credentials.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

user
required
string

The OS username with sudo/admin privileges.

password
required
string <password>

The password for the specified user.

Responses

Request samples

Content type
application/json
{
  • "user": "admin",
  • "password": "mypassword"
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Run Script on Device

Execute a script on a device.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

scriptId
required
string

The identifier of the script to run.

scriptParams
Array of strings or null

Optional parameters for the script.

scriptArgs
string or null

Optional arguments to pass to the script.

osType
string or null
Enum: "Linux" "Windows" null

The OS type of the device. Defaults to the device's own template OS type if omitted.

Responses

Request samples

Content type
application/json
{
  • "scriptId": "abc123abc456",
  • "scriptParams": [
    • "param1",
    • "param2"
    ],
  • "scriptArgs": "--verbose",
  • "osType": "Linux"
}

Response samples

Content type
application/json
{
  • "message": "Script ran successfully."
}

Get Device Auto Shutdown

Get the auto startup/shutdown schedule for a device.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "status": true,
  • "mondayOn": "08:00",
  • "mondayOff": "18:00",
  • "tuesdayOn": "08:00",
  • "tuesdayOff": "18:00",
  • "wednesdayOn": "08:00",
  • "wednesdayOff": "18:00",
  • "thursdayOn": "08:00",
  • "thursdayOff": "18:00",
  • "fridayOn": "08:00",
  • "fridayOff": "18:00",
  • "saturdayOn": null,
  • "saturdayOff": null,
  • "sundayOn": null,
  • "sundayOff": null
}

Update Device Auto Shutdown

Update the auto startup/shutdown schedule for a device.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

status
required
boolean

Enable or disable the auto shutdown schedule.

startup
string or null^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$

Daily startup time in HH:MM format.

shutdown
string or null^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$

Daily shutdown time in HH:MM format.

mondayOn
boolean or null

Enable startup on Monday.

mondayOff
boolean or null

Enable shutdown on Monday.

tuesdayOn
boolean or null

Enable startup on Tuesday.

tuesdayOff
boolean or null

Enable shutdown on Tuesday.

wednesdayOn
boolean or null

Enable startup on Wednesday.

wednesdayOff
boolean or null

Enable shutdown on Wednesday.

thursdayOn
boolean or null

Enable startup on Thursday.

thursdayOff
boolean or null

Enable shutdown on Thursday.

fridayOn
boolean or null

Enable startup on Friday.

fridayOff
boolean or null

Enable shutdown on Friday.

saturdayOn
boolean or null

Enable startup on Saturday.

saturdayOff
boolean or null

Enable shutdown on Saturday.

sundayOn
boolean or null

Enable startup on Sunday.

sundayOff
boolean or null

Enable shutdown on Sunday.

Responses

Request samples

Content type
application/json
{
  • "status": true,
  • "startup": "08:00",
  • "shutdown": "18:00",
  • "mondayOn": true,
  • "mondayOff": true,
  • "tuesdayOn": true,
  • "tuesdayOff": true,
  • "wednesdayOn": true,
  • "wednesdayOff": true,
  • "thursdayOn": true,
  • "thursdayOff": true,
  • "fridayOn": true,
  • "fridayOff": true,
  • "saturdayOn": false,
  • "saturdayOff": false,
  • "sundayOn": false,
  • "sundayOff": false
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "status": true,
    • "mondayOn": "08:00",
    • "mondayOff": "18:00",
    • "tuesdayOn": "08:00",
    • "tuesdayOff": "18:00",
    • "wednesdayOn": "08:00",
    • "wednesdayOff": "18:00",
    • "thursdayOn": "08:00",
    • "thursdayOff": "18:00",
    • "fridayOn": "08:00",
    • "fridayOff": "18:00",
    • "saturdayOn": null,
    • "saturdayOff": null,
    • "sundayOn": null,
    • "sundayOff": null
    },
  • "message": "Auto startup/shutdown settings have been updated."
}

Get Device Current Usage

Get the current resource usage statistics for a device.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Responses

Response samples

Content type
application/json
{
  • "CPU": {
    • "onHours": 0,
    • "offHours": 720,
    • "totalHours": 720,
    • "description": "0 CPU Hours",
    • "pricing": {
      • "outgoing": {
        • "hourly": 0.02,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "partnerDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        },
      • "incoming": {
        • "hourly": 0,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        }
      }
    },
  • "RAM": {
    • "onHours": 0,
    • "offHours": 720,
    • "totalHours": 720,
    • "description": "0 RAM Hours",
    • "pricing": {
      • "outgoing": {
        • "hourly": 0.01,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "partnerDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        },
      • "incoming": {
        • "hourly": 0,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        }
      }
    },
  • "SSD": {
    • "onHours": 4320,
    • "offHours": null,
    • "totalHours": 4320,
    • "description": "4320 GB SSD Hours",
    • "pricing": {
      • "outgoing": {
        • "hourly": 0.0003,
        • "subtotal": 1.296,
        • "tenantDiscount": 0,
        • "partnerDiscount": 0,
        • "total": 1.296,
        • "baseFee": 0
        },
      • "incoming": {
        • "hourly": 0,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        }
      }
    },
  • "HDD": {
    • "onHours": 0,
    • "offHours": null,
    • "totalHours": 0,
    • "description": "0 GB HDD Hours",
    • "pricing": {
      • "outgoing": {
        • "hourly": 0.0001,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "partnerDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        },
      • "incoming": {
        • "hourly": 0,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        }
      }
    },
  • "Snapshot": {
    • "onHours": 50.62536,
    • "offHours": null,
    • "totalHours": 50.62536,
    • "description": "50.63 GB Snapshot Hours",
    • "pricing": {
      • "outgoing": {
        • "hourly": 0.01,
        • "subtotal": 0.5062536,
        • "tenantDiscount": 0,
        • "partnerDiscount": 0,
        • "total": 0.5062536,
        • "baseFee": 0
        },
      • "incoming": {
        • "hourly": 0,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        }
      }
    },
  • "Licenses": {
    • "onHours": 0,
    • "offHours": null,
    • "totalHours": 0,
    • "description": "0 Windows License Hours",
    • "pricing": {
      • "outgoing": {
        • "hourly": 0.67,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "partnerDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        },
      • "incoming": {
        • "hourly": 0,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        }
      }
    },
  • "Firewall": {
    • "onHours": 0,
    • "offHours": null,
    • "totalHours": 0,
    • "description": "0 Firewall Hours",
    • "pricing": {
      • "outgoing": {
        • "hourly": 0.014,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "partnerDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        },
      • "incoming": {
        • "hourly": 0,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        }
      }
    },
  • "Load Balancer": {
    • "onHours": 0,
    • "offHours": null,
    • "totalHours": 0,
    • "description": "0 Load Balancer Hours",
    • "pricing": {
      • "outgoing": {
        • "hourly": 0.013,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "partnerDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        },
      • "incoming": {
        • "hourly": 0,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        }
      }
    },
  • "Backup": {
    • "onHours": 1440,
    • "offHours": 0,
    • "totalHours": 1440,
    • "description": "1440 GB Backup Hours",
    • "pricing": {
      • "outgoing": {
        • "hourly": 0.00015,
        • "subtotal": 0.216,
        • "tenantDiscount": 0,
        • "partnerDiscount": 0,
        • "total": 0.216,
        • "baseFee": 0
        },
      • "incoming": {
        • "hourly": 0,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        }
      }
    },
  • "S3 Storage": {
    • "onHours": null,
    • "offHours": null,
    • "totalHours": null,
    • "description": "S3 Object Storage",
    • "pricing": {
      • "outgoing": {
        • "subtotal": 0,
        • "total": 0,
        • "tenantDiscount": 0,
        • "partnerDiscount": 0
        },
      • "incoming": {
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "total": 0
        }
      }
    },
  • "Total": {
    • "description": "Total",
    • "pricing": {
      • "outgoing": {
        • "subtotal": 2.0182536,
        • "hourly": 0.73755
        }
      }
    }
}

Get Device Usage Graph Data

Get real-time resource usage graph data (CPU, RAM, disk, network) for a device, sampled at 20-second intervals over approximately the last 15 minutes.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Responses

Response samples

Content type
application/json
{
  • "labels": [
    • "2026-04-21 09:24:00",
    • "2026-04-21 09:24:20",
    • "2026-04-21 09:24:40"
    ],
  • "networkData": [
    • 0,
    • 0,
    • 0
    ],
  • "cpuData": [
    • 0,
    • 0,
    • 1
    ],
  • "ramData": [
    • 1,
    • 1,
    • 1
    ],
  • "diskData": [
    • 0,
    • 0,
    • 0
    ]
}

Get Device Historical Usage

Get the resource usage and pricing overview for a device over a given date range. Same response shape as GET /devices/{device_identifier}/usage/current, but computed from historical daily usage records for the requested period instead of the last reported live sample.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

query Parameters
startDate
string <date>
Example: startDate=2026-06-19

Start of the date range (inclusive). Defaults to one month before endDate (or today) if omitted.

endDate
string <date>
Example: endDate=2026-07-19

End of the date range (inclusive). Defaults to today if omitted.

Responses

Response samples

Content type
application/json
{
  • "CPU": {
    • "onHours": 0,
    • "offHours": 720,
    • "totalHours": 720,
    • "description": "0 CPU Hours",
    • "pricing": {
      • "outgoing": {
        • "hourly": 0.02,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "partnerDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        },
      • "incoming": {
        • "hourly": 0,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        }
      }
    },
  • "RAM": {
    • "onHours": 0,
    • "offHours": 720,
    • "totalHours": 720,
    • "description": "0 RAM Hours",
    • "pricing": {
      • "outgoing": {
        • "hourly": 0.01,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "partnerDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        },
      • "incoming": {
        • "hourly": 0,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        }
      }
    },
  • "SSD": {
    • "onHours": 4320,
    • "offHours": null,
    • "totalHours": 4320,
    • "description": "4320 GB SSD Hours",
    • "pricing": {
      • "outgoing": {
        • "hourly": 0.0003,
        • "subtotal": 1.296,
        • "tenantDiscount": 0,
        • "partnerDiscount": 0,
        • "total": 1.296,
        • "baseFee": 0
        },
      • "incoming": {
        • "hourly": 0,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        }
      }
    },
  • "HDD": {
    • "onHours": 0,
    • "offHours": null,
    • "totalHours": 0,
    • "description": "0 GB HDD Hours",
    • "pricing": {
      • "outgoing": {
        • "hourly": 0.0001,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "partnerDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        },
      • "incoming": {
        • "hourly": 0,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        }
      }
    },
  • "Snapshot": {
    • "onHours": 50.62536,
    • "offHours": null,
    • "totalHours": 50.62536,
    • "description": "50.63 GB Snapshot Hours",
    • "pricing": {
      • "outgoing": {
        • "hourly": 0.01,
        • "subtotal": 0.5062536,
        • "tenantDiscount": 0,
        • "partnerDiscount": 0,
        • "total": 0.5062536,
        • "baseFee": 0
        },
      • "incoming": {
        • "hourly": 0,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        }
      }
    },
  • "Licenses": {
    • "onHours": 0,
    • "offHours": null,
    • "totalHours": 0,
    • "description": "0 Windows License Hours",
    • "pricing": {
      • "outgoing": {
        • "hourly": 0.67,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "partnerDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        },
      • "incoming": {
        • "hourly": 0,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        }
      }
    },
  • "Firewall": {
    • "onHours": 0,
    • "offHours": null,
    • "totalHours": 0,
    • "description": "0 Firewall Hours",
    • "pricing": {
      • "outgoing": {
        • "hourly": 0.014,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "partnerDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        },
      • "incoming": {
        • "hourly": 0,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        }
      }
    },
  • "Load Balancer": {
    • "onHours": 0,
    • "offHours": null,
    • "totalHours": 0,
    • "description": "0 Load Balancer Hours",
    • "pricing": {
      • "outgoing": {
        • "hourly": 0.013,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "partnerDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        },
      • "incoming": {
        • "hourly": 0,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        }
      }
    },
  • "Backup": {
    • "onHours": 1440,
    • "offHours": 0,
    • "totalHours": 1440,
    • "description": "1440 GB Backup Hours",
    • "pricing": {
      • "outgoing": {
        • "hourly": 0.00015,
        • "subtotal": 0.216,
        • "tenantDiscount": 0,
        • "partnerDiscount": 0,
        • "total": 0.216,
        • "baseFee": 0
        },
      • "incoming": {
        • "hourly": 0,
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "total": 0,
        • "baseFee": 0
        }
      }
    },
  • "S3 Storage": {
    • "onHours": null,
    • "offHours": null,
    • "totalHours": null,
    • "description": "S3 Object Storage",
    • "pricing": {
      • "outgoing": {
        • "subtotal": 0,
        • "total": 0,
        • "tenantDiscount": 0,
        • "partnerDiscount": 0
        },
      • "incoming": {
        • "subtotal": 0,
        • "tenantDiscount": 0,
        • "total": 0
        }
      }
    },
  • "Total": {
    • "description": "Total",
    • "pricing": {
      • "outgoing": {
        • "subtotal": 2.0182536,
        • "hourly": 0.73755
        }
      }
    }
}

Get Device Statistics

Get historical CPU and RAM usage statistics for a device, as time-series chart data over the requested time range.

Network usage is not included at these time ranges: it is only recorded by the hypervisor at its real-time statistics granularity (see GET /devices/{device_identifier}/usage/graph-data, limited to roughly the last 2 hours), not at the rolled-up "Day"/"Week" granularity backing this endpoint's statrange windows.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

query Parameters
statrange
integer
Enum: 6 12 24 48
Example: statrange=24

Time range in hours for historical data.

Responses

Response samples

Content type
application/json
{
  • "statrange": 24,
  • "usage": [
    • {
      • "time": "2026-07-19T08:00:00+02:00",
      • "cpuUsagePercent": 4,
      • "ramUsageGb": 3.5
      },
    • {
      • "time": "2026-07-19T08:30:00+02:00",
      • "cpuUsagePercent": 12,
      • "ramUsageGb": 3.6
      }
    ]
}

Networks

Networks are the virtual networks that connect your devices.

List Networks

Retrieve a paginated list of networks.

Authorizations:
service_token
query Parameters
perPage
integer
Example: perPage=10

The numbers of items to return

sort
string
Example: sort=name

Sorting parameter

search
string
Example: search=private network 10

Searching string

tenantIds[]
Array of integers

A set of tenant IDs to filter the results by. The caller must have access to each tenant listed.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "abc123abc456",
      • "name": "VLAN 8080 cloud 8 network",
      • "network": "10.0.0.0",
      • "type": "LAN",
      • "networkSize": 24,
      • "clouds": [
        • {
          • "identifier": "1a2b3c4d5e6f",
          • "name": "Aargau",
          • "type": "public"
          }
        ],
      • "owner": {
        • "identifier": "abc123abc456",
        • "name": "Company Inc."
        }
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "from": 1,
    • "lastPage": 13,
    • "perPage": 5,
    • "to": 5,
    • "total": 64
    }
}

List Networks With Available IPs

Retrieve every accessible network together with its available (unassigned) IP addresses. Unlike GET /networks, this endpoint is not paginated.

Authorizations:
service_token
query Parameters
cloudIdentifier
string
Example: cloudIdentifier=a1b2c3d4e5f6

Cloud identifier to filter networks by. If not specified, networks from all accessible clouds are returned.

tenantIds[]
Array of integers

A set of tenant IDs to filter the results by. The caller must have access to each tenant listed.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "abc123abc456",
      • "name": "VLAN 8080 cloud 8 network",
      • "network": "10.0.0.0",
      • "type": "LAN",
      • "networkSize": 24,
      • "availableIps": [
        • {
          • "identifier": "a1b2c3d4e5f6",
          • "ip": "10.0.0.20"
          }
        ]
      }
    ]
}

Get network

Retrieve network information.

Authorizations:
service_token
path Parameters
network_identifier
required
string
Example: a1b2c3d4e5f6

Network identifier

Responses

Response samples

Content type
application/json
{
  • "identifier": "abc123abc456",
  • "name": "VLAN 8080 cloud 8 network",
  • "network": "10.0.0.0",
  • "gateway": "10.0.0.1",
  • "dns1": "8.8.8.8",
  • "dns2": "8.8.4.4",
  • "type": "LAN",
  • "networkSize": 24,
  • "isFree": true,
  • "isStretched": false,
  • "networkSpeedValue": 1000,
  • "networkSpeedUnits": "Mbit",
  • "ips": [
    • {
      • "identifier": "a1b2c3d4e5f6",
      • "ip": "10.0.0.20"
      }
    ],
  • "clouds": [
    • {
      • "identifier": "1a2b3c4d5e6f",
      • "name": "Aargau"
      }
    ],
  • "owner": {
    • "identifier": "abc123abc456",
    • "name": "Company Inc."
    },
  • "assigned": [
    • {
      • "identifier": "abc123abc456",
      • "name": "Company Inc."
      }
    ]
}

Delete network

Delete network

Authorizations:
service_token
path Parameters
network_identifier
required
string
Example: a1b2c3d4e5f6

Network identifier

Responses

Response samples

Content type
application/json
{
  • "message": "Network has been deleted successfully"
}

Create LAN Network

Create LAN network

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

cloudIdentifier
required
string

Cloud identifier

tenantIdentifier
string

Tenant identifier

name
required
string

Network name

dns1
required
string

Primary DNS address

dns2
string

Secondary DNS address

gateway
required
string

Default gateway address

network
required
string

Network

networkSize
required
integer

Network size

networkSpeedValue
required
integer or null
Enum: 1000 10000

Network speed

isStretched
boolean or null

Whether a network is stretched

cloudForStretching
string or null

Cloud identifier to which you want to stretch a network

Responses

Request samples

Content type
application/json
{
  • "cloudIdentifier": "a1b2c3d4f5e6",
  • "tenantIdentifier": "a1b2c3d4f5e6",
  • "name": "Local network",
  • "dns1": "8.8.8.8",
  • "dns2": "8.8.4.4",
  • "gateway": "10.0.0.1",
  • "network": "10.0.0.0",
  • "networkSize": 24,
  • "networkSpeedValue": 500,
  • "isStretched": false,
  • "cloudForStretching": "a1b2c3d4f5e6"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "a1b2c3d4f5e6",
    • "name": "My test network",
    • "dns1": "8.8.8.8",
    • "dns2": "8.8.4.4",
    • "gateway": "10.0.0.1",
    • "network": "10.0.0.0",
    • "networkSize": 24,
    • "networkSpeedValue": 1000,
    • "owner": {
      • "identifier": "abc123abc456",
      • "name": "Company Inc."
      }
    },
  • "message": "LAN network has been successfully added."
}

Update LAN Network

Update LAN network

Authorizations:
service_token
path Parameters
network_identifier
required
string
Example: a1b2c3d4e5f6

Network identifier

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
string

Network name

dns1
string

Primary DNS address

dns2
string

Secondary DNS address. Can be an empty string "" if not needed

gateway
string

Default gateway address

network
string

Network

networkSpeedValue
integer or null
Enum: 1000 10000

Network speed

Responses

Request samples

Content type
application/json
{
  • "name": "Local network",
  • "dns1": "8.8.8.8",
  • "dns2": "8.8.4.4",
  • "gateway": "10.0.0.1",
  • "network": "10.0.0.0",
  • "networkSpeedValue": 1000
}

Response samples

Content type
application/json
{
  • "identifier": "abc123abc456",
  • "name": "VLAN 8080 cloud 8 network",
  • "network": "10.0.0.0",
  • "gateway": "10.0.0.1",
  • "dns1": "8.8.8.8",
  • "dns2": "8.8.4.4",
  • "type": "LAN",
  • "networkSize": 24,
  • "isFree": true,
  • "isStretched": false,
  • "networkSpeedValue": 1000,
  • "networkSpeedUnits": "Mbit",
  • "ips": [
    • {
      • "identifier": "a1b2c3d4e5f6",
      • "ip": "10.0.0.20"
      }
    ],
  • "clouds": [
    • {
      • "identifier": "1a2b3c4d5e6f",
      • "name": "Aargau"
      }
    ],
  • "owner": {
    • "identifier": "abc123abc456",
    • "name": "Company Inc."
    },
  • "assigned": [
    • {
      • "identifier": "abc123abc456",
      • "name": "Company Inc."
      }
    ]
}

Create WAN Network

Create WAN network

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

cloudIdentifier
required
string

Cloud identifier

tenantIdentifier
string

Tenant identifier

name
required
string

Network name

networkSize
required
integer

Network size

networkSpeedValue
required
integer or null
Enum: 250 500 1000 10000

Network speed

isStretched
boolean or null

Whether a network is stretched

cloudForStretching
string or null

Cloud identifier to which you want to stretch a network

Responses

Request samples

Content type
application/json
{
  • "cloudIdentifier": "a1b2c3d4f5e6",
  • "tenantIdentifier": "a1b2c3d4f5e6",
  • "name": "Local network",
  • "networkSize": 29,
  • "networkSpeedValue": 500,
  • "isStretched": false,
  • "cloudForStretching": "a1b2c3d4f5e6"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "a1b2c3d4f5e6",
    • "name": "My test network",
    • "dns1": "8.8.8.8",
    • "dns2": "8.8.4.4",
    • "gateway": "10.0.0.1",
    • "network": "10.0.0.0",
    • "networkSize": 24,
    • "networkSpeedValue": 1000,
    • "owner": {
      • "identifier": "abc123abc456",
      • "name": "Company Inc."
      }
    },
  • "message": "WAN network has been successfully added."
}

Update WAN Network

Update WAN network

Authorizations:
service_token
path Parameters
network_identifier
required
string
Example: a1b2c3d4e5f6

Network identifier

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
string

Network name

dns1
string

Primary DNS address

dns2
string

Secondary DNS address. Can be an empty string "" if not needed

gateway
string

Default gateway address

networkSpeedValue
integer or null
Enum: 250 500 1000 10000

Network speed

Responses

Request samples

Content type
application/json
{
  • "name": "Local network",
  • "dns1": "8.8.8.8",
  • "dns2": "8.8.4.4",
  • "gateway": "10.0.0.1",
  • "networkSpeedValue": 500
}

Response samples

Content type
application/json
{
  • "identifier": "abc123abc456",
  • "name": "VLAN 8080 cloud 8 network",
  • "network": "10.0.0.0",
  • "gateway": "10.0.0.1",
  • "dns1": "8.8.8.8",
  • "dns2": "8.8.4.4",
  • "type": "LAN",
  • "networkSize": 24,
  • "isFree": true,
  • "isStretched": false,
  • "networkSpeedValue": 1000,
  • "networkSpeedUnits": "Mbit",
  • "ips": [
    • {
      • "identifier": "a1b2c3d4e5f6",
      • "ip": "10.0.0.20"
      }
    ],
  • "clouds": [
    • {
      • "identifier": "1a2b3c4d5e6f",
      • "name": "Aargau"
      }
    ],
  • "owner": {
    • "identifier": "abc123abc456",
    • "name": "Company Inc."
    },
  • "assigned": [
    • {
      • "identifier": "abc123abc456",
      • "name": "Company Inc."
      }
    ]
}

Delete networks IPs

Delete networks IPs

Authorizations:
service_token
path Parameters
network_identifier
required
string
Example: a1b2c3d4e5f6

Network identifier

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

ips
Array of arrays

Responses

Request samples

Content type
application/json
{
  • "ips": [
    • "a1b2c3d4f5e6",
    • "a1b2c3d4f5e6"
    ]
}

Response samples

Content type
application/json
{
  • "message": "IPs have been deleted."
}

Get networks to share

Retrieve networks that can be shared.

Authorizations:
service_token
query Parameters
tenantIdentifier
required
string
Example: tenantIdentifier=a1b2c3d4e5f6

Tenant identifier to whom network will be shared

ownerIdentifier
string
Example: ownerIdentifier=a1b2c3d4e5f6

Tenant identifier who's networks will be shared (If not specified, networks of token's user tenant will be shown)

cloudIdentifier
required
string
Example: cloudIdentifier=a1b2c3d4e5f6

Cloud identifier

Responses

Response samples

Content type
application/json
[
  • {
    • "identifier": "abc123abc456",
    • "name": "VLAN 8080 cloud 8 network",
    • "network": "10.0.0.0",
    • "type": "LAN",
    • "networkSize": 24
    }
]

Share networks

Share networks between tenants

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

cloudIdentifier
required
string

Cloud identifier

tenantIdentifier
required
string

Network name

networks
required
Array of arrays

Networks to share

Responses

Request samples

Content type
application/json
{
  • "cloudIdentifier": "a1b2c3d4f5e6",
  • "tenantIdentifier": "a1b2c3d4f5e6",
  • "networks": [
    • "a1b2c3d4f5e6",
    • "a1b2c3d4f5e6"
    ]
}

Response samples

Content type
application/json
{
  • "message": "Shared network successfully added."
}

Delete shared networks

Delete shared networks

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

networkIdentifier
required
string

Network identifier

tenantIdentifier
required
string

Tenant identifier

Responses

Request samples

Content type
application/json
{
  • "networkIdentifier": "a1b2c3d4f5e6",
  • "tenantIdentifier": "a1b2c3d4f5e6"
}

Response samples

Content type
application/json
{
  • "message": "Shared network has been removed."
}

Reserve Network IP

Reserve an IP address within a network.

Authorizations:
service_token
path Parameters
network_identifier
required
string
Example: a1b2c3d4e5f6

Network identifier

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

ip
required
string

The IP address to reserve. Must be a valid IP within the network subnet.

description
string or null

Optional description for the IP reservation.

Responses

Request samples

Content type
application/json
{
  • "ip": "10.0.0.100",
  • "description": "Reserved for load balancer"
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Release Network IP

Release a previously reserved IP address within a network.

Authorizations:
service_token
path Parameters
network_identifier
required
string
Example: a1b2c3d4e5f6

Network identifier

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

ip
required
string

The IP address to release.

Responses

Request samples

Content type
application/json
{
  • "ip": "10.0.0.100"
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Get Network Devices

Get a list of devices connected to a specific network.

Authorizations:
service_token
path Parameters
network_identifier
required
string
Example: a1b2c3d4e5f6

Network identifier

Responses

Response samples

Content type
application/json
[
  • {
    • "identifier": "a1b2c3d4e5f6",
    • "name": "my-server"
    }
]

Get Network Speeds

Get available network speed options for a given cloud and network type.

Authorizations:
service_token
query Parameters
cloudIdentifier
required
string
Example: cloudIdentifier=a1b2c3d4e5f6

Cloud identifier

type
required
string
Enum: "WAN" "LAN" "TRUNK"
Example: type=WAN

The network type to retrieve speeds for.

isStretched
required
boolean

Whether the network is stretched across multiple sites.

Responses

Response samples

Content type
application/json
[
  • {
    • "label": "1000Mbit",
    • "value": 1000
    }
]

Get Subnet Sizes

Get available subnet sizes for creating a WAN network in a given cloud and tenant.

Authorizations:
service_token
query Parameters
cloudIdentifier
required
string
Example: cloudIdentifier=a1b2c3d4e5f6

Cloud identifier

tenantIdentifier
required
string
Example: tenantIdentifier=abc123def456

Tenant identifier.

Responses

Response samples

Content type
application/json
{
  • "subnets": {
    • "dedicated": {
      • "29": "/29 (0.01 CHF/per hour)"
      },
    • "stretched": {
      • "29": "/29 (0.12 CHF/per hour)"
      }
    }
}

Templates

Templates are the base images used to create devices.

Get list of Templates

Retrieve a paginated list of general Templates. If the optional parameter tenantIdentifiers is provided, the response will include custom templates for the specified tenants.

Authorizations:
service_token
query Parameters
page
integer
Example: page=1

The page number to retrieve.

perPage
integer
Example: perPage=10

The numbers of items to return

sort
string
Enum: "name" "description" "type" "category"
Example: sort=name

Sorting parameter

search
string
Example: search=windows

Searching string

tenantIdentifiers[]
Array of strings
Example: tenantIdentifiers[]=a1b2c3d4e5f6&tenantIdentifiers[]=z9y8x7w6v5u4

An set of tenant IDs to filter the results.

cloudIdentifier
string
Example: cloudIdentifier=a1b2c3d4e5f6

The cloud identifier to filter the results.

type
string
Enum: "Linux" "Windows" "pfSense" "Sophos" "Barracuda" "ISO" "OPNsense" "SonicWALL"
Example: type=Linux

The type of the template.

isActive
boolean
Example: isActive=true

The active status of the template. Default is true.

isCustom
boolean

If true - show only custom templates. If false - show only company templates. If not provided - show all templates.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "abc123abc456",
      • "name": "pfSense CE 2.4.2",
      • "ownerTenant": "Parent/Company",
      • "cloudIdentifier": "abc123abc456",
      • "cloudInitType": "cloud-init",
      • "status": 1,
      • "description": "pfSense CE 2.4.2 Open Source Firewall",
      • "internalVersion": "1.0.0",
      • "active": true,
      • "templateType": "Custom",
      • "scriptType": "powershell",
      • "nicCountMin": 1,
      • "nicCountMax": 2,
      • "nicDescription": "NIC1 - Management",
      • "hddUnit": 0,
      • "cloudType": "public",
      • "hddMinSizeGb": 20,
      • "hasSwap": true,
      • "allowedSetPwd": true,
      • "allowedSetDisk": true,
      • "allowedUpdateIpGuest": true,
      • "allowedResizeExistingPartition": true,
      • "hasServiceUser": true,
      • "type": "Linux",
      • "category": "Firewall",
      • "nicUnit": 7,
      • "swapUnit": 1,
      • "vmdkId": "abc123abc456",
      • "vmdkSwapId": "abc123abc456",
      • "instructions": "Please follow the instructions to install the template.",
      • "powerOn": true,
      • "regExp": "^[a-zA-Z0-9]*$",
      • "regExpId": 10,
      • "createdAt": "2024-01-01T00:00:00Z",
      • "updatedAt": "2024-01-01T00:00:00Z",
      • "deletedAt": "2024-01-01T00:00:00Z"
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "from": 1,
    • "lastPage": 13,
    • "perPage": 5,
    • "to": 5,
    • "total": 64
    }
}

Create Template from device

Create a new Template from existing device.

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
required
string <= 100 characters

Template name.

description
string <= 500 characters

Template description.

tenantId
required
string

Current device owner tenant identifier.

deviceId
required
string

Source device identifier.

ownerTenantId
string

Template owner tenant identifier.

sendEmail
required
boolean

Send an email to the authenticated user once creation is complete.

guestOsType
string
Value: "linux"

Guest OS type of the source device. Set this when the source device was installed from an ISO (e.g. an unattended Packer build): without it, an ISO-built device produces a 'Custom' template that cannot be used as a base for new Linux devices (no network configuration script, no stored guest credentials). With 'linux', the resulting template is a first-class Linux template.

Responses

Request samples

Content type
application/json
{
  • "name": "pfSense CE 2.4.2",
  • "description": "pfSense CE 2.4.2 Open Source Firewall",
  • "tenantId": "abc123abc456",
  • "deviceId": "abc123abc456",
  • "ownerTenantId": "abc123abc456",
  • "sendEmail": false,
  • "guestOsType": "linux"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "name": "pfSense CE 2.4.2",
    • "ownerTenant": "Parent/Company",
    • "cloudIdentifier": "abc123abc456",
    • "cloudInitType": "cloud-init",
    • "status": 1,
    • "description": "pfSense CE 2.4.2 Open Source Firewall",
    • "internalVersion": "1.0.0",
    • "active": true,
    • "templateType": "Custom",
    • "scriptType": "powershell",
    • "nicCountMin": 1,
    • "nicCountMax": 2,
    • "nicDescription": "NIC1 - Management",
    • "hddUnit": 0,
    • "cloudType": "public",
    • "hddMinSizeGb": 20,
    • "hasSwap": true,
    • "allowedSetPwd": true,
    • "allowedSetDisk": true,
    • "allowedUpdateIpGuest": true,
    • "allowedResizeExistingPartition": true,
    • "hasServiceUser": true,
    • "type": "Linux",
    • "category": "Firewall",
    • "nicUnit": 7,
    • "swapUnit": 1,
    • "vmdkId": "abc123abc456",
    • "vmdkSwapId": "abc123abc456",
    • "instructions": "Please follow the instructions to install the template.",
    • "powerOn": true,
    • "regExp": "^[a-zA-Z0-9]*$",
    • "regExpId": 10,
    • "createdAt": "2024-01-01T00:00:00Z",
    • "updatedAt": "2024-01-01T00:00:00Z",
    • "deletedAt": "2024-01-01T00:00:00Z"
    },
  • "message": "Template created successfully."
}

Get Template

Get Template by identifier.

Authorizations:
service_token
path Parameters
template_identifier
required
string
Example: a1b2c3d4e5f6

The identifier of the template.

Responses

Response samples

Content type
application/json
{
  • "identifier": "abc123abc456",
  • "name": "pfSense CE 2.4.2",
  • "ownerTenant": "Parent/Company",
  • "cloudIdentifier": "abc123abc456",
  • "cloudInitType": "cloud-init",
  • "status": 1,
  • "description": "pfSense CE 2.4.2 Open Source Firewall",
  • "internalVersion": "1.0.0",
  • "active": true,
  • "templateType": "Custom",
  • "scriptType": "powershell",
  • "nicCountMin": 1,
  • "nicCountMax": 2,
  • "nicDescription": "NIC1 - Management",
  • "hddUnit": 0,
  • "cloudType": "public",
  • "hddMinSizeGb": 20,
  • "hasSwap": true,
  • "allowedSetPwd": true,
  • "allowedSetDisk": true,
  • "allowedUpdateIpGuest": true,
  • "allowedResizeExistingPartition": true,
  • "hasServiceUser": true,
  • "type": "Linux",
  • "category": "Firewall",
  • "nicUnit": 7,
  • "swapUnit": 1,
  • "vmdkId": "abc123abc456",
  • "vmdkSwapId": "abc123abc456",
  • "instructions": "Please follow the instructions to install the template.",
  • "powerOn": true,
  • "regExp": "^[a-zA-Z0-9]*$",
  • "regExpId": 10,
  • "createdAt": "2024-01-01T00:00:00Z",
  • "updatedAt": "2024-01-01T00:00:00Z",
  • "deletedAt": "2024-01-01T00:00:00Z"
}

Update Template

Update Template.

Authorizations:
service_token
path Parameters
template_identifier
required
string
Example: a1b2c3d4e5f6

The identifier of the template.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
string <= 100 characters

Template name.

description
string <= 500 characters

Template description.

cloudInitType
string or null
Enum: "none" "cloud-init" "ignition" null

Cloud-Init provisioning type used by the template.

Responses

Request samples

Content type
application/json
{
  • "name": "pfSense CE 2.4.2",
  • "description": "pfSense CE 2.4.2 Open Source Firewall",
  • "cloudInitType": "cloud-init"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "name": "pfSense CE 2.4.2",
    • "ownerTenant": "Parent/Company",
    • "cloudIdentifier": "abc123abc456",
    • "cloudInitType": "cloud-init",
    • "status": 1,
    • "description": "pfSense CE 2.4.2 Open Source Firewall",
    • "internalVersion": "1.0.0",
    • "active": true,
    • "templateType": "Custom",
    • "scriptType": "powershell",
    • "nicCountMin": 1,
    • "nicCountMax": 2,
    • "nicDescription": "NIC1 - Management",
    • "hddUnit": 0,
    • "cloudType": "public",
    • "hddMinSizeGb": 20,
    • "hasSwap": true,
    • "allowedSetPwd": true,
    • "allowedSetDisk": true,
    • "allowedUpdateIpGuest": true,
    • "allowedResizeExistingPartition": true,
    • "hasServiceUser": true,
    • "type": "Linux",
    • "category": "Firewall",
    • "nicUnit": 7,
    • "swapUnit": 1,
    • "vmdkId": "abc123abc456",
    • "vmdkSwapId": "abc123abc456",
    • "instructions": "Please follow the instructions to install the template.",
    • "powerOn": true,
    • "regExp": "^[a-zA-Z0-9]*$",
    • "regExpId": 10,
    • "createdAt": "2024-01-01T00:00:00Z",
    • "updatedAt": "2024-01-01T00:00:00Z",
    • "deletedAt": "2024-01-01T00:00:00Z"
    },
  • "message": "Template updated successfully."
}

Delete Template

Delete Template by identifier.

A custom template (one created from a device) is backed by a virtual machine clone in vCenter; deleting the template destroys that clone as well. Operator registered templates only have their record removed.

Authorizations:
service_token
path Parameters
template_identifier
required
string
Example: a1b2c3d4e5f6

The identifier of the template.

Responses

Response samples

Content type
application/json
{
  • "message": "Template deleted successfully"
}

Scripts

Scripts are used to automate tasks on your devices.

Get list of Script

Retrieve a paginated list of Script.

Authorizations:
service_token
query Parameters
page
integer
Example: page=1

The page number to retrieve.

perPage
integer
Example: perPage=10

The numbers of items to return

sort
string
Example: sort=name

Sorting parameter

search
string
Example: search=windows

Searching string

tenantIdentifiers[]
Array of strings
Example: tenantIdentifiers[]=a1b2c3d4e5f6&tenantIdentifiers[]=z9y8x7w6v5u4

An set of tenant IDs to filter the results.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "abc123abc456",
      • "name": "Hello, World",
      • "type": "powershell",
      • "script": "echo 'Hello, World!'",
      • "active": true,
      • "owner": "Parent/Company",
      • "createdAt": "2024-01-01T00:00:00Z"
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "from": 1,
    • "lastPage": 13,
    • "perPage": 5,
    • "to": 5,
    • "total": 64
    }
}

Create Script

Create a new Script

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

tenantIdentifier
string

Tenant identifier.

name
required
string <= 50 characters

Script name.

code
required
string

Script content.

type
required
string
Enum: "bash" "powershell"

Script classification

Responses

Request samples

Content type
application/json
{
  • "tenantIdentifier": "abc123abc456",
  • "name": "ValidNameScript",
  • "code": "echo 'Hello, World!'",
  • "type": "powershell"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "name": "Hello, World",
    • "type": "powershell",
    • "script": "echo 'Hello, World!'",
    • "active": true,
    • "owner": "Parent/Company",
    • "createdAt": "2024-01-01T00:00:00Z"
    },
  • "message": "Script created successfully."
}

Get Script

Get Script by identifier.

Authorizations:
service_token
path Parameters
script_identifier
required
string
Example: a1b2c3d4e5f6

The identifier of the script.

Responses

Response samples

Content type
application/json
{
  • "identifier": "abc123abc456",
  • "name": "Hello, World",
  • "type": "powershell",
  • "script": "echo 'Hello, World!'",
  • "active": true,
  • "owner": "Parent/Company",
  • "createdAt": "2024-01-01T00:00:00Z"
}

Update Script

Update Script.

Authorizations:
service_token
path Parameters
script_identifier
required
string
Example: a1b2c3d4e5f6

The identifier of the script.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
string <= 50 characters

Script name.

code
string

Script content.

type
string
Enum: "bash" "powershell"

Script classification

Responses

Request samples

Content type
application/json
{
  • "name": "ValidNameScript",
  • "code": "echo 'Hello, World!'",
  • "type": "powershell"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "name": "Hello, World",
    • "type": "powershell",
    • "script": "echo 'Hello, World!'",
    • "active": true,
    • "owner": "Parent/Company",
    • "createdAt": "2024-01-01T00:00:00Z"
    },
  • "message": "Script updated successfully."
}

Delete Script

Delete Script by identifier.

Authorizations:
service_token
path Parameters
script_identifier
required
string
Example: a1b2c3d4e5f6

The identifier of the script.

Responses

Response samples

Content type
application/json
{
  • "message": "Script deleted successfully"
}

Persistent Storage

Persistent Storages are used to store data that persists even after the device is deleted.

List Persistent Storage

List all persistent storages of current user.

Authorizations:
service_token
query Parameters
perPage
integer
Example: perPage=5

The numbers of items to return

sort
string
Example: sort=name

Sorting parameter

search
string
Example: search=File storage

Searching string

order
string
Example: order=asc

Sorting order

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "abc123abc456",
      • "name": "File storage",
      • "type": 2,
      • "capacity": 100,
      • "attachedDevices": [
        • {
          • "identifier": "dev123dev456",
          • "name": "device1"
          }
        ],
      • "formatted": true,
      • "uuid": "abc123abc456",
      • "createdAt": "2025-01-03 13:36:10",
      • "cloud": {
        • "identifier": "1a2b3c4d5e6f",
        • "name": "Aargau",
        • "type": "public"
        },
      • "tenant": {
        • "identifier": "abc123abc456",
        • "name": "Company Inc."
        }
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "from": 1,
    • "lastPage": 13,
    • "perPage": 5,
    • "to": 5,
    • "total": 64
    }
}

Create Persistent Storage

Create persistent storage.

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

tenantIdentifier
string

Tenant identifier of the persistent storage owner. If not provided, the persistent storage will be created for the current tenant.

cloudIdentifier
string

Cloud identifier

name
required
string

Network name

deviceIdentifier
string

Device identifier

storageSize
required
integer

Size of the storage

type
required
integer
Enum: 1 2

Storage type. 1 - for kubernetes, 2 - for other devices

Responses

Request samples

Content type
application/json
{
  • "cloudIdentifier": "a1b2c3d4f5e6",
  • "name": "Local file storage",
  • "deviceIdentifier": "a1b2c3d4f5e6",
  • "storageSize": 50,
  • "type": 2
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "name": "File storage",
    • "type": 2,
    • "capacity": 100,
    • "attachedDevices": [
      • {
        • "identifier": "dev123dev456",
        • "name": "device1"
        }
      ],
    • "formatted": true,
    • "uuid": "abc123abc456",
    • "createdAt": "2025-01-03 13:36:10",
    • "cloud": {
      • "identifier": "1a2b3c4d5e6f",
      • "name": "Aargau",
      • "type": "public"
      },
    • "tenant": {
      • "identifier": "abc123abc456",
      • "name": "Company Inc."
      }
    },
  • "message": "Persistent storage has been successfully created."
}

Get Persistent Storage

Retrieve persistent storage information.

Authorizations:
service_token
path Parameters
persistent_storage_identifier
string
Example: a1b2c3d4e5f6

Persistent storage identifier

Responses

Response samples

Content type
application/json
{
  • "identifier": "abc123abc456",
  • "name": "File storage",
  • "type": 2,
  • "capacity": 100,
  • "attachedDevices": [
    • {
      • "identifier": "dev123dev456",
      • "name": "device1"
      }
    ],
  • "formatted": true,
  • "uuid": "abc123abc456",
  • "createdAt": "2025-01-03 13:36:10",
  • "cloud": {
    • "identifier": "1a2b3c4d5e6f",
    • "name": "Aargau",
    • "type": "public"
    },
  • "tenant": {
    • "identifier": "abc123abc456",
    • "name": "Company Inc."
    }
}

Delete Persistent Storage

Delete persistent storage.

Authorizations:
service_token
path Parameters
persistent_storage_identifier
string
Example: a1b2c3d4e5f6

Persistent storage identifier

Responses

Response samples

Content type
application/json
{
  • "message": "Persistent storage has been deleted."
}

Update Persistent Storage

Update persistent storage.

Authorizations:
service_token
path Parameters
persistent_storage_identifier
string
Example: a1b2c3d4e5f6

Persistent storage identifier

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
string

Name of the persistent storage

uuid
string

UUID of the persistent storage

Responses

Request samples

Content type
application/json
{
  • "name": "FileStorage",
  • "uuid": "651ce73d-2f52-4175-a143-b15d32c95646"
}

Response samples

Content type
application/json
{
  • "message": "Persistent storage has been successfully updated.",
  • "data": {
    • "identifier": "abc123abc456",
    • "name": "File storage",
    • "type": 2,
    • "capacity": 100,
    • "attachedDevices": [
      • {
        • "identifier": "dev123dev456",
        • "name": "device1"
        }
      ],
    • "formatted": true,
    • "uuid": "abc123abc456",
    • "createdAt": "2025-01-03 13:36:10",
    • "cloud": {
      • "identifier": "1a2b3c4d5e6f",
      • "name": "Aargau",
      • "type": "public"
      },
    • "tenant": {
      • "identifier": "abc123abc456",
      • "name": "Company Inc."
      }
    }
}

Attach Persistent Storage

Attach persistent storage.

Authorizations:
service_token
path Parameters
persistent_storage_identifier
string
Example: a1b2c3d4e5f6

Persistent storage identifier

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

deviceIdentifier
required
string

Device identifier

Responses

Request samples

Content type
application/json
{
  • "deviceIdentifier": "a1b2c3d4f5e6"
}

Response samples

Content type
application/json
{
  • "message": "Persistent storage has been attached."
}

Detach Persistent Storage

Detach persistent storage.

Authorizations:
service_token
path Parameters
persistent_storage_identifier
string
Example: a1b2c3d4e5f6

Persistent storage identifier

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

deviceIdentifier
required
string

Device identifier

Responses

Request samples

Content type
application/json
{
  • "deviceIdentifier": "a1b2c3d4f5e6"
}

Response samples

Content type
application/json
{
  • "message": "Persistent storage has been detached."
}

Extend Persistent Storage

Extend persistent storage.

Authorizations:
service_token
path Parameters
persistent_storage_identifier
string
Example: a1b2c3d4e5f6

Persistent storage identifier

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

diskSize
required
integer

Persistent storage disk size

Responses

Request samples

Content type
application/json
{
  • "diskSize": 150
}

Response samples

Content type
application/json
{
  • "message": "Persistent storage has been extended."
}

DNS

DNS is a service that translates domain names to IP addresses.

List DNS

List all DNS of current user.

Authorizations:
service_token
query Parameters
search
string
Example: search=xelon.ch

Searching string

sort
string
Example: sort=name

Sorting parameter

order
string
Enum: "asc" "desc"
Example: order=asc

The sorting order (asc or desc).

perPage
integer
Example: perPage=10

The numbers of items to return

page
integer
Example: page=1

The page number to retrieve.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "abc123abc456",
      • "name": "dns5.cloud.xelon.com",
      • "ownerName": "Xelon AG",
      • "createdAt": "2024-01-01T12:00:00Z"
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "from": 1,
    • "lastPage": 13,
    • "perPage": 5,
    • "to": 5,
    • "total": 64
    }
}

Create DNS

Create a new DNS

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

domain
required
string

Domain name

Responses

Request samples

Content type
application/json
{
  • "domain": "example.com"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "name": "dns5.cloud.xelon.com",
    • "ownerName": "Xelon AG",
    • "createdAt": "2024-01-01T12:00:00Z"
    },
  • "message": "DNS zone created successfully."
}

Get DNS

Get DNS by identifier.

Authorizations:
service_token
path Parameters
dns_identifier
required
string
Example: abc123abc456

A unique identifier for the DNS.

Responses

Response samples

Content type
application/json
{
  • "identifier": "abc123abc456",
  • "name": "dns5.cloud.xelon.com",
  • "ownerName": "Xelon AG",
  • "createdAt": "2024-01-01T12:00:00Z"
}

Delete DNS

Delete DNS by ID.

Authorizations:
service_token
path Parameters
dns_identifier
required
string
Example: abc123abc456

A unique identifier for the DNS.

Responses

Response samples

Content type
application/json
{
  • "message": "DNS zone has been deleted"
}

List of DNS records

List all DNS records of current DNS zpne.

Authorizations:
service_token
path Parameters
dns_identifier
required
string
Example: abc123abc456

A unique identifier for the DNS.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": 244042432,
      • "type": "A",
      • "host": "www",
      • "record": "nx6",
      • "failover": 0,
      • "ttl": 3600,
      • "status": 1
      }
    ]
}

Create DNS record

Create a new DNS record. Different types [ MX, SRV, TXT, CAA, RP, SSHFP, NS, ALIAS, TLSA, A, AAAA, CNAME, PTR ] of DNS records can be created. Each DNS record type has its own set of required and optional parameters.

Authorizations:
service_token
path Parameters
dns_identifier
required
string
Example: abc123abc456

A unique identifier for the DNS.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

One of
type
required
string

The type of the DNS record.

Value: "MX"
priority
required
integer

The priority of the mail exchange server.

record
required
string

The hostname of the mail server.

host
required
string

The host name for the DNS record.

ttl
required
integer

The time to live for the DNS record.

Responses

Request samples

Content type
application/json
{
  • "type": "A",
  • "record": "string",
  • "host": "example.com",
  • "ttl": 3600
}

Response samples

Content type
application/json
{
  • "message": "DNS record added successfully"
}

Update DNS record

Update DNS record

Authorizations:
service_token
path Parameters
dns_identifier
required
string
Example: abc123abc456

A unique identifier for the DNS.

record_id
required
integer
Example: 244042432

A unique ID for the DNS record.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

One of
type
required
string

The type of the DNS record.

Value: "MX"
priority
required
integer

The priority of the mail exchange server.

record
required
string

The hostname of the mail server.

host
required
string

The host name for the DNS record.

ttl
required
integer

The time to live for the DNS record.

Responses

Request samples

Content type
application/json
{
  • "type": "A",
  • "record": "string",
  • "host": "example.com",
  • "ttl": 3600
}

Response samples

Content type
application/json
{
  • "message": "DNS record updated successfully"
}

Delete DNS record

Delete DNS record by ID.

Authorizations:
service_token
path Parameters
dns_identifier
required
string
Example: abc123abc456

A unique identifier for the DNS.

record_id
required
integer
Example: 244042432

A unique ID for the DNS record.

Responses

Response samples

Content type
application/json
{
  • "message": "DNS record deleted successfully"
}

Get DNS SOA

Get DNS SOA by DNS ID.

Authorizations:
service_token
path Parameters
dns_identifier
required
string
Example: abc123abc456

A unique identifier for the DNS.

Responses

Response samples

Content type
application/json
{
  • "serialNumber": 2025011302,
  • "primaryNs": "ns1.xelon.ch",
  • "adminMail": "hostmaster.xelon.ch",
  • "refresh": 10800,
  • "retry": 3600,
  • "expire": 604800,
  • "ttl": 3600
}

Update DNS SOA

Update DNS SOA

Authorizations:
service_token
path Parameters
dns_identifier
required
string
Example: abc123abc456

A unique identifier for the DNS.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

primaryNs
required
string

The primary name server for the SOA record.

adminMail
required
string

The email address of the administrator for the SOA record.

refresh
required
integer

The refresh time for the SOA record.

retry
required
integer

The retry time for the SOA record.

expire
required
integer

The expire time for the SOA record.

ttl
required
integer

The time to live for the SOA record.

Responses

Request samples

Content type
application/json
{
  • "primaryNs": "ns1.xelon.ch",
  • "adminMail": "hostmaster.xelon.ch",
  • "refresh": 10800,
  • "retry": 3600,
  • "expire": 604800,
  • "ttl": 3600
}

Response samples

Content type
application/json
{
  • "message": "SOA record updated successfully"
}

Firewalls

Firewalls are used to control the incoming and outgoing traffic to your devices.

Create Firewall

Create a new Firewall.

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
required
string^[A-Za-z0-9-]*$

The name of the firewall.

Array of objects
externalIpIdentifier
string or null

Identifier for the external IP. If not provided, an external IP will be automatically assigned. Either this field or externalNetworkIdentifier must be provided, but not both.

externalNetworkIdentifier
string or null

Identifier for the external (wan) network. Either this field or externalIpIdentifier must be provided, but not both.

internalNetworkIdentifier
required
string

Identifier for the internal network.

internalIp
required
string or null <ipv4>

Internal IP address of the firewall. If not provided, an internal IP will be automatically assigned.

cloudIdentifier
required
string

Identifier of the cloud associated with the firewall.

Array of objects or null
tenantIdentifier
required
string

Tenant identifier for the firewall.

Responses

Request samples

Content type
application/json
{
  • "name": "ExampleFirewall",
  • "forwardingRules": [
    • {
      • "protocol": "udp",
      • "type": "inbound",
      • "externalPort": 443,
      • "port": 8443,
      • "sourceIp": "23.45.53.43",
      • "destinationIp": "42.23.42.44"
      }
    ],
  • "externalIpIdentifier": "123abc456def",
  • "externalNetworkIdentifier": "abc123def456",
  • "internalNetworkIdentifier": "abc123def456",
  • "internalIp": "127.0.0.33",
  • "cloudIdentifier": "zxy789abc123",
  • "ipsecRules": [
    • {
      • "isActive": true,
      • "remoteNetwork": "192.168.2.0/24",
      • "localNetwork": "192.168.1.0/24",
      • "remoteGateway": "203.0.113.1",
      • "preSharedKey": "StrongKey123",
      • "phase1EncryptionAlgorithm": "aes256",
      • "phase2EncryptionAlgorithm": "aes256",
      • "phase1HashAlgorithm": "sha1",
      • "phase2HashAlgorithm": "sha1",
      • "phase1DhGroup": "modp1024",
      • "phase2PfsGroup": "modp1024",
      • "phase1Lifetime": 28800,
      • "phase2Lifetime": 3600,
      • "modeType": "tunnel"
      }
    ],
  • "tenantIdentifier": "klm456nop789"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "name": "my-firewall",
    • "createdAt": "2024-03-19T17:24:26+01:00"
    },
  • "message": "Firewall is being created"
}

Get list of Firewalls

Get list of Firewalls.

Authorizations:
service_token
query Parameters
tenantIds[]
string
Example: tenantIds[]=a1b2c3d4e5f6&tenantIds[]=asd123zxc456&tenantIds[]=qwerty123455

An set of tenant IDs to filter the results.

search
string
Example: search=example search

Search query to filter results based on keywords.

sort
string
Example: sort=created_at

The field by which the results should be sorted.

order
string
Enum: "asc" "desc"
Example: order=asc

The sorting order (asc or desc).

perPage
integer
Example: perPage=10

The number of items to display per page.

page
integer
Example: page=1

The page number to retrieve.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "abc123abc456",
      • "name": "my-firewall",
      • "createdAt": "2024-03-19T17:24:26+01:00"
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "from": 1,
    • "lastPage": 13,
    • "perPage": 5,
    • "to": 5,
    • "total": 64
    }
}

Get Firewall

Get Firewall by ID.

Authorizations:
service_token
path Parameters
firewall_identifier
required
string
Example: abc123abc456

A unique identifier for a Firewall.

Responses

Response samples

Content type
application/json
{
  • "identifier": "abc123abc456",
  • "name": "my-firewall",
  • "createdAt": "2024-03-19T17:24:26+01:00",
  • "health": "green",
  • "externalIp": "10.0.0.20",
  • "internalIp": "127.0.0.55",
  • "state": 1,
  • "tenant": {
    • "identifier": "abc123abc456",
    • "name": "my-tenant"
    },
  • "cloud": {
    • "identifier": "abc123abc456",
    • "name": "my-cloud",
    • "type": "public"
    },
  • "forwardingRules": [
    • {
      • "identifier": "123abc456efg",
      • "protocol": "udp",
      • "type": "inbound",
      • "externalPort": 443,
      • "port": 8443,
      • "sourceIp": "23.45.53.43",
      • "destinationIp": "42.23.42.44"
      }
    ],
  • "ipSecRules": [
    • {
      • "identifier": "123abc456efg",
      • "isActive": true,
      • "remoteNetworkIp": "32.43.53.11.0/24",
      • "localNetworkIp": "127.0.0.123.0/24",
      • "remoteGateway": "123.134.34.32",
      • "preSharedKey": "StrongKey123",
      • "phase1EncryptionAlgorithm": "aes256",
      • "phase2EncryptionAlgorithm": "aes256",
      • "phase1HashAlgorithm": "sha1",
      • "phase2HashAlgorithm": "sha1",
      • "phase1DhGroup": "modp1024",
      • "phase2PfsGroup": "modp1024",
      • "phase1Lifetime": 3600,
      • "phase2Lifetime": 3600,
      • "modeType": "tunnel"
      }
    ]
}

Delete Firewall

Delete Firewall.

Authorizations:
service_token
path Parameters
firewall_identifier
required
string
Example: abc123abc456

A unique identifier for a Firewall.

Responses

Response samples

Content type
application/json
{
  • "message": "Firewall deleted successfully."
}

Create Firewall Forwarding Rule

Create a new Firewall Forwarding Rule.

Authorizations:
service_token
path Parameters
firewall_identifier
required
string
Example: abc123abc456

A unique identifier for a Firewall.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

protocol
required
string
Enum: "udp" "tcp" "icmp"

Protocol for the forwarding rule.

type
required
string
Enum: "inbound" "outbound"

Type of the forwarding rule.

externalPort
required
integer or null

External port for the rule.

port
required
integer

Port for the forwarding rule.

required
string or Array of strings

Source IP for the rule. Single IP (string) for outbound rules, array of IPs for inbound rules.

required
string or Array of strings

Destination IP for the rule. Single IP (string) for inbound rules, array of IPs for outbound rules.

Responses

Request samples

Content type
application/json
{
  • "protocol": "udp",
  • "type": "inbound",
  • "externalPort": 443,
  • "port": 8443,
  • "sourceIp": "23.45.53.43",
  • "destinationIp": "42.23.42.44"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "123abc456efg",
    • "protocol": "udp",
    • "type": "inbound",
    • "externalPort": 443,
    • "port": 8443,
    • "sourceIp": "23.45.53.43",
    • "destinationIp": "42.23.42.44"
    },
  • "message": "Forwarding rule added successfully"
}

Update Firewall Forwarding Rule

Update a new Firewall Forwarding Rule.

Authorizations:
service_token
path Parameters
firewall_identifier
required
string
Example: abc123abc456

A unique identifier for a Firewall.

forwarding_rule_identifier
required
string
Example: acb123abc456

A unique identifier for a Firewall Forwarding Rule.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

protocol
required
string
Enum: "udp" "tcp" "icmp"

Protocol for the forwarding rule.

type
required
string
Enum: "inbound" "outbound"

Type of the forwarding rule.

externalPort
required
integer or null

External port for the rule.

port
required
integer

Port for the forwarding rule.

required
string or Array of strings

Source IP for the rule. Single IP (string) for outbound rules, array of IPs for inbound rules.

required
string or Array of strings

Destination IP for the rule. Single IP (string) for inbound rules, array of IPs for outbound rules.

Responses

Request samples

Content type
application/json
{
  • "protocol": "udp",
  • "type": "inbound",
  • "externalPort": 443,
  • "port": 8443,
  • "sourceIp": "23.45.53.43",
  • "destinationIp": "42.23.42.44"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "123abc456efg",
    • "protocol": "udp",
    • "type": "inbound",
    • "externalPort": 443,
    • "port": 8443,
    • "sourceIp": "23.45.53.43",
    • "destinationIp": "42.23.42.44"
    },
  • "message": "Forwarding rule updated successfully"
}

Delete Firewall Forwarding Rule

Delete Firewall Forwarding Rule.

Authorizations:
service_token
path Parameters
firewall_identifier
required
string
Example: abc123abc456

A unique identifier for a Firewall.

forwarding_rule_identifier
required
string
Example: acb123abc456

A unique identifier for a Firewall Forwarding Rule.

Responses

Response samples

Content type
application/json
{
  • "message": "Forwarding rule deleted successfully"
}

Create Firewall IPSec

Create a new Firewall IPSec.

Authorizations:
service_token
path Parameters
firewall_identifier
required
string
Example: abc123abc456

A unique identifier for a Firewall.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

isActive
required
boolean

Whether the IPSec rule is active.

remoteNetwork
required
string

Remote network in CIDR format.

localNetwork
required
string

Local network in CIDR format.

remoteGateway
required
string

Remote gateway address.

preSharedKey
required
string

Pre-shared key for IPSec authentication.

phase1EncryptionAlgorithm
required
string
Enum: "aes256" "aes128"

Phase 1 encryption algorithm.

phase2EncryptionAlgorithm
required
string
Enum: "aes256" "aes128"

Phase 2 encryption algorithm.

phase1HashAlgorithm
required
string
Enum: "sha1" "sha256" "sha384" "sha512"

Phase 1 hash algorithm.

phase2HashAlgorithm
required
string
Enum: "sha1" "sha256" "sha384" "sha512"

Phase 2 hash algorithm.

phase1DhGroup
required
string
Enum: "modp1024" "modp1536" "modp2048" "modp3072" "modp4096" "modp6144" "modp8192" "ecp256" "ecp384" "ecp521" "modp1024s160" "modp2048s224" "modp2048s256" "ecp256bp" "ecp384bp" "ecp512bp"

Phase 1 DH group.

phase2PfsGroup
required
string
Enum: "modp1024" "modp1536" "modp2048" "modp3072" "modp4096" "modp6144" "modp8192" "ecp256" "ecp384" "ecp521" "modp1024s160" "modp2048s224" "modp2048s256" "ecp256bp" "ecp384bp" "ecp512bp"

Phase 2 PFS group.

phase1Lifetime
required
integer

Lifetime of phase 1 in seconds.

phase2Lifetime
required
integer

Lifetime of phase 2 in seconds.

modeType
required
string
Enum: "tunnel" "transport"

Mode type for IPSec.

Responses

Request samples

Content type
application/json
{
  • "isActive": true,
  • "remoteNetwork": "192.168.2.0/24",
  • "localNetwork": "192.168.1.0/24",
  • "remoteGateway": "203.0.113.1",
  • "preSharedKey": "StrongKey123",
  • "phase1EncryptionAlgorithm": "aes256",
  • "phase2EncryptionAlgorithm": "aes256",
  • "phase1HashAlgorithm": "sha1",
  • "phase2HashAlgorithm": "sha1",
  • "phase1DhGroup": "modp1024",
  • "phase2PfsGroup": "modp1024",
  • "phase1Lifetime": 28800,
  • "phase2Lifetime": 3600,
  • "modeType": "tunnel"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "123abc456efg",
    • "isActive": true,
    • "remoteNetworkIp": "32.43.53.11.0/24",
    • "localNetworkIp": "127.0.0.123.0/24",
    • "remoteGateway": "123.134.34.32",
    • "preSharedKey": "StrongKey123",
    • "phase1EncryptionAlgorithm": "aes256",
    • "phase2EncryptionAlgorithm": "aes256",
    • "phase1HashAlgorithm": "sha1",
    • "phase2HashAlgorithm": "sha1",
    • "phase1DhGroup": "modp1024",
    • "phase2PfsGroup": "modp1024",
    • "phase1Lifetime": 3600,
    • "phase2Lifetime": 3600,
    • "modeType": "tunnel"
    },
  • "message": "IPSec added successfully"
}

Update Firewall IPSec

Update a new Firewall IPSec.

Authorizations:
service_token
path Parameters
firewall_identifier
required
string
Example: abc123abc456

A unique identifier for a Firewall.

ipsec_identifier
required
string
Example: acb123abc456

A unique identifier for a Firewall IPSec.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

isActive
required
boolean

Whether the IPSec rule is active.

remoteNetwork
required
string

Remote network in CIDR format.

localNetwork
required
string

Local network in CIDR format.

remoteGateway
required
string

Remote gateway address.

preSharedKey
required
string

Pre-shared key for IPSec authentication.

phase1EncryptionAlgorithm
required
string
Enum: "aes256" "aes128"

Phase 1 encryption algorithm.

phase2EncryptionAlgorithm
required
string
Enum: "aes256" "aes128"

Phase 2 encryption algorithm.

phase1HashAlgorithm
required
string
Enum: "sha1" "sha256" "sha384" "sha512"

Phase 1 hash algorithm.

phase2HashAlgorithm
required
string
Enum: "sha1" "sha256" "sha384" "sha512"

Phase 2 hash algorithm.

phase1DhGroup
required
string
Enum: "modp1024" "modp1536" "modp2048" "modp3072" "modp4096" "modp6144" "modp8192" "ecp256" "ecp384" "ecp521" "modp1024s160" "modp2048s224" "modp2048s256" "ecp256bp" "ecp384bp" "ecp512bp"

Phase 1 DH group.

phase2PfsGroup
required
string
Enum: "modp1024" "modp1536" "modp2048" "modp3072" "modp4096" "modp6144" "modp8192" "ecp256" "ecp384" "ecp521" "modp1024s160" "modp2048s224" "modp2048s256" "ecp256bp" "ecp384bp" "ecp512bp"

Phase 2 PFS group.

phase1Lifetime
required
integer

Lifetime of phase 1 in seconds.

phase2Lifetime
required
integer

Lifetime of phase 2 in seconds.

modeType
required
string
Enum: "tunnel" "transport"

Mode type for IPSec.

Responses

Request samples

Content type
application/json
{
  • "isActive": true,
  • "remoteNetwork": "192.168.2.0/24",
  • "localNetwork": "192.168.1.0/24",
  • "remoteGateway": "203.0.113.1",
  • "preSharedKey": "StrongKey123",
  • "phase1EncryptionAlgorithm": "aes256",
  • "phase2EncryptionAlgorithm": "aes256",
  • "phase1HashAlgorithm": "sha1",
  • "phase2HashAlgorithm": "sha1",
  • "phase1DhGroup": "modp1024",
  • "phase2PfsGroup": "modp1024",
  • "phase1Lifetime": 28800,
  • "phase2Lifetime": 3600,
  • "modeType": "tunnel"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "123abc456efg",
    • "isActive": true,
    • "remoteNetworkIp": "32.43.53.11.0/24",
    • "localNetworkIp": "127.0.0.123.0/24",
    • "remoteGateway": "123.134.34.32",
    • "preSharedKey": "StrongKey123",
    • "phase1EncryptionAlgorithm": "aes256",
    • "phase2EncryptionAlgorithm": "aes256",
    • "phase1HashAlgorithm": "sha1",
    • "phase2HashAlgorithm": "sha1",
    • "phase1DhGroup": "modp1024",
    • "phase2PfsGroup": "modp1024",
    • "phase1Lifetime": 3600,
    • "phase2Lifetime": 3600,
    • "modeType": "tunnel"
    },
  • "message": "IPSec updated successfully"
}

Delete Firewall IPSec

Delete Firewall IPSec.

Authorizations:
service_token
path Parameters
firewall_identifier
required
string
Example: abc123abc456

A unique identifier for a Firewall.

ipsec_identifier
required
string
Example: acb123abc456

A unique identifier for a Firewall IPSec.

Responses

Response samples

Content type
application/json
{
  • "message": "IPSec deleted successfully"
}

Update Firewall Name

Update the name of a Firewall.

Authorizations:
service_token
path Parameters
firewall_identifier
required
string
Example: abc123abc456

A unique identifier for a Firewall.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
required
string^[A-Za-z0-9_-]*$

The new name for the Firewall. Only alphanumeric characters, underscores, and hyphens are allowed.

Responses

Request samples

Content type
application/json
{
  • "name": "my-firewall-01"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "name": "my-firewall-01",
    • "createdAt": "2024-03-19T17:24:26+01:00"
    },
  • "message": "Firewall name is updated"
}

Reboot Firewall

Reboot a Firewall.

Authorizations:
service_token
path Parameters
firewall_identifier
required
string
Example: abc123abc456

A unique identifier for a Firewall.

Responses

Response samples

Content type
application/json
{
  • "message": "Success"
}

Load Balancers

Load balancers sit in front of your application and distribute incoming traffic across multiple Devices.

Create Load balancer

Create a new Load balancer.

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
required
string^[A-Za-z0-9-]*$

The name of the load balancer.

Array of objects
externalIpIdentifier
string or null

Identifier for the external IP. If not provided, an external IP will be automatically assigned. Either this field or externalNetworkIdentifier must be provided, but not both.

externalNetworkIdentifier
string or null

Identifier for the external (wan) network. Either this field or externalIpIdentifier must be provided, but not both.

internalNetworkIdentifier
required
string

Identifier for the internal network.

internalIp
required
string or null <ipv4>

Internal IP address of the load balancer. If not provided, an internal IP will be automatically assigned.

cloudIdentifier
required
string

Identifier of the cloud associated with the load balancer.

tenantIdentifier
required
string

Tenant identifier for the load balancer.

loadBalancingType
required
string
Enum: "layer4" "layer7"

Load balancing type.

assignedDevicesIdentifiers
Array of strings

Identifiers of the devices assigned to the load balancer.

Responses

Request samples

Content type
application/json
{
  • "name": "ExampleLoadBalancer",
  • "forwardingRules": [
    • {
      • "sslAutogenerate": true,
      • "sslBackend": false,
      • "sslCertificate": "-----BEGIN CERTIFICATE-----\nMIICITCCAYmgAwIBAgIJA...",
      • "url": "example.com",
      • "maintenanceMode": false,
      • "indexFilePath": "/index.html",
      • "ports": [
        • 80,
        • 443
        ],
      • "ip": [
        • "10.10.10.1",
        • "10.10.10.2"
        ]
      }
    ],
  • "externalIpIdentifier": "123abc456def",
  • "externalNetworkIdentifier": "abc123def456",
  • "internalNetworkIdentifier": "abc123def456",
  • "internalIp": "127.0.0.33",
  • "cloudIdentifier": "zxy789abc123",
  • "tenantIdentifier": "klm456nop789",
  • "loadBalancingType": "layer4",
  • "assignedDevicesIdentifiers": [
    • "123abc456",
    • "789def012"
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "name": "my-load-balancer",
    • "createdAt": "2024-03-19T17:24:26+01:00"
    },
  • "message": "Load balancer is being created"
}

Get list of Load Balancers

Get list of Load Balancers.

Authorizations:
service_token
query Parameters
tenantIds[]
string
Example: tenantIds[]=a1b2c3d4e5f6&tenantIds[]=asd123zxc456&tenantIds[]=qwerty123455

An set of tenant IDs to filter the results.

search
string
Example: search=example search

Search query to filter results based on keywords.

sort
string
Example: sort=created_at

The field by which the results should be sorted.

order
string
Enum: "asc" "desc"
Example: order=asc

The sorting order (asc or desc).

perPage
integer
Example: perPage=10

The number of items to display per page.

page
integer
Example: page=1

The page number to retrieve.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "abc123abc456",
      • "name": "my-load-balancer",
      • "createdAt": "2024-03-19T17:24:26+01:00"
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "from": 1,
    • "lastPage": 13,
    • "perPage": 5,
    • "to": 5,
    • "total": 64
    }
}

Get Load Balancer

Get Load Balancer by ID.

Authorizations:
service_token
path Parameters
load_balancer_identifier
required
string
Example: abc123abc456

A unique identifier for a Load Balancer.

Responses

Response samples

Content type
application/json
{
  • "identifier": "abc123abc456",
  • "name": "my-load-balancer",
  • "createdAt": "2024-03-19T17:24:26+01:00",
  • "health": "green",
  • "externalNetworkIdentifier": "abc123abc456",
  • "externalIp": "10.0.0.20",
  • "internalNetworkIdentifier": "abc123abc456",
  • "internalIp": "127.0.0.55",
  • "state": 1,
  • "type": "layer4",
  • "tenant": {
    • "identifier": "abc123abc456",
    • "name": "my-tenant"
    },
  • "cloud": {
    • "identifier": "abc123abc456",
    • "name": "my-cloud",
    • "type": "public"
    },
  • "forwardingRules": [
    • {
      • "identifier": "123abc456efg",
      • "ip": [
        • "10.10.10.1",
        • "10.10.10.2"
        ],
      • "ports": [
        • 80,
        • 443
        ],
      • "maintenanceMode": false,
      • "indexFilePath": "/index.html",
      • "url": "example.com",
      • "sslAutogenerate": true,
      • "sslBackend": false,
      • "sslCertificate": "-----BEGIN CERTIFICATE-----\nMIICITCCAYmgAwIBAgIJA..."
      }
    ],
  • "assignedDevices": [
    • {
      • "identifier": "abc123abc456",
      • "name": "Device 1"
      }
    ]
}

Delete Load Balancer

Delete Load Balancer.

Authorizations:
service_token
path Parameters
load_balancer_identifier
required
string
Example: abc123abc456

A unique identifier for a Load Balancer.

Responses

Response samples

Content type
application/json
{
  • "message": "Load balancer deleted successfully."
}

Update Load Balancer Name

Update the name of an existing load balancer.

Authorizations:
service_token
path Parameters
load_balancer_identifier
required
string
Example: abc123abc456

A unique identifier for a Load Balancer.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
required
string^[A-Za-z0-9-]*$

The name of the load balancer.

Responses

Request samples

Content type
application/json
{
  • "name": "ExampleLoadBalancer"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "name": "my-load-balancer",
    • "createdAt": "2024-03-19T17:24:26+01:00"
    },
  • "message": "Load balancer name is updated"
}

Create Load Balancer Forwarding Rule

Create a new Load Balancer Forwarding Rule.

Authorizations:
service_token
path Parameters
load_balancer_identifier
required
string
Example: abc123abc456

A unique identifier for a Load Balancer.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

sslAutogenerate
boolean

Automatically generate SSL certificates.

sslBackend
boolean

Use SSL for the backend.

sslCertificate
string

SSL certificate.

url
string

URL for the forwarding rule.

maintenanceMode
boolean

Maintenance mode for the forwarding rule.

indexFilePath
string

Index file path for the forwarding rule.

Array of integers or integer

Ports for the forwarding rule.

required
Array of strings or string

Ip(s) of the forwarding rule.

Responses

Request samples

Content type
application/json
{
  • "sslAutogenerate": true,
  • "sslBackend": false,
  • "sslCertificate": "-----BEGIN CERTIFICATE-----\nMIICITCCAYmgAwIBAgIJA...",
  • "url": "example.com",
  • "maintenanceMode": false,
  • "indexFilePath": "/index.html",
  • "ports": [
    • 80,
    • 443
    ],
  • "ip": [
    • "10.10.10.1",
    • "10.10.10.2"
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "123abc456efg",
    • "ip": [
      • "10.10.10.1",
      • "10.10.10.2"
      ],
    • "ports": [
      • 80,
      • 443
      ],
    • "maintenanceMode": false,
    • "indexFilePath": "/index.html",
    • "url": "example.com",
    • "sslAutogenerate": true,
    • "sslBackend": false,
    • "sslCertificate": "-----BEGIN CERTIFICATE-----\nMIICITCCAYmgAwIBAgIJA..."
    },
  • "message": "Forwarding rule added successfully"
}

Update Load Balancer Forwarding Rule

Update a new Load Balancer Forwarding Rule.

Authorizations:
service_token
path Parameters
load_balancer_identifier
required
string
Example: abc123abc456

A unique identifier for a Load Balancer.

forwarding_rule_identifier
required
string
Example: acb123abc456

A unique identifier for a Load Balancer Forwarding Rule.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

sslAutogenerate
boolean

Automatically generate SSL certificates.

sslBackend
boolean

Use SSL for the backend.

sslCertificate
string

SSL certificate.

url
string

URL for the forwarding rule.

maintenanceMode
boolean

Maintenance mode for the forwarding rule.

indexFilePath
string

Index file path for the forwarding rule.

Array of integers or integer

Ports for the forwarding rule.

required
Array of strings or string

Ip(s) of the forwarding rule.

Responses

Request samples

Content type
application/json
{
  • "sslAutogenerate": true,
  • "sslBackend": false,
  • "sslCertificate": "-----BEGIN CERTIFICATE-----\nMIICITCCAYmgAwIBAgIJA...",
  • "url": "example.com",
  • "maintenanceMode": false,
  • "indexFilePath": "/index.html",
  • "ports": [
    • 80,
    • 443
    ],
  • "ip": [
    • "10.10.10.1",
    • "10.10.10.2"
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "123abc456efg",
    • "ip": [
      • "10.10.10.1",
      • "10.10.10.2"
      ],
    • "ports": [
      • 80,
      • 443
      ],
    • "maintenanceMode": false,
    • "indexFilePath": "/index.html",
    • "url": "example.com",
    • "sslAutogenerate": true,
    • "sslBackend": false,
    • "sslCertificate": "-----BEGIN CERTIFICATE-----\nMIICITCCAYmgAwIBAgIJA..."
    },
  • "message": "Forwarding rule updated successfully"
}

Delete Load Balancer Forwarding Rule

Delete a new Load Balancer Forwarding Rule.

Authorizations:
service_token
path Parameters
load_balancer_identifier
required
string
Example: abc123abc456

A unique identifier for a Load Balancer.

forwarding_rule_identifier
required
string
Example: acb123abc456

A unique identifier for a Load Balancer Forwarding Rule.

Responses

Response samples

Content type
application/json
{
  • "message": "Forwarding rule deleted successfully"
}

Get Load Balancer Assignable Devices

Get a new Load Balancer Assignable Devices.

Authorizations:
service_token
path Parameters
load_balancer_identifier
required
string
Example: abc123abc456

A unique identifier for a Load Balancer.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "abc123abc456",
      • "name": "Device 1"
      }
    ]
}

Update Load Balancer Assigned Devices

Update Load Balancer Assigned Devices.

Authorizations:
service_token
path Parameters
load_balancer_identifier
required
string
Example: abc123abc456

A unique identifier for a Load Balancer.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

deviceIdentifiers
required
Array of strings

Identifiers of the devices assigned to the load balancer.

Responses

Request samples

Content type
application/json
{
  • "deviceIdentifiers": [
    • "123abc456",
    • "789def012"
    ]
}

Response samples

Content type
application/json
{
  • "message": "Assigned devices updated successfully."
}

Backups

Backups are used to create snapshots of your devices.

Get Available Backup tags on Cloud

Get Available Backup tags on Cloud.

Authorizations:
service_token
query Parameters
cloudIdentifier
required
string
Example: cloudIdentifier=abc123abc456

A unique identifier for a Cloud.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": 2,
      • "name": "Daily Backup, kept for 5 days",
      • "tag": "urn:vmomi:InventoryServiceTag:2190c5fa-03ed-4d10-9982-437373513228:GLOBAL"
      }
    ]
}

Get Device Backup tags

Get Device Backup tags.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": 2,
      • "name": "Daily Backup, kept for 5 days",
      • "tag": "urn:vmomi:InventoryServiceTag:2190c5fa-03ed-4d10-9982-437373513228:GLOBAL"
      }
    ]
}

Change Device Backup tag

Change Device Backup tag.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

backupId
required
integer

The id of the backup to change the tag for.

Responses

Request samples

Content type
application/json
{
  • "backupId": 17
}

Response samples

Content type
application/json
{
  • "message": "Backup has been changed."
}

Delete Device Backup tag

Delete Device Backup tag.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Responses

Response samples

Content type
application/json
{
  • "message": "Backup has been deleted."
}

Get Device Backup points

Get Device Backup points.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": 11,
      • "time": "30 Nov 2024, 22:07",
      • "sizeGb": 3,
      • "restorePointId": "6f2312c9-4660-49bf-9050-454796635b48",
      • "mountStatus": null,
      • "unmountAt": null
      }
    ]
}

Restore Device Backup

Restore Device Backup.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

restoreId
required
string

The unique identifier of the restore point to restore.

powerOn
required
boolean

If true, the device will be powered on after the restore.

Responses

Request samples

Content type
application/json
{
  • "restoreId": "6f2312c9-4660-49bf-9050-454796635b48",
  • "powerOn": true
}

Response samples

Content type
application/json
{
  • "message": "Your device will be restored shortly."
}

Restore Files From Backup

Restore specific files from a backup restore point. This creates a backup_restore_status record and processes the restore asynchronously — this endpoint does not return that record's ID. To later download the restored file or replace it on the server (GET /backup/restore-status/presigned-url, POST /backup/restore-status/replace-file), retrieve the ID via GET /backup/restore-status?deviceId={deviceId}.

Prerequisite: the restore point must already be mounted via POST /backup/restore-points/mount and have reached mountStatus: "mounted" (see GET /devices/{device_identifier}/backups/points). Calling this endpoint against a restore point that isn't mounted yet fails with a 500 error, and — since the failure happens before the backup_restore_status record is created — no record will show up in GET /backup/restore-status for that attempt.

A record appears in GET /backup/restore-status?deviceId={deviceId} as soon as this endpoint succeeds (its path is set immediately); you do not need to wait for the restore to fully complete (status: "Success") for it to be listed. However, the presigned download URL only works once the upload to storage has actually finished — see GET /backup/restore-status/presigned-url.

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

deviceId
required
string

Device local VM ID

restoreId
required
string

Restore point ID

password
string

User password (required for non-service, password-based users; not required for service accounts or Microsoft SSO-authenticated users)

path
required
Array of strings

List of file paths to restore

isNeedReplace
boolean

Whether to replace existing files on the server

Responses

Request samples

Content type
application/json
{
  • "deviceId": "abc123def456",
  • "restoreId": "6f2312c9-4660-49bf-9050-454796635b48",
  • "path": [
    • "/etc/nginx/nginx.conf"
    ],
  • "isNeedReplace": false
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Mount Backup Restore Point

Mount a backup restore point for file-level access. Mounting happens asynchronously — this endpoint only starts the process. Poll GET /devices/{device_identifier}/backups/points and check the mountStatus field for the matching restorePointId until it becomes "mounted" before calling POST /backup/restore-files.

This is a required prerequisite for POST /backup/restore-files. Calling restore-files before the restore point has reached "mounted" status fails with a 500 error (no active mount session exists yet).

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

deviceId
required
string

Device local VM ID

restoreId
required
string

Restore point ID

Responses

Request samples

Content type
application/json
{
  • "deviceId": "abc123def456",
  • "restoreId": "6f2312c9-4660-49bf-9050-454796635b48"
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Unmount Backup Restore Point

Unmount a previously mounted backup restore point.

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

deviceId
required
string

Device local VM ID

restoreId
required
string

Restore point ID

Responses

Request samples

Content type
application/json
{
  • "deviceId": "abc123def456",
  • "restoreId": "6f2312c9-4660-49bf-9050-454796635b48"
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Get Backup Restore Point Files

List files in a mounted backup restore point at a specific path.

Authorizations:
service_token
query Parameters
page
required
integer >= 1

Page number

perPage
required
integer >= 1

Items per page

restorePointId
required
string

Restore point ID

deviceId
required
string

Device local VM ID

path
string or null

Directory path to list (null for root)

Responses

Response samples

Content type
application/json
{
  • "path": "string",
  • "data": [
    • {
      • "name": "string",
      • "path": "string",
      • "type": "file",
      • "updatedAt": "string",
      • "owner": "string",
      • "size": 0
      }
    ],
  • "meta": { }
}

List Restore Statuses

List downloadable restore statuses for a device — the file restores started via POST /backup/restore-files that still have a downloadable file. Use the returned id with GET /backup/restore-status/presigned-url or POST /backup/restore-status/replace-file.

A record shows up here as soon as POST /backup/restore-files succeeds, before the restore has necessarily finished — check status: "Success" on the entry before trusting GET /backup/restore-status/presigned-url to return a working download link. Returns an empty array if POST /backup/restore-files was never called successfully for the device, or if that call failed (e.g. because the restore point wasn't mounted yet — see POST /backup/restore-points/mount), since no record is created on failure.

Authorizations:
service_token
query Parameters
deviceId
required
string

Device local VM ID

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": 42,
      • "status": "Success",
      • "path": "C:\\restored\\file.txt",
      • "backupAt": "2026-07-20T10:15:00.000000Z",
      • "createdAt": "2026-07-20T10:20:00.000000Z",
      • "expiresAt": "2026-07-21T10:20:00.000000Z"
      }
    ]
}

Get Backup Presigned Download URL

Get a presigned URL for downloading a restored file.

The URL is only functional once the restored file has finished uploading to storage (restore status status: "Success"). The underlying storage key is populated asynchronously, after POST /backup/restore-files returns — a backup_restore_status record shows up in GET /backup/restore-status?deviceId={deviceId} (its path is set) before that upload necessarily completes. Calling this endpoint against such a not-yet-uploaded record still returns 200 with a well-formed URL, but the URL will not resolve to a real object until the upload finishes. Poll GET /backup/restore-status?deviceId={deviceId} and wait for status: "Success" on the matching id before relying on the returned URL.

Authorizations:
service_token
query Parameters
id
required
integer

Restore status ID (the ID of the underlying backup_restore_status record created when the file restore was started via POST /backup/restore-files). Retrieve it via GET /backup/restore-status?deviceId={deviceId}, which lists the downloadable restore statuses for a device together with their id.

Responses

Response samples

Content type
application/json
{
  • "url": "string"
}

Replace File From Backup

Start the process of replacing a file on the server with the version from a backup restore.

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

id
required
integer

Restore status ID (the ID of the underlying backup_restore_status record created when the file restore was started via POST /backup/restore-files). Retrieve it via GET /backup/restore-status?deviceId={deviceId}, which lists the downloadable restore statuses for a device together with their id.

Responses

Request samples

Content type
application/json
{
  • "id": 42
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Get Backup Protection Stats

Get backup protection statistics for the current tenant (protected/unprotected device counts and last backup date).

Authorizations:
service_token

Responses

Response samples

Content type
application/json
{
  • "protectedCount": 0,
  • "unprotectedCount": 0,
  • "lastBackupDate": "2019-08-24T14:15:22Z"
}

Replications

Replications are used to create copies of your devices.

Get Available Replication tags on Cloud

Get Available Replication tags on Cloud.

Authorizations:
service_token
query Parameters
cloudIdentifier
required
string
Example: cloudIdentifier=abc123abc456

A unique identifier for a Cloud.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": 2,
      • "jobName": "Replication Job 1",
      • "hoursFrequency": 4,
      • "tag": "urn:vmomi:InventoryServiceTag:2190c5fa-03ed-4d10-9982-437373513228:GLOBAL",
      • "cloud": {
        • "identifier": "1a2b3c4d5e6f",
        • "name": "Aargau",
        • "type": "public"
        },
      • "destinationCloud": {
        • "identifier": "1a2b3c4d5e6f",
        • "name": "Aargau",
        • "type": "public"
        }
      }
    ]
}

Get Device Replication tags

Get Device Replication tags.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": 2,
      • "tag": "urn:vmomi:InventoryServiceTag:2190c5fa-03ed-4d10-9982-437373513228:GLOBAL",
      • "hoursFrequency": 4,
      • "jobName": "Replication Job 1"
      }
    ]
}

Change Device Replication tag

Change Device Replication tag.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

replicationId
required
integer

The id of the replication to change the tag for.

Responses

Request samples

Content type
application/json
{
  • "replicationId": 17
}

Response samples

Content type
application/json
{
  • "message": "Replication tag has been changed."
}

Delete Device Replication tag

Delete all Device Replication assigned tags.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Responses

Response samples

Content type
application/json
{
  • "message": "Replication tag has been deleted."
}

Get Current Device Replication

Get Current Device Replication.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Responses

Response samples

Content type
application/json
{
  • "id": 23,
  • "deviceIdentifier": "123abc456def",
  • "sourceCloudIdentifier": "123abc456def",
  • "destinationCloudIdentifier": "123abc456def",
  • "sourceCloudName": "Zurich",
  • "destinationCloudName": "Aargau",
  • "status": "ready",
  • "createdAt": "2021-01-01T12:00:00Z",
  • "updatedAt": "2021-01-01T12:00:00Z",
  • "readyAt": "2021-01-01T12:00:00Z"
}

Switch Device to Replicated Device

Switch Device to Replicated Device on Destination Cloud.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

replicationId
required
integer

The id of the replication to change the tag for.

backupPlanId
integer

The id of the backup plan.

required
Array of objects

Array of network configurations for the virtual machine.

Responses

Request samples

Content type
application/json
{
  • "replicationId": 17,
  • "backupPlanId": 2,
  • "networks": [
    • {
      • "networkIdentifier": "zxy123zxy456"
      }
    ]
}

Response samples

Content type
application/json
{
  • "message": "Device switched to replicated virtual machine.",
  • "data": {
    • "identifier": "abc123abc456",
    • "displayName": "my-device",
    • "hostName": "my-device",
    • "createdAt": "2024-03-19T17:24:26+01:00"
    }
}

SSH Keys

The Secure Shell (SSH) service provides secure access to your servers. Using SSH, you can remotely connect to and manage your instances with encryption and security. It supports tunneling, port forwarding, and various authentication methods, including passwords and keys.

List SSH Keys

List all SSH keys of current user.

Authorizations:
service_token
query Parameters
page
integer
Example: page=1

The page number to retrieve.

perPage
integer
Example: perPage=10

The numbers of items to return

sort
string
Example: sort=name

Sorting parameter

search
string
Example: search=windows

Searching string

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "abc123abc456",
      • "name": "my-ssh-key",
      • "createdAt": "2024-03-19T17:24:26+01:00",
      • "sshKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDVnEqbeTlrb8jLFyzsKtXfGGnM2P4Ey1bksBDeWxdKdFOV4xGzUgT4CbC7BQOhrH/QqmbmB1Vd6uALDziULfFKu5oLgEBt5wMGECmYQHqBMR9Eb8IqBp0Y5WbsUqF8GLmUgbzALr+fXpP9YEFNSq3xj7G7cF4WmX8D/NzKMH6+1JxFlzpzGgLe8FS3Ycjk+j0YLeJ+7vV4tSfyk+It8kplbJeDKV1RqPhIWjmrAbHX/cw7glN5vLWejCWJr8DpPbJXv5OhtFOfaD4t5Gj4zM63+UQ45QnyA33WJwN2CqHFzR6Dkw",
      • "createdBy": "John Doe"
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "from": 1,
    • "lastPage": 13,
    • "perPage": 5,
    • "to": 5,
    • "total": 64
    }
}

Create SSH Key

Create a new SSH key.

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
required
string

The name of the SSH key.

sshKey
required
string

The SSH key itself. This is the public key part of the SSH key pair. The private key part is kept by the user.

Responses

Request samples

Content type
application/json
{
  • "name": "my-ssh-key",
  • "sshKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDVnEqbeTlrb8jLFyzsKtXfGGnM2P4Ey1bksBDeWxdKdFOV4xGzUgT4CbC7BQOhrH/QqmbmB1Vd6uALDziULfFKu5oLgEBt5wMGECmYQHqBMR9Eb8IqBp0Y5WbsUqF8GLmUgbzALr+fXpP9YEFNSq3xj7G7cF4WmX8D/NzKMH6+1JxFlzpzGgLe8FS3Ycjk+j0YLeJ+7vV4tSfyk+It8kplbJeDKV1RqPhIWjmrAbHX/cw7glN5vLWejCWJr8DpPbJXv5OhtFOfaD4t5Gj4zM63+UQ45QnyA33WJwN2CqHFzR6Dkw"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "name": "my-ssh-key",
    • "createdAt": "2024-03-19T17:24:26+01:00",
    • "sshKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDVnEqbeTlrb8jLFyzsKtXfGGnM2P4Ey1bksBDeWxdKdFOV4xGzUgT4CbC7BQOhrH/QqmbmB1Vd6uALDziULfFKu5oLgEBt5wMGECmYQHqBMR9Eb8IqBp0Y5WbsUqF8GLmUgbzALr+fXpP9YEFNSq3xj7G7cF4WmX8D/NzKMH6+1JxFlzpzGgLe8FS3Ycjk+j0YLeJ+7vV4tSfyk+It8kplbJeDKV1RqPhIWjmrAbHX/cw7glN5vLWejCWJr8DpPbJXv5OhtFOfaD4t5Gj4zM63+UQ45QnyA33WJwN2CqHFzR6Dkw",
    • "createdBy": "John Doe"
    },
  • "message": "SSH key added successfully"
}

Get SSH Key

Get SSH key by identifier.

Authorizations:
service_token
path Parameters
ssh_key_identifier
required
string
Example: abc123abc456

A unique identifier for a Ssh key.

Responses

Response samples

Content type
application/json
{
  • "identifier": "abc123abc456",
  • "name": "my-ssh-key",
  • "createdAt": "2024-03-19T17:24:26+01:00",
  • "sshKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDVnEqbeTlrb8jLFyzsKtXfGGnM2P4Ey1bksBDeWxdKdFOV4xGzUgT4CbC7BQOhrH/QqmbmB1Vd6uALDziULfFKu5oLgEBt5wMGECmYQHqBMR9Eb8IqBp0Y5WbsUqF8GLmUgbzALr+fXpP9YEFNSq3xj7G7cF4WmX8D/NzKMH6+1JxFlzpzGgLe8FS3Ycjk+j0YLeJ+7vV4tSfyk+It8kplbJeDKV1RqPhIWjmrAbHX/cw7glN5vLWejCWJr8DpPbJXv5OhtFOfaD4t5Gj4zM63+UQ45QnyA33WJwN2CqHFzR6Dkw",
  • "createdBy": "John Doe"
}

Update SSH Key

Update SSH key by identifier.

Authorizations:
service_token
path Parameters
ssh_key_identifier
required
string
Example: abc123abc456

A unique identifier for a Ssh key.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
string

The name of the SSH key.

sshKey
string

The SSH key itself. This is the public key part of the SSH key pair. The private key part is kept by the user.

Responses

Request samples

Content type
application/json
{
  • "name": "my-ssh-key-new",
  • "sshKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDVnEqbeTlrb8jLFyzsKtXfGGnM2P4Ey1bksBDeWxdKdFOV4xGzUgT4CbC7BQOhrH/QqmbmB1Vd6uALDziULfFKu5oLgEBt5wMGECmYQHqBMR9Eb8IqBp0Y5WbsUqF8GLmUgbzALr+fXpP9YEFNSq3xj7G7cF4WmX8D/NzKMH6+1JxFlzpzGgLe8FS3Ycjk+j0YLeJ+7vV4tSfyk+It8kplbJeDKV1RqPhIWjmrAbHX/cw7glN5vLWejCWJr8DpPbJXv5OhtFOfaD4t5Gj4zM63+UQ45QnyA33WJwN2CqHFzR6Dkw"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "name": "my-ssh-key",
    • "createdAt": "2024-03-19T17:24:26+01:00",
    • "sshKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDVnEqbeTlrb8jLFyzsKtXfGGnM2P4Ey1bksBDeWxdKdFOV4xGzUgT4CbC7BQOhrH/QqmbmB1Vd6uALDziULfFKu5oLgEBt5wMGECmYQHqBMR9Eb8IqBp0Y5WbsUqF8GLmUgbzALr+fXpP9YEFNSq3xj7G7cF4WmX8D/NzKMH6+1JxFlzpzGgLe8FS3Ycjk+j0YLeJ+7vV4tSfyk+It8kplbJeDKV1RqPhIWjmrAbHX/cw7glN5vLWejCWJr8DpPbJXv5OhtFOfaD4t5Gj4zM63+UQ45QnyA33WJwN2CqHFzR6Dkw",
    • "createdBy": "John Doe"
    },
  • "message": "SSH key updated successfully"
}

Delete SSH Key

Delete SSH key by identifier.

Authorizations:
service_token
path Parameters
ssh_key_identifier
required
string
Example: abc123abc456

A unique identifier for a Ssh key.

Responses

Response samples

Content type
application/json
{
  • "message": "SSH key deleted successfully"
}

ISOs

ISOs are used to install operating systems on your devices.

Get list of ISO

Retrieve a paginated list of ISO.

Authorizations:
service_token
query Parameters
page
integer
Example: page=1

The page number to retrieve.

perPage
integer
Example: perPage=10

The numbers of items to return

sort
string
Example: sort=name

Sorting parameter

search
string
Example: search=windows

Searching string

tenantIdentifiers[]
Array of strings
Example: tenantIdentifiers[]=a1b2c3d4e5f6&tenantIdentifiers[]=z9y8x7w6v5u4

An set of tenant IDs to filter the results.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "abc123abc456",
      • "category": "Ubuntu",
      • "name": "pfSense CE 2.4.2",
      • "description": "pfSense CE 2.4.2",
      • "owner": "Parent/Company",
      • "active": true,
      • "status": true,
      • "createdAt": "2024-01-01T00:00:00Z",
      • "cloud": {
        • "identifier": "abc123abc456",
        • "name": "Cloud name",
        • "type": "private"
        }
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "from": 1,
    • "lastPage": 13,
    • "perPage": 5,
    • "to": 5,
    • "total": 64
    }
}

Create ISO

Create a new ISO

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

tenantIdentifier
string

Tenant identifier.

name
required
string <= 100 characters

Template name.

description
string <= 500 characters

Template description.

url
required
string

URL for ISO downloading

categoryId
required
integer

Category ID of ISO.

cloudIdentifier
required
string

Destination cloud identifier.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "category": "Ubuntu",
    • "name": "pfSense CE 2.4.2",
    • "description": "pfSense CE 2.4.2",
    • "owner": "Parent/Company",
    • "active": true,
    • "status": true,
    • "createdAt": "2024-01-01T00:00:00Z",
    • "cloud": {
      • "identifier": "abc123abc456",
      • "name": "Cloud name",
      • "type": "private"
      }
    },
  • "message": "Uploading ISO file. It may take a few minutes."
}

Upload ISO

Upload a small ISO file directly to the destination cloud's datastore.

The upload is processed synchronously: when the request succeeds, the ISO is already stored on the datastore and immediately usable (status: true).

This endpoint is intended for small, tool-generated images such as unattended installation media (e.g. an OEMDRV-labelled Kickstart CD for a RHEL-family unattended install), and for small network-boot images. The maximum accepted file size is 50 MB — register large installation DVDs from a URL via POST /isos instead.

Authorizations:
service_token
Request Body schema: multipart/form-data

Include a form-data request body with a content type of multipart/form-data.

tenantIdentifier
string

Tenant identifier.

name
required
string <= 200 characters

ISO name.

description
string <= 500 characters

ISO description.

file
required
string <binary>

The ISO file to upload. Must have an .iso extension and be at most 50 MB.

categoryId
required
integer

Category ID of ISO.

cloudIdentifier
required
string

Destination cloud identifier.

Responses

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "category": "Ubuntu",
    • "name": "pfSense CE 2.4.2",
    • "description": "pfSense CE 2.4.2",
    • "owner": "Parent/Company",
    • "active": true,
    • "status": true,
    • "createdAt": "2024-01-01T00:00:00Z",
    • "cloud": {
      • "identifier": "abc123abc456",
      • "name": "Cloud name",
      • "type": "private"
      }
    },
  • "message": "ISO uploaded successfully."
}

Get ISO

Get ISO by identifier.

Authorizations:
service_token
path Parameters
iso_identifier
required
string
Example: abc123abc456

A unique identifier for the Iso.

Responses

Response samples

Content type
application/json
{
  • "identifier": "abc123abc456",
  • "category": "Ubuntu",
  • "name": "pfSense CE 2.4.2",
  • "description": "pfSense CE 2.4.2",
  • "owner": "Parent/Company",
  • "active": true,
  • "status": true,
  • "createdAt": "2024-01-01T00:00:00Z",
  • "cloud": {
    • "identifier": "abc123abc456",
    • "name": "Cloud name",
    • "type": "private"
    }
}

Update ISO

Update ISO.

Authorizations:
service_token
path Parameters
iso_identifier
required
string
Example: abc123abc456

A unique identifier for the Iso.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
string <= 100 characters

Template name.

description
string <= 500 characters

Template description.

categoryId
integer

Category ID of ISO.

Responses

Request samples

Content type
application/json
{
  • "name": "pfSense CE 2.4.2",
  • "description": "pfSense CE 2.4.2 Open Source Firewall",
  • "categoryId": "1"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc456",
    • "category": "Ubuntu",
    • "name": "pfSense CE 2.4.2",
    • "description": "pfSense CE 2.4.2",
    • "owner": "Parent/Company",
    • "active": true,
    • "status": true,
    • "createdAt": "2024-01-01T00:00:00Z",
    • "cloud": {
      • "identifier": "abc123abc456",
      • "name": "Cloud name",
      • "type": "private"
      }
    },
  • "message": "ISO updated successfully."
}

Delete ISO

Delete ISO by identifier.

If the ISO file was fully uploaded to the cloud's datastore, the file is removed from the datastore asynchronously as part of the deletion.

Authorizations:
service_token
path Parameters
iso_identifier
required
string
Example: abc123abc456

A unique identifier for the Iso.

Responses

Response samples

Content type
application/json
{
  • "message": "ISO deleted successfully"
}

Kubernetes

Xelon Kubernetes Service (XKS) is a managed Kubernetes offering.

List Kubernetes Clusters

List the Kubernetes Clusters in your account.

Authorizations:
service_token
query Parameters
search
string

Filter clusters by name.

perPage
integer
Example: perPage=15

Number of items per page.

page
integer
Example: page=1

Page number to retrieve.

sort
string

Field to sort the results by.

order
string
Enum: "asc" "desc"

Sort direction.

cloudIdentifier
string

Filter clusters by cloud identifier.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "abc1234abc",
      • "owner": "Example Tenant",
      • "name": "HPC Cluster",
      • "status": "Ready",
      • "cloud": {
        • "identifier": "abc123abc456",
        • "name": "Aargau"
        },
      • "createdAt": "2024-03-19T17:24:26+01:00",
      • "health": {
        • "health": "healthy",
        • "lastCheckingData": "2024-03-19 18:22:33"
        }
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "from": 1,
    • "lastPage": 13,
    • "perPage": 5,
    • "to": 5,
    • "total": 64
    }
}

Create Kubernetes Cluster

Create a new Kubernetes Talos Cluster.

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

Request fields use camelCase (the v2-canonical style). The legacy snake_case names (e.g. cluster_name, worker_pool) are still accepted for backwards compatibility.

Any of
clusterName
required
string

The name of the Kubernetes cluster. Must be lowercase with no spaces.

tenantIdentifier
required
string

The identifier of the tenant.

cloudIdentifier
required
string

The cloud (HV system) where the cluster will be deployed — the identifier string from GET /clouds. An unknown identifier is rejected with 422. Required unless cloudId is supplied.

cloudId
integer
Deprecated

Deprecated — use cloudIdentifier. The numeric cloud (HV system) id. Required unless cloudIdentifier is supplied.

k8sVersion
required
string

The Kubernetes version for the cluster. Must form a supported pair with talosVersion — fetch the valid combinations from GET /kubernetes/versions/{cloud_id} first. An unsupported k8sVersion/talosVersion pair is rejected with 422.

talosVersion
required
string

The Talos OS version for the cluster. Must form a supported pair with k8sVersion (see GET /kubernetes/versions/{cloud_id}). An unsupported pair is rejected with 422.

podSubnet
required
string

The CIDR subnet for pods.

serviceSubnet
required
string

The CIDR subnet for services.

schematicId
string

Optional schematic ID for custom configurations.

controlPlaneType
required
string

The control plane deployment type. production deploys a high-availability control plane; any other value (e.g. test) deploys a single, non-production control plane. The API accepts any string and is not restricted to an enum.

controlPlaneCpu
required
integer >= 1

Number of CPU cores for each control plane node.

controlPlaneRam
required
integer >= 2

Amount of RAM in GB for each control plane node.

controlPlaneDisk
required
integer >= 20

Disk size in GB for each control plane node.

Array of objects

Array of worker pool configurations.

loadBalancerType
required
string

The load balancer deployment type. production deploys two load balancers (HA); any other value (e.g. test) deploys a single load balancer. The API accepts any string and is not restricted to an enum.

loadBalancerCpu
required
integer >= 1

Number of CPU cores for the load balancer.

loadBalancerRam
required
integer >= 2

Amount of RAM in GB for the load balancer.

loadBalancerDisk
required
integer >= 20

Disk size in GB for the load balancer.

notify
boolean
Default: true

Whether to send the deployment-status email to the requesting user once the cluster finishes deploying (on both success and failure). Set to false to opt out of the email. The post-deploy health check and the websocket status update are unaffected.

Responses

Request samples

Content type
application/json
{
  • "clusterName": "my-k8s-cluster",
  • "tenantIdentifier": "abc123abc456",
  • "cloudIdentifier": "514016275126",
  • "cloudId": 1,
  • "k8sVersion": "1.30.0",
  • "talosVersion": "1.7.0",
  • "podSubnet": "10.244.0.0/16",
  • "serviceSubnet": "10.96.0.0/12",
  • "schematicId": "abc123",
  • "controlPlaneType": "production",
  • "controlPlaneCpu": 2,
  • "controlPlaneRam": 4,
  • "controlPlaneDisk": 50,
  • "workerPool": [
    • {
      • "workerPoolIndex": 0,
      • "workerPoolName": "default-pool",
      • "workerNodeAmount": 3,
      • "workerNodeCpu": 2,
      • "workerNodeRam": 4,
      • "workerNodeDisk": 50,
      • "workerNodeIsStorage": false,
      • "workerNodeExtraDisk": 0
      }
    ],
  • "loadBalancerType": "production",
  • "loadBalancerCpu": 2,
  • "loadBalancerRam": 4,
  • "loadBalancerDisk": 50,
  • "notify": false
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123abc4",
    • "name": "my-cluster",
    • "status": "Created"
    },
  • "message": "Cluster has been deployed! You will receive an email upon its completion."
}

List Kubernetes/Talos Versions

Returns the supported Talos versions and, for each, the list of compatible Kubernetes versions. Used to populate the cluster creation form.

The cloud_id path parameter is currently accepted but ignored — the same version map is returned for every cloud.

Authorizations:
service_token
path Parameters
cloud_id
required
string
Example: 514016275126

The identifier of the cloud (HV system) — use the identifier field value from GET /clouds. Currently accepted but ignored: the same version map is returned for every cloud.

Responses

Response samples

Content type
application/json
{
  • "1.12.8": [
    • "1.30.0",
    • "1.31.0",
    • "1.32.0"
    ],
  • "1.13.3": [
    • "1.31.0",
    • "1.32.0",
    • "1.33.0"
    ]
}

Get Kubernetes Cluster

Get a single Kubernetes Cluster by its identifier.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

Responses

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc1234abc",
    • "owner": "Example Tenant",
    • "name": "HPC Cluster",
    • "status": "Ready",
    • "cloud": {
      • "identifier": "abc123abc456",
      • "name": "Aargau"
      },
    • "createdAt": "2024-03-19T17:24:26+01:00",
    • "health": {
      • "health": "healthy",
      • "lastCheckingData": "2024-03-19 18:22:33"
      }
    }
}

Delete Kubernetes Cluster

Delete an existing Kubernetes Talos Cluster.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

password
string

The user's password for confirmation. Required for non-service, password-based users; not required for service accounts or Microsoft SSO-authenticated users.

Responses

Request samples

Content type
application/json
{
  • "password": "MySecureP@ssw0rd"
}

Response samples

Content type
application/json
{
  • "message": "Cluster has been deleted."
}

List Cluster Pools

List the Cluster Pools on the existing Kubernetes Cluster.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

Responses

Response samples

Content type
application/json
[
  • {
    • "cpu": 4,
    • "disk": 50,
    • "identifier": "abc1234abc",
    • "memory": 4,
    • "name": "main",
    • "hasExtraStorage": 0,
    • "extraStorage": 0,
    • "nodes": [
      • {
        • "identifier": "abc1234abc",
        • "localvmid": "vm1234567890",
        • "name": "hpc-cluster-w-1-1",
        • "status": "Deployed"
        },
      • {
        • "identifier": "def1234def",
        • "localvmid": "vm0987654321",
        • "name": "hpc-cluster-w-1-2",
        • "status": "Deployed"
        }
      ]
    }
]

Add Worker Pool

Add a new worker pool to an existing Kubernetes cluster. The pool's nodes are provisioned asynchronously; the response confirms that the work has started.

Request fields use camelCase (the v2-canonical style). The legacy snake_case names are still accepted for backwards compatibility.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

Request Body schema: application/json
required
workerPoolName
required
string

Name of the new worker pool.

workerNodeAmount
required
integer

Number of worker nodes to deploy in the pool.

workerNodeCpu
required
integer

Number of vCPU cores per worker node.

workerNodeRam
required
integer

Memory (GB) per worker node.

workerNodeDisk
required
integer

Root disk size (GB) per worker node.

workerNodeIsStorage
required
boolean

Whether the pool's nodes provide extra storage.

workerNodeExtraDisk
integer

Extra disk size (GB) per worker node. Required when workerNodeIsStorage is true.

Responses

Request samples

Content type
application/json
{
  • "workerPoolName": "extra-pool",
  • "workerNodeAmount": 2,
  • "workerNodeCpu": 2,
  • "workerNodeRam": 4,
  • "workerNodeDisk": 50,
  • "workerNodeIsStorage": false,
  • "workerNodeExtraDisk": 0
}

Response samples

Content type
application/json
{
  • "message": "New pool will be added to your cluster.",
  • "data": {
    • "identifier": "k3p9x2m7qz",
    • "name": "extra-pool",
    • "status": "Created"
    }
}

Get Worker Pool

Retrieve a single worker pool (including its nodes) on the existing Kubernetes Cluster. Returns 404 when the pool does not exist or belongs to a different cluster.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

cluster_pool_identifier
required
string
Example: abc1234abc

A unique identifier for a cluster pool.

Responses

Response samples

Content type
application/json
{
  • "cpu": 2,
  • "disk": 50,
  • "identifier": "abc1234abc",
  • "memory": 4,
  • "name": "main",
  • "hasExtraStorage": 0,
  • "extraStorage": 0,
  • "desiredNodeCount": 5,
  • "nodes": [
    • {
      • "identifier": "abc1234abc",
      • "localvmid": "vm1234567890",
      • "name": "hpc-cluster-w-1-1",
      • "status": "Deployed"
      }
    ]
}

Update Worker Pool

Update the resources (CPU / memory / disk) of an existing worker pool. Nodes are resized asynchronously; the response confirms that the work has started.

Request fields use camelCase (the v2-canonical style). The legacy snake_case names are still accepted for backwards compatibility.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

cluster_pool_identifier
required
string
Example: abc1234abc

A unique identifier for a cluster pool.

Request Body schema: application/json
required
name
required
string

Name of the worker pool.

cpuCoreCount
required
integer >= 1

Number of vCPU cores per worker node.

memory
required
integer >= 2

Memory (GB) per worker node.

disk
required
integer >= 20

Root disk size (GB) per worker node.

hasExtraStorage
integer

Whether the pool provides extra storage (1) or not (0).

extraStorage
integer

Extra storage size (GB) per worker node.

Responses

Request samples

Content type
application/json
{
  • "name": "default-pool",
  • "cpuCoreCount": 4,
  • "memory": 8,
  • "disk": 50,
  • "hasExtraStorage": 0,
  • "extraStorage": 0
}

Response samples

Content type
application/json
{
  • "message": "Updating process has been started"
}

Delete Worker Pool

Delete a worker pool from an existing Kubernetes cluster. The pool's nodes are drained and removed asynchronously; the pool itself is removed automatically once its last node has been deleted. A single call deletes both the nodes and the pool.

A password confirmation is required for password-based users; service-token callers may omit it.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

cluster_pool_identifier
required
string
Example: abc1234abc

A unique identifier for a cluster pool.

Request Body schema: application/json
optional
password
string <password>

The current user's password. Required for password-based users.

Responses

Request samples

Content type
application/json
{
  • "password": "your-password"
}

Response samples

Content type
application/json
{
  • "message": "Cluster pool has been deleted."
}

Set Worker Pool Desired Node Count

Sets the durable desired number of worker nodes in the pool.

XKS reconciles the worker pool asynchronously toward the requested value: missing nodes are provisioned and surplus nodes are drained and removed (newest first). A successful response confirms that the desired value was stored, but does not guarantee that all requested nodes are already deployed — observe progress through the pool's nodes collection.

The operation is idempotent: repeating the same desired node count does not create additional nodes. A new request replaces the previously stored desired value, even while a reconciliation is still running.

Manual node operations stay in sync with the stored value: adding a node through the pool nodes endpoint increments desiredNodeCount by one and deleting a node decrements it by one.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

cluster_pool_identifier
required
string
Example: abc1234abc

A unique identifier for a cluster pool.

Request Body schema: application/json
required
desiredNodeCount
required
integer >= 0

The durable desired number of worker nodes in the pool.

Responses

Request samples

Content type
application/json
{
  • "desiredNodeCount": 5
}

Response samples

Content type
application/json
{
  • "desiredNodeCount": 5
}

List Control Planes

List the Control Planes on the existing Kubernetes Cluster.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

Responses

Response samples

Content type
application/json
{
  • "controlPlaneCpu": 4,
  • "controlPlaneDisk": 50,
  • "controlPlaneRam": 4,
  • "nodes": [
    • {
      • "identifier": "abc1234abc",
      • "localvmid": "vm1234567890",
      • "name": "hpc-cluster-cp-1-1"
      }
    ]
}

Update Control Planes

Update the resources (CPU / memory / disk) of the cluster's control plane nodes. The update runs asynchronously; the response confirms that the work has started.

The cluster must be in a stable state — the request is rejected with 422 when the cluster is currently being created, deleted, upgraded, or already has a control-plane update in progress.

Request fields use camelCase (the v2-canonical style). The legacy snake_case names are still accepted for backwards compatibility.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

Request Body schema: application/json
required
cpuCoreCount
required
integer

Number of vCPU cores per control plane node.

memory
required
integer

Memory (GB) per control plane node.

disk
required
integer

Root disk size (GB) per control plane node.

Responses

Request samples

Content type
application/json
{
  • "cpuCoreCount": 4,
  • "memory": 8,
  • "disk": 60
}

Response samples

Content type
application/json
{
  • "message": "Updating process has been started"
}

Update Allowed IPs

Update the IP allow-list for the cluster's Kubernetes API (k8s) or Talos API (talos) endpoint. The firewall rules are applied asynchronously.

ips is a comma- or space-separated list of IPv4/IPv6 addresses or ranges, in either pattern format (e.g. 192.168.*.*) or CIDR/subnet format (e.g. 192.168.0.0/16). An unrecognised value is rejected with 422. Send an empty ips to clear the allow-list.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

Request Body schema: application/json
required
type
required
string
Enum: "k8s" "talos"

Which endpoint's allow-list to update.

ips
string or null

Comma/space-separated list of IPs or ranges. Empty clears the allow-list.

Responses

Request samples

Content type
application/json
{
  • "type": "k8s",
  • "ips": "192.168.0.0/16, 10.0.0.1"
}

Response samples

Content type
application/json
{
  • "message": "Allowed IPs update has started."
}

Upgrade Cluster to Production Mode

Upgrade a test-mode cluster (single control plane + single load balancer) to production mode (highly-available: additional control planes and a second load balancer). The upgrade runs asynchronously.

The request is rejected with 422 when the cluster is already in production mode, or when it is in a state that does not allow the upgrade (being created, deleted, upgraded, or updating control planes).

A password confirmation is required for password-based users; service-token callers may omit it.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

Request Body schema: application/json
optional
password
string <password>

The current user's password. Required for password-based users.

Responses

Request samples

Content type
application/json
{
  • "password": "your-password"
}

Response samples

Content type
application/json
{
  • "message": "Upgrade to production mode has started."
}

List Available Kubernetes Versions

List the Kubernetes versions the cluster can currently be upgraded to, based on its current Kubernetes/Talos versions and the supported upgrade path.

The cluster must be Ready (the lookup queries the live cluster) — otherwise the endpoint responds with 422.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

Responses

Response samples

Content type
application/json
[
  • "1.31.0",
  • "1.32.0"
]

Upgrade Kubernetes Version

Upgrade the cluster's Kubernetes version. The upgrade runs asynchronously.

The cluster must be Ready. version must be a valid *.*.* version that is a supported upgrade target — call GET /kubernetes/{kubernetes_cluster_identifier}/k8s-versions first. The request is rejected with 422 for a not-Ready cluster, an invalid format, an in-progress upgrade, an incompatible Talos/Kubernetes combination, a downgrade, or a target above the highest allowed version.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

Request Body schema: application/json
required
version
required
string

The target Kubernetes version (*.*.*).

Responses

Request samples

Content type
application/json
{
  • "version": "1.32.0"
}

Response samples

Content type
application/json
{
  • "message": "Upgrade to newer version has started."
}

List Available Talos Versions

List the Talos OS versions the cluster can currently be upgraded to, based on its current Kubernetes version and the supported compatibility matrix.

The cluster must be Ready (the lookup queries the live cluster) — otherwise the endpoint responds with 422.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

Responses

Response samples

Content type
application/json
[
  • "1.8.0",
  • "1.9.0"
]

Upgrade Talos Version

Upgrade the cluster's Talos OS version. The upgrade runs asynchronously.

The cluster must be Ready. version must be a valid *.*.* version that is compatible with the cluster's current Kubernetes version and supported by the platform's talosctl tooling. Call GET /kubernetes/{kubernetes_cluster_identifier}/talos-versions first. The request is rejected with 422 for a not-Ready cluster, an invalid format, or an unsupported version.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

Request Body schema: application/json
required
version
required
string

The target Talos OS version (*.*.*).

Responses

Request samples

Content type
application/json
{
  • "version": "1.9.0"
}

Response samples

Content type
application/json
{
  • "message": "Upgrade to newer version has started."
}

Check Cluster Health

Trigger an asynchronous health check of the cluster's control planes. The response confirms that the check has started; results are reflected in the cluster info and list endpoints once available.

The request is rejected with 422 when the cluster is in a state that does not allow a health check (being created, deleted, upgraded, or updating control planes).

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

Responses

Response samples

Content type
application/json
{
  • "message": "Checking health process has been started"
}

Get Cluster Info

Get general information about the cluster — status, mode (test / production / deploying), Talos API endpoint and allow-list, Talos version, and the current health and status of each control plane.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

Responses

Response samples

Content type
application/json
{
  • "identifier": "abc123abc456",
  • "clusterName": "my-k8s-cluster",
  • "clusterStatus": "Ready",
  • "clusterMode": "test",
  • "talosApiEndpoint": "203.0.113.10:50000",
  • "talosApiAllowedIps": [
    • "10.0.0.0/8"
    ],
  • "talosVersion": "1.8.0",
  • "controlPlanesHealth": [
    • {
      • "controlPlaneNumber": 1,
      • "health": "OK",
      • "lastHealthCheck": "2026-05-31T10:00:00Z"
      }
    ],
  • "controlPlanesStatus": [
    • "Ready"
    ]
}

Get Cluster Resources

Get the aggregated resource usage across the cluster — total node count and the summed vCPU, memory (GB) and disk (GB) of all control planes, worker pool nodes and load balancers.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

Responses

Response samples

Content type
application/json
{
  • "nodes": 4,
  • "cpu": 10,
  • "ram": 24,
  • "disk": 320
}

Get Kubernetes Cluster Config

Get the cluster's Kubernetes configuration metadata — domain, extra API server arguments, pod/service subnets, the Kubernetes API endpoint and its allow-list, and the current Kubernetes version.

This returns a JSON description of the configuration. To download the actual kubeconfig / talosconfig files, use GET /kubernetes/{kubernetes_cluster_identifier}/config/{type}.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

Responses

Response samples

Content type
application/json
{
  • "clusterDomain": "cluster.local",
  • "extraArgs": "",
  • "podSubnet": "10.244.0.0/16",
  • "serviceSubnet": "10.96.0.0/12",
  • "k8sApiEndpoint": "203.0.113.10:6443",
  • "k8sApiAllowedIps": [
    • "10.0.0.0/8"
    ],
  • "k8sVersion": "v1.31.0"
}

Get Cluster Load Balancers

List the load balancer clusters fronting the Kubernetes cluster, each with its node specification (CPU cores, memory and disk size) and its individual load balancers and their WAN IP addresses.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

Responses

Response samples

Content type
application/json
[
  • {
    • "clusterName": "k8s-lb-cluster",
    • "loadBalancerCpu": 2,
    • "loadBalancerRam": 4,
    • "loadBalancerDisk": 50,
    • "loadBalancers": [
      • {
        • "loadBalancerName": "Load Balancer 1",
        • "loadBalancerIp": "203.0.113.10"
        }
      ]
    }
]

Download Cluster Config (kubeconfig / talosconfig)

Download the cluster's connection credentials as a YAML file.

  • type=kube returns the kubeconfig — feed it to kubectl.
  • type=talos returns the talosconfig — feed it to talosctl.

The response is a raw YAML document served as a file download, not a JSON envelope. The type segment may be omitted (GET /kubernetes/{kubernetes_cluster_identifier}/config), in which case it defaults to kube and the kubeconfig is returned.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

type
required
string
Default: "kube"
Enum: "kube" "talos"
Example: kube

Which config to download: kube for the kubeconfig (kubectl) or talos for the talosconfig (talosctl).

Responses

Response samples

Content type
application/yaml
apiVersion: v1
kind: Config
clusters:
  - name: my-k8s-cluster
    cluster:
      server: https://203.0.113.10:6443
      certificate-authority-data: LS0tLS1CRUdJTi...
users:
  - name: admin@my-k8s-cluster
    user:
      client-certificate-data: LS0tLS1CRUdJTi...
      client-key-data: LS0tLS1CRUdJTi...
contexts:
  - name: admin@my-k8s-cluster
    context:
      cluster: my-k8s-cluster
      user: admin@my-k8s-cluster
current-context: admin@my-k8s-cluster

Create Pool Node

Create Pool Node in the existing Kubernetes Cluster.

If the pool has a stored desiredNodeCount, adding a node increments it by one so the declarative target keeps matching the pool's actual size.

Requires the allow_manage_kubernetes permission.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

cluster_pool_identifier
required
string
Example: abc1234abc

A unique identifier for a cluster pool.

Responses

Response samples

Content type
application/json
{
  • "success": "Cluster node will be added shortly"
}

Delete Pool Node

Delete Pool Node in the existing Kubernetes Cluster.

If the pool has a stored desiredNodeCount, deleting a node decrements it by one so the declarative target keeps matching the pool's actual size.

Requires the allow_manage_kubernetes permission.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

cluster_node_identifier
required
string
Example: abc1234abc

A unique identifier for a cluster node.

Responses

Response samples

Content type
application/json
{
  • "success": "Cluster node has been deleted."
}

Activity

Activity logs track actions performed by users and service tokens across all resources.

Get Kubernetes Cluster Activity

Returns a paginated list of activity log entries for a specific Kubernetes Talos cluster. Requires the allow_manage_kubernetes permission.

Authorizations:
service_token
path Parameters
cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes Talos cluster.

query Parameters
search
string
Example: search=device has been created

Search query to filter activity log entries. The search is case-insensitive.

filter
string
Example: filter=App\Vms

Filter activity log entries by category/type. Available categories for this log type can be retrieved from the corresponding endpoint.

perPage
integer
Example: perPage=25

The number of items to display per page.

page
integer
Example: page=1

The page number to retrieve.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "internalId": "64b1f2e3a5c9d80012345678",
      • "user": "[email protected]",
      • "body": "Virtual machine created",
      • "createdOn": "2024-05-10T12:34:56Z"
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "lastPage": 5,
    • "perPage": 25,
    • "total": 112
    }
}

Export Cluster Activity

Export the cluster's activity log for a given period as a downloadable ZIP archive.

When the number of matching log entries exceeds the download threshold, the archive is generated asynchronously and emailed to the caller instead; in that case the endpoint responds with 202 Accepted and a confirmation message.

dateFrom and dateTo accept any standard date string (parsed server-side). ISO 8601 (YYYY-MM-DD, e.g. 2026-01-01) is recommended. A value that cannot be parsed as a date is rejected with 422.

Authorizations:
service_token
path Parameters
kubernetes_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a Kubernetes cluster.

query Parameters
dateFrom
required
string <date>
Example: dateFrom=2026-01-01

Start of the export period. ISO 8601 (YYYY-MM-DD) recommended.

dateTo
required
string <date>
Example: dateTo=2026-12-31

End of the export period. ISO 8601 (YYYY-MM-DD) recommended.

filter
string

Optional activity-category filter.

Responses

Response samples

Content type
application/json
{
  • "message": "Logs will be send to email"
}

Get Current User Activity

Returns a paginated list of activity log entries for the currently authenticated user, including actions performed via API service tokens.

Authorizations:
service_token
query Parameters
search
string
Example: search=device has been created

Search query to filter activity log entries. The search is case-insensitive.

filter
string
Example: filter=App\Vms

Filter activity log entries by category/type. Available categories for this log type can be retrieved from the corresponding endpoint.

perPage
integer
Example: perPage=25

The number of items to display per page.

page
integer
Example: page=1

The page number to retrieve.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "internalId": "64b1f2e3a5c9d80012345678",
      • "user": "[email protected]",
      • "body": "Virtual machine created",
      • "createdOn": "2024-05-10T12:34:56Z"
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "lastPage": 5,
    • "perPage": 25,
    • "total": 112
    }
}

Get Activity by Cloud

Returns a paginated list of activity log entries scoped to a specific cloud (data center). Shows activity performed by users within the authenticated user's tenant on the given cloud.

Authorizations:
service_token
path Parameters
cloud_id
required
integer
Example: 5

A unique numeric ID for a Cloud.

query Parameters
search
string
Example: search=device has been created

Search query to filter activity log entries. The search is case-insensitive.

filter
string
Example: filter=App\Vms

Filter activity log entries by category/type. Available categories for this log type can be retrieved from the corresponding endpoint.

perPage
integer
Example: perPage=25

The number of items to display per page.

page
integer
Example: page=1

The page number to retrieve.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "internalId": "64b1f2e3a5c9d80012345678",
      • "user": "[email protected]",
      • "body": "Virtual machine created",
      • "createdOn": "2024-05-10T12:34:56Z"
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "lastPage": 5,
    • "perPage": 25,
    • "total": 112
    }
}

Get Activity Categories by Cloud

Returns a list of available activity categories for a specific cloud. Can be filtered to the current month by passing the isMonthly query parameter.

Authorizations:
service_token
path Parameters
cloud_id
required
integer
Example: 5

A unique numeric ID for a Cloud.

query Parameters
isMonthly
boolean
Example: isMonthly=true

When set to true, returns activity categories grouped by the current month only.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "label": "Virtual Machine Created",
      • "value": "App\\Events\\VirtualMachine\\VirtualMachineCreated"
      }
    ]
}

Get User Activity

Returns a paginated list of activity log entries for a specific user by their ID. Requires the allow_manage_users permission.

Authorizations:
service_token
path Parameters
user_id
required
integer
Example: 123

A unique numeric ID for a User.

query Parameters
search
string
Example: search=device has been created

Search query to filter activity log entries. The search is case-insensitive.

filter
string
Example: filter=App\Vms

Filter activity log entries by category/type. Available categories for this log type can be retrieved from the corresponding endpoint.

perPage
integer
Example: perPage=25

The number of items to display per page.

page
integer
Example: page=1

The page number to retrieve.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "internalId": "64b1f2e3a5c9d80012345678",
      • "user": "[email protected]",
      • "body": "Virtual machine created",
      • "createdOn": "2024-05-10T12:34:56Z"
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "lastPage": 5,
    • "perPage": 25,
    • "total": 112
    }
}

Get User Activity Categories

Returns a list of available activity categories for a specific user by their ID. Requires the allow_manage_users permission. Can be filtered to the current month by passing the isMonthly query parameter.

Authorizations:
service_token
path Parameters
user_id
required
integer
Example: 123

A unique numeric ID for a User.

query Parameters
isMonthly
boolean
Example: isMonthly=true

When set to true, returns activity categories grouped by the current month only.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "label": "Virtual Machine Created",
      • "value": "App\\Events\\VirtualMachine\\VirtualMachineCreated"
      }
    ]
}

Get Tenant Activity

Returns a paginated list of activity log entries scoped to a specific tenant. Requires the allow_view_organizations permission.

Authorizations:
service_token
path Parameters
tenant_identifier
required
string
Example: abc123abc456

A unique identifier for a Tenant.

query Parameters
search
string
Example: search=device has been created

Search query to filter activity log entries. The search is case-insensitive.

filter
string
Example: filter=App\Vms

Filter activity log entries by category/type. Available categories for this log type can be retrieved from the corresponding endpoint.

perPage
integer
Example: perPage=25

The number of items to display per page.

page
integer
Example: page=1

The page number to retrieve.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "internalId": "64b1f2e3a5c9d80012345678",
      • "user": "[email protected]",
      • "body": "Virtual machine created",
      • "createdOn": "2024-05-10T12:34:56Z"
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "lastPage": 5,
    • "perPage": 25,
    • "total": 112
    }
}

Get Tenant Activity Categories

Returns a list of available activity categories for a specific tenant. Requires the allow_view_organizations permission. Can be filtered to the current month by passing the isMonthly query parameter.

Authorizations:
service_token
path Parameters
tenant_identifier
required
string
Example: abc123abc456

A unique identifier for a Tenant.

query Parameters
isMonthly
boolean
Example: isMonthly=true

When set to true, returns activity categories grouped by the current month only.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "label": "Virtual Machine Created",
      • "value": "App\\Events\\VirtualMachine\\VirtualMachineCreated"
      }
    ]
}

Get Sub-Tenants Activity

Returns a paginated list of activity log entries across all sub-tenants of the specified tenant. Requires the allow_view_organizations permission.

Authorizations:
service_token
path Parameters
tenant_identifier
required
string
Example: abc123abc456

A unique identifier for a Tenant.

query Parameters
search
string
Example: search=device has been created

Search query to filter activity log entries. The search is case-insensitive.

filter
string
Example: filter=App\Vms

Filter activity log entries by category/type. Available categories for this log type can be retrieved from the corresponding endpoint.

perPage
integer
Example: perPage=25

The number of items to display per page.

page
integer
Example: page=1

The page number to retrieve.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "internalId": "64b1f2e3a5c9d80012345678",
      • "user": "[email protected]",
      • "body": "Virtual machine created",
      • "createdOn": "2024-05-10T12:34:56Z"
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "lastPage": 5,
    • "perPage": 25,
    • "total": 112
    }
}

Get Sub-Tenants Activity Categories

Returns a list of available activity categories across all sub-tenants of the specified tenant. Requires the allow_view_organizations permission.

Authorizations:
service_token
path Parameters
tenant_identifier
required
string
Example: abc123abc456

A unique identifier for a Tenant.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "label": "Virtual Machine Created",
      • "value": "App\\Events\\VirtualMachine\\VirtualMachineCreated"
      }
    ]
}

Get Device Activity

Returns a paginated list of activity log entries for a specific device. Requires the allow_view_virtual_machines permission.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

query Parameters
search
string
Example: search=device has been created

Search query to filter activity log entries. The search is case-insensitive.

filter
string
Example: filter=App\Vms

Filter activity log entries by category/type. Available categories for this log type can be retrieved from the corresponding endpoint.

perPage
integer
Example: perPage=25

The number of items to display per page.

page
integer
Example: page=1

The page number to retrieve.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "internalId": "64b1f2e3a5c9d80012345678",
      • "user": "[email protected]",
      • "body": "Virtual machine created",
      • "createdOn": "2024-05-10T12:34:56Z"
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "lastPage": 5,
    • "perPage": 25,
    • "total": 112
    }
}

Load Balancer Clusters

Load balancers sit in front of your application and distribute incoming traffic across multiple Devices.

List Load Balancer Clusters

List the Load Balancer Clusters in your account.

Authorizations:
service_token

Responses

Response samples

Content type
application/json
[
  • {
    • "createdAt": "2024-03-19T17:24:26+01:00",
    • "hv_system": {
      • "display_short_name": "Aargau",
      • "id": 6
      },
    • "identifier": "abc123abc456",
    • "kubernetesClusterIdentifier": "abc123abc456",
    • "name": "my-hcp-load-balancer-cluster",
    • "nodes": [
      • "abc123abc123",
      • "def456def456"
      ],
    • "status": "Active",
    • "tenantIdentifier": "abc12345"
    }
]

Create Load Balancer Cluster

Create a new Load Balancer Cluster.

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

cloudId
required
integer

The cloud ID of the load balancer cluster.

kubernetesClusterIdentifier
required
string

The Identifier of the kubernetes cluster.

name
required
string

The name of the load balancer cluster. Only lowercase letters, numbers and hyphen-minus (-) allowed, without spaces.

required
object

Nodes specification parameters like CPU cores, memory and disk size.

Responses

Request samples

Content type
application/json
{
  • "cloudId": 6,
  • "name": "my-hcp-load-balancer-cluster",
  • "kubernetesClusterIdentifier": "abc123abc456",
  • "nodesSpec": {
    • "cpuCoreCount": 2,
    • "disk": 50,
    • "memory": 4
    }
}

Response samples

Content type
application/json
{
  • "identifier": "abc123abc123",
  • "status": "Provisioning"
}

Get Load Balancer Cluster

Get information for the Load Balancer Cluster.

Authorizations:
service_token
path Parameters
load_balancer_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a load balancer cluster.

Responses

Response samples

Content type
application/json
{
  • "hv_system": {
    • "display_short_name": "Aargau",
    • "id": 6
    },
  • "identifier": "abc123abc123",
  • "kubernetesClusterIdentifier": "abc123abc123",
  • "name": "scale cluster (k8s lb cluster)",
  • "status": "Provisioning"
}

Update Load Balancer Cluster

Update information for the Load Balancer Cluster. All attributes are optional. If not set, the attributes will retain their original values.

Authorizations:
service_token
path Parameters
load_balancer_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a load balancer cluster.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
required
string

The name of the load balancer cluster. Only lowercase letters, numbers and hyphen-minus (-) allowed, without spaces.

Responses

Request samples

Content type
application/json
{
  • "name": "my-hcp-load-balancer-cluster"
}

Response samples

Content type
application/json
{
  • "success": "Load balancer cluster has been updated"
}

Delete Load Balancer Cluster

Delete the Load Balancer Cluster.

Authorizations:
service_token
path Parameters
load_balancer_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a load balancer cluster.

Responses

Response samples

Content type
application/json
{
  • "success": "Load balancer cluster has been deleted"
}

List Virtual IPs

List the Virtual IPs on the existing Load Balancer Cluster.

Authorizations:
service_token
path Parameters
load_balancer_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a load balancer cluster.

Responses

Response samples

Content type
application/json
[
  • {
    • "ipAddress": "88.77.66.55",
    • "identifier": "abc123abc123",
    • "vipPoolIdentifier": "abc456abc456",
    • "state": "free"
    }
]

Get Virtual IP

Get information for the Virtual IP.

Authorizations:
service_token
path Parameters
load_balancer_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a load balancer cluster.

virtual_ip_identifier
required
string
Example: abc123abc456

A unique identifier for a virtual ip address.

Responses

Response samples

Content type
application/json
{
  • "ipAddress": "88.77.66.55",
  • "identifier": "abc123abc123",
  • "vipPoolIdentifier": "abc456abc456",
  • "state": "free"
}

List Forwarding Rules

List the Forwarding Rules for the Virtual IP.

Authorizations:
service_token
path Parameters
load_balancer_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a load balancer cluster.

virtual_ip_identifier
required
string
Example: abc123abc456

A unique identifier for a virtual ip address.

Responses

Response samples

Content type
application/json
[
  • {
    • "backend": {
      • "identifier": "abc123abc123",
      • "port": 5432,
      • "proxy_protocol": 0
      },
    • "frontend": {
      • "identifier": "def456def456",
      • "port": 8080
      }
    }
]

Create Forwarding Rules

Create Forwarding Rules for the Virtual IP.

Authorizations:
service_token
path Parameters
load_balancer_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a load balancer cluster.

virtual_ip_identifier
required
string
Example: abc123abc456

A unique identifier for a virtual ip address.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

required
object

The backend configuration

required
object

The frontend configuration

Responses

Request samples

Content type
application/json
[
  • {
    • "backend": {
      • "port": 5432,
      • "proxy_protocol": 0,
      • "server_groups": {
        • "controlplanes2": true,
        • "workers3": false,
        • "workers1": false
        },
      • "server_ips": [
        • "1.1.1.1",
        • "1.1.1.2"
        ]
      },
    • "frontend": {
      • "port": 8080
      }
    }
]

Response samples

Content type
application/json
[
  • {
    • "backend": {
      • "identifier": "abc123abc456",
      • "port": 5432,
      • "proxy_protocol": 1
      },
    • "frontend": {
      • "identifier": "def456def456",
      • "port": 8080
      }
    }
]

Update Forwarding Rules

Update Forwarding Rules for the Virtual IP.

Authorizations:
service_token
path Parameters
load_balancer_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a load balancer cluster.

virtual_ip_identifier
required
string
Example: abc123abc456

A unique identifier for a virtual ip address.

forwarding_rule_identifier
required
string
Example: abc123abc456

A unique identifier for a forwarding rule.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

port
required
number

The port number on the Virtual IP to forward to the backend.

proxy_protocol
number

Proxy protocol parameter.

Responses

Request samples

Content type
application/json
{
  • "port": 5432,
  • "proxy_protocol": 1
}

Response samples

Content type
application/json
{
  • "success": "Forwarding rule has been updated"
}

Delete Forwarding Rules

Delete Forwarding Rules for the Virtual IP.

Authorizations:
service_token
path Parameters
load_balancer_cluster_identifier
required
string
Example: abc123abc456

A unique identifier for a load balancer cluster.

virtual_ip_identifier
required
string
Example: abc123abc456

A unique identifier for a virtual ip address.

forwarding_rule_identifier
required
string
Example: abc123abc456

A unique identifier for a forwarding rule.

Responses

Response samples

Content type
application/json
{
  • "success": "Forwarding rule has been deleted"
}

Labels

Labels are used to organize and categorize your devices.

List Labels

Get a list of all labels.

Authorizations:
service_token
query Parameters
page
integer
Default: 1

Page number

perPage
integer
Default: 5

Number of items per page

search
string <= 512 characters

Search string

sort
string
Enum: "name" "createdAt"

Field to sort by (required with order)

order
string
Enum: "asc" "desc"

Sort direction (required with sort)

tenantIdentifier
string

Filter labels by tenant identifier

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": 0,
      • "name": "string",
      • "colorId": 0,
      • "textColor": "string",
      • "backgroundColor": "string",
      • "tenantName": "string",
      • "createdAt": "2019-08-24T14:15:22Z",
      • "devices": [
        • {
          • "identifier": "string",
          • "name": "string"
          }
        ]
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "from": 1,
    • "lastPage": 13,
    • "perPage": 5,
    • "to": 5,
    • "total": 64
    }
}

Create Label

Create a new label.

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
required
string <= 32 characters

Label name

colorId
required
integer

Label color ID

deviceIdentifiers
Array of strings or null

List of device identifiers to attach this label to

tenantIdentifier
string or null

Tenant identifier

Responses

Request samples

Content type
application/json
{
  • "name": "Production",
  • "colorId": 3,
  • "deviceIdentifiers": [
    • "abc123def456"
    ],
  • "tenantIdentifier": null
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 0,
    • "name": "string",
    • "colorId": 0,
    • "textColor": "string",
    • "backgroundColor": "string",
    • "tenantName": "string",
    • "createdAt": "2019-08-24T14:15:22Z"
    },
  • "message": "string"
}

List Label Colors

Get a list of available label colors.

Authorizations:
service_token

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": 0,
      • "name": "string",
      • "textColor": "string",
      • "backgroundColor": "string"
      }
    ]
}

Update Label

Update an existing label.

Authorizations:
service_token
path Parameters
labelId
required
integer
Example: 42

A unique identifier for a Label.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
required
string <= 32 characters

Label name

colorId
required
integer

Label color ID

deviceIdentifiers
Array of strings or null

List of device identifiers to associate with this label. The value fully replaces the existing associations (sync semantics); pass an empty array to detach all devices.

tenantIdentifier
string or null

Tenant identifier

Responses

Request samples

Content type
application/json
{
  • "name": "Production",
  • "colorId": 3,
  • "deviceIdentifiers": [
    • "abc123def456"
    ],
  • "tenantIdentifier": null
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 0,
    • "name": "string",
    • "colorId": 0,
    • "textColor": "string",
    • "backgroundColor": "string",
    • "tenantName": "string",
    • "createdAt": "2019-08-24T14:15:22Z"
    },
  • "message": "string"
}

Delete Label

Delete a label.

Authorizations:
service_token
path Parameters
labelId
required
integer
Example: 42

A unique identifier for a Label.

Responses

Response samples

Content type
application/json
{
  • "message": "Success"
}

Segregation Rules

Segregation Rules enforce placement policies for devices across hypervisors.

List Segregation Rules

Get a list of segregation rules for a tenant.

Authorizations:
service_token
query Parameters
cloudIdentifier
required
string

Cloud identifier

tenantIdentifier
required
string

Tenant identifier

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "string",
      • "status": "Provisioning",
      • "cloud": {
        • "identifier": "string",
        • "name": "string"
        },
      • "name": "string",
      • "description": "string",
      • "type": "string",
      • "created_at": "2019-08-24T14:15:22Z",
      • "updated_at": "2019-08-24T14:15:22Z"
      }
    ]
}

Create Segregation Rule

Create a new segregation rule.

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
required
string

Segregation rule name

description
string or null

Segregation rule description

type
required
string

Segregation rule type

cloudIdentifier
required
string

Cloud identifier

devices
required
Array of strings [ 2 .. 5 ] items

List of device identifiers (2 to 5 devices)

tenantIdentifier
required
string

Tenant identifier

Responses

Request samples

Content type
application/json
{
  • "name": "Rule-1",
  • "description": "Keeps VMs on different hosts",
  • "type": "separate",
  • "cloudIdentifier": "abc123def456",
  • "devices": [
    • "device1identifier",
    • "device2identifier"
    ],
  • "tenantIdentifier": "tenant123"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123def456",
    • "status": "Provisioning",
    • "cloud": {
      • "identifier": "cloud1identifier",
      • "name": "Cloud 1"
      },
    • "name": "Rule-1",
    • "description": "Keeps VMs on different hosts",
    • "type": "separate",
    • "devices": [
      • {
        • "identifier": "device1identifier",
        • "name": "web-server-1"
        },
      • {
        • "identifier": "device2identifier",
        • "name": "web-server-2"
        }
      ],
    • "created_at": "2026-01-01T12:00:00Z",
    • "updated_at": "2026-01-01T12:00:00Z"
    },
  • "message": "Rule has been created"
}

Get Segregation Rule

Get details of a specific segregation rule.

Authorizations:
service_token
path Parameters
identifier
required
string

Segregation rule identifier

Responses

Response samples

Content type
application/json
{
  • "identifier": "string",
  • "status": "Provisioning",
  • "cloud": {
    • "identifier": "string",
    • "name": "string"
    },
  • "name": "string",
  • "description": "string",
  • "type": "string",
  • "devices": [
    • {
      • "identifier": "string",
      • "name": "string"
      }
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Segregation Rule

Update an existing segregation rule.

Authorizations:
service_token
path Parameters
identifier
required
string

Segregation rule identifier

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
required
string

Segregation rule name

description
string or null

Segregation rule description

type
required
string

Segregation rule type

cloudIdentifier
required
string

Cloud identifier

devices
required
Array of strings [ 2 .. 5 ] items

List of device identifiers (2 to 5 devices)

tenantIdentifier
required
string

Tenant identifier

Responses

Request samples

Content type
application/json
{
  • "name": "Rule-1-updated",
  • "description": "Updated rule description",
  • "type": "separate",
  • "cloudIdentifier": "abc123def456",
  • "devices": [
    • "device1identifier",
    • "device3identifier"
    ],
  • "tenantIdentifier": "tenant123"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "abc123def456",
    • "status": "Ready",
    • "cloud": {
      • "identifier": "cloud1identifier",
      • "name": "Cloud 1"
      },
    • "name": "Rule-1-updated",
    • "description": "Updated rule description",
    • "type": "separate",
    • "devices": [
      • {
        • "identifier": "device1identifier",
        • "name": "web-server-1"
        },
      • {
        • "identifier": "device3identifier",
        • "name": "web-server-3"
        }
      ],
    • "created_at": "2026-01-01T12:00:00Z",
    • "updated_at": "2026-01-01T12:30:00Z"
    },
  • "message": "Rule has been updated"
}

Delete Segregation Rule

Delete a segregation rule.

Authorizations:
service_token
path Parameters
identifier
required
string

Segregation rule identifier

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

cloudIdentifier
required
string

Cloud identifier

tenantIdentifier
required
string

Tenant identifier

password
string

User password (required for non-service, password-based users; not required for service accounts or Microsoft SSO-authenticated users)

Responses

Request samples

Content type
application/json
{
  • "cloudIdentifier": "abc123def456",
  • "tenantIdentifier": "tenant123",
  • "password": "secret"
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Active Sessions

Active Sessions track authenticated user sessions and their duration.

List Active Sessions

Get a paginated list of currently active sessions for a tenant's users.

Authorizations:
service_token
query Parameters
page
integer
Default: 1

Page number

perPage
integer
Default: 25

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "string",
      • "userName": "string",
      • "userEmail": "string",
      • "ip": "string",
      • "userAgent": "string",
      • "lastActivity": "2019-08-24T14:15:22Z",
      • "expiresAt": "2019-08-24T14:15:22Z"
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "from": 1,
    • "lastPage": 13,
    • "perPage": 5,
    • "to": 5,
    • "total": 64
    }
}

List Expired Sessions

Get a paginated list of expired sessions for the authenticated user's tenant.

Authorizations:
service_token
query Parameters
page
integer
Default: 1

Page number

perPage
integer
Default: 25

Number of items per page

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "string",
      • "userName": "string",
      • "userEmail": "string",
      • "ip": "string",
      • "userAgent": "string",
      • "lastActivity": "2019-08-24T14:15:22Z",
      • "expiresAt": "2019-08-24T14:15:22Z"
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "from": 1,
    • "lastPage": 13,
    • "perPage": 5,
    • "to": 5,
    • "total": 64
    }
}

Get Session Duration

Get the active session duration (TTL in days) for the authenticated user's tenant.

Authorizations:
service_token

Responses

Response samples

Content type
application/json
7

Update Session Duration

Update the active session duration (TTL in days) for the authenticated user's tenant.

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

duration
required
integer
Enum: 1 7 14 30

Session duration in days

Responses

Request samples

Content type
application/json
{
  • "duration": 7
}

Response samples

Content type
application/json
{
  • "message": "Session duration has been updated."
}

Get Session IP Binding

Get whether session source-IP binding is enabled for the authenticated user's tenant. When enabled, POST /user/refresh refuses to reissue a token whose recorded login IP differs from the current request IP, forcing a fresh sign-in after a network change.

Authorizations:
service_token

Responses

Response samples

Content type
application/json
{
  • "enabled": true
}

Update Session IP Binding

Enable or disable session source-IP binding for the authenticated user's tenant.

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

enabled
required
boolean

Whether session source-IP binding should be enforced for the tenant.

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "message": "Session IP binding has been updated."
}

Expire Session

Invalidate (expire) a specific active session.

Authorizations:
service_token
path Parameters
sessionIdentifier
required
string

Session identifier

Responses

Response samples

Content type
application/json
{
  • "message": "Success"
}

WAF

Web Application Firewall (WAF) protects your applications from web-based attacks.

List WAF OWASP Rules

Get a list of available OWASP security rules for WAF.

Authorizations:
service_token

Responses

Response samples

Content type
application/json
{
  • "property1": [
    • {
      • "id": 0,
      • "group": "string",
      • "name": "string",
      • "description": "string"
      }
    ],
  • "property2": [
    • {
      • "id": 0,
      • "group": "string",
      • "name": "string",
      • "description": "string"
      }
    ]
}

Update WAF

Update a Web Application Firewall field (e.g. name).

Authorizations:
service_token
path Parameters
wafId
required
integer

WAF ID

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
required
string

Field name to update (e.g. "name")

value
required
string

New value for the field

Responses

Request samples

Content type
application/json
{
  • "name": "name",
  • "value": "new-waf-name"
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Delete WAF

Delete a Web Application Firewall.

Authorizations:
service_token
path Parameters
wafId
required
integer

WAF ID

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

password
string

User password (required for non-service, password-based users; not required for service accounts or Microsoft SSO-authenticated users)

Responses

Request samples

Content type
application/json
{
  • "password": "secret"
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Attach Devices to WAF

Attach or sync devices (servers) to a Web Application Firewall.

Authorizations:
service_token
path Parameters
wafId
required
integer

WAF ID

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

attached_servers
required
Array of integers

List of server IDs to attach to the WAF

Responses

Request samples

Content type
application/json
{
  • "attached_servers": [
    • 42,
    • 43
    ]
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Update WAF Forwarding Rule

Update a forwarding rule for a Web Application Firewall.

Authorizations:
service_token
path Parameters
wafId
required
integer

WAF ID

forwardingRuleId
required
integer

Forwarding rule ID

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

ip
required
Array of strings

Backend IP:port addresses (format: '10.0.0.1:80')

url
string or null

URL/domain

ssl_certificate
string or null

SSL certificate content

maintenance_mode
boolean

Enable maintenance mode

ssl_autogenerate
boolean

Auto-generate SSL certificate

ssl_backend
boolean or null

Enable SSL on backend

owasp_security_rules
Array of integers or null

List of OWASP security rule IDs

generate_www_letsencrypt
boolean or null

Generate www Let's Encrypt certificate

Responses

Request samples

Content type
application/json
{
  • "ip": [
    • "10.0.0.10:80"
    ],
  • "url": "example.com",
  • "ssl_autogenerate": true,
  • "maintenance_mode": false
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "forwardingRules": [
    • {
      • "id": 0,
      • "ip": [
        • "string"
        ],
      • "url": "string",
      • "maintenance_mode": true,
      • "ssl_autogenerate": true,
      • "ssl_backend": true,
      • "owasp_security_rules": [
        • 0
        ],
      • "generate_www_letsencrypt": true
      }
    ]
}

List WAF

Get a list of Web Application Firewalls for a tenant.

Authorizations:
service_token
path Parameters
tenant_identifier
required
string

Tenant identifier

query Parameters
cloudId
integer

Filter by cloud ID

Responses

Response samples

Content type
application/json
[
  • {
    • "name": "string",
    • "type": "string",
    • "network_id": 0,
    • "hv_system_id": 0,
    • "hv_type": "string",
    • "health": "string",
    • "ip": "string",
    • "internalIp": "string",
    • "breadcrumbs": "string",
    • "forwardingRules": [
      • {
        • "id": 0,
        • "ip": [
          • "string"
          ],
        • "url": "string",
        • "maintenance_mode": true,
        • "ssl_autogenerate": true
        }
      ],
    • "tenant": {
      • "id": 0,
      • "tenantname": "string",
      • "parent": 0
      },
    • "hvSystem": {
      • "id": 0,
      • "display_short_name": "string",
      • "type": "string"
      }
    }
]

Create WAF

Create a new Web Application Firewall.

Authorizations:
service_token
path Parameters
tenant_identifier
required
string

Tenant identifier

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
required
string

WAF name

type
string
Enum: "servers" "k8s"

WAF type

cloudId
integer or null

Cloud ID (optional, uses tenant's default cloud if not provided)

server_id
Array of arrays or integers or integer

Server ID(s) — use array for k8s type

internal_network_id
integer or null

Internal network ID (required for servers type)

external_network_id
integer or null

External (WAN) network ID

external_ip_id
integer or null

External IP ID

internal_ip_id
integer or null

Internal LAN IP ID

ip
string or null

Custom internal IP address (alternative to internal_ip_id)

required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "name": "my-waf",
  • "type": "servers",
  • "cloudId": 1,
  • "server_id": [
    • 42
    ],
  • "internal_network_id": 5,
  • "forwarding_rules": [
    • {
      • "ip": [
        • "10.0.0.10:80"
        ],
      • "url": "example.com",
      • "ssl_autogenerate": true,
      • "maintenance_mode": false
      }
    ]
}

Response samples

Content type
application/json
{
  • "message": "Success"
}

Get WAF

Get details of a specific Web Application Firewall.

Authorizations:
service_token
path Parameters
tenant_identifier
required
string

Tenant identifier

wafId
required
integer

WAF ID

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "type": "string",
  • "network_id": 0,
  • "hv_system_id": 0,
  • "hv_type": "string",
  • "health": "string",
  • "ip": "string",
  • "internalIp": "string",
  • "creator": "string",
  • "owner": "string",
  • "forwardingRules": [
    • {
      • "id": 0,
      • "ip": [
        • "string"
        ],
      • "url": "string",
      • "ssl_certificate": "string",
      • "maintenance_mode": true,
      • "ssl_autogenerate": true,
      • "ssl_backend": true,
      • "owasp_security_rules": [ ],
      • "generate_www_letsencrypt": true
      }
    ],
  • "assignedServers": [
    • {
      • "id": 0,
      • "health": "string",
      • "ip": "string"
      }
    ]
}

Create WAF Forwarding Rule

Create a forwarding rule for a Web Application Firewall.

Authorizations:
service_token
path Parameters
tenant_identifier
required
string

Tenant identifier

wafId
required
integer

WAF ID

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

ip
required
Array of strings

Backend IP:port addresses (format: '10.0.0.1:80')

url
string or null

URL/domain

ssl_certificate
string or null

SSL certificate content

maintenance_mode
boolean

Enable maintenance mode

ssl_autogenerate
boolean

Auto-generate SSL certificate

ssl_backend
boolean or null

Enable SSL on backend

owasp_security_rules
Array of integers or null

List of OWASP security rule IDs

generate_www_letsencrypt
boolean or null

Generate www Let's Encrypt certificate

Responses

Request samples

Content type
application/json
{
  • "ip": [
    • "10.0.0.10:80"
    ],
  • "url": "example.com",
  • "ssl_autogenerate": true,
  • "maintenance_mode": false
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "ip": [
    • "string"
    ],
  • "url": "string",
  • "maintenance_mode": true,
  • "ssl_autogenerate": true,
  • "ssl_backend": true,
  • "owasp_security_rules": [
    • 0
    ],
  • "generate_www_letsencrypt": true
}

Delete WAF Forwarding Rule

Delete a forwarding rule from a Web Application Firewall.

Authorizations:
service_token
path Parameters
tenant_identifier
required
string

Tenant identifier

wafId
required
integer

WAF ID

forwardingRuleId
required
integer

Forwarding rule ID

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "forwardingRules": [
    • {
      • "id": 0,
      • "ip": [
        • "string"
        ],
      • "url": "string",
      • "maintenance_mode": true,
      • "ssl_autogenerate": true,
      • "ssl_backend": true,
      • "owasp_security_rules": [
        • 0
        ],
      • "generate_www_letsencrypt": true
      }
    ]
}

Revenue

Revenue reports provide billing and income analytics.

Get Income Per Resource

Get income per resource type graph data for the given date range.

Authorizations:
service_token
query Parameters
fromDate
required
string <date>

Start date (inclusive, rounded to start of month)

toDate
required
string <date>

End date (inclusive, rounded to end of month)

tenantId
string or null

Tenant identifier to filter by

Responses

Response samples

Content type
application/json
{
  • "labels": [
    • "string"
    ],
  • "data": {
    • "property1": [
      • 0
      ],
    • "property2": [
      • 0
      ]
    }
}

Get Total Income

Get total income (outgoing) graph data for a specific tenant.

Authorizations:
service_token
query Parameters
fromDate
required
string <date>

Start date (inclusive, rounded to start of month)

toDate
required
string <date>

End date (inclusive, rounded to end of month)

tenantId
required
string

Tenant identifier

Responses

Response samples

Content type
application/json
{
  • "labels": [
    • "string"
    ],
  • "data": {
    • "property1": [
      • 0
      ],
    • "property2": [
      • 0
      ]
    }
}

Get Client Rating

Get top 10 clients by revenue for the given date range.

Authorizations:
service_token
query Parameters
fromDate
required
string <date>

Start date (inclusive, rounded to start of month)

toDate
required
string <date>

End date (inclusive, rounded to end of month)

Responses

Response samples

Content type
application/json
{
  • "labels": [
    • "string"
    ],
  • "data": {
    • "property1": [
      • 0
      ],
    • "property2": [
      • 0
      ]
    }
}

Get Usage By Resource

Get usage by resource type from the last usage report for the current tenant.

Authorizations:
service_token

Responses

Response samples

Content type
application/json
{
  • "labels": [
    • "string"
    ],
  • "data": [
    • 0
    ],
  • "name": "string"
}

Get Margin Comparison

Get income vs outgoing margin comparison per resource type for a specific month.

Authorizations:
service_token
query Parameters
date
required
string <date>

Reference date (month to calculate margin for)

tenantIdentifier
string or null

Tenant identifier to filter by

Responses

Response samples

Content type
application/json
[
  • {
    • "name": "string",
    • "income": 0.1,
    • "outgoing": 0.1,
    • "margin": 0.1,
    • "marginPercent": 0.1
    }
]

Usage Reports

Usage Reports provide detailed resource consumption data for tenants.

Get Current Usage Report

Get the current (in-progress) usage report for the authenticated user's tenant.

Authorizations:
service_token

Responses

Response samples

Content type
application/json
{
  • "id": null,
  • "name": "Current configuration",
  • "createdAt": null,
  • "updatedAt": null,
  • "startDate": "2026-07-01T00:00:00+02:00",
  • "endDate": "2026-07-31T23:59:59+02:00",
  • "data": {
    • "totalOverview": {
      • "pricing": {
        • "tenantDiscountPercentage": 0,
        • "partnerDiscountPercentage": 12,
        • "vatPercentage": "7",
        • "outgoing": {
          • "baseFee": 2,
          • "adminPanelFee": 0,
          • "subtotal": 22050.42333,
          • "tenantDiscount": 0,
          • "partnerDiscount": 0,
          • "totalBeforeCreditsAndVat": 22052.42333,
          • "usedCredits": 0,
          • "totalBeforeVat": 22052.42333,
          • "vat": 0,
          • "finalTotal": 22052.42333
          },
        • "incoming": {
          • "baseFee": 152,
          • "subtotal": 13298.3439454,
          • "tenantDiscount": 302.332231781,
          • "total": 13148.011713619
          }
        },
      • "resources": { },
      • "devices": [ ],
      • "replications": [ ],
      • "networks": [ ],
      • "s3storage": [ ]
      },
    • "tenantsOverview": { }
    }
}

List Usage Reports By Tenant

Get a paginated list of usage reports for a specific tenant (or all tenants).

Authorizations:
service_token
path Parameters
tenantIdentifier
required
string

Tenant identifier (or "all" to get reports for all tenants)

query Parameters
page
integer
Default: 1

Page number. Defaults to 1 if omitted.

perPage
integer
Default: 5

Number of items per page. Defaults to 5 if omitted.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "id": 0,
      • "name": "string",
      • "createdAt": "2019-08-24T14:15:22Z",
      • "updatedAt": "2019-08-24T14:15:22Z",
      • "startDate": "2019-08-24",
      • "endDate": "2019-08-24"
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "from": 1,
    • "lastPage": 13,
    • "perPage": 5,
    • "to": 5,
    • "total": 64
    }
}

Get Usage Report

Get details of a specific usage report by ID.

Authorizations:
service_token
path Parameters
usageReportId
required
integer

Usage report ID

Responses

Response samples

Content type
application/json
{
  • "id": 18637,
  • "name": "June 1-16, 2026",
  • "createdAt": "2026-06-02T04:00:08+02:00",
  • "updatedAt": "2026-06-17T04:00:12+02:00",
  • "startDate": "2026-06-01 01:00:00",
  • "endDate": "2026-06-17 00:59:59",
  • "data": {
    • "totalOverview": {
      • "pricing": {
        • "tenantDiscountPercentage": 0,
        • "partnerDiscountPercentage": 12,
        • "vatPercentage": "7",
        • "outgoing": {
          • "baseFee": 2,
          • "adminPanelFee": 0,
          • "subtotal": 22050.42333,
          • "tenantDiscount": 0,
          • "partnerDiscount": 0,
          • "totalBeforeCreditsAndVat": 22052.42333,
          • "usedCredits": 0,
          • "totalBeforeVat": 22052.42333,
          • "vat": 0,
          • "finalTotal": 22052.42333
          },
        • "incoming": {
          • "baseFee": 152,
          • "subtotal": 13298.3439454,
          • "tenantDiscount": 302.332231781,
          • "total": 13148.011713619
          }
        },
      • "resources": {
        • "CPU": {
          • "onHours": 119103,
          • "offHours": 16656,
          • "totalHours": 135759,
          • "description": "119103 CPU Hours",
          • "pricing": {
            • "outgoing": {
              • "subtotal": 2382.06,
              • "tenantDiscount": 0,
              • "partnerDiscount": 0,
              • "baseFee": 0,
              • "total": 2382.06
              },
            • "incoming": {
              • "subtotal": 832.918,
              • "tenantDiscount": 16.17063,
              • "baseFee": 0,
              • "total": 816.74737
              }
            }
          }
        },
      • "devices": [
        • {
          • "cpuOn": "1440",
          • "ramOn": "1440",
          • "cpuOff": "0",
          • "ramOff": "0",
          • "storage": "5760",
          • "snapshot": "0.00",
          • "windowssrvlic": "0",
          • "firewall": "0",
          • "loadBalancer": "0",
          • "backupStorage": 0,
          • "hdd": "0",
          • "vmid": "da0d6eb17e4a",
          • "vmdisplayname": "dont-delete-PS-DEFAULT-VM9",
          • "tenantid": "2sn54783n",
          • "description": "1440 CPU Hours, 1440 RAM Hours, 5760 GB SSD Hours",
          • "pricing": {
            • "outgoing": {
              • "subtotal": 44.928,
              • "backupFee": 0
              },
            • "incoming": {
              • "subtotal": 0,
              • "backupFee": 0
              }
            }
          }
        ],
      • "replications": [ ],
      • "networks": [
        • {
          • "id": 268,
          • "type": "LAN",
          • "subnet": 24,
          • "access": 1,
          • "is_stretched": null,
          • "network_speed": 1000,
          • "hvType": 2,
          • "attached_at": "2024-08-13 15:23:36",
          • "detached_at": null,
          • "is_free": 0,
          • "tenant": "2sn54783n",
          • "displayname": "alexNetwork",
          • "hours_usage": 720,
          • "description": "alexNetwork (LAN /24, 720 Hours, 1000 Mbit)",
          • "pricing": {
            • "outgoing": {
              • "networkHourly": 0.01,
              • "networkUpgradeHourly": 0,
              • "subtotal": 7.2,
              • "networkSubtotal": 7.2,
              • "networkUpgradeSubtotal": 0,
              • "feePrice": 0
              },
            • "incoming": {
              • "networkHourly": 0,
              • "networkUpgradeHourly": 0,
              • "subtotal": 0,
              • "networkSubtotal": 0,
              • "networkUpgradeSubtotal": 0,
              • "feePrice": 0
              }
            }
          }
        ],
      • "s3storage": [
        • {
          • "name": "James",
          • "created_at": "2025-11-05T18:25:17+01:00",
          • "quota": 2000,
          • "zone_name": "ch1",
          • "tenantid": "2sn54783n",
          • "is_replicated": true,
          • "pricing": {
            • "outgoing": {
              • "feePrice": 160,
              • "subtotal": 160
              },
            • "incoming": {
              • "feePrice": 0,
              • "subtotal": 0
              }
            }
          }
        ]
      },
    • "tenantsOverview": {
      • "2sn54783n": {
        • "tenantid": "2sn54783n",
        • "tenantName": "Xelon AG",
        • "resources": { },
        • "devices": [ ],
        • "networks": [ ],
        • "replications": [ ],
        • "s3storage": [ ],
        • "description": "78244 CPU Hours, 131042 RAM Hours, ...",
        • "pricing": {
          • "outgoing": {
            • "subtotal": 7887.1555,
            • "tenantDiscount": 0,
            • "partnerDiscount": 0,
            • "baseFee": 2,
            • "adminPanelFee": 0,
            • "total": 7889.1555,
            • "tenantDiscountPercentage": 0
            },
          • "incoming": {
            • "subtotal": 0,
            • "tenantDiscount": 0,
            • "baseFee": 0,
            • "total": 0,
            • "tenantDiscountPercentage": 0
            }
          }
        }
      }
    }
}

Billing Plans

Billing Plans define pricing and resource billing configurations.

Get Billing Resources

Get all billing resource reference data including resource types, currencies, billing frequencies, and resource calculations.

Authorizations:
service_token

Responses

Response samples

Content type
application/json
{
  • "resources": [
    • {
      • "id": 1,
      • "name": "Computer Resources"
      },
    • {
      • "id": 2,
      • "name": "Network Resources"
      },
    • {
      • "id": 3,
      • "name": "Microsoft Licenses"
      },
    • {
      • "id": 4,
      • "name": "Network Upgrades"
      },
    • {
      • "id": 5,
      • "name": "Setup fees"
      },
    • {
      • "id": 6,
      • "name": "Monthly fees"
      }
    ],
  • "currencies": [
    • {
      • "id": 1,
      • "code": "CHF",
      • "created_at": null,
      • "updated_at": null
      },
    • {
      • "id": 2,
      • "code": "USD",
      • "created_at": null,
      • "updated_at": null
      },
    • {
      • "id": 3,
      • "code": "EUR",
      • "created_at": null,
      • "updated_at": null
      }
    ],
  • "billing_frequency": [
    • {
      • "id": 1,
      • "name": "Monthly",
      • "billing_type_id": 1,
      • "created_at": null,
      • "updated_at": null
      },
    • {
      • "id": 2,
      • "name": "Monthly",
      • "billing_type_id": 2,
      • "created_at": null,
      • "updated_at": null
      },
    • {
      • "id": 3,
      • "name": "Quarterly",
      • "billing_type_id": 2,
      • "created_at": null,
      • "updated_at": null
      },
    • {
      • "id": 4,
      • "name": "Semi-annually",
      • "billing_type_id": 2,
      • "created_at": null,
      • "updated_at": null
      },
    • {
      • "id": 5,
      • "name": "Annually",
      • "billing_type_id": 2,
      • "created_at": null,
      • "updated_at": null
      }
    ],
  • "resource_calculation": [
    • {
      • "id": 1,
      • "name": "Hourly",
      • "billing_type_id": 1,
      • "created_at": null,
      • "updated_at": null
      },
    • {
      • "id": 2,
      • "name": "Static",
      • "billing_type_id": 2,
      • "created_at": null,
      • "updated_at": null
      }
    ]
}

List Billing Plans

Get a list of billing plans for the current tenant.

Authorizations:
service_token

Responses

Response samples

Content type
application/json
[
  • {
    • "id": 1,
    • "name": "Standard Plan",
    • "type": "Post-Paid",
    • "creator": "Xelon AG",
    • "assignedTenants": [
      • "Acme Corp",
      • "Beta Inc"
      ]
    },
  • {
    • "id": 2,
    • "name": "Reseller Plan",
    • "type": "Post-Paid",
    • "creator": "Xelon AG",
    • "assignedTenants": [ ]
    }
]

Create Billing Plan

Create a new billing plan.

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

Request fields use camelCase (the v2-canonical style). The legacy snake_case names (e.g. currency_code) are still accepted for backwards compatibility.

name
required
string <= 255 characters

Billing plan name

type
required
integer

Billing type ID. Must reference an existing record. Obtain available values from GET /billing/resources.

currency
required
integer

Currency ID. Must reference an existing record. Obtain available values from GET /billing/resources (currencies[].id).

currencyCode
string or null

Currency code (e.g. CHF, EUR). Purely informational — not validated against currency.

minimumSpending
required
number <float> >= 0

Minimum monthly spending

resourceCalculation
required
integer

Resource calculation method ID. Must reference an existing record. Obtain available values from GET /billing/resources (resource_calculation[].id).

billingFrequency
required
integer

Billing frequency ID. Must reference an existing record. Obtain available values from GET /billing/resources (billing_frequency[].id).

required
object

Resource and fee pricing for the new plan, keyed by a fixed resource-group ID (as a string key, since JSON object keys are strings) from 1 to 6. Groups 1-4 are resource categories (see GET /billing/resources, resources[].id, filtered by category) and each item needs resourceId/price; group 1-4 items also need type, which must repeat that group's own key. Groups 5-6 are fee categories and each item needs resourceId (referencing GET /billing/resources fee catalog) and price. All six groups are required (even as an empty array) — omitting one causes a 422.

Responses

Request samples

Content type
application/json
{
  • "name": "Standard Plan",
  • "type": 1,
  • "currency": 1,
  • "currencyCode": "CHF",
  • "minimumSpending": 50,
  • "resourceCalculation": 1,
  • "billingFrequency": 1,
  • "resources": {
    • "1": [
      • {
        • "resourceId": 1,
        • "type": 1,
        • "price": 0.03
        }
      ],
    • "2": [
      • {
        • "resourceId": 2,
        • "type": 2,
        • "price": 0.01
        }
      ],
    • "3": [
      • {
        • "resourceId": 3,
        • "type": 3,
        • "price": 0.02
        }
      ],
    • "4": [
      • {
        • "resourceId": 4,
        • "type": 4,
        • "price": 0.05
        }
      ],
    • "5": [
      • {
        • "resourceId": 1,
        • "price": 30
        }
      ],
    • "6": [
      • {
        • "resourceId": 2,
        • "price": 7
        }
      ]
    }
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "name": "Standard Plan",
    • "type": 1,
    • "type_name": "Post-Paid",
    • "type_id": 1,
    • "currency": "1",
    • "currency_code": "CHF",
    • "minimum_spending": 50,
    • "resource_calculation": 1,
    • "resource_calculation_name": "Hourly",
    • "billing_frequency": 1,
    • "billing_frequency_name": "Monthly",
    • "resources": [
      • {
        • "id": 5,
        • "resource_id": 1,
        • "name": "Per CPU Core",
        • "slug": "cpu",
        • "type": 1,
        • "price": 0.03,
        • "month_price": "21.60",
        • "category": "resource"
        }
      ],
    • "fees": [
      • {
        • "id": 9882,
        • "resource_id": 1,
        • "name": "Base fee",
        • "slug": "base",
        • "type": "monthly",
        • "price": 30,
        • "category": "fee"
        }
      ]
    },
  • "message": "Billing Plan has been created."
}

Get Current Tenant Billing Plan

Get the billing plan assigned to the current user's tenant.

Unlike GET /billing/plans/{planId}, this endpoint always returns resources and fees (never the defaultResources/defaultFees catalog fallback), even if they are empty arrays.

Authorizations:
service_token

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Xelon Post Paid",
  • "type": 1,
  • "type_name": "Post-Paid",
  • "type_id": 1,
  • "currency": "1",
  • "currency_code": "CHF",
  • "minimum_spending": 0,
  • "resource_calculation": 1,
  • "resource_calculation_name": "Hourly",
  • "billing_frequency": 1,
  • "billing_frequency_name": "Monthly",
  • "resources": [
    • {
      • "id": 5,
      • "resource_id": 5,
      • "name": "Per CPU Core",
      • "slug": "cpu",
      • "type": 1,
      • "price": 0.02,
      • "month_price": "14.40",
      • "category": "resource"
      },
    • {
      • "id": 6,
      • "resource_id": 6,
      • "name": "Per GB RAM",
      • "slug": "ram",
      • "type": 1,
      • "price": 0.01,
      • "month_price": "7.20",
      • "category": "resource"
      }
    ],
  • "fees": [
    • {
      • "id": 9882,
      • "resource_id": 14,
      • "name": "Base fee",
      • "slug": "base",
      • "type": "monthly",
      • "price": 2,
      • "category": "fee"
      },
    • {
      • "id": 5335,
      • "resource_id": 8,
      • "name": "Per /29 Dedicated WAN",
      • "slug": "dedicated_29_wan",
      • "type": "setup",
      • "price": 0,
      • "category": "fee"
      }
    ]
}

List Children Billing Plans

Get a list of billing plans created by child tenants of the current user.

Authorizations:
service_token

Responses

Response samples

Content type
application/json
[
  • {
    • "id": 1,
    • "name": "Standard Plan",
    • "type": "Post-Paid",
    • "creator": "Xelon AG",
    • "assignedTenants": [
      • "Acme Corp",
      • "Beta Inc"
      ]
    },
  • {
    • "id": 2,
    • "name": "Reseller Plan",
    • "type": "Post-Paid",
    • "creator": "Xelon AG",
    • "assignedTenants": [ ]
    }
]

Get Replication Billing Data

Get replication billing data (base fee and RTO multipliers) for the current user.

Authorizations:
service_token

Responses

Response samples

Content type
application/json
{
  • "baseFee": 25,
  • "rtoMultipliers": [
    • {
      • "rto": 1,
      • "multiplier": 2.5
      },
    • {
      • "rto": 4,
      • "multiplier": 1.5
      },
    • {
      • "rto": 24,
      • "multiplier": 1
      }
    ]
}

Get Billing Plan

Get details of a specific billing plan including resources and fees.

Authorizations:
service_token
path Parameters
planId
required
integer

Billing plan ID

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Xelon Post Paid",
  • "type": 1,
  • "type_name": "Post-Paid",
  • "type_id": 1,
  • "currency": "1",
  • "currency_code": "CHF",
  • "minimum_spending": 0,
  • "resource_calculation": 1,
  • "resource_calculation_name": "Hourly",
  • "billing_frequency": 1,
  • "billing_frequency_name": "Monthly",
  • "resources": [
    • {
      • "id": 5,
      • "resource_id": 5,
      • "name": "Per CPU Core",
      • "slug": "cpu",
      • "type": 1,
      • "price": 0.02,
      • "month_price": "14.40",
      • "category": "resource"
      },
    • {
      • "id": 6,
      • "resource_id": 6,
      • "name": "Per GB RAM",
      • "slug": "ram",
      • "type": 1,
      • "price": 0.01,
      • "month_price": "7.20",
      • "category": "resource"
      }
    ],
  • "fees": [
    • {
      • "id": 9882,
      • "resource_id": 14,
      • "name": "Base fee",
      • "slug": "base",
      • "type": "monthly",
      • "price": 2,
      • "category": "fee"
      },
    • {
      • "id": 5335,
      • "resource_id": 8,
      • "name": "Per /29 Dedicated WAN",
      • "slug": "dedicated_29_wan",
      • "type": "setup",
      • "price": 0,
      • "category": "fee"
      }
    ]
}

Update Billing Plan

Update an existing billing plan.

Authorizations:
service_token
path Parameters
planId
required
integer

Billing plan ID

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

Request fields use camelCase (the v2-canonical style). The legacy snake_case names (e.g. currency_code) are still accepted for backwards compatibility.

Only name, type, currency, minimumSpending, resourceCalculation, and billingFrequency are actually persisted. currencyCode and resources are accepted but silently ignored — the update does not read them. This means type must hold the billing type ID (not a name), and currency must hold the currency ID (see GET /billing/resources), even though their field names don't say "Id". To change a plan's resources, use its own endpoints rather than this field.

name
required
string <= 255 characters

Billing plan name

type
required
integer

Billing type ID (despite the field name, this is what actually gets written to the plan's type_id column — see note above). Must reference an existing record. Obtain available values from GET /billing/resources.

currency
required
integer

Currency ID (despite the field name, this is what actually gets written to the plan's currency_id column — see note above). Must reference an existing record. Obtain available values from GET /billing/resources (currencies[].id).

currencyCode
string or null

Accepted, but not persisted — has no effect on update.

minimumSpending
required
number <float> >= 0

Minimum monthly spending

resourceCalculation
required
integer

Resource calculation method ID. Must reference an existing record. Obtain available values from GET /billing/resources (resource_calculation[].id).

billingFrequency
required
integer

Billing frequency ID. Must reference an existing record. Obtain available values from GET /billing/resources (billing_frequency[].id).

resources
Array of arrays or null or null

Accepted, but not persisted — has no effect on update.

Responses

Request samples

Content type
application/json
{
  • "name": "Updated Plan",
  • "type": 1,
  • "currency": 1,
  • "minimumSpending": 100,
  • "resourceCalculation": 1,
  • "billingFrequency": 1
}

Response samples

Content type
application/json
{
  • "data": {
    • "id": 1,
    • "name": "Standard Plan",
    • "type": 1,
    • "type_name": "Post-Paid",
    • "type_id": 1,
    • "currency": "1",
    • "currency_code": "CHF",
    • "minimum_spending": 100,
    • "resource_calculation": 1,
    • "resource_calculation_name": "Per Unit",
    • "billing_frequency": 1,
    • "billing_frequency_name": "Monthly",
    • "resources": [
      • {
        • "id": 5,
        • "resource_id": 1,
        • "name": "Per CPU Core",
        • "slug": "cpu",
        • "type": 1,
        • "price": 0.03,
        • "month_price": "21.60",
        • "category": "resource"
        }
      ],
    • "fees": [
      • {
        • "id": 9882,
        • "resource_id": 1,
        • "name": "Base fee",
        • "slug": "base",
        • "type": "monthly",
        • "price": 30,
        • "category": "fee"
        }
      ]
    },
  • "message": "Billing Plan has been updated."
}

Delete Billing Plan

Delete a billing plan (fails if assigned to any tenant).

Authorizations:
service_token
path Parameters
planId
required
integer

Billing plan ID

Responses

Response samples

Content type
application/json
{
  • "message": "Success"
}

Get Tenant Billing Plan

Get the billing plan assigned to a specific tenant.

Unlike GET /billing/plans/{planId}, this endpoint always returns resources and fees (never the defaultResources/defaultFees catalog fallback), even if they are empty arrays.

Authorizations:
service_token
path Parameters
tenant_identifier
required
string

Tenant identifier

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "Xelon Post Paid",
  • "type": 1,
  • "type_name": "Post-Paid",
  • "type_id": 1,
  • "currency": "1",
  • "currency_code": "CHF",
  • "minimum_spending": 0,
  • "resource_calculation": 1,
  • "resource_calculation_name": "Hourly",
  • "billing_frequency": 1,
  • "billing_frequency_name": "Monthly",
  • "resources": [
    • {
      • "id": 5,
      • "resource_id": 5,
      • "name": "Per CPU Core",
      • "slug": "cpu",
      • "type": 1,
      • "price": 0.02,
      • "month_price": "14.40",
      • "category": "resource"
      },
    • {
      • "id": 6,
      • "resource_id": 6,
      • "name": "Per GB RAM",
      • "slug": "ram",
      • "type": 1,
      • "price": 0.01,
      • "month_price": "7.20",
      • "category": "resource"
      }
    ],
  • "fees": [
    • {
      • "id": 9882,
      • "resource_id": 14,
      • "name": "Base fee",
      • "slug": "base",
      • "type": "monthly",
      • "price": 2,
      • "category": "fee"
      },
    • {
      • "id": 5335,
      • "resource_id": 8,
      • "name": "Per /29 Dedicated WAN",
      • "slug": "dedicated_29_wan",
      • "type": "setup",
      • "price": 0,
      • "category": "fee"
      }
    ]
}

Notifications

Notifications keep users informed about important events and changes.

List Notifications

Get a list of notifications for the authenticated user.

Authorizations:
service_token

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "type": "string",
    • "notifiable_type": "string",
    • "notifiable_id": 0,
    • "data": { },
    • "read_at": "2019-08-24T14:15:22Z",
    • "created_at": "2019-08-24T14:15:22Z",
    • "updated_at": "2019-08-24T14:15:22Z"
    }
]

Mark Notification As Read

Mark a specific notification as read.

Authorizations:
service_token
path Parameters
notificationId
required
string

Notification UUID

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Object Storage

Object Storage provides S3-compatible storage for your data. Manage users, access tokens, buckets, versioning, and IP restrictions.

List Current Object Storage Plans

Get a list of the authenticated user's active object storage plans with usage statistics.

Authorizations:
service_token

Responses

Response samples

Content type
application/json
[
  • {
    • "id": 42,
    • "name": "my-s3-user",
    • "createdAt": "2024-06-01T12:00:00+00:00",
    • "quota": 500,
    • "isReplicated": false,
    • "title": "500 GB",
    • "description": "Standard object storage plan with 500 GB of storage.",
    • "price": 9.9,
    • "bucketsCount": 3,
    • "sizeUsedGb": 12.34,
    • "numberOfObjects": 1024
    }
]

List Available Object Storage Plans

Get a list of all available object storage plans with pricing information.

Authorizations:
service_token

Responses

Response samples

Content type
application/json
[
  • {
    • "quota": 500,
    • "title": "500 GB",
    • "price": 9.9,
    • "priceReplicated": 18.9,
    • "description": "Standard object storage plan with 500 GB of storage."
    }
]

List Zone Groups

Get a list of available zone groups for object storage deployment.

Authorizations:
service_token

Responses

Response samples

Content type
application/json
[
  • {
    • "id": "ch1",
    • "name": "Aargau",
    • "hasReplication": false
    }
]

List S3 Users

Get a paginated list of S3 users with their access tokens.

Authorizations:
service_token
query Parameters
tenantId
string
Example: tenantId=abc123

Filter results by tenant identifier.

page
integer
Example: page=1

The page number to retrieve.

perPage
integer
Example: perPage=5

Number of items to return per page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
      • "name": "my-s3-user",
      • "quota": 500,
      • "tenant": {
        • "identifier": "abc123",
        • "name": "acme-corp"
        },
      • "s3endpoints": [],
      • "isReplicated": false,
      • "createdAt": "2024-06-01T12:00:00+00:00",
      • "sizeUsedGb": 12.34,
      • "numObjects": 1024,
      • "tokens": [
        • {
          • "identifier": "a1b2c3d4e5f6",
          • "accessKey": "AKIAIOSFODNN7EXAMPLE",
          • "createdAt": "2024-06-01T12:00:00+00:00"
          }
        ]
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "from": 1,
    • "lastPage": 13,
    • "perPage": 5,
    • "to": 5,
    • "total": 64
    }
}

Create S3 User

Create a new S3 user with the specified storage quota and zone group.

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
required
string <= 255 characters

The name of the S3 user.

quota
required
integer
Enum: 100 250 500 1000 2000

Storage quota in GB. Allowed values are 100, 250, 500, 1000, 2000.

zoneGroup
required
string

The zone group API name where the user should be created (e.g. ch1, zh1).

tenantId
string

Identifier of the tenant to create the user under. Defaults to the authenticated user's tenant.

Responses

Request samples

Content type
application/json
{
  • "name": "my-s3-user",
  • "quota": 500,
  • "zoneGroup": "ch1",
  • "tenantId": "abc123"
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
    • "name": "my-s3-user",
    • "createdAt": "2024-06-01T12:00:00+00:00",
    • "tokens": [
      • {
        • "identifier": "a1b2c3d4e5f6",
        • "accessKey": "AKIAIOSFODNN7EXAMPLE",
        • "secretKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
        • "createdAt": "2024-06-01T12:00:00+00:00"
        }
      ]
    },
  • "message": "S3 user successfully created"
}

Get S3 User

Get a single S3 user with its access tokens and current usage statistics.

Authorizations:
service_token
path Parameters
s3UserIdentifier
required
string
Example: b1a2c3d4-e5f6-7890-abcd-ef1234567890

The identifier (UUID) of the S3 user.

Responses

Response samples

Content type
application/json
{
  • "identifier": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
  • "name": "my-s3-user",
  • "quota": 500,
  • "tenant": {
    • "identifier": "abc123",
    • "name": "acme-corp"
    },
  • "s3endpoints": [],
  • "isReplicated": false,
  • "createdAt": "2024-06-01T12:00:00+00:00",
  • "sizeUsedGb": 12.34,
  • "numObjects": 1024,
  • "tokens": [
    • {
      • "identifier": "a1b2c3d4e5f6",
      • "accessKey": "AKIAIOSFODNN7EXAMPLE",
      • "createdAt": "2024-06-01T12:00:00+00:00"
      }
    ]
}

Edit S3 User

Update the name and storage quota of an existing S3 user.

Authorizations:
service_token
path Parameters
s3UserIdentifier
required
string
Example: b1a2c3d4-e5f6-7890-abcd-ef1234567890

The identifier (UUID) of the S3 user.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
required
string <= 255 characters

The new name for the S3 user.

quota
required
integer
Enum: 100 250 500 1000 2000

New storage quota in GB. Allowed values are 100, 250, 500, 1000, 2000.

Responses

Request samples

Content type
application/json
{
  • "name": "updated-s3-user",
  • "quota": 1000
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
    • "name": "my-s3-user",
    • "createdAt": "2024-06-01T12:00:00+00:00"
    },
  • "message": "S3 user successfully edited"
}

Delete S3 User

Delete an S3 user and all associated resources. The user cannot be deleted if it still has buckets — all buckets must be deleted first.

Authorizations:
service_token
path Parameters
s3UserIdentifier
required
string
Example: b1a2c3d4-e5f6-7890-abcd-ef1234567890

The identifier (UUID) of the S3 user.

Responses

Response samples

Content type
application/json
{
  • "message": "S3 User successfully deleted"
}

Create S3 User Token

Create a new access token for an S3 user. The secret key is only returned once upon creation — store it securely.

Authorizations:
service_token
path Parameters
s3UserIdentifier
required
string
Example: b1a2c3d4-e5f6-7890-abcd-ef1234567890

The identifier (UUID) of the S3 user.

Responses

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "a1b2c3d4e5f6",
    • "accessKey": "AKIAIOSFODNN7EXAMPLE",
    • "secretKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    • "createdAt": "2024-06-01T12:00:00+00:00"
    },
  • "message": "S3 user token successfully created"
}

Delete S3 User Token

Delete an S3 access key for an S3 user.

Note: An S3 user must always retain at least one access key. Deleting the last access key is not permitted, as users without access keys cannot perform any S3 operations, including bucket creation.

Authorizations:
service_token
path Parameters
s3UserIdentifier
required
string
Example: b1a2c3d4-e5f6-7890-abcd-ef1234567890

The identifier (UUID) of the S3 user.

tokenIdentifier
required
string
Example: a1b2c3d4e5f6

The stable identifier of the S3 access token.

Responses

Response samples

Content type
application/json
{
  • "message": "Token successfully deleted"
}

List Buckets

Get a list of all buckets belonging to the authenticated user's tenant. Admins can filter by a specific tenant using the tenantId query parameter.

Authorizations:
service_token
query Parameters
tenantId
string
Example: tenantId=abc123

Filter results by tenant identifier.

page
integer
Example: page=1

The page number to retrieve.

perPage
integer
Example: perPage=5

Number of items to return per page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "zone1.4711.1",
      • "name": "my-bucket",
      • "createdAt": "2024-06-01T12:00:00+00:00",
      • "zoneGroup": "Aargau",
      • "isReplicated": false,
      • "s3UserName": "my-s3-user",
      • "s3UserIdentifier": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
      • "tenant": {
        • "identifier": "abc123",
        • "name": "acme-corp"
        },
      • "isObjectLock": false,
      • "isVersioning": true,
      • "s3endpoints": [],
      • "isWithRestrictedIps": false
      }
    ],
  • "meta": {
    • "currentPage": 1,
    • "from": 1,
    • "lastPage": 13,
    • "perPage": 5,
    • "to": 5,
    • "total": 64
    }
}

Create Bucket

Create a new S3 bucket. The bucket is created asynchronously.

isObjectLock / isVersioning / retentionPeriodDays

Object Lock Versioning Retention Days Result
true true 1–36500 Bucket created with Object Lock in COMPLIANCE mode and the given retention period.
true false any 422 — Object Lock requires isVersioning: true.
true true or false omitted / null 422 — retentionPeriodDays is required when isObjectLock is true.
false true omitted Bucket created without Object Lock; versioning is enabled asynchronously.
false false omitted Bucket created without Object Lock or versioning.
false true or false set Accepted, but ignored — retention only applies when isObjectLock is true.

Object Lock cannot be changed after creation. Versioning can be toggled later via Change Bucket Versioning, subject to the same Object Lock constraint (see that endpoint).

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
required
string <= 255 characters

The name of the bucket. Must be 3–63 characters, lowercase letters, numbers and hyphens only. Cannot start with xn--, end with -s3alias, or be formatted as an IP address.

s3UserIdentifier
required
string <uuid>

The UUID identifier of the S3 user that will own this bucket.

isObjectLock
required
boolean

Whether to enable Object Lock on the bucket. Object Lock prevents objects from being deleted or overwritten. When isObjectLock is true, isVersioning must also be true.

isVersioning
required
boolean

Whether to enable versioning on the bucket. Required to be true when isObjectLock is true.

retentionPeriodDays
integer [ 1 .. 36500 ]

Retention period in days for Object Lock. Required when isObjectLock is true; not applicable otherwise.

Responses

Request samples

Content type
application/json
{
  • "name": "my-bucket",
  • "s3UserIdentifier": "550e8400-e29b-41d4-a716-446655440000",
  • "isObjectLock": false,
  • "isVersioning": true,
  • "retentionPeriodDays": 30
}

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "zone1.4711.1",
    • "name": "my-bucket",
    • "createdAt": "2024-06-01T12:00:00+00:00",
    • "zoneGroup": "Aargau",
    • "isReplicated": false,
    • "s3UserName": "my-s3-user",
    • "s3UserIdentifier": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
    • "tenant": {
      • "identifier": "abc123",
      • "name": "acme-corp"
      },
    • "isObjectLock": false,
    • "isVersioning": true,
    • "retentionPeriodDays": 30,
    • "s3endpoints": [],
    • "isWithRestrictedIps": false
    },
  • "message": "Bucket successfully created"
}

Get Bucket

Get a single bucket belonging to the authenticated user's tenant.

Authorizations:
service_token
path Parameters
bucketName
required
string
Example: my-bucket

The name of the bucket.

s3UserIdentifier
required
string
Example: b1a2c3d4-e5f6-7890-abcd-ef1234567890

The identifier (UUID) of the S3 user.

Responses

Response samples

Content type
application/json
{
  • "data": {
    • "identifier": "zone1.4711.1",
    • "name": "my-bucket",
    • "createdAt": "2024-06-01T12:00:00+00:00",
    • "zoneGroup": "Aargau",
    • "isReplicated": false,
    • "s3UserName": "my-s3-user",
    • "s3UserIdentifier": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
    • "tenant": {
      • "identifier": "abc123",
      • "name": "acme-corp"
      },
    • "isObjectLock": false,
    • "isVersioning": true,
    • "retentionPeriodDays": 30,
    • "s3endpoints": [],
    • "isWithRestrictedIps": false
    }
}

Delete Bucket

Delete a bucket and all its contents.

Authorizations:
service_token
path Parameters
bucketName
required
string
Example: my-bucket

The name of the bucket.

s3UserIdentifier
required
string
Example: b1a2c3d4-e5f6-7890-abcd-ef1234567890

The identifier (UUID) of the S3 user.

Responses

Response samples

Content type
application/json
{
  • "message": "Bucket successfully deleted"
}

Change Bucket Versioning

Enable or disable versioning for a bucket.

Existing Object Lock Requested versioning Result
enabled true No-op success — already enabled per the S3 spec on Object Lock buckets.
enabled false 422 — versioning cannot be disabled on a bucket with Object Lock enabled.
disabled true Versioning set to Enabled.
disabled false Versioning set to Suspended (S3 has no true "off" once versioning was ever enabled).
Authorizations:
service_token
path Parameters
bucketName
required
string
Example: my-bucket

The name of the bucket.

s3UserIdentifier
required
string
Example: b1a2c3d4-e5f6-7890-abcd-ef1234567890

The identifier (UUID) of the S3 user.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

isVersioning
required
boolean

Whether to enable (true) or disable (false) versioning on the bucket.

Responses

Request samples

Content type
application/json
{
  • "isVersioning": true
}

Response samples

Content type
application/json
{
  • "message": "Bucket versioning has been enabled"
}

Get Bucket IP Restrictions

Get the current IP restriction settings for a bucket.

Authorizations:
service_token
path Parameters
bucketName
required
string
Example: my-bucket

The name of the bucket.

s3UserIdentifier
required
string
Example: b1a2c3d4-e5f6-7890-abcd-ef1234567890

The identifier (UUID) of the S3 user.

Responses

Response samples

Content type
application/json
{
  • "data": {
    • "allowedIps": [
      • "192.168.1.0/24"
      ],
    • "enabled": true
    }
}

Update Bucket IP Restrictions

Update the IP restriction settings for a bucket. The update is processed asynchronously. When enabled, only requests from the specified IPs or CIDR ranges will be allowed.

Authorizations:
service_token
path Parameters
bucketName
required
string
Example: my-bucket

The name of the bucket.

s3UserIdentifier
required
string
Example: b1a2c3d4-e5f6-7890-abcd-ef1234567890

The identifier (UUID) of the S3 user.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

enabled
required
boolean

Whether to activate IP restrictions for this bucket.

allowedIps
Array of strings

List of allowed IP addresses or CIDR ranges. Required when enabled is true. At least one entry must be provided when restrictions are enabled.

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "allowedIps": [
    • "192.168.1.0/24",
    • "10.0.0.1"
    ]
}

Response samples

Content type
application/json
{
  • "message": "IP restrictions will updated soon"
}

Create File Manager Session

Creates a temporary session token that grants the File Manager access to the specified S3 user's storage.

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

s3UserIdentifier
required
string <uuid>

The UUID identifier of the S3 user whose storage the File Manager will access.

s3Endpoint
string or null <uri>

Optional custom S3-compatible endpoint URL. When omitted, the zone's default endpoint is used.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Snapshots

Get List of Device Snapshots

Get List of Device Snapshots.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "snapshot-42",
      • "name": "my-snapshot",
      • "description": "Snapshot description",
      • "createdAt": "19-03-2024 17:24:26"
      }
    ]
}

Create Device Snapshot

Create Device Snapshot.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
required
string <= 80 characters

The name of the device snapshot.

description
string <= 240 characters

The description of the device snapshot.

Responses

Request samples

Content type
application/json
{
  • "name": "my-snapshot",
  • "description": "Snapshot description"
}

Response samples

Content type
application/json
{
  • "message": "Snapshot created successfully."
}

Get Device Snapshot

Get Device Snapshot.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

snapshot_identifier
required
string
Example: snapshot-42

A unique identifier for a Device Snapshot.

Responses

Response samples

Content type
application/json
{
  • "identifier": "snapshot-42",
  • "name": "my-snapshot",
  • "description": "Snapshot description",
  • "createdAt": "19-03-2024 17:24:26"
}

Update Device Snapshot

Update Device Snapshot metadata (name and description).

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

snapshot_identifier
required
string
Example: snapshot-42

A unique identifier for a Device Snapshot.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

name
required
string <= 80 characters

The name of the device snapshot.

description
string <= 240 characters

The description of the device snapshot.

Responses

Request samples

Content type
application/json
{
  • "name": "my-snapshot",
  • "description": "Snapshot description"
}

Response samples

Content type
application/json
{
  • "message": "Snapshot successfully updated."
}

Delete Device Snapshot

Delete Device Snapshot.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

snapshot_identifier
required
string
Example: snapshot-42

A unique identifier for a Device Snapshot.

Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

removeChildren
required
boolean

Whether to delete all child snapshots.

Responses

Request samples

Content type
application/json
{
  • "removeChildren": false
}

Response samples

Content type
application/json
{
  • "message": "Snapshot is being deleted."
}

Revert Device Snapshot

Revert Device Snapshot.

Authorizations:
service_token
path Parameters
device_identifier
required
string
Example: abc123abc456

A unique identifier for a Device.

snapshot_identifier
required
string
Example: snapshot-42

A unique identifier for a Device Snapshot.

Responses

Response samples

Content type
application/json
{
  • "message": "Snapshot is being restored."
}

Disaster Recovery

List Replicated Virtual Machines

Returns all replicated virtual machines available in the resource pool of the specified Cloud Connect cloud. Each VM includes its power state, network interface cards, and — if already imported into Xelon — the device identifier and import date.

This endpoint queries the vCenter API for live data.

Authorizations:
service_token
query Parameters
cloudIdentifier
required
string
Example: cloudIdentifier=abc123abc456

A unique identifier for a Cloud.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "remoteId": "vm-1234",
      • "name": "replica-web-01",
      • "powerState": "poweredOn",
      • "networkInterfaces": [
        • {
          • "key": 4000,
          • "macAddress": "00:50:56:ab:cd:ef",
          • "label": "Network adapter 1"
          }
        ],
      • "hvSystem": {
        • "identifier": "abc123abc456",
        • "name": "Zurich CC"
        },
      • "tenant": {
        • "identifier": "t1e2n3a4n5t6",
        • "name": "Acme Corp"
        },
      • "deviceIdentifier": "d1e2v3i4c5e6",
      • "createdAt": "2024-03-15T10:30:00Z"
      }
    ]
}

List Available Destination Tenants

Returns the tenants available as import destinations for virtual machines replicated on the specified cloud. The list includes the cloud's owning tenant and all its active child tenants that have the cloud assigned.

Authorizations:
service_token
query Parameters
cloudIdentifier
required
string
Example: cloudIdentifier=abc123abc456

A unique identifier for a Cloud.

Responses

Response samples

Content type
application/json
{
  • "data": [
    • {
      • "identifier": "t1e2n3a4n5t6",
      • "name": "Acme Corp"
      }
    ]
}

Import Replicated Virtual Machines

Imports one or more replicated virtual machines from a Cloud Connect resource pool into Xelon as managed devices. For each virtual machine the network interface cards are reconfigured to connect to the specified Xelon networks.

Virtual machines that have already been imported are silently skipped.

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

required
Array of objects non-empty

The list of replicated virtual machines to import into Xelon.

Responses

Request samples

Content type
application/json
{
  • "virtualMachines": [
    • {
      • "remoteId": "vm-1234",
      • "tenantIdentifier": "t1e2n3a4n5t6",
      • "cloudIdentifier": "abc123abc456",
      • "displayName": "replica-web-01",
      • "networkInterfaces": [
        • {
          • "networkIdentifier": "n1e2t3w4o5r6",
          • "key": 4000,
          • "macAddress": "00:50:56:ab:cd:ef"
          }
        ]
      }
    ]
}

Response samples

Content type
application/json
{
  • "message": "Virtual machines successfully imported."
}

Define Resource Pool for Tenant

Assigns a vCenter resource pool on the specified cloud to a tenant, enabling that tenant to use Disaster Recovery as a Service (DRaaS) via Cloud Connect / Veeam replication. Once defined, replicated virtual machines in that resource pool will appear for the tenant in the virtual machines list.

Authorizations:
service_token
Request Body schema: application/json

Include a JSON object in the request body with a content type of application/json.

tenantIdentifier
required
string

The unique identifier of the tenant to assign the resource pool to.

cloudIdentifier
required
string

The unique identifier of the cloud (hypervisor system) that contains the resource pool.

resourcePool
required
string [ 3 .. 50 ] characters

The vCenter resource pool ID (ManagedObjectReference value) to assign for disaster recovery.

folderName
string or null [ 1 .. 50 ] characters

An optional vCenter folder name associated with the resource pool.

Responses

Request samples

Content type
application/json
{
  • "tenantIdentifier": "t1e2n3a4n5t6",
  • "cloudIdentifier": "abc123abc456",
  • "resourcePool": "resgroup-42",
  • "folderName": "DRaaS-Folder"
}

Response samples

Content type
application/json
{
  • "message": "Resource pool successfully defined."
}
1.3.1