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.

HTTP
POST $CLOUDSIGMA_API_BASE/connectors/file/preview

Before you call this API¶

Configure the regional API endpoint and authentication, 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¶

Input examples

Preview the temporary file just uploaded:

Shell
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
  }"

Shell
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
  }"

Preview files in a saved connector:

Parameter reference

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.

Response example

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
      }
    ]
  }
}

Field reference

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¶

Response example

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

Field reference

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 15, 2026