Create volume¶

Create a root volume under the specified database.

HTTP
POST $CLOUDSIGMA_API_BASE/catalog/volume/create

Before you call this API¶

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

First query the database list to obtain the target database ID.

Set the operation-specific values used in the request:

$DATABASE_ID: The parent database ID under which the volume is to be created.

Request¶

Input examples

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

Parameter reference

Request body

Parameter	Type	Required	Description
`database_id`	integer	Yes	The parent database ID.
`name`	string	Yes	Volume name, must be a valid identifier.
`description`	string	No	Volume description.

Successful response¶

Returns 200 and the new volume ID on success. This response indicates that the volume has been created.

Response example

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

Field reference

The response fields are as follows.

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.id`	integer	ID of the new volume.

Error response¶

Response example

JSON
{
  "code": "ErrAlreadyExists",
  "msg": "对象已存在",
  "data": null
}

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`ErrParamInvalid`	`database_id`, `name` are missing or the volume name is invalid.	Check the target database ID and volume name.
`403`	`ErrForbidden`	The current identity does not have permission to create volumes in the target database.	Use credentials with write access, or contact your administrator for authorization.
`409`	`ErrReadonlySystemDatabase`、`ErrReadonlyReservedDatabase`	The target database is not writable.	Select a writable database.
`409`	`ErrAlreadyExists`	A volume with the same name already exists in the target database.	Use a different volume name.
`500`	`ErrServer`	The service cannot create the volume.	Record the request time and error message and try again; if it continues to fail, contact support.

Follow-up operations¶

Use data.id Query volume details.

Last updated on Sep 15, 2026