Docs
⌘K

API endpoints

Every public call, 156 in all, read from the API's own OpenAPI 3.1 description. Pick one on the left for what it takes, what it returns, its errors, and how to make it.

https://agental.ioEvery path starts /v1; JSON in and out.
Authorization: Bearer ag_…An API key, which may make only the calls it was made for.
Idempotency-KeyOn a create: send it twice and get one sandbox.
{ "error": { "code" } }Every failure has one shape; the codes are on each call.

Sandboxes18

GET/v1/sandboxesSandboxes that have not been deleted.POST/v1/sandboxesCreate, from templateId or from default. Needs Idempotency-Key.GET/v1/sandboxes/{id}Read one sandbox.PATCH/v1/sandboxes/{id}Change ttlSeconds or name.DELETE/v1/sandboxes/{id}Delete. Needs X-Agental-Confirm-Delete.POST/v1/sandboxes/{id}/startStart again. 202 when archived.POST/v1/sandboxes/{id}/archiveMove a stopped disk to storage now.POST/v1/sandboxes/{id}/stopStop. Keeps the disk, and the memory with {"keepMemory":true}.POST/v1/sandboxes/{id}/execRun a command and wait for it.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.DELETE/v1/sandboxes/{id}/tags/{tag}Takes one of the sandbox's own tags away, and leaves its others as they are.GET/v1/sandboxes/{id}/auto-stopWhen a running sandbox is to be stopped, how long that is from now, and what decided it.PUT/v1/sandboxes/{id}/auto-stopMoves the stop of the run under way, later or sooner: to a time, or a number of seconds from now.DELETE/v1/sandboxes/{id}/auto-stopTakes its time limit away: it runs until it is stopped, this run and every start after.POST/v1/sandboxes/{id}/resumeResume sandbox.POST/v1/sandboxes/{id}/recoverRecover sandbox.GET/v1/stops/{id}Get stop.GET/v1/deletion-operations/{id}Get deletion operation.

Commands and files6

GET/v1/sandboxes/{id}/filesRead a file.PUT/v1/sandboxes/{id}/filesWrite a file.GET/v1/sandboxes/{id}/artifactsDownload artifact.POST/v1/sandboxes/{id}/commandsStart a command without waiting.GET/v1/sandboxes/{id}/commands/{commandId}Status and output of that command.POST/v1/sandboxes/{id}/exec/streamRun a command and stream its output.

Snapshots and forks10

POST/v1/sandboxes/{id}/forkCopy into a new sandbox. Needs Idempotency-Key.GET/v1/snapshotsEvery snapshot you keep.GET/v1/sandboxes/{id}/snapshotsThe snapshots of one sandbox.POST/v1/sandboxes/{id}/snapshotsTake a snapshot.POST/v1/sandboxes/{id}/restoreRoll the sandbox back to a snapshot.GET/v1/sandboxes/{id}/snapshots/latestGet latest sandbox snapshot.GET/v1/snapshots/{id}Get snapshot.DELETE/v1/snapshots/{id}Delete a snapshot.GET/v1/snapshots/{id}/treeGet snapshot tree.GET/v1/snapshots/{id}/filesGet snapshot file.

Templates23

