Objects

The objects the operations of the Netface API take and return.

Reference

A reference to another resource of the project, by id

Field	Type	Required	Description
id	string (uuid)	Yes

NamedReference

Field	Type	Required	Description
id	string (uuid)	Yes
name	string	Yes	(maximum length 64)

NullableNamedReference

One of: NamedReference, null

Protection

Field	Type	Required	Description
delete	boolean	Yes

ProtectionRequest

Field	Type	Required	Description
delete	boolean	Yes

NameLabelsUpdateRequest

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

ErrorResponse

Field	Type	Required	Description
error	Error	Yes

Error

Field	Type	Required	Description
code	unauthenticated, forbidden, resource_limit_exceeded, not_found, method_not_allowed, conflict, idempotency_in_progress, invalid_input, idempotency_key_mismatch, locked, rate_limit_exceeded, internal_error, unavailable	Yes
message	string	Yes	A fixed English text; clients localize by code
details	object	Yes	forbidden: reason (scope_missing, entitlement_inactive, entitlement_restricted); resource_limit_exceeded: metric, limit, used; invalid_input: fields ([{name, message}]); locked: action (the running action's id)

Meta

Field	Type	Required	Description
pagination	Pagination	Yes

Pagination

Field	Type	Required	Description
page	integer	Yes	(minimum 1)
per_page	integer	Yes	(minimum 1, maximum 100)
previous_page	integer or null	Yes	(minimum 1)
next_page	integer or null	Yes	(minimum 1)
last_page	integer	Yes	(minimum 1)
total_entries	integer	Yes	(minimum 0)

Action

Field	Type	Required	Description
id	string (uuid)	Yes
command	string	Yes	create_server, delete_server, poweron_server, ... (snake_case, closed per resource) (pattern ^[a-z][a-z0-9_]{1,63}$)
actor	object	Yes	Who started the action - a person through the Console (user) or an API key; never a name or address
actor.type	user, api_key	Yes
actor.id	string (uuid)	Yes
status	running, success, error	Yes
progress	integer	Yes	(minimum 0, maximum 100)
started	string (date-time)	Yes	RFC 3339, UTC
finished	string or null (date-time)	Yes
error	null or object	Yes
error.code	string	Yes	(pattern ^[a-z][a-z0-9_]{1,63}$)
error.message	string	Yes
resources	array of object	Yes
resources[].id	string (uuid)	Yes
resources[].type	server, network, firewall, floating_ip, volume, snapshot, ssh_key	Yes

ActionList

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

Project

Field	Type	Required	Description
id	string (uuid)	Yes
slug	string	Yes	(pattern ^[a-z0-9][a-z0-9-]{0,38}[a-z0-9]$)
name	string	Yes	(maximum length 120)
labels	map of string	Yes	At most 32 keys; keys and values of 1-63 (values may be empty) letters, digits, ., _, -, starting and ending with a letter or digit
status	active, archived	Yes
created	string (date-time)	Yes	RFC 3339, UTC

ApiKey

Field	Type	Required	Description
id	string (uuid)	Yes
name	string	Yes	1-64 printable characters without @ (minimum length 1, maximum length 64)
prefix	string	Yes	nfk_<key version>_ and the first six characters of the secret (pattern ^nfk_[1-9][0-9]{0,5}_[A-Za-z0-9_-]{6}$)
scope	read, read_write	Yes
status	active, revoked	Yes
created	string (date-time)	Yes	RFC 3339, UTC
expires	string or null (date-time)	Yes
last_used	string or null (date-time)	Yes

Location

Field	Type	Required	Description
id	string (uuid)	Yes
name	string	Yes	Netface region code, e.g. ist (pattern ^[a-z]{3}[0-9]?$)
description	string	Yes	(maximum length 120)
country	string	Yes	ISO 3166-1 alpha-2 (pattern ^[A-Z]{2}$)
city	string	Yes	(maximum length 64)
network_zone	string	Yes	(maximum length 32)

ServerType

Field	Type	Required	Description
id	string (uuid)	Yes
name	string	Yes	(pattern ^[a-z][a-z0-9-]{1,31}$)
description	string	Yes	(maximum length 120)
cores	integer	Yes	(minimum 1)
memory_gb	integer	Yes	GiB (minimum 1)
disk_gb	integer	Yes	GB (minimum 1)
cpu_type	shared, dedicated	Yes
architecture	x86, arm	Yes
deprecated	boolean	Yes
locations	array of NamedReference	Yes	The locations that offer this server type now
prices	array of Price	Yes	The monthly prices in force, one per currency (billed per month, prorated per day; taxes excluded). USD is canonical; other currencies are derived from it. Empty when the type has no price yet.

PriceEstimate

Field	Type	Required	Description
currency	string	Yes	(pattern ^[A-Z]{3}$)
currency_source	billing_profile, canonical, requested	Yes
priced	boolean	Yes	false when a line has no price; the total is then null
lines	array of object	Yes
lines[].resource	server_type, volume, floating_ip	Yes
lines[].quantity	integer	Yes	1 server (minimum 1)
lines[].unit	month, gb_month	Yes
lines[].unit_amount_minor	integer or null	Yes	(minimum 0)
lines[].amount_minor	integer or null	Yes	(minimum 0)
total_minor	integer or null	Yes	One month in the currency's minor unit (minimum 0)

UnitPricing

Field	Type	Required	Description
unit	month, gb_month	Yes	month is per address and month; gb_month per GB and month
prices	array of Price	Yes	One per currency; empty when the resource has no price yet

Price

Field	Type	Required	Description
currency	string	Yes	(pattern ^[A-Z]{3}$)
monthly_amount_minor	integer	Yes	The amount for one month (per server, per GB or per address) in the currency's minor unit (minimum 0)
origin	list, derived, synthetic	Yes	list is set directly and derived comes from the USD price; synthetic appears only in test environments
effective_from	string (date-time)	Yes

Image

Field	Type	Required	Description
id	string (uuid)	Yes
type	system	Yes
status	available, unavailable	Yes
name	string	Yes	(maximum length 64)
description	string	Yes	(maximum length 120)
os_flavor	ubuntu, debian, rocky, alma, fedora, other	Yes
os_version	string	Yes	(maximum length 32)
architecture	x86, arm	Yes
disk_size_gb	integer	Yes	(minimum 1)
default_user	string or null	No	The user the image's cloud-init creates, for ssh <user>@<address>; null when it is not known. SSH uses the keys given at creation; a console password is optional (console_password_hash). (maximum length 32)
created	string (date-time)	Yes	RFC 3339, UTC
labels	map of string	Yes	At most 32 keys; keys and values of 1-63 (values may be empty) letters, digits, ., _, -, starting and ending with a letter or digit
locations	array of NamedReference	Yes	The locations that offer this image now

SshKey

Field	Type	Required	Description
id	string (uuid)	Yes
name	string	Yes	1-64 printable characters without @ (minimum length 1, maximum length 64)
fingerprint	string	Yes	SHA256: and the base64 digest of the public key (maximum length 128)
public_key	string	Yes	(maximum length 4096)
labels	map of string	Yes	At most 32 keys; keys and values of 1-63 (values may be empty) letters, digits, ., _, -, starting and ending with a letter or digit
created	string (date-time)	Yes	RFC 3339, UTC

SshKeyCreateRequest

Field	Type	Required	Description
name	string	Yes	1-64 printable characters without @ (minimum length 1, maximum length 64)
public_key	string	Yes	ssh-ed25519 ... or ssh-rsa ... (OpenSSH format) (maximum length 4096)
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

Server

Field	Type	Required	Description
id	string (uuid)	Yes
name	string	Yes	1-64 printable characters without @ (minimum length 1, maximum length 64)
status	initializing, starting, running, stopping, off, deleting, rebuilding, migrating, unknown	Yes
created	string (date-time)	Yes	RFC 3339, UTC
server_type	NamedReference	Yes
image	NullableNamedReference	Yes
location	NamedReference	Yes
public_net	object	Yes
public_net.ipv4	null or object	Yes
public_net.ipv4.ip	string	Yes	(maximum length 15)
public_net.ipv4.dns_ptr	string or null	Yes	(maximum length 253)
public_net.ipv6	null or object	Yes
public_net.ipv6.ip	string	Yes	An IPv4 or IPv6 range in CIDR notation (maximum length 49)
public_net.floating_ips	array of string (uuid)	Yes
private_net	array of object	Yes
private_net[].network	string (uuid)	Yes
private_net[].ip	string	Yes	(maximum length 45)
volumes	array of string (uuid)	Yes
firewalls	array of string (uuid)	Yes
labels	map of string	Yes	At most 32 keys; keys and values of 1-63 (values may be empty) letters, digits, ., _, -, starting and ending with a letter or digit
locked	boolean	Yes	An action is running on this server
protection	Protection	Yes

ServerCreateRequest

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}$)

