Move and rename a file

Overview

Moves or renames a file within one section without transferring its content. The operation is performed by the file system, so its cost does not depend on file size.

There is no separate method for this: PUT is used on the destination path with the X-Era-Source header and an empty body. The presence of the header distinguishes a move from an upload.

Moving directories is not supported.

Requests

HTTP verb Endpoint Description

PUT

/rest/v1/fs/targets/<target>/<path>

Moving a file


Moving a file

Specifics

  • The X-Era-Source header value is the source path relative to the section root, not a full URL. Escaping the section and .. segments are rejected with code 403.

  • Source and destination belong to the same section. A file cannot be moved between sections in one request.

  • Missing destination path directories are created, and emptied source directories are deleted.

  • The destination path is created only after the source is checked: a failed move leaves no empty directories behind.

  • The request must not contain both a body and the X-Era-Source header: such a request is ambiguous and is rejected with code 400.

Request

Table 1. Request parameters
Name Type Description

overwrite

bool

Allow overwriting an occupied destination path. Default false.

Table 2. Request headers
Name Description

X-Era-Source

Source file path relative to the section root.

Example rename
PUT /rest/v1/fs/targets/files/inbox/report-2026.pdf HTTP/1.1
X-Era-Source: inbox/report.pdf
Content-Length: 0
Example move to another directory with overwrite
PUT /rest/v1/fs/targets/files/archive/2026/report.pdf?overwrite=true HTTP/1.1
X-Era-Source: inbox/report.pdf
Content-Length: 0

Response

Example response
HTTP/1.1 204 No Content
Code Condition

204

File moved.

400

The request contains both a body and the X-Era-Source header.

403

The source path escapes the section.

404

The source file does not exist.

409

The destination path is occupied and the overwrite parameter is not specified; or the source is a directory.