# Storage API

Source: https://docs.oiy.ai/docs/api/storage

Create, read, rename, expand, and delete independent volumes.



## Create [#create]

`POST /api/volumes` requires authentication and an idempotency key.

```json
{
  "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 [#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 [#update]

`PATCH /api/volumes/{id}` requires the current revision and an idempotency key.

```json
{ "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]

`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](/docs/storage) explains how service deletion affects each ownership mode.

## Response shapes and limits [#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.