# 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 $CLOUDSIGMA_API_BASE/connectors/file/preview ``` ## Before you call this API Configure the [regional API endpoint and authentication](https://omnifabric.cloudsigma.com/docs/developer/endpoints-and-authentication.html.md), and select the target workspace. Reading connector files requires usage rights for the connector. Set the operation-specific values used in the request: - `$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 "$CLOUDSIGMA_API_BASE/connectors/file/preview" \ -H "X-API-Key: $CLOUDSIGMA_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 "$CLOUDSIGMA_API_BASE/connectors/file/preview" \ -H "X-API-Key: $CLOUDSIGMA_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](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/data-connections/connector-files/list-files.html.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](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/data-connections/import-tasks/create-import-task.html.md). When you need to get the file content, use this ID [download file](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/data-connections/connector-files/download-file.html.md).