{"openapi":"3.1.0","info":{"title":"TGDirectory API","version":"1.1.0","description":"Read the public directory of Telegram channels, groups and bots (GET /api/v1/*), and list new ones (POST /api/channels/submit — reviewed by an AI pre-screen and a person before going live). Read limits: 60 requests/minute and 1000/day per IP; with an agent API key 300/minute and 5000/day per key. At most 20 results per page and 10 pages per query. Over a limit the answer is 429 with Retry-After."},"servers":[{"url":"https://telegramchannels.io"}],"components":{"securitySchemes":{"agentKey":{"type":"http","scheme":"bearer","description":"Optional. An agent API key raises the read limits to 300/minute and 5000/day per key."}},"schemas":{"Channel":{"type":"object","properties":{"slug":{"type":["string","null"]},"username":{"type":["string","null"],"description":"Telegram username, without @."},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"type":{"type":"string","enum":["channel","group","bot"]},"members":{"type":["integer","null"],"description":"Read from Telegram; null when not measured."},"rating":{"type":["object","null"],"description":"Withheld (null) below three ratings.","properties":{"value":{"type":"number"},"count":{"type":["integer","null"]}}},"category":{"type":["object","null"],"properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"language":{"type":["string","null"]},"verified":{"type":["string","null"],"description":"Verification badge label, when the listing carries one."},"photoUrl":{"type":["string","null"]},"url":{"type":["string","null"],"description":"The listing's page on the directory."},"telegramUrl":{"type":["string","null"]}}}},"responses":{"RateLimited":{"description":"Rate limited. Retry after the number of seconds in Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}}}}},"paths":{"/api/v1/channels":{"get":{"summary":"Search approved listings","description":"Paginated: at most 20 per page (default 10) and at most 10 pages per query — narrow with q, category, language or type to go further.","security":[{},{"agentKey":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":100},"description":"Matches title, username and description."},{"name":"category","in":"query","schema":{"type":"string"},"description":"A category slug or name (see /api/v1/categories)."},{"name":"language","in":"query","schema":{"type":"string"},"description":"A language code, e.g. en (see /api/v1/languages)."},{"name":"type","in":"query","schema":{"type":"string","enum":["channel","group","bot"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["members","rating","new"],"default":"members"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":10,"default":1}},{"name":"perPage","in":"query","schema":{"type":"integer","minimum":1,"maximum":20,"default":10}}],"responses":{"200":{"description":"A page of listings.","content":{"application/json":{"schema":{"type":"object","properties":{"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"page":{"type":"integer"},"perPage":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer","description":"Reachable pages, never more than 10."},"hasMore":{"type":"boolean"}}}}}},"400":{"description":"An invalid parameter, or a page past the cap."},"401":{"description":"An Authorization header with a key that is not valid."},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/channels/{ref}":{"get":{"summary":"Get one approved listing","security":[{},{"agentKey":[]}],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"},"description":"The listing slug, or the Telegram @username (a t.me link works too, URL-encoded)."}],"responses":{"200":{"description":"The listing.","content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"$ref":"#/components/schemas/Channel"}}}}}},"400":{"description":"Not a slug or a username."},"404":{"description":"No approved listing with that slug or username."},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/categories":{"get":{"summary":"Categories with listing counts","security":[{},{"agentKey":[]}],"responses":{"200":{"description":"{ categories: [{ slug, name, count, url }] }"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/languages":{"get":{"summary":"Language codes offered as filters","security":[{},{"agentKey":[]}],"responses":{"200":{"description":"{ languages: [{ code, name }] }"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/channels/submit":{"get":{"summary":"Usage information","responses":{"200":{"description":"How to use the submit endpoint."}}},"post":{"summary":"Submit one or more channels","description":"Lists each handle as a pending channel (reviewed before going live). Up to 500 handles per call.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channels":{"type":"array","items":{"type":"string"},"description":"Telegram handles or t.me links, e.g. [\"@foo\", \"https://t.me/bar\"]"},"channel":{"type":"string","description":"A single handle or t.me link."}}},"examples":{"list":{"value":{"channels":["@crypto_daily","https://t.me/ai_tools"]}},"single":{"value":{"channel":"@my_channel"}}}}}},"responses":{"200":{"description":"Nothing new (all duplicates/invalid)."},"201":{"description":"At least one channel submitted."},"400":{"description":"No channel handles found in the request."},"429":{"description":"Rate limited."}}}}}}