Create volume¶

Create a root volume under the specified database.

POST https://moi.matrixorigin.cn/newmoi/catalog/volume/create

Preparation before calling¶

First query the database list to obtain the target database ID. Prepare the personal access token, target workspace ID, and database ID that have access to the target workspace.

The example below uses:

$AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.
$WORKSPACE_ID: Target workspace ID, passed through X-Workspace-ID Header.
$DATABASE_ID: The parent database ID under which the volume is to be created.

Request example¶

curl -X POST "https://moi.matrixorigin.cn/newmoi/catalog/volume/create" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "database_id": '"$DATABASE_ID"',
    "name": "<VOLUME_NAME>",
    "description": "<VOLUME_DESCRIPTION>"
  }'

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.

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

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¶

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

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 3, 2026