Create file - Cloudreve API Docs

Create a new file with given URI and props. If ancestor folders does not existed for given uri, they will be created automatically.

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 file to be created.

Example:

cloudreve://my/Inspirations/new.txt

type

enum<string>

required

Type of the new file.

Allowed values:

filefolder

metadata

object | null

optional

Key-value map of metadata for the new file.

Additional properties

string

optional

err_on_conflict

string

optional

Define the behavior when there's conflict (object already existed) for given uri:

If true, an error will be returned;

If false, no mutation is performed, the existing file in uri will be returned.

Examples

Create new empty fileSave share link to a shortcutCreate a new folder

{
    "type": "file",
    "uri": "cloudreve://my/Inspirations/new.txt",
    "err_on_conflict": true
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Success

application/json

Body

data

object

required

Response content

type

enum<integer>

required

Type of this file.

Allowed values:

string

required

ID of this file.

name

string

required

Name of this file.

It might not be expected display name. For files under trash bin, this field is a non-readable UUID. The expected display name should be retrieved from metadata with name sys:restore_uri, which can be parsed as a URI.

Example:

btn_google_signin_dark_normal_web@2x.png

permission

string | null

optional

Boolset encoded permissions granted by current authenticated user. For null, all permissions are granted.
Permission definition can be found at File Permissions

created_at

string <date-time>

required

Datetime when the file is created.

Example:

2025-05-24T10:55:22+08:00

updated_at

string <date-time>

required

Datetime when the file is last updated.

Example:

2025-05-24T10:55:22+08:00

size

integer

required

Size of the file, also the size of current primary version blob.

Example:

7536

path

string

required

URI of this file.

Example:

cloudreve://my/%E9%97%A8%E7%A5%A8/btn_google_signin_dark_normal_web%402x.png

capability

string | null

optional

Boolset encoded set of capabilities supported.

Example:

39/9

owned

boolean

required

Whether this file is owned by current authenticated user.

primary_entity

string | null

optional

ID of the primary version blob.

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": {
        "type": 1,
        "id": "d08Wy1Hx",
        "name": "Q3",
        "permission": null,
        "created_at": "2025-05-24T14:24:27+08:00",
        "updated_at": "2025-05-24T14:24:27+08:00",
        "size": 0,
        "metadata": null,
        "path": "cloudreve://my/Inspirations/Q3",
        "capability": "39/9",
        "owned": true,
        "primary_entity": "zOie"
    },
    "msg": ""
}