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 specYAMLAPI explorerREST API guide
Sandboxes
Start, list, change, pause, stop and delete sandboxes.
List sandboxes
GET/sandboxes
Scope: sandboxes:read.
limitinteger optional querycursorstring optional querystatusstring | array of string optional queryliveboolean | "true" | "false" optional querymetadataobject optional query
Answers: 200 ListSandboxesResponse, 400, 401, 403, 429. Try it in the explorer
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-Keystring 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
Get a sandbox
GET/sandboxes/{id}
Scope: sandboxes:read.
idstring required path
Answers: 200 Sandbox, 400, 401, 403, 404, 429. Try it in the explorer
Update a sandbox
PATCH/sandboxes/{id}
Change its timeout, metadata or egress allowlist.
Scope: sandboxes:write.
idstring 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
Delete a sandbox
DELETE/sandboxes/{id}
Stops it and deletes its disk. Cannot be undone.
Scope: sandboxes:write.
idstring required path
Answers: 200 Sandbox, 400, 401, 403, 404, 409, 429. Try it in the explorer
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.
idstring required path
Answers: 200 Sandbox, 400, 401, 403, 404, 409, 429. Try it in the explorer
Resume a paused sandbox
POST/sandboxes/{id}/resume
Scope: sandboxes:write.
idstring required path
Answers: 200 Sandbox, 400, 401, 402, 403, 404, 409, 429. Try it in the explorer
Stop a sandbox
POST/sandboxes/{id}/stop
Shuts it down and keeps its disk: status shut_down, storage only.
Scope: sandboxes:write.
idstring required path
Answers: 200 Sandbox, 400, 401, 403, 404, 409, 429. Try it in the explorer
Start a stopped sandbox
POST/sandboxes/{id}/start
Boots it again from its kept disk: same id, a fresh VM.
Scope: sandboxes:write.
idstring required path
Answers: 200 Sandbox, 400, 401, 402, 403, 404, 409, 429. Try it in the explorer
Get a sandbox's usage and cost
GET/sandboxes/{id}/usage
Scope: sandboxes:read.
idstring required path
Answers: 200 SandboxUsage, 400, 401, 403, 404, 429. Try it in the explorer
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.
idstring required pathportinteger required path
Answers: 101, 400, 401, 403, 404, 429. Try it in the explorer
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.
idstring 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
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.
idstring required path
Answers: 101, 400, 401, 403, 404, 429. Try it in the explorer
List commands
GET/sandboxes/{id}/commands
Scope: sandboxes:read.
idstring required pathstate"running" | "exited" | "lost" optional querylimitinteger optional query
Answers: 200 ListCommandsResponse, 400, 401, 403, 404, 429. Try it in the explorer
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.
idstring 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
Get a command
GET/sandboxes/{id}/commands/{exec_id}
Scope: sandboxes:read.
idstring required pathexec_idstring required path
Answers: 200 SandboxCommand, 400, 401, 403, 404, 429. Try it in the explorer
Read a command's output
GET/sandboxes/{id}/commands/{exec_id}/output
Scope: sandboxes:read.
idstring required pathexec_idstring required pathseqinteger optional queryencoding"utf8" | "base64" optional query
Answers: 200 CommandOutputResponse, 400, 401, 403, 404, 429. Try it in the explorer
Kill a command
POST/sandboxes/{id}/commands/{exec_id}/kill
Scope: sandboxes:write.
idstring required pathexec_idstring required path
Body: KillCommandRequest (signal).
Answers: 200 SandboxCommand, 400, 401, 403, 404, 409, 429. Try it in the explorer
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.
idstring required pathpathstring optional querydirstring optional query
Answers: 200 ListFilesResponse, 400, 401, 403, 404, 429. Try it in the explorer
Write a file
PUT/sandboxes/{id}/files
The body is the file's bytes.
Scope: sandboxes:write.
idstring required pathpathstring required query
Body: application/octet-stream.
Answers: 200 WriteFileResponse, 400, 401, 403, 404, 409, 429. Try it in the explorer
Delete a file or folder
DELETE/sandboxes/{id}/files
Scope: sandboxes:write.
idstring required pathpathstring required queryrecursiveboolean | "true" | "false" optional query
Answers: 200 DeleteFileResponse, 400, 401, 403, 404, 409, 429. Try it in the explorer
Make a folder
POST/sandboxes/{id}/files/mkdir
Makes the parents it needs. A folder already there is fine (created: false).
Scope: sandboxes:write.
idstring required pathpathstring required query
Answers: 200 MakeDirResponse, 400, 401, 403, 404, 409, 429. Try it in the explorer
Get a file's details
GET/sandboxes/{id}/files/stat
Scope: sandboxes:read.
idstring required pathpathstring required query
Answers: 200 FileEntry, 400, 401, 403, 404, 429. Try it in the explorer
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.
idstring required pathIdempotency-Keystring 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
Get a sandbox's timeline
GET/sandboxes/{id}/timeline
Scope: sandboxes:read.
idstring required path
Answers: 200 SandboxTimeline, 400, 401, 403, 404, 429. Try it in the explorer
Set automatic save points
POST/sandboxes/{id}/timeline
Scope: sandboxes:write.
idstring required path
Body: SetTimelineRequest (interval_s required, keep).
Answers: 200 SandboxTimeline, 400, 401, 403, 404, 409, 429. Try it in the explorer
Make a save point now
POST/sandboxes/{id}/snapshots
Scope: sandboxes:write.
idstring required path
Body: CreateSnapshotRequest (label).
Answers: 200 TimelinePoint, 400, 401, 403, 404, 409, 429. Try it in the explorer
Delete a save point
DELETE/sandboxes/{id}/snapshots/{snapshot_id}
409 while a fork group is being restored from it.
Scope: sandboxes:write.
idstring required pathsnapshot_idstring required path
Answers: 200 SandboxTimeline, 400, 401, 403, 404, 409, 429. Try it in the explorer
Rewind to a save point
POST/sandboxes/{id}/restore
Scope: sandboxes:write.
idstring required path
Body: RestoreSandboxRequest (snapshot_id required).
Answers: 200 RestoreSandboxResponse, 400, 401, 403, 404, 409, 429. Try it in the explorer
List snapshots
GET/snapshots
Scope: sandboxes:read.
limitinteger optional querycursorstring optional querysandbox_idstring optional query
Answers: 200 ListSnapshotsResponse, 400, 401, 403, 429. Try it in the explorer
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-Keystring optional header
Body: KeepSnapshotRequest (sandbox_id required, snapshot_id, label).
Answers: 200 Snapshot, 400, 401, 402, 403, 409, 429. Try it in the explorer
Get a snapshot
GET/snapshots/{id}
Scope: sandboxes:read.
idstring required path
Answers: 200 Snapshot, 400, 401, 403, 404, 429. Try it in the explorer
Delete a snapshot
DELETE/snapshots/{id}
Sandboxes already started from it go on. 409 while one is still starting from it.
Scope: sandboxes:write.
idstring required path
Answers: 200 Snapshot, 400, 401, 403, 404, 409, 429. Try it in the explorer
Get a fork group
GET/fork-groups/{id}
Scope: sandboxes:read.
idstring required path
Answers: 200 ForkGroup, 400, 401, 403, 404, 429. Try it in the explorer
Delete a fork group
DELETE/fork-groups/{id}
Scope: sandboxes:write.
idstring required path
Answers: 200 ForkGroup, 400, 401, 403, 404, 409, 429. Try it in the explorer
Templates
Build a sandbox's disk once and start sandboxes from it.
List templates
GET/templates
Scope: sandboxes:read.
limitinteger optional querycursorstring optional queryinclude_hidden"true" | "false" optional query
Answers: 200 ListTemplatesResponse, 400, 401, 403, 429. Try it in the explorer
Create a template
POST/templates
Scope: sandboxes:write.
Idempotency-Keystring 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
Get a template
GET/templates/{id}
{id} is the id or the name.
Scope: sandboxes:read.
idstring required path
Answers: 200 Template, 400, 401, 403, 404, 429. Try it in the explorer
Delete a template
DELETE/templates/{id}
Its versions stop at once; sandboxes running from it go on.
Scope: sandboxes:write.
idstring required path
Answers: 200 OkResponse, 400, 401, 403, 404, 409, 429. Try it in the explorer
List a template's versions
GET/templates/{id}/builds
Scope: sandboxes:read.
idstring required path
Answers: 200 ListTemplateBuildsResponse, 400, 401, 403, 404, 429. Try it in the explorer
Build a new version
POST/templates/{id}/builds
An empty body builds the newest version's spec again, with fresh packages.
Scope: sandboxes:write.
idstring required pathIdempotency-Keystring 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
Read a version's build log
GET/templates/{id}/builds/{version}/logs
Scope: sandboxes:read.
idstring required pathversioninteger required pathafterinteger optional querywait_sinteger optional query
Answers: 200 TemplateLogsResponse, 400, 401, 403, 404, 429. Try it in the explorer
Get the default template
GET/templates/default
Scope: sandboxes:read.
Answers: 200 DefaultTemplateResponse, 401, 403, 429. Try it in the explorer
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
Volumes
Disks that outlive sandboxes.
List volumes
GET/volumes
Scope: sandboxes:read.
limitinteger optional querycursorstring optional query
Answers: 200 ListVolumesResponse, 400, 401, 403, 429. Try it in the explorer
Create a volume
POST/volumes
Billed per GB-month for its whole size until it is deleted.
Scope: sandboxes:write.
Idempotency-Keystring optional header
Body: CreateVolumeRequest (name, size_gb required).
Answers: 200 Volume, 400, 401, 402, 403, 409, 429. Try it in the explorer
Get a volume
GET/volumes/{id}
{id} is the id or the name.
Scope: sandboxes:read.
idstring required path
Answers: 200 Volume, 400, 401, 403, 404, 429. Try it in the explorer
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.
idstring required path
Answers: 200 Volume, 400, 401, 403, 404, 409, 429. Try it in the explorer
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.
namestring required path
Body: SetSecretRequest (value required).
Answers: 200 Secret, 400, 401, 403, 404, 409, 429. Try it in the explorer
Delete a secret
DELETE/secrets/{name}
Sandboxes that use it fail their next command with 409 until it is set again.
Scope: secrets:write.
namestring required path
Answers: 200 OkResponse, 400, 401, 403, 404, 409, 429. Try it in the explorer
List secrets
GET/secrets
Names and dates. Never values.
Scope: secrets:read.
Answers: 200 ListSecretsResponse, 401, 403, 429. Try it in the explorer
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.
idstring 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
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.
idstring required pathafterinteger optional querywait_sinteger optional query
Answers: 200 HandoffState, 400, 401, 403, 404, 429. Try it in the explorer
Ask a person to take control
POST/sandboxes/{id}/handoff
Scope: sandboxes:write.
idstring required path
Body: RequestHandoffRequest (reason required).
Answers: 200 HandoffState, 400, 401, 403, 404, 409, 429. Try it in the explorer
Withdraw a handoff request
POST/sandboxes/{id}/handoff/cancel
Scope: sandboxes:write.
idstring required path
Answers: 200 HandoffState, 400, 401, 403, 404, 409, 429. Try it in the explorer
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.
idstring required path
Body: TakeControlRequest (by).
Answers: 200 HandoffState, 400, 401, 403, 404, 409, 429. Try it in the explorer
Give control back
POST/sandboxes/{id}/handoff/return
The person is done: the agent resumes. The body may be left out.
Scope: sandboxes:write.
idstring required path
Body: ReturnControlRequest (note).
Answers: 200 HandoffState, 400, 401, 403, 404, 409, 429. Try it in the explorer
List live view links
GET/sandboxes/{id}/desktop/links
Scope: sandboxes:read.
idstring required path
Answers: 200 ListDesktopLinksResponse, 400, 401, 403, 404, 429. Try it in the explorer
Create a live view link
POST/sandboxes/{id}/desktop/links
Scope: sandboxes:write.
idstring 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
Revoke a live view link
DELETE/sandboxes/{id}/desktop/links/{link_id}
Open viewers are cut off at once.
Scope: sandboxes:write.
idstring required pathlink_idstring required path
Answers: 200 DesktopLink, 400, 401, 403, 404, 409, 429. Try it in the explorer
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
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
Get a custom domain
GET/domains/{domain}
Scope: sandboxes:read.
domainstring required path
Answers: 200 CustomDomain, 400, 401, 403, 404, 429. Try it in the explorer
Attach a domain to a preview
PATCH/domains/{domain}
Scope: sandboxes:write.
domainstring required path
Body: UpdateCustomDomainRequest (sandbox_id, port).
Answers: 200 CustomDomain, 400, 401, 403, 404, 409, 429. Try it in the explorer
Remove a custom domain
DELETE/domains/{domain}
Scope: sandboxes:write.
domainstring required path
Answers: 200 OkResponse, 400, 401, 403, 404, 409, 429. Try it in the explorer
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.
domainstring required path
Answers: 200 CustomDomain, 400, 401, 403, 404, 409, 429. Try it in the explorer
List a sandbox's previews
GET/sandboxes/{id}/previews
Scope: sandboxes:read.
idstring required path
Answers: 200 ListPreviewsResponse, 400, 401, 403, 404, 429. Try it in the explorer
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.
idstring required path
Body: CreatePreviewRequest (port required, public).
Answers: 201 SandboxPreview, 400, 401, 403, 404, 409, 429. Try it in the explorer
Update a preview
PATCH/sandboxes/{id}/previews/{port}
Scope: sandboxes:write.
idstring required pathportinteger required path
Body: UpdatePreviewRequest (public required).
Answers: 200 SandboxPreview, 400, 401, 403, 404, 409, 429. Try it in the explorer
Remove a preview
DELETE/sandboxes/{id}/previews/{port}
Its URL stops working.
Scope: sandboxes:write.
idstring required pathportinteger required path
Answers: 200 OkResponse, 400, 401, 403, 404, 409, 429. Try it in the explorer
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
Schedules
Run a command in a fresh sandbox on a cron schedule.
List schedules
GET/schedules
Scope: schedules:read.
limitinteger optional querycursorstring optional query
Answers: 200 ListSchedulesResponse, 400, 401, 403, 429. Try it in the explorer
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
Delete a schedule
DELETE/schedules/{id}
Scope: schedules:write.
idstring required path
Answers: 200 OkResponse, 400, 401, 403, 404, 409, 429. Try it in the explorer
CI
Runs, jobs, logs, insights, auto size and test results for GitHub Actions on Groundbox.
List CI runs
GET/ci/runs
Scope: ci:read.
limitinteger optional querycursorstring optional queryrepostring optional querybranchstring optional queryshastring optional querystatusenum optional query
Answers: 200 ListCiRunsResponse, 400, 401, 403, 429. Try it in the explorer
Read a CI job's logs
GET/ci/jobs/{id}/logs
Scope: ci:read.
idstring required path
Answers: 200 CiLogsResponse, 400, 401, 403, 404, 429. Try it in the explorer
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
Get a CI job's VM
GET/ci/jobs/{id}/vm
Scope: ci:read.
idstring required path
Answers: 200 CiJobVm, 400, 401, 403, 404, 429. Try it in the explorer
Open a terminal on a CI job
GET/ci/jobs/{id}/terminal
A WebSocket. groundbox ci ssh uses it.
Scope: ci:write.
idstring required path
Answers: 101, 400, 401, 403, 404, 429. Try it in the explorer
Get CI insights
GET/ci/insights
Time, failures, cost, CPU and memory per job.
Scope: ci:read.
repostring optional querydaysinteger optional query
Answers: 200 CiInsights, 400, 401, 403, 429. Try it in the explorer
List auto-size jobs
GET/ci/auto
Each job on the auto size: its pick, why, and what its runs used.
Scope: ci:read.
repostring optional query
Answers: 200 CiAutoJobs, 400, 401, 403, 429. Try it in the explorer
Get auto-size settings
GET/ci/auto/settings
Scope: ci:read.
Answers: 200 CiAutoSettings, 401, 403, 429. Try it in the explorer
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
List tests
GET/ci/tests
Test results from JUnit reports, with flaky tests.
Scope: ci:read.
repostring optional querydaysinteger optional query
Answers: 200 CiTestsResponse, 400, 401, 403, 429. Try it in the explorer
Get a test's history
GET/ci/tests/{id}
Scope: ci:read.
idstring required path
Answers: 200 CiTestDetail, 400, 401, 403, 404, 429. Try it in the explorer
Get a CI job's test results
GET/ci/jobs/{id}/tests
Scope: ci:read.
idstring required path
Answers: 200 CiJobTests, 400, 401, 403, 404, 429. Try it in the explorer
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
Get test timings
GET/ci/test-timings
Recorded time per test file of one job, for groundbox tests split.
Scope: ci:read.
repostring required queryjobstring optional queryrunnerstring optional querydaysinteger optional query
Answers: 200 CiTestTimingsResponse, 400, 401, 403, 429. Try it in the explorer
Search CI logs
GET/ci/logs/search
Scope: ci:read.
qstring required queryrepostring optional querybranchstring optional querydaysinteger optional querylimitinteger optional query
Answers: 200 CiLogSearchResponse, 400, 401, 403, 429. Try it in the explorer
Get a CI job
GET/ci/jobs/{id}
Scope: ci:read.
idstring required path
Answers: 200 CiJob, 400, 401, 403, 404, 429. Try it in the explorer
Compare a CI job with GitHub-hosted runners
GET/ci/jobs/{id}/comparison
Scope: ci:read.
idstring required path
Answers: 200 JobComparison, 400, 401, 403, 404, 429. Try it in the explorer
Tune-ups
An agent proposes one pull request that makes a repository's CI faster.
List tune-ups
GET/tuneups
Scope: ci:read.
limitinteger optional querycursorstring optional queryrepostring optional query
Answers: 200 ListTuneupsResponse, 400, 401, 403, 429. Try it in the explorer
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
Get a tune-up
GET/tuneups/{id}
Scope: ci:read.
idstring required path
Answers: 200 Tuneup, 400, 401, 403, 404, 429. Try it in the explorer
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.
idstring required path
Body: OpenTuneupPrRequest (return_url).
Answers: 201 OpenTuneupPrResponse, 400, 401, 403, 404, 409, 429. Try it in the explorer
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.
daysinteger optional query
Answers: 200 BuildCacheStats, 400, 401, 403, 429. Try it in the explorer
List builders
GET/builders
Scope: builds:read.
Answers: 200 ListBuildersResponse, 401, 403, 429. Try it in the explorer
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
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
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
List builds
GET/builds
Scope: builds:read.
projectstring optional querylimitinteger optional query
Answers: 200 ListBuildsResponse, 400, 401, 403, 429. Try it in the explorer
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
Finish a build
PATCH/builds/{id}
Scope: builds:write.
idstring required path
Body: FinishBuildRequest (status required, steps, cached_steps).
Answers: 200 Build, 400, 401, 403, 404, 409, 429. Try it in the explorer
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
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
List repositories
GET/registry/repositories
Scope: registry:pull.
Answers: 200 ListRegistryRepositoriesResponse, 401, 403, 429. Try it in the explorer
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.
namestring required path
Answers: 200 ListRegistryTagsResponse, 400, 401, 403, 404, 429. Try it in the explorer
Update a repository
PATCH/registry/repositories/{name}
Scope: registry:push.
namestring required path
Body: UpdateRegistryRepositoryRequest (visibility, retention).
Answers: 200 RegistryRepository, 400, 401, 403, 404, 409, 429. Try it in the explorer
Delete a repository
DELETE/registry/repositories/{name}
Every manifest and tag in it. The blobs go at the next garbage collection.
Scope: registry:push.
namestring required path
Answers: 200 OkResponse, 400, 401, 403, 404, 409, 429. Try it in the explorer
Delete a tag
DELETE/registry/repositories/{name}/tags/{tag}
The tag only; the manifest stays.
Scope: registry:push.
namestring required pathtagstring required path
Answers: 200 OkResponse, 400, 401, 403, 404, 409, 429. Try it in the explorer
Delete a manifest
DELETE/registry/repositories/{name}/manifests/{digest}
The manifest and every tag pointing at it.
Scope: registry:push.
namestring required pathdigeststring required path
Answers: 200 OkResponse, 400, 401, 403, 404, 409, 429. Try it in the explorer
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
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
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
Delete a bucket
DELETE/storage/buckets/{name}
Scope: storage:write.
namestring required pathforce"true" | "false" optional query
Answers: 200 OkResponse, 400, 401, 403, 404, 409, 429. Try it in the explorer
List objects
GET/storage/buckets/{name}/objects
Scope: storage:read.
namestring required pathprefixstring optional querydelimiterstring optional querylimitinteger optional querycursorstring optional query
Answers: 200 ListObjectsResponse, 400, 401, 403, 404, 429. Try it in the explorer
Download an object
GET/storage/buckets/{name}/object
Scope: storage:read.
namestring required pathkeystring required query
Answers: 200, 400, 401, 403, 404, 429. Try it in the explorer
Upload an object
PUT/storage/buckets/{name}/object
The body is the object's bytes.
Scope: storage:write.
namestring required pathkeystring required query
Body: application/octet-stream.
Answers: 200 PutObjectResponse, 400, 401, 403, 404, 409, 429. Try it in the explorer
Delete an object
DELETE/storage/buckets/{name}/object
Scope: storage:write.
namestring required pathkeystring required query
Answers: 200 OkResponse, 400, 401, 403, 404, 409, 429. Try it in the explorer
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
List S3 access keys
GET/storage/access-keys
Scope: storage:read.
Answers: 200 ListAccessKeysResponse, 401, 403, 429. Try it in the explorer
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
Revoke an S3 access key
DELETE/storage/access-keys/{id}
Scope: storage:write.
idstring required path
Answers: 200 OkResponse, 400, 401, 403, 404, 409, 429. Try it in the explorer
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
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
List ledger entries
GET/billing/ledger
Scope: billing:read.
limitinteger optional querycursorstring optional query
Answers: 200 ListLedgerResponse, 400, 401, 403, 429. Try it in the explorer
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
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
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