Dereference file¶

Dereference a set of files. All files must belong to the same root volume.

HTTP
POST $CLOUDSIGMA_API_BASE/catalog/file/delete_ref

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First query the file list to obtain the file ID to be dereferenced.

Set the operation-specific values used in the request:

$FILE_ID: The file ID to be dereferenced.

All files must belong to the same root volume.

Request¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/catalog/file/delete_ref" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "file_ids": ["'"$FILE_ID"'"]
  }'

Parameter reference

Request body

Parameter	Type	Required	Description
`file_ids`	array[string]	Yes	One or more file IDs to dereference.
`volume_id`	integer	No	The declaration must be consistent with the resolved root volume.

Successful response¶

Returns 200 on success, data is null. This operation disassociates the file from the volume and does not mean deleting the file itself.

Response example

JSON
{
  "code": "OK",
  "msg": "OK",
  "data": null
}

Field reference

The response fields are as follows.

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data`	null	Fixed to `null` when the association is successful.

Error response¶

Response example

JSON
{
  "code": "ErrParamInvalid",
  "msg": "文件必须属于同一根卷",
  "data": null
}

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`ErrParamInvalid`	`file_ids` is empty, contains an invalid ID, conflicts with `volume_id`, or the file does not belong to the same root volume.	Pass in a valid file ID from the same root volume.
`403`	`ErrForbidden`	The current identity does not have write permissions to the root volume.	Use credentials with write access, or contact your administrator for authorization.
`404`	`ErrNotFound`	A file does not exist.	Check all file IDs.
`409`	`ErrReadonly`	The destination volume is not writable.	Select a writable volume.
`500`	`ErrServer`	The service cannot disassociate the file.	Record the request time and error message and try again; if it continues to fail, contact support.

Follow-up operations¶

After completion, Query Catalog details confirms the result.

Last updated on Sep 15, 2026