Filespaces

Create and manage filespaces (storage volumes) within your workspace.

GET

/api/v1/filespaces

Returns a list of all filespaces in the workspace the service account belongs to.

Responses

Status	Description
`200`	List of filespaces has been successfully fetched.
`401`	Invalid or missing credentials.

200

Description: List of filespaces has been successfully fetched.

401

Description: Invalid or missing credentials.

200 response

{    "data": [        {            "id": "62ac906f-4522-41ee-a710-695f8a696a9d",            "workspaceId": "8dd7b88e-7f3e-4c52-ae06-3e902f428e6d",            "name": "my-filespace-name",            "storage": {                "owner": "lucidlink",                "provider": "AWS",                "region": "eu-west-1",                "endpoint": "https://s3.eu-west-1.amazonaws.com",                "bucketName": "lucid-fs-62ac906f-4522-41ee-a710-695f8a696a9d"            },            "currentStorageSize": 0,            "status": "ready",            "createdAt": "2025-09-03T12:47:29.261Z",            "updatedAt": "2025-09-03T12:50:49.368Z"        },        {            "id": "79a88257-b107-4cc8-9685-19bd5b08e159",            "workspaceId": "8dd7b88e-7f3e-4c52-ae06-3e902f428e6d",            "name": "my-second-filespace-name",            "storage": {                "owner": "lucidlink",                "provider": "AWS",                "region": "eu-west-1",                "endpoint": "https://s3.eu-west-1.amazonaws.com",                "bucketName": "lucid-fs-79a88257-b107-4cc8-9685-19bd5b08e159"            },            "currentStorageSize": 0,            "status": "ready",            "createdAt": "2025-09-03T12:40:24.886Z",            "updatedAt": "2025-09-03T12:41:26.704Z"        }    ]}

401 response

{    "error": {        "message": "Invalid or expired token"    }}

POST

/api/v1/filespaces

Create filespace.

Used to create filespace creation automations. There are 3 kinds of filespaces, based on storage provider and storage region, that can be created with this endpoint:

LucidLink provided storage
Customer provided storage, known storage provider and known region for provider
Customer provider storage, "Other" provider

To get valid providers and regions, use the /api/v1/providers endpoint in Swagger UI docs, or use the following curl command:

curl -i -X POST 'http://<api-hostname>/api/v1/providers' \    -H 'Authorization: Bearer sa_dev:N5tIXYPUFkxyVtV2fVuUJDQ0S+9LUYfS9/PgAGZ5g7I=:DivbcainTNtoYyKMDt8W2uHj7ldJ+gcK/sUun7uG' \    -H 'Content-Type: application/json'

Examples:

LucidLink provided storage

curl -i -X POST 'http://<api-hostname>/api/v1/filespaces' \    -H 'Authorization: Bearer sa_dev:N5tIXYPUFkxyVtV2fVuUJDQ0S+9LUYfS9/PgAGZ5g7I=:DivbcainTNtoYyKMDt8W2uHj7ldJ+gcK/sUun7uG' \    -H 'Content-Type: application/json' \    -d '{        "name": "my-filespace-name",        "region": "eu-west-1",        "storageOwner": "lucidlink",        "storageProvider": "AWS",        "blockSize": 1024    }'

Customer provider storage from known storage provider

curl -i -X POST 'http://<api-hostname>/api/v1/filespaces' \    -H 'Authorization: Bearer sa_dev:N5tIXYPUFkxyVtV2fVuUJDQ0S+9LUYfS9/PgAGZ5g7I=:DivbcainTNtoYyKMDt8W2uHj7ldJ+gcK/sUun7uG' \    -H 'Content-Type: application/json' \    -d '{        "name": "my-filespace-name",        "region": "eu-west-1",        "storageOwner": "customer",        "storageProvider": "AWS",        "customerStorageParams": {            "endpoint": "http://minio:9090",            "accessKeyId": "valueForAccessKey",            "secretAccessKey": "valueForSecretKey",            "bucketName": "some-bucket-name"        },        "blockSize": 1024    }'

Customer provider storage from known Other provider

