Volume

Download schema

A Block Storage volume is a logical storage drive on a network-connected storage system. It is exposed to Instances as if it were a physical disk, and can be attached and detached like a hard drive. Several Block volumes can be attached to one Instance at a time

Block volumes can be snapshotted, mounted or unmounted

List volumes

GET

https://api.scaleway.com

/block/v1/zones/{zone}/volumes

List all existing volumes in a specified zone. By default, the volumes listed are ordered by creation date in ascending order. This can be modified via the order_by field.

List volumes › path Parameters

zone

string · enum · required

The zone you want to target

Enum values:

fr-par-1

fr-par-2

fr-par-3

nl-ams-1

nl-ams-2

nl-ams-3

pl-waw-1

pl-waw-2

List volumes › query Parameters

include_deleted

boolean · required

Display deleted volumes not erased yet.

order_by

scaleway.block.v1.ListVolumesRequest.OrderBy · enum

Criteria to use when ordering the list.

Enum values:

created_at_asc

created_at_desc

name_asc

name_desc

Default: created_at_asc

project_id

string

Filter by Project ID.

organization_id

string

Filter by Organization ID.

page

integer · int32

Page number.

page_size

integer · uint32

Page size, defines how many entries are returned in one page, must be lower or equal to 100.

name

string

Filter the return volumes by their names.

product_resource_id

string

Filter by a product resource ID linked to this volume (such as an Instance ID).

tags

string[]

Filter by tags. Only volumes with one or more matching tags will be returned.

volume_type

string

Filter by volume type.

volume_ids

string[]

Filter by volume IDs.

List volumes › Responses

200

scaleway.block.v1.ListVolumesResponse

scaleway.block.v1.Volume[]

Paginated returned list of volumes.

total_count

integer · uint64

Total number of volumes in the project.

GET/block/v1/zones/{zone}/volumes

curl -X GET \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  "https://api.scaleway.com/block/v1/zones/{zone}/volumes?include_deleted=false"

Example Responses

{
  "volumes": [
    {
      "id": "6170692e-7363-616c-6577-61792e636f6d",
      "name": "name",
      "type": "type",
      "size": 0,
      "project_id": "6170692e-7363-616c-6577-61792e636f6d",
      "created_at": "2022-03-22T12:34:56.123456Z",
      "updated_at": "2022-03-22T12:34:56.123456Z",
      "references": [
        {
          "id": "6170692e-7363-616c-6577-61792e636f6d",
          "product_resource_type": "product_resource_type",
          "product_resource_id": "6170692e-7363-616c-6577-61792e636f6d",
          "created_at": "2022-03-22T12:34:56.123456Z",
          "type": "unknown_type",
          "status": "unknown_status"
        }
      ],
      "parent_snapshot_id": "6170692e-7363-616c-6577-61792e636f6d",
      "status": "unknown_status",
      "tags": [
        "string"
      ],
      "zone": "zone",
      "specs": {
        "perf_iops": 0,
        "class": "unknown_storage_class"
      },
      "last_detached_at": "2022-03-22T12:34:56.123456Z",
      "kms_key_id": "6170692e-7363-616c-6577-61792e636f6d",
      "srn": "srn"
    }
  ],
  "total_count": 0
}

json

application/json

Create a volume

POST

https://api.scaleway.com

/block/v1/zones/{zone}/volumes

To create a new volume from scratch, you must specify from_empty and the size. To create a volume from an existing snapshot, specify from_snapshot and the snapshot_id in the request payload instead, size is optional and can be specified if you need to extend the original size. The volume will take on the same volume class and underlying IOPS limitations as the original snapshot.

Create a volume › path Parameters

zone

string · enum · required

The zone you want to target

Enum values:

fr-par-1

fr-par-2

fr-par-3

nl-ams-1

nl-ams-2

nl-ams-3

pl-waw-1

pl-waw-2

Create a volume › Request Body

name

string · required

Name of the volume.

project_id

string · required

UUID of the project the volume belongs to.

perf_iops

integer | null · uint32

The maximum IO/s expected, according to the different options available in stock (5000 | 15000).

Specify the size of the new volume if creating a new one from scratch.

Specify the snapshot ID of the original snapshot.

tags

string[]

List of tags assigned to the volume.

kms_key_id

string | null

UUID of the KMS key used to protect the volume's encryption.

Create a volume › Responses

200

scaleway.block.v1.Volume

id

string

UUID of the volume. (UUID format)

name

string

Name of the volume.

type

string

Volume type.

size

integer · uint64

Volume size in bytes. (in bytes)

project_id

string

UUID of the project to which the volume belongs. (UUID format)

created_at

string | null · date-time

Creation date of the volume. (RFC 3339 format)

updated_at

string | null · date-time

Last update of the properties of a volume. (RFC 3339 format)

scaleway.block.v1.Reference[]

List of the references to the volume.

parent_snapshot_id

string | null

When a volume is created from a snapshot, is the UUID of the snapshot from which the volume has been created. (UUID format)

