AnkraDocs
Console

API reference · Networking

Networks, routers and floating IPs

22 operations of the Ankra Cloud API: Private networks, routers, floating IPs, server interfaces and firewalls.

List floating IPs#

GET/v1/floating-ips
Operation
list_floating_ips
Credentials
API token, Portal session
Requires
Permission read

Keyset-paginated, newest first: limit is 1 to 100 (default 50) and next_cursor is null on the last page; pass it back as cursor for the next one. A malformed cursor or a limit out of range is a 400.

Parameters

Parameters
NameInTypeDescription
cursorquerystringThe next_cursor of the previous page.
limitqueryintegerPage size; the server applies its default and maximum.

Responses

200A page of floating IPs, newest first.application/json · FloatingIPList

200 response fields
FieldTypeDescription
itemsrequiredarray of FloatingIP
idrequiredstring
zonerequiredstring
addressrequiredstring
server_idrequiredstring | null
targetrequiredstring | nullpublic, private:<network_id>, or null while unassigned.
requires_restartrequiredbooleanAssigning or unassigning restarts a running server: the address becomes the server's own public IPv4, so the server must not hold another. Such a floating IP counts against the account's public_ipv4_addresses limit and not against floating_ips.
created_atrequiredstring (date-time)
next_cursorrequiredstring | nullPass as ?cursor= for the next page; null on the last page.
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/floating-ips' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Allocate a floating IP, optionally assigning it at once#

POST/v1/floating-ips
Operation
allocate_floating_ip
Credentials
API token, Portal session
Requires
Permission operate

With server_id the target is checked first and the address is allocated and assigned in one step, so a refused assignment (400 / 404) keeps no address. Ankra assigns the address; a request names the zone only. The floating IP is held under one limit, by where the zone takes its address from: one the zone's gateways forward (its requires_restart is false) counts against floating_ips, and one that becomes the server's own public IPv4 (requires_restart true) counts against public_ipv4_addresses and not against floating_ips, once, whether or not it is assigned. Past that limit the answer is 422, naming the limit.

Parameters

Parameters
NameInTypeDescription
Idempotency-KeyheaderstringA key the client chooses for this create, for example a UUID. The same create sent again with the same key within 24 hours answers the first one's answer with Idempotent-Replayed: true and creates nothing. 409 with reason: idempotency_key_in_progress while the first request is still running (try again shortly), with reason: idempotency_key_outcome_unknown when the first request answered 5xx or never finished (the create may or may not exist: list the resource before creating again with a new key), or with reason: idempotency_key_answer_not_stored when the create succeeded but its answer could not be kept (read the resource). 422 with reason: idempotency_key_reused when the key was used with a different request, 400 when the key is not 1 to 255 visible ASCII characters. Only a 4xx answer frees a key before the 24 hours.

Request bodyapplication/json

Request body fields
FieldTypeDescription
zonerequiredstring
server_idstring
targetstringpublic (the default) forwards to the server's public address; private:<network_id> to its interface on that network, which must be attached to a router with NAT enabled.

Responses

201The floating IP; operation is present when it is being assigned.application/json

201 response fields
FieldTypeDescription
floating_iprequiredFloatingIP
idrequiredstring
zonerequiredstring
addressrequiredstring
server_idrequiredstring | null
targetrequiredstring | nullpublic, private:<network_id>, or null while unassigned.
requires_restartrequiredbooleanAssigning or unassigning restarts a running server: the address becomes the server's own public IPv4, so the server must not hold another. Such a floating IP counts against the account's public_ipv4_addresses limit and not against floating_ips.
created_atrequiredstring (date-time)
operationOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 402The account may not create this. reason is payment_method_required while it has no default payment method and its credit does not cover the create: the credit left must cover one month, at monthly list prices, of everything the account already runs plus what the create adds (add a payment method through POST /v1/account/billing/setup-session, or free what the account no longer needs); owner_approval_required while its owner has not approved paid usage and no credit is left; or account_suspended while an invoice is overdue past the grace period (pay it) or Ankra staff suspended the account (contact support). A prepaid account (linked to an Ankra platform organisation) is refused with payment_method_required while it has no card, and with credit_required once it has one but its credit does not cover the create: Cloud never charges its card, so only a top-up on the Ankra platform lifts it, and top_up_url names that page when Cloud knows it. GET /v1/account/billing reports the same standing. For payment_method_required and credit_required, detail names what the create costs, the credit left and the committed monthly spend only to a principal that may read billing (billing.read, and for an API token a scope that includes it); anyone else is told only that the credit does not cover it.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 422The account would exceed a quota; detail names the limit and reason is quota_exceeded.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • 503No capacity or address is free in the zone right now (reason: capacity_unavailable, with availability wording in detail), or a host did not answer; try another plan or zone, or try again later.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/floating-ips' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "zone": "string"
}'