curl -i -X POST 'http://<api-hostname>/api/v1/filespaces' \    -H 'Authorization: Bearer sa_dev:N5tIXYPUFkxyVtV2fVuUJDQ0S+9LUYfS9/PgAGZ5g7I=:DivbcainTNtoYyKMDt8W2uHj7ldJ+gcK/sUun7uG' \    -H 'Content-Type: application/json' \    -d '{        "name": "my-filespace-name",        "region": "other-region",        "storageOwner": "customer",        "storageProvider": "Other",        "customerStorageParams": {            "endpoint": "http://minio:9090",            "accessKeyId": "valueForAccessKey",            "secretAccessKey": "valueForSecretKey",            "bucketName": "some-bucket-name"        },        "blockSize": 1024    }'

Request body

Field	Type	Description
`name`	`string`	Required. Name of the filespace. Filespace name can contain only lowercase letters, numbers and dashes. It cannot start or end with a dash.
`region`	`string`	Required. Region for the given storageProvider. Can be a known region from /api/v1/providers, or it can be an unknown region to LucidLink, but supported by the provider.
`storageProvider`	`string`	Required. If storageOwner is LucidLink, this must always be 'AWS'. Otherwise it's a known provider from /api/v1/providers. The Other provider is special as it denotes custom S3 providers unknown to LucidLink.
`storageOwner`	`StorageOwner`	Required. Storage owner can be 'lucidlink', when the user wants LucidLink to provide S3 storage, or it can be 'customer' when we want the customer to specify a custom storage provider.
`customerStorageParams`	`CustomerStorageParamsDto`	Required when storageOwner is set to 'customer'
`blockSize`	`number`	Default for AWS storage provided by LucidLink and customer storage provided by BackBlaze is 1024, otherwise it is 256

name

Type: string
Description: Required. Name of the filespace. Filespace name can contain only lowercase letters, numbers and dashes. It cannot start or end with a dash.

region

Type: string
Description: Required. Region for the given storageProvider. Can be a known region from /api/v1/providers, or it can be an unknown region to LucidLink, but supported by the provider.

storageProvider

Type: string
Description: Required. If storageOwner is LucidLink, this must always be 'AWS'. Otherwise it's a known provider from /api/v1/providers. The Other provider is special as it denotes custom S3 providers unknown to LucidLink.

storageOwner

Type: StorageOwner
Description: Required. Storage owner can be 'lucidlink', when the user wants LucidLink to provide S3 storage, or it can be 'customer' when we want the customer to specify a custom storage provider.

customerStorageParams

Type: CustomerStorageParamsDto
Description: Required when storageOwner is set to 'customer'

blockSize

Type: number
Description: Default for AWS storage provided by LucidLink and customer storage provided by BackBlaze is 1024, otherwise it is 256

Responses

Status	Description
`201`	Filespace has been been successfully created.
`400`	FilespaceCreateDto is invalid.
`401`	Invalid or missing credentials.
`503`	We are currently deploying an improvement, so this action is paused for a moment. Wait until the deployment is finished. It typically takes around 10 minutes, and we are almost there.

201

Description: Filespace has been been successfully created.

400

Description: FilespaceCreateDto is invalid.

401

Description: Invalid or missing credentials.

503

Description: We are currently deploying an improvement, so this action is paused for a moment. Wait until the deployment is finished. It typically takes around 10 minutes, and we are almost there.

201 response

{    "data": {        "id": "62ac906f-4522-41ee-a710-695f8a696a9d",        "workspaceId": "8dd7b88e-7f3e-4c52-ae06-3e902f428e6d",        "name": "my-filespace-name",        "storage": {            "owner": "lucidlink",            "provider": "AWS",            "region": "eu-west-1",            "endpoint": "https://s3.eu-west-1.amazonaws.com",            "bucketName": "lucid-fs-62ac906f-4522-41ee-a710-695f8a696a9d"        },        "currentStorageSize": 0,        "status": "ready",        "createdAt": "2025-09-03T12:47:29.261Z",        "updatedAt": "2025-09-03T12:50:49.368Z"    }}

400 response

{    "error": {        "message": "Filespace name can contain only alphanumeric characters and dash"    }}

401 response

{    "error": {        "message": "Invalid or expired token"    }}

503 response

{    "error": {        "message": "We are currently deploying an improvement, so this action is paused for a moment. Retry after the delay in the Retry-After header."    }}

GET

/api/v1/filespaces/{filespaceId}

Returns information for a single filespace, including storage configuration and current status.

Parameters

