# 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.

```text
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:

```bash
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:

```bash
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](list-files.md). |
| `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.

```json
{
  "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

```json
{
  "code": "ErrNotFound",
  "msg": "file not found",
  "data": null
}
```

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - 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](../import-tasks/create-import-task.md). When you need to get the file content, use this ID [download file](download-file.md).