v1Checking status

Telegram Storage API

A small object-storage service. Files go into a private Telegram channel, MongoDB keeps the catalog, and you talk to a plain HTTP API with an API key.

Architecture

client ──▶ Next.js API ──▶ Telegram Bot API ──▶ private channel
              │                                   (file bytes, ≤19 MB parts)
              └──▶ MongoDB  (catalog: id → message ids → file_ids)

Telegram has no “list objects” API, so MongoDB is the source of truth for what exists. Downloads are streamed through the API; the bot token never leaves the server.

Endpoints

POST/api/filesUpload a file (multipart, up to 4 MB)
POST/api/files/uploadsStart a large upload (Blob staging token)
POST/api/files/completeFinish a large upload
GET/api/filesList files: page, limit, folder, search
GET/api/files/:idDownload (streams, supports Range)
GET/api/files/:id/urlSigned, expiring download URL
PATCH/api/files/:idMake a file public or private
DELETE/api/files/:idDelete file and Telegram messages
GET/api/public/:id/:namePublic file, no auth, CDN-cached
GET/api/healthDatabase and Telegram connectivity
POST/api/admin/syncBest-effort channel import

Every endpoint except /api/health and public files requires Authorization: Bearer <STORAGE_API_KEY>.

Quick start

# Upload
curl -X POST https://storage.example.com/api/files \
  -H "Authorization: Bearer $STORAGE_API_KEY" \
  -F "file=@image.png" -F "folder=projects"

# List
curl -H "Authorization: Bearer $STORAGE_API_KEY" \
  "https://storage.example.com/api/files?folder=projects&search=image"

# Download
curl -H "Authorization: Bearer $STORAGE_API_KEY" \
  https://storage.example.com/api/files/<id> -o image.png

# Delete
curl -X DELETE -H "Authorization: Bearer $STORAGE_API_KEY" \
  https://storage.example.com/api/files/<id>

Limits

Part size
Files are split into ≤19 MB Telegram documents, below the Bot API's 20 MB download limit.
Large uploads
Requests over 4.5 MB can't reach a Vercel function, so they are staged in Vercel Blob first and deleted once stored.
Deletes
Telegram only guarantees deleting messages younger than 48 hours. Older files leave the index, but their bytes may remain in the channel.
Sync
Bots can't read channel history. Sync only finds files posted by people in the last 24 hours.