Parameter	Type	Description
`filespaceId`	`string`	Required.

filespaceId

Type: string
Description: Required.

Responses

Status	Description
`200`	Filespace has been successfully fetched.
`401`	Invalid or missing credentials.
`404`	Filespace does not exist.

200

Description: Filespace has been successfully fetched.

401

Description: Invalid or missing credentials.

404

Description: Filespace does not exist.

200 response

{    "data": {        "id": "62ac906f-4522-41ee-a710-695f8a696a9d",        "workspaceId": "8dd7b88e-7f3e-4c52-ae06-3e902f428e6d",        "name": "my-filespace-name",        "storage": {            "owner": "lucidlink",            "provider": "AWS",            "region": "eu-west-1",            "endpoint": "https://s3.eu-west-1.amazonaws.com",            "bucketName": "lucid-fs-62ac906f-4522-41ee-a710-695f8a696a9d"        },        "currentStorageSize": 0,        "status": "ready",        "createdAt": "2025-09-03T12:47:29.261Z",        "updatedAt": "2025-09-03T12:50:49.368Z"    }}

401 response

{    "error": {        "message": "Invalid or expired token"    }}

404 response

{    "error": {        "message": "Resource not found or user has no access privilege"    }}

PATCH

/api/v1/filespaces/{filespaceId}

Updates a filespace name. The new name must be 2–30 characters, lowercase alphanumeric and hyphens only, and cannot start or end with a hyphen.

Parameters

Parameter	Type	Description
`filespaceId`	`string`	Required.

filespaceId

Type: string
Description: Required.

Request body

Field	Type	Description
`name`	`string`	Name of the filespace. Filespace name can contain only lowercase letters, numbers and dashes. It cannot start or end with a dash.

name

Type: string
Description: Name of the filespace. Filespace name can contain only lowercase letters, numbers and dashes. It cannot start or end with a dash.

Responses

Status	Description
`200`	Filespace name has been successfully updated.
`400`	FilespaceUpdateDto is invalid.
`401`	Invalid or missing credentials.
`404`	Filespace does not exist.

200

Description: Filespace name has been successfully updated.

400

Description: FilespaceUpdateDto is invalid.

401

Description: Invalid or missing credentials.

404

Description: Filespace does not exist.

200 response

{    "data": {        "id": "62ac906f-4522-41ee-a710-695f8a696a9d",        "workspaceId": "8dd7b88e-7f3e-4c52-ae06-3e902f428e6d",        "name": "my-filespace-name",        "storage": {            "owner": "lucidlink",            "provider": "AWS",            "region": "eu-west-1",            "endpoint": "https://s3.eu-west-1.amazonaws.com",            "bucketName": "lucid-fs-62ac906f-4522-41ee-a710-695f8a696a9d"        },        "currentStorageSize": 0,        "status": "ready",        "createdAt": "2025-09-03T12:47:29.261Z",        "updatedAt": "2025-09-03T12:50:49.368Z"    }}

400 response

{    "error": {        "message": "Filespace name can contain only alphanumeric characters and dash"    }}

401 response

{    "error": {        "message": "Invalid or expired token"    }}

404 response

{    "error": {        "message": "Resource not found or user has no access privilege"    }}

DELETE

/api/v1/filespaces/{filespaceId}

Permanently deletes a filespace and all its data. This action cannot be undone.

Parameters

Parameter	Type	Description
`filespaceId`	`string`	Required.

filespaceId

Type: string
Description: Required.

Responses

Status	Description
`200`	Filespace successfully deleted.
`401`	Invalid or missing credentials.
`404`	Filespace does not exist.
`503`	We are currently deploying an improvement, so this action is paused for a moment. Wait until the deployment is finished. It typically takes around 10 minutes, and we are almost there.

200

Description: Filespace successfully deleted.

401

Description: Invalid or missing credentials.

404

Description: Filespace does not exist.

503

Description: We are currently deploying an improvement, so this action is paused for a moment. Wait until the deployment is finished. It typically takes around 10 minutes, and we are almost there.

401 response

{    "error": {        "message": "Invalid or expired token"    }}

404 response

{    "error": {        "message": "Resource not found or user has no access privilege"    }}

503 response

{    "error": {        "message": "We are currently deploying an improvement, so this action is paused for a moment. Retry after the delay in the Retry-After header."    }}