Block Volumes API (coming soon)

Preview the staged block-volume endpoints and attachment contract. Production creation and metering are disabled today.

The staged API contract covers creating a volume, checking its status, growing it, and attaching or detaching it at an app mount path. For the dashboard flow and product concepts (attach rules, durability, pricing), see Block volumes.

Production feature disabled

These endpoints document a staged interface. Production creation currently returns BLOCK_VOLUME_DISABLED; block-volume metering is also disabled.

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Human-friendly name; a DNS-safe slug is derived from it and used as the PVC's name (and the pvc_name an attach targets).

display_name?string

Optional; defaults to the trimmed name when omitted.

size_gb*integer

Booked capacity in GiB — the billable unit (block_volume rate).

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/volumes" \  -H "Content-Type: application/json" \  -d '{    "name": "data",    "size_gb": 1  }'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "display_name": "string",
  "size_gb": 0,
  "storage_class": "block-durable",
  "access_mode": "ReadWriteOnce",
  "status": "provisioning",
  "status_reason": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/volumes"

{
  "volumes": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
      "name": "string",
      "display_name": "string",
      "size_gb": 0,
      "storage_class": "block-durable",
      "access_mode": "ReadWriteOnce",
      "status": "provisioning",
      "status_reason": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "attached": true
    }
  ]
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

volumeId*string

UUID of the volume service.

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/volumes/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "display_name": "string",
  "size_gb": 0,
  "storage_class": "block-durable",
  "access_mode": "ReadWriteOnce",
  "status": "provisioning",
  "status_reason": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "attachment": {
    "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",
    "mount_path": "string",
    "read_only": true
  }
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

volumeId*string

UUID of the volume service.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

size_gb*integer

The new booked capacity in GiB. Must be >= the volume's current size — PVC expansion is grow-only.

Response Body

`application/json`

curl -X PATCH "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/volumes/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "size_gb": 1  }'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "name": "string",
  "display_name": "string",
  "size_gb": 0,
  "storage_class": "block-durable",
  "access_mode": "ReadWriteOnce",
  "status": "provisioning",
  "status_reason": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

volumeId*string

UUID of the volume service.

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/volumes/497f6eca-6276-4993-bfeb-53cbbbba6f08"

Empty

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

volumeId*string

UUID of the volume service.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

container_id*string

UUID of the container/web/worker service to mount the volume into.

mount_path*string

Absolute filesystem path inside the container.

read_only?boolean

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/volumes/497f6eca-6276-4993-bfeb-53cbbbba6f08/attach" \  -H "Content-Type: application/json" \  -d '{    "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",    "mount_path": "/data"  }'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "volume_id": "f17547b0-76cd-4153-92b9-a7d38dac0aba",
  "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",
  "mount_path": "string",
  "read_only": true,
  "created_at": "2019-08-24T14:15:22Z"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

volumeId*string

UUID of the volume service.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

container_id*string

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/volumes/497f6eca-6276-4993-bfeb-53cbbbba6f08/detach" \  -H "Content-Type: application/json" \  -d '{    "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa"  }'

Empty

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Empty

Errors use a code and a message

Every failed request returns a JSON body of the shape { "code": "...", "message": "..." }. Codes you will see on these endpoints: 401 UNAUTHORIZED; 403 BLOCK_VOLUME_DISABLED (create only — block volumes are not yet enabled on the platform); 409 PROJECT_SUSPENDED (the project itself is suspended); 402 INSUFFICIENT_BALANCE or 403 ACCOUNT_SUSPENDED (your billing account has no funds, or is suspended) on create, and on a resize that grows the size — a same-size resize is never billing-gated; 404 NOT_FOUND (a volume or container you do not own reads as not found, never leaked); 409 INSUFFICIENT_CAPACITY on create or a resize that grows past what your account can book; 400 SHRINK_NOT_SUPPORTED on a resize below the current size; and, on attach, 409 RWO_REPLICA_LIMIT, 409 VOLUME_ALREADY_ATTACHED, 409 ALREADY_ATTACHED, or 409 MOUNT_PATH_IN_USE.

Staged create and readiness flow

After the feature is enabled, POST .../volumes is designed to return immediately with status: "provisioning" while the disk provisions asynchronously. The client then polls GET .../volumes/{volumeId} until status is "running". A new volume carries no attachment until attach is called.

Staged attach and detach

The staged contract makes POST .../volumes/{volumeId}/attach mount the volume's disk into a target container/web/worker service at mount_path and restart that service. The ReadWriteOnce rule is enforced server-side:

A volume may be attached to at most one consumer service at a time (409 VOLUME_ALREADY_ATTACHED if you try a second one).
The target service must be running at most 1 replica (409 RWO_REPLICA_LIMIT otherwise).
The target service cannot already have a different volume mounted at the same mount_path (409 MOUNT_PATH_IN_USE).

In that contract, POST .../volumes/{volumeId}/detach removes the mount and restarts the consumer. The volume itself is left untouched — it can be attached elsewhere, or deleted once nothing has it mounted (DELETE .../volumes/{volumeId} returns 409 VOLUME_ATTACHED while any attachment still exists).

Staged resize is grow-only

The staged PATCH .../volumes/{volumeId} accepts a new size_gb that must be greater than or equal to the volume's current size. A smaller value is rejected with 400 SHRINK_NOT_SUPPORTED before the capacity gate is consulted — the underlying storage layer only supports expanding a live disk, never shrinking it.

Full reference: Block volumes.

Block Volumes API (coming soon)

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

200application/json

401application/json

404application/json

200application/json

401application/json

404application/json

200application/json

400application/json

401application/json

404application/json

409application/json

204

401application/json

404application/json

409application/json

201application/json

400application/json

401application/json

404application/json

409application/json

204

400application/json

401application/json

404

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`