An instance is a micro vm running an application.
List Instances
Get one or many instances with their current status and configuration. It's possible to filter this list by ID(s) (name or UUID).
query Parameters
uuidThe UUID of the resource.
nameThe name of the resource.
detailsWhether to include details about the instance in the response. By default this is set to true, meaning that all information about the instance will be included in the response. If set to false, only the basic information about the instance will be included, such as its name and UUID.
countThe maximum number of instances to return. If set to 0 or not set, all instances matching filters will be returned. When filtering by IDs, this should not be set.
fromIf set, the listing starts from the instance with the given UUID or at the given ISO8601 creation timestamp (inclusive). When count is 0 or not set, a UUID value may be used to match a specific instance by UUID.
tagsA list of tags to filter the instances by.
orderThe sort order for the returned instances.
Valid values are PAGINATION_ORDER_ASC (ascending, oldest first) and
PAGINATION_ORDER_DESC (descending, newest first). Defaults to
PAGINATION_ORDER_ASC.
The sort order used by list endpoints.
sortbyThe field to sort the instances by.
Currently only PAGINATION_SORT_BY_CREATE_TIME is supported. Defaults to
PAGINATION_SORT_BY_CREATE_TIME.
The sort field used by list endpoints.
List Instances › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidThe UUID of the resource.
List Instances › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Create Instance
Create an instance in Unikraft Cloud.
Create Instance › Request Body
name(Optional). The name of the instance.
If not provided, a random name will be generated. The name must be unique.
(Optional). The image to use for the instance.
Either an image or a template must be specified.
args(Optional). The arguments to pass to the instance when it starts.
(Optional). Environment variables to set for the instance.
memory_mb(Optional). Memory in MB to allocate for the instance. Default is 128.
(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.
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.
autostartWhether the instance should start automatically on creation.
Must be set to true when timeout_s is specified.
replicas(Optional). Number of additional replicas to create. The total
number of instances created is replicas + 1. Defaults to 0.
restart_policyRestart 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.
Scale-to-zero configuration for the instance. Requires
service_group to be set. Cannot be combined with the
delete-on-stop feature.
vcpus(Optional). Number of vCPUs to allocate for the instance. Defaults to 1.
wait_timeout_msDeprecated: 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.
featuresFeatures 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.
timeout_sTimeout 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.
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.
(Optional). Plugins to attach to the instance. Plugins let you attach
small helper programs to an instance and reach each one over a direct,
authenticated HTTP endpoint. Each plugin loads from its own ROM image,
mounts at /uk/plugins/<plugin_name>, and is reachable at
.../v1/instances/<uuid>/plugins/<plugin_name>/<path>. At most 8 plugins
may be attached to an instance.
tags(Optional). Tags to associate with the instance.
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_priorityThe scheduling priority for the instance. Only settable by users with scheduling priority override permissions.
(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.
(Optional). Automatic delete-on-idle/request-limit configuration. Not used for template instances.
hostname(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.
(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.
(Optional). Reference to an existing instance to branch from.
The instance can be running, stopped, or a template. If the source
instance is running, a snapshot will be taken asynchronously and the
new instance will wait for it to complete before starting.
Mutually exclusive with image and template.
(Optional). Reference to an existing checkpoint to create the instance
from. The checkpoint must be in the checkpoint state. The new instance
will be created with the same configuration and state as the checkpoint.
Mutually exclusive with image, template, and branch_from.
gatewayThe default gateway to configure inside the guest.
nameserverThe DNS resolver to configure inside the guest.
A list of one to four interfaces to attach
Create Instance › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Delete Instances
Delete the specified instance(s) by ID(s) (name or UUID). After this call the IDs of the instances are no longer valid. If the instances are currently running, they are force-stopped.
Delete Instances › Request Body
timeout_sTimeout in seconds to wait for the instance to be deleted. No wait performed for a value of 0.
dont_retainDelete immediately without retention. If the instance is already being retained, this will force its deletion. Ignored if retention for instances is not configured.
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidMutually exclusive with name.
Delete Instances › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Update Instances
Update (modify) one or more instances by ID(s) (name or UUID). The instances must be in a stopped state for most update operations.
Update Instances › Request Body
propThe property to modify.
opThe operation to perform on the property.
id(Optional). A client-provided identifier for tracking this operation in the response.
valueThe value for the update operation. The type depends on the property and operation:
- For "image": object with image url, credentials, headers and pull policy
- 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) for SET/ADD, or array of schedule names for DEL. 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 "plugins": array of plugin objects (with name, rom, and optional config fields) for SET/ADD
- For "dependencies": array of instance identifiers (name or UUID)
- For "sched_priority": SchedPriority enum value ("normal", "medium", "high", "admin")
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object | |
| type = object |
uuidThe UUID of the instance to update. Mutually exclusive with name.
Update Instances › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
List checkpoint instances
Get one or more checkpoint instances by their UUID(s) or name(s).
query Parameters
uuidThe UUID of the resource.
nameThe name of the resource.
detailsWhether to include details about the checkpoints in the response. By default this is set to true, meaning that all information about the checkpoints will be included in the response. If set to false, only the basic information about the checkpoints will be included, such as their name and UUID.
countThe maximum number of checkpoint instances to return. If set to 0 or not set, all the checkpoint instances matching filters will be returned. When filtering by IDs, this should not be set.
tagsA list of tags to filter the checkpoint instances by.
fromIf set, the listing starts from the checkpoint with the given UUID or at the given ISO8601 creation timestamp (inclusive). When count is 0 or not set, a UUID value may be used to match a specific checkpoint by UUID.
orderThe sort order for the returned checkpoint instances.
Valid values are PAGINATION_ORDER_ASC (ascending, oldest first) and
PAGINATION_ORDER_DESC (descending, newest first). Defaults to
PAGINATION_ORDER_ASC.
The sort order used by list endpoints.
sortbyThe field to sort the checkpoint instances by.
Currently only PAGINATION_SORT_BY_CREATE_TIME is supported. Defaults to
PAGINATION_SORT_BY_CREATE_TIME.
The sort field used by list endpoints.
List checkpoint instances › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidThe UUID of the resource.
List checkpoint instances › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Create checkpoint instances
Create a checkpoint from an existing instance. A checkpoint captures the state of an instance at a specific point in time. Checkpoints can be created from running, stopped, or standby instances.
Create checkpoint instances › Request Body
The source instance to create a checkpoint from (by name or UUID).
name(Optional). The name of the checkpoint. If not provided, a name will be generated.
timeout_sTimeout in seconds to wait for the checkpoint to be created. No wait performed for a value of 0.
Create checkpoint instances › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Delete checkpoint instances
Delete the specified checkpoint instance(s) by ID(s) (name or UUID). After this call the IDs of the checkpoint instances are no longer valid.
Delete checkpoint instances › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidThe UUID of the resource.
Delete checkpoint instances › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Update checkpoint instances
Update (modify) one or more checkpoint instances by ID(s) (name or UUID).
Update checkpoint instances › Request Body
propThe property to modify.
opThe operation to perform on the property.
id(Optional). A client-provided identifier for tracking this operation in the response.
valueThe 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
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object | |
| type = object |
uuidThe UUID of the checkpoint instance to update. Mutually exclusive with name.
Update checkpoint instances › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Get checkpoint history
Get the checkpoint history of one or more checkpoint instances. Returns the ordered list of checkpoints in each checkpoint's history.
query Parameters
uuidThe UUID of the resource.
nameThe name of the resource.
Get checkpoint history › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidThe UUID of the resource.
Get checkpoint history › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Get checkpoint instance by UUID
Get a single checkpoint instance by its UUID.
path Parameters
uuidThe UUID of the checkpoint instance to retrieve.
query Parameters
detailsWhether to include details about the checkpoint in the response. By default this is set to true, meaning that all information about the checkpoint will be included in the response. If set to false, only the basic information about the checkpoint will be included, such as its name and UUID.
Get checkpoint instance by UUID › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Delete checkpoint instance by UUID
Delete a specified checkpoint instance by its UUID. After this call the UUID of the checkpoint instance is no longer valid.
path Parameters
uuidThe UUID of the checkpoint instance to delete.
Delete checkpoint instance by UUID › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Update checkpoint instance by UUID
Update (modify) a checkpoint instance by its UUID.
path Parameters
uuidThe UUID of the checkpoint instance to update.
Update checkpoint instance by UUID › Request Body
propThe property to modify.
opThe operation to perform on the property.
id(Optional). A client-provided identifier for tracking this operation in the response.
valueThe 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
Update checkpoint instance by UUID › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Get checkpoint history by UUID
Get the checkpoint history of a checkpoint instance by its UUID. Returns the ordered list of checkpoints in the checkpoint's history.
path Parameters
uuidThe UUID of the instance or checkpoint to retrieve history for.
Get checkpoint history by UUID › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Get instances checkpoint history
Get the checkpoint history of one or more instances. Returns the ordered list of checkpoints associated with each instance.
query Parameters
uuidThe UUID of the resource.
nameThe name of the resource.
Get instances checkpoint history › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidThe UUID of the resource.
Get instances checkpoint history › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Get Instances Logs
Retrieve the logs of one or more instances by ID(s) (name or UUID).
query Parameters
uuidThe UUID of the instance to retrieve logs for. Mutually exclusive with name.
nameThe name of the instance to retrieve logs for. Mutually exclusive with UUID.
offsetThe byte offset of the log output to receive. A negative sign makes the offset relative to the end of the log.
limitThe amount of bytes to return at most.
Get Instances Logs › Request Body
offsetThe byte offset of the log output to receive. A negative sign makes the offset relative to the end of the log.
limitThe amount of bytes to return at most.
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object | |
| type = object |
uuidThe UUID of the instance to retrieve logs for. Mutually exclusive with name.
Get Instances Logs › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Get Instances Metrics
Get the metrics of one or more instances by their ID(s) (name or UUID).
query Parameters
uuidThe UUID of the resource.
nameThe name of the resource.
Get Instances Metrics › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidThe UUID of the resource.
Get Instances Metrics › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Start Instances
Start previously stopped instances by ID(s) (name or UUID) or do nothing if the instances are already running.
Start Instances › Request Body
wait_timeout_msDeprecated: 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.
timeout_sTimeout 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.
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object | |
| type = object |
uuidThe UUID of the instance to start. Mutually exclusive with name.
Start Instances › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Stop Instances
Stop one or more running instance by ID(s) (name or UUID) or do nothing if the instances are already stopped.
Stop Instances › Request Body
forceWhether to immediately force stop the instance.
drain_timeout_msTimeout 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.
quickWhether to perform a quick shutdown. This flag is overridden by force.
ifstateOnly stop the instance if it is in this state.
dumpIf set, forces the VMM to shutdown immediately and generate a coredump. Can only be used in conjunction with force.
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object | |
| type = object |
uuidThe UUID of the instance to stop. Mutually exclusive with name.
Stop Instances › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Suspend Instances
Suspend one or more running instances by ID(s) (name or UUID) or do nothing if the instances are already suspended.
Suspend Instances › Request Body
drain_timeout_msTimeout for draining connections in milliseconds. No draining will occur if set to 0. Use -1 for the largest possible value.
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object | |
| type = object |
uuidThe UUID of the instance to suspend. Mutually exclusive with name.
Suspend Instances › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
List template instances
Get one or more template instances by their UUID(s) or name(s).
query Parameters
uuidThe UUID of the resource.
nameThe name of the resource.
detailsWhether to include details about the templates in the response. By default this is set to true, meaning that all information about the templates will be included in the response. If set to false, only the basic information about the templates will be included, such as their name and UUID.
countThe maximum number of template instances to return. If set to 0 or not set, all the template instances matching filters will be returned. When filtering by IDs, this should not be set.
tagsA list of tags to filter the template instances by.
fromIf set, the listing starts from the template with the given UUID or at the given ISO8601 creation timestamp (inclusive). When count is 0 or not set, a UUID value may be used to match a specific template by UUID.
orderThe sort order for the returned template instances.
Valid values are PAGINATION_ORDER_ASC (ascending, oldest first) and
PAGINATION_ORDER_DESC (descending, newest first). Defaults to
PAGINATION_ORDER_ASC.
The sort order used by list endpoints.
sortbyThe field to sort the template instances by.
Currently only PAGINATION_SORT_BY_CREATE_TIME is supported. Defaults to
PAGINATION_SORT_BY_CREATE_TIME.
The sort field used by list endpoints.
List template instances › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidThe UUID of the resource.
List template instances › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Create template instances from Instances
Convert one or more existing instances by their UUID(s) or name(s) into template instances that can be used to create new instances.
The existing instances must be in the stopped state and not have existing
snapshots.
Create template instances from Instances › Request Body
timeout_sTimeout in seconds to wait for the template instances to be created. A value of -1 means to wait indefinitely until the instance reaches the desired state. No wait performed for a value of 0.
(Optional). Automatic delete-on-idle configuration for the new template.
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object | |
| type = object |
uuidThe UUID of the instance to convert into template. Mutually exclusive with name.
Create template instances from Instances › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Delete template instances
Delete the specified template instance(s) by ID(s) (name or UUID). After this call the IDs of the template instances are no longer valid.
Delete template instances › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidThe UUID of the resource.
Delete template instances › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Update template instances
Update (modify) one or more template instances by ID(s) (name or UUID).
Update template instances › Request Body
propThe property to modify.
opThe operation to perform on the property.
id(Optional). A client-provided identifier for tracking this operation in the response.
valueThe 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
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object | |
| type = object |
uuidThe UUID of the template instance to update. Mutually exclusive with name.
Update template instances › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Get template instance by UUID
Get a single template instance by its UUID.
path Parameters
uuidThe UUID of the template instance to retrieve.
query Parameters
detailsWhether to include details about the templates in the response. By default this is set to true, meaning that all information about the templates will be included in the response. If set to false, only the basic information about the templates will be included, such as their name and UUID.
Get template instance by UUID › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Delete template instance by UUID
Delete a specified template instance by its UUID. After this call the UUID of the template instance is no longer valid.
path Parameters
uuidThe UUID of the template instance to delete.
Delete template instance by UUID › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Update template instance by UUID
Update (modify) a template instance by its UUID.
path Parameters
uuidThe UUID of the template instance to update.
Update template instance by UUID › Request Body
propThe property to modify.
opThe operation to perform on the property.
id(Optional). A client-provided identifier for tracking this operation in the response.
valueThe 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
Update template instance by UUID › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Wait for Instances States
Wait for one or more instances to reach certain states by ID(s) (name or UUID).
If the instances are already in the desired states, the request will return immediately. If the instances are not in the desired state, the request will block until the instances reach the desired state or the timeout is reached. If the timeout is reached, the request will fail with an error. If the timeout is -1, the request will block indefinitely until the instances reach the desired states.
query Parameters
uuidThe UUID of the instance to wait for. Mutually exclusive with name.
nameThe name of the instance to wait for. Mutually exclusive with UUID.
stateThe desired state to wait for. Default is running.
timeout_msDeprecated: Use timeout_s instead. Timeout in milliseconds to
wait for the instance to reach the desired state. If timeout_s is
not set, this value is converted by rounding up to the next full
second. A value of -1 means to wait indefinitely.
timeout_sTimeout in seconds 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. No wait performed for a value of 0.
Wait for Instances States › Request Body
stateThe desired state to wait for. Default is running.
timeout_msDeprecated: Use timeout_s instead. Timeout in milliseconds to
wait for the instance to reach the desired state. If timeout_s is
not set, this value is converted by rounding up to the next full
second. A value of -1 means to wait indefinitely.
timeout_sTimeout in seconds 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. No wait performed for a value of 0.
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object | |
| type = object |
uuidThe UUID of the instance to wait for. Mutually exclusive with name.
Wait for Instances States › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Get Instance by UUID
Get a single instance by its UUID.
path Parameters
uuidThe UUID of the instance to get.
query Parameters
detailsWhether to include details about the instance in the response. By default this is set to true, meaning that all information about the instance will be included in the response. If set to false, only the basic information about the instance will be included, such as its name and UUID.
Get Instance by UUID › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Delete Instance by UUID
Delete a specified instance by its UUID. After this call the UUID of the instance is no longer valid. If the instance is currently running, it is force-stopped.
path Parameters
uuidThe UUID of the instance to delete.
Delete Instance by UUID › Request Body
timeout_sTimeout in seconds to wait for the instance to be deleted. No wait performed for a value of 0.
dont_retainDelete immediately without retention. If the instance is already being retained, this will force its deletion. Ignored if retention for instances is not configured.
Delete Instance by UUID › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Update Instance by UUID
Update (modify) an instance by its UUID. The instance must be in a stopped state for most update operations.
path Parameters
uuidThe UUID of the instance to update.
Update Instance by UUID › Request Body
propThe property to modify.
opThe operation to perform on the property.
id(Optional). A client-provided identifier for tracking this operation in the response.
valueThe value for the update operation. The type depends on the property and operation:
- For "image": object with image url, credentials, headers and pull policy
- 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) for SET/ADD, or array of schedule names for DEL. 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 "plugins": array of plugin objects (with name, rom, and optional config fields) for SET/ADD
- For "dependencies": array of instance identifiers (name or UUID)
- For "sched_priority": SchedPriority enum value ("normal", "medium", "high", "admin")
Update Instance by UUID › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Get instance checkpoint history by UUID
Get the checkpoint history of an instance by its UUID. Returns the ordered list of checkpoints associated with the instance.
path Parameters
uuidThe UUID of the instance or checkpoint to retrieve history for.
Get instance checkpoint history by UUID › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Get Instance Logs by UUID
Retrieve the logs of an instance by its UUID.
path Parameters
uuidThe UUID of the instance to retrieve logs for.
Get Instance Logs by UUID › Request Body
offsetThe byte offset of the log output to receive. A negative sign makes the offset relative to the end of the log.
limitThe amount of bytes to return at most.
Get Instance Logs by UUID › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Get Instance Metrics by UUID
Get the metrics of an instance by its UUID.
path Parameters
uuidThe UUID of the instance to retrieve metrics for.
Get Instance Metrics by UUID › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Start Instance by UUID
Start a previously stopped instance by its UUID or do nothing if the instance is already running.
path Parameters
uuidThe UUID of the instance to start.
Start Instance by UUID › Request Body
wait_timeout_msDeprecated: 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.
timeout_sTimeout 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.
Start Instance by UUID › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Stop Instance by UUID
Stop a running instance by its UUID or do nothing if the instance is already stopped.
path Parameters
uuidThe UUID of the instance to stop.
Stop Instance by UUID › Request Body
forceWhether to immediately force stop the instance.
drain_timeout_msTimeout 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.
quickWhether to perform a quick shutdown. This flag is overridden by force.
ifstateOnly stop the instance if it is in this state.
dumpIf set, forces the VMM to shutdown immediately and generate a coredump. Can only be used in conjunction with force.
Stop Instance by UUID › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Suspend Instance by UUID
Suspend a running instance by its UUID or do nothing if the instance is already suspended.
path Parameters
uuidThe UUID of the instance to suspend.
Suspend Instance by UUID › Request Body
drain_timeout_msTimeout for draining connections in milliseconds. No draining will occur if set to 0. Use -1 for the largest possible value.
Suspend Instance by UUID › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
Wait for Instance State by UUID
Wait for an instance to reach a certain state, by its UUID.
If the instance is already in the desired state, the request will return immediately. If the instance is not in the desired state, the request will block until the instance reaches the desired state or the timeout is reached. If the timeout is reached, the request will fail with an error. If the timeout is -1, the request will block indefinitely until the instance reaches the desired state.
path Parameters
uuidThe UUID of the instance to wait for.
Wait for Instance State by UUID › Request Body
stateThe desired state to wait for. Default is running.
timeout_msDeprecated: Use timeout_s instead. Timeout in milliseconds to
wait for the instance to reach the desired state. If timeout_s is
not set, this value is converted by rounding up to the next full
second. A value of -1 means to wait indefinitely.
timeout_sTimeout in seconds 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. No wait performed for a value of 0.
Wait for Instance State by UUID › Responses
default
statusThe status of the response.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.