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.sh/app/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

curl https://api.sb.createos.sh/v1/shapes

Success response 200

{
  "status": "success",
  "data": {
    "data": [
      {
        "id": "s-1vcpu-256mb",
        "vcpu": 1,
        "mem_mib": 256,
        "default_disk_mib": 10240
      },
      {
        "id": "s-1vcpu-1gb",
        "vcpu": 1,
        "mem_mib": 1024,
        "default_disk_mib": 10240
      }
    ],
    "pagination": { "total": 2, "limit": 50, "offset": 0, "count": 2 }
  }
}

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

curl https://api.sb.createos.sh/v1/rootfs

Success response 200

{
  "status": "success",
  "data": {
    "rootfs": ["devbox:1", "ubuntu:26.04", "debian:13", "alpine:3.20"],
    "default": "devbox:1"
  }
}

The names listed here are the first-party base images. They're kept warm on the hosts and start immediately with no image pull, so they're the fastest way to launch a sandbox. A custom template you build is slower the first time it runs on a given host (the host fetches it before the first boot) and fast on every boot after that.

Response fields

GET /v1/hosts

Host enumeration is an operator-only endpoint. A customer API key does not grant access. Use the shapes and rootfs catalogs above to choose resources; CreateOS handles placement.

Auth required: Operator authorization.

Query parameters

Success response 200

{
  "status": "success",
  "data": {
    "data": [
      {
        "id": "192.0.2.10",
        "status": "active",
        "free_mib": 8192,
        "vm_count": 12,
        "rootfses": ["devbox:1", "node"]
      }
    ],
    "pagination": { "total": 1, "limit": 50, "offset": 0, "count": 1 }
  }
}

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

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

Success response 200

{
  "status": "success",
  "data": {
    "user_id": "usr_01K…",
    "stats": {
      "running": 3,
      "paused": 1,
      "other": 0,
      "total": 47
    }
  }
}

stats fields

GET /healthz

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

Auth required: No

Example

curl https://api.sb.createos.sh/healthz

Success response 200

{ "status": "success", "data": { "up": true } }

GET /readyz

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

Auth required: No

Example

curl https://api.sb.createos.sh/readyz

Success response 200

{ "status": "success", "data": { "ready": true } }

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