Create viewer session - Cloudreve API Docs

Request

Authorization

Add the parameter

Authorization

to Headers，whose value is to concatenate the Token after the Bearer.

Example:

Authorization: Bearer ********************

Header Params

X-Cr-Purchase-Ticket

string

optional

Can be used to authenticate to paid share links with a anonymous identity. The ticket value can be obtained after an anonymous user purchase a paid share link.

Example:

1f63aa26-edc0-40ce-950a-cb4d4323158e

Body Params application/json

uri

string

required

URI of the target file.

Example:

cloudreve://JbVTn@share/1.docx

version

string | null

optional

Desired version ID to open. Empty value indicating the current version.

Example:

zOe1D

viewer_id

string

required

ID of the file apps. List of available file apps can be get from file_viewers in Get site settings under explorer section.

Example:

af01b85b-f57d-46d2-8ad6-1d9b96548e78

preferred_action

enum<string>

required

Preferred action for this session.

Allowed values:

editview

parent_uri

string | null

optional

URI of the parent folder where the file is located.
Usualy it can be calculated from uri field. But for single-file symbolic links, uri can be a different folder or filesystem from where the symbolic link is located.

Example:

cloudreve://my/Inspirations

Example

{
    "uri": "cloudreve://JbVTn@share/1.docx",
    "viewer_id": "af01b85b-f57d-46d2-8ad6-1d9b96548e78",
    "preferred_action": "edit",
    "parent_uri": "cloudreve://my/Inspirations"
}

Request samples

Shell

JavaScript

Java

Swift

Go

PHP

Python

HTTP

C

C#

Objective-C

Ruby

OCaml

Dart

R

curl --location --request PUT '/file/viewerSession' \
--header 'X-Cr-Purchase-Ticket: 1f63aa26-edc0-40ce-950a-cb4d4323158e' \
--header 'Content-Type: application/json' \
--data-raw '{
    "uri": "cloudreve://JbVTn@share/1.docx",
    "viewer_id": "af01b85b-f57d-46d2-8ad6-1d9b96548e78",
    "preferred_action": "edit",
    "parent_uri": "cloudreve://my/Inspirations"
}'

Responses

🟢200Success

application/json

Body

data

object

optional

Response content. In some error type, e.g. lock conflicting errors, this field wil present details of the error, e.g. who is locking the current file.

session

object

required

wopi_src

string | null

optional

WOPISrc of the target WOPI viewer.

code

integer

required

Response code.
0 - Success.

Default:

0

Example:

0

msg

string

optional

Human readable error message (if any).

error

string | null

optional

Internal error message, only visable in debug mode.

correlation_id

string <uuid> | null

optional

Correlation ID of the request. Only presented on failed reqeust.

Example:

b4351ecc-ee1a-4455-bc94-2c3dbcc58538

Example

{
    "code": 0,
    "data": {
        "session": {
            "id": "7f50a377-e55b-41f3-a64e-3624e9cd120d",
            "access_token": "7f50a377-e55b-41f3-a64e-3624e9cd120d.y0SWlTrJFWd2dcPg7fcyx2tSovFpsq45U2iHGfjeyYq23Zkq5KOnyLgcwPkwZEy27gKLQW4b9Lv713Objot2dvsiuJq4vbDKvx637mnolww35tDbIMOdJKDUb5J8qDzD",
            "expires": 1749576616773
        },
        "wopi_src": "http://localhost:9980/browser/594b605/cool.html?WOPISrc=http%3A%2F%2Fhost.docker.internal%3A5212%2Fapi%2Fv4%2Ffile%2Fwopi%2F6Zebb3Ug\u0026lang=lng"
    },
    "msg": ""
}