Skip to main content
API docs by Redocly

Block Storage API Product (1.171.0)

Block Storage API Product

volumes

Operations with volumes, including create, delete, extend, retype, list and other actions.

List all volumes.

Retrieve a list of Volumes for the currently authenticated tenant.

Notes

  • Use the expand argument to obtain additional details about the Volume Type.
query Parameters
expand
Array of strings (Expand)
Default: ""

You can get more detailed info about: ['volume_type', 'attachment']

_limit
integer ( Limit) > 0
Default: 50
_offset
integer ( Offset) >= 0
Default: 0
_sort
string ( Sort) ^(^[\w-]+:(asc|desc)(,[\w-]+:(asc|desc))*)?$
Default: "created_at:asc"
Name (string) or Name (null) (Name)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "volumes": [
    ]
}

Create a new volume.

Create a Volume for the currently authenticated tenant.

The Volume can be used when it reaches the "available" state and "completed" status.

Rules

  • The Volume name must be unique; otherwise, the creation will be disallowed.
  • The Volume type must be available to use.

Notes

  • Utilize the block-storage volume-types list command to retrieve a list of all available Volume Types.
  • Verify the state and status of your Volume using the block-storage volume get --id [uuid] command".
header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
name
required
string (Name) [ 3 .. 50 ] characters
size
required
integer (Size) [ 10 .. 2147483648 ]

Gibibytes (GiB)

required
IdRequest (object) or Name (object) (Type)
IdRequest (object) or Name (object) or Backup (null) (Backup)
IdRequest (object) or Name (object) or Snapshot (null) (Snapshot)
Availability Zone (string) or Availability Zone (null) (Availability Zone)

Responses

Request samples

Content type
application/json
{
  • "availability_zone": "br-se1-a",
  • "backup": {
    },
  • "name": "volume-name",
  • "size": 10,
  • "snapshot": {
    },
  • "type": {
    }
}

Response samples

Content type
application/json
{
  • "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Delete a volume.

Delete a Volume for the currently authenticated tenant.

Rules

  • The Volume cannot be attached to a Virtual Machine, i.e., its state cannot be "in-use". If necessary, detach the Volume from the Virtual Machine before proceeding with deletion.
  • The Volume must not have any snapshots. If necessary, delete the Volume's snapshots before proceeding with deletion.
  • The Volume must have the status "completed", i.e., must not have any actions in progress.

Notes

  • Check the state and status of your Volume using the block-storage volume get --id [uuid] command".
path Parameters
id
required
string <uuid> (Id)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve the details of a specific volume.

Retrieve details of a Volume for the currently authenticated tenant.

Notes

  • Use the expand argument to obtain additional details about the Volume Type.
  • Utilize the block-storage volume list command to retrieve a list of all Volumes and obtain the ID of the Volume for which you want to retrieve details.
path Parameters
id
required
string <uuid> (Id)
query Parameters
expand
Array of strings (Expand)
Default: ""

You can get more detailed info about: ['volume_type', 'attachment']

header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "attachment": {
    },
  • "availability_zones": [
    ],
  • "created_at": "2022-01-01T00:00:10Z",
  • "error": {
    },
  • "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  • "name": "volume name",
  • "size": 10,
  • "state": "in-use",
  • "status": "completed",
  • "type": {
    },
  • "updated_at": "2022-01-01T00:00:10Z"
}

Attach the volume to an instance.

Attach a Volume to a Virtual Machine instance for the currently authenticated tenant.

The Volume attachment will be completed when the Volume status returns to "completed", and the state becomes "in-use".

Rules

  • The Volume and the Virtual Machine must belong to the same tenant.
  • Both the Volume and Virtual Machine must have the status "completed".
  • The Volume's state must be "available".
  • The Virtual Machine's state must be "stopped" or "running".

Notes

  • Verify the state and status of your Volume using the block-storage volume get --id [uuid] command.
  • Verify the state and status of your Virtual Machine using the virtual-machine instances get --id [uuid] command".
path Parameters
id
required
string <uuid> (Id)
virtual_machine_id
required
string <uuid> (Virtual Machine Id)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Detach the volume from an instance.

Detach a Volume from a Virtual Machine instance for the currently authenticated tenant.

The Volume detachment will be completed when the Volume state returns to "available," and the status becomes "completed".

