API reference · Compute

Console, metadata and metrics

6 operations of the Ankra Cloud API: The console, the metadata service setting, server metrics and network transfer.

Type into the serial console#

POST/v1/servers/{id}/console/input

Operation: send_server_console_input
Credentials: API token, Portal session
Requires: Permission operate

At most 4 KiB (decoded) per request and 50 requests per second per server. The first input of each session_id is recorded in the audit log as server.console_session.

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Request bodyapplication/json · ConsoleInput

Request body fields
Field	Type	Description
`session_id`required	string (uuid)	One per open console; its first input is audited.
`data`required	string (byte)	Base64 of at most 4096 bytes.

Responses

204Sent to the server's serial port.

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 or the email is locked out.
503No capacity or address is free, or a host did not answer; try again later.
defaultAny other error, usually 500.

Example

bash

curl -X POST 'https://cloud.ankra.app/v1/servers/<id>/console/input' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "session_id": "00000000-0000-0000-0000-000000000000",
  "data": "string"
}'

The interactive serial console as Server-Sent Events#

GET/v1/servers/{id}/console/stream

Operation: stream_server_console
Credentials: API token, Portal session
Requires: Permission operate
Note: Reveals a credential or a live view; read-only support sessions are refused.

Starts with event: tail (base64 of the last 64 KiB of console output), then event: status with a ConsoleStatus, then one event: output (base64 of raw terminal bytes) per chunk the guest writes, and a : keepalive comment every 15 s. The stream ends after 30 minutes; EventSource clients reconnect.

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Responses

200The event stream.text/event-stream

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.
defaultAny other error, usually 500.

Example

bash

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

Whether the metadata service at 169.254.169.254 answers the server#

GET/v1/servers/{id}/metadata

Operation: get_server_metadata_setting
Credentials: API token, Portal session
Requires: Permission operate
Note: Reveals a credential or a live view; read-only support sessions are refused.

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Responses

200The setting.application/json · MetadataSetting

200 response fields
Field	Type	Description
`enabled`required	boolean

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.
defaultAny other error, usually 500.

Example

bash

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

Turn the metadata service on or off for the server#

PUT/v1/servers/{id}/metadata

Operation: set_server_metadata_setting
Credentials: API token, Portal session
Requires: Permission operate

Applies within seconds, also to running servers.

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Request bodyapplication/json · MetadataSetting

Request body fields
Field	Type	Description
`enabled`required	boolean

Responses

202Accepted; poll the operation (server.metadata).application/json

