REST API v1

API Documentation

Integrate TeleKeep into your workflows. Manage files, query stats, and automate your cloud storage via our REST API.

All API endpoints require a valid X-API-Key header. Business plan required.
Authentication
Generate your API key from the TeleKeep desktop app under Settings → API Keys. Pass it in every request using the X-API-Key header.
curl -H "X-API-Key: tk_your_api_key_here" \ https://your-server.com/api/v1/files

Alternatively, use Authorization: Bearer tk_... — both are supported.

Rate Limits

Each API key allows 100 requests / minute. Exceeding this returns 429 Too Many Requests.

Response HeaderDescription
X-RateLimit-LimitTotal requests allowed per day
X-RateLimit-RemainingRequests remaining today
Retry-AfterSeconds until limit resets (on 429)
Error Codes
CodeMeaning
400Bad Request — missing or invalid parameters
401Unauthorized — API key missing or invalid
403Forbidden — insufficient plan or permissions
404Not Found — resource does not exist
429Rate Limit Exceeded
500Internal Server Error
Files

Returns a paginated list of your files.

Query ParamTypeDefaultDescription
limitinteger50Max results (max 200)
offsetinteger0Skip first N results
searchstring—Filter by filename
{ "files": [ { "id": "abc123", "file_name": "report.pdf", "file_size": 1048576, "file_type": "document", "created_at": "2026-01-15T10:30:00Z" } ], "pagination": { "total": 42, "limit": 50, "offset": 0 } }

Returns metadata for a specific file by its ID.

GET /api/v1/files/abc123 X-API-Key: tk_your_key_here

Deactivates a file's public share link. Requires files:delete permission on the API key.

This does not permanently delete the file from Telegram — it only disables the share link.
Stats

Returns aggregate statistics for your account: total files, storage used, downloads served.

{ "totalFiles": 42, "totalSizeBytes": 5368709120, "totalSizeFormatted": "5.0 GB", "totalDownloads": 156, "activeShareLinks": 12 }
Teams

Returns all teams you are a member of, with your role in each.

{ "teams": [ { "id": "t1", "name": "Design Team", "role": "owner", "members": 4 } ] }
API Key Management

Returns your API keys list (actual key values are NOT returned for security).

Generates a new API key. Authentication is via desktop app HWID, not an existing API key.

Body FieldTypeRequiredDescription
namestringyesFriendly name for this key
permissionsstring[]yesfiles:read, files:write, files:delete, folders:manage
rate_limitintegernoCustom rate limit (default: 100/min)
POST /api/apikeys Content-Type: application/json { "name": "My Integration", "permissions": ["files:read", "files:write"] } // Response: { "key": "tk_live_abc123..." } ← Save this, shown only once!
The API key value is returned only once on creation. Store it securely.

Immediately revokes the API key, making any future requests with it return 401.