Skip to content

Download API ​

GET /api/download/:id ​

Download the encrypted file stream.

Request ​

Headers:

HeaderTypeDescription
X-Auth-Tokenbase64urlAuthentication token

Response ​

200 OK:

The response body is the raw encrypted stream (application/octet-stream).

Response headers:

HeaderValue
Content-Typeapplication/octet-stream
Content-LengthSize in bytes
Cache-Controlno-store
X-File-CountNumber of files in the upload

401 Unauthorized:

json
{
  "error": "Invalid or missing auth token"
}

410 Gone:

json
{
  "error": "Upload expired or download limit reached"
}

429 Too Many Requests (too many wrong tokens from this IP, with a Retry-After header):

json
{
  "error": "Too many failed attempts. Try again later."
}

A sent but wrong X-Auth-Token counts against the same lockout as POST /api/password/:id, PASSWORD_MAX_ATTEMPTS per IP and upload. A request without the header does not count, so another site cannot lock a visitor out.

Notes ​

  • Each successful download atomically increments the download counter
  • If the download limit is reached during the increment, the request fails with 410
  • The file is streamed directly from disk - no buffering in memory
  • Cache-Control: no-store prevents caching of encrypted content
  • The X-File-Count header tells the client whether the payload is a single file or archive
  • HEAD answers 405 with Allow: GET. It would count a download otherwise, since the framework answers HEAD with the GET handler
  • An upgrade request (Upgrade header) is accepted only on the two WebSocket upload routes. Anywhere else the server answers 400 before any route runs

Example ​

bash
curl -o encrypted.bin \
  -H "X-Auth-Token: dGVzdA" \
  http://localhost:3000/api/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890