homeaboutvideotry it nowpricingdocs
Docs

Getting Started

Download as zip

Download many files, or a whole folder, as one zip. Fileboy builds the zip while it sends it, from the dashboard or your server.

From the dashboard

On your app's Files page, tick the files you want (across pages if you like) and press Download zip. Inside a folder, the download button next to the folder's name zips the folder and every folder inside it. The download starts straight away and comes straight from Fileboy's API, so it works for big zips too.

From your server

POST /files/zip
answers with the zip itself.
POST /files/zip/link
answers with a short-lived link instead, so a browser can download the zip directly without your private key passing through it. Both need the private key and take the same body: exactly one of

  • ids
    : up to 1,000 file ids;
  • folderId
    or
    folderPath
    : every file in a folder, and in the folders inside it unless
    recursive
    is false.
    folderId: null
    (or the path
    /
    ) is every file in the app;

and optionally

structure
(
folders
, the default, or
flat
),
filename
and
allowMissing
. A link also takes
expiresIn
, in seconds: 60 to 3600, 600 if you leave it out.

Download as zip
// on your server, with the private key
await fileboy.downloadZipToPath({ ids: [photoId, invoiceId], filename: "order-42" }, "order-42.zip")

// a folder and everything in it, streamed on to your own response
const zip = await fileboy.downloadZip({ folderPath: "/Products/Shoes" })
zip.pipe(res)

// or a link the browser downloads straight from Fileboy, for ten minutes
const link = await fileboy.createZipLink({ ids, structure: "flat", expiresIn: 600 })
res.redirect(link.url)

The zip comes with

Content-Disposition: attachment
, the number of files in
X-Fileboy-Zip-Files
and, with
allowMissing
, how many ids were left out in
X-Fileboy-Zip-Missing
. A link's answer has its
url
,
expiresAt
,
filename
,
fileCount
and
totalBytes
. See the management API for the details.

What's inside

A zipped folder is the top folder of the zip, with its subfolders below it, like a folder download from Google Drive or Dropbox. Files picked by id keep their folders below the deepest folder they all share: pick three files in

/Products/Shoes
and they sit at the top of the zip; pick files from
/Products/Shoes
and
/Products/Hats
and you get
Shoes/
and
Hats/
. With
structure: flat
every file goes at the top.

  • Each file is named as it is in Fileboy. If the name has no extension, the one it was uploaded with is added, so it still opens in the right app.
  • Names are made safe to unzip anywhere. Slashes, backslashes and the characters Windows refuses become
    _
    , control characters are dropped, and names like
    ..
    or
    CON
    are changed. No file can land outside the folder you unzip into.
  • Two files with the same name in the same place (ignoring case, as macOS and Windows do) become
    photo.jpg
    and
    photo (2).jpg
    . The older file keeps the plain name. Folders are numbered the same way if their safe names clash, so two folders never merge into one, and a file never takes a folder's name.
  • Images, video, audio, PDFs, Office documents and archives are stored as they are, as compressing them again saves almost nothing. Everything else is compressed.
  • Each file's date in the zip is when it was uploaded.
Zips hold the original files. Resized or converted images are not included yet: to send a set of thumbnails, use image transform URLs.

Which files can go in

Only your app's own files. An id of another app's file, of part of a video (videos are downloaded through their own URLs), or of a file that was deleted is not found. By default that fails the whole request with

404 files_not_found
, naming the ids, so a zip is never quietly missing files. Send
allowMissing: true
to zip the files that were found instead.

Files set to Signed URLs only are included: the private key, and members of the app in the dashboard, can read them anyway. A zip link grants what a signed URL made with your key would, for the files it was made for, until it expires.

Limits

  • 1,000 files per zip (
    too_many_files
    ). Zip a big folder one subfolder at a time.
  • 10 GB of files per zip, before compression (
    zip_too_large
    ).
  • An empty folder is
    400 nothing_to_zip
    .
  • An app can have 1,000 zip links that have not expired.

Zips over 4 GB, or with files over 4 GB, use zip64, which every current unzip tool reads (Windows Explorer, macOS Archive Utility, 7-Zip,

unzip
).

Streaming and errors

Fileboy reads each file from storage and writes it into the zip as the zip goes out, so a download starts at once and big zips don't wait to be built. That also means the size isn't known in advance, so there is no

Content-Length
and browsers show the download without a percentage.

If storage can't be read before the zip starts, the answer is

502 storage_error
. If it fails part way, Fileboy cuts the connection instead of finishing the zip, so the download fails visibly rather than leaving you a zip that looks complete but isn't. Try again.

Zip downloads count the same as downloading each file on its own.

Download as zip

From the dashboardFrom your serverWhat's insideWhich files can go inZip linksLimitsStreaming and errors
hello@fileboy.io

Fileboy

HomeAboutPricingChangelog
© Copyright 2026, CD2 Solutions Ltd.
Terms and ConditionsPrivacy Policy