AnkraDocs
Console

API reference · Managed services

Playgrounds

7 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
NameInTypeDescription
cursorquerystringThe next_cursor of the previous page.
limitqueryintegerPage 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
FieldTypeDescription
itemsrequiredarray of Playground
idrequiredstring
namerequiredstringThe DNS label, pg- and ten hex digits.
regionrequiredstring
staterequiredstringprovisioning 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
limitsrequiredPlaygroundLimitsWhat the playground's workloads may use; the control plane's own reservation comes on top.
vcpusrequiredinteger
memory_mebibytesrequiredinteger
storage_gibibytesrequiredinteger
podsrequiredinteger
volumesrequiredinteger
app_domainrequiredstringThe wildcard the playground serves its Ingresses under.
endpointrequiredstring | nullThe API server URL once ready.
end_reasonrequiredstring | nullOne of expired, deleted, ended_by_staff, failed
failure_reasonrequiredstring | nullWhy a playground that failed to start did.
created_atrequiredstring (date-time)
ready_atrequiredstring (date-time) | null
expires_atrequiredstring (date-time)
extended_atrequiredstring (date-time) | nullWhen the playground took its one extension (extend_playground); null while it has not.
ended_atrequiredstring (date-time) | null
deleted_atrequiredstring (date-time) | null
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/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, reason: email_domain_blocked when the caller's email address is at a disposable or blocked domain; 422 for a region that does not offer playgrounds; 503 while playgrounds are not offered, and with reason: at_capacity when the region (or, without one, every offered region) holds its maximum of active playgrounds. Recorded in the account's audit log (playground.start).

Request bodyapplication/json · StartPlayground

Request body fields
FieldTypeDescription
regionstring | nullA region from regions of get_playground_offer; the first when absent.

Responses

201The provisioning playground.application/json · PlaygroundEnvelope