GET/v1/templatesYour templates, default first.POST/v1/templatesMakes a template with nothing in it but the tags and metadata sent.GET/v1/templates/{id}Read one: the names of its variables and files, not their values, and which variables are kept out of the sandbox.PATCH/v1/templates/{id}Renames a template, or changes its tags and metadata, or both.DELETE/v1/templates/{id}Deletes a template that no sandbox is on.PUT/v1/templates/{id}/tags/{tag}Gives the template one more tag, and so every sandbox on it, at once, running or not.DELETE/v1/templates/{id}/tags/{tag}Takes a tag away from the template, and so from every sandbox on it that does not have it of its own, at once.GET/v1/templates/{id}/startWhat a sandbox made from the template starts as: its size, a snapshot or a new machine, and how long it runs after each start.PUT/v1/templates/{id}/startSets what a sandbox made from the template starts as, from now on: its size, a snapshot or a new machine, and how long it runs after each start.GET/v1/templates/{id}/secrets/variablesThe names of the template's variables, and which of them are kept out of the sandbox.GET/v1/templates/{id}/secrets/variables/{name}One of the template's variables: a plain one with its value, and one kept out of the sandbox with its hosts and its stand-in, never its value.PUT/v1/templates/{id}/secrets/variables/{name}Sets one of the template's variables, which every command run in it has in its environment.DELETE/v1/templates/{id}/secrets/variables/{name}Removes one of the template's variables.PUT/v1/templates/{id}/secrets/variables/{name}/hostsNarrows the hosts one of the template's kept-out variables is sent to, without sending its value again: each host has to be one it is sent to now, or under one of its wildcards.GET/v1/templates/{id}/secrets/filesWith path, one of the template's secret files and what it holds.PUT/v1/templates/{id}/secrets/filesSets one of the template's secret files, which is written into it, relative to its working folder, before every command.DELETE/v1/templates/{id}/secrets/filesRemoves one of the template's secret files.GET/v1/templates/{id}/networkWhat a sandbox on the template may reach outside itself, before the addresses of its own.PUT/v1/templates/{id}/networkSets what a sandbox on the template may reach outside itself, in place of the rule it had.GET/v1/templates/{id}/sandboxesThe sandboxes on the template, each with whether it has the template's variables, files and outbound rule as they are now, and the addresses of its own it may reach on top of the rule.POST/v1/templates/{id}/applyBrings running sandboxes on the template up to date with it now: all of them, or the ones named.GET/v1/sandboxes/{id}/templateWhich template the sandbox is on, whether it is up to date with it, and the names of what it has from it.PUT/v1/sandboxes/{id}/templatePuts the sandbox on another template of its account.

Secrets8

GET/v1/sandboxes/{id}/secrets/variablesThe names of the sandbox's variables, and which of them are kept out of the sandbox.GET/v1/sandboxes/{id}/secrets/variables/{name}One of the sandbox's variables: a plain one with its value, and one kept out of the sandbox with its hosts and its stand-in, never its value.PUT/v1/sandboxes/{id}/secrets/variables/{name}Sets one of the sandbox's variables, which every command run in it has in its environment.DELETE/v1/sandboxes/{id}/secrets/variables/{name}Removes one of the sandbox's variables.PUT/v1/sandboxes/{id}/secrets/variables/{name}/hostsNarrows the hosts one of the sandbox's kept-out variables is sent to, without sending its value again: each host has to be one it is sent to now, or under one of its wildcards.GET/v1/sandboxes/{id}/secrets/filesWith path, one of the sandbox's secret files and what it holds.PUT/v1/sandboxes/{id}/secrets/filesSets one of the sandbox's secret files, which is written into it, relative to its working folder, before every command.DELETE/v1/sandboxes/{id}/secrets/filesRemoves one of the sandbox's secret files.

Outbound rules2

GET/v1/sandboxes/{id}/networkWhat the sandbox may reach outside itself: the rule it is held to, as network on the sandbox says it, and what it comes from: its template's rule as the sandbox has it, and its own addresses on top.PUT/v1/sandboxes/{id}/networkSets the addresses the sandbox may reach on top of its template's outbound rule, in place of the ones it had.

Public URLs5

GET/v1/sandboxes/{id}/hostList sandbox host routes.POST/v1/sandboxes/{id}/hostGive a port a public address.GET/v1/host-routesList host routes.POST/v1/host-routes/{id}/hideHide host route.GET/v1/host-routes/{id}/proxyProxy host route.

SSH11

