API reference · Account and billing

Private cloud

4 operations of the Ankra Cloud API: Private cloud: physical hosts dedicated to one account. An account reads the capacity it has per zone (never which machines carry it) and asks for a private cloud or more of it; staff review the requests and dedicate hosts in the fleet.

The account's private cloud, or what it takes to request one#

GET/v1/private-cloud

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

has_private_hosts says whether staff dedicated physical hosts to the account. When they did, zones sums the dedicated capacity per zone (hosts, vCPU budget, memory, disk) with what the account's servers on those hosts take, totals sums every zone and servers lists the account's servers placed on its private hosts (at most 500, newest first; servers_truncated is true when there are more). Customers see capacity, never the machines: no hostname, address or hardware detail of a host is returned. minimums and maximums bound a new request, open_request is the request waiting for staff (null when none) and recent_requests the account's five newest requests.

Responses

200The private cloud overview.application/json · PrivateCloudOverview

200 response fields
Field	Type	Description
`has_private_hosts`required	boolean
`minimums`required	PrivateCloudAmounts
`vcpus`required	integer
`memory_gibibytes`required	integer
`disk_gigabytes`required	integer
`maximums`required	PrivateCloudAmounts
`vcpus`required	integer
`memory_gibibytes`required	integer
`disk_gigabytes`required	integer
`totals`required	PrivateCloudCapacity	Dedicated capacity and what the account's servers on it take. `vcpus` is the vCPU budget the scheduler places against (each logical CPU carries 4 vCPUs), `memory_mebibytes` the memory servers may take (each host keeps 2 GiB for itself), `disk_gigabytes` the hosts' raw disk. `local_storage_used_gibibytes` is the Ankra Local volumes the account keeps on the hosts.
`host_count`required	integer
`logical_cpus`required	integer
`vcpus`required	integer
`vcpus_used`required	integer
`memory_mebibytes`required	integer
`memory_used_mebibytes`required	integer
`disk_gigabytes`required	integer
`local_storage_used_gibibytes`required	integer
`server_count`required	integer
`zones`required	array of PrivateCloudZone
`zone`required	string
`zone_display_name`required	string
`region`required	string
`region_display_name`required	string
`host_count`required	integer
`logical_cpus`required	integer
`vcpus`required	integer
`vcpus_used`required	integer
`memory_mebibytes`required	integer
`memory_used_mebibytes`required	integer
`disk_gigabytes`required	integer
`local_storage_used_gibibytes`required	integer
`server_count`required	integer
`servers`required	array of PrivateCloudServer
`id`required	string
`hostname`required	string
`title`required	string
`zone`required	string
`plan`required	string
`cores`required	integer
`memory_mebibytes`required	integer
`state`required	string	The server state as `get_server` reports it.
`servers_truncated`required	boolean
`open_request`required	PrivateCloudRequest \| null
`id`required	string
`state`required	string	`open` waits for staff, `in_review` is being worked on, `fulfilled` means the hosts are dedicated, `declined` carries the staff's reason, `withdrawn` was taken back by the account.One of `open`, `in_review`, `fulfilled`, `declined`, `withdrawn`
`vcpus`required	integer
`memory_gibibytes`required	integer
`disk_gigabytes`required	integer
`region`required	string \| null
`notes`required	string
`staff_reason`required	string \| null	What staff said when they last moved the request on; a decline always carries one.
`requested_by_email`required	string
`created_at`required	string (date-time)
`updated_at`required	string (date-time)
`decided_at`required	string (date-time) \| null	When the request was fulfilled, declined or withdrawn.
`recent_requests`required	array of PrivateCloudRequest
`id`required	string
`state`required	string	`open` waits for staff, `in_review` is being worked on, `fulfilled` means the hosts are dedicated, `declined` carries the staff's reason, `withdrawn` was taken back by the account.One of `open`, `in_review`, `fulfilled`, `declined`, `withdrawn`
`vcpus`required	integer
`memory_gibibytes`required	integer
`disk_gigabytes`required	integer
`region`required	string \| null
`notes`required	string
`staff_reason`required	string \| null	What staff said when they last moved the request on; a decline always carries one.
`requested_by_email`required	string
`created_at`required	string (date-time)
`updated_at`required	string (date-time)
`decided_at`required	string (date-time) \| null	When the request was fulfilled, declined or withdrawn.

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

The account's private cloud requests, newest first#

GET/v1/private-cloud/requests

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

Parameters

Parameters
Name	In	Type	Description
`cursor`	query	string	The `next_cursor` of the previous page.
`limit`	query	integer	Page size; the server applies its default and maximum.

Responses

