AnkraDocs
Console

API reference · Managed services

Databases

12 operations of the Ankra Cloud API: Managed PostgreSQL databases.

List managed databases#

GET/v1/databases
Operation
list_databases
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 databases, newest first.application/json

200 response fields
FieldTypeDescription
itemsrequiredarray of Database
idrequiredstring
zonerequiredstring
namerequiredstring
network_idrequiredstring
enginerequiredstringOne of postgresql-17
planrequiredstring
storage_gibibytesrequiredinteger
database_namerequiredstring
owner_namerequiredstring
hostrequiredstring | nullThe VM's private address; null until placed.
portrequiredinteger
connection_urirequiredstring | nullWithout the password; sslmode=verify-full, so save ca_certificate as ~/.postgresql/root.crt or pass it as sslrootcert.
staterequiredstringOne of creating, running, error, deleting
is_healthyrequiredboolean
health_detailrequiredstring
is_configuration_appliedrequiredboolean
backup_schedulerequiredstring
backupsrequiredDatabaseBackupSummary
is_enabledrequiredbooleanFalse until the controller created the repository, or when the zone has no backup endpoint.
retention_daysrequiredinteger
earliest_recoverable_atrequiredstring (date-time) | null
latest_recoverable_atrequiredstring (date-time) | null
observed_atrequiredstring (date-time) | null
archive_failurerequiredstring
tls_server_namerequiredstringThe DNS name the server certificate carries besides the host address.
certificate_expires_atrequiredstring (date-time) | nullRenewed 30 days before.
ca_certificatestring | nullPEM of the zone's database authority the server certificate chains to; only on GET /v1/databases/{id}.
storage_growth_availablebooleanWhether POST /v1/databases/{id}/resize would be accepted right now; only on GET /v1/databases/{id}. False while the database is not running, at the maximum size, or while its VM's data file system size is not known to the platform (see storage_growth_unavailable_reason).
storage_growth_unavailable_reasonstringWhy storage cannot grow online right now; only on GET /v1/databases/{id}, and only when storage_growth_available is false. It names the remedy when there is one: a host that cannot report the file system yet has to be updated by the platform first, and a restart would not help; a database that started before online storage growth has to restart once (a plan change restarts it).
backups_availablebooleanWhether the database's zone keeps its point-in-time backups; only on GET /v1/databases/{id}. False in a zone without object storage for them (see backups_unavailable_reason): the database cannot be restored, its deletion takes no final backup, and its data is gone once it is deleted.
backups_unavailable_reasonstringWhy the database keeps no backups; only on GET /v1/databases/{id}, and only when backups_available is false.
restored_fromrequiredobject | null
database_idrequiredstring
target_timerequiredstring (date-time) | null
active_operationrequiredOperation | null
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
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/databases' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Create a managed PostgreSQL 17 database on a private network#

POST/v1/databases
Operation
create_database
Credentials
API token, Portal session
Requires
Permission operate

