An instance is a unikernel virtual machine 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
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.
sortbyThe field to sort the instances by.
Currently only PAGINATION_SORT_BY_CREATE_TIME is supported. Defaults to
PAGINATION_SORT_BY_CREATE_TIME.
List Instances › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidMutually exclusive with name.
List Instances › Responses
default
statusThe status of 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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
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.
imageThe image to use for the instance.
metro(Only applies when using global control plane). The metro to route the request to.
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.
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_priority(Optional). The scheduling priority for the instance. Higher values indicate higher priority.
(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.
Create Instance › Responses
default
statusThe status of 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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
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
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.
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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
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
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.
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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Get Instances Logs
Retrieve the logs of one or more instances by ID(s) (name or UUID).
Get Instances Logs › Request Body
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.
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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Get Instances Metrics
Get the metrics of one or more instances by their ID(s) (name or UUID).
Get Instances Metrics › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidMutually exclusive with name.
Get Instances Metrics › Responses
default
statusThe status of 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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
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
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.
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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
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
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.
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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
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
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.
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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
List template instances
Get one or more template instances by their UUID(s) or name(s).
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.
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.
sortbyThe field to sort the template instances by.
Currently only PAGINATION_SORT_BY_CREATE_TIME is supported. Defaults to
PAGINATION_SORT_BY_CREATE_TIME.
List template instances › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidMutually exclusive with name.
List template instances › Responses
default
statusThe status of 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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
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
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidMutually exclusive with name.
Create template instances from Instances › Responses
default
statusThe status of 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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
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 |
uuidMutually exclusive with name.
Delete template instances › Responses
default
statusThe status of 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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Update template instances
Update (modify) one or more template instances by ID(s) (name or UUID).
Update template instances › Request Body
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.
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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
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.
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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
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.
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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
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.
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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
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.
Wait for Instances States › Request Body
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.
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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
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.
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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
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.
Delete Instance by UUID › Responses
default
statusThe status of 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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
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": 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)
Update Instance by UUID › Responses
default
statusThe status of 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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
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.
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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
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.
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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
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.
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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
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.
Stop Instance by UUID › Responses
default
statusThe status of 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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
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.
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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
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_msTimeout 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.
Wait for Instance State by UUID › Responses
default
statusThe status of 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.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.