Upload files¶

Upload a file that is not associated with a volume. Once uploaded, it can be associated to the volume via Create file.

POST https://moi.matrixorigin.cn/newmoi/catalog/file/upload

Preparation before calling¶

Use multipart/form-data request. Prepare a personal access token and target workspace ID that has 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.

Request example¶

curl -X POST "https://moi.matrixorigin.cn/newmoi/catalog/file/upload" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -F "file=@./orders.csv"

Form fields¶

Field	Type	Required	Description
`file`	file	Yes	The local file to upload.

Successful response¶

Returns 200 and file_id on success. This request only uploads the file and does not associate it with a volume.

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "file_id": "file-123"
  }
}

The response fields are as follows.

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.file_id`	string	File ID generated after upload; can be used for Create file request.

Error response¶

{
  "code": "ErrParamInvalid",
  "msg": "缺少 file 字段",
  "data": null
}

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`ErrParamInvalid`	`file` field is missing from multipart request.	Resubmit using `-F "file=@<本地文件>"`.
`403`	`ErrForbidden`	The current identity does not have upload permission.	Use credentials with upload permissions, or contact the administrator for authorization.
`500`	`ErrServer`	The service cannot save the uploaded content.	Keep the desensitized response information and try again; if it continues to fail, contact support personnel.

Follow-up operations¶

Use data.file_id [create-file.md] to associate the file to the volume.

Last updated on Sep 3, 2026