Regions
Lists the regions the organization can create its own regions under.
AuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: read:regions
org_id*stringThe organization ID
uuidThe parent regions
application/json- response
The parent regions the organization may create a region under.
parent_regions*array<>The parent regions, ordered by ID.
curl -X GET 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/parent-regions'{ "parent_regions": [ { "id": "string", "name": "string" } ]}AuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: read:regions
org_id*stringThe organization ID
uuidlimit?integerMaximum number of items to return, 1–200 (default 100)
int641 <= value <= 200100cursor?stringOpaque continuation token returned as next_cursor by a previous request
The page of organization regions
application/json- response
A page of organization regions.
next_cursor?|The cursor for the next page, or null on the last page.
regions*array<>The regions on this page, ordered by ID.
curl -X GET 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/regions'{ "next_cursor": "string", "regions": [ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "name": "string", "parent_region_id": "string", "preview_domain": "string", "runner_count": 0, "sandbox_cidr": "string", "status": "active", "subnet_prefix_length": 0, "toolbox_proxy_url": "string", "updated_at": "2019-08-24T14:15:22Z" } ]}Creates a region whose sandboxes run on the organization's own infrastructure, under one of the organization's parent regions. The region ID is generated.
AuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: write:regions
org_id*stringThe organization ID
uuidapplication/json- body
The body of an organization-region create.
name*stringThe display name, 1 to 100 characters.
parent_region_id*stringThe ID of a parent region from the organization's parent regions.
sandbox_cidr?|The private IPv4 range sandbox addresses are allocated from, a prefix
length between 12 and 20. Default 10.213.0.0/16.
subnet_prefix_length?|The prefix length of each runner's subnet, between 22 and 28 and longer
than the prefix length of sandbox_cidr. Default 24.
int32The created organization region
application/json- response
A region an organization created on its own infrastructure.
created_at*stringWhen the region was created.
date-timeid*stringThe region ID. Generated when the region is created; pass it as the region of a sandbox create.
name*stringThe display name.
parent_region_id*stringThe ID of the parent region this region was created under.
preview_domain?|The base domain of the region's preview URLs, or null when none is
set.
runner_count*integerThe number of runners enrolled in the region.
int64sandbox_cidr*stringThe private IPv4 range sandbox addresses are allocated from.
status*RegionStatusWhether the region accepts new sandboxes.
"active""disabled"subnet_prefix_length*integerThe prefix length of the subnet each runner receives from
sandbox_cidr.
int32toolbox_proxy_url?|The base URL of the region's proxy, or null when none is
set.
updated_at*stringWhen the region last changed.
date-timecurl -X POST 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/regions' \ -H 'Content-Type: application/json' \ -d '{ "name": "string", "parent_region_id": "string"}'{ "created_at": "2019-08-24T14:15:22Z", "id": "string", "name": "string", "parent_region_id": "string", "preview_domain": "string", "runner_count": 0, "sandbox_cidr": "string", "status": "active", "subnet_prefix_length": 0, "toolbox_proxy_url": "string", "updated_at": "2019-08-24T14:15:22Z"}AuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: read:regions
org_id*stringThe organization ID
uuidregion_id*stringThe organization region ID
The organization region
application/json- response
A region an organization created on its own infrastructure.
created_at*stringWhen the region was created.
date-timeid*stringThe region ID. Generated when the region is created; pass it as the region of a sandbox create.
name*stringThe display name.
parent_region_id*stringThe ID of the parent region this region was created under.
preview_domain?|The base domain of the region's preview URLs, or null when none is
set.
runner_count*integerThe number of runners enrolled in the region.
int64sandbox_cidr*stringThe private IPv4 range sandbox addresses are allocated from.
status*RegionStatusWhether the region accepts new sandboxes.
"active""disabled"subnet_prefix_length*integerThe prefix length of the subnet each runner receives from
sandbox_cidr.
int32toolbox_proxy_url?|The base URL of the region's proxy, or null when none is
set.
updated_at*stringWhen the region last changed.
date-timecurl -X GET 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/regions/string'{ "created_at": "2019-08-24T14:15:22Z", "id": "string", "name": "string", "parent_region_id": "string", "preview_domain": "string", "runner_count": 0, "sandbox_cidr": "string", "status": "active", "subnet_prefix_length": 0, "toolbox_proxy_url": "string", "updated_at": "2019-08-24T14:15:22Z"}AuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: write:regions
org_id*stringThe organization ID
uuidregion_id*stringThe organization region ID
application/json- body
The body of an organization-region update. An omitted field keeps its
value; null clears toolbox_proxy_url or preview_domain.
name?|The new display name, 1 to 100 characters.
preview_domain?|The base domain of the region's preview URLs. Must be unique, must not
be a public suffix such as co.uk, and must not be, or be inside, a
domain the platform serves.
toolbox_proxy_url?|The base URL of the region's proxy. Must be an https:// URL.
The organization region
application/json- response
A region an organization created on its own infrastructure.
created_at*stringWhen the region was created.
date-timeid*stringThe region ID. Generated when the region is created; pass it as the region of a sandbox create.
name*stringThe display name.
parent_region_id*stringThe ID of the parent region this region was created under.
preview_domain?|The base domain of the region's preview URLs, or null when none is
set.
runner_count*integerThe number of runners enrolled in the region.
int64sandbox_cidr*stringThe private IPv4 range sandbox addresses are allocated from.
status*RegionStatusWhether the region accepts new sandboxes.
"active""disabled"subnet_prefix_length*integerThe prefix length of the subnet each runner receives from
sandbox_cidr.
int32toolbox_proxy_url?|The base URL of the region's proxy, or null when none is
set.
updated_at*stringWhen the region last changed.
date-timecurl -X PATCH 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/regions/string' \ -H 'Content-Type: application/json' \ -d '{}'{ "created_at": "2019-08-24T14:15:22Z", "id": "string", "name": "string", "parent_region_id": "string", "preview_domain": "string", "runner_count": 0, "sandbox_cidr": "string", "status": "active", "subnet_prefix_length": 0, "toolbox_proxy_url": "string", "updated_at": "2019-08-24T14:15:22Z"}Deletes a region that has no runners and no sandboxes left.
AuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: delete:regions
org_id*stringThe organization ID
uuidregion_id*stringThe organization region ID
Organization region deleted
curl -X DELETE 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/regions/string'Returns the non-secret values an installation of the region's runners and proxy needs.
AuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: read:regions
org_id*stringThe organization ID
uuidregion_id*stringThe organization region ID
The region installation
application/json- response
The non-secret values an installation in the region needs.
api_url?|The API URL runners enroll against, or null when not configured.
bootstrap_image?|The image that runs the bootstrap script, or null when not
configured.
bus_url?|The message bus address the region's runners connect out to, or null
when not configured. Allow it in your firewall.
chart*stringThe Helm chart that installs the region's runners, as an OCI reference.
chart_version?|The chart version to install, or null for the latest.
installer_image?|The installer image, or null when not configured.
proxy_image?|The proxy image, or null when not configured.
region_id*stringThe region ID.
terraform_module?|The Terraform module, as an OCI reference, or null when not
configured.
usage_reporting_url?|The address the region's runners report sandbox usage to, or null
when not configured. Allow it in your firewall.
curl -X GET 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/regions/string/installation'{ "api_url": "string", "bootstrap_image": "string", "bus_url": "string", "chart": "string", "chart_version": "string", "installer_image": "string", "proxy_image": "string", "region_id": "string", "terraform_module": "string", "usage_reporting_url": "string"}AuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: read:regions
org_id*stringThe organization ID
uuidregion_id*stringThe organization region ID
limit?integerMaximum number of items to return, 1–200 (default 100)
int641 <= value <= 200100cursor?stringOpaque continuation token returned as next_cursor by a previous request
The page of region proxy tokens
application/json- response
A page of the region's live proxy tokens.
next_cursor?|The cursor for the next page, or null on the last page.
proxy_tokens*array<>The proxy tokens, newest first.
curl -X GET 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/regions/string/proxy-tokens'{ "next_cursor": "string", "proxy_tokens": [ { "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "last_used_at": "2019-08-24T14:15:22Z", "name": "string", "region_id": "string", "rotated_from": "c5500ae4-3bf4-4b9d-9292-5dcc0d464d8b", "updated_at": "2019-08-24T14:15:22Z" } ]}Creates the token the region's own proxy authenticates with. The secret is returned only once.
AuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: write:regions
org_id*stringThe organization ID
uuidregion_id*stringThe organization region ID
application/json- body
The body of a proxy-token create. Name expires_at or set no_expiry.
expires_at?|When the token expires; must be in the future.
date-timename?|The display name, 1 to 100 characters.
no_expiry?booleanWhether the token never expires.
The created region proxy token
application/json- response
A newly created proxy token and its one-time secret.
created_at*stringWhen the token was created.
date-timeexpires_at?|When the token expires, or null when it does not.
date-timeid*stringThe proxy token ID.
uuidlast_used_at?|When the token last authenticated, or null when it never has.
date-timename?|The display name, or null when none was given.
region_id*stringThe region the token is bound to.
rotated_from?|The ID of the token this one replaced, or null.
uuidupdated_at*stringWhen the token last changed: a rotation shortens the replaced token's lifetime.
date-timetoken*stringThe secret, returned only when the token is created.
curl -X POST 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/regions/string/proxy-tokens' \ -H 'Content-Type: application/json' \ -d '{}'{ "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "last_used_at": "2019-08-24T14:15:22Z", "name": "string", "region_id": "string", "rotated_from": "c5500ae4-3bf4-4b9d-9292-5dcc0d464d8b", "updated_at": "2019-08-24T14:15:22Z", "token": "string"}Revokes the token and disconnects the proxy that holds it.
AuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: delete:regions
org_id*stringThe organization ID
uuidregion_id*stringThe organization region ID
proxy_token_id*stringThe region proxy token ID
uuidRegion proxy token deleted
curl -X DELETE 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/regions/string/proxy-tokens/497f6eca-6276-4993-bfeb-53cbbbba6f08'Creates a successor token. The replaced token keeps working for overlap_seconds.
AuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: write:regions
org_id*stringThe organization ID
uuidregion_id*stringThe organization region ID
proxy_token_id*stringThe region proxy token ID
uuidapplication/json- body
The body of a proxy-token rotation: the successor's lifetime, and how long the replaced token keeps working.
expires_at?|When the successor expires; must be in the future.
date-timename?|The successor's display name, 1 to 100 characters.
no_expiry?booleanWhether the successor never expires.
overlap_seconds?|Seconds the replaced token keeps working, 0 to 86400. Default 0.
int64The created region proxy token
application/json- response
A newly created proxy token and its one-time secret.
created_at*stringWhen the token was created.
date-timeexpires_at?|When the token expires, or null when it does not.
date-timeid*stringThe proxy token ID.
uuidlast_used_at?|When the token last authenticated, or null when it never has.
date-timename?|The display name, or null when none was given.
region_id*stringThe region the token is bound to.
rotated_from?|The ID of the token this one replaced, or null.
uuidupdated_at*stringWhen the token last changed: a rotation shortens the replaced token's lifetime.
date-timetoken*stringThe secret, returned only when the token is created.
curl -X POST 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/regions/string/proxy-tokens/497f6eca-6276-4993-bfeb-53cbbbba6f08/rotation' \ -H 'Content-Type: application/json' \ -d '{}'{ "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "last_used_at": "2019-08-24T14:15:22Z", "name": "string", "region_id": "string", "rotated_from": "c5500ae4-3bf4-4b9d-9292-5dcc0d464d8b", "updated_at": "2019-08-24T14:15:22Z", "token": "string"}AuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: read:regions
org_id*stringThe organization ID
uuidregion_id*stringThe organization region ID
limit?integerMaximum number of items to return, 1–200 (default 100)
int641 <= value <= 200100cursor?stringOpaque continuation token returned as next_cursor by a previous request
The page of registration tokens
application/json- response
A page of the region's live registration tokens.
next_cursor?|The cursor for the next page, or null on the last page.
registration_tokens*array<>The registration tokens, newest first.
curl -X GET 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/regions/string/registration-tokens'{ "next_cursor": "string", "registration_tokens": [ { "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "max_uses": 0, "name": "string", "region_id": "string", "updated_at": "2019-08-24T14:15:22Z", "uses": 0 } ]}Creates a token that enrolls runners into the region. The secret is returned only once.
AuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: write:runners
org_id*stringThe organization ID
uuidregion_id*stringThe organization region ID
application/json- body
The body of a registration-token create.
expires_in_seconds?|Seconds until the token expires, 300 to 2592000. Default 604800.
int64max_uses?|How many runners the token may enroll, 1 to 1000. Default 100.
int32name*stringThe display name, 1 to 100 characters.
The created registration token
application/json- response
A newly created registration token and its one-time secret.
created_at*stringWhen the token was created.
date-timeexpires_at*stringWhen the token stops enrolling runners.
date-timeid*stringThe registration token ID.
uuidmax_uses*integerHow many runners the token may enroll.
int32name*stringThe display name.
region_id*stringThe region the token enrolls runners into.
updated_at*stringWhen the token last changed.
date-timeuses*integerHow many runners the token has enrolled.
int32token*stringThe secret, returned only when the token is created.
curl -X POST 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/regions/string/registration-tokens' \ -H 'Content-Type: application/json' \ -d '{ "name": "string"}'{ "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "max_uses": 0, "name": "string", "region_id": "string", "updated_at": "2019-08-24T14:15:22Z", "uses": 0, "token": "string"}Revokes the token. Runners it already enrolled keep working.
AuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: delete:runners
org_id*stringThe organization ID
uuidregion_id*stringThe organization region ID
registration_token_id*stringThe registration token ID
uuidRegistration token deleted
curl -X DELETE 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/regions/string/registration-tokens/497f6eca-6276-4993-bfeb-53cbbbba6f08'AuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: read:runners
org_id*stringThe organization ID
uuidregion_id*stringThe organization region ID
limit?integerMaximum number of items to return, 1–200 (default 100)
int641 <= value <= 200100cursor?stringOpaque continuation token returned as next_cursor by a previous request
The page of region runners
application/json- response
A page of a region's runners.
next_cursor?|The cursor for the next page, or null on the last page.
runners*array<>The runners on this page.
curl -X GET 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/regions/string/runners'{ "next_cursor": "string", "runners": [ { "admin_state": "active", "billed_cores": 0, "enrolled_at": "2019-08-24T14:15:22Z", "id": "string", "last_seen_at": "2019-08-24T14:15:22Z", "node_name": "string", "region_id": "string", "sandbox_count": 0, "status": "online", "updated_at": "2019-08-24T14:15:22Z", "version": "string" } ]}AuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: read:runners
org_id*stringThe organization ID
uuidregion_id*stringThe organization region ID
runner_id*stringThe runner ID
The region runner
application/json- response
A runner enrolled in an organization region.
admin_state*OrganizationRunnerAdminStateWhether the runner accepts new sandboxes.
"active""cordoned"billed_cores?|The cores the runner is billed at per hour: its logical CPUs ÷ 2.
null before the runner first reports its CPUs.
doubleenrolled_at*stringWhen the runner enrolled.
date-timeid*stringThe runner ID.
last_seen_at?|When the runner was last heard from, or null when never.
date-timenode_name*stringThe Kubernetes node name the runner enrolled with.
region_id*stringThe region the runner is enrolled in.
sandbox_count*integerThe number of sandboxes on the runner.
int64status*OrganizationRunnerStatusWhether the runner is connected.
"online""offline""lost"updated_at*stringWhen the runner was last cordoned or uncordoned, or when it enrolled.
date-timeversion?|The runner software version, or null when not reported yet.
curl -X GET 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/regions/string/runners/string'{ "admin_state": "active", "billed_cores": 0, "enrolled_at": "2019-08-24T14:15:22Z", "id": "string", "last_seen_at": "2019-08-24T14:15:22Z", "node_name": "string", "region_id": "string", "sandbox_count": 0, "status": "online", "updated_at": "2019-08-24T14:15:22Z", "version": "string"}Removes the runner from the region and revokes its credentials. Its ID is never reused.
AuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: delete:runners
org_id*stringThe organization ID
uuidregion_id*stringThe organization region ID
runner_id*stringThe runner ID
Runner deleted
curl -X DELETE 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/regions/string/runners/string'Stops new sandboxes from being placed on the runner. Its running sandboxes keep running.
AuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: write:runners
org_id*stringThe organization ID
uuidregion_id*stringThe organization region ID
runner_id*stringThe runner ID
The region runner
application/json- response
A runner enrolled in an organization region.
admin_state*OrganizationRunnerAdminStateWhether the runner accepts new sandboxes.
"active""cordoned"billed_cores?|The cores the runner is billed at per hour: its logical CPUs ÷ 2.
null before the runner first reports its CPUs.
doubleenrolled_at*stringWhen the runner enrolled.
date-timeid*stringThe runner ID.
last_seen_at?|When the runner was last heard from, or null when never.
date-timenode_name*stringThe Kubernetes node name the runner enrolled with.
region_id*stringThe region the runner is enrolled in.
sandbox_count*integerThe number of sandboxes on the runner.
int64status*OrganizationRunnerStatusWhether the runner is connected.
"online""offline""lost"updated_at*stringWhen the runner was last cordoned or uncordoned, or when it enrolled.
date-timeversion?|The runner software version, or null when not reported yet.
curl -X POST 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/regions/string/runners/string/cordon'{ "admin_state": "active", "billed_cores": 0, "enrolled_at": "2019-08-24T14:15:22Z", "id": "string", "last_seen_at": "2019-08-24T14:15:22Z", "node_name": "string", "region_id": "string", "sandbox_count": 0, "status": "online", "updated_at": "2019-08-24T14:15:22Z", "version": "string"}Lets new sandboxes be placed on the runner again.
AuthorizationBearer <token>Bearer access token for a signed-in user.
Scope: write:runners
org_id*stringThe organization ID
uuidregion_id*stringThe organization region ID
runner_id*stringThe runner ID
The region runner
application/json- response
A runner enrolled in an organization region.
admin_state*OrganizationRunnerAdminStateWhether the runner accepts new sandboxes.
"active""cordoned"billed_cores?|The cores the runner is billed at per hour: its logical CPUs ÷ 2.
null before the runner first reports its CPUs.
doubleenrolled_at*stringWhen the runner enrolled.
date-timeid*stringThe runner ID.
last_seen_at?|When the runner was last heard from, or null when never.
date-timenode_name*stringThe Kubernetes node name the runner enrolled with.
region_id*stringThe region the runner is enrolled in.
sandbox_count*integerThe number of sandboxes on the runner.
int64status*OrganizationRunnerStatusWhether the runner is connected.
"online""offline""lost"updated_at*stringWhen the runner was last cordoned or uncordoned, or when it enrolled.
date-timeversion?|The runner software version, or null when not reported yet.
curl -X POST 'https://example.com/orgs/497f6eca-6276-4993-bfeb-53cbbbba6f08/regions/string/runners/string/uncordon'{ "admin_state": "active", "billed_cores": 0, "enrolled_at": "2019-08-24T14:15:22Z", "id": "string", "last_seen_at": "2019-08-24T14:15:22Z", "node_name": "string", "region_id": "string", "sandbox_count": 0, "status": "online", "updated_at": "2019-08-24T14:15:22Z", "version": "string"}Lists selectable regions in tree order: earth first, then each region followed by its contained regions. parent_region_ids lists containing regions. A parent region none of whose contained regions accepts automatic placement remains listed with available: false and cannot be requested when creating a sandbox.
AuthorizationBearer <token>Bearer project API key.
The regions
application/json- response
The caller's regions.
default_region_id*|ID of the caller's default region: the project's default region, else
the organization's, else the platform's. A client sends a create that
names no region to this region's api_base_url. null when that
region is not listed.
regions*array<>Every listed region in tree order: Earth first, then each region followed by the regions inside it.
curl -X GET 'https://example.com/regions'{ "default_region_id": "string", "regions": [ { "api_base_url": "string", "available": true, "id": "string", "name": "string", "parent_region_ids": [ "string" ] } ]}