API reference

A small HTTP API for uploading, inspecting, downloading, and deleting temporary files. Every file expires no later than 20 hours after upload and is deleted permanently.

Limits

Maximum 150 MB per file (enforced server-side)
Maximum 5 files per request
Maximum lifetime 20 hours — not extendable
Uploads are rejected when the temporary storage limit is reached

Authentication

Write and administrative endpoints require an API key, sent in the X-API-Key header. An administrator can create keys in the admin dashboard. Keys are shown once at creation time and stored only as a hash, so save the value immediately. Revoke a key at any time to invalidate it.

X-API-Key: tf_live_xxxxxxxxxxxxxxxxxxxx

Endpoints

POST/api/public/upload· API key required

Uploads 1–5 files as multipart/form-data. Repeat the files field once per file. Returns a link for each uploaded file.

curl -X POST https://your-host/api/public/upload \
  -H "X-API-Key: $TEMPFILES_API_KEY" \
  -F "files=@report.pdf" \
  -F "files=@screenshot.png"

{
  "files": [
    {
      "public_id": "0Xq7...",
      "filename": "report.pdf",
      "size": 184320,
      "mime_type": "application/pdf",
      "uploaded_at": "2026-01-01T09:00:00.000Z",
      "expires_at": "2026-01-02T05:00:00.000Z",
      "page_url": "https://your-host/f/0Xq7...",
      "download_url": "https://your-host/api/public/f/0Xq7..."
    }
  ]
}

GET/api/public/files/:publicId· No key required

Returns safe metadata for a file. Expired or deleted files return an error status.

curl https://your-host/api/public/files/0Xq7...

GET/api/public/f/:publicId· No key required

Streams the file contents. Expiry is checked on every request, so an expired file is refused even before the cleanup job removes it. Each successful download increments the download counter.

curl -OJ https://your-host/api/public/f/0Xq7...

DELETE/api/public/files/:publicId· API key required

Deletes a file immediately, before its expiry time.

curl -X DELETE https://your-host/api/public/files/0Xq7... \
  -H "X-API-Key: $TEMPFILES_API_KEY"

GET/api/public/admin/stats· API key required

Returns active file count, files uploaded today, storage used and limit, files expiring within the hour, and files awaiting cleanup.

curl https://your-host/api/public/admin/stats \
  -H "X-API-Key: $TEMPFILES_API_KEY"

GET/api/public/admin/files· API key required

Lists files. Optional query parameters: search (filename contains), status (all, active, expired, deleted, pending), and limit (1–200, default 50).

curl "https://your-host/api/public/admin/files?status=active&search=report&limit=20" \
  -H "X-API-Key: $TEMPFILES_API_KEY"

Errors

Errors return JSON shaped as { "error": { "code", "message" } }.

Status	Code	Meaning
400	invalid_request	Malformed request body or query parameter
400	no_files	No files were included
400	too_many_files	More than 5 files in one request
400	blocked_type	File extension is not allowed
400	empty_file	A file had no content
401	unauthorized	Missing, invalid, or revoked API key
404	not_found	No such file
410	expired	The file passed its expiry time
410	deleted	The file was already deleted
413	file_too_large	A file exceeds the 150 MB limit
429	rate_limited	Too many requests
500	server_error	Unexpected server or storage failure
507	storage_full	Temporary storage limit reached

Files are automatically deleted after a maximum of 20 hours.