Create download URL - 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-Context-Hint

string <uuid>

optional

Optional context hint to speed up DB queries. You can get its value from the response of listing files. It is recommended to set this header if you need to perform action on files that are just listed by List files API.

Example:

b832b998-7ece-4ffd-ba6b-afb64530ca70

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

uris

array[string]

required

List of URI of the target files.

>= 1 items

download

boolean | null

optional

Whether the desired URL is for downloading files.
For supported storage policy, browser will download file instead of previewing it directly if this field is set to true.

redirect

boolean | null

optional

Only works if only 1 items presented in uris.
If set to true, the HTTP response will use 302 status code to redirect to target URL instead of returning result in JSON response.

entity

string | null

optional

Only works if only 1 items presented in uris and archive is false. Specify preferred ID of the file blob.
By default, latest version blob will be selected.

Example:

aO8j

use_primary_site_url

boolean | null

optional

By default, the host domain of file URL will try to accommodate the actual Host that the client site requesting the API (If the Host is presented in primary/secondary site URL setting in dashboard). If you wish to force using primary site URL, please set this to true.

skip_error

boolean | null

optional

Whether to skip errors and return partial successful file URLs. If set to false or omited, the whole request will fail if errors occurs for any items in uris.

Request samples

Shell

JavaScript

Java

Swift

Go

PHP

Python

HTTP

C

C#

Objective-C

Ruby

OCaml

Dart

R

cURL

Server-side batch downloadGet download URL for multiple files

curl --location --request POST '/file/url' \
--header 'X-Cr-Context-Hint: b832b998-7ece-4ffd-ba6b-afb64530ca70' \
--header 'X-Cr-Purchase-Ticket: 1f63aa26-edc0-40ce-950a-cb4d4323158e' \
--header 'Content-Type: application/json' \
--data-raw '{
    "uris": [
        "cloudreve://my/The%20Man.mp3",
        "cloudreve://my/Taylor%20Swift%20-%20Untouchable%20(Taylor%E2%80%99s%20Version).mp3",
        "cloudreve://my/%E9%81%A0%E9%87%8E%E3%81%B2%E3%81%8B%E3%82%8B%20-%20LOVE%202000.mp3",
        "cloudreve://my/Taylor%20Swift%20-%20Guilty%20as%20Sin.mp3"
    ],
    "archive": true
}'

Responses

🟢200Success

application/json

Body

data

object

required

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.

urls

array [object {2}]

required

List of file URL.

expires

string <date-time>

required

The earliest expire time among the returned urls.

Example:

2025-06-10T12:06:55.011624+08:00

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.

aggregated_error

object | null

optional

Map of multiple error in batch request. The key is the failed resource ID, it could be a file URI or a resource ID, the value is a Response.

Additional properties

object (Response)

optional

correlation_id

string <uuid> | null

optional

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

Example:

b4351ecc-ee1a-4455-bc94-2c3dbcc58538

Examples

Server-side batch downloadGet download URL for multiple files

{
    "code": 0,
    "data": {
        "urls": [
            {
                "url": "http://localhost:5173/api/v4/file/archive/56bb8329-3afa-4137-9ebb-2a07b6ea19b9/archive.zip?sign=1CgU15Is0ezKeTVKE_OAu2tJJoB6lN5s_DvRXTcP7GQ%3D%3A1749525301"
            }
        ],
        "expires": "2025-06-10T11:15:01.186053+08:00"
    },
    "msg": ""
}