Upload files¶

Upload a local file and get a temporary file ID that can be previewed, downloaded, or used for subsequent imports. Uploading only saves temporary files and does not start the import task.

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

Preparation before calling¶

Use multipart/form-data request. The current public contract does not define a maximum file size limit for a single upload. 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: The workspace ID of the file to be uploaded, passed through the X-Workspace-ID Header.

Request example¶

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

Form fields¶

Field	Type	Is it required	Description
`files`	file[]	No	One or more files to upload. It is recommended to use `files`; the service will read all file fields in the multipart form. To get available temporary file IDs, pass in at least one file.

[] after a type denotes an array. [] in a field path denotes each item in an array.

Successful response¶

Returns 200 on success.

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "conn_file_ids": ["conn_file_01"],
    "file_ids": ["file_01"]
  }
}

The response fields are as follows.

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.conn_file_ids`	string[] or null	Temporary connector file IDs, returned in the order of uploaded files. `null` if no file is passed in.
`data.file_ids`	string[]	Stores file IDs, corresponding to `data.conn_file_ids` in the same order. May be omitted if no file is passed in.

In field paths, [] means each item in an array. For example, items[].name is the name field of each item in items.

Error response¶

{
  "code": "ErrParamInvalid",
  "msg": "invalid multipart form",
  "data": null
}

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`ErrParamInvalid`	Invalid multipart request.	Check the form format and file content and try again.
`401`	`ErrUnauthorized`	The access token is invalid or has expired.	Try again after updating the access token.
`403`	`ErrForbidden`	The caller does not have permission to upload files in this workspace.	Check workspace ID and access permissions.
`503`	`ErrServiceUnavailable`	The service is temporarily unable to store temporary files.	Keep the desensitization error message and try again.

Follow-up operations¶

Save the returned data.conn_file_ids. When you need to view the content, preview file; when you need to take out the file, download file. After confirming that it is useless, delete the file.

Last updated on Sep 3, 2026