Create folder¶

Create a folder under a volume or existing folder.

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

Preparation before calling¶

First query the object in the database to obtain the parent volume or parent folder ID. Prepare a personal access token with access to the target workspace, the target workspace ID, and the parent volume or parent folder ID.

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.
$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 example¶

curl -X POST "https://moi.matrixorigin.cn/newmoi/catalog/folder/create" \
  -H "X-API-Key: $AI_STUDIO_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>"
  }'

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.

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

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¶

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

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