# OpenAPI reference

Every endpoint of the Groundbox API, read from its OpenAPI spec, relative to `https://api.groundbox.dev/v1`. Send `Authorization: Bearer gbx_...`. Each endpoint names the scope its key needs.

[OpenAPI spec](https://groundbox.dev/openapi.json)[YAML](https://groundbox.dev/openapi.yaml)[API explorer](https://groundbox.dev/docs/api/explorer)[REST API guide](https://groundbox.dev/docs/api)

## Sandboxes

Start, list, change, pause, stop and delete sandboxes.

### List sandboxes

GET`/sandboxes`

Scope: `sandboxes:read`.

- `limit` integer optional query
- `cursor` string optional query
- `status` string | array of string optional query
- `live` boolean | "true" | "false" optional query
- `metadata` object optional query

Answers: `200` ListSandboxesResponse, `400`, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listSandboxes)

### Create a sandbox

POST`/sandboxes`

Starts a Linux VM. Billed by the second until it stops. Give `template`, `image` or `snapshot_id` to start from one.

Scope: `sandboxes:write`.

- `Idempotency-Key` string optional header

Body: `CreateSandboxRequest` (`cpus`, `memory_gb`, `disk_gb`, `timeout_minutes`, `on_timeout`, `idle_timeout_seconds`, `on_idle`, `idle_cpu_percent`, `wake_on_request`, `env`, `metadata`, `allow_hosts`, `deny_hosts`, `secrets`, `env_from_secrets`, `flex`, `shared_cpu`, `template`, `image`, `snapshot_id`, `volumes`, `desktop`).

Answers: `200` Sandbox, `400`, `401`, `402`, `403`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#createSandbox)

### Get a sandbox

GET`/sandboxes/{id}`

Scope: `sandboxes:read`.

- `id` string required path

Answers: `200` Sandbox, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getSandbox)

### Update a sandbox

PATCH`/sandboxes/{id}`

Change its timeout, metadata or egress allowlist.

Scope: `sandboxes:write`.

- `id` string required path

Body: `UpdateSandboxRequest` (`timeout_minutes`, `idle_timeout_seconds`, `on_idle`, `idle_cpu_percent`, `wake_on_request`, `allow_hosts`, `deny_hosts`, `metadata`).

Answers: `200` Sandbox, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#updateSandbox)

### Delete a sandbox

DELETE`/sandboxes/{id}`

Stops it and deletes its disk. Cannot be undone.

Scope: `sandboxes:write`.

- `id` string required path

Answers: `200` Sandbox, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#deleteSandbox)

### Pause a sandbox

POST`/sandboxes/{id}/pause`

Keeps its memory and disk. Billed for storage only while paused. The body may be left out.

Scope: `sandboxes:write`.

- `id` string required path

Answers: `200` Sandbox, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#pauseSandbox)

### Resume a paused sandbox

POST`/sandboxes/{id}/resume`

Scope: `sandboxes:write`.

- `id` string required path

Answers: `200` Sandbox, `400`, `401`, `402`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#resumeSandbox)

### Stop a sandbox

POST`/sandboxes/{id}/stop`

Shuts it down and keeps its disk: status `shut_down`, storage only.

Scope: `sandboxes:write`.

- `id` string required path

Answers: `200` Sandbox, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#stopSandbox)

### Start a stopped sandbox

POST`/sandboxes/{id}/start`

Boots it again from its kept disk: same id, a fresh VM.

Scope: `sandboxes:write`.

- `id` string required path

Answers: `200` Sandbox, `400`, `401`, `402`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#startSandbox)

### Get a sandbox's usage and cost

GET`/sandboxes/{id}/usage`

Scope: `sandboxes:read`.

- `id` string required path

Answers: `200` SandboxUsage, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getSandboxUsage)

### Open a TCP tunnel to a port

GET`/sandboxes/{id}/tcp/{port}`

A WebSocket. Binary messages are the connection's bytes, each way. For a database, SSH or anything that is not HTTP. `groundbox sandbox tcp` uses it.

Scope: `sandboxes:write`.

- `id` string required path
- `port` integer required path

Answers: `101`, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#tcpTunnel)

## Commands

Run commands in a sandbox, in one call or in the background, and read their output.

### Run a command

POST`/sandboxes/{id}/exec`

Runs it and answers when it exits, with its output and exit code.

Scope: `sandboxes:write`.

- `id` string required path

