Schemas

AddUsersResponse

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

ResponseError[]

A list of errors which may have occurred during the request.

object

The response data for this request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 46

AddUsersResponseData

DataResult[]

The status of the operation for each user in the request.

AttachVolumeByUUIDRequestBody

object · required

UUID or name of the instance to attach the volume to.

at

string · regex · pattern: ^/(?!.*\.\./|.*\.$|.… · required

Path of the mountpoint.

The path must be absolute, not contain . and .. components, and not contain colons (:). The path must point to an empty directory. If the directory does not exist, it is created.

Example: /mnt/my-volume

readonly

boolean

Whether the volume should be mounted read-only.

Example: false

AttachVolumesRequestItem

A single request item for attaching a volume to an instance.

object · required

UUID or name of the instance to attach the volume to.

at

string · regex · pattern: ^/(?!.*\.\./|.*\.$|.… · required

Path of the mountpoint.

The path must be absolute, not contain . and .. components, and not contain colons (:). The path must point to an empty directory. If the directory does not exist, it is created.

Example: /mnt/my-volume

readonly

boolean

Whether the volume should be mounted read-only.

Example: false

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: uuid
	type = object · requires: name

Properties for uuid:

uuid

string · uuid · required

The UUID of the volume to attach. Mutually exclusive with name. Exactly one of uuid or name must be provided.

Example: c1d2e3f4-5678-90ab-cdef-1234567890ab

AttachVolumesResponse

The response message for attaching one or more volume(s) given their UUID(s) or name(s).

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 46

AttachVolumesResponseAttachedVolume

status

string · enum · enum

The status of the response.

Enum values:

success

error

uuid

string · uuid

The UUID of the volume that was attached.

Example: c1d2e3f4-5678-90ab-cdef-1234567890ab

name

string

The name of the volume that was attached.

Example: funky-vol-g7gum5cj

metro

string

(Only applies when using global control plane). The metro of the volume.

Example: fra

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No volume with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

AttachVolumesResponseData

AttachVolumesResponseAttachedVolume[]

The volume(s) which were attached by the request.

AutoscalePolicy

AutoscalePolicy defines the autoscale policy for a service. Right now it contains fields from both the `ondemand` and `step` policies. They are marked both as optional, so only one of them should be set at a time. This is a current limitation of the API design.

name

string

The name of the policy.

Example: funky-policy

metro

string

(Only applies when using global control plane). The metro of the service group the policy applies to.

Example: fra

enabled

boolean

If the policy is enabled.

Example: true

metric

string · enum · enum

Metric to use for the step policy.

Enum values:

cpu

adjustment_type

string · enum · enum

The type of adjustment to be made in the step policy.

Enum values:

change

exact

percentage

AutoscalePolicyStep[]

The steps for the step policy. Each step defines an adjustment value and optional bounds.

AutoscalePolicyStep

adjustment

integer · int64

The adjustment value for the step.

Example: 50

lower_bound

integer · int64

Lower bound for the step.

Example: 10

upper_bound

integer · int64

Upper bound for the step.

Example: 500

BodyInstanceID

Reference to the instance to detach the volume from.

uuid

string · uuid

The UUID of the instance that the volume is detached from.

Example: c1d2e3f4-5678-90ab-cdef-1234567890ab

name

string

The name of the instance that the volume is detached from.

Example: funky-town-g7gum5cj

Certificate

uuid

string · uuid

The UUID of the certificate.

This is a unique identifier for the certificate that is generated when the certificate is created. The UUID is used to reference the certificate in API calls and can be used to identify the certificate in all API calls that require an identifier.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the certificate.

This is a human-readable name that can be used to identify the certificate. The name must be unique within the context of your account. The name can also be used to identify the certificate in API calls.

Example: funky-certificate

metro

string

(Only applies when using global control plane). Where the certificate is located.

Example: fra

created_at

string · date-time

The time the certificate was created.

Example: 2023-10-01T12:00:00Z

common_name

string

The common name (CN) field from the certificate's subject.

This is typically the primary domain name that the certificate is issued for. It represents the main identity that the certificate validates.

Example: my-common-name

subject

string

The complete subject distinguished name (DN) of the certificate.

This contains the full subject information from the certificate, including the common name, organization, organizational unit, locality, state, and country. The subject identifies the entity that the certificate is issued to.

Example: example.com

issuer

string

The complete issuer distinguished name (DN) of the certificate.

This identifies the Certificate Authority (CA) that issued the certificate. It contains information about the CA including its common name, organization, and country.

Example: CN=R10,O=Let's Encrypt,C=US

serial_number

string

The unique serial number assigned to the certificate by the issuing CA.

This is a unique identifier within the scope of the issuing CA that can be used to identify and track the certificate. Serial numbers are typically represented as hexadecimal strings.

Example: 123456789ABCDEF123456789ABCDEF123456

not_before

string · date-time

The date and time when the certificate becomes valid.

The certificate should not be trusted before this date. This timestamp marks the beginning of the certificate's validity period.

Example: 2023-10-01T12:00:00Z

not_after

string · date-time

The date and time when the certificate expires.

The certificate should not be trusted after this date. This timestamp marks the end of the certificate's validity period. Certificates should be renewed before this date to maintain service availability.

Example: 2023-10-01T12:00:00Z

state

string · enum · enum

The current state of the certificate.

This indicates whether the certificate is pending issuance, valid and ready for use, or in an error state. See CertificateState enum for detailed state descriptions.

Enum values:

pending

valid

error

status

string · enum · enum

An optional field representing the status of the request. This field is only set when this message object is used as a response message.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is only set when this message object is used as a response message, and is useful when the status is not success.

Example: No certificate with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is only set when this message object is used as a response message, and is useful when the status is not success.

Example: 8

CloneVolumeByUUIDRequestBody

vol_name

string

The name of the new cloned volume. If not provided, a random name of the form vol-X is generated for you, where X is a 5 character long random alphanumeric suffix.

Example: funky-vol-t7qumh5j

quota_policy

string · enum · enum

The quota policy for the new cloned volume. If not provided, the quota policy of the source volume is used.

Enum values:

static

dynamic

Example: static

tags

string[]

A list of tags to assign to the new cloned volume.

CloneVolumesRequestItem

A single request item describing the volume to clone.

vol_name

string

The name of the new cloned volume. If not provided, a random name of the form vol-X is generated for you, where X is a 5 character long random alphanumeric suffix.

Example: funky-vol-t7qumh5j

quota_policy

string · enum · enum

The quota policy for the new cloned volume. If not provided, the quota policy of the source volume is used.

Enum values:

static

dynamic

Example: static

tags

string[]

A list of tags to assign to the new cloned volume.

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for uuid:

uuid

string · uuid

The UUID of the volume to clone. Mutually exclusive with name.

Example: c1d2e3f4-5678-90ab-cdef-1234567890ab

CloneVolumesResponse

The response message for cloning one or more volume(s).

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 46

CloneVolumesResponseData

CloneVolumesResponseVolume[]

The volume(s) which were cloned by the request.

CloneVolumesResponseVolume

status

string · enum · enum

The status of the response.

Enum values:

success

error

uuid

string · uuid

The UUID of the newly cloned volume.

Example: c1d2e3f4-5678-90ab-cdef-1234567890ab

name

string

The name of the newly cloned volume.

Example: funky-vol-g7gum5cj

metro

string

(Only applies when using global control plane). The metro of the volume.

Example: fra

state

string · enum · enum

The state of the volume.

Enum values:

uninitialized

initializing

available

idle

mounted

busy

error

template

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No volume with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

ConfigurationInstanceCreateArgs

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for roms:

object

The ROM to use for the autoscale configuration.

CreateAutoscaleConfigurationByServiceGroupUUIDRequest

The request message to create an autoscale configuration for a service group based on its UUID.

uuid

string · uuid

The UUID of the service to create a configuration for. Mutually exclusive with name.

min_size

integer · int64

The minimum number of instances to keep running.

max_size

integer · int64

The maximum number of instances to keep running.

warmup_time_ms

integer · int64

The warmup time in milliseconds for new instances.

cooldown_time_ms

integer · int64

The cooldown time in milliseconds for the autoscale configuration.

object

The arguments to use when creating the autoscale configuration.

AutoscalePolicy[]

The policies to apply to the autoscale configuration.

CreateAutoscaleConfigurationByServiceGroupUUIDRequestInstanceCreateArgs

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for roms:

object

The ROM to use for the autoscale configuration.

CreateAutoscaleConfigurationPolicyRequest

The request message to create an autoscale configuration policy for a service.

name

string · required

The Name of the service to add a policy to.

Example: funky-service

object · required

The policy type to add to the autoscale configuration.

CreateAutoscaleConfigurationPolicyResponse

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 32

CreateAutoscaleConfigurationPolicyResponseData

CreateAutoscaleConfigurationPolicyResponsePolicy[]

The policies which were added by the request.

CreateAutoscaleConfigurationPolicyResponsePolicy

status

string · enum · enum

The status of the response.

Enum values:

success

error

uuid

string · uuid

The UUID of the service of the added policy.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the service of the added policy.

Example: funky-policy

metro

string

(Only applies when using global control plane). The metro of the resource.

Example: fra

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No service with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

CreateAutoscaleConfigurationsRequestConfiguration

metro

string

(Optional, only applies when using global control plane). The metro to route the request to.

Example: fra

min_size

integer · int64

The minimum number of instances to keep running.

Example: 2

max_size

integer · int64

The maximum number of instances to keep running.

Example: 12

warmup_time_ms

integer · int64

The warmup time in milliseconds for new instances.

Example: 100

cooldown_time_ms

integer · int64

The cooldown time in milliseconds for the autoscale configuration.

Example: 100

object

The arguments to use when creating the autoscale configuration.

AutoscalePolicy[]

The policies to apply to the autoscale configuration.

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for uuid:

uuid

string · uuid

The UUID of the service to create a configuration for. Mutually exclusive with name.

Example: 123e4567-e89b-12d3-a456-426614174000

CreateAutoscaleConfigurationsResponse

The response to a CreateAutoscaleConfigurationRequest.

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 34

CreateAutoscaleConfigurationsResponseConfigurationsResponse

status

string · enum · enum

The status of the response.

Enum values:

success

error

uuid

string · uuid

The UUID of the service where the configuration was created.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the service where the configuration was created.

Example: funky-instance-template

metro

string

(Only applies when using global control plane). The metro of the configuration.

Example: fra

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No service with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

CreateAutoscaleConfigurationsResponseData

CreateAutoscaleConfigurationsResponseConfigurationsResponse[]

The configuration(s) which were created by the request.

CreateCertificateRequest

The request message for creating/uploading a new certificate.

chain

string · required

The chain of the certificate.

Example: -----BEGIN CERTIFICATE----- MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDQ... -----END CERTIFICATE-----

pkey

string · required

The private key of the certificate.

Example: -----BEGIN PRIVATE KEY----- MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDQ... -----END PRIVATE KEY-----

name

string

The name of the certificate.

This is a human-readable name that can be used to identify the certificate. The name must be unique within the context of your account. If no name is specified, a random name is generated for you. The name can also be used to identify the certificate in API calls.

Example: funky-certificate

metro

string

(Only applies when using global control plane). The metro to route the request to.

Example: fra

cn

string

The common name (CN) of the certificate.

Deprecated: Use common_name instead.

Example: funky-town.com

common_name

string

The common name (CN) of the certificate.

This must be a fully-qualified domain name (FQDN). Exactly one of cn or common_name must be specified.

Example: funky-town.com

CreateCertificateResponse

The response message for creating of a certificate.

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 32

CreateCertificateResponseData

Certificate[]

The certificate which was created by this request.

Note: only one certificate can be specified in the request, so this will always contain a single entry.

CreateInstanceRequest

The request message for creating a new instance.

name

string

(Optional). The name of the instance.

If not provided, a random name will be generated. The name must be unique.

Example: funky-town-g756b5d

image

string

The image to use for the instance.

Example: nginx:latest

metro

string

(Only applies when using global control plane). The metro to route the request to.

Example: fra

args

string[]

(Optional). The arguments to pass to the instance when it starts.

Example: --port=8080 --debug

object

(Optional). Environment variables to set for the instance.

Example: {"ENV_VAR1":"value1","ENV_VAR2":"value2"}

memory_mb

integer · int64

(Optional). Memory in MB to allocate for the instance. Default is 128.

Example: 256

object

(Optional). The service group configuration when creating an instance.

When creating an instance, either a previously created (persistent) service group can be referenced (either through its name or UUID), or a new (ephemeral) service group can be created for the instance by specifying the list of services it should expose and optionally the domains it should use. Not used by template instances.

CreateInstanceRequestVolume[]

Volumes to attach to the instance.

This list can contain both existing and new volumes to create as part of the instance creation. Existing volumes can be referenced by their name or UUID. New volumes can be created by specifying a name, size in MiB, and mount point in the instance. The mount point is the directory in the instance where the volume will be mounted.

autostart

boolean

Whether the instance should start automatically on creation. Must be set to true when timeout_s is specified.

Example: true

replicas

integer · int64

(Optional). Number of additional replicas to create. The total number of instances created is replicas + 1. Defaults to 0.

Example: 5

restart_policy

string · enum · enum

Restart policy for the instance. This defines how the instance should behave when it stops or crashes. Cannot be combined with the delete-on-stop feature.

Enum values:

never

always

on-failure

object

Scale-to-zero configuration for the instance. Requires service_group to be set. Cannot be combined with the delete-on-stop feature.

vcpus

integer · int32

(Optional). Number of vCPUs to allocate for the instance. Defaults to 1.

Example: 1

wait_timeout_ms

integer · int64

Deprecated: Use timeout_s instead. Timeout in milliseconds to wait for all new instances to reach running state. Requires autostart to be set. If timeout_s is not set, this value is converted by rounding up to the next full second. No wait performed for a value of 0.

Example: 2000

features

string[]

Features to enable for the instance. Features are specific configurations or capabilities that can be enabled for the instance. The scale-to-zero and delete-on-stop features are mutually exclusive.

Enum values:

delete-on-stop

timeout_s

integer · int64

Timeout in seconds to wait for all new instances to reach running state. Requires autostart to be set. If you autostart your new instance, you can wait for it to finish starting with a blocking API call if you specify a wait timeout greater than zero. No wait performed for a value of 0.

Example: 2

CreateInstanceRequestRom[]

Read-Only Memory (ROM) blobs to attach to the instance. Unikraft Cloud supports the ability to attach Read-Only Memory (ROM) blobs to instances. It allows you to create a general-purpose base image and then customize individual instances by attaching code or data as separate ROM blobs.

tags

string[]

(Optional). Tags to associate with the instance.

object

Template instances. An existing instance can be saved as a template. This template is then used to create new instances that inherit the exact configuration and state the original instance had when the template was created.

sched_priority

integer · int32

(Optional). The scheduling priority for the instance. Higher values indicate higher priority.

Example: 10

Schedule[]

(Optional). Schedules for the instance. Scheduled operations let you automatically start, stop, delete, or exec a command in the instance on a calendar-based schedule. For exec schedules, set the args field to the command and its arguments. Each instance stores its own schedules, and cloning preserves them.

object

(Optional). Automatic delete-on-idle/request-limit configuration. Not used for template instances.

hostname

string

(Optional). The hostname of the instance.

If not provided, the hostname will be set to the instance name. The hostname must be a valid DNS label (e.g., "my-instance") and is used for internal DNS resolution within the Unikraft Cloud network.

Example: my-instance

NameOrUUID[]

(Optional). Dependencies of the instance.

A list of instance identifiers (name or UUID) that this instance depends on. Dependencies define startup ordering and can be used to ensure that prerequisite instances are running before this instance starts.

CreateInstanceRequestAutokill

Automatic delete-on-idle/request-limit configuration for non-template instances.

time_ms

integer · uint64

Time in milliseconds after the instance was stopped before it is deleted. A value of 0 disables time-based autokill.

num_requests

integer · uint32

Maximum number of requests/connections the instance serves before it is deleted. A value of 0 disables request-based autokill.

CreateInstanceRequestDomain

The domain configuration for the service group. A domain defines a publicly accessible domain name for the instance. If the domain name ends with a period `.`, it must be a valid Fully Qualified Domain Name (FQDN), otherwise it will become a subdomain of the target metro. The domain can be associated with an existing certificate by specifying the certificate's name or UUID. If no certificate is specified and a FQDN is provided, Unikraft Cloud will automatically generate a new certificate for the domain based on Let's Encrypt and seek to accomplish a DNS-01 challenge.

name

string · required

Publicly accessible domain name.

If this name ends in a period . it must be a valid Full Qualified Domain Name (FQDN), e.g. example.com.; otherwise it will become a subdomain of the target metro, e.g. example becomes example.fra0.unikraft.app.

Example: funky-town-g756b5d.fra0.unikraft.app.

object

A reference to an existing certificate which can be used for the specified domain. If unspecified, Unikraft Cloud will automatically generate a new certificate for the domain based on Let's Encrypt and seek to accomplish a DNS-01 challenge.

CreateInstanceRequestRom

Read-Only Memory (ROM) blob to attach to the instance.

name

string

The name of the ROM to use for the instance configuration.

Example: funky-rom

image

string

(Optional). The image of the ROM to use for the instance configuration. Mutually exclusive with files.

Example: nginx:latest

InlineFile[]

(Optional). Inline files to use as the ROM content. When specified, the platform creates an EROFS image from the provided files. Mutually exclusive with image.

CreateInstanceRequestServiceGroup

The service group configuration when creating an instance. If no existing (persistent) service group is specified via its identifier, a new (ephemeral) service group can be created by specifying the services it should expose. A service defines the configuration settings of an exposed port by the instance. A service is a combination of a public port, an internal port, and a set of handlers that define how the service will handle incoming connections.

CreateInstanceRequestDomain[]

If no existing (persistent) service group is specified via its identifier, a new (ephemeral) service group can be created. In addition to the services it must expose, you can specify which domains it should use too.

Service[]

If no existing service group identifier is provided, one or more new (ephemeral, non-persistent) service(s) can be created with the following definitions.

soft_limit

integer · uint32 · min: 1 · max: 65535

The soft limit for the number of services that can be created in this service group.

Example: 100

hard_limit

integer · uint32 · min: 1 · max: 65535

The hard limit for the number of services that can be created in this service group.

Example: 200

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for uuid:

uuid

string · uuid

(Optional). Reference an existing (persistent) service group by its UUID. Mutually exclusive with name.

Example: 123e4567-e89b-12d3-a456-426614174000

CreateInstanceRequestTemplate

Defines the source template used to build a new instance.

prepare

boolean

(Optional). Whether the instance needs to run in order to reach template state

Example: false

uuid

string · uuid

(Optional). The UUID of a template instance to create the instance from. Mutually exclusive with name.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

(Optional). The name of a template instance to create the instance from. Mutually exclusive with UUID.

Example: my-template

metro

string

(Only applies when using global control plane). Where the volume is located.

Example: fra

object

(Optional). Configuration parameters to apply when building the new instance from the source template.

CreateInstanceRequestVolume

A volume defines a storage volume that can be attached to the instance.

at

string · required

The mount point for the volume in the instance.

Example: /mnt/funky-volume

uuid

string · uuid

The UUID of an existing volume.

If this is the only specified field, then it will look up an existing volume by this UUID.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the volume.

If this is the only specified field, then it will look up an existing volume by this name. If the volume does not exist, the request will fail. If a new volume is intended to be created, then this field must be specified along with the mount point in the instance and a provisioning source (size_mb or host_path).

Example: funky-volume-g756b5d

readonly

boolean

Whether the volume is read-only.

If this field is set to true, the volume will be mounted as read-only in the instance. This field is optional and defaults to false and is only applicable when using an existing volume.

Example: false

quota_policy

string

Quota policy for the volume.

Example: static

filesystem

string

Filesystem type to format or configure. Without custom configuration, this is either ext4 or virtiofs.

Example: ext4

tags

string[]

Tags to assign to the new volume.

uid

integer · uint32

Guest UID for managed volumes (host_path mode only).

gid

integer · uint32

Guest GID for managed volumes (host_path mode only).

object

Script arguments passed to volume initialization scripts.

Example: {"arg1":"value1","arg2":"value2"}

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for size_mb:

size_mb

integer · uint64

The size of the volume when creating a new volume.

When creating a new volume as part of the instance create request, specify the size of the volume in MiB.

Example: 32

CreateInstanceResponse

The response message for creating a new instance.

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 875

CreateInstanceResponseData

Instance[]

The instance that was created in this request.

CreateInstanceScaleToZero

policy

string · enum · enum

The specific policy to use for scaling the instance to zero.

Enum values:

off

idle

stateful

boolean

Whether the instance should be stateful when scaled to zero. If set to true, the instance will retain its state (e.g., RAM contents) when scaled to zero. This is useful for instances that need to maintain their state across scale-to-zero operations. If set to false, the instance will lose its state when scaled to zero, and it will be restarted from scratch when scaled back up.

Example: true

cooldown_time_ms

integer · int32

The cooldown time in milliseconds before the instance can be scaled to zero again. This is useful to prevent rapid scaling to zero and back up, which can lead to performance issues or resource exhaustion.

Example: 3000

notify_time_ms

integer · int32

The notification time in milliseconds before the instance is scaled to zero. This allows the instance to perform any necessary cleanup or state saving before being scaled down.

Example: 1000

CreateServiceGroupRequest

The request message for creating a new service group.

name

string

Name of the service group. This is a human-readable name that can be used to identify the service group. The name must be unique within the context of your account. If no name is specified, a random name is generated for you. The name can also be used to identify the service group in API calls.

Example: funky-service-g7gum5cj

metro

string

(Only applies when using global control plane). The metro to route the request to.

Example: fra

Service[]

Description of exposed services.

CreateServiceGroupRequestDomain[]

Description of domains associated with the service group.

soft_limit

integer · uint64

The soft limit is used by the Unikraft Cloud load balancer to decide when to wake up another standby instance.

For example, if the soft limit is set to 5 and the service consists of 2 standby instances, one of the instances receives up to 5 concurrent requests. The 6th parallel requests wakes up the second instance. If there are no more standby instances to wake up, the number of requests assigned to each instance will exceed the soft limit. The load balancer makes sure that when the number of in-flight requests goes down again, instances are put into standby as fast as possible.

Example: 1

hard_limit

integer · uint64

The hard limit defines the maximum number of concurrent requests that an instance assigned to the this service can handle.

The load balancer will never assign more requests to a single instance. In case there are no other instances available, excess requests fail (i.e., they are blocked and not queued).

Example: 100

object

Automatic delete-on-idle configuration.

CreateServiceGroupRequestAutokill

Automatic delete-on-idle configuration for service groups.

time_ms

integer · uint64

Time in milliseconds after the service group becomes empty before it is deleted. A value of 0 disables autokill.

CreateServiceGroupRequestDomain

A domain name

name

string · required

Publicly accessible domain name. If this name ends in a period . it must be a valid Full Qualified Domain Name (FQDN), otherwise it will become a subdomain of the target metro.

Example: example.com.

object

Use an existing certificate for the domain. If this field is specified, the domain must be associated with a valid certificate.

CreateServiceGroupResponse

The response message for creating of a service group.

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 46

CreateServiceGroupResponseData

ServiceGroup[]

The service group which was created by this request.

Note: only one service group can be specified in the request, so this will always contain a single entry.

CreateTemplateInstancesResponse

The response message for creating one or more template instances.

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 76

CreateTemplateInstancesResponseData

CreateTemplateInstancesResponseTemplateInstance[]

List of template instances that were created during the operation.

CreateTemplateInstancesResponseTemplateInstance

status

string · enum · enum

The status of this particular template instance creation operation.

Enum values:

success

error

uuid

string · uuid

The UUID of the template instance that was created.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the template instance that was created.

Example: funky-town-g756b5d

metro

string

(Only applies when using global control plane). The metro of the template instance.

Example: fra

state

string · enum · enum

The current state of the instance.

Enum values:

stopped

starting

running

draining

stopping

template

standby

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No instance with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

CreateTemplateVolumesResponse

The response message for creating one or more template volumes.

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 46

CreateTemplateVolumesResponseData

CreateTemplateVolumesResponseTemplateVolume[]

The template volume(s) which were created by the request.

CreateTemplateVolumesResponseTemplateVolume

status

string · enum · enum

The status of the response.

Enum values:

success

error

uuid

string · uuid

The UUID of the volume converted into a template.

Example: c1d2e3f4-5678-90ab-cdef-1234567890ab

name

string

The name of the volume converted into a template.

Example: funky-vol-g7gum5cj

state

string · enum · enum

The state of the volume.

Enum values:

uninitialized

initializing

available

idle

mounted

busy

error

template

Example: available

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No volume with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

CreateVolumeRequest

The request message for creating a volume.

name

string

The name of the volume.

This is a human-readable name that can be used to identify the volume. The name must be unique within the context of your account. If no name is specified, a random name of the form vol-X is generated for you, where X is a 5 character long random alphanumeric suffix.. The name can also be used to identify the volume in API calls.

Example: funky-vol-t7qumh5j

metro

string

(Only applies when using global control plane). The metro to route the request to.

Example: fra

quota_policy

string · enum · enum

Quota policy for the volume.

Enum values:

static

dynamic

Example: static

filesystem

string

Filesystem type to format or configure. Without custom configuration, this is either ext4 or virtiofs.

Example: ext4

tags

string[]

Tags to assign to the new volume.

uid

integer · uint32

Guest UID for managed volumes (host_path mode only).

gid

integer · uint32

Guest GID for managed volumes (host_path mode only).

object

Script arguments passed to volume initialization scripts.

Example: {"arg1":"value1","arg2":"value2"}

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object
	type = object

Properties for size_mb:

size_mb

integer · uint64

The size of the volume in megabytes.

Example: 64

CreateVolumeResponse

The response message for creating of a volume.

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

CreateVolumeResponseData

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 46

CreateVolumeResponseData

CreateVolumeResponseVolume[]

The volume(s) which were created by the request.

CreateVolumeResponseVolume

status

string · enum · enum

The status of the response.

Enum values:

success

error

uuid

string · uuid

UUID of the newly created volume.

Example: c1d2e3f4-5678-90ab-cdef-1234567890ab

name

string

The name of the newly created volume.

Example: funky-vol-g7gum5cj

metro

string

(Only applies when using global control plane). The metro of the volume.

Example: fra

state

string · enum · enum

The state of the volume.

Enum values:

uninitialized

initializing

available

idle

mounted

busy

error

template

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No volume with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

DataResult

uuid

string · uuid

added

boolean

DeleteAutoscaleConfigurationPolicyResponse

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 54

DeleteAutoscaleConfigurationPolicyResponseData

DeleteAutoscaleConfigurationPolicyResponsePoliciesResponse[]

The policies which were deleted by the request.

DeleteAutoscaleConfigurationPolicyResponsePoliciesResponse

status

string · enum · enum

The status of the response.

Enum values:

success

error

name

string

The name of the service of the deleted policy.

Example: funky-policy

metro

string

(Only applies when using global control plane). The metro of the resource.

Example: fra

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No service with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

DeleteAutoscaleConfigurationsResponse

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 60

DeleteAutoscaleConfigurationsResponseData

DeleteAutoscaleConfigurationsResponseServiceGroup[]

The configuration(s) which were deleted by the request.

DeleteAutoscaleConfigurationsResponseServiceGroup

status

string · enum · enum

The status of the response.

Enum values:

success

error

uuid

string · uuid

The UUID of the service where the configuration was deleted.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the service where the configuration was deleted.

Example: funky-instance-template

metro

string

(Only applies when using global control plane). The metro of the resource.

Example: fra

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No service with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

DeleteCertificatesResponse

The response message for deleting of one or more certificate(s) given their UUID(s) or name(s).

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 42

DeleteCertificatesResponseData

DeleteCertificatesResponseDeletedCertificate[]

The certificate(s) which were deleted by the request.

DeleteCertificatesResponseDeletedCertificate

Details of the certificate which was deleted by this request.

status

string · enum · enum

Indicates whether the delete operation was successful or not for this certificate.

Enum values:

success

error

uuid

string · uuid

The UUID of the certificate which was deleted.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the certificate which was deleted.

Example: funky-certificate

metro

string

(Only applies when using global control plane). The metro of the certificate.

Example: fra

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No certificate with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

DeleteInstanceByUUIDRequestBody

Parameters for deleting the instance by UUID.

timeout_s

integer · int64

Timeout in seconds to wait for the instance to be deleted. No wait performed for a value of 0.

Example: 2

DeleteInstanceRequestItem

The request item for deleting an instance by its UUID or name.

metro

string

(Only applies when using global control plane). The metro of the instance.

Example: fra

timeout_s

integer · int64

Timeout in seconds to wait for the instance to be deleted. No wait performed for a value of 0.

Example: 2

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: uuid
	type = object · requires: name

Properties for uuid:

uuid

string · uuid · required

Mutually exclusive with name.

Example: 123e4567-e89b-12d3-a456-426614174000

DeleteInstancesResponse

The response message for deleting one or more instance(s) given their UUID(s) or name(s).

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 221

DeleteInstancesResponseData

DeleteInstancesResponseInstance[]

The instance(s) which were deleted by the request.

DeleteInstancesResponseInstance

Details of the instance which was deleted by this request.

status

string · enum · enum

Indicates whether the start operation was successful or not for this instance.

Enum values:

success

error

uuid

string · uuid

The UUID of the instance which was deleted.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the instance which was deleted.

Example: funky-town-g756b5d

metro

string

(Only applies when using global control plane). The metro of the instance.

Example: fra

previous_state

string

The previous state of the instance before it was deleted.

Example: stopped

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No instance with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

DeletePolicyRequest

The request message to delete an autoscale configuration policy by name.

name

string · required

The Name of the policy to delete.

Example: funky-policy

DeleteServiceGroupsResponse

The response message for deleting of one or more service group(s) given their UUID(s) or name(s).

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 46

DeleteServiceGroupsResponseData

DeleteServiceGroupsResponseDeletedServiceGroup[]

The service group(s) which were deleted by the request.

DeleteServiceGroupsResponseDeletedServiceGroup

Details of the service group which was deleted by this request.

status

string · enum · enum

Indicates whether the delete operation was successful or not for this service group.

Enum values:

success

error

uuid

string · uuid

The UUID of the service group which was deleted.

Example: 12345678-90ab-cdef-1234-567890abcdef

name

string

The name of the service group which was deleted.

Example: funky-service-g7gum5cj

metro

string

(Only applies when using global control plane). The metro of the service group.

Example: fra

message

string

An optional message providing additional information about the status. This field is only set when this message object is used as a response message, and is useful when the status is not success.

Example: No service with name 'funky-town-g756b5d'

error

integer · int32

Example: 8

DeleteTemplateInstancesResponse

The response message for deleting one or more template instances.

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 76

DeleteTemplateInstancesResponseData

DeleteTemplateInstancesResponseTemplateInstance[]

List of template instances that were processed during the delete operation.

DeleteTemplateInstancesResponseTemplateInstance

uuid

string · uuid

The UUID of the template instance that was deleted.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the template instance that was deleted.

Example: funky-town-g756b5d

status

string · enum · enum

The status of this particular template instance deletion operation.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No template instance with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

DeleteTemplateVolumesResponse

The response message for deleting one or more template volumes.

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 46

DeleteTemplateVolumesResponseData

DeleteTemplateVolumesResponseTemplateVolume[]

The template volume(s) which were deleted by the request.

DeleteTemplateVolumesResponseTemplateVolume

uuid

string · uuid

The UUID of the template volume that was deleted.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the template volume that was deleted.

Example: funky-town-g756b5d

status

string · enum · enum

The status of this particular template volume deletion operation.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No volume with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

DeleteVolumesResponse

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 46

DeleteVolumesResponseData

DeleteVolumesResponseDeletedVolume[]

The volume(s) which were deleted by the request.

DeleteVolumesResponseDeletedVolume

status

string · enum · enum

The status of the response.

Enum values:

success

error

uuid

string · uuid

The UUID of the volume that was deleted.

Example: c1d2e3f4-5678-90ab-cdef-1234567890ab

name

string

The name of the volume that was deleted.

Example: funky-vol-g7gum5cj

metro

string

(Only applies when using global control plane). The metro of the volume.

Example: fra

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No volume with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

DetachVolumeByUUIDRequestBody

object

UUID or name of the instance to detach the volume from.

DetachVolumesRequestItem

A single request of detaching a volume.

object

UUID or name of the instance to detach the volume from.

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: uuid
	type = object · requires: name

Properties for uuid:

uuid

string · uuid · required

The UUID of the volume to detach. Mutually exclusive with name. Exactly one of uuid or name must be provided.

Example: c1d2e3f4-5678-90ab-cdef-1234567890ab

DetachVolumesResponse

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 46

DetachVolumesResponseData

DetachVolumesResponseDetachedVolume[]

The volume(s) which were detached by the request.

DetachVolumesResponseDetachedVolume

status

string · enum · enum

The status of the response.

Enum values:

success

error

uuid

string · uuid

The UUID of the volume that was detached.

Example: c1d2e3f4-5678-90ab-cdef-1234567890ab

name

string

The name of the volume that was detached.

Example: funky-vol-g7gum5cj

metro

string

(Only applies when using global control plane). The metro of the volume.

Example: fra

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No volume with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

Domain

A domain name. Domain names are completely specified with all labels in the hierarchy of the DNS, having no parts omitted. The domain can be associated with an existing certificate by specifying the certificate's name or UUID. If no certificate is specified and a FQDN is provided, Unikraft Cloud will automatically generate a new certificate for the domain based on Let's Encrypt and seek to accomplish a DNS-01 challenge.

fqdn

string

Publicly accessible domain name. If this name ends in a period . it must be a valid Full Qualified Domain Name (FQDN), otherwise it will become a subdomain of the target metro.

Example: example.com.

object

Use an existing certificate for the domain. If this field is specified, the domain must be associated with a valid certificate.

GetAutoscaleConfigurationPolicyRequest

The request message to get an autoscale configuration policy by name.

name

string · required

The Name of the policy to get.

Example: funky-policy

GetAutoscaleConfigurationPolicyResponse

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 12

GetAutoscaleConfigurationPolicyResponseData

GetAutoscaleConfigurationPolicyResponsePolicyResponse[]

The policy which was retrieved by the request.

GetAutoscaleConfigurationPolicyResponsePolicyResponse

status

string · enum · enum

The status of the response.

Enum values:

success

error

object

The policy which was retrieved by the request.

metro

string

(Only applies when using global control plane). The metro of the resource.

Example: fra

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No service with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

GetAutoscaleConfigurationsResponse

The response message for a GetAutoscaleConfigurationsRequest.

status

string · enum · enum

The status of the response.

Enum values:

success

error

unconfigured

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 50

GetAutoscaleConfigurationsResponseData

GetAutoscaleConfigurationsResponseServiceGroup[]

The configuration(s) which were retrieved by the request.

GetAutoscaleConfigurationsResponseServiceGroup

status

string · enum · enum

The status of the response.

Enum values:

success

error

uuid

string · uuid

The UUID of the service where the configuration was created.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the service where the configuration was created.

Example: funky-instance-template

metro

string

(Only applies when using global control plane). The metro of the service group.

Example: fra

enabled

boolean

If the autoscale configuration is enabled.

Example: true

min_size

integer · int64

The minimum number of instances to keep running. Only if enabled is true.

Example: 2

max_size

integer · int64

The maximum number of instances to keep running. Only if enabled is true.

Example: 10

warmup_time_ms

integer · int64

The warmup time in seconds for new instances. Only if enabled is true.

Example: 3000

cooldown_time_ms

integer · int64

The cooldown time in seconds for the autoscale configuration. Only if enabled is true.

Example: 3000

object

The instance template used for the autoscale configuration. Only if enabled is true.

AutoscalePolicy[]

The policies applied to the autoscale configuration.

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No service with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

GetCertificatesResponse

The response message for getting one or more certificate(s) given their UUID(s) or name(s).

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 55

GetCertificatesResponseData

Certificate[]

The certificate(s) which were retrieved by the request.

GetImagesRequestTagOrDigest

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: digest
	type = object · requires: tag

Properties for digest:

digest

string · required

GetImagesResponse

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the response.

Example: No images found

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 123

GetImagesResponseData

Image[]

The list of images.

GetInstanceLogsByUUIDRequestBody

offset

integer · int64

The byte offset of the log output to receive. A negative sign makes the offset relative to the end of the log.

Example: 56000

limit

integer · int64

The amount of bytes to return at most.

Example: 1500

GetInstancesLogsRequestItem

A single item in the request.

offset

integer · int64

The byte offset of the log output to receive. A negative sign makes the offset relative to the end of the log.

Example: 450

limit

integer · int64

The amount of bytes to return at most.

Example: 3000

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for uuid:

uuid

string · uuid

The UUID of the instance to retrieve logs for. Mutually exclusive with name.

Example: 123e4567-e89b-12d3-a456-426614174000

GetInstancesLogsResponse

The response message for getting the logs of one or more instance(s) by their UUID(s) or name(s).

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 47

GetInstancesLogsResponseAvailable

start

integer · int64

The first byte offset that can be retrieved.

Example: 250

end

integer · int64

The last byte offset that can be retrieved.

Example: 2700

GetInstancesLogsResponseData

GetInstancesLogsResponseLoggedInstance[]

The instance which this requested waited on.

Note: only one instance can be specified in the request, so this will always contain a single entry.

GetInstancesLogsResponseLoggedInstance

uuid

string · uuid

The UUID of the instance.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the instance.

Example: funky-town-g756b5d

output

string

Base64 encoded log output of the instance.

Example: d2h5LWFyZS15b3UtZGVjb2RpbmctdGhpcw==

object

Description of the log availability.

object

Description of the range that was returned. Useful for requests with offset relative to end.

state

string · enum · enum

State of the instance when the logs were retrieved.

Enum values:

stopped

starting

running

draining

stopping

template

standby

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No instance with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

status

string · enum · enum

The status of the response.

Enum values:

success

error

GetInstancesLogsResponseRange

start

integer · int64

The first retrieved byte.

Example: 450

end

integer · int64

The last retrieved byte.

Example: funky-town-g756b5d

GetInstancesMetricsResponse

The response message for getting the metrics of one or more instance(s) given their UUID(s) or name(s).

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 76

GetInstancesMetricsResponseData

GetInstancesMetricsResponseInstanceMetrics[]

The instance which this requested metrics for. Note: only one instance can be specified in the request, so this will always contain a single entry.

GetInstancesMetricsResponseInstanceMetrics

rss_bytes

integer · uint64

Resident set size of the VMM in bytes.

The resident set size (RSS) specifies the amount of physical memory that has been touched by the instance and is currently reserved for the instance on the Unikraft Cloud server. The RSS grows until the instance has touched all memory assigned to it via the memory_mb setting and may also exceed this value as supporting services running outside the instance acquire memory. The RSS is different from the current amount of memory allocated by the application, which is likely to fluctuate over the lifetime of the application. The RSS is not a cumulative metric. When the instance is stopped rss goes down to 0.

Example: 5677765543

cpu_time_ms

integer · uint64

Consumed CPU time in milliseconds.

Example: 560007005

boot_time_us

integer · uint64

The boot time of the instance in microseconds. We take a pragmatic approach is to define the boot time. We calculate this as the difference in time between the moment the virtualization toolstack is invoked to respond to a VM boot request and the moment the OS starts executing user code (i.e., the end of the guest OS boot process). This is essentially the time that a user would experience in a deployment, minus the application initialization time, which we leave out since it is independent from the OS.

Example: 560007005

net_time_us

integer · uint64

This is the time it took for the user-level application to start listening on a non-localhost port measured in microseconds. This is the time from when the instance started until it reasonably ready to start responding to network requests. This is useful for measuring the time it takes for the instance to become operationally ready.

Example: 560007005

rx_bytes

integer · uint64

Total amount of bytes received from network.

Example: 12312353

rx_packets

integer · uint64

Total count of packets received from network.

Example: 43432

tx_bytes

integer · uint64

Total amount of bytes transmitted over network.

Example: 6565643

tx_packets

integer · uint64

Total count of packets transmitted over network.

Example: 54534

nconns

integer · uint64

Number of currently established inbound connections (non-HTTP).

Example: 5

nreqs

integer · uint64

Number of in-flight HTTP requests.

Example: 12

nqueued

integer · uint64

Number of queued inbound connections and HTTP requests.

Example: 5

ntotal

integer · uint64

Total number of inbound connections and HTTP requests handled.

Example: 21

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No instance with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

status

string · enum · enum

The status of the response.

Enum values:

success

error

GetInstancesResponse

The response after retrieving an instance by its name or UUID.

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 432

GetInstancesResponseData

Instance[]

The instance(s) that were retrieved by the request.

GetServiceGroupsResponse

The response message for getting one or more service group(s) given their UUID(s) or name(s).

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 46

GetServiceGroupsResponseData

ServiceGroup[]

The service group(s) which were retrieved by the request.

GetTemplateInstancesResponse

The response message for getting one or more template instances.

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 76

GetTemplateInstancesResponseData

Instance[]

List of template instances that were retrieved during the operation.

GetTemplateVolumesResponse

The response message for getting one or more template volumes.

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Partial success

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 46

GetTemplateVolumesResponseData

Volume[]

The template volume(s) which were retrieved by the request.

GetVolumesResponse

The response message for getting one or more volume(s) given their UUID(s) or name(s).

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 46

GetVolumesResponseData

Volume[]

The volume(s) which were retrieved by the request.

GoogleProtobufValue

HealthzResponse

The response message for a health check of the platform.

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the response.

Example: Invalid name 'non-funky-town'

ResponseError[]

A list of errors which may have occurred during the request.

object

The response data for this request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 875

HealthzResponseData

For now, no additional data is returned by the health check.

object

Image

url

string

metro

string

(Only applies when using global control plane). The metro of the image.

Example: fra

created_at

string · date-time

The time the volume was created.

Example: 2021-01-01T00:00:00Z

initrd_or_rom

boolean

size_in_bytes

integer · int64

args

string[]

object

tags

string[]

users

string[]

InlineFile

An inline file entry represents a single file within an image.

path

string · required

The file path within the image.

data

string · required

The file data, encoded according to the encoding field.

encoding

string · enum · enum

(Optional). The encoding of the data field. Defaults to "text".

Enum values:

text

base64

Instance

An instance is a unikernel virtual machine running an application.

uuid

string · uuid

The UUID of the instance.

This is a unique identifier for the instance that is generated when the instance is created. The UUID is used to reference the instance in API calls and can be used to identify the instance in all API calls that require an instance identifier.

name

string

The name of the instance.

This is a human-readable name that can be used to identify the instance. The name must be unique within the context of your account. The name can also be used to identify the instance in API calls.

Example: funky-town-g756b5d

metro

string

(Only applies when using global control plane). Where the instance is located.

Example: fra

created_at

string · date-time

The time the instance was created.

Example: 2023-10-01T12:00:00Z

state

string · enum · enum

The state of the instance. This indicates the current state of the instance, such as whether it is running, stopped, or in an error state.

Enum values:

stopped

starting

running

draining

stopping

template

standby

private_fqdn

string

The internal hostname of the instance. This address can be used privately within the Unikraft Cloud network to access the instance. It is not accessible from the public Internet.

Example: funky-town-g756b5d.internal

image

string

The image used to create the instance. This is a reference to the Unikraft image that was used to create the instance.

Example: nginx:latest

memory_mb

integer · uint64

The amount of memory in megabytes allocated for the instance. This is the total amount of memory that is available to the instance for its operations.

Example: 1024

vcpus

integer · uint32

The number of vCPUs allocated for the instance. This is the total number of virtual CPUs that are available to the instance for its operations.

Example: 1

args

string[]

The arguments passed to the instance when it was started. This is a list of command-line arguments that were provided to the instance at startup. These arguments can be used to configure the behavior of the instance and its applications.

Example: --port=8080 --debug

object

Environment variables set for the instance.

Example: {"ENV_VAR":"value"}

start_count

integer · uint64

The total number of times the instance has been started. This is a counter that increments each time the instance is started, regardless of whether it was manually stopped or restarted. This can be useful for tracking the usage of the instance over time and/or for debugging purposes.

Not used for template instances.

Example: 6

restart_count

integer · uint64

The total number of times the instance has been restarted. This is a counter that increments each time the instance has been restarted. This can be useful for tracking the usage of the instance over time and/or for debugging purposes. Not used for template instances.

Example: 1

started_at

string · date-time

The time the instance was started. This is the timestamp when the instance was last started. Not used for template instances.

Example: 2023-10-01T12:00:00Z

stopped_at

string · date-time

The time the instance was stopped. This is the timestamp when the instance was last stopped. If the instance is currently running, this field will be empty. Not used for template instances.

Example: 2023-10-01T12:00:00Z

uptime_ms

integer · uint64

The total amount of time the instance has been running in milliseconds. Not used for template instances.

Example: 8954050300

vmm_start_time_us

integer · uint64

(Developer-only). The time taken between the main controller and the beginning of execution of the VMM (Virtual Machine Monitor) measured in microseconds. This field is primarily used for debugging and performance analysis purposes. Not used for template instances.

Example: 70040

vmm_load_time_us

integer · uint64

(Developer-only). The time it took the VMM (Virtual Machine Monitor) to load the instance's kernel and initramfs into VM memory measured in microseconds. This field is primarily used for debugging and performance analysis purposes. Not used for template instances.

Example: 4050

vmm_ready_time_us

integer · uint64

(Developer-only). The time taken for the VMM (Virtual Machine Monitor) to become ready to execute the instance measured in microseconds. This is the time from when the VMM started until it was ready to execute the instance's code. This field is primarily used for debugging and performance analysis purposes. Not used for template instances.

Example: 400

boot_time_us

integer · uint64

Example: 9000

net_time_us

integer · uint64

Example: 11000

stop_reason

integer · uint32

The instance stop reason.

Provides reason as to why an instance is stopped or in the process of shutting down. The stop reason is a bitmask that tells you the origin of the shutdown:

Bit	4	3	2	1	0 (LSB)
Purpose	[F]orced	[U]ser	[P]latform	[A]pp	[K]ernel

Forced: This was a force stop. A forced stop does not give the instance a chance to perform a clean shutdown. Bits 0 (Kernel) and 1 (App) can thus never be set for forced shutdowns. Consequently, there won't be an exit_code or stop_code.
User: Stop initiated by user, e.g. via an API call.
Platform: Stop initiated by platform, e.g. an autoscale policy.
App: The Application exited. The exit_code field will be set.
Kernel: The kernel exited. The stop_code field will be set.

For example, the stop reason will contain the following values in the given scenarios:

Value	Bitmask	Aliases	Scenario
28	`11100`	`FUP--`	Forced user-initiated shutdown.
15	`01111`	`-UPAK`	Regular user-initiated shutdown. The application and kernel have exited. The exit_code and stop_code indicate if the application and kernel shut down cleanly.
13	`01101`	`-UP-K`	The user initiated a shutdown but the application was forcefully killed by the kernel during shutdown. This can be the case if the image does not support a clean application exit or the application crashed after receiving a termination signal. The exit_code won’t be present in this scenario.
7	`00111`	`--PAK`	Unikraft Cloud initiated the shutdown, for example, due to scale-to-zero. The application and kernel have exited. The exit_code and stop_code indicate if the application and kernel shut down cleanly.
3	`00011`	`---AK`	The application exited. The exit_code and stop_code indicate if the application and kernel shut down cleanly.
1	`00001`	`----K`	The instance likely expierenced a fatal crash and the stop_code contains more information about the cause of the crash.
0	`00000`	`-----`	The stop reason is unknown.
Not used for template instances.

Example: 15

exit_code

integer · uint32

The application exit code.

This is the code which the application returns upon leaving its main entry point. The encoding of the exit code is application specific. See the documentation of the application for more details. Usually, an exit code of 0 indicates success / no failure. Not used for template instances.

Example: 137

stop_code

integer · uint32

The kernel stop code.

This value encodes multiple details about the stop irrespective of the application.

Code
MSB                                                     LSB
┌──────────────┬──────────┬──────────┬───────────┬────────┐
│ 31 ────── 24 │ 23 ── 16 │    15    │ 14 ──── 8 │ 7 ── 0 │
├──────────────┼──────────┼──────────┼───────────┼────────┤
│ reserved[^1] │ errno    │ shutdown │ initlevel │ reason │
└──────────────┴──────────┴──────────┴───────────┴────────┘

errno: The application errno, using Linux's errno.h values. (Optional, can be 0.)
shutdown: Whether the shutdown originated from the inittable (0) or from the termtable (1).
initlevel: The initlevel at the time of the stop.
reason: The reason for the stop. See StopCodeReason.

Example: 33024

restart_policy

string · enum · enum

The restart configuration for the instance.

When an instance stops either because the application exits or the instance crashes, Unikraft Cloud can auto-restart your instance. Auto-restarts are performed according to the restart policy configured for a particular instance.

The policy can have the following values:

Policy	Description
`never`	Never restart the instance (default).
`always`	Always restart the instance when the stop is initiated from within the instance (i.e., the application exits or the instance crashes).
`on-failure`	Only restart the instance if it crashes.

When an instance stops, the stop reason and the configured restart policy are evaluated to decide if a restart should be performed. Unikraft Cloud uses an exponential back-off delay (immediate, 5s, 10s, 20s, 40s, ..., 5m) to slow down restarts in tight crash loops. If an instance runs without problems for 10s the back-off delay is reset and the restart sequence ends.

The restart.attempt attribute reported in counts the number of restarts performed in the current sequence. The restart.next_at field indicates when the next restart will take place if a back-off delay is in effect.

A manual start or stop of the instance aborts the restart sequence and resets the back-off delay.

Enum values:

never

always

on-failure

object

The scale-to-zero configuration for the instance.

With conventional cloud platforms you need to keep at least one instance running at all times to be able to respond to incoming requests. Performing a just-in-time cold boot is simply too time-consuming and would create a response latency of multiple seconds. This is not the case with Unikraft Cloud. Instances on Unikraft Cloud are able to cold boot within milliseconds, which allows us to perform low-latency scale-to-zero.

To enable scale-to-zero for an instance it is sufficient to add a scale_to_zero configuration block. Unikraft Cloud will then put the instance into standby if there is no traffic to your service within the window of a cooldown period. When there is new traffic coming in, it is automatically started again.

If you have a heavyweight application that takes long to cold boot or has bad first request latency (e.g., with JIT compilation) consider to enable stateful scale-to-zero.

InstanceVolume[]

The list of volumes attached to the instance.

object

The service group configuration for the instance.

InstanceNetworkInterface[]

The network interfaces of the instance. Not used for template instances.

tags

string[]

The tags associated with the instance.

status

string · enum · enum

An optional field representing the status of the request. This field is only set when this message object is used as a response message.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is only set when this message object is used as a response message, and is useful when the status is not success.

Example: No instance with name 'funky-town-g756b5d'

error

integer · int32

Example: 8

object

The snapshot of the instance, if exists.

delete_lock

boolean

If set to true, the instance cannot be deleted until the lock is removed.

object

The current restart attempt for the instance. Not used for template instances.

InstanceRom[]

Schedule[]

Scheduled operations for this instance.

Each schedule defines a calendar expression and an action (start, stop, delete, or exec) to perform at matching times. When the action is exec, the args field of the schedule specifies the command to run inside the instance.

object

Automatic delete-on-idle/request-limit configuration. Not used for template instances.

object

Template-specific automatic delete-on-idle configuration. Not used for non-template instances.

InstanceAutokill

Automatic delete-on-idle/request-limit configuration for non-template instances. Not used for template instances.

time_ms

integer · uint64

Time in milliseconds after the instance was stopped before it is deleted. A value of 0 disables time-based autokill.

num_requests

integer · uint32

Maximum number of requests/connections the instance serves before it is deleted. A value of 0 disables request-based autokill.

InstanceCreateArgsInstanceCreateRequestRoms

name

string

The name of the ROM to use for the autoscale configuration.

image

string

(Optional). The image of the ROM to use for the autoscale configuration. Mutually exclusive with files.

InlineFile[]

(Optional). Inline files to use as the ROM content. When specified, the platform creates an EROFS image from the provided files. Mutually exclusive with image.

InstanceNetworkInterface

An instance network interface.

uuid

string · uuid

The UUID of the network interface. This is a unique identifier for the network interface that is generated when the instance is created.

Example: c1d2e3f4-5678-90ab-cdef-1234567890ab

private_ip

string

The private IP address of the network interface. This is the internal IP address that is used for communication between instances within the same network.

Example: 10.0.0.61

mac

string

The MAC address of the network interface.

Example: 12:b0:a0:00:00:3d

rx_bytes

integer · uint64

Amount of bytes received from interface.

Example: 5345

rx_packets

integer · uint64

Count of packets received from interface

Example: 110

tx_bytes

integer · uint64

Amount of bytes sent to interface.

Example: 1500

tx_packets

integer · uint64

Count of packets sent to interface

Example: 12

InstanceRestartAttempt

Records the current restart attempt of an instance.

attempt

integer · uint32

Current restart attempt number. This is incremented each time the instance is restarted automatically by the platform.

Example: 1

next_at

string · date-time

Timestamp of the next scheduled restart attempt.

Example: 2023-10-05T14:48:00Z

InstanceRom

Read-Only Memory (ROM) blob to attach to the instance.

name

string

The name of the ROM to use for the instance configuration.

Example: funky-rom

image

string

(Optional). The image of the ROM to use for the instance configuration. Mutually exclusive with files.

Example: nginx:latest

at

string

(Optional). The path at which the ROM should be automatically mounted inside the instance. When set, the platform mounts the ROM device at the specified path so the guest does not need to mount it manually. When omitted, the ROM is exposed as a raw block device and the guest is responsible for mounting it.

Example: /rom0

InlineFile[]

(Optional). Inline files to use as the ROM content. When specified, the platform creates an EROFS image from the provided files. Mutually exclusive with image.

InstanceScaleToZero

Scale-to-zero defines the configuration for scaling the instance to zero. When an instance is scaled-to-zero it can be either stopped (and fully shutdown) or paused wherein the state of the instance is preserved (e.g., RAM contents) and the instance can be resumed later without losing its state, i.e. "stateful".

enabled

boolean

Indicates whether scale-to-zero is enabled for the instance.

Example: true

policy

string · enum · enum

The specific policy to use for scaling the instance to zero.

Enum values:

off

idle

stateful

boolean

Example: true

cooldown_time_ms

integer · int32

Example: 3000

notify_time_ms

integer · int32

The notification time in milliseconds before the instance is scaled to zero. This allows the instance to perform any necessary cleanup or state saving before being scaled down.

Example: 1000

InstanceServiceGroup

The service group configuration for the instance. This is a reference to the service group that the instance is part of. The service group defines the services (e.g. ports, connection handling) that the instance exposes and how they are configured.

uuid

string · uuid

The UUID of the service group.

This is a unique identifier for the service group that is generated when the service is created. The UUID is used to reference the service group in API calls and can be used to identify the service in all API calls that require an service identifier.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the service group.

This is a human-readable name that can be used to identify the service group. The name is unique within the context of your account. The name can also be used to identify the service group in API calls.

Example: funky-service-g756b5d

metro

string

(Only applies when using global control plane). Where the service group is located.

Example: fra

ServiceGroupInstanceDomain[]

The domain configuration for the service group.

InstanceSnapshot

The snapshot UUID of the instance.

uuid

string · uuid

The UUID of the snapshot.

InstanceTemplateAutokill

Automatic delete-on-idle configuration for template instances.

time_ms

integer · uint64

Time in milliseconds after the template was last used for cloning before it is deleted. A value of 0 disables template autokill.

InstanceVolume

A volume defines a storage which can be attached to the instance. Volumes can be used to store persistent data which should remain available even if the instance is stopped or restarted.

uuid

string · uuid

The UUID of the volume.

This is a unique identifier for the volume that is generated when the volume is created. The UUID is used to reference the volume in API calls and can be used to identify the volume in all API calls that require a volume identifier.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the volume.

This is a human-readable name that can be used to identify the volume. The name must be unique within the context of your account. The name can also be used to identify the volume in API calls.

Example: funky-volume-g756b5d

metro

string

(Only applies when using global control plane). Where the volume is located.

Example: fra

at

string

The mount point of the volume in the instance. This is the directory in the instance where the volume will be mounted.

Example: /mnt/funky-volume

readonly

boolean

Whether the volume is read-only or not.

Example: true

NameOrUUID

An identifier for a resource. Either a name or a UUID.

metro

string

(Only applies when using global control plane). The metro of the resource.

Example: fra

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: uuid
	type = object · requires: name

Properties for uuid:

uuid

string · uuid · required

Mutually exclusive with name.

Example: 123e4567-e89b-12d3-a456-426614174000

Quotas

uuid

string · uuid

The UUID of the quota.

Example: c1d2e3f4-5678-90ab-cdef-1234567890ab

object

Used quota

object

Configured quota limits

object

Additional limits

status

string · enum · enum

An optional field representing the status of the request. This field is only set when this message object is used as a response message.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is only set when this message object is used as a response message, and is useful when the status is not success.

Example: No user with name 'funky-user'

error

integer · int32

Example: 8

QuotasLimits

min_memory_mb

integer · int64

Minimum amount of memory assigned to live instances in megabytes

Example: 16

max_memory_mb

integer · int64

Maximum amount of memory assigned to live instances in megabytes

Example: 2048

min_volume_mb

integer · int64

Minimum size of a volume in megabytes

Example: 1

max_volume_mb

integer · int64

Maximum size of a volume in megabytes

Example: 1024

min_autoscale_size

integer · int64

Minimum size of an autoscale group

Example: 1

max_autoscale_size

integer · int64

Maximum size of an autoscale group

Example: 16

min_vcpus

integer · int64

Minimum number of vCPUs

Example: 2

max_vcpus

integer · int64

Maximum number of vCPUs

Example: 4

QuotasResponse

The response message for getting the quota of a user given their UUID.

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 46

QuotasResponseData

Quotas[]

The quota(s) which were retrieved by the request.

QuotasStats

instances

integer · int64

Number of instances

Example: 16

live_instances

integer · int64

Number of instances that are not in the stopped state

Example: 4

live_vcpus

integer · int64

Number of vCPUs

Example: 4

live_memory_mb

integer · int64

Amount of memory assigned to instances that are not in the stopped state in megabytes

Example: 2048

service_groups

integer · int64

Number of services

Example: 15

services

integer · int64

Number of published network ports over all existing services

Example: 30

volumes

integer · int64

Number of volumes

Example: 2

total_volume_mb

integer · int64

Total size of all volumes in megabytes

Example: 1024

ResponseError

The error response message for an API request.

status

integer · uint64

The HTTP status code of the error.

Example: 401

ResponseStatus

string · enum · enum

Enum values:

success

error

The response status of an API request.

Schedule

A schedule defines when an action should be performed on an instance. Each schedule specifies a name, a calendar expression following systemd calendar event syntax, and an action (start, stop, delete, or exec). Calendar expressions format: [weekday] [[year-]month-day] [hour:minute[:second]] Supported syntax: - `*` - Any value - `5` - Exact value - `1..5` - Range - `1..5/2` - Range with step - `1,2,5` - Comma-separated list Example: `*-*-* 09:00:00` - Every day at 09:00 UTC Example: `Sat,Sun *-*-* 20:00:00` - Every Saturday and Sunday at 20:00 UTC

name

string · required

The name of the schedule.

Must be unique within an instance.

Example: daily-stop

when

string · required

The calendar expression specifying when the action should be performed.

Uses systemd calendar event syntax. See https://www.man7.org/linux/man-pages/man7/systemd.time.7.html

Example: null

action

string · enum · enum · required

The action to perform at the scheduled time.

Enum values:

start

stop

delete

exec

Example: stop

next_at

integer · int64 · readOnly

The timestamp of when the next scheduled action will occur.

This field is populated only in responses (not settable in requests). Unix timestamp in seconds. Omitted if no next execution is scheduled.

Example: 1696512000

args

string[]

The command to execute when the action is exec.

Required when action is SCHEDULE_ACTION_EXEC, ignored otherwise. Each element is a separate argument; the first element is the executable.

Example: ["/bin/sh","-c","echo hello"]

Service

A service connects a public-facing port to an internal destination port on which an application instance listens on. Additional handlers can be defined for each published port in order to define how the service will handle incoming connections and forward traffic from the Internet to your application. For example, a service can be configured to terminate TLS connections, redirect HTTP traffic, or enable HTTP mode for load balancing.

port

integer · uint32 · required

This is the public-facing port that the service will be accessible from on the Internet.

Example: 443

destination_port

integer · uint32

The port number that the instance is listening on. This is the internal port which Unikraft Cloud will forward traffic to.

Example: 8080

handlers

string[]

Connection handlers to use for the service. Handlers define how the service will handle incoming connections and forward traffic from the Internet to your application. For example, a service can be configured to terminate TLS connections, redirect HTTP traffic, or enable HTTP mode for load balancing. You configure the handlers for every published service port individually.

Enum values:

tls

http

redirect

ServiceGroup

A service group on Unikraft Cloud is used to describe how your application exposes its functionality to the outside world. Once defined, assigning an instance to the service will make it accessible from the Internet. An application, running as an instance, may expose one or more ports, e.g. it listens on port 80 because your application exposes a HTTP web service. This, along with a set of additional metadata defines how the "service" is configured and accessed. For example, a service may be configured to use TLS, or be bound to a specific domain name. When an instance is assigned to a service group, it immediately becomes accessible over the Internet on the exposed public port, using the set DNS name, and is routed to the set destination port. Note: If you do not specify a DNS name when you create a service and you indicate that the application exposes some ports, Unikraft Cloud will generates a random DNS name for you. Unikraft Cloud also supports custom domains like www.example.com and wildcard domains like *.example.com.

uuid

string · uuid

The UUID of the service group.

This is a unique identifier for the service group that is generated when the service group is created. The UUID is used to reference the service in API calls and can be used to identify the service group in all API calls that require an identifier.

Example: c1d2e3f4-5678-90ab-cdef-1234567890ab

name

string

The name of the service group.

This is a human-readable name that can be used to identify the service group. The name must be unique within the context of your account. The name can also be used to identify the service in API calls.

Example: funky-service-g7gum5cj

metro

string

(Only applies when using global control plane). Where the service group is located.

Example: fra

created_at

string · date-time

The time the service was created.

Example: 2023-10-01T12:00:00Z

persistent

boolean

Indicates if the service will stay remain even after the last instance detached. If this is set to false, the service will be deleted when the last instance detached from it. If this is set to true, the service will remain and can be reused by other instances. This is useful if you want to keep the service configuration, e.g., the published ports, handlers, and domains, even if there are no instances assigned to it.

Example: true

autoscale

boolean

Indicates if the service has autoscale enabled. See the associated autoscale documentation for more information about how to set this up. Autoscale policies can be set up after the service has been created.

Example: true

soft_limit

integer · uint64

The soft limit is used by the Unikraft Cloud load balancer to decide when to wake up another standby instance. For example, if the soft limit is set to 5 and the service consists of 2 standby instances, one of the instances receives up to 5 concurrent requests. The 6th parallel requests wakes up the second instance. If there are no more standby instances to wake up, the number of requests assigned to each instance will exceed the soft limit. The load balancer makes sure that when the number of in-flight requests goes down again, instances are put into standby as fast as possible.

Example: 1

hard_limit

integer · uint64

The hard limit defines the maximum number of concurrent requests that an instance assigned to the this service can handle. The load balancer will never assign more requests to a single instance. In case there are no other instances available, excess requests fail (i.e., they are blocked and not queued).

Example: 100

Service[]

List of published network ports for this service and the destination port to which Unikraft Cloud will forward traffic to. Additional handlers can be defined for each published port in order to define how the service will handle incoming connections and forward traffic from the Internet to your application. For example, a service can be configured to terminate TLS connections, redirect HTTP traffic, or enable HTTP mode for load balancing.

Domain[]

List of domains associated with the service. Domains are used to access the service over the Internet.

ServiceGroupInstance[]

List of instances assigned to the service.

status

string · enum · enum

An optional field representing the status of the request. This field is only set when this message object is used as a response message.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is only set when this message object is used as a response message, and is useful when the status is not success.

Example: No service with name 'funky-town-g756b5d'

error

integer · int32

Example: 8

object

Automatic delete-on-idle configuration.

ServiceGroupAutokill

Automatic delete-on-idle configuration for service groups.

time_ms

integer · uint64

Time in milliseconds after the service group becomes empty before it is deleted. A value of 0 disables autokill.

ServiceGroupInstance

uuid

string · uuid

The UUID of the instance. This is a unique identifier for the instance that is generated when the instance is created. The UUID is used to reference the instance in API calls and can be used to identify the instance in all API calls that require an instance identifier.

Example: 12345678-90ab-cdef-1234-567890abcdef

name

string

The name of the instance. This is a human-readable name that can be used to identify the instance. The name must be unique within the context of your account. If no name is specified, a random name is generated for you. The name can also be used to identify the instance in API calls.

Example: funky-vol-g7gum5cj

ServiceGroupInstanceDomain

The domain configuration for the service group. Domain names are completely specified with all labels in the hierarchy of the DNS, having no parts omitted. The domain can be associated with an existing certificate by specifying the certificate's name or UUID. If no certificate is specified and a FQDN is provided, Unikraft Cloud will automatically generate a new certificate for the domain based on Let's Encrypt and seek to accomplish a DNS-01 challenge.

fqdn

string

Publicly accessible domain name.

If this name ends in a period . it must be a valid Full Qualified Domain Name (FQDN), otherwise it will become a subdomain of the target metro.

Example: funky-town-g756b5d.fra0.unikraft.app.

object

The certificate associated with the domain.

The certificate is used to secure the domain with TLS/SSL. If no certificate is specified, Unikraft Cloud will automatically generate a new certificate for the domain based on Let's Encrypt and seek to accomplish a DNS-01 challenge.

ServiceGroupTemplate

name

string

The name of the template used for the autoscale configuration.

Example: funky-instance-template

uuid

string · uuid

The UUID of the template used for the autoscale configuration.

Example: 123e4567-e89b-12d3-a456-426614174000

StartInstanceByUUIDRequestBody

Parameters for starting the instance.

wait_timeout_ms

integer · int64

Deprecated: Use timeout_s instead. Timeout in milliseconds to wait for the instance to reach running state. If timeout_s is not set, this value is converted by rounding up to the next full second. No wait performed for a value of 0.

Example: 2000

timeout_s

integer · int64

Timeout in seconds to wait for the instance to reach running state. If you start your instance, you can wait for it to finish starting with a blocking API call if you specify a wait timeout greater than zero. No wait performed for a value of 0.

Example: 2

StartInstancesRequestItem

A single request item to start an instance.

metro

string

(Only applies when using global control plane). The metro to route the request to.

Example: fra

wait_timeout_ms

integer · int64

Example: 2000

timeout_s

integer · int64

Example: 2

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for uuid:

uuid

string · uuid

The UUID of the instance to start. Mutually exclusive with name.

Example: 123e4567-e89b-12d3-a456-426614174000

StartInstancesResponse

The response message for starting one or more instance(s) given their UUID(s) or name(s).

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 256

StartInstancesResponseData

StartInstancesResponseStartedInstance[]

The instance(s) which were started by the request.

StartInstancesResponseStartedInstance

status

string · enum · enum

Indicates whether the start operation was successful or not for this instance.

Enum values:

success

error

uuid

string · uuid

The UUID of the instance which was deleted.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the instance which was deleted.

Example: funky-town-g756b5d

metro

string

(Only applies when using global control plane). The metro of the instance.

Example: fra

state

string

The current state of the instance after this request.

Example: running

previous_state

string

The previous state of the instance before it was deleted.

Example: stopped

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No instance with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

StopInstanceByUUIDRequestBody

Parameters for stopping the instance.

force

boolean

Whether to immediately force stop the instance.

Example: true

drain_timeout_ms

integer · uint64

Timeout for draining connections in milliseconds. No draining will occur if set to 0. The instance does not receive new connections in the draining phase. The instance is stopped when the last connection has been closed or the timeout expired. The maximum timeout may vary. Use -1 for the largest possible value. Ignored if force is set.

Note: This endpoint does not block. Use the wait endpoint for the instance to reach the stopped state.

Example: 550

quick

boolean

Whether to perform a quick shutdown. This flag is overridden by force.

Example: false

ifstate

string

Only stop the instance if it is in this state.

Example: running

StopInstancesRequestItem

A single request item to stop an instance.

metro

string

(Only applies when using global control plane). The metro to route the request to.

Example: fra

force

boolean

Whether to immediately force stop the instance.

Example: false

drain_timeout_ms

integer · uint64

Timeout for draining connections in milliseconds. The instance does not receive new connections in the draining phase. The instance is stopped when the last connection has been closed or the timeout expired. The maximum timeout may vary. Use -1 for the largest possible value.

Note: This endpoint does not block. Use the wait endpoint for the instance to reach the stopped state.

Example: 250

quick

boolean

Whether to perform a quick shutdown. This flag is overridden by force.

Example: false

ifstate

string

Only stop the instance if it is in this state.

Example: running

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for uuid:

uuid

string · uuid

The UUID of the instance to stop. Mutually exclusive with name.

Example: 123e4567-e89b-12d3-a456-426614174000

StopInstancesResponse

The response message for stopping one or more instance(s) given their UUID(s) or name(s).

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 23

StopInstancesResponseData

StopInstancesResponseStoppedInstance[]

The instance(s) which were stopped by the request.

StopInstancesResponseStoppedInstance

uuid

string · uuid

The UUID of the instance.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the instance.

Example: funky-town-g756b5d

metro

string

(Only applies when using global control plane). The metro of the instance.

Example: fra

state

string · enum · enum

The current state of the instance.

Enum values:

stopped

starting

running

draining

stopping

template

standby

previous_state

string · enum · enum

The previous state of the instance before the stop operation was invoked.

Enum values:

stopped

starting

running

draining

stopping

template

standby

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No instance with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

SuspendInstanceByUUIDRequestBody

Parameters for suspending the instance.

drain_timeout_ms

integer · uint64

Timeout for draining connections in milliseconds. No draining will occur if set to 0. Use -1 for the largest possible value.

Example: 550

SuspendInstancesRequestItem

A single request item to suspend an instance.

metro

string

(Only applies when using global control plane). The metro to route the request to.

Example: fra

drain_timeout_ms

integer · uint64

Timeout for draining connections in milliseconds. No draining will occur if set to 0. Use -1 for the largest possible value.

Example: 250

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for uuid:

uuid

string · uuid

The UUID of the instance to suspend. Mutually exclusive with name.

Example: 123e4567-e89b-12d3-a456-426614174000

SuspendInstancesResponse

The response message for suspending one or more instance(s) given their UUID(s) or name(s).

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 23

SuspendInstancesResponseData

SuspendInstancesResponseSuspendedInstance[]

The instance(s) which were suspended by the request.

SuspendInstancesResponseSuspendedInstance

uuid

string · uuid

The UUID of the instance.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the instance.

Example: funky-town-g756b5d

metro

string

(Only applies when using global control plane). The metro of the instance.

Example: fra

state

string · enum · enum

The current state of the instance.

Enum values:

stopped

starting

running

draining

stopping

template

standby

previous_state

string · enum · enum

The previous state of the instance before the suspend operation was invoked.

Enum values:

stopped

starting

running

draining

stopping

template

standby

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No instance with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

UpdateCertificateByUUIDRequest

The request message for updating a certificate by its UUID.

chain

string · required

The new certificate chain.

This is the public chain of the certificate in PEM format. The chain should include the certificate and any intermediate certificates.

Example: -----BEGIN CERTIFICATE----- MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDQ... -----END CERTIFICATE-----

pkey

string · required

The new private key.

This is the private key of the certificate in PEM format. The private key must match the public key in the certificate chain.

Example: -----BEGIN PRIVATE KEY----- MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDQ... -----END PRIVATE KEY-----

uuid

string · uuid

The UUID of the certificate to update.

UpdateCertificateRequest

The request message for updating one or more certificate(s) by their UUID(s) or name(s).

object · required

The ID of the certificate to update.

chain

string · required

The new certificate chain.

This is the public chain of the certificate in PEM format. The chain should include the certificate and any intermediate certificates.

Example: -----BEGIN CERTIFICATE----- MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDQ... -----END CERTIFICATE-----

pkey

string · required

The new private key.

This is the private key of the certificate in PEM format. The private key must match the public key in the certificate chain.

Example: -----BEGIN PRIVATE KEY----- MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDQ... -----END PRIVATE KEY-----

UpdateCertificateResponse

The response message for updating one or more certificate(s).

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 45

UpdateCertificateResponseData

Certificate[]

The certificate(s) which were updated by the request.

UpdateInstanceByUUIDRequestBody

prop

string · enum · enum · required

The property to modify.

Enum values:

image

args

env

memory_mb

vcpus

scale_to_zero

tags

delete_lock

Example: memory_mb

op

string · enum · enum · required

The operation to perform on the property.

Enum values:

set

add

del

Example: set

id

string

(Optional). A client-provided identifier for tracking this operation in the response.

Example: op-1

value

The value for the update operation. The type depends on the property and operation:

For "image": string
For "args": string or array of strings
For "env": object (for SET/ADD) or string/array of strings (for DEL)
For "memory_mb": integer
For "vcpus": integer
For "scale_to_zero": object with cooldown_time_ms, policy, and stateful fields
For "tags": array of strings
For "delete_lock": boolean
For "schedules": array of schedule objects (with name, when, action, and optional args fields). Use action "exec" together with args to execute a command at the scheduled time.
For "autokill": object with time_ms and num_requests fields
For "hostname": string (valid DNS label)
For "roms": array of ROM objects (with name and image fields) for SET/ADD, or array of ROM names for DEL
For "dependencies": array of instance identifiers (name or UUID)
For "sched_priority": integer (scheduling priority value)

UpdateInstancesRequestItem

A single update operation to be applied to an instance.

prop

string · enum · enum · required

The property to modify.

Enum values:

image

args

env

memory_mb

vcpus

scale_to_zero

tags

delete_lock

Example: memory_mb

op

string · enum · enum · required

The operation to perform on the property.

Enum values:

set

add

del

Example: set

id

string

(Optional). A client-provided identifier for tracking this operation in the response.

Example: op-1

metro

string

(Only applies when using global control plane). The metro to route the request to.

Example: fra

value

The value for the update operation. The type depends on the property and operation:

For "image": string
For "args": string or array of strings
For "env": object (for SET/ADD) or string/array of strings (for DEL)
For "memory_mb": integer
For "vcpus": integer
For "scale_to_zero": object with cooldown_time_ms, policy, and stateful fields
For "tags": array of strings
For "delete_lock": boolean
For "schedules": array of schedule objects (with name, when, action, and optional args fields). Use action "exec" together with args to execute a command at the scheduled time.
For "autokill": object with time_ms and num_requests fields
For "hostname": string (valid DNS label)
For "roms": array of ROM objects (with name and image fields) for SET/ADD, or array of ROM names for DEL
For "dependencies": array of instance identifiers (name or UUID)
For "sched_priority": integer (scheduling priority value)

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for uuid:

uuid

string · uuid

The UUID of the instance to update. Mutually exclusive with name.

Example: 123e4567-e89b-12d3-a456-426614174000

UpdateInstancesResponse

The response message for updating one or more instances.

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 76

UpdateInstancesResponseData

UpdateInstancesResponseUpdatedInstance[]

List of instances that were processed during the update operation.

UpdateInstancesResponseUpdatedInstance

uuid

string · uuid

The UUID of the instance that was updated.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the instance that was updated.

Example: funky-town-g756b5d

status

string · enum · enum

The status of this particular instance update operation.

Enum values:

success

error

metro

string

(Only applies when using global control plane). The metro of the instance.

Example: fra

id

string

(Optional). The client-provided ID from the request.

Example: op-1

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No instance with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

UpdateServiceGroupByUUIDRequestBody

prop

string · enum · enum · required

The property to modify.

Enum values:

services

domains

soft_limit

hard_limit

autokill

Example: services

op

string · enum · enum · required

The operation to perform.

Enum values:

set

add

del

Example: set

id

string

(Optional). A client-provided identifier for tracking this operation in the response.

Example: op-1

value

The value for the update operation:

For "services": array of Service objects (same as for creation)
For "domains": array of Domain objects (same as for creation)
For "soft_limit": integer (1–65535), must be <= "hard_limit"
For "hard_limit": integer (1–65535), must be >= "soft_limit"
For "autokill": object with time_ms field

UpdateServiceGroupsRequestItem

A single update operation to be applied to a service group

prop

string · enum · enum · required

The property to modify.

Enum values:

services

domains

soft_limit

hard_limit

autokill

Example: services

op

string · enum · enum · required

The operation to perform.

Enum values:

set

add

del

Example: set

id

string

(Optional). A client-provided identifier for tracking this operation in the response.

Example: op-1

value

The value for the update operation:

For "services": array of Service objects (same as for creation)
For "domains": array of Domain objects (same as for creation)
For "soft_limit": integer (1–65535), must be <= "hard_limit"
For "hard_limit": integer (1–65535), must be >= "soft_limit"
For "autokill": object with time_ms field

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for uuid:

uuid

string · uuid

The UUID of the service group to update. Mutually exclusive with name.

Example: 123e4567-e89b-12d3-a456-426614174000

UpdateServiceGroupsResponse

The response message for updating one or more service groups.

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 76

UpdateServiceGroupsResponseData

UpdateServiceGroupsResponseUpdatedServiceGroup[]

List of service groups that were processed during the update operation.

UpdateServiceGroupsResponseUpdatedServiceGroup

uuid

string · uuid

The UUID of the service group that was updated.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the service group that was updated.

Example: funky-town-g756b5d

metro

string

(Only applies when using global control plane). The metro of the service group.

Example: fra

status

string · enum · enum

The status of this particular service group update operation.

Enum values:

success

error

id

string

(Optional). The client-provided ID from the request.

Example: op-1

message

string

An optional message providing additional information about the status. This field is only set when this message object is used as a response message, and is useful when the status is not success.

Example: No service with name 'funky-town-g756b5d'

error

integer · int32

Example: 8

UpdateTemplateInstanceByUUIDRequestBody

prop

string · enum · enum · required

The property to modify.

Enum values:

tags

delete_lock

autokill

Example: tags

op

string · enum · enum · required

The operation to perform on the property.

Enum values:

set

add

del

Example: add

id

string

(Optional). A client-provided identifier for tracking this operation in the response.

Example: op-1

value

The value for the update operation. The type depends on the property and operation:

For "tags": array of strings
For "delete_lock": boolean
For "autokill": object with time_ms field

UpdateTemplateInstancesRequestItem

A single update operation to be applied to a template instance.

prop

string · enum · enum · required

The property to modify.

Enum values:

tags

delete_lock

autokill

Example: tags

op

string · enum · enum · required

The operation to perform on the property.

Enum values:

set

add

del

Example: add

id

string

(Optional). A client-provided identifier for tracking this operation in the response.

Example: op-1

metro

string

(Only applies when using global control plane). The metro of the template instance.

Example: fra

value

The value for the update operation. The type depends on the property and operation:

For "tags": array of strings
For "delete_lock": boolean
For "autokill": object with time_ms field

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for uuid:

uuid

string · uuid

The UUID of the template instance to update. Mutually exclusive with name.

Example: 123e4567-e89b-12d3-a456-426614174000

UpdateTemplateInstancesResponse

The response message for updating a template instance by its UUID.

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 76

UpdateTemplateInstancesResponseData

UpdateTemplateInstancesResponseTemplateInstance[]

List of template instances that were processed during the update operation.

UpdateTemplateInstancesResponseTemplateInstance

uuid

string · uuid

The UUID of the template instance that was updated.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the template instance that was updated.

Example: funky-town-g756b5d

metro

string

(Only applies when using global control plane). The metro of the template instance.

Example: fra

status

string · enum · enum

The status of this particular template instance update operation.

Enum values:

success

error

id

string

(Optional). The client-provided ID from the request.

Example: op-1

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No template instance with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

UpdateTemplateVolumeByUUIDRequestBody

prop

string · enum · enum · required

The property to modify.

Enum values:

tags

delete_lock

Example: tags

op

string · enum · enum · required

The operation to perform.

Enum values:

set

add

del

Example: set

id

string

(Optional). A client-provided identifier for tracking this operation in the response.

Example: op-1

value

The value for the update operation. The type depends on the property and operation:

For "tags": array of Strings
For "delete_lock": boolean

UpdateTemplateVolumesRequestItem

A single update operation to be applied to a template volume.

prop

string · enum · enum · required

The property to modify.

Enum values:

tags

delete_lock

Example: tags

op

string · enum · enum · required

The operation to perform.

Enum values:

set

add

del

Example: add

id

string

(Optional). A client-provided identifier for tracking this operation in the response.

Example: op-1

value

The value for the update operation. The type depends on the property and operation:

For "tags": array of Strings
For "delete_lock": boolean

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for uuid:

uuid

string · uuid

The UUID of the template volume to update. Mutually exclusive with name.

Example: 123e4567-e89b-12d3-a456-426614174000

UpdateTemplateVolumesResponse

The response message for updating one or more template volumes.

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 46

UpdateTemplateVolumesResponseData

UpdateTemplateVolumesResponseTemplateVolume[]

The template volume(s) which were updated by the request.

UpdateTemplateVolumesResponseTemplateVolume

uuid

string · uuid

The UUID of the template volume that was updated.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the template volume that was updated.

Example: funky-town-g756b5d

status

string · enum · enum

The status of this particular volume update operation.

Enum values:

success

error

id

string

(Optional). The client-provided ID from the request.

Example: op-1

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No volume with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

UpdateVolumeByUUIDRequestBody

prop

string · enum · enum · required

The property to modify.

Enum values:

size_mb

tags

quota_policy

delete_lock

Example: size_mb

op

string · enum · enum · required

The operation to perform.

Enum values:

set

add

del

Example: set

id

string

(Optional). A client-provided identifier for tracking this operation in the response.

Example: op-1

value

The value for the update operation. The type depends on the property and operation:

For "size_mb": unsigned integer
For "quota_policy": "static" or "dynamic"
For "tags": array of Strings
For "delete_lock": boolean

UpdateVolumesRequestItem

A single request item for updating a volume.

prop

string · enum · enum · required

The property to modify.

Enum values:

size_mb

tags

quota_policy

delete_lock

Example: size_mb

op

string · enum · enum · required

The operation to perform.

Enum values:

set

add

del

Example: set

id

string

(Optional). A client-provided identifier for tracking this operation in the response.

Example: op-1

value

The value for the update operation. The type depends on the property and operation:

For "size_mb": unsigned integer
For "quota_policy": "static" or "dynamic"
For "tags": array of Strings
For "delete_lock": boolean

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for uuid:

uuid

string · uuid

The UUID of the volume to update. Mutually exclusive with name.

Example: 123e4567-e89b-12d3-a456-426614174000

UpdateVolumesResponse

The response message for updating one or more volume(s).

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 76

UpdateVolumesResponseData

UpdateVolumesResponseUpdatedVolume[]

List of volumes that were processed during the update operation.

UpdateVolumesResponseUpdatedVolume

uuid

string · uuid

The UUID of the volume that was updated.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the volume that was updated.

Example: funky-town-g756b5d

metro

string

(Only applies when using global control plane). The metro of the volume.

Example: fra

status

string · enum · enum

The status of this particular volume update operation.

Enum values:

success

error

id

string

(Optional). The client-provided ID from the request.

Example: op-1

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No volume with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

Volume

A volume represents a storage device that can be attached to an instance.

uuid

string · uuid

The UUID of the volume.

Example: c1d2e3f4-5678-90ab-cdef-1234567890ab

name

string

The name of the volume.

This is a human-readable name that can be used to identify the volume. The name must be unique within the context of your account. The name can also be used to identify the volume in API calls.

Example: funky-town-g7gum5cj

metro

string

(Only applies when using global control plane). Where the volume is located.

Example: fra

created_at

string · date-time

The time the volume was created.

Example: 2021-01-01T00:00:00Z

state

string · enum · enum

Current state of the volume.

Enum values:

uninitialized

initializing

available

idle

mounted

busy

error

template

size_mb

integer · uint64

The size of the volume in megabytes.

Example: 64

persistent

boolean

Indicates if the volume will stay alive when the last instance is deleted that this volume is attached to.

Example: true

VolumeInstanceID[]

List of instances that this volume is attached to.

VolumeInstanceMount[]

List of instances that have this volume mounted. This does not apply to template volumes.

tags

string[]

The tags associated with the volume. Maximum 16 tags are allowed, and each tag may not be longer than 256 characters.

status

string · enum · enum

An optional field representing the status of the request. This field is only set when this message object is used as a response message.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is only set when this message object is used as a response message, and is useful when the status is not success.

Example: No volume with name 'funky-town-g756b5d'

error

integer · int32

Example: 8

quota_policy

string · enum · enum

Either static or dynamic reservation.

Enum values:

static

dynamic

Example: static

delete_lock

boolean

If set to true, the volume cannot be deleted.

Example: false

free_mb

integer · uint32

The amount of free space in the volume in megabytes.

Example: 32

filesystem

string

The filesystem type of this volume. Without custom configuration, this is either ext4 or virtiofs.

Example: ext4

host_path

string

Host path backing this managed volume. This field is only available for managed volumes and users with appropriate permissions.

Example: /usr/lib/unikraft/volumes/my-vol

object

Optional script arguments that were applied to the custom volume filesystem initialization scripts.

Example: {"arg1":"value1","arg2":"value2"}

VolumeInstanceID

Reference to the instance to attach the volume to.

uuid

string · uuid

The UUID of the instance that the volume is attached to.

Example: c1d2e3f4-5678-90ab-cdef-1234567890ab

name

string

The name of the instance that the volume is attached to.

Example: funky-town-g7gum5cj

VolumeInstanceMount

uuid

string · uuid

The UUID of the instance that the volume is mounted in.

Example: funky-town-g7gum5cj

name

string

The name of the instance that the volume is mounted in.

Example: funky-town-g7gum5cj

readonly

boolean

Whether the volume is mounted read-only or read-write.

Example: true

WaitInstanceByUUIDRequestBody

Wait parameters.

state

string · enum · enum

The desired state to wait for. Default is running.

Enum values:

stopped

starting

running

draining

stopping

template

standby

timeout_ms

integer · int64

Timeout in milliseconds to wait for the instance to reach the desired state. If the timeout is reached, the request will fail with an error. A value of -1 means to wait indefinitely until the instance reaches the desired state.

Example: 450

WaitInstancesRequestItem

A single wait operation to be applied to an instance.

state

string · enum · enum

The desired state to wait for. Default is running.

Enum values:

stopped

starting

running

draining

stopping

template

standby

timeout_ms

integer · int64

Example: 450

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for uuid:

uuid

string · uuid

The UUID of the instance to wait for. Mutually exclusive with name.

Example: 123e4567-e89b-12d3-a456-426614174000

WaitInstancesResponse

The response message for waiting for one or more instance(s) to reach a certain state given their UUID(s) or name(s).

status

string · enum · enum

The status of the response.

Enum values:

success

error

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: Failed to perform all operations

object

The response data for this request.

ResponseError[]

A list of errors which may have occurred during the request.

op_time_us

integer · uint64

The operation time in microseconds. This is the time it took to process the request and generate the response.

Example: 450

WaitInstancesResponseData

WaitInstancesResponseWaitedInstance[]

The instance(s) which this requested waited on.

WaitInstancesResponseWaitedInstance

uuid

string · uuid

The UUID of the instance.

Example: 123e4567-e89b-12d3-a456-426614174000

name

string

The name of the instance.

Example: funky-town-g756b5d

state

string · enum · enum

The current state of the instance.

Enum values:

stopped

starting

running

draining

stopping

template

standby

message

string

An optional message providing additional information about the status. This field is useful when the status is not success.

Example: No instance with name 'funky-town-g756b5d'

error

integer · int32

An optional error code providing additional information about the status. This field is useful when the status is not success.

Example: 8

status

string · enum · enum

The status of the response.

Enum values:

success

error