Zudoku
Unikraft Cloud Platform API

Volumes

Server

Initrd (initial ramdisk) and actual volumes serve different purposes. An initrd is a file system loaded into memory during the boot process of the instance. Any new files created as well as any modifications made to files in the initrd are lost when the instance is stopped. In contrast, a volume is a persistent storage device that keeps data across restarts. In addition, it can be initialized with a set of files with one instance and then be detached and attached to a another one.


List Volumes

GET
https://api.sfo.unikraft.cloud
/v1/volumes

List volumes.

List Volumes › query Parameters

uuid
​string[]

The UUID of the resource.

name
​string[]

The name of the resource.

details
​boolean
count
​integer · uint32
from
​string
order
​Common.PaginationOrder · enum

The sort order used by list endpoints.

Enum values:
asc
desc
sortby
​Common.PaginationSortBy · enum

The sort field used by list endpoints.

Enum values:
create_time
tags
​string[]

List Volumes › Request Body optional

An identifier for a resource — either a name or a UUID, but not both.
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: uuid
type = object · requires: name
Properties for Variant 1:
uuid
​string · uuid · required

The UUID of the resource.

name
​string

The name of the resource.

List Volumes › Responses

200

The request has succeeded.

The response message for getting one or more volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

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


Create Volume

POST
https://api.sfo.unikraft.cloud
/v1/volumes

Create a new volume.

Create Volume › Request Body

The request message for creating a volume.
name
​string

The name of the resource. If not provided, a random name is generated. The name must be unique within the context of your account.

node
​string

The name of the node to place the resource on. If not provided, the platform picks one. Only accepted on metros that span multiple nodes.

size_mb
​integer · uint64
host_path
​string

An identifier for a resource — either a name or a UUID, but not both.

quota_policy
​Volumes.VolumeQuotaPolicy · enum

Quota policy for a volume.

Enum values:
static
dynamic
filesystem
​string
tags
​string[]
uid
​integer · uint32
gid
​integer · uint32
access_mode
​Volumes.VolumeAccessMode · enum

VolumeAccessMode defines the access mode of a volume, which controls sharing behavior and caching strategy.

Enum values:
rwo
rox
rwx
​object
oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: size_mb
type = object · requires: host_path
type = object · requires: template
Properties for Variant 1:
size_mb
​integer · uint64 · required
name
​string

The name of the resource. If not provided, a random name is generated. The name must be unique within the context of your account.

node
​string

The name of the node to place the resource on. If not provided, the platform picks one. Only accepted on metros that span multiple nodes.

host_path
​string

An identifier for a resource — either a name or a UUID, but not both.

quota_policy
​Volumes.VolumeQuotaPolicy · enum

Quota policy for a volume.

Enum values:
static
dynamic
filesystem
​string
tags
​string[]
uid
​integer · uint32
gid
​integer · uint32
access_mode
​Volumes.VolumeAccessMode · enum

VolumeAccessMode defines the access mode of a volume, which controls sharing behavior and caching strategy.

Enum values:
rwo
rox
rwx
​object

Create Volume › Responses

200

The request has succeeded.

The response message for creating a volume.
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

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


Update Volumes

PATCH
https://api.sfo.unikraft.cloud
/v1/volumes

Update volumes.

Update Volumes › Request Body

A single update operation to be applied to a volume.
prop
​string · enum · required

The property to modify.

Enum values:
size_mb
tags
quota_policy
delete_lock
op
​string · enum · required

The operation to perform.

Enum values:
set
add
del
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

id
​string

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

Example: op-1
value
​

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

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

Update Volumes › Responses

200

The request has succeeded.

The response message for updating one or more volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

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


Delete Volumes

DELETE
https://api.sfo.unikraft.cloud
/v1/volumes

Delete volumes by ID(s).

Delete Volumes › Request Body

An identifier for a resource — either a name or a UUID, but not both.
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: uuid
type = object · requires: name
Properties for Variant 1:
uuid
​string · uuid · required

The UUID of the resource.

name
​string

The name of the resource.

Delete Volumes › Responses

200

The request has succeeded.

The response message for deleting one or more volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

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


Attach Volumes

PUT
https://api.sfo.unikraft.cloud
/v1/volumes/attach

Attach volumes to instances.