One VM with its data on an Ankra Storage volume, serving TLS only and archiving its WAL and a daily full backup to the zone's object storage for point-in-time recovery; the owner's password is generated and returned in credentials. An account may hold 5. In a zone without object storage for the backups (database_backups in the zone's capabilities) the request needs acknowledge_no_backups (409 without it).

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
network_idrequiredstring
planstringOne of db-1c-2g, db-2c-4g, db-4c-8g
storage_gibibytesinteger
database_namerequiredstring
owner_namestring
zone_redundantbooleanPrimary and replica in different zones of the zone's region. Validated against the region (400 in a region with one zone), then answered 501 until zone-redundant placement lands.
acknowledge_no_backupsbooleanIn a zone whose databases keep no backups (database_backups: false in GET /v1/zones/{zone}/capabilities, which says why in database_backups_reason), creating a database answers 409 unless this is true. Such a database has no point-in-time backups: it cannot be restored, and its data is gone once it is deleted. Ignored in a zone that keeps them.

Responses

202The database, its database.create operation and the owner's credentials.application/json

202 response fields
FieldTypeDescription
databaserequiredDatabase
idrequiredstring
zonerequiredstring
namerequiredstring
network_idrequiredstring
enginerequiredstringOne of postgresql-17
planrequiredstring
storage_gibibytesrequiredinteger
database_namerequiredstring
owner_namerequiredstring
hostrequiredstring | nullThe VM's private address; null until placed.
portrequiredinteger
connection_urirequiredstring | nullWithout the password; sslmode=verify-full, so save ca_certificate as ~/.postgresql/root.crt or pass it as sslrootcert.
staterequiredstringOne of creating, running, error, deleting
is_healthyrequiredboolean
health_detailrequiredstring
is_configuration_appliedrequiredboolean
backup_schedulerequiredstring
backupsrequiredDatabaseBackupSummary
is_enabledrequiredbooleanFalse until the controller created the repository, or when the zone has no backup endpoint.
retention_daysrequiredinteger
earliest_recoverable_atrequiredstring (date-time) | null
latest_recoverable_atrequiredstring (date-time) | null
observed_atrequiredstring (date-time) | null
archive_failurerequiredstring
tls_server_namerequiredstringThe DNS name the server certificate carries besides the host address.
certificate_expires_atrequiredstring (date-time) | nullRenewed 30 days before.
ca_certificatestring | nullPEM of the zone's database authority the server certificate chains to; only on GET /v1/databases/{id}.
storage_growth_availablebooleanWhether POST /v1/databases/{id}/resize would be accepted right now; only on GET /v1/databases/{id}. False while the database is not running, at the maximum size, or while its VM's data file system size is not known to the platform (see storage_growth_unavailable_reason).
storage_growth_unavailable_reasonstringWhy storage cannot grow online right now; only on GET /v1/databases/{id}, and only when storage_growth_available is false. It names the remedy when there is one: a host that cannot report the file system yet has to be updated by the platform first, and a restart would not help; a database that started before online storage growth has to restart once (a plan change restarts it).
backups_availablebooleanWhether the database's zone keeps its point-in-time backups; only on GET /v1/databases/{id}. False in a zone without object storage for them (see backups_unavailable_reason): the database cannot be restored, its deletion takes no final backup, and its data is gone once it is deleted.
backups_unavailable_reasonstringWhy the database keeps no backups; only on GET /v1/databases/{id}, and only when backups_available is false.
restored_fromrequiredobject | null
database_idrequiredstring
target_timerequiredstring (date-time) | null
active_operationrequiredOperation | null
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
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
credentialsrequiredDatabaseCredentials
owner_namerequiredstring
passwordrequiredstring
connection_urirequiredstringWith the password.
  • 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.
  • 501The capability is not implemented yet; detail names the follow-up that adds it.
  • 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/databases' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "zone": "string",
  "name": "string",
  "network_id": "string",
  "database_name": "string"
}'

Get a database with its health#

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

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200The database.application/json