GET/v1/sandboxes/{id}/sshWhether SSH is turned on for the sandbox, and where it is logged in to now.PUT/v1/sandboxes/{id}/sshTurns SSH on for the sandbox.DELETE/v1/sandboxes/{id}/sshTurns SSH off for the sandbox.GET/v1/sandboxes/{id}/ssh/keysThe keys that may log in to the sandbox as root: what its machine's authorized keys file holds, whoever put it there, through this API or from inside.POST/v1/sandboxes/{id}/ssh/keysLets a public key log in to the sandbox as root.DELETE/v1/sandboxes/{id}/ssh/keys/{keyId}Lets a key log in to the sandbox no longer.GET/v1/templates/{id}/sshWhat a sandbox made from the template is given for SSH as it is made: whether SSH is turned on for it, and the public keys let in to its machine.PUT/v1/templates/{id}/sshTurns SSH on for every sandbox made from the template from now on: each has its port opened as it is made, as PUT /v1/sandboxes/{id}/ssh would, and GET /v1/sandboxes/{id}/ssh says where to connect.DELETE/v1/templates/{id}/sshA sandbox made from the template from now on has SSH off as it is made.POST/v1/templates/{id}/ssh/keysLets a public key log in as root to every sandbox made from the template from now on: it is written to the machine's authorized keys file as the sandbox is made, before the create answers.DELETE/v1/templates/{id}/ssh/keys/{keyId}Takes a key out of what the sandboxes made from the template from now on are given.

Desktop15

GET/v1/sandboxes/{id}/desktopWhether a desktop is turned on for the sandbox, whether it is running, and where it is watched.PUT/v1/sandboxes/{id}/desktopTurns a desktop on for the sandbox.DELETE/v1/sandboxes/{id}/desktopTurns the desktop off for the sandbox.GET/v1/sandboxes/{id}/desktop/screenshotA picture of the sandbox's screen as it is now.GET/v1/sandboxes/{id}/desktop/clipboardThe text on the clipboard of the sandbox's desktop: what a paste there, as ctrl+v, would put in.PUT/v1/sandboxes/{id}/desktop/clipboardPuts text on the clipboard of the sandbox's desktop, in place of what was on it, for a paste there to take.GET/v1/sandboxes/{id}/desktop/linksThe links to the sandbox's desktop that have not expired, the oldest first.POST/v1/sandboxes/{id}/desktop/linksMakes a link to the sandbox's desktop, at an address of its own, for someone to watch the screen, or use it as well, until the link expires: 10 minutes from now unless expiresIn says otherwise.DELETE/v1/sandboxes/{id}/desktop/links/{linkId}Takes a link to the sandbox's desktop away before it expires.POST/v1/sandboxes/{id}/desktop/clickMoves the pointer to a point of the sandbox's screen and presses a button there: once, or with count 2 or 3 as a double or a triple click.POST/v1/sandboxes/{id}/desktop/moveMoves the pointer to a point of the sandbox's screen, and presses nothing.POST/v1/sandboxes/{id}/desktop/dragPresses a button at one point of the sandbox's screen, moves the pointer to another with the button held, and lets go there.POST/v1/sandboxes/{id}/desktop/scrollMoves the pointer to a point of the sandbox's screen and turns the wheel there: dy notches down, or up when it is negative, and dx notches to the right, or to the left.POST/v1/sandboxes/{id}/desktop/typeTypes text on the sandbox's desktop, a key at a time, where its keyboard's focus is: click the field first.POST/v1/sandboxes/{id}/desktop/keyPresses keys on the sandbox's desktop.

Browser3

GET/v1/sandboxes/{id}/browserWhether the sandbox's browser is turned on to be driven from outside it, whether it is running, and where it is reached.PUT/v1/sandboxes/{id}/browserTurns the sandbox's browser on to be driven from outside it: Chrome is started in the sandbox's machine with its DevTools on, and the answer says where to connect.DELETE/v1/sandboxes/{id}/browserTurns the sandbox's browser off.

Email9

