Unikraft Cloud Platform API

Instances

Endpoint

An instance is a unikernel virtual machine running an application.

List Instances

GET

https://api.fra.unikraft.cloud

/v1/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).

List Instances › query Parameters

detailsboolean
Whether 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.

List Instances › Request Body

oneOf

Exactly one variant must match.

Decision Table

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

Properties for uuid:

uuidstring · uuid · required
Mutually exclusive with name.
Example: 123e4567-e89b-12d3-a456-426614174000

List Instances › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
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
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 432

Create Instance

POST

https://api.fra.unikraft.cloud

/v1/instances

Create an instance in Unikraft Cloud.

Create Instance › Request Body

imagestring · required
The image to use for the instance.
Example: nginx:latest

namestring
(Optional). The name of the instance.

If not provided, a random name will be generated. The name must be unique.
Example: funky-town-g756b5d
argsstring[]
(Optional). The arguments to pass to the instance when it starts.
Example: --port=8080 --debug
envobject
(Optional). Environment variables to set for the instance.
Example: {"ENV_VAR1":"value1","ENV_VAR2":"value2"}
memory_mbinteger · int64
(Optional). Memory in MB to allocate for the instance. Default is 128.
Example: 256
service_groupobject
(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.
volumesobject[]
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.
autostartboolean
Whether the instance should start automatically on creation.
Example: true
replicasinteger · int64
Number of replicas for the instance.
Example: 5
restart_policystring · enum · enum
Restart policy for the instance. This defines how the instance should behave when it stops or crashes.
Enum values:
never
always
on_failure
scale_to_zeroobject
Scale-to-zero configuration for the instance.
vcpusinteger · int32
Number of vCPUs to allocate for the instance.
Example: 1
wait_timeout_msinteger · int64
Timeout to wait for all new instances to reach running state in milliseconds. 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: 2000
featuresstring[]
Features to enable for the instance. Features are specific configurations or capabilities that can be enabled for the instance.
Enum values:
delete_on_stop

Create Instance › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
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
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 875

Delete Instances

DELETE

https://api.fra.unikraft.cloud

/v1/instances

Delete the specified instance(s) by ID(s) (name or UUID). After this call the name of the instances are no longer valid. If the instances are currently running, they are force-stopped.

Delete Instances › Request Body

oneOf

Exactly one variant must match.

Decision Table

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

Properties for uuid:

uuidstring · uuid · required
Mutually exclusive with name.
Example: 123e4567-e89b-12d3-a456-426614174000

Delete Instances › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
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
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 221

Update Instances

PATCH

https://api.fra.unikraft.cloud

/v1/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

propstring · enum · enum · required
The property to modify.
Enum values:
image
args
env
memory_mb
vcpus
scale_to_zero
tags
delete_lock
Example: memory_mb
opstring · enum · enum · required
The operation to perform on the property.
Enum values:
set
add
del
Example: set

idstring
(Optional). A client-provided identifier for tracking this operation in the response.
Example: op-1
uuidstring · uuid
The UUID of the instance to update. Mutually exclusive with name.
Example: 123e4567-e89b-12d3-a456-426614174000
namestring
The name of the instance to update. Mutually exclusive with UUID.
Example: funky-town-g756b5d
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

Update Instances › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
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
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 76

Get Instances Logs

GET

https://api.fra.unikraft.cloud

/v1/instances/log

Retrieve the logs of one or more instances by ID(s) (name or UUID).

Get Instances Logs › Request Body

uuidstring · uuid · required
The UUID of the instance to retrieve logs for. Mutually exclusive with name.
Example: 123e4567-e89b-12d3-a456-426614174000
namestring · required
The name of the instance to retrieve logs for. Mutually exclusive with UUID.
Example: funky-town-g756b5d

offsetinteger · uint64
The byte offset of the log output to receive. A negative sign makes the offset relative to the end of the log.
Example: 450
limitinteger · int64
The amount of bytes to return at most.
Example: 3000

Get Instances Logs › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
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
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 47

Get Instances Metrics

GET

https://api.fra.unikraft.cloud

/v1/instances/metrics

Get the metrics of an instance by its UUID or name.

Get Instances Metrics › query Parameters

uuidstring
Mutually exclusive with name.
namestring
Mutually exclusive with UUID.

Get Instances Metrics › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
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
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 76

Start Instances

PUT

https://api.fra.unikraft.cloud

/v1/instances/start

Start previously stopped instances by ID(s) (name or UUID) or do nothing if the instances are already running.

Start Instances › Request Body

oneOf

Exactly one variant must match.

Decision Table

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

Properties for uuid:

uuidstring · uuid · required
Mutually exclusive with name.
Example: 123e4567-e89b-12d3-a456-426614174000

Start Instances › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
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
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 256

Stop Instances

PUT

https://api.fra.unikraft.cloud

/v1/instances/stop

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

uuidstring · uuid · required
The UUID of the instance to stop. Mutually exclusive with name.
Example: 123e4567-e89b-12d3-a456-426614174000
namestring · required
The name of the instance to stop. Mutually exclusive with UUID.
Example: funky-town-g756b5d

forceboolean
Whether to immediately force stop the instance.
Example: false
drain_timeout_msinteger · 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

Stop Instances › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
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
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 23

Wait for Instances States

GET

https://api.fra.unikraft.cloud

/v1/instances/wait

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 › query Parameters

statestring · enum · enum
The desired state to wait for. Default is running.
Enum values:
stopped
starting
running
draining
stopping
standby
timeout_msinteger · 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.

Wait for Instances States › Request Body

oneOf

Exactly one variant must match.

Decision Table

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

Properties for uuid:

uuidstring · uuid · required
Mutually exclusive with name.
Example: 123e4567-e89b-12d3-a456-426614174000

Wait for Instances States › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
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
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 450

Get Instance by UUID

GET

https://api.fra.unikraft.cloud

/v1/instances/{uuid}

Get a single instance by its UUID.

Get Instance by UUID › path Parameters

uuidstring · uuid · required
The UUID of the instance to get.

Get Instance by UUID › query Parameters

detailsboolean
Whether 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

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
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
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 432

Delete Instance by UUID

DELETE

https://api.fra.unikraft.cloud

/v1/instances/{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.

Delete Instance by UUID › path Parameters

uuidstring · uuid · required
The UUID of the instance to delete.

Delete Instance by UUID › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
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
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 221

Update Instance by UUID

PATCH

https://api.fra.unikraft.cloud

/v1/instances/{uuid}

Update (modify) an instance by its UUID. The instance must be in a stopped state for most update operations.

Update Instance by UUID › path Parameters

uuidstring · uuid · required
The UUID of the instance to update.
Example: 123e4567-e89b-12d3-a456-426614174000

Update Instance by UUID › Request Body

propstring · enum · enum · required
The property to modify.
Enum values:
image
args
env
memory_mb
vcpus
scale_to_zero
tags
delete_lock
Example: memory_mb
opstring · enum · enum · required
The operation to perform on the property.
Enum values:
set
add
del
Example: set

idstring
(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

Update Instance by UUID › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
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
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 76

Get Instance Logs by UUID

GET

https://api.fra.unikraft.cloud

/v1/instances/{uuid}/log

Retrieve the logs of an instance by its UUID.

Get Instance Logs by UUID › path Parameters

uuidstring · uuid · required
The UUID of the instance to retrieve logs for.
Example: 123e4567-e89b-12d3-a456-426614174000

Get Instance Logs by UUID › Request Body

offsetinteger · uint64
The byte offset of the log output to receive. A negative sign makes the offset relative to the end of the log.
Example: 56000
limitinteger · int64
The amount of bytes to return at most.
Example: 1500

Get Instance Logs by UUID › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
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
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 47

Get Instance Metrics by UUID

GET

https://api.fra.unikraft.cloud

/v1/instances/{uuid}/metrics

Get the metrics of an instance by its UUID.

Get Instance Metrics by UUID › path Parameters

uuidstring · uuid · required
The UUID of the instance to retrieve metrics for.

Get Instance Metrics by UUID › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
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
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 76

Start Instance by UUID

PUT

https://api.fra.unikraft.cloud

/v1/instances/{uuid}/start

Start a previously stopped instance by its UUID or do nothing if the instance is already running.

Start Instance by UUID › path Parameters

uuidstring · uuid · required
The UUID of the instance to start.

Start Instance by UUID › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
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
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 256

Stop Instance by UUID

PUT

https://api.fra.unikraft.cloud

/v1/instances/{uuid}/stop

Stop a running instance by its UUID or do nothing if the instance is already stopped.

Stop Instance by UUID › path Parameters

uuidstring · uuid · required
The UUID of the instance to stop.

Stop Instance by UUID › query Parameters

forceboolean
Whether to immediately force stop the instance.
drain_timeout_msinteger · 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.

Stop Instance by UUID › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
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
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 23

Wait for Instance State by UUID

GET

https://api.fra.unikraft.cloud

/v1/instances/{uuid}/wait

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.

Wait for Instance State by UUID › path Parameters

uuidstring · uuid · required
The UUID of the instance to wait for.
Example: 123e4567-e89b-12d3-a456-426614174000

Wait for Instance State by UUID › Request Body

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object

Properties for timeout_ms:

timeout_msinteger · 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

Wait for Instance State by UUID › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
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
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 450

Images ServiceGroups