Volumes

Volumes of the project

GET /volumes

Parameters

Name	In	Type	Required	Description
page	query	integer	No	(minimum 1, default 1)
per_page	query	integer	No	(minimum 1, maximum 100, default 25)
name	query	string	No	Exact name (maximum length 64)
label_selector	query	string	No	key, !key, key==v, key=v, key!=v, key in (a,b), key notin (a,b); comma-separated (and) (maximum length 1024)
sort	query	string	No	<field>:asc|desc; fields id, name, created; default created:desc (pattern ^(id|name|created):(asc|desc)$)
q	query	string	No	Every word must match, in any case: part of the name, or label:key, label:key=value (minimum length 2, maximum length 100)
status	query	creating, available	No

Responses

Status	Description
200	Volumes
401	No valid API key
403	The key's scope or the organization's subscription does not allow the request (forbidden), or a quota is exhausted (resource_limit_exceeded)
422	A field is missing or malformed (invalid_input, details.fields) or an Idempotency-Key was reused with a different request (idempotency_key_mismatch)
429	The key's allowance is used up

Response body

Field	Type	Required	Description
volumes	array of Volume	Yes
meta	Meta	Yes

Create a volume

POST /volumes

Counts against the volume quota. Either location or server is given.

Parameters

Name	In	Type	Required	Description
Idempotency-Key	header	string	No	16-128 visible ASCII characters; the first response is replayed for 24 hours (pattern ^[\x21-\x7e]{16,128}$)

Request body

Field	Type	Required	Description
name	string	Yes	1-64 printable characters without @ (minimum length 1, maximum length 64)
size_gb	integer	Yes	(minimum 10, maximum 10000)
location	Reference	No
server	Reference	No
automount	boolean	No	(default false)
format	ext4, xfs	No
labels	map of string	No	At most 32 keys; keys and values of 1-63 (values may be empty) letters, digits, ., _, -, starting and ending with a letter or digit

Responses

Status	Description
201	The volume (creating), its action and the attach action when a server was given
401	No valid API key
403	The key's scope or the organization's subscription does not allow the request (forbidden), or a quota is exhausted (resource_limit_exceeded)
409	The request conflicts with the resource's state (conflict) or an Idempotency-Key is still being processed (idempotency_in_progress)
422	A field is missing or malformed (invalid_input, details.fields) or an Idempotency-Key was reused with a different request (idempotency_key_mismatch)
429	The key's allowance is used up

Response body

Field	Type	Required	Description
volume	Volume	Yes
action	Action	Yes
next_actions	array of Action	Yes

One volume

GET /volumes/{id}

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	Yes

Responses

Status	Description
200	The volume
401	No valid API key
404	No such resource in this project
429	The key's allowance is used up

Response body

Field	Type	Required	Description
volume	Volume	Yes

Rename or relabel a volume

PUT /volumes/{id}

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	Yes

Request body

Field	Type	Required	Description
name	string	No	1-64 printable characters without @ (minimum length 1, maximum length 64)
labels	map of string	No	At most 32 keys; keys and values of 1-63 (values may be empty) letters, digits, ., _, -, starting and ending with a letter or digit

Responses

Status	Description
200	The volume
401	No valid API key
403	The key's scope or the organization's subscription does not allow the request (forbidden), or a quota is exhausted (resource_limit_exceeded)
404	No such resource in this project
409	The request conflicts with the resource's state (conflict) or an Idempotency-Key is still being processed (idempotency_in_progress)
422	A field is missing or malformed (invalid_input, details.fields) or an Idempotency-Key was reused with a different request (idempotency_key_mismatch)
423	The resource has a running action
429	The key's allowance is used up

Response body

Field	Type	Required	Description
volume	Volume	Yes

Delete a volume

DELETE /volumes/{id}

Refused while attached or while protection.delete is on (409).

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	Yes

Responses

Status	Description
204	Deleted
401	No valid API key
403	The key's scope or the organization's subscription does not allow the request (forbidden), or a quota is exhausted (resource_limit_exceeded)
404	No such resource in this project
409	The request conflicts with the resource's state (conflict) or an Idempotency-Key is still being processed (idempotency_in_progress)
423	The resource has a running action
429	The key's allowance is used up

Actions of a volume

GET /volumes/{id}/actions

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	Yes
page	query	integer	No	(minimum 1, default 1)
per_page	query	integer	No	(minimum 1, maximum 100, default 25)
status	query	running, success, error	No
sort	query	string	No	<field>:asc|desc; fields id, command, status, started, finished; default started:desc (pattern ^(id|command|status|started|finished):(asc|desc)$)

