Rage TG Downloader API

Getting access

1. Open the Telegram bot and send /start.
2. Redeem an API license key: /redeem YOUR-KEY. It activates API Access and adds 150 credits to your single main balance.
3. Send /api new to create an API key. The key is shown once — store it safely.

Authentication

Every request needs your API key in the Authorization header. Requests without a valid, active key are refused with 401.

Authorization: Bearer rage_sk_xxxxxxxxxxxxxxxxxxxxxxxx

Credits and quota

• There is exactly one credit balance, shared by the bot and the API.
• Premium accounts spend 1 credit per delivered media file. Nothing else is charged.
• Lifetime accounts are unlimited and are never charged.
• “API quota used” is a cumulative statistic of credits spent through the API — it is not a second balance.
• When the balance is insufficient the request returns 402; API Access itself stays active.

Delivery modes

The API works for websites, mobile apps, servers and Telegram bots. Choose per request with the delivery field:

• "files" (default) — the media is returned as expiring signed download URLs. Display or download them straight from your website or app; no Telegram bot needed.
• "telegram" — the media is delivered into your own Telegram chat with the bot. Requires you to have opened the bot with /start once.

File URLs stay valid for 24 hours and are unlisted — fetch or re-host them within that window if you need them longer.

GET /api/public/v1/me

Your plan, current balance, cumulative API quota used and the delivery modes this key can use.

curl https://downloaderr.lovable.app/api/public/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "plan": "PREMIUM",
  "api_access": true,
  "credits": 148,
  "unlimited": false,
  "api_quota_used": 2,
  "delivery_modes": ["files", "telegram"],
  "default_delivery": "files"
}

POST /api/public/v1/download

Saves one Telegram link. Supported links are public posts (https://t.me/channel/123), private posts (https://t.me/c/1234567890/123) and stories (https://t.me/channel/s/5). Private posts require your own Telegram account to be connected with /login — Telegram permissions are never bypassed. Telegram delivery always goes to your own chat; the API cannot send content to anyone else.

# Website / app: get download URLs back
curl -X POST https://downloaderr.lovable.app/api/public/v1/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://t.me/durov/123","delivery":"files"}'

{
  "job_id": "6f1c…",
  "content_type": "album",
  "media_count": 3,
  "partial": false,
  "truncated": false,
  "credits_charged": 3,
  "delivered_to": "files",
  "files": [
    {
      "kind": "photo",
      "filename": "telegram-123.jpg",
      "size": 184320,
      "mime": "image/jpeg",
      "url": "https://…/api-media/…?token=…",
      "expires_in": 86400
    }
  ]
}

# Telegram bot integration: delivered to your own chat
curl -X POST https://downloaderr.lovable.app/api/public/v1/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://t.me/durov/123","delivery":"telegram"}'

In a website you can render files[].url directly in an img /video tag, or link to it as a download.

GET /api/public/v1/jobs

Your most recent jobs. Optional ?limit= between 1 and 50 (default 20).

curl "https://downloaderr.lovable.app/api/public/v1/jobs?limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "jobs": [
    {
      "id": "6f1c…",
      "status": "COMPLETED",
      "content_type": "photo",
      "media_count": 1,
      "error_code": null,
      "created_at": "2026-01-01T10:00:00.000Z",
      "completed_at": "2026-01-01T10:00:04.000Z"
    }
  ]
}

Errors

{ "error": { "code": "QUOTA_EXCEEDED", "message": "…" } }

Limits

• Requests per minute per API key are set by the administrator (30 by default).
• One save request per account runs at a time.
• Keys can be revoked at any time with /api revoke KEY_ID.