Quick start

Before you start

Open the Platform console, bind a card without payment to claim your $5 new-account Promotion Credits (valid until 30 days after registration) or add prepaid credit, and create a personal API key or a key for your Team Project. Copy the key when it is shown; it cannot be viewed again. These commands use curl.

export SANDPI_API_TOKEN="your-platform-token"

Commands below come from the API contract. Replace placeholders such as YOUR_SUPPORTED_MODEL_ID and YOUR_SESSION_ID with your own values. Path variables use the returned resource IDs.

Choose a model and harness

Choose a native Harness and prepare your model API base URL and API key. Your gateway must support that Harness's native API. See model connections for the protocol mapping. Model charges go to your provider; Sandpi bills actual Sandbox runtime by the second, at a rate equivalent to $0.10/hour for a fixed 2 vCPU / 4 GiB Sandbox.

Create a persistent Environment

curl -X POST \
    "https://api.sandpi.ai/v1/environments" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "name": "PR review workspace",
  "labels": {
    "repo": "sandpi",
    "purpose": "review"
  }
}'

{
  "name": "PR review workspace",
  "labels": {
    "repo": "sandpi",
    "purpose": "review"
  }
}

{
  "data": {
    "id": "",
    "name": "",
    "status": "ready",
    "platform": {
      "initialCheckpointStatus": "pending",
      "workspaceRevision": -9007199254740991
    },
    "labels": {},
    "labelsRevision": 0,
    "networkPolicy": {
      "mode": "allow-all",
      "domainExceptions": [
        "example"
      ]
    }
  }
}

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

The JSON result is wrapped in data. Save data.id as ENVIRONMENT_ID. Poll the Environment until its status and platform.initialCheckpointStatus are both ready. A successful creation response can precede initialization completion.

export ENVIRONMENT_ID="returned-environment-id"

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

{
  "data": {
    "id": "",
    "name": "",
    "status": "ready",
    "platform": {
      "initialCheckpointStatus": "pending",
      "workspaceRevision": -9007199254740991
    },
    "labels": {},
    "labelsRevision": 0,
    "networkPolicy": {
      "mode": "allow-all",
      "domainExceptions": [
        "example"
      ]
    }
  }
}

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

Create a harness Session

The Session retains native conversation history across Runs. Supply your native connection when creating the Session. Pi additionally requires its API type.

curl -X POST \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/sessions" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "harness": "codex",
  "connection": {
    "baseUrl": "https://gateway.example.com/v1",
    "apiKey": "YOUR_GATEWAY_KEY"
  }
}'

{
  "harness": "codex",
  "connection": {
    "baseUrl": "https://gateway.example.com/v1",
    "apiKey": "YOUR_GATEWAY_KEY"
  }
}

{
  "data": {
    "id": "",
    "environmentId": "",
    "harness": "codex",
    "provider": "openai",
    "nativeHistoryState": "new",
    "createdAt": "2026-10-12T01:00:00Z"
  }
}

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

Save data.id as SESSION_ID. A Platform Session is a headless conversation; it is separate from an interactive TUI terminal.

export SESSION_ID="returned-session-id"
export REQUEST_KEY="$(uuidgen)"

Submit your first Run

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

{
  "model": "YOUR_SUPPORTED_MODEL_ID",
  "input": "Fix the login error"
}

{
  "data": {
    "id": "",
    "environmentId": "",
    "sessionId": "",
    "environmentSequence": -9007199254740991,
    "model": "",
    "input": "",
    "files": [
      {
        "path": ""
      }
    ],
    "status": "queued",
    "stopRequested": false,
    "fileDiff": [
      {
        "path": "",
        "kind": "added"
      }
    ],
    "fileDiffStatus": "pending",
    "checkpoint": {
      "status": "pending"
    },
    "createdAt": "2026-10-12T01:00:00Z",
    "steeringEnabled": false
  }
}

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

Save the returned data.id as RUN_ID. Keep the same request key and body if the connection fails during submission. A new key means new work. Runs in one Environment execute serially, including Runs from different Sessions.

export RUN_ID="returned-run-id"

Follow execution and collect the result

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"

id: 42
event: run.output
data: {"id":42,"type":"run.output"}

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

The SSE connection can be closed without stopping the Run. Reconnect using the last event ID rather than resubmitting the task.

curl \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/sessions/$SESSION_ID/runs/$RUN_ID" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

{
  "data": {
    "id": "",
    "environmentId": "",
    "sessionId": "",
    "environmentSequence": -9007199254740991,
    "model": "",
    "input": "",
    "files": [
      {
        "path": ""
      }
    ],
    "status": "queued",
    "stopRequested": false,
    "fileDiff": [
      {
        "path": "",
        "kind": "added"
      }
    ],
    "fileDiffStatus": "pending",
    "checkpoint": {
      "status": "pending"
    },
    "createdAt": "2026-10-12T01:00:00Z",
    "usage": {
      "calls": [],
      "serviceFeePercent": 0,
      "upstreamAmountUsd": "",
      "serviceFeeUsd": "",
      "totalAmountUsd": "",
      "sandboxAmountUsd": ""
    }
  }
}

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

Inspect the Run status and output, then its separate checkpoint, file-diff and usage state. Output can be available while checkpoint capture is still pending. Wait for the checkpoint and lifecycle lock to settle before retrieving files or forking.

Next steps

Add shared instructions, Skills or MCP tools. Use schedules for timed work and inbound webhooks for external events. See errors and retries if admission fails.