Responses

Status	Description
200	Actions
401	No valid API key
404	No such resource in this project
422	A field is missing or malformed (invalid_input, details.fields) or an Idempotency-Key was reused with a different request (idempotency_key_mismatch)
429	The key's allowance is used up

Response body

Field	Type	Required	Description
actions	array of Action	Yes
meta	Meta	Yes

One action of a volume

GET /volumes/{id}/actions/{action_id}

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	Yes
action_id	path	string (uuid)	Yes

Responses

Status	Description
200	The action
401	No valid API key
404	No such resource in this project
429	The key's allowance is used up

Response body

Field	Type	Required	Description
action	Action	Yes

Attach a volume to a server in the same location

POST /volumes/{id}/actions/attach

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	Yes
Idempotency-Key	header	string	No	16-128 visible ASCII characters; the first response is replayed for 24 hours (pattern ^[\x21-\x7e]{16,128}$)

Request body

Field	Type	Required	Description
server	Reference	Yes
automount	boolean	No	(default false)

Responses

Status	Description
201	The action
401	No valid API key
403	The key's scope or the organization's subscription does not allow the request (forbidden), or a quota is exhausted (resource_limit_exceeded)
404	No such resource in this project
409	The request conflicts with the resource's state (conflict) or an Idempotency-Key is still being processed (idempotency_in_progress)
422	A field is missing or malformed (invalid_input, details.fields) or an Idempotency-Key was reused with a different request (idempotency_key_mismatch)
423	The resource has a running action
429	The key's allowance is used up

Response body

Field	Type	Required	Description
action	Action	Yes

Detach a volume

POST /volumes/{id}/actions/detach

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	Yes
Idempotency-Key	header	string	No	16-128 visible ASCII characters; the first response is replayed for 24 hours (pattern ^[\x21-\x7e]{16,128}$)

Responses

Status	Description
201	The action
401	No valid API key
403	The key's scope or the organization's subscription does not allow the request (forbidden), or a quota is exhausted (resource_limit_exceeded)
404	No such resource in this project
409	The request conflicts with the resource's state (conflict) or an Idempotency-Key is still being processed (idempotency_in_progress)
422	A field is missing or malformed (invalid_input, details.fields) or an Idempotency-Key was reused with a different request (idempotency_key_mismatch)
423	The resource has a running action
429	The key's allowance is used up

Response body

Field	Type	Required	Description
action	Action	Yes

Grow a volume

POST /volumes/{id}/actions/resize

Only growth; counts against the volume quota.

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	Yes
Idempotency-Key	header	string	No	16-128 visible ASCII characters; the first response is replayed for 24 hours (pattern ^[\x21-\x7e]{16,128}$)

Request body

Field	Type	Required	Description
size_gb	integer	Yes	(minimum 10, maximum 10000)

Responses

Status	Description
201	The action
401	No valid API key
403	The key's scope or the organization's subscription does not allow the request (forbidden), or a quota is exhausted (resource_limit_exceeded)
404	No such resource in this project
409	The request conflicts with the resource's state (conflict) or an Idempotency-Key is still being processed (idempotency_in_progress)
422	A field is missing or malformed (invalid_input, details.fields) or an Idempotency-Key was reused with a different request (idempotency_key_mismatch)
423	The resource has a running action
429	The key's allowance is used up

Response body

Field	Type	Required	Description
action	Action	Yes

Protect a volume from deletion

POST /volumes/{id}/actions/change_protection

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	Yes
Idempotency-Key	header	string	No	16-128 visible ASCII characters; the first response is replayed for 24 hours (pattern ^[\x21-\x7e]{16,128}$)

Request body

Field	Type	Required	Description
delete	boolean	Yes

Responses

Status	Description
201	The action
401	No valid API key
403	The key's scope or the organization's subscription does not allow the request (forbidden), or a quota is exhausted (resource_limit_exceeded)
404	No such resource in this project
409	The request conflicts with the resource's state (conflict) or an Idempotency-Key is still being processed (idempotency_in_progress)
422	A field is missing or malformed (invalid_input, details.fields) or an Idempotency-Key was reused with a different request (idempotency_key_mismatch)
423	The resource has a running action
429	The key's allowance is used up

Response body

Field	Type	Required	Description
action	Action	Yes