REST API — automate Telm from your own code

1What the API lets you do

The Telm REST API gives your own code the same reach as the dashboard: run any text through the anti-spam pipeline, look up a Telegram user before you let them in, read and change a group's protection settings, manage custom rules and whitelists, pull the moderation journal and analytics, and register webhooks for real-time events.

That turns Telm from a bot living inside your groups into infrastructure you can wire in anywhere — a website sign-up form, a CRM bot, your own Telegram bots, or a script that configures a hundred groups at once.

• Base URL: api.telm.com/api/public/v1 — a stable, versioned path (the v1 is the contract version).
• Every request and response is JSON over HTTPS.
• Interactive docs and the machine-readable OpenAPI 3.1 spec live on the developers page — load the spec into Postman, a code generator or an AI agent to scaffold an integration in minutes.
• Metered calls return X-Quota-Limit, X-Quota-Used and X-Quota-Reset headers on every response.

2How a request flows through Telm

The public API lives on its own path prefix, /api/public/, separate from the dashboard. Each call is authenticated by an API key rather than a browser session, checked against your plan and quota, run against the same live engine that moderates your groups, and returned as JSON.

Because the API reaches the same engine and data as the bot, anything you can see or change in the dashboard you can also do in code — and any change you make in code appears in the dashboard immediately.

• Requests are stateless: each one carries its own key and stands on its own.
• A key acts on behalf of your account and can only touch groups where your account is an admin.
• The spam-check endpoint reaches the exact production rules pipeline, so an API verdict matches what the bot would do in the group.

3Authentication with API keys

Every request is authenticated with an API key of the form tk_live_ followed by random characters — not your dashboard login. You create keys in your account and send the key in the Authorization header as a Bearer token, or in an X-API-Key header.

The full secret is shown once, at creation time. After that the dashboard lists a key only by its short prefix, so you can recognise it without ever storing the full value. If a key leaks, revoke it and issue a new one — revocation takes effect right away.

• Send the key as Authorization: Bearer tk_live_your_key_here (an X-API-Key header also works).
• Keys carry read or write scope — read for GET requests, write for anything that changes data. A read-only key cannot create or edit.
• You can hold up to ten active keys at once, so you can use a separate key per script or service.
• A missing or invalid key returns 401; a key without the required scope returns 403 insufficient_scope.

4Available endpoints

The API is organised around spam and user checks, group management, and account self-service. The single spam-check endpoint is open to every plan; the rest of the surface is part of Pro and Business.

• POST /spam/check — run one text through the same rules engine that moderates live traffic (every plan). An optional AI check can be enabled on Pro and above.
• POST /spam/check-batch — check up to 20 texts in one call, rules-only (Pro+).
• POST /users/check — look up a Telegram user: CAS status, Telm spam-decision signals and reputation in your groups (Pro+).
• GET /groups and GET /groups/{id} — list and read your groups (Pro+).
• GET and PATCH /groups/{id}/settings — read and change a group's protection settings (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules — manage custom moderation rules (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist — manage the group whitelist (Pro+).
• GET /groups/{id}/journal and GET /groups/{id}/analytics — read the moderation log and analytics (Pro+).
• GET/POST/PATCH/DELETE /webhooks — manage real-time event webhooks (Pro+).
• GET /usage and GET /me — check your quota and key information; these never consume quota (every plan).

5The spam-check endpoint in detail

POST /spam/check is the heart of the API and the one endpoint you can try on any plan. Send a JSON body with the text to check; the response returns a verdict, a numeric score, a confidence value and a recommended action you can apply in your own product.

A single text can be up to 10,000 characters. On Pro and above you can opt into an AI check for harder cases, drawn from a separate daily AI-check allowance. For high volume, the batch endpoint checks up to 20 texts in one call and counts quota per item.

• Use the verdict and score to decide what your own product does — block a form submission, flag a lead, or auto-remove a message in your own bot.
• The batch endpoint is rules-only; the AI ladder is available only on the single-text endpoint.
• Request bodies are capped (roughly 64 KB for a single check, 256 KB for a batch); oversized bodies return 413.

6Plans, rate limits and daily quotas

Access is metered two ways: a per-minute rate limit (a burst ceiling) and a daily call quota that resets at midnight UTC. Daily quotas are per account; the per-minute limit applies to each API key. You can try the single spam-check endpoint on any plan, but a real integration that touches rules, settings, batch checks and webhooks needs Pro or higher.

• Free — 100 calls/day, spam-check only.
• Basic — 1,000 calls/day, spam-check only.
• Pro — 10,000 calls/day, full API and webhooks, plus a daily AI-check allowance.
• Business — 50,000 calls/day, full API and webhooks, larger AI allowance.
• Per-minute rate limits scale too — higher plans get a much larger burst ceiling.

7Error handling and status codes

The API uses standard HTTP status codes with a machine-readable error code in the body. Build your client to read these codes and back off or prompt an upgrade rather than retrying blindly.

When you exceed your daily quota, a metered call returns 429 with a daily_quota_exceeded code, a Retry-After header, and a body listing your plan, limit, used count, reset time and an upgrade hint. Endpoints that need a higher plan return 403 plan_required with the required plan.

• 401 — missing or invalid API key.
• 403 plan_required — the endpoint needs Pro or higher.
• 403 insufficient_scope — the key lacks write scope for a changing call.
• 429 daily_quota_exceeded or rate_limit_exceeded — wait for the reset time or upgrade; honour the Retry-After header.
• Read the X-Quota-* response headers to stay ahead of the limit.

8Best practices for a solid integration

A few habits keep an integration reliable and secure as it grows.

• Store keys in a secrets manager, never in client-side code or a git repository; use a separate key per service so you can revoke one without breaking the others.
• Watch the X-Quota-Used and X-Quota-Limit headers (or poll GET /usage) and throttle before you hit the wall, not after.
• On 429, respect Retry-After and back off; on 403 plan_required, show an upgrade prompt rather than retrying.
• For real-time reactions, prefer webhooks over polling — let Telm push events to you.
• Rotate keys periodically, and immediately if one may have leaked.

9Common integration scenarios

The API is used for far more than moderating Telegram messages.

• Website and app sign-up: run submitted text or usernames through POST /spam/check before you accept a registration or a comment.
• Your own Telegram bots: reuse Telm intelligence in a bot that Telm does not manage by calling the check endpoint from your handler.
• Bulk configuration: script the same rules, whitelists and settings across dozens of groups with the settings and rules endpoints.
• Data and alerting: register webhooks to stream moderation events into a data warehouse, a dashboard or an alerting channel in real time.