202 response fields
Field	Type	Description
`enabled`required	boolean
`operation`required	Operation
`id`required	string
`kind`required	string	One of `server.create`, `server.metadata`, `server.start`, `server.stop`, `server.restart`, `server.delete`, `server.force_release`, `server.change_plan`, `server.rebuild`, `server.renumber_ipv6`, `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`, `server.move`, `server.migrate`, `server.recover`, `server.settle_migration`, `node.cordon`, `node.uncordon`, `node.drain`, `node.fence`, `node.maintenance`, `node.agent_upgrade`, `node.provision`, `load_balancer.create`, `load_balancer.delete`, `database.create`, `database.delete`, `database.restore`, `edge.sync`, `edge.delete`, `storage.move`, `storage.rebalance_policy`, `storage.drain_host`, `object_storage.migrate`, `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_cluster.platform_register`, `kubernetes_cluster.platform_deregister`, `control_plane.expand`, `control_plane.shrink`, `backup.verify`
`server_id`required	string \| null
`storage_id`required	string \| null
`backup_id`required	string \| null
`template_id`required	string \| null
`router_id`required	string \| null
`floating_ip_id`required	string \| null
`node_id`	string	Set on node maintenance operations (operator only); absent otherwise.
`load_balancer_id`	string \| null	Set on the operations that create and delete a load balancer.
`database_id`	string \| null	Set on the operations that create and delete a managed database.
`edge_id`	string \| null	Set on the operations that sync and delete a network edge.
`snapshot_id`	string \| null	Set on the operations that create and delete a snapshot, and on a `storage.create` that clones one.
`kubernetes_cluster_id`	string \| null	Set on the operations of a managed Kubernetes cluster.
`node_pool_id`	string \| null	Set on the operations of a Kubernetes node pool.
`kubernetes_host_id`	string	Set on a regional host cluster bootstrap (operator only); absent otherwise.
`status`required	string	One of `pending`, `running`, `succeeded`, `failed`, `cancelled`
`step`required	string	Machine name of the current step, e.g. `create_disk` or `transfer_cross_zone`.
`step_index`required	integer
`step_count`required	integer
`error`required	string	Empty unless the operation failed.
`created_at`required	string (date-time)
`started_at`required	string (date-time) \| null
`finished_at`required	string (date-time) \| null
`deadline_at`required	string (date-time)
`actor`	string	Who asked for the operation: `user:<id>`, `token:<name>`, `operator`, `system:<component>`; empty on older operations.
`progress`	MigrationProgress	Present on `GET /v1/operations/{id}` while a `server.migrate` drives a live transfer.
`state`required	string	One of `reserved`, `detached`, `preparing`, `sending`, `switched`, `aborting`
`source_node_id`required	string
`target_node_id`required	string
`phase`required	string	How far the nodes report the current attempt.One of , `preparing`, `transferring`, `completed`, `failed`
`attempt`required	integer	Which send this is under the convergence policy, from 1.
`iteration`required	integer	Memory passes so far in the current attempt.
`transferred_bytes`required	integer
`total_bytes`required	integer	0 when the hypervisor does not report it.
`dirty_bytes_per_second`required	integer
`downtime_milliseconds`required	integer	The pause the guest took at handover, once completed.
`detail`required	string
`reported_at`required	string (date-time) \| null	The reporting node's clock.
`events`	array of OperationEvent	Present on `GET /v1/operations/{id}`; the newest 100 entries of the operation's log, oldest first.
`at`required	string (date-time)
`kind`required	string	For example `target_chosen`, `send_started`, `handed_over`, `undoing`, `cold_fallback`, `move_cancelled`, `recovery_started`, `succeeded`, `failed`.
`message`required	string
`data`required	object

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.
defaultAny other error, usually 500.

Example

bash

curl -X PUT 'https://cloud.ankra.app/v1/servers/<id>/metadata' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "enabled": false
}'

Network and disk metrics of the server#

GET/v1/servers/{id}/metrics

Operation: get_server_metrics
Credentials: API token, Portal session
Requires: Permission read

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string
`period`	query	string

Responses

200One point per step, oldest first, zero-filled; the last step is in progress.application/json · MetricsSeries

200 response fields
Field	Type	Description
`period`required	string	One of `1h`, `24h`, `7d`, `30d`
`step_seconds`required	integer
`points`required	array of MetricsPoint
`at`required	string (date-time)
`network_received_bytes`required	integer (int64)
`network_transmitted_bytes`required	integer (int64)
`disk_read_bytes`required	integer (int64)
`disk_written_bytes`required	integer (int64)
`disk_read_operations`required	integer (int64)
`disk_write_operations`required	integer (int64)

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.
defaultAny other error, usually 500.

Example

bash

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

Public network traffic per server in a month#

GET/v1/usage/network-transfer

Operation: get_network_transfer
Credentials: API token, Portal session
Requires: Permission billing.read

Outbound traffic of a server's public interface beyond 1 TiB per calendar month is billed at €0.01 per GiB (resource_type network_transfer); inbound and private-network traffic are free.

Parameters

Parameters
Name	In	Type	Description
`month`	query	string	The UTC month, `YYYY-MM`; the current one when omitted.

Responses

200The month's network transfer.application/json · NetworkTransfer

200 response fields
Field	Type	Description
`period_start`required	string (date-time)
`period_end`required	string (date-time)
`allowance_bytes_per_server`required	integer (int64)
`price_per_gibibyte_millicents`required	integer (int64)
`total_received_bytes`required	integer (int64)
`total_transmitted_bytes`required	integer (int64)
`total_billable_bytes`required	integer (int64)
`total_amount_cents`required	integer (int64)
`items`required	array of object
`server_id`required	string
`server_name`required	string
`received_bytes`required	integer (int64)
`transmitted_bytes`required	integer (int64)
`billable_bytes`required	integer (int64)
`amount_cents`required	integer (int64)
`daily`required	array of object
`date`required	string (date)
`received_bytes`required	integer (int64)
`transmitted_bytes`required	integer (int64)

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).
defaultAny other error, usually 500.

Example

bash

curl 'https://cloud.ankra.app/v1/usage/network-transfer' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"