Servers

Servers of the project

GET /servers

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, status, server_type; default created:desc (pattern ^(id|name|created|status|server_type):(asc|desc)$)
q	query	string	No	Every word must match, in any case: part of the name or a public address, or label:key, label:key=value (minimum length 2, maximum length 100)
status	query	initializing, starting, running, stopping, off, deleting, rebuilding, migrating, unknown	No
busy	query	boolean	No	true: a running action or a transitional status; false: neither

Responses

Status	Description
200	Servers
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
servers	array of Server	Yes
meta	Meta	Yes

Create a server

POST /servers

Counts against the project's servers, vcpu, ram and volume quota (403 resource_limit_exceeded).

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

Exactly one of image and snapshot. A snapshot gives only its root disk; it must be of this project and location, and the server type's disk no smaller than the snapshot.

Field	Type	Required	Description
name	string	Yes	1-64 printable characters without @ (minimum length 1, maximum length 64)
server_type	Reference	Yes
image	Reference	No
snapshot	Reference	No
location	Reference	Yes
ssh_keys	array of Reference	No	(at most items 20)
networks	array of Reference	No	(at most items 10)
firewalls	array of Reference	No	(at most items 5)
user_data	string	No	cloud-init user data; at most 24 KiB (24576 bytes in UTF-8). A longer value is 422 user_data malformed. (maximum length 24576)
start_after_create	boolean	No	(default true)
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
console_password_hash	string	No	Optional console password for the image's default user (Image.default_user), as a SHA-512 crypt hash only: the password never reaches Netface. SSH stays key-only. The hash goes to the server's user data last, after user_data, and is taken away once the server has started; the two together are limited to 24576 bytes. Not offered for an image without a default user, nor with a user_data that is itself a MIME multipart. (pattern ^\$6\$(rounds=[1-9][0-9]{3,8}\$)?[./0-9A-Za-z]{1,16}\$[./0-9A-Za-z]{86}$)

Responses

Status	Description
201	The server (initializing) and the create 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)
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
server	Server	Yes
action	Action	Yes
root_password	string or null	Yes	Reserved; null in this version. Sign in with an SSH key or the console password.

One server

GET /servers/{id}

Parameters

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

Responses

Status	Description
200	The server
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
server	Server	Yes

Rename or relabel a server

PUT /servers/{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 server
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
server	Server	Yes

Delete a server

DELETE /servers/{id}

Refused while protection.delete is on (409). Releases the server's quota when the action succeeds.

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	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)
423	The resource has a running action
429	The key's allowance is used up

Response body

Field	Type	Required	Description
action	Action	Yes

Actions of a server

GET /servers/{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 server

GET /servers/{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

Power a server on

POST /servers/{id}/actions/poweron

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

Cut a server's power (hard)

POST /servers/{id}/actions/poweroff

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

Shut a server down (ACPI)

POST /servers/{id}/actions/shutdown

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

Reboot a server (ACPI)

POST /servers/{id}/actions/reboot

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

Reset a server (hard)

POST /servers/{id}/actions/reset

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

Change the server type

POST /servers/{id}/actions/resize

The server must be off. Counts against the vcpu, ram and 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
server_type	Reference	Yes
upgrade_disk	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

Rebuild a server from an image or a snapshot

POST /servers/{id}/actions/rebuild

Exactly one of image and snapshot. Everything on the root disk is replaced; a failed rebuild may already have replaced it (the action then ends resolution_required).

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
image	Reference	No
snapshot	Reference	No
console_password_hash	string	No	Optional new console password for the image's default user, as a SHA-512 crypt hash only. A password set earlier does not carry over a rebuild. The hash is taken away once the server has started. Not offered with snapshot, nor for an image without a default user; a server whose user_data cannot take it (a MIME multipart, or over 24576 bytes together) ends the action provider_refused, with the disk untouched. (pattern ^\$6\$(rounds=[1-9][0-9]{3,8}\$)?[./0-9A-Za-z]{1,16}\$[./0-9A-Za-z]{86}$)

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

Snapshot a server's disk

POST /servers/{id}/actions/create_snapshot

Counts against the snapshot 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
name	string	Yes	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
201	The snapshot (creating) and its 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
snapshot	Snapshot	Yes
action	Action	Yes

Attach a server to a private network

POST /servers/{id}/actions/attach_to_network

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
network	Reference	Yes
ip	string	No	A free address of the network's subnet; chosen by the platform when absent (maximum length 45)

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 server from a private network

POST /servers/{id}/actions/detach_from_network

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
network	Reference	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

Protect a server from deletion

POST /servers/{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

A short-lived console link of a running server

POST /servers/{id}/actions/request_console

Only a running server (409 conflict, details.reason = invalid_state) and only a read_write key or person, also while the subscription is restricted. No body and no Idempotency-Key (422 invalid_input): the link is returned once, to this requester, and is never stored for a replay. Opening the link gives full access to the server's screen and keyboard; treat it as a secret until expires_at (at most 60 seconds; the link works once). When the link is not ready within seconds the request is 503 unavailable with Retry-After and the link is never returned later; ask again. A location that offers no console is 409 conflict with details.reason = not_offered and details.action (the action ends with the error code not_offered); asking again does not help. A console allowance per server and per requester applies on top of the key's (429).

Parameters

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

Responses

Status	Description
201	The finished action and the link
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
503	The service could not answer in time (unavailable); ask again after Retry-After

Response body

Field	Type	Required	Description
action	Action	Yes
console	object	Yes
console.url	string (uri)	Yes	Opens the console in a browser
console.expires_at	string (date-time)	Yes