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:

Get your API key at https://createos.nodeops.network/profile.

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

Response Envelope (JSend)

Every response wraps its payload in a JSend envelope.

Success (2xx)

JSON
Copy
1{
2  "status": "success",
3  "data": { ... }
4}

Fail (4xx) — validation or not-found

JSON
Copy
1{
2  "status": "fail",
3  "data": {
4    "shape": "unknown shape: s-bad"
5  }
6}

Error (5xx) — server fault

JSON
Copy
1{
2  "status": "error",
3  "message": "internal error",
4  "code": 500
5}

Pagination

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

JSON
Copy
1{
2  "status": "success",
3  "data": {
4    "data": [ { ... }, { ... } ],
5    "pagination": {
6      "total": 42,
7      "limit": 50,
8      "offset": 0,
9      "count": 42
10    }
11  }
12}

Default limit is 50; maximum is 500.

ID Formats

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

Content Types

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. The template-logs endpoint also streams NDJSON.

Each ExecStreamEvent line is one of:

Standard HTTP Status Codes

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

• Sandboxes — create, list, get, update, delete
• Execution & Files — run commands, upload and download files
• Pause, Resume & Fork — lifecycle snapshots and cloning
• Networks — private sandbox-to-sandbox networks
• Egress — outbound firewall allowlists
• Disks — S3-backed persistent volumes
• Templates — custom rootfs images built from Dockerfiles
• Bandwidth & Resize — quota management and disk resize
• Catalog & Identity — shapes, rootfs catalog, whoami