Get a floating IP#

GET/v1/floating-ips/{id}
Operation
get_floating_ip
Credentials
API token, Portal session
Requires
Permission read

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200The floating IP.application/json

200 response fields
FieldTypeDescription
floating_iprequiredFloatingIP
idrequiredstring
zonerequiredstring
addressrequiredstring
server_idrequiredstring | null
targetrequiredstring | nullpublic, private:<network_id>, or null while unassigned.
requires_restartrequiredbooleanAssigning or unassigning restarts a running server: the address becomes the server's own public IPv4, so the server must not hold another. Such a floating IP counts against the account's public_ipv4_addresses limit and not against floating_ips.
created_atrequiredstring (date-time)
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/floating-ips/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Release a floating IP to the pool#

DELETE/v1/floating-ips/{id}
Operation
release_floating_ip
Credentials
API token, Portal session
Requires
Permission operate

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

202Accepted; poll the operation.application/json · OperationEnvelope

202 response fields
FieldTypeDescription
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X DELETE 'https://cloud.ankra.app/v1/floating-ips/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Move a floating IP to a server, or unassign it#

POST/v1/floating-ips/{id}/assign
Operation
assign_floating_ip
Credentials
API token, Portal session
Requires
Permission operate

For a floating IP whose requires_restart is true, assigning and unassigning restart a running server, the server must not hold another public IPv4 (remove it first; 409 otherwise), and moving the address is an unassignment followed by an assignment.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Request bodyapplication/json

Request body fields
FieldTypeDescription
server_idstring | nullA null (or missing) server_id unassigns the floating IP.
targetstringpublic (the default) forwards to the server's public address; private:<network_id> to its interface on that network, which must be attached to a router with NAT enabled.

Responses

202Accepted; poll the operation.application/json · OperationEnvelope

202 response fields
FieldTypeDescription
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/floating-ips/<id>/assign' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "server_id": "string",
  "target": "string"
}'

List private networks#

GET/v1/networks
Operation
list_networks
Credentials
API token, Portal session
Requires
Permission read

Keyset-paginated, newest first: limit is 1 to 100 (default 50) and next_cursor is null on the last page; pass it back as cursor for the next one. A malformed cursor or a limit out of range is a 400.

Parameters

Parameters
NameInTypeDescription
cursorquerystringThe next_cursor of the previous page.
limitqueryintegerPage size; the server applies its default and maximum.

Responses

200A page of private networks, newest first.application/json · NetworkList

200 response fields
FieldTypeDescription
itemsrequiredarray of Network
idrequiredstring
zonerequiredstringThe home zone, where a router of the network lives.
regionrequiredstring
zonesrequiredarray of stringEvery zone of region the network is present in, sorted.
namerequiredstring
cidrrequiredstringThe IPv4 subnet, shared by every zone the network spans.
ula_prefixrequiredstringThe network's IPv6 ULA /64, the same in every zone it spans.
gatewayrequiredstringThe first host address, reserved for a router.
router_idrequiredstring | null
membersarray of InterfaceOnly in GET /v1/networks/{id}.
idrequiredstring
server_idrequiredstring
network_idrequiredstring
addressrequiredstring
address6requiredstringThe leg's address on the network's ULA /64 (every leg carries one, derived from the network and address).
mac_addressrequiredstring
device_indexrequiredinteger
created_atrequiredstring (date-time)
next_cursorrequiredstring | nullPass as ?cursor= for the next page; null on the last page.
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/networks' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Create a private network#

POST/v1/networks
Operation
create_network
Credentials
API token, Portal session
Requires
Permission operate

cidr is RFC 1918, /16 … /29, and may not overlap any public address pool or the reserved infrastructure ranges (400). zone is the network's home zone (where a router of it lives); zones lists the zones of the home zone's region the network is present in (default: the home zone alone). A network in several zones is one layer-2 segment across them: its ULA /64 and IPv4 subnet are shared, servers of every listed zone join it, and broadcast stays inside each zone (ARP/ND are answered from EVPN).