status

scaleway.block.v1.Volume.Status · enum

Current status of the volume (available, in_use, ...).

Enum values:

unknown_status

creating

available

in_use

deleting

deleted

resizing

error

Default: unknown_status

tags

string[]

List of tags assigned to the volume.

zone

string

Volume zone.

scaleway.block.v1.VolumeSpecifications

Specifications of the volume.

last_detached_at

string | null · date-time

Last time the volume was detached. (RFC 3339 format)

kms_key_id

string | null

KMS Key used for securing the volume's encryption. (UUID format)

srn

string

The SRN of the volume.

POST/block/v1/zones/{zone}/volumes

curl -X POST \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","project_id":"string"}' \
  "https://api.scaleway.com/block/v1/zones/{zone}/volumes"

Example Request Body

{
  "name": "name",
  "perf_iops": 0,
  "project_id": "project_id",
  "from_empty": {
    "size": 0
  },
  "from_snapshot": {
    "size": 0,
    "snapshot_id": "snapshot_id"
  },
  "tags": [
    "string"
  ],
  "kms_key_id": "kms_key_id"
}

json

Example Responses

{
  "id": "6170692e-7363-616c-6577-61792e636f6d",
  "name": "name",
  "type": "type",
  "size": 0,
  "project_id": "6170692e-7363-616c-6577-61792e636f6d",
  "created_at": "2022-03-22T12:34:56.123456Z",
  "updated_at": "2022-03-22T12:34:56.123456Z",
  "references": [
    {
      "id": "6170692e-7363-616c-6577-61792e636f6d",
      "product_resource_type": "product_resource_type",
      "product_resource_id": "6170692e-7363-616c-6577-61792e636f6d",
      "created_at": "2022-03-22T12:34:56.123456Z",
      "type": "unknown_type",
      "status": "unknown_status"
    }
  ],
  "parent_snapshot_id": "6170692e-7363-616c-6577-61792e636f6d",
  "status": "unknown_status",
  "tags": [
    "string"
  ],
  "zone": "zone",
  "specs": {
    "perf_iops": 0,
    "class": "unknown_storage_class"
  },
  "last_detached_at": "2022-03-22T12:34:56.123456Z",
  "kms_key_id": "6170692e-7363-616c-6577-61792e636f6d",
  "srn": "srn"
}

json

application/json

Get a volume

GET

https://api.scaleway.com

/block/v1/zones/{zone}/volumes/{volume_id}

Retrieve technical information about a specific volume. Details such as size, type, and status are returned in the response.

Get a volume › path Parameters

zone

string · enum · required

The zone you want to target

Enum values:

fr-par-1

fr-par-2

fr-par-3

nl-ams-1

nl-ams-2

nl-ams-3

pl-waw-1

pl-waw-2

volume_id

string · required

UUID of the volume.

Get a volume › Responses

200

scaleway.block.v1.Volume

id

string

UUID of the volume. (UUID format)

name

string

Name of the volume.

type

string

Volume type.

size

integer · uint64

Volume size in bytes. (in bytes)

project_id

string

UUID of the project to which the volume belongs. (UUID format)

created_at

string | null · date-time

Creation date of the volume. (RFC 3339 format)

updated_at

string | null · date-time

Last update of the properties of a volume. (RFC 3339 format)

scaleway.block.v1.Reference[]

List of the references to the volume.

parent_snapshot_id

string | null

When a volume is created from a snapshot, is the UUID of the snapshot from which the volume has been created. (UUID format)

status

scaleway.block.v1.Volume.Status · enum

Current status of the volume (available, in_use, ...).

Enum values:

unknown_status

creating

available

in_use

deleting

deleted

resizing

error

Default: unknown_status

tags

string[]

List of tags assigned to the volume.

zone

string

Volume zone.

scaleway.block.v1.VolumeSpecifications

Specifications of the volume.

last_detached_at

string | null · date-time

Last time the volume was detached. (RFC 3339 format)

kms_key_id

string | null

KMS Key used for securing the volume's encryption. (UUID format)

srn

string

The SRN of the volume.

GET/block/v1/zones/{zone}/volumes/{volume_id}

curl -X GET \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  "https://api.scaleway.com/block/v1/zones/{zone}/volumes/{volume_id}"

Example Responses

{
  "id": "6170692e-7363-616c-6577-61792e636f6d",
  "name": "name",
  "type": "type",
  "size": 0,
  "project_id": "6170692e-7363-616c-6577-61792e636f6d",
  "created_at": "2022-03-22T12:34:56.123456Z",
  "updated_at": "2022-03-22T12:34:56.123456Z",
  "references": [
    {
      "id": "6170692e-7363-616c-6577-61792e636f6d",
      "product_resource_type": "product_resource_type",
      "product_resource_id": "6170692e-7363-616c-6577-61792e636f6d",
      "created_at": "2022-03-22T12:34:56.123456Z",
      "type": "unknown_type",
      "status": "unknown_status"
    }
  ],
  "parent_snapshot_id": "6170692e-7363-616c-6577-61792e636f6d",
  "status": "unknown_status",
  "tags": [
    "string"
  ],
  "zone": "zone",
  "specs": {
    "perf_iops": 0,
    "class": "unknown_storage_class"
  },
  "last_detached_at": "2022-03-22T12:34:56.123456Z",
  "kms_key_id": "6170692e-7363-616c-6577-61792e636f6d",
  "srn": "srn"
}

