API documentation
Programmatic access to VorcaroFiles. Two HTTP surfaces, plus a couple of browser-facing pages that are not part of the API.
application/json./v/{folder_id} can list/modify files in that folder.
If a folder has an additional password, pass it in X-Folder-Password for JSON endpoints.
Direct file downloads via /d/{file_id} are always open — the file ID alone is the credential.
Upload
tus.io v1 · /flux/
Resumable, chunk-based uploads using the
tus.io v1 protocol.
Send the Tus-Resumable: 1.0.0 header on every request.
Initialize a new upload. The server allocates a tus upload ID and (optionally) creates a new folder.
Required headers
| name | type | description |
|---|---|---|
| Tus-Resumable | string | Must be 1.0.0 |
| Upload-Length | int64 | Total file size in bytes |
| Upload-Metadata | csv | Comma-separated key value-base64 pairs (see below) |
Upload-Metadata fields
Each value is base64-encoded UTF-8. Example: filename ZmlsZS50eHQ=,encrypt dHJ1ZQ==
| key | type | description |
|---|---|---|
| filename | string | Original file name |
| content_type | string | MIME type (e.g. image/png) |
| encrypt | bool | true to encrypt the file server-side with password |
| password | string | Required when encrypt=true. Never stored. |
| ttl_hours | int | Lifetime in hours. 0 = never. Capped by retention settings unless folder is premium. |
| folder_id | string | Attach to an existing folder. Omit to create a new one. |
mf_v_<folder_id>) must be present, or the upload is rejected with 403.
Response — 201 Created
Header Location contains the URL for subsequent PATCH/HEAD/DELETE requests.
Final response — after the last PATCH
JSON body and these headers:
| header / json key | description |
|---|---|
| X-File-Id / file_id | Public 40+ char file ID (used in /d/<id>) |
| X-Folder-Id / folder_id | Parent folder ID |
| X-Folder-New / folder_new | true if a new folder was created |
| X-Download-Url / download_url | Absolute or relative download URL |
| X-Folder-Url / folder_url | Folder admin URL — keep secret |
| expires_at / expires_iso | Unix seconds + ISO-8601 UTC expiration |
Example
# filename=file.txt, encrypt=true, password=hunter2, ttl_hours=168 curl -i -X POST "http://localhost:8080/flux/" \ -H "Tus-Resumable: 1.0.0" \ -H "Upload-Length: 1024" \ -H "Upload-Metadata: filename ZmlsZS50eHQ=,encrypt dHJ1ZQ==,password aHVudGVyMg==,ttl_hours MTY4"
Returns the current upload offset for resuming. Useful after a network drop.
Response — 200 OK
| header | description |
|---|---|
| Upload-Offset | Bytes already received by the server |
| Upload-Length | Total expected size |
Sends a chunk of bytes starting at Upload-Offset. Body is raw binary.
Required headers
| name | value |
|---|---|
| Tus-Resumable | 1.0.0 |
| Upload-Offset | Byte offset where this chunk begins |
| Content-Type | application/offset+octet-stream |
Returns 204 No Content. On the final chunk, returns 200 OK with the headers/body documented in POST /flux/.
Aborts an in-progress upload and discards every byte uploaded so far. Returns 204 No Content.
Folder API
/api/v1/folders/
Manage folder content programmatically. All responses are application/json.
Password set? Send
X-Folder-Password: <password> on every request. Wrong/missing password → 401.
Returns folder metadata and the list of non-deleted files inside.
Response — 200 OK
{
"id": "3kQ...",
"created_day": 20596,
"file_count": 2,
"total_bytes": 2048,
"premium": false,
"password_set": true,
"password_set_day": 20597,
"files": [ /* array of file objects */ ]
}
Permanently deletes the folder and every file inside. The on-disk blobs are removed.
{
"deleted": true,
"folder_id": "3kQ...",
"files_deleted": 2
}
Removes a single file from the folder. The file_id must belong to the given folder, otherwise 404.
Generates a new public file ID. The old /d/{old_file_id} URL stops working immediately.
The underlying encrypted blob is not moved or re-encrypted — only the URL token rotates.
429 Too Many Requests otherwise.
Response — 200 OK
{
"file_id": "newPublicId...",
"old_file_id": "oldPublicId...",
"download_url": "/d/newPublicId..."
}
Manages the folder password (Argon2id, irrecoverable). To change an existing password, you still send the current one in X-Folder-Password.
Request body
{ "new_password": "hunter2" } // or "" to remove
Minimum 4 characters. Removing the password makes the folder publicly accessible again (still requires the folder ID).
File API
/api/v1/files/Lookup file metadata by its public ID. No password needed — the file ID itself is the credential.
Returns metadata only (no binary). Use POST /d/{id} to download the bytes.
Response — 200 OK
{
"id": "V5pY...",
"original_name": "file.txt",
"content_type": "text/plain",
"size_bytes": 1024,
"encrypted": true,
"cipher": "age-v1",
"download_count": 0,
"expires_at": 1779494400,
"expires_iso": "2026-05-22T18:00:00Z",
"created_day": 20596,
"download_url": "/d/V5pY..."
}
Note: The parent folder_id is intentionally not exposed here. Anyone with the file ID can fetch metadata, but they should not learn which folder it belongs to.
Download
/d/{file_id}
For programmatic downloads, use POST — it streams the raw bytes as Content-Disposition: attachment.
The GET variant returns an HTML page meant for browsers (with a password prompt if the file is encrypted) and is not considered API.
Request body (optional)
Form field password is required when the file is encrypted, ignored otherwise.
password=hunter2
Response
200 OK— binary stream of the file401 Unauthorized— missing or wrong password404 Not Found— file expired, deleted, or unknown
Example
curl -X POST "http://localhost:8080/d/V5pY..." \ -d "password=hunter2" \ -o file.txt
Errors
status codesAll JSON endpoints return errors as {"error": "...", "code": "..."} with these status codes.