Manage sandboxes

Base path: /api/v1/sandboxes

List Sandboxes

GET /api/v1/sandboxes

Returns all sandboxes belonging to the authenticated tenant.

Query Parameters

Auth

Bearer token required.

Response - 200 OK

{
  "data": [
    {
      "id": "sbx_01j9xr2t4fk8me3n5q",
      "template_id": "miosa-sandbox",
      "state": "running",
      "cpu_count": 2,
      "memory_mb": 4096,
      "created_at": "2026-04-25T10:00:00Z"
    }
  ]
}

curl "https://api.miosa.ai/api/v1/sandboxes?state=running" 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Get a Sandbox

GET /api/v1/sandboxes/{id}

Auth

Bearer token required.

Path Parameters

Response - 200 OK

Full sandbox object (same shape as the create response with current state).

Errors

curl https://api.miosa.ai/api/v1/sandboxes/sbx_01j9xr2t4fk8me3n5q 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Destroy a Sandbox

DELETE /api/v1/sandboxes/{id}

Permanently deletes the sandbox, removes saved state, and settles billing. Use POST /pause when the user is done for now but may resume later.

Auth

Bearer token required.

Path Parameters

Response - 200 OK

{
  "id": "sbx_01j9xr2t4fk8me3n5q",
  "state": "destroyed",
  "total_runtime_sec": 42
}

Errors

curl -X DELETE https://api.miosa.ai/api/v1/sandboxes/sbx_01j9xr2t4fk8me3n5q 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Pause and Resume

POST /api/v1/sandboxes/{id}/pause suspends guest vCPU execution for a running persistent sandbox while preserving its workspace. It returns 409 if the sandbox is not running.

POST /api/v1/sandboxes/{id}/resume transitions a paused sandbox back to running and returns 409 if it is not paused. Command and file operations can automatically resume a paused persistent sandbox before dispatch.

curl -X POST https://api.miosa.ai/api/v1/sandboxes/{id}/pause 
  -H "Authorization: Bearer $MIOSA_API_KEY"

curl -X POST https://api.miosa.ai/api/v1/sandboxes/{id}/resume 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Idempotency-Key: resume-session-001"

Fork a Sandbox

POST /api/v1/sandboxes/{id}/fork creates a new sandbox from a copy-on-write snapshot of a running sandbox. The optional body accepts timeout_sec and template_id for the new sandbox.

curl -X POST https://api.miosa.ai/api/v1/sandboxes/{id}/fork 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -H "Idempotency-Key: fork-experiment-001" 
  -d '{"timeout_sec":3600}'

Canonical public V1 exposes standalone snapshot create, list, inspect, delete, and restore operations. Use fork when a customer needs an independent branch of current running state without managing the intermediate snapshot directly.

Extend the Timeout

POST /api/v1/sandboxes/{id}/extend

Replaces the active-session timeout with timeout_sec from 1 through 86400. The operation does not add duration to the old value. Omitting the body preserves the current timeout.

curl -X POST https://api.miosa.ai/api/v1/sandboxes/{id}/extend 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"timeout_sec":7200}'

Get Sandbox Usage

GET /api/v1/sandboxes/{id}/usage

Returns measured runtime, provisioned vCPU time, active CPU, network traffic, estimated cost, and timeout visibility.

{
  "data": {
    "sandbox_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "state": "running",
    "runtime_sec": 47,
    "provisioned_vcpu_ms": 94000,
    "active_cpu_ms": 12000,
    "network_ingress_bytes": 2048,
    "network_egress_bytes": 4096,
    "measurement_status": {
      "active_cpu": "measured",
      "network": "measured",
      "provisioned_resources": "measured"
    },
    "estimated_cost_cents": 1,
    "timeout_sec": 3600,
    "timeout_remaining_ms": 3553000
  }
}

Interpret nullable measurements through measurement_status. unavailable means no trustworthy value exists and the related field is null, not zero. stale means the retained value is not current and must be labeled as such. timeout_remaining_ms can be null before start or when timeout enforcement is disabled.