200 response fields
FieldTypeDescription
databaserequiredDatabase
idrequiredstring
zonerequiredstring
namerequiredstring
network_idrequiredstring
enginerequiredstringOne of postgresql-17
planrequiredstring
storage_gibibytesrequiredinteger
database_namerequiredstring
owner_namerequiredstring
hostrequiredstring | nullThe VM's private address; null until placed.
portrequiredinteger
connection_urirequiredstring | nullWithout the password; sslmode=verify-full, so save ca_certificate as ~/.postgresql/root.crt or pass it as sslrootcert.
staterequiredstringOne of creating, running, error, deleting
is_healthyrequiredboolean
health_detailrequiredstring
is_configuration_appliedrequiredboolean
backup_schedulerequiredstring
backupsrequiredDatabaseBackupSummary
is_enabledrequiredbooleanFalse until the controller created the repository, or when the zone has no backup endpoint.
retention_daysrequiredinteger
earliest_recoverable_atrequiredstring (date-time) | null
latest_recoverable_atrequiredstring (date-time) | null
observed_atrequiredstring (date-time) | null
archive_failurerequiredstring
tls_server_namerequiredstringThe DNS name the server certificate carries besides the host address.
certificate_expires_atrequiredstring (date-time) | nullRenewed 30 days before.
ca_certificatestring | nullPEM of the zone's database authority the server certificate chains to; only on GET /v1/databases/{id}.
storage_growth_availablebooleanWhether POST /v1/databases/{id}/resize would be accepted right now; only on GET /v1/databases/{id}. False while the database is not running, at the maximum size, or while its VM's data file system size is not known to the platform (see storage_growth_unavailable_reason).
storage_growth_unavailable_reasonstringWhy storage cannot grow online right now; only on GET /v1/databases/{id}, and only when storage_growth_available is false. It names the remedy when there is one: a host that cannot report the file system yet has to be updated by the platform first, and a restart would not help; a database that started before online storage growth has to restart once (a plan change restarts it).
backups_availablebooleanWhether the database's zone keeps its point-in-time backups; only on GET /v1/databases/{id}. False in a zone without object storage for them (see backups_unavailable_reason): the database cannot be restored, its deletion takes no final backup, and its data is gone once it is deleted.
backups_unavailable_reasonstringWhy the database keeps no backups; only on GET /v1/databases/{id}, and only when backups_available is false.
restored_fromrequiredobject | null
database_idrequiredstring
target_timerequiredstring (date-time) | null
active_operationrequiredOperation | null
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
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/databases/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Delete a database with its VM and data disk#

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

The VM takes a last full backup first. The backups in object storage are kept for the database's retention window, restorable with POST /v1/databases/{id}/restore by the deleted database's id, and purged afterwards.

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/databases/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

The recovery window and base backups of a database, newest first#

GET/v1/databases/{id}/backups
Operation
list_database_backups
Credentials
API token, Portal session
Requires
Permission read

Also answers for a deleted database whose backups are still kept (retained_until). The window is as the VM last reported it (every 5 minutes).

Parameters

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

Responses

200The window and one page of base backups.application/json

200 response fields
FieldTypeDescription
database_idrequiredstring
staterequiredstringOne of creating, running, error, deleting, deleted
backupsrequiredDatabaseBackupSummary
is_enabledrequiredbooleanFalse until the controller created the repository, or when the zone has no backup endpoint.
retention_daysrequiredinteger
earliest_recoverable_atrequiredstring (date-time) | null
latest_recoverable_atrequiredstring (date-time) | null
observed_atrequiredstring (date-time) | null
archive_failurerequiredstring
retained_untilrequiredstring (date-time) | nullWhen a deleted database's backups are purged.
itemsrequiredarray of DatabaseBaseBackup
idrequiredstring
labelrequiredstring
kindrequiredstringOne of full, diff, incr
started_atrequiredstring (date-time)
finished_atrequiredstring (date-time)
database_bytesrequiredinteger
repository_bytesrequiredintegerWhat the backup stores in object storage, compressed and encrypted.
next_cursorrequiredstring | null
  • 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.
  • 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/databases/<id>/backups' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Show the owner's password and connection URI (audited)#

GET/v1/databases/{id}/credentials
Operation
get_database_credentials
Credentials
API token, Portal session
Requires
Permission operate
Note
Reveals a credential or a live view; read-only support sessions are refused.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200The credentials.application/json

200 response fields
FieldTypeDescription
credentialsrequiredDatabaseCredentials
owner_namerequiredstring
passwordrequiredstring
connection_urirequiredstringWith the password.
  • 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.
  • 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 'https://cloud.ankra.app/v1/databases/<id>/credentials' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

CPU, memory, disk and query time of a database#

GET/v1/databases/{id}/metrics
Operation
get_database_metrics
Credentials
API token, Portal session
Requires
Permission read

