Skip to content

Volume API reference

A disk that outlives the machines it is attached to.

Base URL: https://api.withruntime.com. Authentication, idempotency and errors work the same way for every product.

Its states: making, ready, failed, deleted.

Updated .md

Endpoints#

Method Path Description
POST /v2/volumes Create a volume
GET /v2/volumes List volumes
GET /v2/volumes/{id} Get a volume
DELETE /v2/volumes/{id} Delete a volume

Create a volume#

POST /v2/volumes

Creates an empty volume. Asked again with the same Idempotency-Key, it returns the same one.

Its action, for a key's grant: volumes:create.

Body: a VolumeCreate.

Returns a Stored.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/volumes" \  -H "Authorization: Bearer $RUNTIME_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "sizeMiB": 1 }'
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.volumes.create({ sizeMiB: 1 });
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.volumes.create(size_mib=1)
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.volumes.create(size_mib: 1)
Terminalruntime volumes create --size-mib 1

List volumes#

GET /v2/volumes

Lists the project's volumes, newest first.

Its action, for a key's grant: volumes:list.

Query:

Field Type Required Description
name string No Only those of this name.
state string No Only those in these states, comma-separated.
label list of string No Only those with every label given (repeat it for several): key:value, or a key for any value.
cursor string No Where the page starts: a page's next.
limit integer No The most items the page holds. At least 1. At most 200. Default: 50.

Returns a page: items, each a Stored, and next, where the next page starts, none on the last.

In v1: GET /v1/volumes.

Examples:

Terminalcurl -X GET "https://api.withruntime.com/v2/volumes" \  -H "Authorization: Bearer $RUNTIME_API_KEY"
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.volumes.list();
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.volumes.list()
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.volumes.list
Terminalruntime volumes list

Get a volume#

GET /v2/volumes/{id}

Returns a volume.

Its action, for a key's grant: volumes:get.

Path: id.

Returns a Stored.

Examples:

Terminalcurl -X GET "https://api.withruntime.com/v2/volumes/VOLUME_ID" \  -H "Authorization: Bearer $RUNTIME_API_KEY"
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.volumes.get("VOLUME_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.volumes.get("VOLUME_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.volumes.get("VOLUME_ID")
Terminalruntime volumes get VOLUME_ID

Delete a volume#

DELETE /v2/volumes/{id}

Deletes a volume and what it holds. One attached to a sandbox is refused: delete the sandbox first.

Its action, for a key's grant: volumes:delete.

Path: id.

Returns a Stored.

Examples:

Terminalcurl -X DELETE "https://api.withruntime.com/v2/volumes/VOLUME_ID" \  -H "Authorization: Bearer $RUNTIME_API_KEY"
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.volumes.delete("VOLUME_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.volumes.delete("VOLUME_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.volumes.delete("VOLUME_ID")
Terminalruntime volumes delete VOLUME_ID

Objects#

VolumeCreate

A volume to create: an empty disk, formatted ext4 at its first mount.

Field Type Required Description
name string No Its name, unique in its project among volumes.
labels labels (keys under runtime. are Runtime's) No Labels to find it by.
sizeMiB integer Yes Its size in MiB, 64 to 409600 (400 GiB).

Stored

Stored data: a snapshot, an image or a volume.

Field Type Required Description
id string Yes Its ID.
object one of snapshot, image, volume Yes Its kind: snapshot, image or volume.
name string No Its name, unique in its project among its kind.
state one of making, ready, failed, deleted Yes Where it is.
labels labels (keys under runtime. are Runtime's) Yes Its labels.
sizeBytes integer Yes What it was made to hold, in bytes.
storedBytes integer Yes What it holds now, in bytes.
parentId string No What it was made from (a snapshot's sandbox, an image's base), if anything.
attachedTo string No The machine it is attached to now, if any.
createdAt string (RFC 3339) No When it was made.
version integer No An image's version of its name: each build or keep of a name is its next.
tags list of string No An image's tags, each name:tag.
error string No Why an image's build failed.
deletedAt string (RFC 3339) No When it was deleted: a delete's answer, its state deleted.
Try it on your own work.Signing up takes no card. Your first sandbox asks for one, and the trial starts then. Or paste the setup prompt into your agent.
Start your free trial