API guide

Base URL: <DOCK_PUBLIC_URL>/v1 on your self-hosted control plane. The running API serves its contract at /openapi.json.

Envelopes

Every successful response is wrapped:

{ "ok": true, "data": { "...operation payload..." } }

Every failure uses the same shape with a stable machine-readable code:

{ "ok": false, "code": "dock_not_found", "message": "Dock not found" }

Codes are snake_case. Generic ones follow the HTTP status (validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, internal_error); operation-specific ones include dock_not_found, dock_name_taken (409), capacity_exhausted (503), no_host_capacity (503), image_unavailable (400, the host cannot serve the image), confirm_required, and idempotency_key_reused.

Authentication

Automation authenticates with an API key: Authorization: Bearer dock_.... Create and revoke keys in the dashboard under Developers > API keys, or with POST /v1/api-keys from a signed-in session. A key acts as the user who created it; the raw value is shown once and only its hash is stored. Some account and webhook-management actions need a signed-in browser session and refuse API keys with session_required.

The dashboard itself signs in through cookie sessions under /api/auth. Routes marked public (health, webhooks from GitHub) need no credentials.

Lifecycle calls

• POST /v1/docks and POST /v1/docks/:id/branch accept an idempotency-key header. A retry with the same key returns the original Dock instead of creating another; reusing a key for a different request fails with idempotency_key_reused.
• Create, stop, resume, and branch return when the host has finished the change, with the Dock's new state.
• DELETE /v1/docks/:id and DELETE /v1/snapshots/:id return an operation you can poll at GET /v1/operations/:id. Both require an x-confirm-delete header whose value is the id being deleted; without it they fail with confirm_required.

Creating a Dock

POST /v1/docks takes workspaceId and optionally name (unique per workspace), image (only ubuntu-24.04), cpus (1 to 64, default 2), memoryMiB (512 to 262144, default 4096), diskGiB (1 to 2048, default 20), ttlSeconds, environment, noEnv, env, from, and setupScript. Branch accepts the same size fields. A Dock object carries cpus, memoryMiB, diskGiB, image, runtime (microvm or gvisor, set by the host), and persistentPaths. See Runtimes and images.

The Dock object is an explicit allowlist: id, workspaceId, name, image, cpus, memoryMiB, diskGiB, runtime, persistentPaths, state, ttlSeconds, environment, fromTemplate, ip, hostId, billingPausedAt, setupStatus, setupError, lastSnapshotAt, stateChangedAt, createdAt, and updatedAt. Environment variable values and credential hashes are never returned.

Runs

GET /v1/github/runs, GET /v1/github/runs/:id and POST /v1/github/runs/:id/promote return an explicit allowlist: id, installationId, workspaceId, organizationId, repo, issueNumber, dockId, executionTarget, state, prNumber, prUrl, failureReason, agent, branch, baseBranch, promptVersion, testCommand, completionStatus, events, createdAt, and updatedAt. Tokens, token hashes, and the run envelope are never returned.