API for developers

Read the directory from your own app or website. Every answer is JSON.

Getting a key

API keys are issued by the site team. Contact us and tell us what you are building.

Making a request

Send the key in the X-Api-Key header (or as Authorization: Bearer …). The base address is:

https://www.tggroups.com/api/v1

curl -H "X-Api-Key: YOUR_KEY" "https://www.tggroups.com/api/v1/links?type=group&per_page=10"

Each key may make 60 requests per minute. Past that the answer is 429 with a Retry-After header.

Answers

{ "success": true, "data": [ … ], "meta": { "page": 1, "per_page": 20, "total": 134, "last_page": 7 } }
{ "success": false, "error": { "code": "invalid_key", "message": "This API key is not valid." } }

Endpoints

Request	What it returns
`GET /`	Name of the site and what your key may do.
`GET /types`	The link types this directory accepts, each with its label, colour, icon name, button text and count label.
`GET /categories`	All categories with their number of links.
`GET /links`	A page of links. See the filters below.
`GET /links/{slug}`	One link.
`POST /links`	Submit a link (keys with the “submit” permission).

Filters for `GET /links`

Parameter	Meaning
`q`	Search in names, descriptions and tags.
`type`	One of: group, channel, bot, miniapp, stickers, emoji, folder, theme, profile.
`category`	Category slug or id. Sub-categories are included.
`country`	Two-letter country code, e.g. `IN`.
`language`	Language code, e.g. `en`.
`featured`	`1` to return featured links only.
`sort`	`newest` (default), `trending`, `popular`, `views` or `rating`.
`page`, `per_page`	Paging. `per_page` can be up to 50.

A link

{
  "slug": "daily-cricket-talk",
  "type": "group",
  "title": "Daily Cricket Talk",
  "handle": "@dailycrickettalk",
  "description": "Match previews, live score chat …",
  "image": null,
  "category": { "name": "Cricket", "slug": "cricket" },
  "tags": ["cricket", "ipl"],
  "country": "IN",
  "language": "en",
  "members": 8420,
  "views": 3063,
  "clicks": 1094,
  "featured": true,
  "verified": true,
  "page": "https://www.tggroups.com/link/daily-cricket-talk",
  "join": "https://www.tggroups.com/go/daily-cricket-talk",
  "added_at": "2026-10-06T09:12:00+00:00"
}

Send your visitors to join to open the link, or to page for the full details. handle is the public @username, or null for private invite links, sticker packs and other links without one. members is the number of members, subscribers or monthly users, depending on the type.

Submitting a link

curl -X POST "https://www.tggroups.com/api/v1/links" \
  -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://t.me/yourchannel", "category": "sports", "title": "My channel", "tags": ["cricket"], "country": "IN", "language": "en"}'

Only url and category are needed when the name can be read from the link. The answer has the link's status: approved or pending (waiting for a moderator). A link that is already listed, not recognised or refused answers 422 with the reason.

Error codes

missing_key and invalid_key (401) · forbidden (403) · not_found (404) · invalid (422) · rate_limited (429).