REST API reference

The sandbox REST API lives at https://api.orkestr.eu/v1. Use it directly from any language, or pick the Python or JS SDK and skip the wire format entirely.

Base URL

https://api.orkestr.eu/v1

Authentication

Every request must carry a Bearer token in the Authorization header. Mint tokens in the orkestr console with the sandboxes:read and sandboxes:write scopes. Tokens that lack the required scope get 403 Forbidden.

curl https://api.orkestr.eu/v1/sandboxes \
  -H "Authorization: Bearer $ORKESTR_API_KEY"

Endpoints

Seventeen endpoints across lifecycle, exec, files, metrics, port exposure, pause / resume, and custom templates:

• POST /v1/sandboxes - create a sandbox
• GET /v1/sandboxes - list yours
• GET /v1/sandboxes/limits - sizes and caps your plan allows
• GET /v1/sandboxes/{id} - get one
• GET /v1/sandboxes/{id}/metrics - live CPU + memory
• GET /v1/sandboxes/{id}/host?port=N - public URL for a port
• DELETE /v1/sandboxes/{id} - terminate
• POST /v1/sandboxes/{id}/exec - run a command
• POST /v1/sandboxes/{id}/files - write file
• GET /v1/sandboxes/{id}/files?path=... - read file or list dir
• DELETE /v1/sandboxes/{id}/files?path=... - delete file
• POST /v1/sandboxes/{id}/pause - snapshot + suspend
• POST /v1/sandboxes/{id}/resume - restore
• POST /v1/templates - build a custom template
• GET /v1/templates - list yours
• GET /v1/templates/{id} - get one (poll build status)
• DELETE /v1/templates/{id} - delete a template + its image
• POST /v1/sandboxes/volumes - create a persistent volume
• GET /v1/sandboxes/volumes - list yours
• POST /v1/sandboxes/volumes/{id}/move - move a detached volume to another region
• DELETE /v1/sandboxes/volumes/{id} - delete a volume + its data

Create a sandbox

POST /v1/sandboxes requires the sandboxes:write scope.

Request

import httpx, os

response = httpx.post(
    "https://api.orkestr.eu/v1/sandboxes",
    headers={"Authorization": f"Bearer {os.environ['ORKESTR_API_KEY']}"},
    json={
        "template": "python-3.12",
        "size": "small",
        "network": "off",
        "timeout_seconds": 600,
        "env": {"OPENAI_API_KEY": "sk-..."},
        "metadata": {"agent_run": "r_42"},
    },
)
sandbox = response.json()

Response

{
  "id": "sbx_01HXYZ...",
  "status": "running",
  "template": "python-3.12",
  "network": "off",
  "cpu": 1.0,
  "memory_mb": 2048,
  "region": "fsn1",
  "created_at": "2026-05-19T14:22:11Z",
  "expires_at": "2026-05-19T14:32:11Z",
  "endpoints": {
    "exec": "/v1/sandboxes/sbx_01HXYZ.../exec",
    "files": "/v1/sandboxes/sbx_01HXYZ.../files",
    "pause": "/v1/sandboxes/sbx_01HXYZ.../pause",
    "resume": "/v1/sandboxes/sbx_01HXYZ.../resume"
  },
  "metadata": {"agent_run": "r_42"}
}

Run a command

POST /v1/sandboxes/{id}/exec requires sandboxes:write. Set stream to false for a buffered response, true for an SSE stream.

Request

httpx.post(
    "https://api.orkestr.eu/v1/sandboxes/sbx_01HXYZ.../exec",
    headers={"Authorization": f"Bearer {os.environ['ORKESTR_API_KEY']}"},
    json={
        "command": "python -c 'print(2+2)'",
        "cwd": "/workspace",
        "timeout_seconds": 60,
        "stream": False,
    },
).json()

Buffered response (stream=false)

{
  "stdout": "4\n",
  "stderr": "",
  "exit_code": 0,
  "duration_ms": 18
}

Streaming response (stream=true)

Content type is text/event-stream. Each frame is a data: line containing a JSON object with a kind field. data on chunk frames is base64-encoded.

data: {"kind":"exec_started","pid":42}

data: {"kind":"exec_chunk","stream":"stdout","data":"NA=="}

data: {"kind":"exec_chunk","stream":"stderr","data":"d2Fybg=="}

data: {"kind":"exec_exited","code":0,"duration_ms":23}

Frame kinds:

Files

Three endpoints sharing the path under /v1/sandboxes/{id}/files. All file content is base64 over the wire so binary round-trips cleanly. Reads and writes are capped at 16 MiB per request.

Write a file

POST /v1/sandboxes/{id}/files requires sandboxes:write. Writes go to /workspace or /tmp.

