API for developers

The catalog of channels, chats, bots and mini apps, plus the state of our Telegram availability monitor, as JSON. Reading is free: 1000 requests a day per key.

The key

Created in your dashboard and sent in the x-api-key header. Do not put it in the query string: from there it lands in proxy logs and browser history.

Create a key in the dashboard

The ceiling

1000 requests a day per key. The counter resets at 00:00 UTC. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; over the ceiling you get 429 and Retry-After with the seconds left until the reset.

Try it

Replace KEY with your own and run this in a terminal.

curl -H "x-api-key: KEY" \
  "https://tg.place/api/v1/top?limit=3"

Endpoints

GET /api/v1/search?q=ai: Search the catalog.
GET /api/v1/listings/{slug}: One entry: metrics and the score with its breakdown and preliminary flag.
GET /api/v1/categories: Category trees per entry type. Empty ones are left out.
GET /api/v1/top?limit=10: Catalog top by Place Score — the same selection as the showcase.
GET /api/v1/status: State of the Signal monitor. The same data sits at /api/status without a key.

Errors

Every error has the same shape: a code, a line for a human and a link back to this page. Codes: no_key, bad_key, bad_request, not_found, rate_limited, internal.

{
  "error": {
    "code": "rate_limited",
    "message": "…",
    "docs": "https://tg.place/en/developers"
  }
}

Specification

The OpenAPI document is built from the same schemas that validate the requests, so it cannot drift from the behaviour.

openapi.json

Keys and limits

A key opens read access to the catalog through /api/v1. Free tier: 1000 requests a day per key, up to 5 keys per account.