Block Storage

Download schema

A storage device is a block device similar to a physical hard disk. It can be used to install an operating system or hold some other filesystem for a server.

Storages can be freely attached to any server within the same zone and under the same account. A maximum of 16 storage devices can be attached to a server at the same time; however, the combined limit for network interfaces and storage devices is 24.

Storage types

There are four different storage types: disk, cdrom, template and backup.

List storages

GET

https://api.upcloud.com

/1.3/storage

Returns a list of storage devices. Supports filtering by type, access level, and labels, as well as sorting and pagination

List storages › query Parameters

type

storageType · enum

Filter by storage type

Storage type filter

Enum values:

normal

template

cdrom

backup

access

storageAccessFilter · enum

Filter by access level (public or private)

Storage access level filter

Enum values:

public

private

label

storageLabelFilter · pattern: ^!?[^=]+=.*$

Filter by labels. Can be specified multiple times.

Label filter in format key=value or !key=value for negation

Example: environment=production

sort_by

storageSortBy · enum

Sort results by the specified field

Field to sort storage results by

Enum values:

created

size

title

type

order_by

storageOrderBy · enum

Sort order (ascending or descending). Only valid when sort_by is also specified.

Sort order for storage results

Enum values:

asc

desc

limit

storageLimit · min: 1 · max: 1000

Maximum number of storages to return per page

Maximum number of items to return. Default is 25.

Example: 25

offset

storageOffset · min: 0

Number of storages to skip before starting to return results

Number of items to skip before starting to return results. Default is 0.

Example: 0

allow_hidden

storageAllowHidden · enum

Include hidden storages in the response

Whether to include hidden storages in the response

Enum values:

yes

Example: yes

favorite

storageFavorite · enum

Filter storages by favorite status

Enum values:

yes

Example: yes

metadata

storageMetadata · enum

Whether to include metadata in the response

Enum values:

yes

Example: yes

servers

storageServers · enum

Whether to include server information in the response

Enum values:

yes

Example: yes

List storages › Responses

A list of storages

storages

object · required

Create new storage

POST

https://api.upcloud.com

/1.3/storage

Create new storage

Create new storage › Request Body

Request schema for creating a storage

createStorageRequest

object · required

Create new storage › Responses

Storage created

Created storage

createStorageResponse

storageDetails · required

POST/1.3/storage

curl https://api.upcloud.com/1.3/storage \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "storage": {
    "backup_rule": {
      "interval": "interval",
      "retention": "retention",
      "time": "time"
    },
    "components": "components",
    "force_backend": "force_backend",
    "size": 0,
    "size_factor": "size_factor",
    "tier": "tier",
    "title": "title",
    "uuid": "0414e0d7-4436-4037-9dd8-6eaf47dce599",
    "zone": "fi-hel1"
  }
}'

Example Request Body

{
  "storage": {
    "backup_rule": {
      "interval": "interval",
      "retention": "retention",
      "time": "time"
    },
    "components": "components",
    "force_backend": "force_backend",
    "size": 0,
    "size_factor": "size_factor",
    "tier": "tier",
    "title": "title",
    "uuid": "0414e0d7-4436-4037-9dd8-6eaf47dce599",
    "zone": "fi-hel1"
  }
}

json

Example Responses

{
  "storage": {
    "access": "public",
    "encrypted": "yes",
    "labels": [
      {
        "key": "env",
        "value": "production"
      }
    ],
    "license": 0,
    "metadata": {
      "key": "string"
    },
    "part_of_plan": "yes",
    "size": 1,
    "state": "online",
    "tier": "tier",
    "title": "title",
    "type": "normal",
    "uuid": "0414e0d7-4436-4037-9dd8-6eaf47dce599",
    "zone": "fi-hel1"
  }
}

json

application/json

Create new CD-ROM storage

POST

https://api.upcloud.com

/1.3/storage/create_cdrom

Create new CD-ROM storage

Create new CD-ROM storage › Request Body

Schema for creating a new CD-ROM image

storageCreateCdromRequest

object · required

Create new CD-ROM storage › Responses

CD-ROM storage created

Created storage

createStorageResponse

storageDetails · required

POST/1.3/storage/create_cdrom

curl https://api.upcloud.com/1.3/storage/create_cdrom \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "create_cdrom": {
    "access": "access",
    "architecture": "architecture",
    "category": "category",
    "default_disk_bus": "default_disk_bus",
    "default_nic_model": "default_nic_model",
    "default_video_model": "default_video_model",
    "description_en": "description_en",
    "description_fi": "description_fi",
    "md5sum": "md5sum",
    "owner": "owner",
    "title": "title",
    "url": "url",
    "uuid": "0414e0d7-4436-4037-9dd8-6eaf47dce599",
    "zone": "fi-hel1"
  }
}'

