API documentation

Quick start

Open the Platform console to add prepaid credits and create an API token. Copy the token when it is shown: it cannot be viewed again. Set it in your shell, then list the supported models and their published prices.

export SANDPI_API_TOKEN="your-platform-token"

curl https://api.sandpi.ai/v1/models \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

Choose a model from the response. Its provider must match the Session provider. Create an Environment, then a Session inside it. Wait for the Environment to be ready before submitting a Run.

curl https://api.sandpi.ai/v1/environments \
    -H "Authorization: Bearer $SANDPI_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"name":"My project"}'

curl https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/sessions \
    -H "Authorization: Bearer $SANDPI_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"harness":"pi","provider":"anthropic"}'

Use the returned IDs and a supported model to submit a Run. Keep the same Idempotency-Key when retrying that submission.

export RUN_KEY="$(uuidgen)"

curl https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/sessions/$SESSION_ID/runs \
    -H "Authorization: Bearer $SANDPI_API_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $RUN_KEY" \
    -d '{"model":"YOUR_SUPPORTED_MODEL_ID","input":"Fix the login error"}'

Creation returns 202 and a Run ID. Fetch the Run or connect to its event stream to follow progress. Provider execution depends on the deployment being configured for that provider; unavailable providers return 503 on Run submission.

Authentication

Send a Platform API token in the Authorization: Bearerheader on every /v1 request. Tokens belong to an personal account or one Team Project and can be created or revoked in the console. The public API does not use the browser session cookie. A Project key can use only Environments and Runs in that Project; a personal key cannot access Team Projects. Sandpi holds the upstream provider credentials; clients do not provide provider API keys.

Environments, Sessions & Runs

A new Environment requires prepaid credit. You may optionally provide a public HTTPS Git repository.url and a branch or tag repository.ref; Sandpi clones it into /workspace/project before the initial checkpoint. Repository credentials and private hosts are not accepted.

Choose codex for OpenAI, claude-code for Anthropic, or pi with an explicit provider of openai or anthropic. To change harness or provider, create another Session in the same Environment.

Events & results

GET .../runs/{runId} returns status, final output, file changes, checkpoint state, and itemized usage. Run status can be queued, running, completed, failed, stopped, reverting, or reverted. checkpoint.status and fileDiffStatus are separate from Run status.

Stream events with Server-Sent Events. After a disconnect, send the last received event ID in Last-Event-ID or the after query parameter to replay later events.

curl -N \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/sessions/$SESSION_ID/runs/$RUN_ID/events" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN" \
    -H "Last-Event-ID: 42"

fileDiff lists added, modified, and deleted regular files under /workspace with before and after SHA-256 identities. Generated caches, Git metadata, and Sandpi-managed state are excluded. Large workspaces can report fileDiffStatus: "failed" without failing the Run.

Stop & rollback

POST .../runs/{runId}/stop asks the harness to stop. It leaves files already written in the Environment and does not undo external side effects. A Run that finishes before the stop request may remain completed.

Every terminal Run gets a RootFS checkpoint. The next Run waits for a consistent checkpoint boundary. DELETE on the latest Run restores the state before it, including native Session history. Rollback is asynchronous (202) and is only allowed for the latest Run across the whole Environment. Older Runs or later workspace mutations return 409. Rollback does not reverse token charges or external writes.

Billing & limits

Add USD prepaid credits in the dashboard. Checkout charges the selected credit amount plus a separate 5% top-up fee; the wallet receives the selected amount. Model tokens are rated at the published provider price with no Run-level markup or separate Sandbox charge. The Run usage result includes provider, model, token categories, price version, and charge.

Credit is required to create an Environment and submit a Run. Platform currently allows up to three active Environments per funding account. Team owners can share a Project with existing Sandpi users. Its Project keys have one immutable Project scope; owners and admins manage them in the console. A Project's USD monthly budget uses UTC calendar months and counts posted charges and unresolved reservations when admitting provider calls. A completed call can exceed its conservative reservation; later calls are blocked once the budget is spent. A request may be held for usage reconciliation if its provider usage is uncertain. The current provider path accepts text-only calls; multimodal inputs and separately billed provider-hosted tools are not supported.

API reference

All paths below are relative to https://api.sandpi.ai. Path IDs must belong to the token's personal account or Project and to their named parent resource. Successful JSON responses wrap the result in data; 204 has no body.

Errors

Errors return an HTTP status and an error object with a stable code, a message, and a requestId. Common responses include 400 for invalid input, 401 for a missing or invalid Platform token, 402 for insufficient credit, 404 for an unknown or inaccessible resource, 409 for a conflicting Run or rollback, and 503 when a provider is unavailable.

{
    "error": {
        "code": "platform_balance_insufficient",
        "message": "Top up Platform credits before submitting a Run.",
        "requestId": "..."
    }
}