Rules

  • The Volume and the Virtual Machine must belong to the same tenant.
  • Both the Volume and Virtual Machine must have the status "completed".
  • The Volume's state must be "in-use".
  • The Virtual Machine's state must be "stopped".

Notes

  • Verify the state and status of your Volume using the block-storage volume get --id [uuid] command.
  • Verify the state and status of your Virtual Machine using the virtual-machine instances get --id [uuid] command.
  • Ensure that any file systems on the device within your operating system are unmounted before detaching the Volume.

Troubleshooting

  • A failure during detachment can result in the Volume becoming stuck in the busy state. If this occurs, detachment may be delayed indefinitely until you unmount the Volume, force detachment, reboot the instance, or perform all three.
path Parameters
id
required
string <uuid> (Id)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Extend the size of a volume.

Extend the size of an existing Volume for the currently authenticated tenant.

The Volume extension will be completed when the Volume status returns to "completed".

Rules

  • The Volume state must be "available".
  • The Volume status must be "completed" or "extend_error".
  • The new Volume size must be larger than the current size.

Notes

  • Utilize the block-storage volume list command to retrieve a list of all Volumes and obtain the ID of the Volume you want to extend.
  • Storage quotas are managed internally. If the operation fails due to quota restrictions, please contact our support team for assistance.
path Parameters
id
required
string <uuid> (Id)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
size
required
integer (Size) > 0

New volume size in GB

Responses

Request samples

Content type
application/json
{
  • "size": 20
}

Response samples

Content type
application/json
[
  • {
    }
]

Rename a volume.

Rename a Volume for the currently authenticated tenant.

Rules

  • The Volume name must be unique; otherwise, renaming will not be allowed.

Notes

  • Utilize the block-storage volume list command to retrieve a list of all Volumes and obtain the ID of the Volume you wish to rename.
path Parameters
id
required
string <uuid> (Id)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
name
required
string (Name) [ 3 .. 50 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "volume-name"
}

Response samples

Content type
application/json
[
  • {
    }
]

Change the type of a volume.

Change the Volume Type of an existing Volume for the currently authenticated tenant.

The Volume retype will be completed when the Volume status returns to "completed".

Rules

  • The Volume state must be "available".
  • The Volume status must be "completed" or "retype_error".
  • The new Volume Type must belong to the same region as the Volume.

Notes

  • Utilize the block-storage volume list command to retrieve a list of all Volumes and obtain the ID of the Volume you want to retype.
  • Utilize the block-storage volume-types list command to retrieve a list of all Volume Types and obtain the ID of the Volume Type you want to use.
path Parameters
id
required
string <uuid> (Id)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
required
IdRequest (object) or Name (object) (New Type)
Any of
id
required
string (Id) non-empty

Responses

Request samples

Content type
application/json
{
  • "new_type": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]

volume-types

Operations with volume types for volumes.

List all volume types.

List Volume Types allowed in the current region.

Notes

  • Volume types are managed internally. If you wish to use a Volume Type that is not yet available, please contact our support team for assistance.
query Parameters
Availability-Zone (string) or Availability-Zone (null) (Availability-Zone)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "types": [
    ]
}

snapshots

Operations with snapshots for volumes.

List all snapshots.

Retrieve a list of Snapshots for the currently authenticated tenant.

Notes

  • Use the expand argument to obtain additional details about the Volume used to create each Snapshot.
query Parameters
expand
Array of strings (Expand)
Default: ""
Items Value: "volume"
_limit
integer ( Limit) > 0
Default: 50
_offset
integer ( Offset) >= 0
Default: 0
_sort
string ( Sort) ^(^[\w-]+:(asc|desc)(,[\w-]+:(asc|desc))*)?$
Default: "created_at:asc"
Name (string) or Name (null) (Name)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "snapshots": [
    ]
}

Create a snapshot.

Create a Snapshot for the currently authenticated tenant.

The Snapshot can be used when it reaches the "available" state and the "completed" status.

Rules

  • The Snapshot name must be unique; otherwise, the creation will be disallowed.
  • Creating Snapshots from restored Volumes may lead to future conflicts as you can't delete a Volume with an Snapshot and can't delete a Snapshot with a restored Volume, so we recommend avoiding it.