What the database's VM used, as its guest agent reports it on every health check (every 5 seconds), in five-minute buckets kept for 35 days. Query time is the mean execution time of the statements the database's own roles finished in the step, from pg_stat_statements; a database created before query statistics existed collects them from PostgreSQL's next start (collects_query_statistics).

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring
periodquerystring

Responses

200One point per step, oldest first; a reading is null in a step without samples, and the last step is in progress.application/json · DatabaseMetricsSeries

200 response fields
FieldTypeDescription
periodrequiredstringOne of 1h, 24h, 7d, 30d
step_secondsrequiredinteger
collects_query_statisticsrequiredbooleanWhether any step in the period carried query statistics.
pointsrequiredarray of DatabaseMetricsPoint
atrequiredstring (date-time)
cpu_percentrequirednumber | nullShare of the VM's CPU time spent busy in the step, 0 to 100.
memory_used_bytesrequiredinteger (int64) | nullAverage memory in use (total less available).
memory_total_bytesrequiredinteger (int64) | null
disk_used_bytesrequiredinteger (int64) | nullAverage space used on the data disk.
disk_total_bytesrequiredinteger (int64) | null
query_countrequiredinteger (int64)Statements the database's roles finished in the step.
query_mean_millisecondsrequirednumber | nullTheir mean execution time; null without statements.
  • 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.
  • 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/databases/<id>/metrics' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Scale a running database up or down to another plan#

POST/v1/databases/{id}/plan
Operation
change_database_plan
Credentials
API token, Portal session
Requires
Permission operate

Operation database.change_plan. The database's VM stops, takes the new plan's cores and memory (on its node when the node has room, otherwise moved cold to another node of the zone) and starts again, so the database is unavailable for a few minutes. Its data disk, address, password, certificate and backups stay, and so does the recovery window it was created with. The new plan is billed from the hour it is applied. A change that fails starts the VM again on the size it still has (operation database.start). 409 unless the database is running, while another operation holds it, or when it already has the plan.

A plan whose monthly price (with the database's storage) is higher is refused with 402 while the account may not spend the difference. A plan that costs the same or less is never refused for billing, so an account without a payment method, credit or the owner's approval can still scale down; only a suspension by Ankra staff refuses it (402, reason account_suspended).

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
planrequiredstringA database plan from GET /v1/databases/plans, such as db-2c-4g.

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 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/databases/<id>/plan' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "plan": "string"
}'

Give the owner a new password#

POST/v1/databases/{id}/reset-password
Operation
reset_database_password
Credentials
API token, Portal session
Requires
Permission operate

The VM applies it within seconds (is_configuration_applied turns true); until then the old one works.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200The database and the new credentials.application/json

