Synology NAS Ready WebDAV Chunked Streaming 3x Retry Protected

Synology WebDAV Chunked Uploader API

Resilient chunked file uploader with direct WebDAV staging, 3x exponential backoff retry, and O(1) constant-memory stream merging.

🩺 Health Probe 📄 Raw JSON Spec

🔒 Authentication Required

All /upload/* endpoints require the API key in the HTTP request header.

Header: x-api-key: <API_KEY>
GET /health • Service Health Probe
Public
Description

Returns the health status, uptime, and memory consumption of the Node.js API.

Response Example (HTTP 200)
JSON Response 
{
  "status": "healthy",
  "timestamp": "2026-09-07T18:00:00.000Z",
  "uptime": 142.5,
  "memoryUsage": {
    "rss": 65432100,
    "heapTotal": 16023552,
    "heapUsed": 12450800
  }
}
cURL Command Example
cURL CLI 
curl -X GET "http://api.fileuploader.commandos.rozsnorbert.hu/health"
POST /upload/start • Initialize Upload Session
Auth Required
Description

Creates a unique upload session on the server and prepares the remote WebDAV staging directory.

Request Body (application/json)
Parameter Type Requirement Description
filename string Required Original filename to upload (e.g., "video.mp4")
fileSize integer Optional Total file size in bytes. Recommended: enables the size-based chunk size recommendation (adaptive chunking)
totalChunks integer Optional Expected number of chunks (informational; with adaptive chunking the real count is only known at the end)
chunkSize integer Optional Fixed chunk size in bytes (max MAX_CHUNK_SIZE_MB). Omit it to use the recommended, adaptive size
targetPath string Optional WebDAV target directory. Must be inside WEBDAV_UPLOAD_DIR; relative paths are placed under it; ".." is rejected (400)
Response Example (HTTP 200)
JSON Response 
{
  "success": true,
  "uploadId": "a5496992-5356-4fa9-a383-0ef8b4c81d53",
  "filename": "dataset-sample.zip",
  "targetPath": "/EpochMedia",
  "stagingDir": "/EpochMedia/.staging_a5496992-5356-4fa9-a383-0ef8b4c81d53",
  "totalChunks": null,
  "chunkSize": null,
  "fileSize": 20971520,
  "recommendedChunkSize": 5242880,
  "minChunkSize": 1048576,
  "maxChunkSize": 52428800,
  "chunkTargetSeconds": 8,
  "message": "Upload session initialized successfully."
}
cURL Command Example
cURL CLI 
curl -X POST "http://api.fileuploader.commandos.rozsnorbert.hu/upload/start" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{"filename": "dataset-sample.zip", "totalChunks": 4}'
Sample Payload (JSON)
payload.json 
{
  "filename": "dataset-sample.zip",
  "fileSize": 20971520,
  "targetPath": "/EpochMedia/videos"
}
POST /upload/chunk • Upload Chunk Part
Auth Required
Description

Uploads a single chunk slice directly to the WebDAV staging directory. Employs 3-attempt exponential backoff retry on network drops.

Request Body (multipart/form-data)
Parameter Type Requirement Description
file binary/file Required The binary chunk slice data
uploadId string (UUID) Required The uploadId received from /upload/start
chunkIndex integer Required 0-indexed sequence number (0, 1, 2...)
totalChunks integer Optional Total chunk count (informational)
filename string Optional Original filename. REQUIRED when the session no longer exists (server restart), so the upload can resume
Response Example (HTTP 200)
JSON Response 
{
  "success": true,
  "uploadId": "a5496992-5356-4fa9-a383-0ef8b4c81d53",
  "chunkIndex": 0,
  "size": 5242880,
  "remotePath": "/EpochMedia/.staging_a549.../dataset-sample.zip.part0",
  "speedBytesPerSec": 3145728,
  "nextChunkSize": 10485760,
  "message": "Chunk 0 uploaded successfully to WebDAV."
}
cURL Command Example
cURL CLI 
curl -X POST "http://api.fileuploader.commandos.rozsnorbert.hu/upload/chunk" \
  -H "x-api-key: your-api-key" \
  -F "uploadId=a5496992-5356-4fa9-a383-0ef8b4c81d53" \
  -F "chunkIndex=0" \
  -F "file=@part0.bin"
POST /upload/finish • Finalize & Stream-Merge File
Auth Required
Description

Downloads all .part chunks from WebDAV, sequentially merges them via local stream pipeline (O(1) RAM usage), streams the final assembled file to WebDAV destination, and deletes staging parts. Before merging it verifies on WebDAV that exactly the parts 0..totalChunks-1 exist.

Request Body (application/json)
Parameter Type Requirement Description
uploadId string (UUID) Required Active upload session identifier
totalChunks integer Required Total number of chunk parts to merge
filename string Optional Filename fallback if session was restarted
targetPath string Optional Destination directory on WebDAV
Response Example (HTTP 200)
JSON Response 
{
  "success": true,
  "uploadId": "a5496992-5356-4fa9-a383-0ef8b4c81d53",
  "filename": "dataset-sample.zip",
  "destination": "/EpochMedia/dataset-sample.zip",
  "fileSize": 20971520,
  "totalChunks": 4,
  "message": "File successfully assembled and uploaded to WebDAV."
}
cURL Command Example
cURL CLI 
curl -X POST "http://api.fileuploader.commandos.rozsnorbert.hu/upload/finish" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{"uploadId": "a5496992-5356-4fa9-a383-0ef8b4c81d53", "totalChunks": 4}'
Sample Payload (JSON)
payload.json 
{
  "uploadId": "a5496992-5356-4fa9-a383-0ef8b4c81d53",
  "totalChunks": 4,
  "filename": "dataset-sample.zip"
}
POST /upload/failed • Abort Upload & Cleanup
Auth Required
Description

Triggered if chunk upload fails after retries. Immediately deletes all uploaded .part files and staging directories from WebDAV.

Request Body (application/json)
Parameter Type Requirement Description
uploadId string (UUID) Required Upload session identifier to abort
filename string Optional Filename fallback
Response Example (HTTP 200)
JSON Response 
{
  "success": true,
  "uploadId": "a5496992-5356-4fa9-a383-0ef8b4c81d53",
  "status": "aborted",
  "cleaned": true,
  "message": "Upload aborted and all temporary staging chunks deleted from WebDAV."
}
cURL Command Example
cURL CLI 
curl -X POST "http://api.fileuploader.commandos.rozsnorbert.hu/upload/failed" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{"uploadId": "a5496992-5356-4fa9-a383-0ef8b4c81d53"}'
Sample Payload (JSON)
payload.json 
{
  "uploadId": "a5496992-5356-4fa9-a383-0ef8b4c81d53"
}
GET /upload/status/:uploadId • Query Upload Status
Auth Required
Description

Returns the current progress, received chunk indexes, and timestamps of an active upload session.

Response Example (HTTP 200)
JSON Response 
{
  "uploadId": "a5496992-5356-4fa9-a383-0ef8b4c81d53",
  "filename": "dataset-sample.zip",
  "status": "uploading",
  "uploadedChunksCount": 3,
  "uploadedChunkIndexes": [
    0,
    1,
    2
  ],
  "totalChunks": 4,
  "createdAt": "2026-09-07T18:00:00.000Z",
  "lastActivityAt": "2026-09-07T18:00:15.000Z"
}
cURL Command Example
cURL CLI 
curl -X GET "http://api.fileuploader.commandos.rozsnorbert.hu/upload/status/a5496992-5356-4fa9-a383-0ef8b4c81d53" \
  -H "x-api-key: your-api-key"
GET /download • Stream File Download with Range Support
Auth Required
Description

Directly streams a file from WebDAV storage to client with O(1) memory usage. Supports HTTP Range (206 Partial Content) for resumable downloads / video seeking, and ?inline=true for in-browser media display. Supports authentication via x-api-key header or ?apiKey= query parameter.

Response Example (HTTP 200)
JSON Response 
undefined
cURL Command Example
cURL CLI 
curl -X GET "http://api.fileuploader.commandos.rozsnorbert.hu/download?path=/EpochMedia/dataset-sample.zip" \
  -H "x-api-key: your-api-key" \
  -o "dataset-sample.zip"
GET /download/info • Query File Metadata
Auth Required
Description

Retrieves file existence, size, MIME type, ETag, and last modified timestamp from WebDAV storage prior to downloading.

Response Example (HTTP 200)
JSON Response 
{
  "success": true,
  "file": {
    "path": "/EpochMedia/dataset-sample.zip",
    "filename": "dataset-sample.zip",
    "size": 20971520,
    "mimeType": "application/zip",
    "lastModified": "2026-09-07T18:05:00.000Z",
    "etag": "\"abc123\"",
    "type": "file"
  }
}
cURL Command Example
cURL CLI 
curl -X GET "http://api.fileuploader.commandos.rozsnorbert.hu/download/info?path=/EpochMedia/dataset-sample.zip" \
  -H "x-api-key: your-api-key"
GET /download/list • Browse WebDAV Directory
Auth Required
Description

Lists all files and subdirectories located inside a specified WebDAV folder.

Response Example (HTTP 200)
JSON Response 
{
  "success": true,
  "directory": "/EpochMedia",
  "count": 2,
  "items": [
    {
      "name": "dataset-sample.zip",
      "path": "/EpochMedia/dataset-sample.zip",
      "type": "file",
      "size": 20971520,
      "mimeType": "application/zip",
      "lastModified": "2026-09-07T18:05:00.000Z"
    },
    {
      "name": "subfolder",
      "path": "/EpochMedia/subfolder",
      "type": "directory",
      "size": null,
      "mimeType": "inode/directory",
      "lastModified": "2026-09-07T18:00:00.000Z"
    }
  ]
}
cURL Command Example
cURL CLI 
curl -X GET "http://api.fileuploader.commandos.rozsnorbert.hu/download/list?path=/EpochMedia" \
  -H "x-api-key: your-api-key"
DELETE /files • Delete File or Folder
Auth Required
Description

Deletes a file (or, with recursive=true, a folder with all its content) inside the folder of the API key. A key bound to a folder can only delete inside that folder; keys without a folder act on the whole WEBDAV_UPLOAD_DIR. The key folder itself and internal .staging_* folders cannot be deleted.

Request Body (query parameters)
Parameter Type Requirement Description
path string Required File or folder path, relative to the key folder (or absolute inside it). Also accepted as DELETE /files/
recursive boolean Optional Must be true to delete a folder
Response Example (HTTP 200)
JSON Response 
{
  "success": true,
  "deleted": {
    "path": "/EpochMedia/ugyfel1/videos/dataset.mp4",
    "type": "file"
  },
  "message": "file deleted."
}
cURL Command Example
cURL CLI 
curl -X DELETE "http://api.fileuploader.commandos.rozsnorbert.hu/files?path=videos/dataset.mp4" -H "x-api-key: your-api-key"
GET /health/key • API Key Health
Auth Required
Description

Status report limited to the calling API key: the key itself (name, folder, expiry, last use; never the secret), the state and size of its WebDAV folder and its own active uploads. No server-wide data (uptime, memory, other keys or folders). Add deep=true for a recursive (bounded) size scan of the folder.

Request Body (query parameters)
Parameter Type Requirement Description
deep boolean Optional true = count files recursively (at most 200 folder listings); default: top level only
Response Example (HTTP 200)
JSON Response 
{
  "status": "healthy",
  "timestamp": "2026-11-03T10:00:00.000Z",
  "key": {
    "type": "managed",
    "id": "b1c2...",
    "name": "Customer 1",
    "folder": "ugyfel1",
    "enabled": true,
    "expiresAt": null,
    "lastUsedAt": "2026-11-03T09:59:00.000Z"
  },
  "storage": {
    "rootDir": "/EpochMedia/ugyfel1",
    "reachable": true,
    "exists": true,
    "scope": "top-level",
    "complete": true,
    "fileCount": 12,
    "folderCount": 0,
    "totalBytes": 52428800
  },
  "uploads": {
    "active": 0,
    "sessions": []
  }
}
cURL Command Example
cURL CLI 
curl "http://api.fileuploader.commandos.rozsnorbert.hu/health/key" -H "x-api-key: your-api-key"
GET /docs • API Specification & Interactive Explorer
Public
Description

Returns this interactive API documentation page (HTML) or complete JSON schema (Accept: application/json).

Response Example (HTTP 200)
JSON Response 
undefined
cURL Command Example
cURL CLI 
curl -X GET "http://api.fileuploader.commandos.rozsnorbert.hu/docs" -H "Accept: application/json"