API reference · Managed services

Playgrounds

6 operations of the Ankra Cloud API: Native playgrounds (ADR 0010): a free, short-lived Kubernetes cluster (a vCluster on the region's host cluster) for every verified account, one at a time and at most the allowance ever; staff list them and end one with a reason.

The account's playgrounds, newest first#

GET/v1/playgrounds

Operation: list_playgrounds
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 playgrounds (limit at most 100, default 20).application/json · PlaygroundList

200 response fields
Field	Type	Description
`items`required	array of Playground
`id`required	string
`name`required	string	The DNS label, `pg-` and ten hex digits.
`region`required	string
`state`required	string	`provisioning` until the API is ready, `ready` until it expires or is ended, `deleting` until everything it ran is gone, then `deleted`.One of `provisioning`, `ready`, `deleting`, `deleted`
`limits`required	PlaygroundLimits	What the playground's workloads may use; the control plane's own reservation comes on top.
`vcpus`required	integer
`memory_mebibytes`required	integer
`storage_gibibytes`required	integer
`pods`required	integer
`volumes`required	integer
`app_domain`required	string	The wildcard the playground serves its Ingresses under.
`endpoint`required	string \| null	The API server URL once ready.
`end_reason`required	string \| null	One of `expired`, `deleted`, `ended_by_staff`, `failed`
`failure_reason`required	string \| null	Why a playground that failed to start did.
`created_at`required	string (date-time)
`ready_at`required	string (date-time) \| null
`expires_at`required	string (date-time)
`ended_at`required	string (date-time) \| null
`deleted_at`required	string (date-time) \| null
`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/playgrounds' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Start the account's free playground#

POST/v1/playgrounds

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

Creates a playground in region (the first offered region when absent) that is provisioning until its API is ready (usually under a minute) and expires lifetime_hours after creation. Free: no payment method or credit is needed, but the caller's email address must be verified. 409 while the account has an active playground; 403 with reason: allowance_used once the account has used its free playground (one per account by default), reason: account_suspended while it is suspended; 422 for a region that does not offer playgrounds; 503 while playgrounds are not offered. Recorded in the account's audit log (playground.start).

Request bodyapplication/json · StartPlayground

Request body fields
Field	Type	Description
`region`	string \| null	A region from `regions` of `get_playground_offer`; the first when absent.

Responses

201The provisioning playground.application/json · PlaygroundEnvelope

201 response fields
Field	Type	Description
`playground`required	Playground
`id`required	string
`name`required	string	The DNS label, `pg-` and ten hex digits.
`region`required	string
`state`required	string	`provisioning` until the API is ready, `ready` until it expires or is ended, `deleting` until everything it ran is gone, then `deleted`.One of `provisioning`, `ready`, `deleting`, `deleted`
`limits`required	PlaygroundLimits	What the playground's workloads may use; the control plane's own reservation comes on top.
`vcpus`required	integer
`memory_mebibytes`required	integer
`storage_gibibytes`required	integer
`pods`required	integer
`volumes`required	integer
`app_domain`required	string	The wildcard the playground serves its Ingresses under.
`endpoint`required	string \| null	The API server URL once ready.
`end_reason`required	string \| null	One of `expired`, `deleted`, `ended_by_staff`, `failed`
`failure_reason`required	string \| null	Why a playground that failed to start did.
`created_at`required	string (date-time)
`ready_at`required	string (date-time) \| null
`expires_at`required	string (date-time)
`ended_at`required	string (date-time) \| null
`deleted_at`required	string (date-time) \| 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).
409The resource's state does not allow this now.
422The region does not offer playgrounds.
503No capacity or address is free, or a host did not answer; try again later.
defaultAny other error, usually 500.

Example

bash

curl -X POST 'https://cloud.ankra.app/v1/playgrounds' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "region": "string"
}'

One of the account's playgrounds#

GET/v1/playgrounds/{id}

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

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Responses

200The playground.application/json · PlaygroundEnvelope

200 response fields
Field	Type	Description
`playground`required	Playground
`id`required	string
`name`required	string	The DNS label, `pg-` and ten hex digits.
`region`required	string
`state`required	string	`provisioning` until the API is ready, `ready` until it expires or is ended, `deleting` until everything it ran is gone, then `deleted`.One of `provisioning`, `ready`, `deleting`, `deleted`
`limits`required	PlaygroundLimits	What the playground's workloads may use; the control plane's own reservation comes on top.
`vcpus`required	integer
`memory_mebibytes`required	integer
`storage_gibibytes`required	integer
`pods`required	integer
`volumes`required	integer
`app_domain`required	string	The wildcard the playground serves its Ingresses under.
`endpoint`required	string \| null	The API server URL once ready.
`end_reason`required	string \| null	One of `expired`, `deleted`, `ended_by_staff`, `failed`
`failure_reason`required	string \| null	Why a playground that failed to start did.
`created_at`required	string (date-time)
`ready_at`required	string (date-time) \| null
`expires_at`required	string (date-time)
`ended_at`required	string (date-time) \| null
`deleted_at`required	string (date-time) \| null

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

End the account's playground before it expires#

DELETE/v1/playgrounds/{id}

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

The playground becomes deleting (end_reason: deleted) and then deleted once everything it ran is gone, workloads and volumes included. Only a provisioning or ready playground can be ended (409 otherwise). Recorded in the account's audit log (playground.end).

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Responses

200The ended playground.application/json · PlaygroundEnvelope

200 response fields
Field	Type	Description
`playground`required	Playground
`id`required	string
`name`required	string	The DNS label, `pg-` and ten hex digits.
`region`required	string
`state`required	string	`provisioning` until the API is ready, `ready` until it expires or is ended, `deleting` until everything it ran is gone, then `deleted`.One of `provisioning`, `ready`, `deleting`, `deleted`
`limits`required	PlaygroundLimits	What the playground's workloads may use; the control plane's own reservation comes on top.
`vcpus`required	integer
`memory_mebibytes`required	integer
`storage_gibibytes`required	integer
`pods`required	integer
`volumes`required	integer
`app_domain`required	string	The wildcard the playground serves its Ingresses under.
`endpoint`required	string \| null	The API server URL once ready.
`end_reason`required	string \| null	One of `expired`, `deleted`, `ended_by_staff`, `failed`
`failure_reason`required	string \| null	Why a playground that failed to start did.
`created_at`required	string (date-time)
`ready_at`required	string (date-time) \| null
`expires_at`required	string (date-time)
`ended_at`required	string (date-time) \| null
`deleted_at`required	string (date-time) \| null

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

A kubeconfig with a cluster-admin credential of a ready playground (audited)#

GET/v1/playgrounds/{id}/kubeconfig

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

The credential is valid at most until the playground expires (expires_at). 409 while the playground is not ready. Recorded in the account's audit log (playground.kubeconfig).

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Responses

200The kubeconfig.application/json

200 response fields
Field	Type	Description
`kubeconfig`required	string	The kubeconfig YAML.
`expires_at`required	string (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.
409The resource's state does not allow this now.
defaultAny other error, usually 500.

Example

bash

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

Whether the account may start a free playground, and on what terms#

GET/v1/playgrounds/offer

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

eligibility is eligible, or why a playground cannot be started now: unavailable (playgrounds are not offered yet; is_available is false), active_playground (end the active one first), allowance_used (every free playground the account gets is used) or account_suspended. regions lists the regions that offer playgrounds, lifetime_hours how long one lives, limits what its workloads may use, allowance how many an account gets ever and allowance_used how many it used (playgrounds that failed to start do not count). active is the account's provisioning or ready playground, null when none. Starting one also needs a verified email address, which this answer does not check.

Responses

200The offer.application/json · PlaygroundOffer

200 response fields
Field	Type	Description
`is_available`required	boolean
`eligibility`required	string	One of `eligible`, `unavailable`, `active_playground`, `allowance_used`, `account_suspended`
`regions`required	array of string
`lifetime_hours`required	integer
`allowance`required	integer
`allowance_used`required	integer
`limits`required	PlaygroundLimits	What the playground's workloads may use; the control plane's own reservation comes on top.
`vcpus`required	integer
`memory_mebibytes`required	integer
`storage_gibibytes`required	integer
`pods`required	integer
`volumes`required	integer
`active`required	Playground \| null
`id`required	string
`name`required	string	The DNS label, `pg-` and ten hex digits.
`region`required	string
`state`required	string	`provisioning` until the API is ready, `ready` until it expires or is ended, `deleting` until everything it ran is gone, then `deleted`.One of `provisioning`, `ready`, `deleting`, `deleted`
`limits`required	PlaygroundLimits	What the playground's workloads may use; the control plane's own reservation comes on top.
`vcpus`required	integer
`memory_mebibytes`required	integer
`storage_gibibytes`required	integer
`pods`required	integer
`volumes`required	integer
`app_domain`required	string	The wildcard the playground serves its Ingresses under.
`endpoint`required	string \| null	The API server URL once ready.
`end_reason`required	string \| null	One of `expired`, `deleted`, `ended_by_staff`, `failed`
`failure_reason`required	string \| null	Why a playground that failed to start did.
`created_at`required	string (date-time)
`ready_at`required	string (date-time) \| null
`expires_at`required	string (date-time)
`ended_at`required	string (date-time) \| null
`deleted_at`required	string (date-time) \| null

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