Bandwidth & Resize

Every sandbox starts with a cluster-default bandwidth quota (5 GiB). When the quota is exhausted outbound traffic is dropped in-kernel until you top up. Disk can be grown online (no restart) to any of the fixed available sizes.

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/sandboxes/{id}/bandwidth`

Read the current bandwidth quota and usage for a sandbox.

Auth required: Yes

Path parameters

Parameter	Description
`id`	Sandbox id.

Example

Bash
1curl https://api.sb.createos.sh/v1/sandboxes/sb-01K.../bandwidth \
2  -H "X-Api-Key: $CREATEOS_API_KEY"

Success response 200

JSON
1{
2  "status": "success",
3  "data": {
4    "id": "sb-01K…",
5    "quota_bytes": 5368709120,
6    "used_bytes": 1073741824,
7    "remaining_bytes": 4294967296,
8    "capped": false
9  }
10}

Response fields

Field	Type	Description
`id`	string	Sandbox id.
`quota_bytes`	integer	Total outbound bandwidth budget in bytes.
`used_bytes`	integer	Bytes consumed since last recharge.
`remaining_bytes`	integer	`quota_bytes - used_bytes`.
`capped`	boolean	`true` when outbound traffic is currently being dropped in-kernel because usage hit the quota. Clears within ~5 seconds of a successful recharge.

Notable errors: 404 sandbox not found.

POST `/v1/sandboxes/{id}/bandwidth/recharge`

Top up a sandbox's bandwidth quota by adding bytes to the current quota. This is an additive operation; it adds to the existing quota rather than replacing it.

If the sandbox is currently capped (capped: true), the in-kernel DROP rule is removed within ~5 seconds after a recharge that pushes usage below the new quota.

Auth required: Yes

Path parameters

Parameter	Description
`id`	Sandbox id.

Request body

Field	Type	Required	Description
`add_bytes`	integer	Yes	Number of bytes to add to the current quota. Additive, not a reset.

Example: add 10 GiB

Bash
1curl -X POST https://api.sb.createos.sh/v1/sandboxes/sb-01K.../bandwidth/recharge \
2  -H "X-Api-Key: $CREATEOS_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"add_bytes": 10737418240}'

Success response 200

JSON
1{
2  "status": "success",
3  "data": {
4    "id": "sb-01K…",
5    "quota_bytes": 16106127360,
6    "used_bytes": 5368709120,
7    "remaining_bytes": 10737418240,
8    "capped": false
9  }
10}

Notable errors: 400 invalid add_bytes. 404 sandbox not found.

POST `/v1/sandboxes/{id}/resize`

Grow a sandbox's disk online. No sandbox restart is needed, though the resize may take a few seconds on large changes.

Disk size can only increase, not decrease. The new size must be one of the fixed menu values.

Auth required: Yes

Path parameters

Parameter	Description
`id`	Sandbox id.

Request body

Field	Type	Required	Description
`disk_mib`	integer	Yes	New disk size in MiB. Must be one of: `10240`, `20480`, `30720`, `40960`, `51200`, `61440`. Must be larger than the current size.

Example: grow to 20 GiB

Bash
1curl -X POST https://api.sb.createos.sh/v1/sandboxes/sb-01K.../resize \
2  -H "X-Api-Key: $CREATEOS_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"disk_mib": 20480}'

Success response 200

JSON
1{
2  "status": "success",
3  "data": {
4    "id": "sb-01K…",
5    "disk_mib": 20480
6  }
7}

Notable errors: 400 invalid disk_mib (not in the allowed list, or smaller than current size). 404 sandbox not found.

Bandwidth & Resize

GET /v1/sandboxes/{id}/bandwidth

POST /v1/sandboxes/{id}/bandwidth/recharge

POST /v1/sandboxes/{id}/resize

100,000+ Builders. One Platform.

GET `/v1/sandboxes/{id}/bandwidth`

POST `/v1/sandboxes/{id}/bandwidth/recharge`

POST `/v1/sandboxes/{id}/resize`