Disks

Disks let you mount an S3-compatible bucket into a sandbox as a filesystem path. Register a bucket once as a named disk, then attach it to any sandbox at create time or live.

Credentials are encrypted at rest (AES-256-GCM) and are never returned in any API response.

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

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/disks

List all disks registered by the caller. Credentials are never included.

Auth required: Yes

Query parameters

Example

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

Success response 200

JSON
Copy
1{
2  "status": "success",
3  "data": {
4    "data": [
5      {
6        "id": "disk_01KSHT…",
7        "name": "my-data",
8        "kind": "s3",
9        "config": {
10          "bucket": "my-data-bucket",
11          "endpoint": "https://s3.amazonaws.com",
12          "region": "us-east-1",
13          "use_path_style": false
14        },
15        "created_at": "2024-01-15T10:00:00Z"
16      }
17    ],
18    "pagination": { "total": 1, "limit": 50, "offset": 0, "count": 1 }
19  }
20}

Notable errors: 401 — unauthorized. 503 — disks feature not configured on this cluster.

POST /v1/disks

Register an S3-compatible bucket as a named disk. The API probes the bucket at registration time (3-second HEAD request) to catch typos early. Credentials are encrypted and stored — they are write-only and never returned.

Auth required: Yes

Request body

Example

Bash
Copy
1curl -X POST https://api.sb.createos.sh/v1/disks \
2  -H "X-Api-Key: $CREATEOS_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "my-data",
6    "kind": "s3",
7    "config": {
8      "bucket": "my-data-bucket",
9      "endpoint": "https://s3.amazonaws.com",
10      "region": "us-east-1"
11    },
12    "credentials": {
13      "access_key": "AKIA…",
14      "secret_key": "wJalrX…"
15    }
16  }'

Success response 200

JSON
Copy
1{
2  "status": "success",
3  "data": {
4    "id": "disk_01KSHT…",
5    "name": "my-data",
6    "kind": "s3",
7    "config": {
8      "bucket": "my-data-bucket",
9      "endpoint": "https://s3.amazonaws.com",
10      "region": "us-east-1",
11      "use_path_style": false
12    },
13    "created_at": "2024-01-15T10:00:00Z"
14  }
15}

Notable errors:

GET /v1/disks/{idOrName}

Get a single disk by id or user-scoped name. Credentials are never returned.

Auth required: Yes

Path parameters

Example

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

Success response 200 — same shape as the object in POST /v1/disks response.

Notable errors: 401 — unauthorized. 404 — not found or owned by another user (identical body — no existence leak across tenants). 503 — disks feature not configured.

DELETE /v1/disks/{idOrName}

Soft-delete a disk. Returns 409 if the disk is currently attached to any sandbox — detach it first.

Auth required: Yes

Path parameters

Example

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

Success response 200

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

Notable errors: 401 — unauthorized. 404 — not found. 409 — disk still attached to one or more sandboxes.

GET /v1/sandboxes/{id}/disks

List all disks attached to a sandbox, including live mount_status reported by the in-VM agent (polled every 30 seconds).

Auth required: Yes

Path parameters

Example

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

Success response 200

JSON
Copy
1{
2  "status": "success",
3  "data": {
4    "data": [
5      {
6        "disk_id": "disk_01KSHT…",
7        "name": "my-data",
8        "kind": "s3",
9        "config": {
10          "bucket": "my-data-bucket",
11          "endpoint": "https://s3.amazonaws.com"
12        },
13        "mount_path": "/mnt/data",
14        "sub_path": "",
15        "mount_status": "mounted",
16        "mount_error": null
17      }
18    ],
19    "pagination": { "total": 1, "limit": 50, "offset": 0, "count": 1 }
20  }
21}

mount_status values

Notable errors: 401 — unauthorized. 404 — sandbox not found.

POST /v1/sandboxes/{id}/disks

Live-attach a disk to a running sandbox. The agent mounts it within ~1 second of detection. Only works on sandboxes with status = "running".

Auth required: Yes

Path parameters

Request body

Example

Bash
Copy
1curl -X POST https://api.sb.createos.sh/v1/sandboxes/sb_01K.../disks \
2  -H "X-Api-Key: $CREATEOS_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"disk_id": "my-data", "mount_path": "/mnt/data"}'

Success response 200

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

Notable errors:

DELETE /v1/sandboxes/{id}/disks/{disk_id}

Live-detach a disk from a sandbox. Only the in-VM mount is dropped — the bucket contents are never touched.

A disk may be mounted at multiple paths in the same sandbox; use the mount_path query parameter to target a specific attachment.

Auth required: Yes

Path parameters

Query parameters

Example

Bash
Copy
1curl -X DELETE \
2  "https://api.sb.createos.sh/v1/sandboxes/sb_01K.../disks/disk_01KSHT...?mount_path=/mnt/data" \
3  -H "X-Api-Key: $CREATEOS_API_KEY"

Success response 200

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

Notable errors: 401 — unauthorized. 404 — disk not attached at that path (or sandbox/disk not owned by caller). First DELETE wins; a second call for the same (disk_id, mount_path) returns 404.