Docs
⌘K
Sandboxes ›

Add sandbox tag

PUT/v1/sandboxes/{id}/tags/{tag}

Gives the sandbox one more tag of its own, and leaves its others as they are, so that two callers tagging one sandbox at once lose neither. A tag it has already is left as it is. PATCH /v1/sandboxes/{id} with tags puts a whole list in place of its own instead.

Requestcurl
  1. curl -X PUT https://agental.io/v1/sandboxes/sbx_2a9a47e50daec64a/tags/example-tag \
  2. -H "Authorization: Bearer $AGENTAL_API_KEY"
Answer200 OK · Sandbox
  1. {
  2. "id": string,
  3. "name": string,
  4. "region": string,
  5. "size": "tiny" | "small" | "medium" | "large",
  6. "status": "creating" | "running" | "stopped" | "error" | "deleted" | "restoring" | …,
  7. "hostId": string | null,
  8. "vmIsolation": boolean,
  9. "resources": {
  10. "vcpu": integer,
  11. "memoryMb": integer,
  12. "diskGb": integer,
  13. },
  14. "error": string | null,
  15. … 20 more
  16. }

Sandbox, with the tag.

Path

idrequired
string
 e.g. "sbx_0123456789abcdef"
tagrequired
string
 e.g. "run-7f3a"

Headers

Authorizationrequired
Bearer key
An API key that may make this call.

Returns

200 Sandbox, with the tag.

Sandbox29 fields
id
string
name
string
region
string
The region it runs in.
More It is placed, moved and kept on servers of that region and no other.
size
tinysmallmediumlarge
status
creatingrunningstoppederrordeletedrestoringmigrating
running: use it.
More stopped: start it. creating, restoring or migrating: wait, and read it again. restoring is a stopped sandbox whose start is under way: one that was accepted with 202, or one the service makes itself after moving a sandbox that was running. Its machine is being brought back from storage, or was being archived or moved when the start arrived, or has just been moved. Read the sandbox every 10 seconds until its status is running. If the start fails, the status is stopped again and error says why: start it again. migrating is a stopped sandbox whose machine is being moved to another server, with its disk and its snapshots. What needs the machine answers 409 sandbox_migrating meanwhile: read the sandbox every 10 seconds until its status changes, then carry on. A start of one that is migrating is accepted with 202, and its status is restoring from then until it is running. A sandbox that is running can be moved too, for maintenance of the server it is on. It is moved while it runs: its status is running all the while, it stands still for a few seconds, what is running in it goes on, and its machine's own network address changes, so connections that were open are lost. A request cut at that moment answers 503 sandbox_moved and is sent again, and what would change its machine answers 409 sandbox_migrating for as long as the move takes. More rarely, when it cannot be moved while it runs, it is stopped, and its status is then migrating, then restoring, then running again, with nothing asked of its owner. Its disk is kept and what was running in it is not, as after a stop and a start, and migratedAt says when.
hostId
stringnull
vmIsolation
boolean
True when the sandbox runs in its own virtual machine.
resources
MachineResources3 fields
vcpu
integer
memoryMb
integer
diskGb
integer
error
stringnull
What went wrong, or null.
More On a sandbox that is stopped, it says why a start that was accepted with 202 failed. A start that is accepted, or one that works, clears it.
createdAt
string
updatedAt
string
stoppedAt
stringnull
ttlSeconds
integernull
Seconds the sandbox runs after a start before it is stopped.
More Stop keeps the disk. Null uses the deployment default. The count begins again at every start, the one that follows a move to another server included. PUT /v1/sandboxes/{id}/auto-stop moves the stop of the run under way.
autoStopAt
stringnull
When this running sandbox will be stopped: the time PUT /v1/sandboxes/{id}/auto-stop set for the run under way, or else its last start plus ttlSeconds.
More Null when it is not running, or has no time limit: it then runs until it is stopped.
subdomain
stringnull
Stored only.
More This is not registered in DNS.
shared
boolean
Organization share flag.
More Stored only. It does not publish a URL.
templateId
stringnull
The template the sandbox is on.
More Its commands get that template's variables and files as they were when it last started, or was applied to, with the sandbox's own on top. GET /v1/sandboxes/{id}/template says whether it is up to date with the template.
organizationId
string
The organization it belongs to, which pays for it: the one the request that made it acted in.
createdBy
stringnull
The account that made it, whose address its mail to its account is sent to.
More Null when it was made with the dev key, and once that account is erased.
archived
boolean
True when the sandbox's machine is kept in storage and not where sandboxes run.
More Its status is stopped and nothing on its disk is lost. A start brings it back, which takes longer than a start of one that is not archived. While it is brought back its status is restoring, and this is still true.
archivedAt
stringnull
When it was archived.
More Null when it is not.
migratedAt
stringnull
When the service last stopped the sandbox, while it was running, to move it to another server.
More It was stopped, moved and started again, so its disk is as it was and what was running in it then is gone: start that again. It is set also when the move could not be made and the sandbox was started again where it was. Null if it never happened. A move of a sandbox that was already stopped does not set it, and neither does a move of one while it runs, which stops nothing.
memoryKept
boolean
True while it is stopped with its memory kept, by POST /v1/sandboxes/{id}/stop with keepMemory: a start puts back every process as it was, and its clock is set again.
More It costs 10% of its running price meanwhile, and is not archived. A snapshot put back while it is stopped lets the memory go. False whenever it is not stopped.
memoryLost
stringnull
Why the memory its last stop kept was not put back by its last start, which started it from its disk: as after an upgrade of the server it is on, which the memory cannot be put back across.
More Null when it was put back, or none was kept.
network
SandboxNetwork2 fields
outbound
openblockedallowlist
What the sandbox may reach outside itself: its template's rule with its own addresses on top.
More open is the internet, which is what a sandbox has when nothing is asked. blocked lets nothing out: names still resolve, and no connection leaves. allowlist lets out only what goes to an address in allow. It is enforced outside the sandbox, on the server it runs on, so nothing running in the sandbox can change it, root included. What reaches the sandbox is not affected: commands, files and its public addresses work as before. Whatever this says, no sandbox reaches another sandbox or a private network, or delivers mail on port 25.
allow
string[]
The IPv4 addresses and ranges an allowlist lets out to, over any protocol and port: its template's and its own.
More Empty for open and blocked.
tags
string[]
Its template's tags and its own, each once: the template's first.
More A change to its template's tags shows here at once. GET /v1/sandboxes?tag= finds sandboxes by them.
metadata
object
Its template's metadata, with its own value for a key in place of the template's.
More A change to its template's shows here at once, for the keys it does not set itself.
ownTags
string[]
Of its tags, the ones it has itself, and not from its template.
More PATCH /v1/sandboxes/{id} sets them.
ownMetadata
object
Of its metadata, the keys it sets itself.
More PATCH /v1/sandboxes/{id} changes them.

Errors and other answers

400invalid_tag the tag is not one.
400too_many_tags it has 30 of its own. Nothing was changed.
404 Not found.

Every error answers { "error": { "code", "message" } }; a key without the action a call needs answers 403 key_action_forbidden, naming it.

← Exec commandRemove sandbox tag →