Sandbox quickstart

Sandbox API access is available to every Sparkles user. Open the API access page while signed in to create a key for your active WorkOS organization, and include the sandboxes scope. Store the key in a server-side environment variable:

export SPARKLES_API_KEY='spk_test_…'

1. Create a sandbox

Use an idempotency key so a network retry cannot create a second sandbox:

curl https://sparkles.dev/api/public/v1/sandboxes \
  --request POST \
  --header "Authorization: Bearer $SPARKLES_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: onboarding-example-1" \
  --data '{
    "repos": [{ "fullName": "acme/widgets" }],
    "prompt": "Find and fix the failing unit test, then summarize the change.",
    "title": "Fix the failing test"
  }'

The response is queued immediately. Save its id, which is also the public sandbox identifier:

{
	"id": "c_…",
	"object": "sandbox",
	"status": "queued"
}

2. Stream the lifecycle

The stream covers boot, agent output, approvals, tools, and completion in one connection. Use a fetch-based SSE client because browser EventSource cannot set the authorization header.

curl -N https://sparkles.dev/api/public/v1/sandboxes/c_…/events/stream \
  --header "Authorization: Bearer $SPARKLES_API_KEY" \
  --header "Accept: text/event-stream"

Durable events include an SSE id. Reconnect with Last-Event-ID, or pass the same value as ?since= when your HTTP client cannot set that header. Delivery is at least once, so apply events idempotently.

3. Send a follow-up

After the first turn settles, the same sandbox can accept another prompt. A stable promptId makes retries idempotent.

curl https://sparkles.dev/api/public/v1/sandboxes/c_…/messages \
  --request POST \
  --header "Authorization: Bearer $SPARKLES_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "prompt": "Now add a regression test for the fix.",
    "promptId": "regression-test-1"
  }'

4. Terminate the sandbox

Termination is idempotent:

curl https://sparkles.dev/api/public/v1/sandboxes/c_…/terminate \
  --request POST \
  --header "Authorization: Bearer $SPARKLES_API_KEY"

Get started

Sparkles CLI

Sandbox API

API reference

1. Create a sandbox

2. Stream the lifecycle

3. Send a follow-up

4. Terminate the sandbox

​1. Create a sandbox

​2. Stream the lifecycle

​3. Send a follow-up

​4. Terminate the sandbox

1. Create a sandbox

2. Stream the lifecycle

3. Send a follow-up

4. Terminate the sandbox