Example Request Body

{
  "create_cdrom": {
    "access": "access",
    "architecture": "architecture",
    "category": "category",
    "default_disk_bus": "default_disk_bus",
    "default_nic_model": "default_nic_model",
    "default_video_model": "default_video_model",
    "description_en": "description_en",
    "description_fi": "description_fi",
    "md5sum": "md5sum",
    "owner": "owner",
    "title": "title",
    "url": "url",
    "uuid": "0414e0d7-4436-4037-9dd8-6eaf47dce599",
    "zone": "fi-hel1"
  }
}

json

Example Responses

{
  "storage": {
    "access": "public",
    "encrypted": "yes",
    "labels": [
      {
        "key": "env",
        "value": "production"
      }
    ],
    "license": 0,
    "metadata": {
      "key": "string"
    },
    "part_of_plan": "yes",
    "size": 1,
    "state": "online",
    "tier": "tier",
    "title": "title",
    "type": "normal",
    "uuid": "0414e0d7-4436-4037-9dd8-6eaf47dce599",
    "zone": "fi-hel1"
  }
}

json

application/json

List favorite storages

GET

https://api.upcloud.com

/1.3/storage/favorite

List favorite storages

List favorite storages › Responses

A list of favorite storages

storages

object · required

Get storage details

GET

https://api.upcloud.com

/1.3/storage/{uuid}

Get storage details

Get storage details › path Parameters

uuid

storageUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Storage UUID

Universally unique identifier

Get storage details › Responses

Storage details

storage

storageDetails · required

Modify storage

PUT

https://api.upcloud.com

/1.3/storage/{uuid}

Modify storage

Modify storage › path Parameters

uuid

storageUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Storage UUID

Universally unique identifier

Modify storage › Request Body

Modify storage › Responses

Delete storage

DELETE

https://api.upcloud.com

/1.3/storage/{uuid}

Delete storage

Delete storage › path Parameters

uuid

storageUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Storage UUID

Universally unique identifier

Delete storage › query Parameters

backups

string · enum

Policy for handling backups when deleting a storage. Allowed values: keep, delete, keep_latest

Enum values:

keep

delete

keep_latest

Delete storage › Responses

Storage deleted

No data returned

Add storage component

POST

https://api.upcloud.com

/1.3/storage/{uuid}/add_component

Add storage component

Add storage component › path Parameters

uuid

storageUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Storage UUID

Universally unique identifier

Add storage component › Request Body

Schema for adding a storage component to a storage device

addStorageComponentRequest

object · required

Add storage component › Responses

Storage component added

No data returned

Attach storage to server

POST

https://api.upcloud.com

/1.3/storage/{uuid}/attach

Attach storage to server

Attach storage to server › path Parameters

uuid

storageUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Storage UUID

Universally unique identifier

Attach storage to server › Request Body

Schema for attaching a storage device to a server

attachStorage

object · required

Attach storage to server › Responses

Storage attached to server

No data returned

Create on-demand backup

POST

https://api.upcloud.com

/1.3/storage/{uuid}/backup

Create on-demand backup

Create on-demand backup › path Parameters

uuid

storageUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Storage UUID

Universally unique identifier

Create on-demand backup › Request Body

createStorageBackupRequest

interval

string · required

retention

string · required

time

string · required

Create on-demand backup › Responses

On-demand backup created

Created storage

createStorageResponse

storageDetails · required

POST/1.3/storage/{uuid}/backup

curl https://api.upcloud.com/1.3/storage/:uuid/backup \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "interval": "interval",
  "retention": "retention",
  "time": "time"
}'

Example Request Body

{
  "interval": "interval",
  "retention": "retention",
  "time": "time"
}

json

Example Responses

{
  "storage": {
    "access": "public",
    "encrypted": "yes",
    "labels": [
      {
        "key": "env",
        "value": "production"
      }
    ],
    "license": 0,
    "metadata": {
      "key": "string"
    },
    "part_of_plan": "yes",
    "size": 1,
    "state": "online",
    "tier": "tier",
    "title": "title",
    "type": "normal",
    "uuid": "0414e0d7-4436-4037-9dd8-6eaf47dce599",
    "zone": "fi-hel1"
  }
}

json

application/json

Cancel storage operation

POST

https://api.upcloud.com

