API reference · Locations and tools

Regions

2 operations of the Ankra Cloud API: Regions (a metro of availability zones within about 2 ms of each other) and, for operators, the racks of a zone (ADR 0003).

List regions with their zones#

GET/v1/regions

Operation: list_regions
Credentials: Operator token, API token, Portal session
Requires: Permission read

A region groups the availability zones of one metro. Private networks can span the zones of a region, server groups can spread over them, and backups are copied to another zone of the region by default. Regions are ordered by the position of their first zone. A customer sees only the zones it may use and no region without one. Accepts the operator token as well as a customer credential.

Responses

200Every region (next_cursor is always null).application/json · RegionList

200 response fields
Field	Type	Description
`items`required	array of Region
`name`required	string
`display_name`required	string
`country`required	string
`control_plane_endpoint`required	string \| null	The regional control plane's API URL; null while the global one serves the region.
`zones`required	array of Zone	The region's zones by name.
`name`required	string
`region`required	string
`display_name`required	string
`created_at`required	string (date-time)
`underlay`	string	How the zone's hosts reach each other (ADR 0004): `fabric` is a private network, `wireguard` the encrypted underlay.One of `fabric`, `wireguard`
`country`	string	The zone's region's ISO 3166-1 alpha-2 country code.
`position`	integer	Where the zone is listed, lowest first (then by name); regions follow the position of their first zone.
`customer_visible`	boolean	False for a zone hidden from customers: a customer only sees it, and places new resources in it, when the account may use hidden zones or has private hosts there. Operators always see every zone.
`is_private_cloud`	boolean	True, in a customer's listing, on a zone in which Ankra dedicated compute hosts to the caller's account (its private cloud): the account's servers there run only on its own hosts. Hidden zone access alone never sets it; always false for operators.
`created_at`required	string (date-time)
`is_private_cloud`	boolean	True, in a customer's listing, when one of the region's zones holds hosts dedicated to the caller's account.
`next_cursor`required	string \| null	Pass as `?cursor=` for the next page; null on the last page.

401Not signed in, or the credential is invalid or expired.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
defaultAny other error, usually 500.

Example

bash

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

Get a region with its zones#

GET/v1/regions/{region}

Operation: get_region
Credentials: Operator token, API token, Portal session
Requires: Permission read

Accepts the operator token as well as a customer credential.

Parameters

Parameters
Name	In	Type	Description
`region`required	path	string

Responses

200The region.application/json · RegionEnvelope

200 response fields
Field	Type	Description
`region`required	Region
`name`required	string
`display_name`required	string
`country`required	string
`control_plane_endpoint`required	string \| null	The regional control plane's API URL; null while the global one serves the region.
`zones`required	array of Zone	The region's zones by name.
`name`required	string
`region`required	string
`display_name`required	string
`created_at`required	string (date-time)
`underlay`	string	How the zone's hosts reach each other (ADR 0004): `fabric` is a private network, `wireguard` the encrypted underlay.One of `fabric`, `wireguard`
`country`	string	The zone's region's ISO 3166-1 alpha-2 country code.
`position`	integer	Where the zone is listed, lowest first (then by name); regions follow the position of their first zone.
`customer_visible`	boolean	False for a zone hidden from customers: a customer only sees it, and places new resources in it, when the account may use hidden zones or has private hosts there. Operators always see every zone.
`is_private_cloud`	boolean	True, in a customer's listing, on a zone in which Ankra dedicated compute hosts to the caller's account (its private cloud): the account's servers there run only on its own hosts. Hidden zone access alone never sets it; always false for operators.
`created_at`required	string (date-time)
`is_private_cloud`	boolean	True, in a customer's listing, when one of the region's zones holds hosts dedicated to the caller's account.

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