Attach Volumes › Request Body

A single request item to attach a volume to an instance.
​object · required

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

at
​string · required

Path of the mountpoint.

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

Example: /mnt/my-volume
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

readonly
​boolean

Whether the volume should be mounted read-only.

Example: false

Attach Volumes › Responses

200

The request has succeeded.

The response message for attaching one or more volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

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


Clone Volumes

POST
https://api.sfo.unikraft.cloud
/v1/volumes/clone

Clone volumes.

Clone Volumes › Request Body

A single request item to clone a volume.
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

vol_name
​string

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

Example: funky-vol-t7qumh5j
quota_policy
​string · enum

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

Enum values:
static
dynamic
tags
​string[]

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

access_mode
​Volumes.VolumeAccessMode · enum

VolumeAccessMode defines the access mode of a volume, which controls sharing behavior and caching strategy.

Enum values:
rwo
rox
rwx

Clone Volumes › Responses

200

The request has succeeded.

The response message for cloning one or more volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

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


Detach Volumes

PUT
https://api.sfo.unikraft.cloud
/v1/volumes/detach

Detach volumes from instances.

Detach Volumes › Request Body

A single request item to detach a volume from an instance.
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

​object

UUID or name of the instance to detach the volume from. If not specified, the volume is detached from all instances.

Detach Volumes › Responses

200

The request has succeeded.

The response message for detaching one or more volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

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


List Template Volumes

GET
https://api.sfo.unikraft.cloud
/v1/volumes/templates

List template volumes.

List Template Volumes › query Parameters

uuid
​string[]

The UUID of the resource.

name
​string[]

The name of the resource.

details
​boolean
count
​integer · uint32
from
​string
order
​Common.PaginationOrder · enum

The sort order used by list endpoints.

Enum values:
asc
desc
sortby
​Common.PaginationSortBy · enum

The sort field used by list endpoints.

Enum values:
create_time
tags
​string[]

List Template Volumes › Request Body optional

An identifier for a resource — either a name or a UUID, but not both.
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: uuid
type = object · requires: name
Properties for Variant 1:
uuid
​string · uuid · required

The UUID of the resource.

name
​string

The name of the resource.

List Template Volumes › Responses

200

The request has succeeded.

The response message for getting one or more template volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

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


Create Template Volume

POST
https://api.sfo.unikraft.cloud
/v1/volumes/templates

Create a template volume.

Create Template Volume › Request Body

An identifier for a resource — either a name or a UUID, but not both.
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: uuid
type = object · requires: name
Properties for Variant 1:
uuid
​string · uuid · required

The UUID of the resource.

name
​string

The name of the resource.

Create Template Volume › Responses

200

The request has succeeded.

The response message for converting one or more volume(s) to templates.
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

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


Update Template Volumes

PATCH
https://api.sfo.unikraft.cloud
/v1/volumes/templates

Update template volumes.

Update Template Volumes › Request Body

A single update operation to be applied to a template volume.
prop
​string · enum · required

The property to modify.

Enum values:
tags
delete_lock
op
​string · enum · required

The operation to perform.

Enum values:
set
add
del
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

id
​string

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

Example: op-1
value
​

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

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

Update Template Volumes › Responses

200

The request has succeeded.

The response message for updating one or more template volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

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


Delete Template Volumes

DELETE
https://api.sfo.unikraft.cloud
/v1/volumes/templates

Delete template volumes by ID(s).

Delete Template Volumes › Request Body

An identifier for a resource — either a name or a UUID, but not both.
uuid
​string · uuid

The UUID of the resource.

name
​string

The name of the resource.

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: uuid
type = object · requires: name
Properties for Variant 1:
uuid
​string · uuid · required

The UUID of the resource.

name
​string

The name of the resource.

Delete Template Volumes › Responses

200

The request has succeeded.

The response message for deleting one or more template volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

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


Get Template Volume by UUID

GET
https://api.sfo.unikraft.cloud
/v1/volumes/templates/{uuid}

Get a template volume by UUID.

Get Template Volume by UUID › path Parameters

uuid
​string · uuid · required

Get Template Volume by UUID › query Parameters

details
​boolean

Get Template Volume by UUID › Responses

200

The request has succeeded.

The response message for getting one or more template volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

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


