Volumes

Create, manage, and share persistent storage volumes. Volumes provide durable storage for workspaces and can be attached to multiple workspaces within a project.

All endpoints require authentication via X-API-Key header and the appropriate scope.

---

Volume Object

{
  "id": "vol_def001",
  "label": "Training Data",
  "name": "training-data",
  "description": "Dataset for ML model training",
  "status": "bound",
  "type": "data",
  "volumeType": "persistent",
  "sizeGb": 64,
  "mountPath": "/data/training",
  "organizationId": "org_xyz",
  "owner": {
    "id": "user_456",
    "name": "Jane Smith",
    "email": "jane@example.com"
  },
  "ownerId": "user_456",
  "projectId": "proj_abc123",
  "isShared": false,
  "shared": false,
  "sharedWith": [],
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-02-01T14:22:00Z"
}

---

GET /api/v1/volumes

List all volumes accessible to the authenticated user.

Scope: volumes:read

Query Parameters

Parameter	Type	Required	Description
search	string	No	Search by label, name, or description
type	string	No	Filter by type: data, model, workspace, shared
projectId	string	No	Filter by project ID
limit	integer	No	Number of results to return (default: 20)
offset	integer	No	Number of results to skip (default: 0)
sort	string	No	Sort field and direction, e.g. createdAt:desc

Response 200 OK

{
  "count": 6,
  "limit": 20,
  "offset": 0,
  "volumes": [
    {
      "id": "vol_def001",
      "label": "Training Data",
      "name": "training-data",
      "description": "Dataset for ML model training",
      "status": "bound",
      "type": "data",
      "volumeType": "persistent",
      "sizeGb": 64,
      "mountPath": "/data/training",
      "organizationId": "org_xyz",
      "ownerId": "user_456",
      "projectId": "proj_abc123",
      "isShared": false,
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-02-01T14:22:00Z"
    }
  ]
}

---

POST /api/v1/volumes

Create a new volume.

Scope: volumes:write

Request Body

{
  "projectId": "proj_abc123",
  "label": "Training Data",
  "sizeGB": 64,
  "description": "Dataset for ML model training",
  "type": "data",
  "mountPath": "/data/training"
}

Field	Type	Required	Description
projectId	string	Yes	Project to attach the volume to
label	string	Yes	Human-readable label for the volume
sizeGB	integer	Yes	Volume size in gigabytes
description	string	No	Volume description
type	string	No	Volume type: data, model, workspace (default: data)
mountPath	string	No	Mount path inside workspaces (default: /data/<label-slug>)

Response 201 Created

{
  "volumeId": "vol_def001"
}

---

GET /api/v1/volumes/:id

Get a single volume by ID.

Scope: volumes:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Volume ID

Response 200 OK

Returns the full Volume object.

---

PUT /api/v1/volumes/:id

Update an existing volume. Protected fields (_id, owner, createdAt, organizationId) cannot be overwritten.

Scope: volumes:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Volume ID

Request Body

{
  "label": "Updated Training Data",
  "description": "Updated description",
  "mountPath": "/data/updated-training"
}

Field	Type	Required	Description
label	string	No	Human-readable label
description	string	No	Volume description
mountPath	string	No	Mount path inside workspaces

Response 200 OK

Returns the updated Volume object.

---

DELETE /api/v1/volumes/:id

Delete a volume. The volume must not be attached to any running workspace. This action is irreversible.

Scope: volumes:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Volume ID

Response 204 No Content

---

POST /api/v1/volumes/:id/sync

Sync volume contents to S3. Creates a backup of the volume data in the organization's configured S3 bucket.

Scope: volumes:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Volume ID

Response 200 OK

{
  "message": "Volume sync to S3 initiated",
  "volumeId": "vol_def001",
  "syncJobId": "sync_abc001"
}

---

POST /api/v1/volumes/:id/make-shared

Make a volume shared across the organization. Once shared, the volume becomes read-accessible to all organization members.

Scope: volumes:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Volume ID

Response 200 OK

{
  "message": "Volume is now shared",
  "volumeId": "vol_def001",
  "isShared": true
}

---

GET /api/v1/volumes/shared

List all shared volumes available within the organization.

Scope: volumes:read

Query Parameters

Parameter	Type	Required	Description
search	string	No	Search by label, name, or description
limit	integer	No	Number of results to return (default: 20)
offset	integer	No	Number of results to skip (default: 0)
sort	string	No	Sort field and direction, e.g. createdAt:desc

Response 200 OK

{
  "count": 3,
  "limit": 20,
  "offset": 0,
  "volumes": [
    {
      "id": "vol_shared001",
      "label": "Common Datasets",
      "name": "common-datasets",
      "description": "Shared datasets for the organization",
      "status": "bound",
      "type": "data",
      "sizeGb": 256,
      "organizationId": "org_xyz",
      "ownerId": "user_456",
      "isShared": true,
      "createdAt": "2025-01-10T08:00:00Z",
      "updatedAt": "2025-01-28T16:30:00Z"
    }
  ]
}