Domain data directory in the :SITESHARE storage (siteshare/domain)

Overview

Provides administrative access to files and directories placed in the current domain data directory inside the :SITESHARE storage.

The domain is taken from the session and is not specified in the path. Each domain manages only its own directory; the master domain manages its own. It is impossible to reach another domain data directory through this endpoint.

Deletion and clearing in this section affect the entire working data of the domain.

Management of this directory relies on external synchronization, for example mounting it to an NFS server. Without external synchronization in a multi-server system this directory is individual to each server; managing it via the API affects only the server running the web server role.

Access to the directory from scripts is via the directory category prefix ":SS_DOM/".

Available in any domains.

Requests

HTTP verb Endpoint Description

POST

/rest/v1/fs/targets/siteshare/domain

Uploading a group of files

GET

/rest/v1/fs/targets/siteshare/domain

Getting the list of files

GET

/rest/v1/fs/targets/siteshare/domain/<filename>

Downloading a file

PUT

/rest/v1/fs/targets/siteshare/domain/<filename>

Re-uploading an existing file

DELETE

/rest/v1/fs/targets/siteshare/domain/<filename>

Deleting a file

HEAD

/rest/v1/fs/targets/siteshare/domain/<filename>

Getting file metadata

METADATA

/rest/v1/fs/targets/siteshare/domain/<filename>

Getting file metadata (METADATA)

PUT

/rest/v1/fs/targets/siteshare/domain/<filename>

Move and rename a file

PUT

/rest/v1/fs/targets/siteshare/domain/<path>/

Directory operations

DELETE

/rest/v1/fs/targets/siteshare/domain/<path>/

Directory operations

CLEAR

/rest/v1/fs/targets/siteshare/domain/<path>/

Directory operations

DOWNLOADZIP

/rest/v1/fs/targets/siteshare/domain

Downloading and uploading a directory as an archive

UPLOADZIP

/rest/v1/fs/targets/siteshare/domain

Downloading and uploading a directory as an archive

METADATA

/rest/v1/fs/targets/siteshare/domain

Section root operations

CLEAR

/rest/v1/fs/targets/siteshare/domain

Section root operations


Uploading a group of files

Upload to the collection is performed with Content-Type: multipart/formdata.

The request may contain one or several files. Files are placed under the names specified in the Content-Disposition headers of each part.

If a file with the specified name already exists, it is not saved and an error is returned. Depending on the Content-Type and the presence of successfully placed files, either a failed HTTP response or failure information in the body of a 200 OK HTTP response may be returned.

The directory to which the upload is performed must exist: accessing a nonexistent directory returns 405 Method Not Allowed. To place a file together with missing path directories, use the PUT method.

Request

Example request
POST /rest/v1/fs/targets/siteshare/domain HTTP/1.1
Content-Type: multipart/form-data; boundary=-----------boundary_69df8120352a996e

-----------boundary_69df8120352a996e
Content-Type: application/octet-stream
Content-Disposition: form-data; name="filename"; filename="data.bin"
Content-Transfer-Encoding: binary

BINARY BODY OF 'data.bin'
-----------boundary_69df8120352a996e--

Response

Example response
[
  {
    "name" : "1.mp3",
    "size" : 46020,
    "status" : "ok"
  }
]

Getting the list of files

Request

Table 1. Request parameters
Name Type Description

filter

object

Filter by field values.

mask

str

List of fields to output. Available fields for output: name, size, last_modified.

offset

int

Offset in the list of files to output.

limit

int

Maximum number of files in the list.

order

array<object|str>

Sorting order of files in the list.

countonly

bool

When true, only the number of files is returned.

It is counted after applying the filter: with the filter parameter, the number of files matching the filter is returned, not the total number of files in the directory.

Example request
GET /rest/v1/fs/targets/siteshare/domain HTTP/1.1

Response

The time in the last_modified field is returned in UTC.

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "last_modified" : "2021-12-22 15:42:06",
    "name" : "a",
    "type" : "directory"
  }
]

Downloading a file

Request

Table 2. Request parameters
Name Type Description

attachment

bool

Output type. Default false.

true – returned with the header Content-Disposition: attachment; filename=filename.ext or Content-Disposition: attachment; filename*=UTF-8''%d1%84%d0%b0%d0%b9%d0%bb.ext, where file.ext is the file name in UTF-8 encoding and URL-encoded.

false – returned without the Content-Disposition header.

Example request
GET /rest/v1/fs/targets/siteshare/domain/data.bin?attachment=true HTTP/1.1

Response

Example response
HTTP/1.1 200 OK
Content-Type: application/octet-stream; charset=utf-8
Content-Disposition: attachment; filename*=UTF-8''data.bin

BINARY BODY OF 'data.bin'

Re-uploading an existing file

Replaces the file.

A single file is uploaded either with Content-Type: multipart/formdata or with an arbitrary non-multipart Content-Type.

If the upload uses Content-Type: multipart/formdata, only the first file is saved (the first part having a filename field in the Content-Disposition header), and the file name itself is ignored.

The file name is always taken from the URL.

If the file at the specified path does not exist, it is created along with missing path directories.

A request with Content-Type: application/octet-stream and zero body length creates an empty file. A request without a body, without Content-Type, and without the X-Era-Source header is rejected with code 400: the intent cannot be determined from such a request.

The PUT method has another meaning with a different request form: Move and rename a file.

