Required scopes per operation:
sessions:read- list, getsessions:write- createsessions:delete- destroy
All session endpoints honor
X-Organization-Id. Personal keys may omit the
header to operate on personal sessions; org keys must use the header that
matches the key’s organization.List Sessions
GET /api/sessions
Returns a paginated list of sessions visible to the caller. Personal keys see only organization_id = NULL sessions; org keys see sessions in the active organization. Pass team_mode=true with an org key to see sessions other org members have explicitly shared with the team (visibility = "team").
Query Parameters
When
true and an org context is set, return sessions other members shared
with the team. Your own private sessions appear under the default “you”
view, not here.Response
Create Session
POST /api/sessions
Provisions a new sandbox. The response returns immediately with state
creating; poll GET /api/sessions/{id} (or call POST /api/sessions/{id}/start)
until state = "running".
Background-agent sessions (e.g.
source = "api") require a stored Anthropic
API key. Configure one in the dashboard under
Settings → Integrations → Anthropic, or set it via
Provider Keys.
Without a stored key, this endpoint returns 400.Body Parameters
Project scaffold to use (
web-app, backend-service, static-site).
Optional - sessions can also start blank or attach to a GitHub repo.One of:
claude-code, codex, opencode, github-copilot,
cursor-cli, devin-cli, gemini-cli.autopilot (auto-approve actions) or interactive (allows the agent to
ask for confirmation).Up to 5 repos for multi-repo sessions. Takes precedence over
github_repo.
First entry is treated as the primary repo. Each entry mirrors the
github_repo schema.Free-form attribution string. Customers calling from automation typically use
api. Internal source values (used by Slack/Linear bots and the dashboard)
are not part of the public contract and must not be relied on.Lifecycle action after a prompt finishes:
pause, destroy, or
keep_alive. Defaults to keep_alive for interactive sessions.Hard maximum lifetime in minutes (1-1440). Sessions exceeding this are
destroyed regardless of activity. Recommended for unattended agent runs.
Response
Working directory inside the sandbox. Non-
/home/user values indicate an
org template with code already baked into the image.Get Session
GET /api/sessions/{session_id}
Returns the full session object. By default (refresh=true), the backend
reconciles the cached state with the actual sandbox before responding, which
catches sandboxes that were destroyed externally.
Path Parameters
Query Parameters
When
true, verify the sandbox exists in the provider before responding.
Pass false for snappier reads when staleness is acceptable.Response
Same shape as the items in List Sessions.Destroy Session
DELETE /api/sessions/{session_id}
Marks the session as destroying and returns immediately. The sandbox
teardown and any session-scoped key revocation finish in the background, so
the session may briefly remain visible in destroying state before flipping
to destroyed.
This action is permanent - destroyed sessions cannot be resumed. To
preserve filesystem and memory state, use Pause instead.