List files

GET

/file

Auth: JWT Optional

List files under given URI, can also be used to search files if the URI contains search conditions.

Request

Authorization

Add the parameter

Authorization

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

Example:

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

Query Params

uri

string

required

URI of the folder to list.
You can specify Query - Search Conditions in the URI to search files.

Example:

cloudreve://my/Luke's%20AMA

page

integer

required

Desired page, only used in offset pagination.

>= 0

Example:

page_size

integer

required

Page size. Cannot exceed navigator's max supported size defined in max_page_size form list response.

Example:

order_by

string

optional

All possible values are defined in order_by_options from list response.

Default:

created_at

Example:

created_at

order_direction

string

optional

All possible values are defined in order_direction_options from list response.

Default:

asc

Example:

asc

next_page_token

string

optional

Token for requesting next page. Empty value means requesting the first page. Only used in cursor pagination.

Example:

4|eyJpZCI6InJwR3pZMUY1In0=

Header Params

X-Cr-Purchase-Ticket

string <uuid>

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

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request GET '/file?uri=cloudreve://my/Luke'\''s%20AMA&page=0&page_size=50&order_by=created_at&order_direction=asc&next_page_token=4|eyJpZCI6InJwR3pZMUY1In0=' \
--header 'X-Cr-Purchase-Ticket: 1f63aa26-edc0-40ce-950a-cb4d4323158e'

Responses

🟢200Success

application/json

Body

data

object

required

Response content

files

array [object {13}]

required

List of files.

parent

object (FileResponse)

required

Parent folder of current location.

pagination

object (PaginationResults)

required

Pagination props.

props

object (NavigatorProps)

required

Navigator props.

context_hint

string <uuid>

required

ContextHint is used to speed up following operations under this listed directory. It persists some intermedia state so that the following request don't need to query database again.
One typical case is loading thumbnails under the listed folder, carry context hint in X-Cr-Context-Hint header in the thumbnail request can speed up backend database operations.

Example:

4008c479-0e1b-409b-950d-e12fd8003fb0

recursion_limit_reached

boolean | null

optional

Only applies to search list, indicating whether the recursion limit has been reached. Client side should suggest user narrow down search root folder in this case.

mixed_type

boolean

required

If it's false, folders is alway placed in front of the file list. If it's true, folders might be mixed with files in the list. Cloudreve will try its best not to mix file types, but in search result list, this value is false.

single_file_view

boolean | null

optional

Indicating the frontend UI should use "Single share file" UI, since there's only one file in single file share link.

storage_policy

optional

Storage policy that should be used to upload new files to this folder.

view

object (ExplorerView)

optional

View setting stored in the server for current folder.
It could be null, indicating local preference is preferred.

code

integer

required

Response code.
0 - Success.

Default:

Example:

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": {
        "files": [
            {
                "type": 1,
                "id": "N93dL8ig",
                "name": "Takeout",
                "permission": null,
                "created_at": "2025-02-13T20:14:15+08:00",
                "updated_at": "2025-02-13T20:17:36+08:00",
                "size": 0,
                "metadata": {},
                "path": "cloudreve://my/Luke's%20AMA/Takeout",
                "capability": "39/9",
                "owned": true,
                "primary_entity": "zOie"
            },
            {
                "type": 1,
                "id": "8zXA03uL",
                "name": "新建文件夹",
                "permission": null,
                "created_at": "2025-02-20T15:16:28+08:00",
                "updated_at": "2025-02-20T15:16:28+08:00",
                "size": 0,
                "metadata": {
                    "tag:asd": ""
                },
                "path": "cloudreve://my/Luke's%20AMA/%E6%96%B0%E5%BB%BA%E6%96%87%E4%BB%B6%E5%A4%B9",
                "capability": "39/9",
                "owned": true,
                "primary_entity": "zOie"
            },
            {
                "type": 0,
                "id": "8zXBp3UL",
                "name": "sample.psd",
                "permission": null,
                "created_at": "2025-05-22T14:34:24+08:00",
                "updated_at": "2025-05-22T14:34:24+08:00",
                "size": 3285099,
                "metadata": {
                    "thumb:disabled": ""
                },
                "path": "cloudreve://my/Luke's%20AMA/%E5%B0%8F%E7%88%B1%E8%B1%86.psd",
                "capability": "39/9",
                "owned": true,
                "primary_entity": "jYOAc8"
            }
        ],
        "parent": {
            "type": 1,
            "id": "0OmpAGUn",
            "name": "Luke's AMA",
            "permission": null,
            "created_at": "2024-01-27T10:58:20+08:00",
            "updated_at": "2025-05-23T15:09:15+08:00",
            "size": 0,
            "metadata": null,
            "path": "cloudreve://my/Luke's%20AMA",
            "capability": "39/9",
            "owned": true,
            "primary_entity": "zOie"
        },
        "pagination": {
            "page": 0,
            "page_size": 100,
            "is_cursor": true
        },
        "props": {
            "capability": "39/9",
            "max_page_size": 2000,
            "order_by_options": [
                "name",
                "size",
                "updated_at",
                "created_at"
            ],
            "order_direction_options": [
                "asc",
                "desc"
            ]
        },
        "context_hint": "5c6ea8a1-86e0-4967-8d40-598c6eb78bff",
        "mixed_type": false,
        "storage_policy": {
            "id": "Emta",
            "name": "minio",
            "type": "s3",
            "max_size": 0
        }
    },
    "msg": ""
}

Modified at 2025-06-27 03:14:12

Delete direct link

List file activities