Update Template Volume by UUID

PATCH
https://api.sfo.unikraft.cloud
/v1/volumes/templates/{uuid}

Update a template volume by UUID.

Update Template Volume by UUID › path Parameters

uuid
​string · uuid · required

Update Template Volume by UUID › Request Body

prop
​string · enum · required

The property to modify.

Enum values:
tags
delete_lock
op
​string · enum · required

The operation to perform.

Enum values:
set
add
del
id
​string

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

Example: op-1
value
​

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

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

Update Template Volume by UUID › Responses

200

The request has succeeded.

The response message for updating one or more template volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

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


Delete Template Volume by UUID

DELETE
https://api.sfo.unikraft.cloud
/v1/volumes/templates/{uuid}

Delete a template volume by UUID.

Delete Template Volume by UUID › path Parameters

uuid
​string · uuid · required

Delete Template Volume by UUID › Responses

200

The request has succeeded.

The response message for deleting one or more template volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

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


Get Volume by UUID

GET
https://api.sfo.unikraft.cloud
/v1/volumes/{uuid}

Get a volume by UUID.

Get Volume by UUID › path Parameters

uuid
​string · uuid · required

Get Volume by UUID › query Parameters

details
​boolean

Get Volume by UUID › Responses

200

The request has succeeded.

The response message for getting one or more volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

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


Update Volume by UUID

PATCH
https://api.sfo.unikraft.cloud
/v1/volumes/{uuid}

Update a volume by UUID.

Update Volume by UUID › path Parameters

uuid
​string · uuid · required

Update Volume by UUID › Request Body

prop
​string · enum · required

The property to modify.

Enum values:
size_mb
tags
quota_policy
delete_lock
op
​string · enum · required

The operation to perform.

Enum values:
set
add
del
id
​string

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

Example: op-1
value
​

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

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

Update Volume by UUID › Responses

200

The request has succeeded.

The response message for updating one or more volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

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


Delete Volume by UUID

DELETE
https://api.sfo.unikraft.cloud
/v1/volumes/{uuid}

Delete a volume by UUID.

Delete Volume by UUID › path Parameters

uuid
​string · uuid · required

Delete Volume by UUID › Responses

200

The request has succeeded.

The response message for deleting one or more volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

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


Attach Volume by UUID

PUT
https://api.sfo.unikraft.cloud
/v1/volumes/{uuid}/attach

Attach a volume by UUID.

Attach Volume by UUID › path Parameters

uuid
​string · uuid · required

Attach Volume by UUID › Request Body

​object · required

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

at
​string · required

Path of the mountpoint.

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

Example: /mnt/my-volume
readonly
​boolean

Whether the volume should be mounted read-only.

Example: false

Attach Volume by UUID › Responses

200

The request has succeeded.

The response message for attaching one or more volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

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


Clone Volume by UUID

POST
https://api.sfo.unikraft.cloud
/v1/volumes/{uuid}/clone

Clone a volume by UUID.

Clone Volume by UUID › path Parameters

uuid
​string · uuid · required

Clone Volume by UUID › Request Body

vol_name
​string

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

Example: funky-vol-t7qumh5j
quota_policy
​string · enum

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

Enum values:
static
dynamic
tags
​string[]

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

access_mode
​Volumes.VolumeAccessMode · enum

VolumeAccessMode defines the access mode of a volume, which controls sharing behavior and caching strategy.

Enum values:
rwo
rox
rwx

Clone Volume by UUID › Responses

200

The request has succeeded.

The response message for cloning one or more volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

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


Detach Volume by UUID

PUT
https://api.sfo.unikraft.cloud
/v1/volumes/{uuid}/detach

Detach a volume by UUID.

Detach Volume by UUID › path Parameters

uuid
​string · uuid · required

Detach Volume by UUID › Request Body

​object

UUID or name of the instance to detach the volume from. If not specified, the volume is detached from all instances.

Detach Volume by UUID › Responses

200

The request has succeeded.

The response message for detaching one or more volume(s) given their UUID(s) or name(s).
status
​string · enum · required

The status of the response.

Enum values:
success
error
partial_success
op_time_us
​integer · uint64 · required

The operation time in microseconds.

message
​string

An optional message providing additional information about the status.

​object

The response data for this request.

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