200 response fields
FieldTypeDescription
databaserequiredDatabase
idrequiredstring
zonerequiredstring
namerequiredstring
network_idrequiredstring
enginerequiredstringOne of postgresql-17
planrequiredstring
storage_gibibytesrequiredinteger
database_namerequiredstring
owner_namerequiredstring
hostrequiredstring | nullThe VM's private address; null until placed.
portrequiredinteger
connection_urirequiredstring | nullWithout the password; sslmode=verify-full, so save ca_certificate as ~/.postgresql/root.crt or pass it as sslrootcert.
staterequiredstringOne of creating, running, error, deleting
is_healthyrequiredboolean
health_detailrequiredstring
is_configuration_appliedrequiredboolean
backup_schedulerequiredstring
backupsrequiredDatabaseBackupSummary
is_enabledrequiredbooleanFalse until the controller created the repository, or when the zone has no backup endpoint.
retention_daysrequiredinteger
earliest_recoverable_atrequiredstring (date-time) | null
latest_recoverable_atrequiredstring (date-time) | null
observed_atrequiredstring (date-time) | null
archive_failurerequiredstring
tls_server_namerequiredstringThe DNS name the server certificate carries besides the host address.
certificate_expires_atrequiredstring (date-time) | nullRenewed 30 days before.
ca_certificatestring | nullPEM of the zone's database authority the server certificate chains to; only on GET /v1/databases/{id}.
storage_growth_availablebooleanWhether POST /v1/databases/{id}/resize would be accepted right now; only on GET /v1/databases/{id}. False while the database is not running, at the maximum size, or while its VM's data file system size is not known to the platform (see storage_growth_unavailable_reason).
storage_growth_unavailable_reasonstringWhy storage cannot grow online right now; only on GET /v1/databases/{id}, and only when storage_growth_available is false. It names the remedy when there is one: a host that cannot report the file system yet has to be updated by the platform first, and a restart would not help; a database that started before online storage growth has to restart once (a plan change restarts it).
backups_availablebooleanWhether the database's zone keeps its point-in-time backups; only on GET /v1/databases/{id}. False in a zone without object storage for them (see backups_unavailable_reason): the database cannot be restored, its deletion takes no final backup, and its data is gone once it is deleted.
backups_unavailable_reasonstringWhy the database keeps no backups; only on GET /v1/databases/{id}, and only when backups_available is false.
restored_fromrequiredobject | null
database_idrequiredstring
target_timerequiredstring (date-time) | null
active_operationrequiredOperation | null
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
created_atrequiredstring (date-time)
credentialsrequiredDatabaseCredentials
owner_namerequiredstring
passwordrequiredstring
connection_urirequiredstringWith the password.
  • 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.
  • 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/databases/<id>/reset-password' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Grow a database's storage online#

POST/v1/databases/{id}/resize
Operation
resize_database
Credentials
API token, Portal session
Requires
Permission operate

Operation database.resize, grow only. The data disk's volume grows, the running hypervisor presents the new size to the VM (step await_storage_resized), the VM's guest agent grows the ext4 file system under the running PostgreSQL, and the operation finishes once the guest reports a file system of the new size (step await_database_filesystem_grown), usually well within a minute: no restart, clients keep their connections. storage_gibibytes shows the new size, and the database is billed at it, only from then on; a growth the guest finishes after the operation gave up is recorded as soon as it reports it. Managed databases' storage does not count against the account's storage quota.

400 for a size that is not larger than the current one, past the maximum, or smaller than the data disk already is after an attempt that did not finish (ask for at least that size to finish it). 409 unless the database is running, while another operation holds it, and while the platform does not know the size of the database's file system, without which the growth could not be confirmed. The 409 says which of three it is, and GET /v1/databases/{id} says the same up front (storage_growth_available, storage_growth_unavailable_reason): the database's host cannot report it yet (the platform has to update the host first, and a restart would not help until then); the database started before online storage growth (restart it once, or change its plan, which restarts it); or it has not measured its file system yet (try again in a minute).

An operation that runs out of time waiting for the file system fails with an error that says so: the disk has its new size, and storage shows and is billed at the new size once the database finishes growing it, without another request (audit action database.storage_grown).

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
storage_gibibytesrequiredintegerLarger than the current size.

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 POST 'https://cloud.ankra.app/v1/databases/<id>/resize' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "storage_gibibytes": 11
}'

Restore a database's backups into a new database#

POST/v1/databases/{id}/restore
Operation
restore_database
Credentials
API token, Portal session
Requires
Permission operate

Creates a new database from this one's backups, recovered to target_time (within the recovery window) or, without it, to everything it archived. The source may have been deleted within its retention window. The new database has the source's database and owner names, a new password and backups of its own; its database.restore operation finishes once the data is recovered. plan and storage_gibibytes size the new database; to resize this one in place use POST /v1/databases/{id}/plan and POST /v1/databases/{id}/resize. The new database goes to the source's zone, so a zone whose databases keep no backups (database_backups false in its capabilities) answers 409, as there are no backups to read.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Request bodyapplication/json · optional