Network

Field	Type	Required	Description
id	string (uuid)	Yes
name	string	Yes	1-64 printable characters without @ (minimum length 1, maximum length 64)
ip_range	string	Yes	An IPv4 or IPv6 range in CIDR notation (maximum length 49)
subnets	array of object	Yes
subnets[].ip_range	string	Yes	An IPv4 or IPv6 range in CIDR notation (maximum length 49)
subnets[].gateway	string	Yes	(maximum length 45)
servers	array of string (uuid)	Yes
labels	map of string	Yes	At most 32 keys; keys and values of 1-63 (values may be empty) letters, digits, ., _, -, starting and ending with a letter or digit
created	string (date-time)	Yes	RFC 3339, UTC
locked	boolean	Yes
protection	Protection	Yes

NetworkCreateRequest

Field	Type	Required	Description
name	string	Yes	1-64 printable characters without @ (minimum length 1, maximum length 64)
ip_range	string	Yes	An IPv4 or IPv6 range in CIDR notation (maximum length 49)
subnets	array of object	No	(at most items 50)
subnets[].ip_range	string	Yes	An IPv4 or IPv6 range in CIDR notation (maximum length 49)
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

FirewallRule

Field	Type	Required	Description
direction	in, out	Yes
protocol	tcp, udp, icmp, esp, gre	Yes
port	string or null	Yes	80 or 1024-2048; null for icmp, esp and gre (pattern ^[0-9]{1,5}(-[0-9]{1,5})?$)
source_ips	array of string	Yes	(at most items 100)
destination_ips	array of string	Yes	(at most items 100)
description	string or null	Yes	(maximum length 200)