Notes

  • Use the block-storage volume list command to retrieve a list of all Volumes and obtain the ID of the Volume that will be used to create the Snapshot.
header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
name
required
string (Name) [ 3 .. 50 ] characters
required
IdRequest (object) or Name (object) (Volume)
required
Description (string) or Description (null) (Description)

Responses

Request samples

Content type
application/json
{
  • "description": "my-snapshot",
  • "name": "snapshot-name",
  • "volume": {
    }
}

Response samples

Content type
application/json
{
  • "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Delete a snapshot.

Delete a Snapshot for the currently authenticated tenant.

Rules

  • The Snapshot's status must be "completed".
  • The Snapshot's state must be "available".
  • Deleting a Snapshot that has been restored is not possible. If necessary, delete the restored Volume first and then proceed to delete the Snapshot.

Notes

  • Utilize the block-storage snapshots list command to retrieve a list of all Snapshots and obtain the ID of the Snapshot you wish to delete.
  • If needed, you can use the block-storage volume list command to retrieve a list of all Volumes and obtain the ID of the restored Volume.
path Parameters
id
required
string <uuid> (Id)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve the details of a specific snapshot.

Retrieve details of a Snapshot for the currently authenticated tenant.

Notes

  • Use the expand argument to obtain additional details about the Volume used to create the Snapshot.
  • Utilize the block-storage snapshots list command to retrieve a list of all Snapshots and obtain the ID of the Snapshot for which you want to retrieve details.
path Parameters
id
required
string <uuid> (Id)
query Parameters
expand
Array of strings (Expand)
Default: ""
Items Value: "volume"
header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "availability_zones": [
    ],
  • "created_at": "2022-01-01T00:00:10Z",
  • "description": "my snapshot for testing",
  • "error": {
    },
  • "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  • "name": "My snapshot",
  • "size": 10,
  • "state": "available",
  • "status": "completed",
  • "updated_at": "2022-01-01T00:00:10Z",
  • "volume": {
    }
}

Rename a snapshot.

Rename a Snapshot for the currently authenticated tenant.

Rules

  • The Snapshot name must be unique; otherwise, renaming will not be allowed.

Notes

  • Utilize the block-storage snapshots list command to retrieve a list of all Snapshots and obtain the ID of the Snapshot you wish to rename.
path Parameters
id
required
string <uuid> (Id)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
name
required
string (Name) [ 3 .. 50 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "snapshot-name"
}

Response samples

Content type
application/json
[
  • {
    }
]

usage

Get Usage

Retrieve usage for specific quota_slug (disk & volumes)

query Parameters
Quota Slug (string) or Quota Slug (null) (Quota Slug)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

attachments

Attach a volume to an instance.

Attach a Volume to a Virtual Machine instance for the currently authenticated tenant.

The Volume attachment will be completed when the Volume status returns to "completed", and the state becomes "in-use".

Rules

  • The Volume and the Virtual Machine must belong to the same tenant.
  • Both the Volume and Virtual Machine must have the status "completed".
  • The Volume's state must be "available".
  • The Virtual Machine's state must be "stopped" or "running".

Notes

  • Verify the state and status of your Volume using the block-storage volume get --id [uuid] command.
  • Verify the state and status of your Virtual Machine using the virtual-machine instances get --id [uuid] command".
header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
required
object (IdRequest)
required
object (IdRequest)
Device (string) or Device (null) (Device)

Responses

Request samples

Content type
application/json
{
  • "device": "/dev/vdc",
  • "instance": {
    },
  • "volume": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]

Delete an attachment.

Detach a Volume from a Virtual Machine instance for the currently authenticated tenant.

The Volume detachment will be completed when the Volume state returns to "available," and the status becomes "completed".

Rules

  • The Volume and the Virtual Machine must belong to the same tenant.
  • Both the Volume and Virtual Machine must have the status "completed".
  • The Volume's state must be "in-use".
  • The Virtual Machine's state must be "stopped".

Notes

  • Verify the state and status of your Volume using the block-storage volume get --id [uuid] command.
  • Verify the state and status of your Virtual Machine using the virtual-machine instances get --id [uuid] command.
  • Ensure that any file systems on the device within your operating system are unmounted before detaching the Volume.

