Xeonr Developer Docs
API Specificationcontainers.api.v1.VolumeService

Create Volume

POST
/containers.api.v1.VolumeService/CreateVolume

Creates a volume record in PENDING state; the image and its node are chosen when the first workload mounting it is scheduled. tier is required. size_mb must be 64 MiB-512 GiB. A cache volume requires a cache_key (AlreadyExists if the key is taken in the namespace) and cannot be seeded; a scratch volume takes neither a cache key nor a seed; seed_snapshot_id is for persistent volumes. Workload-scoped agent keys are refused.

Access: operator or admin role in the namespace (via Xeonr team role or a namespace API key), or a platform admin.

Authorization

BearerAuth
AuthorizationBearer <token>

A namespace-scoped API key (cpk_…) for machines, or a Xeonr Auth OIDC token for humans. The key's namespace and role are pinned server-side.

In: header

Header Parameters

Connect-Protocol-Version?number

Define the version of the Connect protocol

Connect-Timeout-Ms?number

Define the timeout, in ms

Request Body

application/json

namespace?string
Lengthlength <= 64
tier?not unknown

Required: UNSPECIFIED is refused. enum.defined_only = true

Value in"VOLUME_TIER_UNSPECIFIED" | "VOLUME_TIER_SCRATCH" | "VOLUME_TIER_CACHE" | "VOLUME_TIER_PERSISTENT"
sizeMb?string

64 MiB (an empty ext4 filesystem) to 512 GiB.

Formatint64
Range64 <= value <= 524288
label?string
Lengthlength <= 4096
cacheKey?string

Required for VOLUME_TIER_CACHE, rejected otherwise.

Lengthlength <= 255
seedSnapshotId?string

Populate from this snapshot at creation. Persistent tier only.

Lengthlength <= 128
[key: string]?never

Response Body

application/json

application/json

curl -X POST "https://containers.xeonr.io/containers.api.v1.VolumeService/CreateVolume" \  -H "Connect-Protocol-Version: 1" \  -H "Connect-Timeout-Ms: 1000" \  -H "Content-Type: application/json" \  -d '{}'
{
  "volume": {
    "volumeId": "string",
    "namespace": "string",
    "tier": "VOLUME_TIER_UNSPECIFIED",
    "state": "VOLUME_STATE_UNSPECIFIED",
    "label": "string",
    "cacheKey": "string",
    "sizeMb": "string",
    "usedBytes": "string",
    "node": "string",
    "createdAtUnix": "string",
    "archivedAtUnix": "string",
    "archiveSnapshotId": "string",
    "seedSnapshotId": "string",
    "mountedBy": "string",
    "pendingSeedSnapshotId": "string",
    "lastArchiveDurationMs": 0
  }
}
{
  "code": "not_found",
  "message": "string",
  "details": [
    {
      "type": "string",
      "value": "string",
      "debug": {}
    }
  ]
}

Archive Volume POST

Copies a persistent volume's current contents into the workspace store as a snapshot and returns its id. Only persistent volumes can be archived. `label` defaults to "archive of <volume_id>". Returns Unimplemented when no workspace store is configured. Returns FailedPrecondition if the volume has never been mounted (its node is not known yet) or its node is unreachable, and Unimplemented when the volume file API is not configured. **Access:** any role in the volume's namespace, or a platform admin.

Delete Volume POST

Releases the volume's claim and deletes its record. A mounted volume is refused with FailedPrecondition unless `force` is set. Workload-scoped agent keys are refused. **Access:** operator or admin role in the volume's namespace, or a platform admin.