Skip to main content
A sandbox is an asynchronous coding-agent job owned by the API access grant that created it. Its public id starts with c_; internal session identifiers, agent URLs, preview ports, and credentials are never returned.

​
Access model

Sandbox requests require all of the following:
  • an active API access grant bound to a WorkOS organization;
  • an active key with the sandboxes scope;
  • a live organization membership for the grant’s WorkOS user; and
  • exact ownership by the same access grant for every read or command.
Looking up a sandbox from another grant returns 404, including when both grants belong to the same organization.

​
Lifecycle

The status field has seven values: Treat GET /api/public/v1/sandboxes/{id} as the source of truth. Streaming lifecycle frames and webhooks are notifications that tell you when to reconcile.

​
Create requests

Creation accepts repositories, an initial prompt, optional model and reasoning settings, a title, approval mode, and up to 16 string metadata entries. Request bodies are limited to 64 KiB. Sparkles selects the standard runtime, organization visibility, and the execution region server-side. Pass Idempotency-Key for safe retries. Reusing a key with the same normalized request returns the existing sandbox once its row exists; a retry that arrives earlier returns 409 idempotency_in_progress. Using the key with different details returns 409 idempotency_conflict. A failed creation releases its lease so the same request can be retried. Each access grant has a concurrent-sandbox limit. Creation and terminal-sandbox restart checks are serialized under the grant lock so concurrent requests cannot exceed the limit.

​
Read and list

List sandboxes with an optional status or repo filter. Pagination uses an opaque after cursor and a maximum page size of 100. The resource response deliberately whitelists public fields: status, repositories, selected model and runtime, current turn, usage rollup, metadata, error, timestamps, and links. Usage is eventually consistent while inference settlements are still in flight.

​
Commands

  • POST /messages queues a follow-up prompt. Supply promptId to deduplicate retries. A terminal job can restart, subject to the same concurrency cap.
  • POST /interrupt aborts the latest running agent session.
  • POST /approvals/{approvalId} resolves a pending tool approval with approve or deny.
  • POST /terminate idempotently shuts down the sandbox without purging its history.
Command responses are receipts. They acknowledge durable acceptance, not completion; observe the stream or resource state for the outcome.

​
Files and pull requests

The v1 file API is read-only. List a live sandbox’s file tree or load a bounded text document; file writes remain agent-driven. Pull-request creation uses Sparkles’ short-lived, repository-scoped GitHub App credentials and always creates or reuses a draft pull request. GET /files/download?path=… streams one working-tree file from a running sandbox as an attachment. Sparkles reads the bytes over the sandbox’s ACP agent connection, so downloads need a running sandbox with a live agent; files above 100 MiB, protected files such as .env, and .git contents are refused.