GET/v1/sandboxes/{id}/emailWhether mail is on for the sandbox, and the domain its addresses end in.PUT/v1/sandboxes/{id}/emailTurns mail on for the sandbox.DELETE/v1/sandboxes/{id}/emailTurns mail off for the sandbox.GET/v1/sandboxes/{id}/email/messagesThe sandbox's messages, newest first, a page at a time.POST/v1/sandboxes/{id}/email/messagesSends one message from the sandbox to the address of its own account, which is the only address a sandbox may write to.GET/v1/sandboxes/{id}/email/messages/{messageId}One message: who it is from, what was made of that, its headers and what it says.DELETE/v1/sandboxes/{id}/email/messages/{messageId}Deletes one message.GET/v1/sandboxes/{id}/email/messages/{messageId}/rawThe message exactly as it was transmitted, attachments included.GET/v1/emailThe account's mail: the handle every address of its sandboxes carries, what its plan allows, and what it has had of that today.

Metrics and telemetry7

GET/v1/sandboxes/{id}/metricsWhat one sandbox read between two moments: CPU, memory, disk and network.GET/v1/metricsWhat each of your sandboxes read at one moment.GET/v1/metrics/runningHow many of your sandboxes were running, step by step.GET/v1/telemetryWhere your metrics and events are sent, and how the last export went.PUT/v1/telemetrySet the OTLP collector they are sent to.DELETE/v1/telemetryStop sending to the collector.POST/v1/telemetry/testSend the collector one empty export.

Account, keys and webhooks32

GET/v1/meGet me.DELETE/v1/meErase a closed account now, rather than 30 days after it was closed.GET/v1/limitsGet limits.GET/v1/usageRunning time and list-price cost of your sandboxes, by sandbox, key, day and hour. apiKeyId narrows it to one key or several.GET/v1/sandboxes/{id}/usageThe same for one sandbox.GET/v1/api-keys/{id}/usageThe same for the sandboxes one key made.GET/v1/webhooksList your webhooks.POST/v1/webhooksAdd a webhook. Answers with its signing secret, once.GET/v1/webhooks/{id}One webhook, and its tries of the last 30 days.PATCH/v1/webhooks/{id}Change its url, events or description.DELETE/v1/webhooks/{id}Delete a webhook.POST/v1/webhooks/{id}/rotateA new signing secret.GET/v1/data-retentionHow long your sandboxes' history is kept, and what the last clean-up deleted.PATCH/v1/data-retentionKeep it 1, 7, 30 or 90 days, or until the sandbox is deleted.GET/v1/githubGet git hub connection.POST/v1/github/connectBegin git hub connection.POST/v1/github/installationsConnect git hub installation.DELETE/v1/github/installations/{installationId}Disconnect git hub installation.GET/v1/me/exportEverything kept about the account and you, as one JSON document.POST/v1/me/closeClose the account. A person signed in only. It can be reopened for 30 days.POST/v1/me/reopenOpen a closed account again.GET/v1/me/heardGet heard.PUT/v1/me/heardSet heard.GET/v1/api-keysYour keys: what each may do and where, and when and from where each was last used.POST/v1/api-keysMakes a key that may do what it is given and nothing else: a preset, or actions named.GET/v1/api-keys/{id}One key.DELETE/v1/api-keys/{id}Delete a key. Whatever holds it is refused from the next request.PUT/v1/api-keys/{id}/allow-fromReplaces the addresses the key may be used from, from its next request.GET/v1/policyGet policy.GET/v1/burstWhat your account runs against its plan's running count, what it may start now for nothing, and what a start of each size would cost in burst fees.PUT/v1/burst/budgetSet the most your account spends on burst fees in a month, or null for the default.GET/v1/tierGet tier.

Billing5

GET/v1/billing/plansWhat is sold: plans, top-ups and their bonus, the free plan's terms and the hourly prices.GET/v1/billingWhere the account stands: its plan, the month's usage, what is left.POST/v1/billing/checkoutThe payment page for a plan or a top-up, for a person to pay on.PUT/v1/billing/auto-reloadSet billing auto reload.POST/v1/billing/portalCreate billing portal.

Sizes and regions2

GET/v1/sizesList sizes.GET/v1/regionsThe regions sandboxes can be made in, and the sizes each has room for now.