Request body fields
FieldTypeDescription
namestringDefaults to the source's name with " (restored)".
network_idstringDefaults to the source's network.
planstringDefaults to the source's plan.One of db-1c-2g, db-2c-4g, db-4c-8g
storage_gibibytesintegerAt least the source's; defaults to it.
target_timestring (date-time)

Responses

202The new database, its database.restore operation and the owner's credentials.application/json

202 response fields
FieldTypeDescription
databaserequiredDatabase
idrequiredstring
zonerequiredstring
namerequiredstring
network_idrequiredstring
enginerequiredstringOne of postgresql-17
planrequiredstring
storage_gibibytesrequiredinteger
database_namerequiredstring
owner_namerequiredstring
hostrequiredstring | nullThe VM's private address; null until placed.
portrequiredinteger
connection_urirequiredstring | nullWithout the password; sslmode=verify-full, so save ca_certificate as ~/.postgresql/root.crt or pass it as sslrootcert.
staterequiredstringOne of creating, running, error, deleting
is_healthyrequiredboolean
health_detailrequiredstring
is_configuration_appliedrequiredboolean
backup_schedulerequiredstring
backupsrequiredDatabaseBackupSummary
is_enabledrequiredbooleanFalse until the controller created the repository, or when the zone has no backup endpoint.
retention_daysrequiredinteger
earliest_recoverable_atrequiredstring (date-time) | null
latest_recoverable_atrequiredstring (date-time) | null
observed_atrequiredstring (date-time) | null
archive_failurerequiredstring
tls_server_namerequiredstringThe DNS name the server certificate carries besides the host address.
certificate_expires_atrequiredstring (date-time) | nullRenewed 30 days before.
ca_certificatestring | nullPEM of the zone's database authority the server certificate chains to; only on GET /v1/databases/{id}.
storage_growth_availablebooleanWhether POST /v1/databases/{id}/resize would be accepted right now; only on GET /v1/databases/{id}. False while the database is not running, at the maximum size, or while its VM's data file system size is not known to the platform (see storage_growth_unavailable_reason).
storage_growth_unavailable_reasonstringWhy storage cannot grow online right now; only on GET /v1/databases/{id}, and only when storage_growth_available is false. It names the remedy when there is one: a host that cannot report the file system yet has to be updated by the platform first, and a restart would not help; a database that started before online storage growth has to restart once (a plan change restarts it).
backups_availablebooleanWhether the database's zone keeps its point-in-time backups; only on GET /v1/databases/{id}. False in a zone without object storage for them (see backups_unavailable_reason): the database cannot be restored, its deletion takes no final backup, and its data is gone once it is deleted.
backups_unavailable_reasonstringWhy the database keeps no backups; only on GET /v1/databases/{id}, and only when backups_available is false.
restored_fromrequiredobject | null
database_idrequiredstring
target_timerequiredstring (date-time) | null
active_operationrequiredOperation | null
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
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
credentialsrequiredDatabaseCredentials
owner_namerequiredstring
passwordrequiredstring
connection_urirequiredstringWith the password.
  • 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.
  • 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/databases/<id>/restore' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "network_id": "string",
  "plan": "db-1c-2g",
  "storage_gibibytes": 10,
  "target_time": "2026-09-28T12:00:00Z"
}'

The database sizes on offer and the storage price#

GET/v1/databases/plans
Operation
list_database_plans
Credentials
API token, Portal session
Requires
Permission read

Responses

200The plans.application/json

200 response fields
FieldTypeDescription
itemsrequiredarray of object
namerequiredstring
coresrequiredinteger
memory_mebibytesrequiredinteger
price_monthly_centsrequiredinteger
storage_price_per_gibibyte_monthly_centsrequiredinteger
minimum_storage_gibibytesrequiredinteger
maximum_storage_gibibytesrequiredinteger
default_storage_gibibytesrequiredinteger
  • 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/databases/plans' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"