Request bodyapplication/json

Request body fields
FieldTypeDescription
zonerequiredstring
namerequiredstring
cidrrequiredstring
zonesarray of stringZones of the home zone's region; the home zone is added when missing.

Responses

201The network.application/json · NetworkEnvelope

201 response fields
FieldTypeDescription
networkrequiredNetwork
idrequiredstring
zonerequiredstringThe home zone, where a router of the network lives.
regionrequiredstring
zonesrequiredarray of stringEvery zone of region the network is present in, sorted.
namerequiredstring
cidrrequiredstringThe IPv4 subnet, shared by every zone the network spans.
ula_prefixrequiredstringThe network's IPv6 ULA /64, the same in every zone it spans.
gatewayrequiredstringThe first host address, reserved for a router.
router_idrequiredstring | null
membersarray of InterfaceOnly in GET /v1/networks/{id}.
idrequiredstring
server_idrequiredstring
network_idrequiredstring
addressrequiredstring
address6requiredstringThe leg's address on the network's ULA /64 (every leg carries one, derived from the network and address).
mac_addressrequiredstring
device_indexrequiredinteger
created_atrequiredstring (date-time)
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 422The account would exceed a quota; detail names the limit and reason is quota_exceeded.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/networks' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "zone": "string",
  "name": "string",
  "cidr": "10.0.0.0/24"
}'

Get a private network with its members#

GET/v1/networks/{id}
Operation
get_network
Credentials
API token, Portal session
Requires
Permission read

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200The network; members is always present here.application/json · NetworkEnvelope

200 response fields
FieldTypeDescription
networkrequiredNetwork
idrequiredstring
zonerequiredstringThe home zone, where a router of the network lives.
regionrequiredstring
zonesrequiredarray of stringEvery zone of region the network is present in, sorted.
namerequiredstring
cidrrequiredstringThe IPv4 subnet, shared by every zone the network spans.
ula_prefixrequiredstringThe network's IPv6 ULA /64, the same in every zone it spans.
gatewayrequiredstringThe first host address, reserved for a router.
router_idrequiredstring | null
membersarray of InterfaceOnly in GET /v1/networks/{id}.
idrequiredstring
server_idrequiredstring
network_idrequiredstring
addressrequiredstring
address6requiredstringThe leg's address on the network's ULA /64 (every leg carries one, derived from the network and address).
mac_addressrequiredstring
device_indexrequiredinteger
created_atrequiredstring (date-time)
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/networks/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Change the zones a private network is present in#

PATCH/v1/networks/{id}
Operation
update_network
Credentials
API token, Portal session
Requires
Permission operate

Sets the zones of the network's region the network spans; the home zone always stays. A zone whose servers are still on the network cannot be removed (409). The gateways of every zone the network spanned or spans are republished by the returned operation.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Request bodyapplication/json

Request body fields
FieldTypeDescription
zonesrequiredarray of string

Responses

202The network and the operation that republishes its zones' gateways.application/json

202 response fields
FieldTypeDescription
networkrequiredNetwork
idrequiredstring
zonerequiredstringThe home zone, where a router of the network lives.
regionrequiredstring
zonesrequiredarray of stringEvery zone of region the network is present in, sorted.
namerequiredstring
cidrrequiredstringThe IPv4 subnet, shared by every zone the network spans.
ula_prefixrequiredstringThe network's IPv6 ULA /64, the same in every zone it spans.
gatewayrequiredstringThe first host address, reserved for a router.
router_idrequiredstring | null
membersarray of InterfaceOnly in GET /v1/networks/{id}.
idrequiredstring
server_idrequiredstring
network_idrequiredstring
addressrequiredstring
address6requiredstringThe leg's address on the network's ULA /64 (every leg carries one, derived from the network and address).
mac_addressrequiredstring
device_indexrequiredinteger
created_atrequiredstring (date-time)
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X PATCH 'https://cloud.ankra.app/v1/networks/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "zones": [
    "string"
  ]
}'

Delete a private network#

DELETE/v1/networks/{id}
Operation
delete_network
Credentials
API token, Portal session
Requires
Permission operate

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

204Deleted.

  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X DELETE 'https://cloud.ankra.app/v1/networks/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

List routers#

GET/v1/routers
Operation
list_routers
Credentials
API token, Portal session
Requires
Permission read