In sections with nested structure, PUT on a path with a trailing slash creates a directory, see Directory operations.

Request

Example request (octet-stream)
PUT /rest/v1/fs/targets/siteshare/domain/data.bin HTTP/1.1
Content-Type: application/octet-stream

BINARY BODY OF 'data.bin'
Example request (multipart)
PUT /rest/v1/fs/targets/siteshare/domain/data.bin HTTP/1.1
Content-Type: multipart/form-data; boundary=-----------boundary_69df8120352a996e

-----------boundary_69df8120352a996e
Content-Type: application/octet-stream
Content-Disposition: form-data; name="data.bin"; filename="data.bin"
Content-Transfer-Encoding: binary

BINARY BODY OF 'data.bin'
-----------boundary_69df8120352a996e--

Response

Example response
HTTP/1.1 204 No Content

Deleting a file

Request

Example request
DELETE /rest/v1/fs/targets/siteshare/domain/data.bin HTTP/1.1

Response

Example response
HTTP/1.1 204 No Content

Getting file metadata

Returns file metadata, including the size in the Content-Length header.

Specifics

  • The HTTP response contains no body despite the presence of the Content-Length header.

Request

Table 3. Request parameters
Name Type Description

attachment

bool

Output type. Default false.

true – returned with the header Content-Disposition: attachment; filename=filename.ext or Content-Disposition: attachment; filename*=UTF-8''%d1%84%d0%b0%d0%b9%d0%bb.ext, where file.ext is the file name in UTF-8 encoding and URL-encoded.

false – returned without the Content-Disposition header.

Example request
HEAD /rest/v1/fs/targets/siteshare/domain/data.bin?attachment=true HTTP/1.1

Response

Example successful response
HTTP/1.1 200 OK
Accept-Ranges: bytes
Allow: GET, HEAD, POST, PUT, DELETE, METADATA, OPTIONS
Content-Disposition: attachment; filename=1.mp3
Content-Length: 46020
Content-Type: audio/mp3
Example failed response
HTTP/1.1 404 Not Found

Getting file metadata (METADATA)

Returns the file size and modification time in JSON format. Unlike the HEAD method, the information comes in the response body and does not require parsing headers.

The method is non-standard and is accepted in two equivalent forms: by the method itself (METADATA /rest/v1/fs/targets/siteshare/domain/data.bin) and by POST on a path with the suffix (POST /rest/v1/fs/targets/siteshare/domain/data.bin!metadata). More — Non-standard methods in the path.

The request must not contain a body in either form: a request with a body is treated as a file upload.

Specifics

  • The time in the mtime field is returned in UTC in RFC 3339 format.

  • The content checksum is returned only on a request with the hasha=true parameter. Without the parameter the file content is not read, so the request is cheap regardless of file size.

Request

Table 4. Request parameters
Name Type Description

hasha

bool

Add a content checksum to the response. Default false.

Calculation requires reading the entire file, so for large files the parameter should be specified only when explicitly necessary.

Example request
POST /rest/v1/fs/targets/siteshare/domain/data.bin!metadata HTTP/1.1

Response

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "size" : 3836,
  "mtime" : "2026-07-01T16:47:31Z"
}
Example response with hasha=true
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "size" : 3836,
  "mtime" : "2026-07-01T16:47:31Z",
  "hasha" : "md5;9f86d081884c7d659a2feaa0c55ad015"
}

Move and rename a file

Moves or renames a file within a section without transferring its content.

Performed by PUT on the destination path with the X-Era-Source header and an empty body. The header specifies the source path relative to the section root.

Request

Table 5. Request parameters
Name Type Description

overwrite

bool

Allow overwriting an occupied destination path. Default false.

Example request
PUT /rest/v1/fs/targets/siteshare/domain/<filename> HTTP/1.1
X-Era-Source: inbox/data.bin
Content-Length: 0

Response

Example response
HTTP/1.1 204 No Content

Directory operations

The section supports nested directories of arbitrary depth, so directory operations are available in it.

Request Action

PUT <path>/

Create a directory. The path is specified with a trailing slash, the request body is absent.

DELETE <path>

Delete an empty directory.

DELETE <path>?recursive=true

Delete the directory with its contents. Requires key confirmation.

CLEAR <path>

Clear the directory, leaving it in place. Requires key confirmation.

Deleting and clearing a non-empty directory are performed with two requests: the first deletes nothing and returns a confirmation key along with the scope of the upcoming operation, the second performs the operation with this key.

The section root cannot be deleted (405), but it can be cleared.

More, together with the confirmation key and limits description: Directory operations.


Downloading and uploading a directory as an archive

Request Action

DOWNLOADZIP <path>

Download the directory as one archive.

UPLOADZIP <path>

Upload a file structure from an archive into the directory.

An archive containing an escape beyond its boundaries — entries with .., absolute paths, or symbolic links outside — is rejected entirely with code 422.


Section root operations

In addition to listing and uploading files, the section root supports two methods.

Request Action

METADATA /rest/v1/fs/targets/siteshare/domain

Section description and information about its root: supported operations, limits, number of top-level elements.

CLEAR /rest/v1/fs/targets/siteshare/domain

Clearing the section: all contents are deleted, the section itself remains. The operation is recursive and requires key confirmation.

The section cannot be deleted: DELETE on the root path always returns 405.