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 |
|---|---|---|
|
|
|
|
|
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
409refusal 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.
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 theContent-Lengthheader is rejected with code411: 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
treestructure the archive structure is preserved: the entrysub/report.pdfgoes into thesubsubdirectory, 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
flatstructure 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
UPLOADZIP /rest/v1/fs/targets/files/certificates HTTP/1.1
Content-Type: application/zip
BINARY BODY OF ARCHIVE
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.
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 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. |