API Reference

Full spec: openapi.yaml (OpenAPI 3.1)

Base URL: https://api.isorun.ai

All /v1/* endpoints require Authorization: Bearer <api-key>.

Create a sandbox

curl -X POST https://api.isorun.ai/v1/runs \\
  -H "Authorization: Bearer $ISORUN_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"image": "python", "vcpus": 1, "mem_mib": 1024}'

{
  "id": "run78cbccbab85efc28",
  "status": "running",
  "image": "python",
  "vcpus": 1,
  "mem_mib": 1024,
  "disk_mib": 10240,
  "create_ms": 9,
  "created_at": "2026-04-05T12:00:00Z"
}

Execute a command

curl -X POST https://api.isorun.ai/v1/runs/run78cbccbab85efc28/exec \\
  -H "Authorization: Bearer $ISORUN_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"command": "python3 -c \\\"print(1+1)\\\"", "timeout": 30}'

{
  "exit_code": 0,
  "stdout": "2\n",
  "stderr": ""
}

Destroy a sandbox

curl -X DELETE https://api.isorun.ai/v1/runs/run78cbccbab85efc28 \\
  -H "Authorization: Bearer $ISORUN_API_KEY"

{
  "status": "destroyed",
  "cpu_ms": 48,
  "mem_peak_bytes": 48926720,
  "disk_used_bytes": 339968,
  "uptime_ms": 59000
}

All endpoints

Method	Path	Description
GET	/healthz	Health check (no auth)
POST	/v1/runs	Create a sandbox
GET	/v1/runs	List active sandboxes
GET	/v1/runs/{id}	Get sandbox status
DELETE	/v1/runs/{id}	Destroy a sandbox
POST	/v1/runs/{id}/exec	Execute command (JSON response)
POST	/v1/runs/{id}/exec/stream	Execute command (SSE stream)
GET	/v1/runs/{id}/terminal?token=KEY	WebSocket PTY terminal
POST	/v1/runs/{id}/snapshot	Snapshot a running sandbox
POST	/v1/runs/restore	Restore from snapshot
POST	/v1/runs/{id}/files/upload?path=PATH	Upload file
GET	/v1/runs/{id}/files/download?path=PATH	Download file
GET	/v1/runs/{id}/files?path=PATH	List directory
POST	/v1/images/build	Build image from Docker Hub

See the OpenAPI spec for request/response schemas, error codes, and parameter constraints.