201 response fields
FieldTypeDescription
playgroundrequiredPlayground
idrequiredstring
namerequiredstringThe DNS label, pg- and ten hex digits.
regionrequiredstring
staterequiredstringprovisioning 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
limitsrequiredPlaygroundLimitsWhat the playground's workloads may use; the control plane's own reservation comes on top.
vcpusrequiredinteger
memory_mebibytesrequiredinteger
storage_gibibytesrequiredinteger
podsrequiredinteger
volumesrequiredinteger
app_domainrequiredstringThe wildcard the playground serves its Ingresses under.
endpointrequiredstring | nullThe API server URL once ready.
end_reasonrequiredstring | nullOne of expired, deleted, ended_by_staff, failed
failure_reasonrequiredstring | nullWhy a playground that failed to start did.
created_atrequiredstring (date-time)
ready_atrequiredstring (date-time) | null
expires_atrequiredstring (date-time)
extended_atrequiredstring (date-time) | nullWhen the playground took its one extension (extend_playground); null while it has not.
ended_atrequiredstring (date-time) | null
deleted_atrequiredstring (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.
  • 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/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
NameInTypeDescription
idrequiredpathstring

Responses

200The playground.application/json · PlaygroundEnvelope

200 response fields
FieldTypeDescription
playgroundrequiredPlayground
idrequiredstring
namerequiredstringThe DNS label, pg- and ten hex digits.
regionrequiredstring
staterequiredstringprovisioning 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
limitsrequiredPlaygroundLimitsWhat the playground's workloads may use; the control plane's own reservation comes on top.
vcpusrequiredinteger
memory_mebibytesrequiredinteger
storage_gibibytesrequiredinteger
podsrequiredinteger
volumesrequiredinteger
app_domainrequiredstringThe wildcard the playground serves its Ingresses under.
endpointrequiredstring | nullThe API server URL once ready.
end_reasonrequiredstring | nullOne of expired, deleted, ended_by_staff, failed
failure_reasonrequiredstring | nullWhy a playground that failed to start did.
created_atrequiredstring (date-time)
ready_atrequiredstring (date-time) | null
expires_atrequiredstring (date-time)
extended_atrequiredstring (date-time) | nullWhen the playground took its one extension (extend_playground); null while it has not.
ended_atrequiredstring (date-time) | null
deleted_atrequiredstring (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.
  • 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/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
NameInTypeDescription
idrequiredpathstring

Responses

200The ended playground.application/json · PlaygroundEnvelope

200 response fields
FieldTypeDescription
playgroundrequiredPlayground
idrequiredstring
namerequiredstringThe DNS label, pg- and ten hex digits.
regionrequiredstring
staterequiredstringprovisioning 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
limitsrequiredPlaygroundLimitsWhat the playground's workloads may use; the control plane's own reservation comes on top.
vcpusrequiredinteger
memory_mebibytesrequiredinteger
storage_gibibytesrequiredinteger
podsrequiredinteger
volumesrequiredinteger
app_domainrequiredstringThe wildcard the playground serves its Ingresses under.
endpointrequiredstring | nullThe API server URL once ready.
end_reasonrequiredstring | nullOne of expired, deleted, ended_by_staff, failed
failure_reasonrequiredstring | nullWhy a playground that failed to start did.
created_atrequiredstring (date-time)
ready_atrequiredstring (date-time) | null
expires_atrequiredstring (date-time)
extended_atrequiredstring (date-time) | nullWhen the playground took its one extension (extend_playground); null while it has not.
ended_atrequiredstring (date-time) | null
deleted_atrequiredstring (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.
  • 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/playgrounds/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Give the account's playground its one free extension#

POST/v1/playgrounds/{id}/extend
Operation
extend_playground
Credentials
API token, Portal session
Requires
Permission operate

Moves expires_at of a provisioning or ready playground extension_hours (72) later and records when in extended_at. Free, and once per playground: 409 when the playground has already been extended, has ended or has expired; 403 with reason: account_suspended while the account is suspended. A kubeconfig issued before the extension stays valid only until the old expiry; fetch a new one. Recorded in the account's audit log (playground.extend).

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200The extended playground.application/json · PlaygroundEnvelope

200 response fields
FieldTypeDescription
playgroundrequiredPlayground
idrequiredstring
namerequiredstringThe DNS label, pg- and ten hex digits.
regionrequiredstring
staterequiredstringprovisioning 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
limitsrequiredPlaygroundLimitsWhat the playground's workloads may use; the control plane's own reservation comes on top.
vcpusrequiredinteger
memory_mebibytesrequiredinteger
storage_gibibytesrequiredinteger
podsrequiredinteger
volumesrequiredinteger
app_domainrequiredstringThe wildcard the playground serves its Ingresses under.
endpointrequiredstring | nullThe API server URL once ready.
end_reasonrequiredstring | nullOne of expired, deleted, ended_by_staff, failed
failure_reasonrequiredstring | nullWhy a playground that failed to start did.
created_atrequiredstring (date-time)
ready_atrequiredstring (date-time) | null
expires_atrequiredstring (date-time)
extended_atrequiredstring (date-time) | nullWhen the playground took its one extension (extend_playground); null while it has not.
ended_atrequiredstring (date-time) | null
deleted_atrequiredstring (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.
  • 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/playgrounds/<id>/extend' \
  -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
NameInTypeDescription
idrequiredpathstring

Responses

200The kubeconfig.application/json

200 response fields
FieldTypeDescription
kubeconfigrequiredstringThe kubeconfig YAML.
expires_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.
  • 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 '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), account_suspended, email_domain_blocked (the caller's email address is at a disposable or blocked domain) or at_capacity (every offered region holds its maximum of active playgrounds; try again later). 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
FieldTypeDescription
is_availablerequiredboolean
eligibilityrequiredstringOne of eligible, unavailable, active_playground, allowance_used, account_suspended, email_domain_blocked, at_capacity
regionsrequiredarray of string
lifetime_hoursrequiredinteger
extension_hoursrequiredintegerHow much later the one free extension (extend_playground) moves the expiry.
allowancerequiredinteger
allowance_usedrequiredinteger
limitsrequiredPlaygroundLimitsWhat the playground's workloads may use; the control plane's own reservation comes on top.
vcpusrequiredinteger
memory_mebibytesrequiredinteger
storage_gibibytesrequiredinteger
podsrequiredinteger
volumesrequiredinteger
activerequiredPlayground | null
idrequiredstring
namerequiredstringThe DNS label, pg- and ten hex digits.
regionrequiredstring
staterequiredstringprovisioning 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
limitsrequiredPlaygroundLimitsWhat the playground's workloads may use; the control plane's own reservation comes on top.
vcpusrequiredinteger
memory_mebibytesrequiredinteger
storage_gibibytesrequiredinteger
podsrequiredinteger
volumesrequiredinteger
app_domainrequiredstringThe wildcard the playground serves its Ingresses under.
endpointrequiredstring | nullThe API server URL once ready.
end_reasonrequiredstring | nullOne of expired, deleted, ended_by_staff, failed
failure_reasonrequiredstring | nullWhy a playground that failed to start did.
created_atrequiredstring (date-time)
ready_atrequiredstring (date-time) | null
expires_atrequiredstring (date-time)
extended_atrequiredstring (date-time) | nullWhen the playground took its one extension (extend_playground); null while it has not.
ended_atrequiredstring (date-time) | null
deleted_atrequiredstring (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).
  • 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/playgrounds/offer' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"