Body: `ExecRequest` (`cmd`, `args`, `cwd`, `env`, `encoding`, `timeout_s`, `stdin`, `stdin_base64`).

Answers: `200` ExecResponse, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#exec)

### Run a command over a WebSocket

GET`/sandboxes/{id}/exec/stream`

Output as it comes, stdin and terminal resize. Use the SDK or the CLI.

Scope: `sandboxes:write`.

- `id` string required path

Answers: `101`, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#execStream)

### List commands

GET`/sandboxes/{id}/commands`

Scope: `sandboxes:read`.

- `id` string required path
- `state` "running" | "exited" | "lost" optional query
- `limit` integer optional query

Answers: `200` ListCommandsResponse, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listCommands)

### Start a command in the background

POST`/sandboxes/{id}/commands`

Answers at once with the command's id. Read its output with `GET .../commands/{exec_id}/output`.

Scope: `sandboxes:write`.

- `id` string required path

Body: `StartCommandRequest` (`cmd`, `args`, `cwd`, `env`, `timeout_s`, `stdin`).

Answers: `200` SandboxCommand, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#startCommand)

### Get a command

GET`/sandboxes/{id}/commands/{exec_id}`

Scope: `sandboxes:read`.

- `id` string required path
- `exec_id` string required path

Answers: `200` SandboxCommand, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getCommand)

### Read a command's output

GET`/sandboxes/{id}/commands/{exec_id}/output`

Scope: `sandboxes:read`.

- `id` string required path
- `exec_id` string required path
- `seq` integer optional query
- `encoding` "utf8" | "base64" optional query

Answers: `200` CommandOutputResponse, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getCommandOutput)

### Kill a command

POST`/sandboxes/{id}/commands/{exec_id}/kill`

Scope: `sandboxes:write`.

- `id` string required path
- `exec_id` string required path

Body: `KillCommandRequest` (`signal`).

Answers: `200` SandboxCommand, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#killCommand)

## Files

Read, write, list and delete files in a sandbox.

### Read a file or list a folder

GET`/sandboxes/{id}/files`

With `path`, the file's bytes. With `dir`, the folder's entries as JSON. Pass exactly one.

Scope: `sandboxes:read`.

- `id` string required path
- `path` string optional query
- `dir` string optional query

Answers: `200` ListFilesResponse, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#readFiles)

### Write a file

PUT`/sandboxes/{id}/files`

The body is the file's bytes.

Scope: `sandboxes:write`.

- `id` string required path
- `path` string required query

Body: `application/octet-stream`.

Answers: `200` WriteFileResponse, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#writeFile)

### Delete a file or folder

DELETE`/sandboxes/{id}/files`

Scope: `sandboxes:write`.

- `id` string required path
- `path` string required query
- `recursive` boolean | "true" | "false" optional query

Answers: `200` DeleteFileResponse, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#deleteFile)

### Make a folder

POST`/sandboxes/{id}/files/mkdir`

Makes the parents it needs. A folder already there is fine (`created: false`).

Scope: `sandboxes:write`.

- `id` string required path
- `path` string required query

Answers: `200` MakeDirResponse, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#makeDir)

### Get a file's details

GET`/sandboxes/{id}/files/stat`

Scope: `sandboxes:read`.

- `id` string required path
- `path` string required query

Answers: `200` FileEntry, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#statFile)

## Snapshots

Save points, rewind, forks and snapshots kept beyond their sandbox.

### Fork a sandbox

POST`/sandboxes/{id}/fork`

A copy of the running VM. With `count`, `snapshot_id` or `size` the answer is a fork group.

Scope: `sandboxes:write`.

- `id` string required path
- `Idempotency-Key` string optional header

Body: `ForkSandboxRequest` (`metadata`, `timeout_minutes`, `cpus`, `memory_gb`, `disk_gb`, `snapshot_id`, `count`, `size`).

Answers: `200` ForkSandboxResponse, `400`, `401`, `402`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#forkSandbox)

### Get a sandbox's timeline

GET`/sandboxes/{id}/timeline`

Scope: `sandboxes:read`.

- `id` string required path

Answers: `200` SandboxTimeline, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getTimeline)

### Set automatic save points

POST`/sandboxes/{id}/timeline`

Scope: `sandboxes:write`.

- `id` string required path

Body: `SetTimelineRequest` (`interval_s` required, `keep`).

Answers: `200` SandboxTimeline, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#setTimeline)

### Make a save point now

