Download and upload a directory as an archive

Overview

The DOWNLOADZIP and UPLOADZIP methods allow working with a directory as a whole: download it as one archive and upload a file structure from an archive. This eliminates the need for a request per file.

The methods are available in sections with tree structure — where nested directories exist. The section structure comes in the structure field of the section description.

The same methods apply to script attachments, see IVR script attachments.

Requests

HTTP verb Endpoint Description

DOWNLOADZIP

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

Downloading a directory as an archive

UPLOADZIP

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

Uploading a directory as an archive


Downloading a directory as an archive

Packs the directory with all contents and returns the archive.

Specifics

  • Applicable both to the section root and to any of its subdirectories.

  • The archive name is formed from the section name and directory path: cacerts.zip, files-certificates-2026.zip.

  • The directory scope is checked before packing. A 409 refusal occurs when the directory has 10,000 files or more, or the volume reaches 2,000,000,000 bytes: the limit here is the first rejected size. No temporary archive is created on refusal.

  • File names in UTF-8 encoding are preserved.

  • Symbolic links leading outside the packed directory are not included in the archive. Internal links are preserved as links.

Request

Example request
DOWNLOADZIP /rest/v1/fs/targets/files/certificates HTTP/1.1

Response

Example response
HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename=files-certificates.zip

BINARY BODY OF 'files-certificates.zip'

Uploading a directory as an archive

Unpacks the archive contents into the specified directory.

Specifics

  • The request body size limit is 2,000,000,000 bytes. A request of this size or larger is rejected with code 413: the limit here is the first rejected size, not the last allowed one. A request with a body but without the Content-Length header is rejected with code 411: the volume cannot be checked before acceptance.

  • The total unpacked data volume must not exceed 2,000,000,000 bytes. It is calculated from the archive table of contents before writing to disk, so an oversized archive is rejected immediately rather than after partial unpacking. Unlike the request body limit, refusal here occurs on exceeding: exactly the limit volume is allowed.

  • An individual file inside the archive must not exceed the general file size limit — 512 MB. A record above it rejects the entire archive, with its name indicated.

  • In sections with tree structure the archive structure is preserved: the entry sub/report.pdf goes into the sub subdirectory, missing directories are created.

  • When uploading script attachments (they have no subdirectories), the archive hierarchy is discarded and all entries are placed at one level. In sections with flat structure the archive methods are unavailable (405).

  • Existing files with matching names are overwritten.

  • Directory contents not affected by the archive are preserved.

  • The archive is checked for safety before and after unpacking, see Archive content requirements. An unsafe archive is rejected entirely; nothing reaches the target directory.

Request

Example request
UPLOADZIP /rest/v1/fs/targets/files/certificates HTTP/1.1
Content-Type: application/zip

BINARY BODY OF ARCHIVE

Response

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

[
  { "name" : "1789660649498", "status" : "ok" }
]

The response contains one element per accepted archive, not per file inside it: name is the internal archive identifier, status is its unpacking result. The unpacked composition is discovered by listing the directory.

Example response for a rejected archive
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8

{
  "error_code" : 1406,
  "error_message" : "Archive rejected: entries must stay inside the archive"
}

Archive content requirements

Archive contents must not escape its boundaries. An archive violating this rule is rejected entirely: not a single file from it reaches the disk, including safe ones.

An archive is also rejected entirely if it exceeds volume limits: total unpacked size above 2 GB or an individual entry above the section max_file_size. Both cases are determined from the table of contents before unpacking.

Not allowed:

  • entries with .. segments in the path;

  • entries with absolute paths;

  • symbolic links whose target is outside the archive;

  • entries whose name the server cannot address: if any segment of the entry path ends with !<method>, where <method> is a method supported by the section, such a file or directory would be unreachable. See Non-standard methods in the path.

Internal symbolic links are allowed and preserved on unpacking.

The rule applies in all unpacking modes and for all archive consumers on the platform, including script attachments. There is no separate "lenient" mode.

Archives obtained via DOWNLOADZIP satisfy these rules by construction: a directory downloaded as an archive and uploaded back is reproduced together with its subdirectory structure.

Packing and unpacking limits are coordinated so that everything downloadable as an archive can also be uploaded back: packing rejects a directory of 2,000,000,000 bytes, while unpacking still accepts such a volume. If the ratio were reversed, there would be a directory that can be downloaded but not returned.