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#
/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; a small fixed catalogue, so the list is never paged and next_cursor is always null.application/json · RegionList
| Field | Type | Description |
|---|---|---|
itemsrequired | array of Region | |
namerequired | string | |
display_namerequired | string | |
countryrequired | string | |
control_plane_endpointrequired | string | null | The regional control plane's API URL; null while the global one serves the region. |
zonesrequired | array of Zone | The region's zones by name. |
namerequired | string | |
regionrequired | string | |
display_namerequired | string | |
created_atrequired | 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. |
sold_out_plan_families | array of string | The plan tiers (a plan's family) out of stock in the zone: a new server, or a plan change into the tier, is refused there. Servers already on the tier keep it and resize within it. Empty when every tier is on sale.One of starter, cloud_native, premium |
sells_dedicated_cpu | boolean | True on a zone that sells the Dedicated CPU tier (premium plans) as dedicated: a new server on it there has its vCPUs pinned one to one to host CPUs no other server uses. Elsewhere the tier's servers share host CPUs, and a server keeps the CPUs it was created with. |
public_ipv4_available | boolean | Whether the zone can hand out a public IPv4 address now, the priced add-on (public_ipv4 on a server or a load balancer). Absent when that could not be read, which is not a no. Availability can change at any time: the create decides. |
created_atrequired | 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_cursorrequired | 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_credentialson 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
curl 'https://cloud.ankra.app/v1/regions' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Get a region with its zones#
/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
| Name | In | Type | Description |
|---|---|---|---|
regionrequired | path | string |
Responses
200The region.application/json · RegionEnvelope
| Field | Type | Description |
|---|---|---|
regionrequired | Region | |
namerequired | string | |
display_namerequired | string | |
countryrequired | string | |
control_plane_endpointrequired | string | null | The regional control plane's API URL; null while the global one serves the region. |
zonesrequired | array of Zone | The region's zones by name. |
namerequired | string | |
regionrequired | string | |
display_namerequired | string | |
created_atrequired | 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. |
sold_out_plan_families | array of string | The plan tiers (a plan's family) out of stock in the zone: a new server, or a plan change into the tier, is refused there. Servers already on the tier keep it and resize within it. Empty when every tier is on sale.One of starter, cloud_native, premium |
sells_dedicated_cpu | boolean | True on a zone that sells the Dedicated CPU tier (premium plans) as dedicated: a new server on it there has its vCPUs pinned one to one to host CPUs no other server uses. Elsewhere the tier's servers share host CPUs, and a server keeps the CPUs it was created with. |
public_ipv4_available | boolean | Whether the zone can hand out a public IPv4 address now, the priced add-on (public_ipv4 on a server or a load balancer). Absent when that could not be read, which is not a no. Availability can change at any time: the create decides. |
created_atrequired | 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_credentialson 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
curl 'https://cloud.ankra.app/v1/regions/<region>' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"