POST`/sandboxes/{id}/snapshots`

Scope: `sandboxes:write`.

- `id` string required path

Body: `CreateSnapshotRequest` (`label`).

Answers: `200` TimelinePoint, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#createSnapshot)

### Delete a save point

DELETE`/sandboxes/{id}/snapshots/{snapshot_id}`

409 while a fork group is being restored from it.

Scope: `sandboxes:write`.

- `id` string required path
- `snapshot_id` string required path

Answers: `200` SandboxTimeline, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#deleteSavePoint)

### Rewind to a save point

POST`/sandboxes/{id}/restore`

Scope: `sandboxes:write`.

- `id` string required path

Body: `RestoreSandboxRequest` (`snapshot_id` required).

Answers: `200` RestoreSandboxResponse, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#restoreSandbox)

### List snapshots

GET`/snapshots`

Scope: `sandboxes:read`.

- `limit` integer optional query
- `cursor` string optional query
- `sandbox_id` string optional query

Answers: `200` ListSnapshotsResponse, `400`, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listSnapshots)

### Keep a snapshot

POST`/snapshots`

Keeps a moment of a sandbox beyond the sandbox. Billed per GB-month until deleted. Waits up to a minute; then answers with status `creating`.

Scope: `sandboxes:write`.

- `Idempotency-Key` string optional header

Body: `KeepSnapshotRequest` (`sandbox_id` required, `snapshot_id`, `label`).

Answers: `200` Snapshot, `400`, `401`, `402`, `403`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#keepSnapshot)

### Get a snapshot

GET`/snapshots/{id}`

Scope: `sandboxes:read`.

- `id` string required path

Answers: `200` Snapshot, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getSnapshot)

### Delete a snapshot

DELETE`/snapshots/{id}`

Sandboxes already started from it go on. 409 while one is still starting from it.

Scope: `sandboxes:write`.

- `id` string required path

Answers: `200` Snapshot, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#deleteSnapshot)

### Get a fork group

GET`/fork-groups/{id}`

Scope: `sandboxes:read`.

- `id` string required path

Answers: `200` ForkGroup, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getForkGroup)

### Delete a fork group

DELETE`/fork-groups/{id}`

Scope: `sandboxes:write`.

- `id` string required path

Answers: `200` ForkGroup, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#deleteForkGroup)

## Templates

Build a sandbox's disk once and start sandboxes from it.

### List templates

GET`/templates`

Scope: `sandboxes:read`.

- `limit` integer optional query
- `cursor` string optional query
- `include_hidden` "true" | "false" optional query

Answers: `200` ListTemplatesResponse, `400`, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listTemplates)

### Create a template

POST`/templates`

Scope: `sandboxes:write`.

- `Idempotency-Key` string optional header

Body: `CreateTemplateRequest` (`name` required, `image`, `dockerfile`, `apt`, `pip`, `npm`, `files`, `run`, `env`, `secrets`, `cpus`, `memory_gb`, `disk_gb`).

Answers: `200` Template, `400`, `401`, `402`, `403`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#createTemplate)

### Get a template

GET`/templates/{id}`

`{id}` is the id or the name.

Scope: `sandboxes:read`.

- `id` string required path

Answers: `200` Template, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getTemplate)

### Delete a template

DELETE`/templates/{id}`

Its versions stop at once; sandboxes running from it go on.

Scope: `sandboxes:write`.

- `id` string required path

Answers: `200` OkResponse, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#deleteTemplate)

### List a template's versions

GET`/templates/{id}/builds`

Scope: `sandboxes:read`.

- `id` string required path

Answers: `200` ListTemplateBuildsResponse, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listTemplateBuilds)

### Build a new version

POST`/templates/{id}/builds`

An empty body builds the newest version's spec again, with fresh packages.

Scope: `sandboxes:write`.

- `id` string required path
- `Idempotency-Key` string optional header

Body: `TemplateBuildSpec` (`image`, `dockerfile`, `apt`, `pip`, `npm`, `files`, `run`, `env`, `secrets`, `cpus`, `memory_gb`, `disk_gb`).

Answers: `200` TemplateBuild, `400`, `401`, `402`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#buildTemplate)

### Read a version's build log

GET`/templates/{id}/builds/{version}/logs`

Scope: `sandboxes:read`.

- `id` string required path
- `version` integer required path
- `after` integer optional query
- `wait_s` integer optional query

Answers: `200` TemplateLogsResponse, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getTemplateLogs)

