Write the code that names, finds, and lists sandboxes.
Before you start
- To read and list sandboxes, you need an API key with the
sandboxes:readscope. To create, change, or delete sandboxes, you needsandboxes:write. See API keys. - Read Create, get, and delete a sandbox first.
Give a sandbox a name and labels
Sendname and labels in the body of POST /v1/sandboxes:
- It has 1 to 63 characters: lowercase letters, digits, and hyphens.
- It cannot start or end with a hyphen.
- It is unique in the workspace. Two workspaces can use the same name.
- A sandbox can have up to 50 labels.
- A key has 1 to 63 characters: letters, digits, and the characters
._/-. It starts and ends with a letter or a digit. - A value has up to 255 characters.
When the name is in use
If another sandbox in the workspace has the name, the API answers409 with the code sandbox_name_taken. The sandboxId field gives the sandbox that has the name:
failed, deleting, or deleted. Then a new sandbox can use the name. For example, a create that answers 503 no_capacity does not keep the name, so a retry can use it.
Change the name or the labels
SendPATCH /v1/sandboxes/{id} with the fields to change. The API changes only the fields that you send:
namesets a new name.nullremoves the name.labelsreplaces all labels of the sandbox.{}removes all labels.
200 with the changed sandbox. A name that another sandbox has answers 409 sandbox_name_taken.
The same request also takes state to stop or resume the sandbox. See Stop and resume a sandbox.
Find a sandbox by its name
SendGET /v1/sandboxes with the name parameter:
failed or deleting can have the same name as a newer sandbox. To get only sandboxes that you can use, also send state, for example state=running&state=stopped.
List sandboxes
GET /v1/sandboxes returns one page of sandboxes, newest first by default. A deleted sandbox is not in the list. Use these query parameters:
The response has
data, the sandboxes, and nextCursor. If nextCursor is null, the page is the last page. To get the next page, send the same parameters with cursor set to nextCursor:
List the cost of each sandbox
Addinclude=cost to GET /v1/sandboxes. Each sandbox gets costMicros, its cost since the first day of the month (UTC). The page gets deletedCostMicros, the cost of the deleted sandboxes this month. Amounts are in micro-dollars: 1,000,000 is $1.
Create or delete many sandboxes
SendPOST /v1/sandboxes/create-many with items, a list of 1 to 500 creates. Each item has the fields of a create. Send POST /v1/sandboxes/delete-many with ids, a list of 1 to 500 sandbox IDs.
200 with a result for each item, in the sequence of the request:
- For a create,
idis the ID of the new sandbox. If the create failed,idisnullanderrorgives the reason. - For a delete,
idis the ID that you sent. If the delete failed,errorgives the reason. messageis the first error, ornull.
create-many takes no Idempotency-Key. Each new sandbox moves to running as a single create does. Each deleted sandbox moves to deleting, then to deleted.