Storage API
Create, read, rename, expand, and delete independent volumes.
Create
POST /api/volumes requires authentication and an idempotency key.
{
"name": "models",
"region": "economy",
"geography": "oceania",
"sizeGb": 100
}Creation provisions storage without starting compute. Valid sizes are 10–4,096 GB. Geography defaults to auto. The name accepts 1–64 characters.
Read
GET /api/volumes returns { "volumes": [...] }. GET /api/volumes/{id} returns { "volume": ... }.
Important fields include mode, serviceId, status, revision, sizeGb, requestedSizeGb, provisioned, hourlyMicros, and error. Check provisioned allocation separately from lifecycle readiness.
Update
PATCH /api/volumes/{id} requires the current revision and an idempotency key.
{ "revision": 1, "name": "checkpoints", "sizeGb": 200 }Use the real current revision. At least one of name or size must be provided. Expansion cannot shrink a volume. Pause an attached service first and wait for ready storage before starting it again.
Delete
DELETE /api/volumes/{id} requires an idempotency key. Only an unattached independent volume can be deleted directly. This removes its files: confirm ownership and keep a backup before issuing the request.
Storage behavior explains how service deletion affects each ownership mode.
Response shapes and limits
Create returns a bare Volume with HTTP 201. Update returns a bare Volume with HTTP 200. Individual reads use { "volume": ... }; listing uses { "volumes": [...] }.
Deletion returns volumeId, operationId, and status: "deleting". Confirm the resulting volume state afterward; the response is not proof that backing storage has already been released.
Accounts can retain up to 50 volumes. New independent storage and volume updates require verified email. Deletion remains subject to ownership and detachment checks.