Skip to content
LogoLogo

REST API Overview

The CreateOS Sandbox REST API lets you create, run, and manage microVMs programmatically.

At a glance

  • Base URL: https://api.sb.createos.sh
  • Auth: X-Api-Key: <token> header (get a token)
  • Response envelope: JSend: {"status": "...", "data": ...}

Base URL

https://api.sb.createos.sh

All paths are versioned under /v1.

Authentication

Every request must carry one of these headers:

HeaderDescription
X-Api-KeyPer-user API key. Sandbox ownership is scoped to the authenticated user; GET /v1/sandboxes returns only the caller's VMs.
X-Auth-TokenOpaque session token validated against the users service.
X-Access-TokenOAuth-style access token.

Get your API key at https://createos.sh/app/profile.

curl https://api.sb.createos.sh/v1/whoami \
  -H "X-Api-Key: $CREATEOS_API_KEY"

Response Envelope (JSend)

Every response wraps its payload in a JSend envelope.

Success (2xx)

{
  "status": "success",
  "data": { ... }
}

Fail (4xx): validation or not-found

{
  "status": "fail",
  "data": {
    "shape": "unknown shape: s-bad"
  }
}

Error (5xx): server fault

{
  "status": "error",
  "message": "internal error",
  "code": 500
}

Pagination

All list endpoints accept limit and offset query parameters. Paginated responses nest items under data.data[] alongside a pagination block:

{
  "status": "success",
  "data": {
    "data": [ { ... }, { ... } ],
    "pagination": {
      "total": 42,
      "limit": 50,
      "offset": 0,
      "count": 42
    }
  }
}
FieldDescription
totalTotal rows matching the query, ignoring limit/offset
limitLimit applied by the server
offsetOffset applied by the server
countItems in this response (≤ limit)

Default limit is 50; maximum is 500.

ID Formats

ResourceFormatExample
Sandboxsb-<ulid>sb-01K…
Networknet-<ulid>net-01k2x…
Diskdisk_<ulid>disk_01KSHT…
Templatetpl_<ulid>tpl_01K…

Networks and disks can also be referenced by their user-facing name where the spec notes it.

Content Types

DirectionContent-Type
JSON request bodiesapplication/json
File upload bodyapplication/octet-stream
File download responseapplication/octet-stream
Streaming exec responseapplication/x-ndjson
Managed process output streamapplication/x-ndjson

Streaming (NDJSON)

The exec endpoint supports a streaming mode (?stream=true). The response is HTTP/1.1 chunked transfer with Content-Type: application/x-ndjson, one JSON object per line. Managed process /connect and the template-logs endpoint also stream NDJSON.

Each ExecStreamEvent line is one of:

FrameShape
stdout chunk{"stdout": "…"}
stderr chunk{"stderr": "…"}
heartbeat{"hb": true} (every 5 s; clients ignore)
terminal{"exit_code": N}, last frame
agent error{"error": "…"}

Standard HTTP Status Codes

CodeMeaning
200Success
202Accepted, async operation in progress (poll via GET)
400Bad request / validation error
401Missing or invalid auth
402Payment required / quota exceeded
404Resource not found
409Conflict (e.g. sandbox not in correct state)
429Rate limited
503Service unavailable / no host capacity

Async operations (pause, resume, fork) return 202 with an X-Poll-After header (suggested seconds before next poll). Poll GET /v1/sandboxes/{id} until status reaches the expected terminal value.

API Sections