---
title: "Create a volume"
method: POST
path: "/volumes"
tags: ["Volumes"]
---

# Create a volume

`POST /volumes`

Provisions a persistent volume synchronously. Volumes are backed by Brimble's
globally distributed S3-compatible object storage; when the response returns
the disk is allocated and ready to attach to a sandbox or project.

Names are unique per user. Region is permanently pinned at creation;
volumes can only attach to sandboxes / projects in the same region.

`type` declares the surface this volume is intended for and drives where
it shows up in attach pickers:
- `web`, project disk (default)
- `sandbox`, sandbox disk

## Request body

- CreateVolumeInput
  - `name` string, required — Lowercase letters, digits, hyphens; 1–40 chars. Unique per user.
  - `sizeGB` integer, required — Disk size in GB. Subject to plan caps.
  - `region` string, required — Region id from `GET /v1/regions`. Cannot be changed after creation.
  - `type` 'web' | 'sandbox' — Which surface a volume is intended for: - `web`, project disk (default) - `sandbox`, sandbox disk
  - `teamId` string — Create the volume under a team you're a member of. Copy the team ID from the team's settings page in the dashboard. Omit for a personal volume.

## Response `201`

Volume created

- VolumeEnvelope
  - `message` string, required
  - `data` Volume, required
    - `id` string, required
    - `name` string, required — Matches `^[a-z0-9-]{1,40}$`.
    - `type` 'web' | 'sandbox', required — Which surface a volume is intended for: - `web`, project disk (default) - `sandbox`, sandbox disk
    - `team` string, nullable — Team id if team-scoped.
    - `volume_handle` string, nullable — Storage-layer handle for the volume. Surfaced in advanced / debug views only.
    - `size` integer, required — Disk size in GB (10–50).
    - `region` SandboxRegion
      - `id` string, required
      - `name` string, required
      - `country` string, required
      - `continent` string, required
      - `enabled` boolean, required — Whether the region is currently accepting new sandboxes.
      - `type` 'sandbox', required — Region kind. Sandbox endpoints only return sandbox-eligible regions.
    - `mount_path` string, nullable — Where the volume mounts inside the attached sandbox or project.
    - `attached_sandbox_id` string, nullable, required — Non-null when the volume is currently attached to a sandbox.
    - `attached_project_id` string, nullable, required — Non-null when the volume is currently attached to a project.
    - `last_attached_at` string, date-time, nullable
    - `created_at` string, date-time, nullable
    - `updated_at` string, date-time, nullable

## Other responses

- `400` — Validation error / invalid state transition
- `403` — Plan / spending-limit / permission error

## Changes

- **2026-05-23** `b236bf76f9a7` — 2 info
  - added `#/components/schemas/SandboxRegion` to the `data/region` response property `allOf` list for the response status `201`
  - removed `#/components/schemas/RegionSummary` from the `data/region` response property `allOf` list for the response status `201`

[Change history](https://skmtc.dev/brimblehq/apis/brimble-sandbox-api/changes/volumes/post.md)

---

[API](https://skmtc.dev/brimblehq/apis/brimble-sandbox-api.md) · [All operations](https://skmtc.dev/brimblehq/apis/brimble-sandbox-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/brimblehq/brimble-sandbox-api/revisions/7fe2df041597/schema)