### Get the default template

GET`/templates/default`

Scope: `sandboxes:read`.

Answers: `200` DefaultTemplateResponse, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getDefaultTemplate)

### Set the default template

PUT`/templates/default`

Scope: `sandboxes:write`.

Body: `SetDefaultTemplateRequest` (`template` required).

Answers: `200` DefaultTemplateResponse, `400`, `401`, `403`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#setDefaultTemplate)

## Volumes

Disks that outlive sandboxes.

### List volumes

GET`/volumes`

Scope: `sandboxes:read`.

- `limit` integer optional query
- `cursor` string optional query

Answers: `200` ListVolumesResponse, `400`, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listVolumes)

### Create a volume

POST`/volumes`

Billed per GB-month for its whole size until it is deleted.

Scope: `sandboxes:write`.

- `Idempotency-Key` string optional header

Body: `CreateVolumeRequest` (`name`, `size_gb` required).

Answers: `200` Volume, `400`, `401`, `402`, `403`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#createVolume)

### Get a volume

GET`/volumes/{id}`

`{id}` is the id or the name.

Scope: `sandboxes:read`.

- `id` string required path

Answers: `200` Volume, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getVolume)

### Delete a volume

DELETE`/volumes/{id}`

409 while it is attached to a sandbox that is not stopped. The data cannot be had back.

Scope: `sandboxes:write`.

- `id` string required path

Answers: `200` Volume, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#deleteVolume)

## Secrets

Team secrets, given to sandboxes by name. Values are write-only.

### Set a secret

PUT`/secrets/{name}`

Sets a team secret or replaces its value. The value is write-only.

Scope: `secrets:write`.

- `name` string required path

Body: `SetSecretRequest` (`value` required).

Answers: `200` Secret, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#setSecret)

### Delete a secret

DELETE`/secrets/{name}`

Sandboxes that use it fail their next command with 409 until it is set again.

Scope: `secrets:write`.

- `name` string required path

Answers: `200` OkResponse, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#deleteSecret)

### List secrets

GET`/secrets`

Names and dates. Never values.

Scope: `secrets:read`.

Answers: `200` ListSecretsResponse, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listSecrets)

## Agent computers

Computer-use actions, live view links and human handoff on desktop sandboxes.

### Do a computer-use action

POST`/sandboxes/{id}/computer`

One action on a desktop sandbox, in the shape computer-use models emit. 409 (`human_in_control`) while a person has control; 429 past the per-desktop rate.

Scope: `sandboxes:write`.

- `id` string required path

Body: `ComputerAction` (`action`, `format`, `quality`, `max_width`, `max_height`, `coordinate_space`, `screenshot`, `screenshot_delay_ms`, `coordinate`, `text`, `start_coordinate`, `scroll_direction`, `scroll_amount`, `duration`, `url`, `timeout_s`, `since`).

Answers: `200` ComputerActionResponse, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#computerAction)

### Get the handoff state

GET`/sandboxes/{id}/handoff`

With `after` (a version) and `wait_s`, waits up to 25 seconds for a change.

Scope: `sandboxes:read`.

- `id` string required path
- `after` integer optional query
- `wait_s` integer optional query

Answers: `200` HandoffState, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getHandoff)

### Ask a person to take control

POST`/sandboxes/{id}/handoff`

Scope: `sandboxes:write`.

- `id` string required path

Body: `RequestHandoffRequest` (`reason` required).

Answers: `200` HandoffState, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#requestHandoff)

### Withdraw a handoff request

POST`/sandboxes/{id}/handoff/cancel`

Scope: `sandboxes:write`.

- `id` string required path

Answers: `200` HandoffState, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#cancelHandoff)

### Take control

POST`/sandboxes/{id}/handoff/take`

A person takes control, from your own app's button. The body may be left out.

Scope: `sandboxes:write`.

- `id` string required path

Body: `TakeControlRequest` (`by`).

Answers: `200` HandoffState, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#takeControl)

### Give control back

POST`/sandboxes/{id}/handoff/return`

The person is done: the agent resumes. The body may be left out.

Scope: `sandboxes:write`.

- `id` string required path

Body: `ReturnControlRequest` (`note`).

Answers: `200` HandoffState, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#returnControl)

### List live view links

GET`/sandboxes/{id}/desktop/links`

Scope: `sandboxes:read`.

- `id` string required path