import base64
httpx.post(
    f"{BASE}/sandboxes/{sandbox_id}/files",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "path": "/workspace/main.py",
        "content": base64.b64encode(b"print(2+1)").decode(),
        "mode": 0o644,
    },
)

Read a file or list a directory

GET /v1/sandboxes/{id}/files?path=... requires sandboxes:read. Returns one shape for both cases - is_dir tells you which fields are populated.

File response

{
  "path": "/workspace/main.py",
  "is_dir": false,
  "content": "cHJpbnQoMisxKQ==",
  "size": 10
}

Directory response

{
  "path": "/workspace",
  "is_dir": true,
  "entries": [
    {
      "name": "main.py",
      "is_dir": false,
      "size": 10,
      "mode": 420,
      "modified_at": "2026-05-19T14:23:00Z"
    }
  ]
}

Delete a file

DELETE /v1/sandboxes/{id}/files?path=... requires sandboxes:write. Returns 204 No Content on success. Directories are rejected; terminate the sandbox to drop everything.

Pause and resume

POST /v1/sandboxes/{id}/pause snapshots the sandbox and stops the compute meter. Returns the sandbox id and the server-side snapshot id; pass the sandbox id back to /resume when you want to come back.

Pause response

{
  "sandbox_id": "sbx_01HXYZ...",
  "snapshot_id": "snap_...",
  "status": "paused",
  "snapshot_size_mb": 1024,
  "created_at": "2026-05-19T14:30:00Z"
}

POST /v1/sandboxes/{id}/resume restores from the most recent snapshot for that sandbox. Returns the same shape as create. May be served from a different host than the original; restore latency depends on snapshot size.

Live metrics

GET /v1/sandboxes/{id}/metrics requires sandboxes:read. Returns the latest CPU and memory reading plus a rolling ~60s window of one-second samples (a sparkline in one call) and the sandbox's lifetime totals. cpu.usage_percent is normalised to allocated cores, so a one-core sandbox fully pegged reads 100. memory.usage_bytes is the working set (it excludes reclaimable file cache), so it tracks pressure that can actually run a sandbox out of memory.

Response

{
  "sandbox_id": "sbx_01HXYZ...",
  "sandbox_status": "running",
  "as_of": "2026-05-19T14:25:00+00:00",
  "as_of_unix": 1747665900,
  "sample_interval_seconds": 1,
  "window_seconds": 60,
  "cpu": { "cores": 1.0, "usage_cores": 0.94, "usage_percent": 94.0 },
  "memory": { "limit_bytes": 536870912, "usage_bytes": 188743680, "usage_percent": 35.2 },
  "lifetime": { "cpu_seconds": 12.84, "gb_seconds": 5.63 },
  "samples": [
    { "t": 1747665899, "cpu_percent": 92.4, "mem_bytes": 187000000 },
    { "t": 1747665900, "cpu_percent": 94.0, "mem_bytes": 188743680 }
  ]
}

Expose a port

GET /v1/sandboxes/{id}/host?port={port} requires sandboxes:read. Returns the public URL for an HTTP port a process in the sandbox is serving. host has the form <port>-<id>.sbx.orkestr.run, where <id> is the sandbox id with the sbx_ prefix dropped and lowercased. url is host with an https:// scheme.

{
  "port": 3000,
  "host": "3000-01hxyz....sbx.orkestr.run",
  "url": "https://3000-01hxyz....sbx.orkestr.run"
}

Custom templates

Build a reusable image with your dependencies preinstalled, then boot sandboxes from it in ~300 ms. Building is a control-plane operation - the SDKs consume templates but don't build them. The Custom templates guide covers the full flow.

Build a template

POST /v1/templates requires sandboxes:write and a paid plan. The build is asynchronous - the response returns immediately with status: "building".

curl -X POST https://api.orkestr.eu/v1/templates \
  -H "Authorization: Bearer $ORKESTR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-stack",
    "base_template": "python-3.12",
    "recipe": ["pip install pandas numpy"],
    "network": "restricted"
  }'

Response

{
  "id": "tmpl_01J...",
  "name": "data-stack",
  "base_template": "python-3.12",
  "recipe": ["pip install pandas numpy"],
  "status": "building",
  "error_message": null,
  "size_mb": null,
  "created_at": "2026-06-16T12:00:00Z",
  "built_at": null
}

Poll GET /v1/templates/{id} until status is ready (or failed, with error_message). GET /v1/templates lists yours, and DELETE /v1/templates/{id} removes a template and its image. Boot from a ready template by passing its id as the template on POST /v1/sandboxes.

Errors

Error bodies are JSON with at minimum a detail string. Many also carry a machine-readable code - dispatch on that when present, fall back to the HTTP status code otherwise.

{
  "detail": "API token missing required scope(s): sandboxes:write",
  "code": "missing_scope"
}

Request IDs

Every response carries an x-request-id header. Include it in support tickets so we can correlate against server logs.