---
title: "Create a persistent volume, empty or restored from a backup."
method: POST
path: "/v1/volumes"
tags: ["volumes"]
---

# Create a persistent volume, empty or restored from a backup.

`POST /v1/volumes`

## Request

- Base URL: `https://api.withruntime.com`
- URL: `https://api.withruntime.com/v1/volumes`
- Auth: HTTP bearer

Ready in about a second (a restore takes as long as its download); send Prefer: wait=10 to wait for it. Attach it when creating a sandbox with volumes: [{volumeId, path, mode}]. A volume lives on one host's disks. It is backed up off that host daily unless you turn that off, and whenever you ask; backedUp is true once a backup has been copied off the host and checked. Writes since the last backup are not in it. A backup is crash-consistent: what a program had not yet written to the disk is not in it.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `name` string: Your own handle for the resource. Letters, digits, dot, dash, underscore.
  - `labels` object: Your own key/value tags, at most 32. Filter lists with label=key:value.
  - `region` string: Omit for the default region, or the backup's region.
  - `sizeMiB` integer: Fixed size, reserved in full. 64 MiB to 1 TiB. Omit when restoring a backup.
  - `fromBackup` string: A ready backup to restore into the new volume. The new volume is the backup's size, in its region, on whichever host has room, and is ready once the restore is checked.

## Response `200`

Success

- object
  - `id` string, required
  - `kind` 'volume', required
  - `status` string, required
  - `state` 'creating' | 'ready' | 'failed' | 'deleting' | 'deleted', required
  - `name` string, nullable
  - `sizeMiB` integer, required
  - `usedMiB` integer, nullable
  - `backedUp` boolean, required: A volume lives on one host's disks. It is backed up off that host daily unless you turn that off, and whenever you ask; backedUp is true once a backup has been copied off the host and checked. Writes since the last backup are not in it. A backup is crash-consistent: what a program had not yet written to the disk is not in it.
  - `backups` object
    - `daily` boolean: Whether a backup is made each day.
    - `retentionDays` integer: How long each daily backup is kept.
    - `lastReadyAt` string, nullable: When the newest ready backup was taken.
  - `restoredFrom` string, nullable: The backup this volume was made from.
  - `attachments` object[]
    - `sandboxId` string
    - `mode` 'rw' | 'snapshot'
    - `path` string
    - `attachedAt` string
  - `createdAt` string

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/withruntime/apis/runtime-cloud-api.md) · [All operations](https://skmtc.dev/withruntime/apis/runtime-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/withruntime/apis/runtime-cloud-api/revisions/6f4012286988?raw)