Answers: `200` ListDesktopLinksResponse, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listDesktopLinks)

### Create a live view link

POST`/sandboxes/{id}/desktop/links`

Scope: `sandboxes:write`.

- `id` string required path

Body: `CreateDesktopLinkRequest` (`control`, `expires_in_minutes`, `label`, `frame_origins`).

Answers: `200` CreateDesktopLinkResponse, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#createDesktopLink)

### Revoke a live view link

DELETE`/sandboxes/{id}/desktop/links/{link_id}`

Open viewers are cut off at once.

Scope: `sandboxes:write`.

- `id` string required path
- `link_id` string required path

Answers: `200` DesktopLink, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#revokeDesktopLink)

## Previews

A port in a sandbox at an HTTPS address, and custom domains for it.

### List custom domains

GET`/domains`

Scope: `sandboxes:read`.

Answers: `200` ListCustomDomainsResponse, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listDomains)

### Claim a custom domain

POST`/domains`

Answers with the two DNS records to add.

Scope: `sandboxes:write`.

Body: `CreateCustomDomainRequest` (`domain` required).

Answers: `201` CustomDomain, `400`, `401`, `403`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#createDomain)

### Get a custom domain

GET`/domains/{domain}`

Scope: `sandboxes:read`.

- `domain` string required path

Answers: `200` CustomDomain, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getDomain)

### Attach a domain to a preview

PATCH`/domains/{domain}`

Scope: `sandboxes:write`.

- `domain` string required path

Body: `UpdateCustomDomainRequest` (`sandbox_id`, `port`).

Answers: `200` CustomDomain, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#updateDomain)

### Remove a custom domain

DELETE`/domains/{domain}`

Scope: `sandboxes:write`.

- `domain` string required path

Answers: `200` OkResponse, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#deleteDomain)

### Check a domain's DNS records

POST`/domains/{domain}/verify`

Verified: the certificate is asked for. Not yet: 200 with `dns[].ok` saying which record is missing.

Scope: `sandboxes:write`.

- `domain` string required path

Answers: `200` CustomDomain, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#verifyDomain)

### List a sandbox's previews

GET`/sandboxes/{id}/previews`

Scope: `sandboxes:read`.

- `id` string required path

Answers: `200` ListPreviewsResponse, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listPreviews)

### Expose a port

POST`/sandboxes/{id}/previews`

A port in the sandbox at an HTTPS URL. Private unless `public: true`. 201 when made, 200 when the port has one already.

Scope: `sandboxes:write`.

- `id` string required path

Body: `CreatePreviewRequest` (`port` required, `public`).

Answers: `201` SandboxPreview, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#createPreview)

### Update a preview

PATCH`/sandboxes/{id}/previews/{port}`

Scope: `sandboxes:write`.

- `id` string required path
- `port` integer required path

Body: `UpdatePreviewRequest` (`public` required).

Answers: `200` SandboxPreview, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#updatePreview)

### Remove a preview

DELETE`/sandboxes/{id}/previews/{port}`

Its URL stops working.

Scope: `sandboxes:write`.

- `id` string required path
- `port` integer required path

Answers: `200` OkResponse, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#deletePreview)

### Report a preview

POST`/previews/report`

Anyone may report a preview for phishing or malware. No key.

No key.

Body: `PreviewReportRequest` (`url` required, `reason` required, `details`).

Answers: `200` OkResponse, `400`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#reportPreview)

## Schedules

Run a command in a fresh sandbox on a cron schedule.

### List schedules

GET`/schedules`

Scope: `schedules:read`.

- `limit` integer optional query
- `cursor` string optional query

Answers: `200` ListSchedulesResponse, `400`, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listSchedules)

### Create a schedule

POST`/schedules`

Each run starts a sandbox and is billed.

Scope: `schedules:write`.

Body: `CreateScheduleRequest` (`name`, `cron` required, `timezone`, `sandbox`, `cmd` required).

Answers: `200` Schedule, `400`, `401`, `402`, `403`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#createSchedule)

### Delete a schedule

DELETE`/schedules/{id}`

Scope: `schedules:write`.

- `id` string required path

Answers: `200` OkResponse, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#deleteSchedule)

## CI

Runs, jobs, logs, insights, auto size and test results for GitHub Actions on Groundbox.

### List CI runs

GET`/ci/runs`

Scope: `ci:read`.

- `limit` integer optional query
- `cursor` string optional query
- `repo` string optional query
- `branch` string optional query
- `sha` string optional query
- `status` enum optional query

