Preview file¶

Preview files as inline content.

HTTP
POST $CLOUDSIGMA_API_BASE/catalog/file/preview_stream

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First query the file list to obtain the target file ID.

Set the operation-specific values used in the request:

$FILE_ID: File ID to preview.
$VOLUME_ID: The data volume ID where the target file is located.

The caller requires read access to the root volume.

Request¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/catalog/file/preview_stream" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "volume_id": "'"$VOLUME_ID"'",
    "file_id": "'"$FILE_ID"'"
  }'

Parameter reference

Request body

Parameter	Type	Required	Description
`file_id`	string	Yes	File ID.
`volume_id`	string	Yes	The ID of the data volume where the file is located.

Successful response¶

On success, 200 is returned, the response body is the file content, and Content-Disposition: inline is used. The caller requires read access to the root volume.

The response is not a JSON envelope. Content type of the service settings file; application/octet-stream is used when not provided. If a filename is available, the response header also contains Content-Disposition: inline.

Response items	Description
HTTP status code	`200`.
`Content-Type`	File MIME type; `application/octet-stream` when not provided.
`Content-Disposition`	Displayed inline when filename is available.
Response body	File binary content.

Error response¶

When the preview fails before starting, the response uses a JSON error envelope:

Response example

JSON
{
  "code": "ErrNotFound",
  "msg": "对象不存在",
  "data": null
}

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`ErrParamInvalid`	`file_id` is missing or the request body is invalid.	Pass in a valid file ID.
`403`	`ErrForbidden`	The current identity does not have read permission on the root volume to which it belongs.	Use credentials with read access, or contact your administrator for authorization.
`404`	`ErrNotFound`	File does not exist.	Check file ID.
`500`	`ErrServer`	The service cannot open the file preview stream.	Record the request time and error message and try again; if it continues to fail, contact support.

Follow-up operations¶

After completion, Query Catalog details confirms the result.

Last updated on Sep 15, 2026