Keyset-paginated, newest first: limit is 1 to 100 (default 50) and next_cursor is null on the last page; pass it back as cursor for the next one. A malformed cursor or a limit out of range is a 400.

Parameters

Parameters
NameInTypeDescription
cursorquerystringThe next_cursor of the previous page.
limitqueryintegerPage size; the server applies its default and maximum.

Responses

200A page of routers, newest first, each with its attached networks.application/json · RouterList

200 response fields
FieldTypeDescription
itemsrequiredarray of Router
idrequiredstring
zonerequiredstring
namerequiredstring
nat_enabledrequiredboolean
nat_addressrequiredstring | null
nat_address_billedrequiredbooleanWhether the NAT address is a public IPv4 address, billed at the public IPv4 price (€4.00 a month, a public_ipv4 usage line under the router's name) for as long as the router holds it, whatever uplink the NAT gateway is on. False without NAT, and for a NAT address that is not a public address: the NAT gateway then costs its own price alone.
uplinkrequiredstringWhat the router's NAT gateway runs on. shared is the uplink every NAT gateway starts on. dedicated is a 1 Gbit/s connection that only your servers use; Ankra sets it up, so on a router it reads dedicated while the request is pending or active (see dedicated_uplink.state) and shared otherwise.One of shared, dedicated
dedicated_uplinkrequiredDedicatedUplink | nullThe router's last request for a dedicated uplink; null when it never asked for one.
staterequiredstringpending waits for Ankra to connect the uplink: the gateway runs on the shared uplink and is billed as a shared NAT gateway. active means it is connected and billed per 30-day term. declined carries Ankra's reason and leaves the gateway on the shared uplink. removed was taken back by the account, by setting the uplink to shared, turning NAT off or deleting the router.One of pending, active, declined, removed
requested_atrequiredstring (date-time)
activated_atrequiredstring (date-time) | nullWhen Ankra activated it: the start of the first 30-day term and of its billing.
term_ends_atrequiredstring (date-time) | nullWhile active: when the term already charged ends and the next one starts.
decline_reasonrequiredstring | nullWhen declined: what Ankra said.
networksrequiredarray of Network
idrequiredstring
zonerequiredstringThe home zone, where a router of the network lives.
regionrequiredstring
zonesrequiredarray of stringEvery zone of region the network is present in, sorted.
namerequiredstring
cidrrequiredstringThe IPv4 subnet, shared by every zone the network spans.
ula_prefixrequiredstringThe network's IPv6 ULA /64, the same in every zone it spans.
gatewayrequiredstringThe first host address, reserved for a router.
router_idrequiredstring | null
membersarray of InterfaceOnly in GET /v1/networks/{id}.
idrequiredstring
server_idrequiredstring
network_idrequiredstring
addressrequiredstring
address6requiredstringThe leg's address on the network's ULA /64 (every leg carries one, derived from the network and address).
mac_addressrequiredstring
device_indexrequiredinteger
created_atrequiredstring (date-time)
created_atrequiredstring (date-time)
next_cursorrequiredstring | nullPass as ?cursor= for the next page; null on the last page.
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/routers' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Create a router, optionally a NAT gateway#

POST/v1/routers
Operation
create_router
Credentials
API token, Portal session
Requires
Permission operate

503 when no NAT address is free (then no router is created). uplink is shared when left out. With uplink: dedicated the router is created as a NAT gateway and a dedicated uplink is requested for it, exactly as update_router does: it needs nat_enabled: true (400 otherwise), is pending until Ankra has connected it, and until then the gateway runs on the shared uplink and is billed as a shared NAT gateway.

Parameters

Parameters
NameInTypeDescription
Idempotency-KeyheaderstringA key the client chooses for this create, for example a UUID. The same create sent again with the same key within 24 hours answers the first one's answer with Idempotent-Replayed: true and creates nothing. 409 with reason: idempotency_key_in_progress while the first request is still running (try again shortly), with reason: idempotency_key_outcome_unknown when the first request answered 5xx or never finished (the create may or may not exist: list the resource before creating again with a new key), or with reason: idempotency_key_answer_not_stored when the create succeeded but its answer could not be kept (read the resource). 422 with reason: idempotency_key_reused when the key was used with a different request, 400 when the key is not 1 to 255 visible ASCII characters. Only a 4xx answer frees a key before the 24 hours.

Request bodyapplication/json

Request body fields
FieldTypeDescription
zonerequiredstring
namerequiredstring
nat_enabledboolean
uplinkstringWhat the router's NAT gateway runs on. shared is the uplink every NAT gateway starts on. dedicated is a 1 Gbit/s connection that only your servers use; Ankra sets it up, so on a router it reads dedicated while the request is pending or active (see dedicated_uplink.state) and shared otherwise.One of shared, dedicated

Responses

202The router is being set up.application/json

202 response fields
FieldTypeDescription
routerrequiredRouter
idrequiredstring
zonerequiredstring
namerequiredstring
nat_enabledrequiredboolean
nat_addressrequiredstring | null
nat_address_billedrequiredbooleanWhether the NAT address is a public IPv4 address, billed at the public IPv4 price (€4.00 a month, a public_ipv4 usage line under the router's name) for as long as the router holds it, whatever uplink the NAT gateway is on. False without NAT, and for a NAT address that is not a public address: the NAT gateway then costs its own price alone.
uplinkrequiredstringWhat the router's NAT gateway runs on. shared is the uplink every NAT gateway starts on. dedicated is a 1 Gbit/s connection that only your servers use; Ankra sets it up, so on a router it reads dedicated while the request is pending or active (see dedicated_uplink.state) and shared otherwise.One of shared, dedicated
dedicated_uplinkrequiredDedicatedUplink | nullThe router's last request for a dedicated uplink; null when it never asked for one.
staterequiredstringpending waits for Ankra to connect the uplink: the gateway runs on the shared uplink and is billed as a shared NAT gateway. active means it is connected and billed per 30-day term. declined carries Ankra's reason and leaves the gateway on the shared uplink. removed was taken back by the account, by setting the uplink to shared, turning NAT off or deleting the router.One of pending, active, declined, removed
requested_atrequiredstring (date-time)
activated_atrequiredstring (date-time) | nullWhen Ankra activated it: the start of the first 30-day term and of its billing.
term_ends_atrequiredstring (date-time) | nullWhile active: when the term already charged ends and the next one starts.
decline_reasonrequiredstring | nullWhen declined: what Ankra said.
networksrequiredarray of Network
idrequiredstring
zonerequiredstringThe home zone, where a router of the network lives.
regionrequiredstring
zonesrequiredarray of stringEvery zone of region the network is present in, sorted.
namerequiredstring
cidrrequiredstringThe IPv4 subnet, shared by every zone the network spans.
ula_prefixrequiredstringThe network's IPv6 ULA /64, the same in every zone it spans.
gatewayrequiredstringThe first host address, reserved for a router.
router_idrequiredstring | null
membersarray of InterfaceOnly in GET /v1/networks/{id}.
idrequiredstring
server_idrequiredstring
network_idrequiredstring
addressrequiredstring
address6requiredstringThe leg's address on the network's ULA /64 (every leg carries one, derived from the network and address).
mac_addressrequiredstring
device_indexrequiredinteger
created_atrequiredstring (date-time)
created_atrequiredstring (date-time)
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 402The account may not create this. reason is payment_method_required while it has no default payment method and its credit does not cover the create: the credit left must cover one month, at monthly list prices, of everything the account already runs plus what the create adds (add a payment method through POST /v1/account/billing/setup-session, or free what the account no longer needs); owner_approval_required while its owner has not approved paid usage and no credit is left; or account_suspended while an invoice is overdue past the grace period (pay it) or Ankra staff suspended the account (contact support). A prepaid account (linked to an Ankra platform organisation) is refused with payment_method_required while it has no card, and with credit_required once it has one but its credit does not cover the create: Cloud never charges its card, so only a top-up on the Ankra platform lifts it, and top_up_url names that page when Cloud knows it. GET /v1/account/billing reports the same standing. For payment_method_required and credit_required, detail names what the create costs, the credit left and the committed monthly spend only to a principal that may read billing (billing.read, and for an API token a scope that includes it); anyone else is told only that the credit does not cover it.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 409The resource's state does not allow this now.
  • 422The account would exceed a quota; detail names the limit and reason is quota_exceeded.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • 503No capacity or address is free in the zone right now (reason: capacity_unavailable, with availability wording in detail), or a host did not answer; try another plan or zone, or try again later.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/routers' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "zone": "string",
  "name": "string"
}'

Get a router#

GET/v1/routers/{id}
Operation
get_router
Credentials
API token, Portal session
Requires
Permission read

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200The router.application/json

200 response fields
FieldTypeDescription
routerrequiredRouter
idrequiredstring
zonerequiredstring
namerequiredstring
nat_enabledrequiredboolean
nat_addressrequiredstring | null
nat_address_billedrequiredbooleanWhether the NAT address is a public IPv4 address, billed at the public IPv4 price (€4.00 a month, a public_ipv4 usage line under the router's name) for as long as the router holds it, whatever uplink the NAT gateway is on. False without NAT, and for a NAT address that is not a public address: the NAT gateway then costs its own price alone.
uplinkrequiredstringWhat the router's NAT gateway runs on. shared is the uplink every NAT gateway starts on. dedicated is a 1 Gbit/s connection that only your servers use; Ankra sets it up, so on a router it reads dedicated while the request is pending or active (see dedicated_uplink.state) and shared otherwise.One of shared, dedicated
dedicated_uplinkrequiredDedicatedUplink | nullThe router's last request for a dedicated uplink; null when it never asked for one.
staterequiredstringpending waits for Ankra to connect the uplink: the gateway runs on the shared uplink and is billed as a shared NAT gateway. active means it is connected and billed per 30-day term. declined carries Ankra's reason and leaves the gateway on the shared uplink. removed was taken back by the account, by setting the uplink to shared, turning NAT off or deleting the router.One of pending, active, declined, removed
requested_atrequiredstring (date-time)
activated_atrequiredstring (date-time) | nullWhen Ankra activated it: the start of the first 30-day term and of its billing.
term_ends_atrequiredstring (date-time) | nullWhile active: when the term already charged ends and the next one starts.
decline_reasonrequiredstring | nullWhen declined: what Ankra said.
networksrequiredarray of Network
idrequiredstring
zonerequiredstringThe home zone, where a router of the network lives.
regionrequiredstring
zonesrequiredarray of stringEvery zone of region the network is present in, sorted.
namerequiredstring
cidrrequiredstringThe IPv4 subnet, shared by every zone the network spans.
ula_prefixrequiredstringThe network's IPv6 ULA /64, the same in every zone it spans.
gatewayrequiredstringThe first host address, reserved for a router.
router_idrequiredstring | null
membersarray of InterfaceOnly in GET /v1/networks/{id}.
idrequiredstring
server_idrequiredstring
network_idrequiredstring
addressrequiredstring
address6requiredstringThe leg's address on the network's ULA /64 (every leg carries one, derived from the network and address).
mac_addressrequiredstring
device_indexrequiredinteger
created_atrequiredstring (date-time)
created_atrequiredstring (date-time)
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/routers/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Turn a router's NAT gateway on or off, or change its uplink#

PATCH/v1/routers/{id}
Operation
update_router
Credentials
API token, Portal session
Requires
Permission operate

nat_enabled turns the NAT gateway on or off: 409 when a floating IP forwards through the NAT gateway being turned off.

uplink chooses what the NAT gateway runs on. dedicated asks for a dedicated uplink: a 1 Gbit/s connection that only your servers use. Ankra sets it up, so it is a request: the router's dedicated_uplink is pending until Ankra has connected it, and until then the gateway keeps running on the shared uplink and is billed as a shared NAT gateway (EUR 10 a month, by the hour). When it is connected the state becomes active and the account is told (network.dedicated_uplink_decided); a request Ankra cannot serve becomes declined with the reason, the gateway stays on the shared uplink, and it may be asked for again. Only a router that is a NAT gateway can ask (400 otherwise; nat_enabled: true in the same request counts). Asking while a request is pending or active changes nothing.

Billing starts when the dedicated uplink is activated: EUR 85 for each 30-day term, the first term starting at the activation and the following ones every 30 days after it, automatically. A term is charged in full when it starts, on the invoice of the month it starts in (resource type nat_gateway_dedicated_uplink), is never prorated and never refunded, and replaces the shared NAT gateway price for as long as the dedicated uplink is active. dedicated_uplink.term_ends_at is when the term already charged ends and the next one starts. Each term includes 50 TB of transfer through the gateway; beyond that the price is EUR 2 per TB (10^12 bytes), metered on the gateway and billed as nat_gateway_transfer (GET /v1/routers/{id}/transfer has the current term's figures). The gateway's address is not part of the term: on top, the gateway is charged EUR 4 a month for every public IPv4 address it holds.

uplink: shared takes a pending request back or removes an active dedicated uplink (state removed): no further term is charged, the term already charged is not refunded, and the gateway is billed as a shared NAT gateway again. Turning NAT off or deleting the router removes the dedicated uplink the same way. A term that started before the removal is charged even when the meter had not reached it yet.

uplink is shared or dedicated; an empty one is a 400, as is any other value. Turning NAT on and asking for a dedicated uplink commit the account to spend, so they are refused with 402 while the account may not spend what they add; turning NAT off and removing a dedicated uplink are never refused for billing. An Idempotency-Key makes a repeated request answer what the first one did.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring
Idempotency-KeyheaderstringA key the client chooses for this create, for example a UUID. The same create sent again with the same key within 24 hours answers the first one's answer with Idempotent-Replayed: true and creates nothing. 409 with reason: idempotency_key_in_progress while the first request is still running (try again shortly), with reason: idempotency_key_outcome_unknown when the first request answered 5xx or never finished (the create may or may not exist: list the resource before creating again with a new key), or with reason: idempotency_key_answer_not_stored when the create succeeded but its answer could not be kept (read the resource). 422 with reason: idempotency_key_reused when the key was used with a different request, 400 when the key is not 1 to 255 visible ASCII characters. Only a 4xx answer frees a key before the 24 hours.

Request bodyapplication/json

Request body fields
FieldTypeDescription
nat_enabledboolean
uplinkstringWhat the router's NAT gateway runs on. shared is the uplink every NAT gateway starts on. dedicated is a 1 Gbit/s connection that only your servers use; Ankra sets it up, so on a router it reads dedicated while the request is pending or active (see dedicated_uplink.state) and shared otherwise.One of shared, dedicated

Responses

202Accepted; poll the operation.application/json · OperationEnvelope

202 response fields
FieldTypeDescription
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 402The account may not create this. reason is payment_method_required while it has no default payment method and its credit does not cover the create: the credit left must cover one month, at monthly list prices, of everything the account already runs plus what the create adds (add a payment method through POST /v1/account/billing/setup-session, or free what the account no longer needs); owner_approval_required while its owner has not approved paid usage and no credit is left; or account_suspended while an invoice is overdue past the grace period (pay it) or Ankra staff suspended the account (contact support). A prepaid account (linked to an Ankra platform organisation) is refused with payment_method_required while it has no card, and with credit_required once it has one but its credit does not cover the create: Cloud never charges its card, so only a top-up on the Ankra platform lifts it, and top_up_url names that page when Cloud knows it. GET /v1/account/billing reports the same standing. For payment_method_required and credit_required, detail names what the create costs, the credit left and the committed monthly spend only to a principal that may read billing (billing.read, and for an API token a scope that includes it); anyone else is told only that the credit does not cover it.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 422The Idempotency-Key was already used with a different request (reason: idempotency_key_reused).
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • 503No capacity or address is free in the zone right now (reason: capacity_unavailable, with availability wording in detail), or a host did not answer; try another plan or zone, or try again later.
  • defaultAny other error, usually 500.

Example

bash
curl -X PATCH 'https://cloud.ankra.app/v1/routers/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "nat_enabled": false,
  "uplink": "shared"
}'

Delete a router#

DELETE/v1/routers/{id}
Operation
delete_router
Credentials
API token, Portal session
Requires
Permission operate

409 while networks are attached. A pending or active dedicated uplink is removed with the router: no further term is charged and the term already charged is not refunded.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

202Accepted; poll the operation.application/json · OperationEnvelope

202 response fields
FieldTypeDescription
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X DELETE 'https://cloud.ankra.app/v1/routers/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Attach a private network to a router#

POST/v1/routers/{id}/networks
Operation
attach_router_network
Credentials
API token, Portal session
Requires
Permission operate

400 when the network overlaps a network already on the router.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Request bodyapplication/json

Request body fields
FieldTypeDescription
network_idrequiredstring
addressstringAccepted for symmetry with server attachment and ignored.

Responses

202Accepted; poll the operation.application/json · OperationEnvelope

202 response fields
FieldTypeDescription
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/routers/<id>/networks' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "network_id": "string"
}'

Detach a private network from a router#

DELETE/v1/routers/{id}/networks/{network}
Operation
detach_router_network
Credentials
API token, Portal session
Requires
Permission operate

409 when a floating IP forwards into the network.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring
networkrequiredpathstringThe private network's id.

Responses

202Accepted; poll the operation.application/json · OperationEnvelope

202 response fields
FieldTypeDescription
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X DELETE 'https://cloud.ankra.app/v1/routers/<id>/networks/<network>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Get a server's firewall#

GET/v1/servers/{id}/firewall
Operation
get_server_firewall
Credentials
API token, Portal session
Requires
Permission read

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200The firewall.application/json

200 response fields
FieldTypeDescription
firewallrequiredFirewallRules apply in order, the first match decides, then the direction's default; established and related traffic is always allowed.
enabledrequiredboolean
default_inboundrequiredstringOne of accept, drop
default_outboundrequiredstringOne of accept, drop
rulesrequiredarray of FirewallRule
directionrequiredstringOne of inbound, outbound
actionrequiredstringOne of accept, drop
protocolrequiredstringOne of , tcp, udp, icmp
remote_cidrrequiredstringAn IPv4 or IPv6 address or CIDR; empty for any.
port_startrequiredinteger0 is any; needs tcp or udp.
port_endrequiredinteger
commentrequiredstring
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/servers/<id>/firewall' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Replace a server's firewall#

PUT/v1/servers/{id}/firewall
Operation
replace_server_firewall
Credentials
API token, Portal session
Requires
Permission operate

Applies within seconds, also to running servers.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Request bodyapplication/json · Firewall

Request body fields
FieldTypeDescription
enabledrequiredboolean
default_inboundrequiredstringOne of accept, drop
default_outboundrequiredstringOne of accept, drop
rulesrequiredarray of FirewallRule
directionrequiredstringOne of inbound, outbound
actionrequiredstringOne of accept, drop
protocolrequiredstringOne of , tcp, udp, icmp
remote_cidrrequiredstringAn IPv4 or IPv6 address or CIDR; empty for any.
port_startrequiredinteger0 is any; needs tcp or udp.
port_endrequiredinteger
commentrequiredstring

Responses

202Accepted; poll the operation.application/json · OperationEnvelope

202 response fields
FieldTypeDescription
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X PUT 'https://cloud.ankra.app/v1/servers/<id>/firewall' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "enabled": false,
  "default_inbound": "accept",
  "default_outbound": "accept",
  "rules": [
    {
      "direction": "inbound",
      "action": "accept",
      "protocol": "",
      "remote_cidr": "string",
      "port_start": 0,
      "port_end": 0,
      "comment": "string"
    }
  ]
}'

