Skip to content
GroundboxDocs
API referenceStatusPricing
DashboardStart free
GroundboxGitHub Actions runners and Linux sandboxes for AI agents. One key, one bill.System status

Product

CI runnersSandboxesBuilds and cacheAgent computersPricing

Developers

DocsAPI referenceAPI explorerCLIMCP serverBenchmark

Compare

vs GitHub-hostedvs Blacksmithvs E2Bvs DaytonaAll comparisons

Company

Talk to usSupportcontact@groundbox.devGroundmail ↗
© 2026 Groundbox
TermsPrivacyllms.txt
OverviewCI in one lineFirst sandboxHand it to your agent
Sizes and labelsCachesBuild cachesMigrateci waitTerminal on a jobPublic repositoriesAuto sizeAuto size: own runnersFlexCI tune-upSplit tests by timeDocker buildsGitLab CI
Start, exec, filesFrom a Docker imageCommandsForkTime machineSnapshotsPause and resumeStop and startIdle pause and wakeScheduled runsPreviewsSecretsEgress allowlistFlex sandboxesTemplatesVolumes
Push and pullIn GitHub ActionsStorage and retention
Desktop and actionsLive view in your appHuman handoffSign in onceAgent loop example
BucketsAccess keysMount a bucket
Move from Runloop
Omnara
REST APIAPI explorerOpenAPI referenceCLIMCP serverSDKsKeys and capsLeave or delete a team
  1. Reference
  2. OpenAPI reference
Markdown
Open in
ClaudeChatGPT
On this page

    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 · YAML · API explorer · REST API guide

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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.

    • limit integer optional query
    • cursor string 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-Key string 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.

    • id string 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.

    • id string 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.

    • name string 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.

    • name string 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.

    • 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

    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

    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

    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

    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

    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

    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

    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

    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

    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.

    • domain string 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.

    • domain string 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.

    • domain string 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.

    • domain string 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.

    • id string 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.

    • id string 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.

    • 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

    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

    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.

    • limit integer optional query
    • cursor string 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.

    • id string 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.

    • 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

    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

    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.

    • id string 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.

    • id string 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.

    • repo string optional query
    • days integer 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.

    • repo string 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.

    • repo string optional query
    • days integer 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.

    • id string 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.

    • id string 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.

    • 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

    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

    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

    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

    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

    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.

    • id string 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.

    • id string 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.

    • days integer 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.

    • project string optional query
    • limit integer 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.

    • 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

    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.

    • name string 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.

    • name string 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.

    • name string 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.

    • name string required path
    • tag string 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.

    • name string required path
    • digest string 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.

    • name string required path
    • force "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.

    • 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

    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

    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

    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

    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.

    • id string 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.

    • limit integer optional query
    • cursor string 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

    ← PreviousAPI explorerNext →CLI
    System statusSupportPricingllms.txtgroundbox.dev