Answers: `200` ListCiRunsResponse, `400`, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listCiRuns)

### Read a CI job's logs

GET`/ci/jobs/{id}/logs`

Scope: `ci:read`.

- `id` string required path

Answers: `200` CiLogsResponse, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getCiLogs)

### Wait for CI

POST`/ci/wait`

Waits for the run of a branch, commit or run id to finish, up to `timeout_s`. Pass exactly one of `branch`, `sha` or `run_id`.

Scope: `ci:read`.

Body: `CiWaitRequest` (`repo` required, `branch`, `sha`, `run_id`, `timeout_s`).

Answers: `200` CiWaitResponse, `400`, `401`, `403`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#waitForCi)

### Get a CI job's VM

GET`/ci/jobs/{id}/vm`

Scope: `ci:read`.

- `id` string required path

Answers: `200` CiJobVm, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getCiJobVm)

### Open a terminal on a CI job

GET`/ci/jobs/{id}/terminal`

A WebSocket. `groundbox ci ssh` uses it.

Scope: `ci:write`.

- `id` string required path

Answers: `101`, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#ciTerminal)

### Get CI insights

GET`/ci/insights`

Time, failures, cost, CPU and memory per job.

Scope: `ci:read`.

- `repo` string optional query
- `days` integer optional query

Answers: `200` CiInsights, `400`, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getCiInsights)

### List auto-size jobs

GET`/ci/auto`

Each job on the auto size: its pick, why, and what its runs used.

Scope: `ci:read`.

- `repo` string optional query

Answers: `200` CiAutoJobs, `400`, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listCiAuto)

### Get auto-size settings

GET`/ci/auto/settings`

Scope: `ci:read`.

Answers: `200` CiAutoSettings, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getCiAutoSettings)

### Set the largest auto size

PUT`/ci/auto/settings`

A higher cap lets jobs cost more a minute.

Scope: `ci:write`.

Body: `UpdateCiAutoSettingsRequest` (`max_vcpus` required).

Answers: `200` CiAutoSettings, `400`, `401`, `403`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#updateCiAutoSettings)

### List tests

GET`/ci/tests`

Test results from JUnit reports, with flaky tests.

Scope: `ci:read`.

- `repo` string optional query
- `days` integer optional query

Answers: `200` CiTestsResponse, `400`, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getCiTests)

### Get a test's history

GET`/ci/tests/{id}`

Scope: `ci:read`.

- `id` string required path

Answers: `200` CiTestDetail, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getCiTest)

### Get a CI job's test results

GET`/ci/jobs/{id}/tests`

Scope: `ci:read`.

- `id` string required path

Answers: `200` CiJobTests, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getCiJobTests)

### Upload test results

POST`/ci/tests/upload`

Scope: `ci:write`.

Body: `UploadCiTestsRequest` (`repo` required, `runner_name`, `run_id`, `run_attempt`, `job`, `files` required).

Answers: `200` UploadCiTestsResponse, `400`, `401`, `403`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#uploadCiTests)

### Get test timings

GET`/ci/test-timings`

Recorded time per test file of one job, for `groundbox tests split`.

Scope: `ci:read`.

- `repo` string required query
- `job` string optional query
- `runner` string optional query
- `days` integer optional query

Answers: `200` CiTestTimingsResponse, `400`, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getCiTestTimings)

### Search CI logs

GET`/ci/logs/search`

Scope: `ci:read`.

- `q` string required query
- `repo` string optional query
- `branch` string optional query
- `days` integer optional query
- `limit` integer optional query

Answers: `200` CiLogSearchResponse, `400`, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#searchCiLogs)

### Get a CI job

GET`/ci/jobs/{id}`

Scope: `ci:read`.

- `id` string required path

Answers: `200` CiJob, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getCiJob)

### Compare a CI job with GitHub-hosted runners

GET`/ci/jobs/{id}/comparison`

Scope: `ci:read`.

- `id` string required path

Answers: `200` JobComparison, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getCiJobComparison)

## Tune-ups

An agent proposes one pull request that makes a repository's CI faster.

### List tune-ups

GET`/tuneups`

Scope: `ci:read`.

- `limit` integer optional query
- `cursor` string optional query
- `repo` string optional query

Answers: `200` ListTuneupsResponse, `400`, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listTuneups)

### Start a tune-up

POST`/tuneups`

Free on every plan. 503 `not_available` until it is switched on.

