Download file¶

Get the download address of the temporary file. This interface only returns the download path, not the file content.

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

Preparation before calling¶

Prepare a personal access token that has access to the target workspace, the target workspace ID, and the temporary file ID.

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 downloaded, passed through the X-Workspace-ID Header.
$CONN_FILE_ID: Temporary file ID obtained after uploading or previewing, passed through conn_file_id.
$DOWNLOAD_PATH: The relative download path returned by this interface, used for subsequent download file streams.

Request example¶

curl -X POST "https://moi.matrixorigin.cn/newmoi/connectors/file/download" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d "{
    \"conn_file_id\": \"$CONN_FILE_ID\"
  }"

Request body¶

Field	Type	Is it required	Description
`conn_file_id`	string	Yes	The ID of the temporary file to download.

Successful response¶

On success, 200 and the relative download path are returned, but the file content is not returned.

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "url": "/newmoi/connectors/file/stream?conn_file_id=conn_file_01"
  }
}

The response fields are as follows.

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.url`	string	Relative download path, not file content. Use `https://moi.matrixorigin.cn` and this path to form the file stream request address.

Use the returned path to download the file stream and carry the same authentication request header as this interface:

curl -L "https://moi.matrixorigin.cn$DOWNLOAD_PATH" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -o ./downloaded-file

Error response¶

{
  "code": "ErrParamInvalid",
  "msg": "invalid file identifier",
  "data": null
}

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`200`	`ErrParamInvalid`	The JSON request body is invalid; the interface returns this type of error in this status.	Check the HTTP status and `code` at the same time, and then correct the request body.
`404`	`ErrNotFound`	`conn_file_id` is empty or the temporary file does not exist.	Reupload the file, or confirm the temporary file ID.
`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 access the temporary file.	Check workspace ID and access permissions.
`503`	`ErrServiceUnavailable`	The service is temporarily unable to generate a download path.	Keep the desensitization error message and try again.

Follow-up operations¶

When the temporary file is no longer needed, use conn_file_id to delete the file.

Last updated on Sep 3, 2026