Preview file¶

Read the preview contents of a connector file or temporary file. You can upload local files first, or query the file list in the connector first.

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

Preparation before calling¶

Prepare a personal access token with access to the target workspace, the target workspace ID, and the temporary file ID, or connector ID and file URI. Reading connector files requires usage rights for the connector.

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 read, passed through the X-Workspace-ID Header.
$CONN_FILE_ID: The temporary file ID returned after uploading the file, passed through conn_file_id.
$CONNECTOR_ID and $FILE_URI: The connector ID and file uri obtained after querying the connector file list, passed through connector_id and uri.

Request example¶

Preview the temporary file just uploaded:

curl -X POST "https://moi.matrixorigin.cn/newmoi/connectors/file/preview" \
  -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\",
    \"rowStart\": 1,
    \"isColumnName\": true
  }"

Preview files in a saved connector:

curl -X POST "https://moi.matrixorigin.cn/newmoi/connectors/file/preview" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d "{
    \"connector_id\": \"$CONNECTOR_ID\",
    \"uri\": \"$FILE_URI\",
    \"rowStart\": 1,
    \"isColumnName\": true
  }"

Request body¶

Field	Type	Is it required	Description
`conn_file_id`	string	Required	Temporary file ID. This field will be used first when it is not empty. `connector_id` and `uri` will not participate in this preview.
`connector_id`	string or integer	Required	Connector ID. Only used when `conn_file_id` is empty; also pass `uri`.
`uri`	string	Required	Connector file URI. Only used when `conn_file_id` is empty; also pass `connector_id`.
`sheet_name`	string	No	The sheet name of the XLS or XLSX file.
`rowStart`	integer	No	The starting row of preview data; if `0`, it starts from the first row.
`columnNameRow`	integer	No	The row number used as the column name; only used when `isColumnName=true`.
`isColumnName`	boolean	No	Whether to use the row specified by `columnNameRow` as the column name.
`file_type`	integer	no	File type code. Greater than `0` overrides the type inferred from the filename or URI. The code meaning is the same as `type` in Query file list.
`csv`	object	No	CSV parsing configuration. Use commas to separate and double quotes when omitted.
`csv.separator`	string	No	Field separator, using the first byte of the string.
`csv.delimiter`	string	No	Field wrapper, using the first byte of the string; no wrapper is used when omitted.
`csv.isEscape`	boolean	No	Whether to use backslash as the escape character for the wrapper.

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

The request must provide a valid conn_file_id, or both connector_id and uri if conn_file_id is empty.

Successful response¶

Returns 200 on success.

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "conn_file_id": "conn_file_01",
    "file_type": 1,
    "rows": [
      {
        "number": 1,
        "columnName": "id",
        "columnValues": ["1", "2"],
        "charNumber": "1",
        "charColumnName": "A"
      }
    ],
    "sheets": [
      {
        "name": "Sheet1",
        "row_count": 2
      }
    ]
  }
}

The response fields are as follows.

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.conn_file_id`	string	ID of the temporary file being previewed. When using connector file preview, this ID is returned after the content is saved as a temporary file; available for download or deletion.
`data.file_type`	integer	File type code.
`data.rows`	object[]	Preview rows.
`data.rows[].number`	integer	Row number.
`data.rows[].columnName`	string	Column name.
`data.rows[].columnValues`	string[]	Preview values for the column.
`data.rows[].charNumber`	string	Character position identifier.
`data.rows[].charColumnName`	string	Column name for the character position.
`data.sheets`	object[]	Spreadsheet sheet; may be omitted for other file types.
`data.sheets[].name`	string	Worksheet name.
`data.sheets[].row_count`	integer	Worksheet row count.

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": "ErrNotFound",
  "msg": "file not found",
  "data": null
}

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`—`	The JSON request body cannot be parsed. The response uses the `error` field and does not use the standard `code` field.	Check JSON type and format and try again.
`404`	`ErrNotFound`	The temporary file or connector file does not exist.	Query the file again and confirm the file ID or URI.
`500`	`ErrServer`	The file location field was not provided, or the service failed to read, save, or parse the file.	Pass in a valid file location field; check the file format and try again.

Follow-up operations¶

After confirming that the preview rows and worksheet are as expected, if the response returns a temporary file ID, use that ID Create Task. When you need to get the file content, use this ID download file.

Last updated on Sep 3, 2026