REST API

Every endpoint, relative to https://api.groundbox.dev/v1. Bodies are JSON with snake_case fields. Money is an integer count of micro-dollars in fields ending _micros.

API endpoints
MethodPathScope
POST/sandboxessandboxes:write
GET/sandboxessandboxes:read
GET/sandboxes/{id}sandboxes:read
PATCH/sandboxes/{id}sandboxes:write
DELETE/sandboxes/{id}sandboxes:write
POST/sandboxes/{id}/execsandboxes:write
GET/sandboxes/{id}/exec/streamsandboxes:write
PUT/sandboxes/{id}/filessandboxes:write
GET/sandboxes/{id}/filessandboxes:read
GET/sandboxes/{id}/filessandboxes:read
POST/sandboxes/{id}/pausesandboxes:write
POST/sandboxes/{id}/resumesandboxes:write
POST/sandboxes/{id}/forksandboxes:write
GET/sandboxes/{id}/usagesandboxes:read
POST/schedulesschedules:write
GET/schedulesschedules:read
DELETE/schedules/{id}schedules:write
GET/accountaccount:read
POST/signupnone
GET/ci/runsci:read
GET/ci/jobs/{id}/logsci:read
POST/ci/waitci:read
POST/auth/device/startnone
POST/auth/device/tokennone
POST/feedbacknone

Errors come back as {"error": {"code": "...", "message": "..."}} with a matching HTTP status.

Keys and caps

Create a key under API keys in the dashboard. Keys start with gbx_; keys that start with gbx_test_ are test keys. One key works for CI and for sandboxes.

  • Scopes. A key does only what its scopes allow: sandboxes:read, sandboxes:write, schedules:read, schedules:write, ci:read, ci:write, billing:read, account:read.
  • Spend cap. A key can have a monthly cap in dollars. The key cannot raise its own cap; the account owner can.
  • Agent sign-up. An agent can call POST /signup with no key. It gets a key and a claim link; the key works once a person opens the link and approves it.

Questions: contact@groundbox.dev. Prices are on the pricing page.

Create an account and get an API key.