Scope: `ci:write`.

Body: `CreateTuneupRequest` (`repo` required, `switch_runners`).

Answers: `201` Tuneup, `400`, `401`, `403`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#createTuneup)

### Get a tune-up

GET`/tuneups/{id}`

Scope: `ci:read`.

- `id` string required path

Answers: `200` Tuneup, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getTuneup)

### Open a tune-up's pull request

POST`/tuneups/{id}/pr`

Dashboard sessions only: the pull request is opened as the signed-in person. An API key is refused (403).

Scope: `ci:write`.

- `id` string required path

Body: `OpenTuneupPrRequest` (`return_url`).

Answers: `201` OpenTuneupPrResponse, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#openTuneupPr)

## Builds

Remote Docker builders, builds and the build cache.

### Get build cache stats

GET`/cache/stats`

What the team's remote build cache holds, and hits, misses and bytes per tool.

Scope: `cache:read`.

- `days` integer optional query

Answers: `200` BuildCacheStats, `400`, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getCacheStats)

### List builders

GET`/builders`

Scope: `builds:read`.

Answers: `200` ListBuildersResponse, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listBuilders)

### Start a builder

POST`/builders`

Starts the project's BuildKit builder if it is not up and waits until it answers. Paid plan.

Scope: `builds:write`.

Body: `EnsureBuilderRequest` (`project` required).

Answers: `200` Builder, `400`, `401`, `402`, `403`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#ensureBuilder)

### Clear a builder's cache

POST`/builders/clear-cache`

Scope: `builds:write`.

Body: `ClearBuildCacheRequest` (`project` required).

Answers: `200` Builder, `400`, `401`, `403`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#clearBuildCache)

### Connect to a builder

GET`/builders/connect`

A WebSocket: one BuildKit connection, as binary messages. The project goes in the `x-groundbox-build-project` header.

Scope: `builds:write`.

Answers: `101`, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#connectBuilder)

### List builds

GET`/builds`

Scope: `builds:read`.

- `project` string optional query
- `limit` integer optional query

Answers: `200` ListBuildsResponse, `400`, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listBuilds)

### Record a build

POST`/builds`

Scope: `builds:write`.

Body: `CreateBuildRequest` (`project` required, `tags`).

Answers: `200` Build, `400`, `401`, `403`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#createBuild)

### Finish a build

PATCH`/builds/{id}`

Scope: `builds:write`.

- `id` string required path

Body: `FinishBuildRequest` (`status` required, `steps`, `cached_steps`).

Answers: `200` Build, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#finishBuild)

## Registry

The team's private container image registry.

### Get the registry

GET`/registry`

Scope: `registry:pull`.

Answers: `200` RegistryOverview, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getRegistry)

### Claim the namespace

PUT`/registry/namespace`

Once per team. It cannot be changed after the first push.

Scope: `registry:push`.

Body: `ClaimRegistryNamespaceRequest` (`namespace` required).

Answers: `200` RegistryOverview, `400`, `401`, `403`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#claimRegistryNamespace)

### List repositories

GET`/registry/repositories`

Scope: `registry:pull`.

Answers: `200` ListRegistryRepositoriesResponse, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listRegistryRepositories)

### List a repository's tags

GET`/registry/repositories/{name}/tags`

`{name}` is the repository name with its slashes percent-encoded: `acme%2Fapp`.

Scope: `registry:pull`.

- `name` string required path

Answers: `200` ListRegistryTagsResponse, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listRegistryTags)

### Update a repository

PATCH`/registry/repositories/{name}`

Scope: `registry:push`.

- `name` string required path

Body: `UpdateRegistryRepositoryRequest` (`visibility`, `retention`).

Answers: `200` RegistryRepository, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#updateRegistryRepository)

### Delete a repository

DELETE`/registry/repositories/{name}`

Every manifest and tag in it. The blobs go at the next garbage collection.

Scope: `registry:push`.

- `name` string required path

Answers: `200` OkResponse, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#deleteRegistryRepository)

### Delete a tag

DELETE`/registry/repositories/{name}/tags/{tag}`

The tag only; the manifest stays.

Scope: `registry:push`.

- `name` string required path
- `tag` string required path

Answers: `200` OkResponse, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#deleteRegistryTag)

### Delete a manifest

DELETE`/registry/repositories/{name}/manifests/{digest}`

The manifest and every tag pointing at it.

Scope: `registry:push`.