Troubleshooting

  • A failure during detachment can result in the Volume becoming stuck in the busy state. If this occurs, detachment may be delayed indefinitely until you unmount the Volume, force detachment, reboot the instance, or perform all three.
path Parameters
id
required
string <uuid> (Id)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

backups

List all backups.

Retrieve a list of Backups for the currently authenticated tenant.

Notes

  • Use the expand argument to obtain additional details about the Volume used to create each Backup.
query Parameters
expand
Array of strings (Expand)
Default: ""
Items Value: "volume"
_limit
integer ( Limit) > 0
Default: 50
_offset
integer ( Offset) >= 0
Default: 0
_sort
string ( Sort) ^(^[\w-]+:(asc|desc)(,[\w-]+:(asc|desc))*)?$
Default: "created_at:asc"
Name (string) or Name (null) (Name)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "backups": [
    ]
}

Create a backup.

Create a backup for the currently authenticated tenant.

The Backup can be used when it reaches the "available" state and the "completed" status.

Rules

  • The Backup name must be unique; otherwise, the creation will be disallowed.
  • The Volume can be either in in-use or available states.
  • The Volume must not have an operation in execution.

Notes

  • Use the block-storage volume list command to retrieve a list of all Volumes and obtain the ID of the Volume that will be used to create the Backup.
header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
Description (string) or Description (null) (Description)
required
IdRequest (object) or Name (object) (Volume)
name
required
string (Name)
type
string (BackupType)
Default: "full"
Enum: "full" "incremental"

Responses

Request samples

Content type
application/json
{
  • "description": "my-backup",
  • "name": "backup name",
  • "type": "full",
  • "volume": {
    }
}

Response samples

Content type
application/json
{
  • "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Copy backup cross region.

Copy a backup cross region for the currently authenticated tenant.

Rules

  • The copy only be accepted when the destiny region is different from origin region.
  • The copy only be accepted if the backup's name in destiny region is different from input name.
  • The copy only be accepted if the user has access to destiny region.

Notes

  • Utilize the block-storage backups list command to retrieve a list of all Backups and obtain the ID of the Backup you wish to copy across different region.
header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
destiny_region
required
string (Destiny Region) [ 1 .. 255 ] characters
required
object (BackupIdRequest)

Responses

Request samples

Content type
application/json
{
  • "backup": {
    },
  • "destiny_region": "br-ne1"
}

Response samples

Content type
application/json
[
  • {
    }
]

Delete a backup.

Delete a Backup for the currently authenticated tenant.

Rules

  • The Backup's status must be "completed".
  • The Backup's state must be "available".

Notes

  • Utilize the block-storage backups list command to retrieve a list of all Backups and obtain the ID of the Backup you wish to delete.
path Parameters
id
required
string <uuid> (Id)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve the details of a specific backup.

Retrieve details of a Backup for the currently authenticated tenant.

Notes

  • Use the expand argument to obtain additional details about the Volume used to create the Backup.
  • Utilize the block-storage backups list command to retrieve a list of all Backups and obtain the ID of the Backup for which you want to retrieve details.
path Parameters
id
required
string <uuid> (Id)
query Parameters
expand
Array of strings (Expand)
Default: ""
Items Value: "volume"
header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "created_at": "2022-01-01T00:00:10Z",
  • "description": "my backup for testing",
  • "error": {
    },
  • "id": "c2ea3568-0298-43ea-986a-f27ce3cf182b",
  • "name": "My backup",
  • "size": 10,
  • "source_backup": {
    },
  • "state": "available",
  • "status": "completed",
  • "type": "incremental",
  • "updated_at": "2022-01-01T00:00:10Z",
  • "volume": {
    }
}

Rename a backup.

Patches a Backup for the currently authenticated tenant.

Rules

  • The Backup name must be unique; otherwise, renaming will not be allowed.
  • The Backup's state must be available.

Notes

  • Utilize the block-storage backups list command to retrieve a list of all Backups and obtain the ID of the Backup you wish to rename.
path Parameters
id
required
string <uuid> (Id)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)

Responses

Request samples

Content type
application/json
{
  • "description": "new description to my resource",
  • "name": "new name to my resource"
}

Response samples

Content type
application/json
[
  • {
    }
]

healthchecks

Health Check

Check api status

Responses

Response samples

Content type
application/json
{
  • "status": "OK"
}

Liveness

Liveness probe

Responses