{
	"info": {
		"description": "Telegram catalogue API. Search 1M channels, 150K chats and 100K bots by meaning using hybrid search (embedding similarity + BM25 keyword matches), or fetch the stored messages and profile details of channels, groups and bots by exact username.",
		"title": "Semagram",
		"version": "0.1.0",
		"x-guidance": "Use POST /api/agent/search to find Telegram channels, groups, and bots you cannot name: pass query param 'q' with your search text and optional 'limit' for max results (default 100, max 1000), priced at 0.01 USDC per 100 results. Use POST /api/agent/fetch when you already know the names: pass query param 'usernames' with up to 100 comma-separated Telegram usernames and get each one's profile details plus its stored messages (text and captions only, each tagged with the media kind), priced at 0.01 USDC per name. Both require x402 payment."
	},
	"openapi": "3.1.0",
	"paths": {
		"/api/agent/fetch": {
			"post": {
				"operationId": "fetch",
				"parameters": [
					{
						"description": "Telegram usernames, comma-separated. Between 1 and 100 of them; more is refused with 400 and charged nothing. Each name is charged for whether or not the catalogue holds it.",
						"in": "query",
						"name": "usernames",
						"required": true,
						"schema": {
							"type": "string"
						}
					}
				],
				"responses": {
					"200": {
						"content": {
							"application/json": {
								"schema": {
									"items": {
										"properties": {
											"avatar_url": {
												"type": "string"
											},
											"bio": {
												"type": "string"
											},
											"canonical_username": {
												"type": "string"
											},
											"commands": {
												"description": "A bot's commands, name to description",
												"type": "object"
											},
											"description": {
												"type": "string"
											},
											"lang": {
												"type": "string"
											},
											"mau": {
												"description": "Monthly active users. Bots only",
												"type": "integer"
											},
											"messages": {
												"description": "Stored posts, newest first. Present only for a channel, and then always an array — empty when we hold none. Absent entirely for a group, a bot or an absent name: Telegram publishes no readable history for any of them, so there is nothing to come back for. Text and captions only, never media files, and every post carries a kind saying what it was.",
												"items": {
													"properties": {
														"forwarded_from": {
															"description": "Where the post came from: the origin's username when the origin is public, `true` when the origin hid itself, absent when the post is original.",
															"type": [
																"string",
																"boolean"
															]
														},
														"id": {
															"type": "integer"
														},
														"image_count": {
															"type": "integer"
														},
														"kind": {
															"description": "What the post is. Always present, including for posts this API carries no text for: only text and captions are stored, never media files, so this is the only thing that says a post was a video rather than an empty message.",
															"enum": [
																"text",
																"photo",
																"video",
																"round_video",
																"voice",
																"sticker",
																"document",
																"media_group",
																"poll",
																"location",
																"contact",
																"invoice",
																"service",
																"unsupported",
																"unknown"
															],
															"type": "string"
														},
														"link": {
															"type": "string"
														},
														"posted_at": {
															"format": "date-time",
															"type": "string"
														},
														"reaction_count": {
															"type": "integer"
														},
														"text": {
															"description": "The post's text, or the caption of a media post. Absent when the post carried neither — check `kind` for what it was.",
															"type": "string"
														},
														"view_count": {
															"type": "integer"
														}
													},
													"required": [
														"id",
														"kind",
														"posted_at",
														"link"
													],
													"type": "object"
												},
												"type": "array"
											},
											"messages_scraped_at": {
												"description": "When the history was last read off Telegram successfully. Absent when that is not known.",
												"format": "date-time",
												"type": "string"
											},
											"name": {
												"type": "string"
											},
											"profile_scraped_at": {
												"description": "When the profile was last read off Telegram successfully. Absent when that is not known.",
												"format": "date-time",
												"type": "string"
											},
											"type": {
												"description": "channel, group, bot, or absent when the catalogue holds no such entity",
												"enum": [
													"channel",
													"group",
													"bot",
													"absent"
												],
												"type": "string"
											},
											"user_count": {
												"description": "Subscribers for a channel, members for a group. Never present for a bot.",
												"type": "integer"
											},
											"username": {
												"type": "string"
											},
											"uuid": {
												"type": "string"
											}
										},
										"required": [
											"type",
											"username"
										],
										"type": "object"
									},
									"type": "array"
								}
							}
						},
						"description": "One entry per name asked for, in the order asked"
					},
					"400": {
						"description": "No usernames given, or more than 100 of them. Nothing is charged."
					},
					"402": {
						"description": "Payment Required"
					},
					"502": {
						"description": "Upstream catalogue service unavailable"
					}
				},
				"summary": "Stored messages and profile details for named Telegram channels, groups, and bots",
				"tags": [
					"Fetch"
				],
				"x-payment-info": {
					"basePrice": "0.01",
					"pricingMode": "dynamic",
					"pricingRule": "names * basePrice",
					"protocols": [
						"x402",
						"mpp"
					]
				}
			}
		},
		"/api/agent/search": {
			"post": {
				"operationId": "search",
				"parameters": [
					{
						"description": "Semantic search query",
						"in": "query",
						"name": "q",
						"required": true,
						"schema": {
							"type": "string"
						}
					},
					{
						"description": "Maximum number of results. Price scales with limit (ceil(limit/100) * base price).",
						"in": "query",
						"name": "limit",
						"required": false,
						"schema": {
							"default": 100,
							"maximum": 1000,
							"minimum": 1,
							"type": "integer"
						}
					},
					{
						"description": "Language filter (ISO 639-1 code, e.g. \"en\", \"ru\")",
						"in": "query",
						"name": "lang",
						"required": false,
						"schema": {
							"type": "string"
						}
					},
					{
						"description": "Entity type filter (\"channel\", \"group\", or \"bot\")",
						"in": "query",
						"name": "kind",
						"required": false,
						"schema": {
							"enum": [
								"channel",
								"group",
								"bot"
							],
							"type": "string"
						}
					},
					{
						"description": "Minimum subscriber/member count",
						"in": "query",
						"name": "min_users",
						"required": false,
						"schema": {
							"type": "integer"
						}
					},
					{
						"description": "Maximum subscriber/member count",
						"in": "query",
						"name": "max_users",
						"required": false,
						"schema": {
							"type": "integer"
						}
					}
				],
				"responses": {
					"200": {
						"content": {
							"application/json": {
								"schema": {
									"items": {
										"properties": {
											"avatar_url": {
												"type": "string"
											},
											"bio": {
												"type": "string"
											},
											"description": {
												"type": "string"
											},
											"kind": {
												"type": "string"
											},
											"name": {
												"type": "string"
											},
											"user_count": {
												"type": "integer"
											},
											"username": {
												"type": "string"
											},
											"uuid": {
												"type": "string"
											}
										},
										"required": [
											"uuid",
											"username"
										],
										"type": "object"
									},
									"type": "array"
								}
							}
						},
						"description": "Successful response"
					},
					"402": {
						"description": "Payment Required"
					},
					"502": {
						"description": "Upstream search service unavailable"
					}
				},
				"summary": "Semantic search across Telegram channels, groups, and bots",
				"tags": [
					"Search"
				],
				"x-payment-info": {
					"basePrice": "0.01",
					"pricingMode": "dynamic",
					"pricingRule": "ceil(limit / 100) * basePrice",
					"protocols": [
						"x402",
						"mpp"
					]
				}
			}
		}
	},
	"x-discovery": {
		"ownershipProofs": []
	}
}