- `name` string required path
- `digest` string required path

Answers: `200` OkResponse, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#deleteRegistryManifest)

### Get a registry token

GET`/registry/token`

Docker's token endpoint. Basic auth with the key as the password; no credentials gets a token for pulls of public repositories only.

The key as a Basic auth password, or nothing.

Answers: `200` RegistryTokenResponse, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#registryToken)

## Storage

S3-compatible buckets, objects and access keys.

### List buckets

GET`/storage/buckets`

Scope: `storage:read`.

Answers: `200` ListBucketsResponse, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listBuckets)

### Create a bucket

POST`/storage/buckets`

Scope: `storage:write`.

Body: `CreateBucketRequest` (`name` required).

Answers: `201` StorageBucket, `400`, `401`, `403`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#createBucket)

### Delete a bucket

DELETE`/storage/buckets/{name}`

Scope: `storage:write`.

- `name` string required path
- `force` "true" | "false" optional query

Answers: `200` OkResponse, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#deleteBucket)

### List objects

GET`/storage/buckets/{name}/objects`

Scope: `storage:read`.

- `name` string required path
- `prefix` string optional query
- `delimiter` string optional query
- `limit` integer optional query
- `cursor` string optional query

Answers: `200` ListObjectsResponse, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listObjects)

### Download an object

GET`/storage/buckets/{name}/object`

Scope: `storage:read`.

- `name` string required path
- `key` string required query

Answers: `200`, `400`, `401`, `403`, `404`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getObject)

### Upload an object

PUT`/storage/buckets/{name}/object`

The body is the object's bytes.

Scope: `storage:write`.

- `name` string required path
- `key` string required query

Body: `application/octet-stream`.

Answers: `200` PutObjectResponse, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#putObject)

### Delete an object

DELETE`/storage/buckets/{name}/object`

Scope: `storage:write`.

- `name` string required path
- `key` string required query

Answers: `200` OkResponse, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#deleteObject)

### Make a presigned URL

POST`/storage/presign`

Scope: `storage:read`.

Body: `PresignRequest` (`bucket` required, `key` required, `method`, `expires_s`).

Answers: `200` PresignResponse, `400`, `401`, `403`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#presign)

### List S3 access keys

GET`/storage/access-keys`

Scope: `storage:read`.

Answers: `200` ListAccessKeysResponse, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listAccessKeys)

### Create an S3 access key

POST`/storage/access-keys`

The secret is shown once.

Scope: `storage:read`.

Body: `CreateAccessKeyRequest` (`name`, `permission`, `buckets`).

Answers: `201` CreateAccessKeyResponse, `400`, `401`, `403`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#createAccessKey)

### Revoke an S3 access key

DELETE`/storage/access-keys/{id}`

Scope: `storage:write`.

- `id` string required path

Answers: `200` OkResponse, `400`, `401`, `403`, `404`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#revokeAccessKey)

## Account

The team's account, balance, ledger and feedback.

### Get the account

GET`/account`

The team, its plan, balance and spend cap.

Scope: `account:read`.

Answers: `200` Account, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#getAccount)

### Send feedback

POST`/feedback`

Any valid key.

Any valid key.

Body: `FeedbackRequest` (`message` required, `source`, `last_call`).

Answers: `201` FeedbackResponse, `400`, `401`, `403`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#sendFeedback)

### List ledger entries

GET`/billing/ledger`

Scope: `billing:read`.

- `limit` integer optional query
- `cursor` string optional query

Answers: `200` ListLedgerResponse, `400`, `401`, `403`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#listLedger)

## Sign-up

Keys for agents and devices. These take no key.

### Sign up an agent

POST`/signup`

A key for an agent, with free credit and no card. The answer has `api_key`, `claim_url` and `message_for_human`.

No key.

Body: `SignupRequest` (`agent_name`, `email`).

Answers: `201` SignupResponse, `400`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#signup)

### Start the device flow

POST`/auth/device/start`

What `groundbox login` calls first.

No key.

Body: `DeviceStartRequest` (`client`, `client_name`, `scopes`).

Answers: `201` DeviceStartResponse, `400`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#deviceStart)

### Poll the device flow

POST`/auth/device/token`

No key.

Body: `DeviceTokenRequest` (`device_code` required).

Answers: `200` DeviceTokenResponse, `400`, `409`, `429`. [Try it in the explorer](https://groundbox.dev/docs/api/explorer#deviceToken)
