Catalog & Identity

These endpoints expose the static catalog (shapes, rootfs images, hosts) and identity/health utilities. Most are unauthenticated or low-overhead — useful for validating credentials, listing available options, or checking service health.

Get your API key from https://createos.nodeops.network/profile. Pass it as X-Api-Key: <token> on requests that require auth.

Base URL: https://api.sb.createos.sh

At a glance

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

GET /v1/shapes

List the available VM shapes. Use the id value (e.g. s-1vcpu-256mb) as the shape field when creating a sandbox.

Auth required: No

Example

Bash
Copy
1curl https://api.sb.createos.sh/v1/shapes

Success response 200

JSON
Copy
1{
2  "status": "success",
3  "data": {
4    "data": [
5      { "id": "s-1vcpu-256mb", "vcpu": 1, "mem_mib": 256, "default_disk_mib": 10240 },
6      { "id": "s-1vcpu-1gb",   "vcpu": 1, "mem_mib": 1024, "default_disk_mib": 10240 }
7    ],
8    "pagination": { "total": 2, "limit": 50, "offset": 0, "count": 2 }
9  }
10}

Shape fields

GET /v1/rootfs

List available rootfs images. Use the rootfs field value when creating a sandbox. Disabled rootfses are filtered out. The response also indicates the recommended default.

Auth required: No

Example

Bash
Copy
1curl https://api.sb.createos.sh/v1/rootfs

Success response 200

JSON
Copy
1{
2  "status": "success",
3  "data": {
4    "rootfs": ["devbox:1", "node"],
5    "default": "devbox:1"
6  }
7}

Response fields

GET /v1/hosts

List hosts in the cluster (public view). Shows capacity and available rootfs images per host.

Auth required: No

Query parameters

Example

Bash
Copy
1curl https://api.sb.createos.sh/v1/hosts

Success response 200

JSON
Copy
1{
2  "status": "success",
3  "data": {
4    "data": [
5      {
6        "id": "136.243.150.252",
7        "status": "active",
8        "free_mib": 8192,
9        "vm_count": 12,
10        "rootfses": ["devbox:1", "node"]
11      }
12    ],
13    "pagination": { "total": 1, "limit": 50, "offset": 0, "count": 1 }
14  }
15}

Host fields

GET /v1/whoami

Return the identity resolved from the bearer token plus a snapshot of the caller's sandbox counts. Useful for confirming credentials before doing real work — equivalent in spirit to aws sts get-caller-identity.

Counts are observational and carry no atomicity guarantee against concurrent creates/destroys.

Auth required: Yes

Example

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

Success response 200

JSON
Copy
1{
2  "status": "success",
3  "data": {
4    "user_id": "usr_01K…",
5    "stats": {
6      "running": 3,
7      "paused": 1,
8      "other": 0,
9      "total": 47
10    }
11  }
12}

stats fields

GET /healthz

Liveness probe. Returns {"up": true} when the control plane process is alive.

Auth required: No

Example

Bash
Copy
1curl https://api.sb.createos.sh/healthz

Success response 200

JSON
Copy
1{ "status": "success", "data": { "up": true } }

GET /readyz

Readiness probe. Returns {"ready": true} when the control plane can reach its database.

Auth required: No

Example

Bash
Copy
1curl https://api.sb.createos.sh/readyz

Success response 200

JSON
Copy
1{ "status": "success", "data": { "ready": true } }

Notable errors: 503 — control plane is up but cannot reach the database.