Create folder¶

Create a folder under a volume or existing folder.

HTTP
POST $CLOUDSIGMA_API_BASE/catalog/folder/create

Before you call this API¶

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

First query the object in the database to obtain the parent volume or parent folder ID.

Set the operation-specific values used in the request:

$VOLUME_ID: Parent volume or parent folder ID; the service resolves this to the root volume.

The caller needs write access to the root volume.

Request¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/catalog/folder/create" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "parent_volume_id": '"$VOLUME_ID"',
    "database_id": '"$DATABASE_ID"',
    "name": "<FOLDER_NAME>",
    "description": "<FOLDER_DESCRIPTION>"
  }'

Parameter reference

Request body

Parameter	Type	Required	Description
`parent_volume_id`	integer	Yes	The parent volume or parent folder ID; the service resolves this to the root volume.
`database_id`	integer	Yes	Database ID.
`name`	string	Yes	Folder name, must be a valid identifier.
`description`	string	No	Folder description.

Successful response¶

Returns 200 and the new folder ID on success. The caller needs write access to the root volume and the parent database.

Response example

JSON
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "901"
  }
}

Field reference

The response fields are as follows.

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.id`	string	ID of the newly created folder, returned as a numeric string. When calling subsequent endpoints that require an integer ID, use this numeric value itself.

Error response¶

Response example

JSON
{
  "code": "ErrParamInvalid",
  "msg": "name 无效",
  "data": null
}

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`ErrParamInvalid`	`parent_volume_id`, `name` are missing, or have invalid names.	Check parent object ID and folder name.
`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.
`409`	`ErrReadonly`	The database where the target volume is located is not writable.	Select a writable volume.
`500`	`ErrServer`	The service cannot create the folder.	Record the request time and error message and try again; if it continues to fail, contact support.

Follow-up operations¶

Log data.id. Use this ID to Query Catalog details to confirm the saving result.

Last updated on Sep 15, 2026