FirewallTarget

Field	Type	Required	Description
type	server	Yes
server	Reference	Yes

Firewall

Field	Type	Required	Description
id	string (uuid)	Yes
name	string	Yes	1-64 printable characters without @ (minimum length 1, maximum length 64)
rules	array of FirewallRule	Yes	(at most items 50)
applied_to	array of FirewallTarget	Yes
labels	map of string	Yes	At most 32 keys; keys and values of 1-63 (values may be empty) letters, digits, ., _, -, starting and ending with a letter or digit
created	string (date-time)	Yes	RFC 3339, UTC
locked	boolean	Yes

FirewallCreateRequest

Field	Type	Required	Description
name	string	Yes	1-64 printable characters without @ (minimum length 1, maximum length 64)
rules	array of object	No	(at most items 50)
rules[].direction	in, out	Yes
rules[].protocol	tcp, udp, icmp, esp, gre	Yes
rules[].port	string or null	No	(pattern ^[0-9]{1,5}(-[0-9]{1,5})?$)
rules[].source_ips	array of string	No	(at most items 100)
rules[].destination_ips	array of string	No	(at most items 100)
rules[].description	string or null	No	(maximum length 200)
apply_to	array of FirewallTarget	No	(at most items 100)
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

FloatingIp

Field	Type	Required	Description
id	string (uuid)	Yes
name	string	Yes	1-64 printable characters without @ (minimum length 1, maximum length 64)
description	string or null	Yes	(maximum length 200)
ip	string	Yes	The address (IPv4) or the /64 range (IPv6) (maximum length 49)
type	ipv4, ipv6	Yes
server	null or string (uuid)	Yes
location	NamedReference	Yes
dns_ptr	array of object	Yes
dns_ptr[].ip	string	Yes	(maximum length 45)
dns_ptr[].dns_ptr	string	Yes	(maximum length 253)
labels	map of string	Yes	At most 32 keys; keys and values of 1-63 (values may be empty) letters, digits, ., _, -, starting and ending with a letter or digit
created	string (date-time)	Yes	RFC 3339, UTC
blocked	boolean	Yes	Blocked by the platform (abuse)
locked	boolean	Yes
protection	Protection	Yes

FloatingIpCreateRequest

Field	Type	Required	Description
type	ipv4, ipv6	Yes
location	Reference	No
server	Reference	No
name	string	No	1-64 printable characters without @ (minimum length 1, maximum length 64)
description	string	No	(maximum length 200)
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

Volume

Field	Type	Required	Description
id	string (uuid)	Yes
name	string	Yes	1-64 printable characters without @ (minimum length 1, maximum length 64)
size_gb	integer	Yes	(minimum 10, maximum 10000)
status	creating, available	Yes
server	null or string (uuid)	Yes
location	NamedReference	Yes
format	ext4, xfs, null	Yes
linux_device	string or null	Yes	(maximum length 128)
labels	map of string	Yes	At most 32 keys; keys and values of 1-63 (values may be empty) letters, digits, ., _, -, starting and ending with a letter or digit
created	string (date-time)	Yes	RFC 3339, UTC
locked	boolean	Yes
protection	Protection	Yes

VolumeCreateRequest

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

Snapshot

Field	Type	Required	Description
id	string (uuid)	Yes
name	string	Yes	1-64 printable characters without @ (minimum length 1, maximum length 64)
status	creating, available, deleting	Yes
server	NullableNamedReference	Yes
size_gb	integer	Yes	(minimum 0)
labels	map of string	Yes	At most 32 keys; keys and values of 1-63 (values may be empty) letters, digits, ., _, -, starting and ending with a letter or digit
created	string (date-time)	Yes	RFC 3339, UTC
locked	boolean	Yes