Volumes
List the persistent volumes in an environment
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/volumes \ -H "Authorization: Bearer kc_your_api_token"[ { "id": "acct_01example0000000000000000x", "environmentId": "env_01example0000000000000000x", "serviceId": "svc_01example0000000000000000x", "name": "my-app", "mountPath": "example", "sizeGb": 0, "status": { "state": "ready", "location": "example", "currentSizeGb": 1, "usedBytes": 1, "commands": [ { "id": "acct_01example0000000000000000x", "kind": "expand", "status": "running", "startedAt": "2026-01-01T00:00:00.000Z", "completedAt": "2026-01-01T00:00:00.000Z", "error": "example", "detail": "example" } ] }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }]Get a persistent volume
The environment this volume belongs to.
The service mounting this volume; null when detached (an orphan).
Volume name, unique within the environment.
Path the volume is mounted at when attached.
Current volume size in GB.
Read-only: live disk state (provisioning/ready, actual size, usage).
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/volumes/:volumeId \ -H "Authorization: Bearer kc_your_api_token"{ "id": "acct_01example0000000000000000x", "environmentId": "env_01example0000000000000000x", "serviceId": "svc_01example0000000000000000x", "name": "my-app", "mountPath": "example", "sizeGb": 0, "status": { "state": "ready", "location": "example", "currentSizeGb": 1, "usedBytes": 1, "commands": [ { "id": "acct_01example0000000000000000x", "kind": "expand", "status": "running", "startedAt": "2026-01-01T00:00:00.000Z", "completedAt": "2026-01-01T00:00:00.000Z", "error": "example", "detail": "example" } ] }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z"}Destroy a detached (orphan) volume
Deletes a DETACHED volume and its data permanently. 409 if still attached (detach from its service first); 412 without confirmDataLoss.
Must be true to proceed: deleting a detached volume destroys its data permanently.
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/volumes/:volumeId \ -X DELETE \ -H "Authorization: Bearer kc_your_api_token" \ -H "Content-Type: application/json" \ -d '{ "confirmDataLoss": true }'Get a volume’s live state
The disk’s live lifecycle, actual size/usage, the location it is provisioned in, and which day-2 commands (expand/snapshot/restore) are currently in flight. The console gates the volume actions on this.
Live state of the attached disk: `ready` (bound + in use), `provisioning` (being created/attached), `repairing`, or `unknown`.
The location the volume is actually provisioned in (when provisioned).
Actual provisioned capacity in GiB, as the storage layer reports it live.
Bytes currently used on the disk.
Recent day-2 commands (newest first), persisted by Koo — live AND terminal state, so the console shows an in-progress or just-completed/failed operation even after a page reload.
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/volumes/:volumeId/status \ -H "Authorization: Bearer kc_your_api_token"{ "state": "ready", "location": "example", "currentSizeGb": 1, "usedBytes": 1, "commands": [ { "id": "acct_01example0000000000000000x", "kind": "expand", "status": "running", "startedAt": "2026-01-01T00:00:00.000Z", "completedAt": "2026-01-01T00:00:00.000Z", "error": "example", "detail": "example" } ]}Grow a persistent volume
Grow-only — a shrink is rejected (422). The mounting service’s spec is kept in sync.
New volume size in GB. Must be larger than the current size — volumes only grow.
The environment this volume belongs to.
The service mounting this volume; null when detached (an orphan).
Volume name, unique within the environment.
Path the volume is mounted at when attached.
Current volume size in GB.
Read-only: live disk state (provisioning/ready, actual size, usage).
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/volumes/:volumeId/expand \ -X POST \ -H "Authorization: Bearer kc_your_api_token" \ -H "Content-Type: application/json" \ -d '{ "sizeGb": 0 }'{ "id": "acct_01example0000000000000000x", "environmentId": "env_01example0000000000000000x", "serviceId": "svc_01example0000000000000000x", "name": "my-app", "mountPath": "example", "sizeGb": 0, "status": { "state": "ready", "location": "example", "currentSizeGb": 1, "usedBytes": 1, "commands": [ { "id": "acct_01example0000000000000000x", "kind": "expand", "status": "running", "startedAt": "2026-01-01T00:00:00.000Z", "completedAt": "2026-01-01T00:00:00.000Z", "error": "example", "detail": "example" } ] }, "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z"}List a volume’s snapshots (live storage state)
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/volumes/:volumeId/snapshots \ -H "Authorization: Bearer kc_your_api_token"[ { "name": "my-app", "id": "acct_01example0000000000000000x", "createdAt": "2026-01-01T00:00:00.000Z", "sizeGb": 1, "status": "creating" }]Take a manual snapshot of a volume
A timestamped name is generated when omitted.
Optional name for the snapshot. A timestamped name is generated when omitted.
Snapshot name — use it to restore or delete the snapshot.
Read-only snapshot identifier assigned by Koo’s storage layer.
When the snapshot was taken.
Snapshot size in GB.
Durable lifecycle (creating/ready/deleting); absent for a snapshot found only in live storage state (no Koo record).
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/volumes/:volumeId/snapshots \ -X POST \ -H "Authorization: Bearer kc_your_api_token" \ -H "Content-Type: application/json" \ -d '{}'{ "name": "my-app", "id": "acct_01example0000000000000000x", "createdAt": "2026-01-01T00:00:00.000Z", "sizeGb": 1, "status": "creating"}Restore a volume in place from a snapshot
Destructive — overwrites the volume’s current data with the snapshot’s. 412 without confirmDataLoss.
Snapshot name to restore.
Must be true to proceed: restoring overwrites the volume’s current data with the snapshot’s.
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/volumes/:volumeId/snapshots/:name/restore \ -X POST \ -H "Authorization: Bearer kc_your_api_token" \ -H "Content-Type: application/json" \ -d '{ "confirmDataLoss": true }'Delete a volume snapshot
Snapshot name to delete.
curl https://api.koo.io/accounts/:accountId/projects/:projectId/environments/:environmentId/volumes/:volumeId/snapshots/:name \ -X DELETE \ -H "Authorization: Bearer kc_your_api_token"