Create upload session

Create a upload session, which is required before uploading files. After upload session created, client should start uploading using the information included in the upload session. The implementation of upload differs from different storage policy type, you can find Cloudreve's implentation in uploader.

A general file uploading includes 4 steps: Select storage policy, create upload session, upload chunks, finish upload request. For small files, please consider using Update file content.

1. Select storage policy

Use List files to get the parent storage policy for current folder.

If storage policy type is load_balance, you should select one child storage policy from storag_policy.children based on their weight.

For other storage policy type, you can just use it directly.

2. Create upload session

Use current method to create an upload session.

3. Upload chunks

For local storage policy, or any other storage policy with storage_policy.relay set to true, use Upload file chunk;

For remote storage policy, send chunks to the URL defined in upload_urls, there should be only one element in upload_urls. The request is similar to Upload file chunk, except:

Chunk index is passed through query chunk, e.g. http://slavecloudreve.com:5213/api/v4/slave/upload/f1dd2c8c-0c51-475b-a086-b338ae1d8109?chunk=2

Authorization shoud be the value of credential in upload session, e.g. Bearer Cr sBnnQ3rZ-UBr7d8ohKpUFtsQc8OMLuWwn1VhuJtdc5k=:1749623351

For any other storage policies, please refer to:

S3: UploadPart

OSS: UploadPart

COS: UploadPart

OBS: Uploading Parts

OneDrive: Upload bytes to the upload session

Qiniu: 分块上传数据

Upyun: 大文件上传

4. Finish upload

For local/remote/upyun storage policy, or any other storage policy with storage_policy.relay set to true, you don't need to finish upload, it's automatically finished after last chunk uploaded.

OneDrive: Complete OneDrive upload

S3: CompleteMultipartUpload, then send Complete S3 upload

COS: Complete Multipart Upload, then send Complete COS upload

OBS: Completing a Multipart Upload, then send Complete OBS upload

Qiniu: 完成文件上传

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://my/Inspirations/archive%20(3).zip

size

integer

required

Size of the file.

last_modified

integer | null

optional

Optional Unix milliseconds timestamp of when the file is last modified.

Example:

1749524701494

mime_type

string | null

optional

Optional mime type of the file. If not set, will try to guess from file extension name.

Example:

application/zip

policy_id

string

required

ID of the storage policy to use.

metadata

object | null

optional

Optional key-value of file metadata.

Additional properties

string

optional

entity_type

enum<string> | enum<null>

optional

Optional blob type.
By default (omit this field), request will fail if file name conflict with exsting file.
If set to version, exsiting file will be overwritten.
If set to live_photo, the file specified in uri must be an existing file.

Allowed values:

live_photoversion

Example

{
    "uri": "cloudreve://my/Inspirations/archive%20(3).zip",
    "size": 65328441,
    "policy_id": "J7uV",
    "last_modified": 1749524701494,
    "mime_type": "application/zip"
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Success

application/json

Body

data

object | null

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_id

string <uuid>

required

ID of the upload session. Might be used in following upload requests.

Example:

9897ebae-7b73-4169-aabc-6396f470e4bb

upload_id

string

optional

ID of the multipart upload request. Only used by some storage policy.

Example:

AGKGs9fltDAfRRyIGhkAutvsUbPfUOLxRBTs82pm_yoCiQA77sUMuCX5KLTB1dxyv_-zkBfiNyfS4NYTIdafVgkmWL6y3KxKVeiZMgFiNxo2ZLF03-WAJTg92KuOwvrE9DdDNnivKbX4IyR2VfLtP_tbIb0oVh8Gji2IN3p3xvMkcVJcG3KZwaNC3-IaN0xATVA-Bov7qVLT_mU-bGjS6w-c6hIw3_FHouALE4HFmlOrOYbu0IUDdCNAvN9_yvncfVANxEvQIp3sOuEvtqZrS9OByPXtFjR-kADsY0CstrbPHeR1amXEqphiLGK5EucWu0NMWfM8HMz9pKAc7zUkYK8

chunk_size

integer

required

Size of a chunk in multipart uplaod. 0 means multipart upload is disabled.

expires

integer

required

Unix timestamp of the expiration date for this uplaod session. Client must finish the uploading before this time.

Example:

1749620903

upload_urls

array[string] | null

optional

List of URLs to upload each chunk. Some storage policy use only one URL for all chunks, in this case only one URL is included in the list.

credential

string | null

optional

Some storage policy (qiniu, upyun, remote) requires addition credential to upload.

Example:

Bearer Cr sBnnQ3rZ-UBr7d8ohKpUFtsQc8OMLuWwn1VhuJtdc5k=:1749623351

completeURL

string | null

optional

URL to finish multipart upload. Used by cos, oss, s3 and obs.

Example:

https://a09fb0452cf79d9c5ce7f7d.r2.cloudflarestorage.com/cloudrevetest/uploadsr2/3/Inspirations/3_24474f62-88ee-4d37-bcf3-3952cc6f80ea_archive%20%283%29.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=f12234edc4f50556e102723bcd504dec%2F20250610%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20250610T054824Z&X-Amz-Expires=86398&X-Amz-SignedHeaders=host&uploadId=AGKGs9fltDAfRRyIGhkAutvsUbPfUOLxRBTs82pm_yoCiQA77sUMuCX5KLTB1dxyv_-zkBfiNyfS4NYTIdafVgkmWL6y3KxKVeiZMgFiNxo2ZLF03-WAJTg92KuOwvrE9DdDNnivKbX4IyR2VfLtP_tbIb0oVh8Gji2IN3p3xvMkcVJcG3KZwaNC3-IaN0xATVA-Bov7qVLT_mU-bGjS6w-c6hIw3_FHouALE4HFmlOrOYbu0IUDdCNAvN9_yvncfVANxEvQIp3sOuEvtqZrS9OByPXtFjR-kADsY0Cs0NMWfM8HMz9pKAc7zUkYK8&X-Amz-Signature=26760a67676f1293ba63b6be65aaf13408527c95ba033fcf58d79f93

storage_policy

object (StoragePolicy)

required

Stroage policy to use.

mime_type

string | null

optional

Desired value of content-type in uplaod requests. Only used by qiniu and upyun.

Example:

application/zip

upload_policy

string | null

optional

Upyun upload policy.

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": {
        "session_id": "9897ebae-7b73-4169-aabc-6396f470e4bb",
        "upload_id": "",
        "chunk_size": 26214400,
        "expires": 1749620196,
        "storage_policy": {
            "id": "J7uV",
            "name": "Default storage policy",
            "type": "local",
            "max_size": 0
        },
        "uri": "cloudreve://my/Inspirations/archive%20(3).zip",
        "callback_secret": "0SivUl28p44BADmQDkTJrJOo7iozN74W"
    },
    "msg": ""
}

1. Select storage policy#

2. Create upload session#

3. Upload chunks#

4. Finish upload#

Request

Request samples

Responses

1. Select storage policy

2. Create upload session

3. Upload chunks

4. Finish upload