List a server's private interfaces#

GET/v1/servers/{id}/networks
Operation
list_server_interfaces
Credentials
API token, Portal session
Requires
Permission read

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200Every interface in device order; a server has at most 7, so the list is never paged and next_cursor is always null.application/json · InterfaceList

200 response fields
FieldTypeDescription
itemsrequiredarray of Interface
idrequiredstring
server_idrequiredstring
network_idrequiredstring
addressrequiredstring
address6requiredstringThe leg's address on the network's ULA /64 (every leg carries one, derived from the network and address).
mac_addressrequiredstring
device_indexrequiredinteger
next_cursorrequiredstring | nullPass as ?cursor= for the next page; null on the last page.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/servers/<id>/networks' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Attach a stopped server to a private network#

POST/v1/servers/{id}/networks
Operation
attach_server_network
Credentials
API token, Portal session
Requires
Permission operate

400 when the server is already on the network, has no free interface slot (7 at most) or address is taken, all checked before the operation is queued.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Request bodyapplication/json

Request body fields
FieldTypeDescription
network_idrequiredstring
addressstringA fixed address in the network; the next free one when omitted.

Responses

202Accepted; poll the operation.application/json · OperationEnvelope

202 response fields
FieldTypeDescription
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/servers/<id>/networks' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "network_id": "string"
}'

Detach a stopped server from a private network#

DELETE/v1/servers/{id}/networks/{network}
Operation
detach_server_network
Credentials
API token, Portal session
Requires
Permission operate

409 when a floating IP forwards to the server on this network.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring
networkrequiredpathstringThe private network's id.

Responses

202Accepted; poll the operation.application/json · OperationEnvelope

202 response fields
FieldTypeDescription
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X DELETE 'https://cloud.ankra.app/v1/servers/<id>/networks/<network>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"