json

application/json

Delete a detached volume

DELETE

https://api.scaleway.com

/block/v1/zones/{zone}/volumes/{volume_id}

You must specify the volume_id of the volume you want to delete. The volume must not be in the in_use status.

Delete a detached volume › path Parameters

zone

string · enum · required

The zone you want to target

Enum values:

fr-par-1

fr-par-2

fr-par-3

nl-ams-1

nl-ams-2

nl-ams-3

pl-waw-1

pl-waw-2

volume_id

string · required

UUID of the volume.

Delete a detached volume › Responses

No data returned

Update a volume

PATCH

https://api.scaleway.com

/block/v1/zones/{zone}/volumes/{volume_id}

Update the technical details of a volume, such as its name, tags, or its new size and volume_type (within the same Block Storage class). You can only resize a volume to a larger size. It is currently not possible to change your Block Storage Class.

Update a volume › path Parameters

zone

string · enum · required

The zone you want to target

Enum values:

fr-par-1

fr-par-2

fr-par-3

nl-ams-1

nl-ams-2

nl-ams-3

pl-waw-1

pl-waw-2

volume_id

string · required

UUID of the volume.

Update a volume › Request Body

name

string | null

When defined, is the new name of the volume.

size

integer | null · uint64

Optional field for increasing the size of a volume (size must be equal or larger than the current one). Size in bytes of the volume, with a granularity of 1 GB (10^9 bytes). (in bytes)

tags

array | null

List of tags assigned to the volume.

perf_iops

integer | null · uint32

The maximum IO/s expected, according to the different options available in stock (5000 | 15000). The selected value must be available for the volume's current storage class.

Update a volume › Responses

200

scaleway.block.v1.Volume

id

string

UUID of the volume. (UUID format)

name

string

Name of the volume.

type

string

Volume type.

size

integer · uint64

Volume size in bytes. (in bytes)

project_id

string

UUID of the project to which the volume belongs. (UUID format)

created_at

string | null · date-time

Creation date of the volume. (RFC 3339 format)

updated_at

string | null · date-time

Last update of the properties of a volume. (RFC 3339 format)

scaleway.block.v1.Reference[]

List of the references to the volume.

parent_snapshot_id

string | null

When a volume is created from a snapshot, is the UUID of the snapshot from which the volume has been created. (UUID format)

status

scaleway.block.v1.Volume.Status · enum

Current status of the volume (available, in_use, ...).

Enum values:

unknown_status

creating

available

in_use

deleting

deleted

resizing

error

Default: unknown_status

tags

string[]

List of tags assigned to the volume.

zone

string

Volume zone.

scaleway.block.v1.VolumeSpecifications

Specifications of the volume.

last_detached_at

string | null · date-time

Last time the volume was detached. (RFC 3339 format)

kms_key_id

string | null

KMS Key used for securing the volume's encryption. (UUID format)

srn

string

The SRN of the volume.

PATCH/block/v1/zones/{zone}/volumes/{volume_id}

curl -X PATCH \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://api.scaleway.com/block/v1/zones/{zone}/volumes/{volume_id}"

Example Request Body

{
  "name": "name",
  "size": 0,
  "tags": [],
  "perf_iops": 0
}

json

Example Responses

{
  "id": "6170692e-7363-616c-6577-61792e636f6d",
  "name": "name",
  "type": "type",
  "size": 0,
  "project_id": "6170692e-7363-616c-6577-61792e636f6d",
  "created_at": "2022-03-22T12:34:56.123456Z",
  "updated_at": "2022-03-22T12:34:56.123456Z",
  "references": [
    {
      "id": "6170692e-7363-616c-6577-61792e636f6d",
      "product_resource_type": "product_resource_type",
      "product_resource_id": "6170692e-7363-616c-6577-61792e636f6d",
      "created_at": "2022-03-22T12:34:56.123456Z",
      "type": "unknown_type",
      "status": "unknown_status"
    }
  ],
  "parent_snapshot_id": "6170692e-7363-616c-6577-61792e636f6d",
  "status": "unknown_status",
  "tags": [
    "string"
  ],
  "zone": "zone",
  "specs": {
    "perf_iops": 0,
    "class": "unknown_storage_class"
  },
  "last_detached_at": "2022-03-22T12:34:56.123456Z",
  "kms_key_id": "6170692e-7363-616c-6577-61792e636f6d",
  "srn": "srn"
}

json

application/json

Volume Type Snapshot