/1.3/storage/{uuid}/cancel

Cancel storage operation

Cancel storage operation › path Parameters

uuid

storageUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Storage UUID

Universally unique identifier

Cancel storage operation › Responses

Storage operation cancelled

No data returned

Clone storage

POST

https://api.upcloud.com

/1.3/storage/{uuid}/clone

Clone storage

Clone storage › path Parameters

uuid

storageUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Storage UUID

Universally unique identifier

Clone storage › Request Body

TODO

cloneStorageRequest

object · required

Clone storage › Responses

Storage cloned

Created storage

createStorageResponse

storageDetails · required

POST/1.3/storage/{uuid}/clone

curl https://api.upcloud.com/1.3/storage/:uuid/clone \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "storage": {
    "components": "components",
    "tier": "tier",
    "title": "title",
    "zone": "fi-hel1"
  }
}'

Example Request Body

{
  "storage": {
    "components": "components",
    "tier": "tier",
    "title": "title",
    "zone": "fi-hel1"
  }
}

json

Example Responses

{
  "storage": {
    "access": "public",
    "encrypted": "yes",
    "labels": [
      {
        "key": "env",
        "value": "production"
      }
    ],
    "license": 0,
    "metadata": {
      "key": "string"
    },
    "part_of_plan": "yes",
    "size": 1,
    "state": "online",
    "tier": "tier",
    "title": "title",
    "type": "normal",
    "uuid": "0414e0d7-4436-4037-9dd8-6eaf47dce599",
    "zone": "fi-hel1"
  }
}

json

application/json

Detach storage from server

POST

https://api.upcloud.com

/1.3/storage/{uuid}/detach

Detach storage from server

Detach storage from server › path Parameters

uuid

storageUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Storage UUID

Universally unique identifier

Detach storage from server › Responses

Storage detached from server

No data returned

Add storage to favorites

POST

https://api.upcloud.com

/1.3/storage/{uuid}/favorite

Add storage to favorites

Add storage to favorites › path Parameters

uuid

storageUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Storage UUID

Universally unique identifier

Add storage to favorites › Responses

Storage added to favorites

No data returned

Remove storage from favorites

DELETE

https://api.upcloud.com

/1.3/storage/{uuid}/favorite

Remove storage from favorites

Remove storage from favorites › path Parameters

uuid

storageUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Storage UUID

Universally unique identifier

Remove storage from favorites › Responses

Storage removed from favorites

No data returned

Resize storage

POST

https://api.upcloud.com

/1.3/storage/{uuid}/resize

Resize storage

Resize storage › path Parameters

uuid

storageUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Storage UUID

Universally unique identifier

Resize storage › Responses

Restore storage from backup

POST

https://api.upcloud.com

/1.3/storage/{uuid}/restore

Restore storage from backup

Restore storage from backup › path Parameters

uuid

storageUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Storage UUID

Universally unique identifier

Restore storage from backup › Responses

Storage restore started

No data returned

Create template from storage

POST

https://api.upcloud.com

/1.3/storage/{uuid}/templatize

Create template from storage

Create template from storage › path Parameters

uuid

storageUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Storage UUID

Universally unique identifier

Create template from storage › Request Body

Request schema for creating a storage template

createStorageTemplateRequest

object · required

Create template from storage › Responses

Template created

Created storage

createStorageResponse

storageDetails · required

POST/1.3/storage/{uuid}/templatize

curl https://api.upcloud.com/1.3/storage/:uuid/templatize \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "storage": {
    "title": "My Template"
  }
}'

Example Request Body

{
  "storage": {
    "title": "My Template"
  }
}

json

Example Responses

{
  "storage": {
    "access": "public",
    "encrypted": "yes",
    "labels": [
      {
        "key": "env",
        "value": "production"
      }
    ],
    "license": 0,
    "metadata": {
      "key": "string"
    },
    "part_of_plan": "yes",
    "size": 1,
    "state": "online",
    "tier": "tier",
    "title": "title",
    "type": "normal",
    "uuid": "0414e0d7-4436-4037-9dd8-6eaf47dce599",
    "zone": "fi-hel1"
  }
}

json

application/json

Update public template from source

POST

https://api.upcloud.com

/1.3/storage/{uuid}/update_template

Update public template from source

Update public template from source › path Parameters

uuid

storageUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Storage UUID

Universally unique identifier

Update public template from source › Request Body

Request schema for updating a storage template

storageUpdateTemplateRequest

object · required

Update public template from source › Responses

Template update started

No data returned

Partner Object Storage