Developers & API

Automating your workflow? You can list channels without the web form. Every submission is reviewed (an AI pre-screen plus human review) before it goes live — so the API is safe to open, and nothing is published automatically.

Read the directory (REST)

Search and look up approved listings as JSON. No key is needed, and every field returned is already public on the channel page — title, username, description, type, members, rating (withheld below three votes), category, language, verified badge and links.

curl "https://telegramchannels.io/api/v1/channels?q=crypto&language=en&type=channel&sort=members&perPage=10"
curl "https://telegramchannels.io/api/v1/channels/@telegram"
curl "https://telegramchannels.io/api/v1/categories"
curl "https://telegramchannels.io/api/v1/languages"

type is channel, group or bot; sort is members, rating or new. Pages hold at most 20 results and a query goes at most 10 pages deep — narrow the query with q, category, language or type to reach further.

Limits: 60 requests a minute and 1,000 a day per IP. With an agent API key (Authorization: Bearer …) the limits are 300 a minute and 5,000 a day per key. Over a limit the answer is 429 with a Retry-After header.

Submit a channel (REST)

Send one handle or many. Handles can be @name, a t.me/name link, or a bare name. Both fields are accepted: channels (an array) or channel (a single string).

curl -X POST https://telegramchannels.io/api/channels/submit \
  -H "Content-Type: application/json" \
  -d '{"channels": ["@crypto_daily", "https://t.me/ai_tools"]}'

Or from JavaScript:

await fetch("https://telegramchannels.io/api/channels/submit", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ channel: "@my_channel" }),
});

The response reports what happened to each handle:

{
  "ok": true,
  "submitted": 1,
  "duplicates": 1,
  "invalid": 0,
  "results": [
    { "input": "@crypto_daily", "handle": "crypto_daily", "status": "submitted", "channelId": "..." },
    { "input": "https://t.me/ai_tools", "handle": "ai_tools", "status": "duplicate", "channelId": "..." }
  ],
  "note": "Submitted channels are PENDING and go live after the AI pre-screen + review."
}

Bulk lists

Up to 500 handles per call. Larger lists: split across calls. Rate limit is 30 calls a minute (per account or IP), and nothing per hour. A GET on the same URL returns the usage as JSON.

Use it as an AI tool (MCP)

We run a Model Context Protocol server, so an AI assistant can list a channel as a native tool call. Point your MCP client at:

https://telegramchannels.io/api/mcp

Example client config (Streamable HTTP):

{
  "mcpServers": {
    "tgdirectory": { "url": "https://telegramchannels.io/api/mcp" }
  }
}

For a client that only speaks stdio, bridge it with npx mcp-remote https://telegramchannels.io/api/mcp. The tools are submit_channel({ channels: [...] }) and, to read, search_channels, get_channel, list_categories and list_languages — with the same page caps and limits as the REST read API.

Machine-readable specs

• OpenAPI: https://telegramchannels.io/api/openapi.json
• llms.txt: https://telegramchannels.io/llms.txt

What gets listed

Each submitted handle becomes a pending channel. The AI pre-screen blocks adult, gambling and illegal content; the rest is reviewed by a person before it appears in the directory. Metadata (title, members, photo) is fetched from Telegram automatically — you only send the handle.