200A page of requests (limit at most 100, default 20).application/json · PrivateCloudRequestList

200 response fields
Field	Type	Description
`items`required	array of PrivateCloudRequest
`id`required	string
`state`required	string	`open` waits for staff, `in_review` is being worked on, `fulfilled` means the hosts are dedicated, `declined` carries the staff's reason, `withdrawn` was taken back by the account.One of `open`, `in_review`, `fulfilled`, `declined`, `withdrawn`
`vcpus`required	integer
`memory_gibibytes`required	integer
`disk_gigabytes`required	integer
`region`required	string \| null
`notes`required	string
`staff_reason`required	string \| null	What staff said when they last moved the request on; a decline always carries one.
`requested_by_email`required	string
`created_at`required	string (date-time)
`updated_at`required	string (date-time)
`decided_at`required	string (date-time) \| null	When the request was fulfilled, declined or withdrawn.
`next_cursor`required	string \| null	Pass 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).
defaultAny other error, usually 500.

Example

bash

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

Ask Ankra for a private cloud, or for more private capacity#

POST/v1/private-cloud/requests

Operation: create_private_cloud_request
Credentials: API token, Portal session
Requires: Permission billing.manage

Records what the account wants dedicated to it (vCPUs, memory, disk, optionally a region and notes) for staff to review; nothing is provisioned or billed by the request itself. Each amount must be at least the minimum get_private_cloud returns and at most its maximum (422 otherwise). An account has one open request at a time: 409 while another is open or in_review (withdraw it first). Recorded in the account's audit log (private_cloud_request.create) and emailed to Ankra's admin staff. The caller's email address must be verified.

Request bodyapplication/json · CreatePrivateCloudRequest

Request body fields
Field	Type	Description
`vcpus`required	integer	vCPUs wanted; at least `minimums.vcpus`.
`memory_gibibytes`required	integer	Memory wanted in GiB; at least `minimums.memory_gibibytes`.
`disk_gigabytes`required	integer	Disk wanted in GB; at least `minimums.disk_gigabytes`.
`region`	string \| null	The region wanted (a name from `list_regions`); null or absent for any.
`notes`	string \| null	Anything staff should know: workloads, timing, contacts.

Responses

201The recorded request.application/json · PrivateCloudRequestEnvelope

201 response fields
Field	Type	Description
`request`required	PrivateCloudRequest
`id`required	string
`state`required	string	`open` waits for staff, `in_review` is being worked on, `fulfilled` means the hosts are dedicated, `declined` carries the staff's reason, `withdrawn` was taken back by the account.One of `open`, `in_review`, `fulfilled`, `declined`, `withdrawn`
`vcpus`required	integer
`memory_gibibytes`required	integer
`disk_gigabytes`required	integer
`region`required	string \| null
`notes`required	string
`staff_reason`required	string \| null	What staff said when they last moved the request on; a decline always carries one.
`requested_by_email`required	string
`created_at`required	string (date-time)
`updated_at`required	string (date-time)
`decided_at`required	string (date-time) \| null	When the request was fulfilled, declined or withdrawn.

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).
409The resource's state does not allow this now.
422An amount is below the minimum or above the maximum, the region is unknown or the notes are too long.
defaultAny other error, usually 500.

Example

bash

curl -X POST 'https://cloud.ankra.app/v1/private-cloud/requests' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "vcpus": 1,
  "memory_gibibytes": 1,
  "disk_gigabytes": 1
}'

Withdraw an open private cloud request#

DELETE/v1/private-cloud/requests/{id}

Operation: cancel_private_cloud_request
Credentials: API token, Portal session
Requires: Permission billing.manage

The request becomes withdrawn. Only an open or in_review request can be withdrawn (409 otherwise). Recorded in the account's audit log (private_cloud_request.withdraw).

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Responses

200The withdrawn request.application/json · PrivateCloudRequestEnvelope

200 response fields
Field	Type	Description
`request`required	PrivateCloudRequest
`id`required	string
`state`required	string	`open` waits for staff, `in_review` is being worked on, `fulfilled` means the hosts are dedicated, `declined` carries the staff's reason, `withdrawn` was taken back by the account.One of `open`, `in_review`, `fulfilled`, `declined`, `withdrawn`
`vcpus`required	integer
`memory_gibibytes`required	integer
`disk_gigabytes`required	integer
`region`required	string \| null
`notes`required	string
`staff_reason`required	string \| null	What staff said when they last moved the request on; a decline always carries one.
`requested_by_email`required	string
`created_at`required	string (date-time)
`updated_at`required	string (date-time)
`decided_at`required	string (date-time) \| null	When the request was fulfilled, declined or withdrawn.

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

Example

bash

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