{ "openapi": "3.1.0", "info": { "title": "Telepath REST API", "version": "2026-11-05", "description": "30 public REST operations. OAuth Authorization Code with S256 PKCE and canonical resource https://telepath.lemma.company/mcp. POST is also used for read-only actions; consult each operation scope. Inputs match the REST allowlist; domain rules also apply. Success schemas describe known fields and allow additional metadata. Example IDs, text and results are synthetic.", "contact": { "name": "Telepath Support", "url": "https://t.me/hellolemma" } }, "servers": [ { "url": "https://telepath.lemma.company" } ], "externalDocs": { "description": "API Reference", "url": "https://telepath.lemma.company/api-reference" }, "paths": { "/api/v1/chats/search": { "get": { "operationId": "telegram_find_chat", "summary": "Find Telegram chats", "description": "Find a chat by name, username or numeric ID. This is not a global Telegram directory search.", "tags": [ "Chats & groups" ], "security": [ { "TelepathOAuth": [ "telegram.read" ] } ], "responses": { "200": { "description": "count and chats; search can include query. Chat entries include chat_id, name, type, username and archive coverage fields. Session reads add source, coverage and partial metadata. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "count": { "type": "integer" }, "chats": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "query": { "type": "string" }, "source": { "type": "string" }, "history_archived": { "type": "boolean" }, "effective_limit": { "type": "integer" }, "coverage": { "type": "string" }, "partial": { "type": "boolean" }, "setup_required": { "type": "string" }, "history_notice": { "type": "string" } } }, "example": { "count": 1, "chats": [ { "chat_id": 123456789, "name": "Example contact", "type": "private", "username": null, "message_count": 1 } ] } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Search text; Notes search also accepts an empty string." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum results; source-specific caps may be lower. No Return All or implicit pagination. Default 20 for archive reads." } } ] } }, "/api/v1/messages/search": { "get": { "operationId": "telegram_search_messages", "summary": "Search Telegram messages", "description": "Search available message text. Optionally narrow to a chat and a lower date bound.", "tags": [ "Chats & groups" ], "security": [ { "TelepathOAuth": [ "telegram.read" ] } ], "responses": { "200": { "description": "count and messages; single-chat reads include chat, search includes query, and date-filtered reads can include since. Message entries include chat_id, message_id, date, direction, text, text_source, sender and available media/transcript metadata. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "count": { "type": "integer" }, "messages": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "chat": { "type": "object", "additionalProperties": true }, "query": { "type": "string" }, "since": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "history_archived": { "type": "boolean" }, "effective_limit": { "type": "integer" }, "coverage": { "type": "string" }, "partial": { "type": "boolean" }, "setup_required": { "type": "string" }, "history_notice": { "type": "string" } } }, "example": { "count": 1, "messages": [ { "chat_id": 123456789, "message_id": 42, "chat_name": "Example contact", "date": "2026-11-05T08:00:00.000Z", "direction": "incoming", "text": "Could you send the details?", "text_source": "written", "message_type": "text" } ] } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Search text; Notes search also accepts an empty string." } }, { "name": "chat_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Nonzero safe integer identifying a chat. JSON bodies use numbers; GET parameters are decimal strings on the wire.", "not": { "const": 0 } } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "ISO 8601 lower date bound, with Z or an explicit UTC offset." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum results; source-specific caps may be lower. No Return All or implicit pagination. Default 30 for archive reads." } } ] } }, "/api/v1/chats/{chat_id}/messages": { "get": { "operationId": "telegram_get_messages", "summary": "Read one chat", "description": "Read a bounded message window in a chat. The REST gateway requires this chat to exist in the account archive before delegating a read.", "tags": [ "Chats & groups" ], "security": [ { "TelepathOAuth": [ "telegram.read" ] } ], "responses": { "200": { "description": "count and messages; single-chat reads include chat, search includes query, and date-filtered reads can include since. Message entries include chat_id, message_id, date, direction, text, text_source, sender and available media/transcript metadata. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "count": { "type": "integer" }, "messages": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "chat": { "type": "object", "additionalProperties": true }, "query": { "type": "string" }, "since": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "history_archived": { "type": "boolean" }, "effective_limit": { "type": "integer" }, "coverage": { "type": "string" }, "partial": { "type": "boolean" }, "setup_required": { "type": "string" }, "history_notice": { "type": "string" } } }, "example": { "count": 1, "messages": [ { "chat_id": 123456789, "message_id": 42, "chat_name": "Example contact", "date": "2026-11-05T08:00:00.000Z", "direction": "incoming", "text": "Could you send the details?", "text_source": "written", "message_type": "text" } ] } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "parameters": [ { "name": "chat_id", "in": "path", "required": true, "description": "A nonzero safe integer; this chat must exist in the account archive.", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "not": { "const": 0 } } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "ISO 8601 upper date bound, with Z or an explicit UTC offset." } }, { "name": "since", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/telegram_get_messagesInput/properties/before", "description": "ISO 8601 lower date bound, with Z or an explicit UTC offset." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum results; source-specific caps may be lower. No Return All or implicit pagination. Default 50 for archive reads." } } ] }, "post": { "operationId": "telegram_send_message", "summary": "Send a message", "description": "Send to a known private Business or group chat. Business replies require reply permission and an incoming message within the last 24 hours; groups send as the bot. Use channel post operations for channels. Ordinary sends have no idempotency key.", "tags": [ "Chats & groups" ], "security": [ { "TelepathOAuth": [ "telegram.write" ] } ], "responses": { "200": { "description": "sent, chat_id, chat_name, message_id, date and text. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "sent": { "type": "boolean" }, "chat_id": { "type": "integer" }, "chat_name": { "type": "string" }, "message_id": { "type": "integer" }, "date": { "type": "string" }, "text": { "type": "string" } } }, "example": { "sent": true, "chat_id": 123456789, "chat_name": "Example contact", "message_id": 43, "date": "2026-11-05T08:01:00.000Z", "text": "Thanks for your message." } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/telegram_send_messageInput" }, "example": { "text": "Thanks for your message." } } } }, "parameters": [ { "name": "chat_id", "in": "path", "required": true, "description": "A nonzero safe integer; this chat must exist in the account archive.", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "not": { "const": 0 } } } ] } }, "/api/v1/messages/photos": { "post": { "operationId": "telegram_get_photos", "summary": "Get multiple archived photos", "description": "Retrieve up to five photos from one archived chat. Returns photo data and expiring links; n8n does not render the ChatGPT photo widget.", "tags": [ "Chats & groups" ], "security": [ { "TelepathOAuth": [ "telegram.read" ] } ], "responses": { "200": { "description": "count, bytes_per_photo and photos. Each entry has message_id and photo fields, or an error for that item; HTTP 200 does not mean every photo loaded. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "count": { "type": "integer" }, "bytes_per_photo": { "type": "integer" }, "photos": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "example": { "count": 1, "bytes_per_photo": 250000, "photos": [ { "message_id": 42, "data": "", "mimeType": "image/jpeg", "bytes": 12345, "caption": null, "url": null } ] } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/telegram_get_photosInput" }, "example": { "chat_id": 123456789, "message_ids": [ 42 ] } } } } } }, "/api/v1/bot/messages": { "post": { "operationId": "telegram_bot_direct_messages", "summary": "List bot inbox messages", "description": "Read the bot's separate direct-message inbox. Never mix this line with private Business chats, even when chat IDs match.", "tags": [ "Bot inbox" ], "security": [ { "TelepathOAuth": [ "telegram.read" ] } ], "responses": { "200": { "description": "count, note and messages. Entries use line=bot_dm, sender display name, date, text and also_has_business_chat. This inbox is separate from Business chats and channel DMs. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "count": { "type": "integer" }, "note": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "example": { "count": 1, "messages": [ { "chat_id": 123456789, "message_id": 42, "from": "Example contact", "date": "2026-11-05T08:00:00.000Z", "text": "Hello", "line": "bot_dm", "also_has_business_chat": false } ] } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/telegram_bot_direct_messagesInput" }, "example": { "limit": 10 } } } } } }, "/api/v1/bot/reply": { "post": { "operationId": "telegram_bot_dm_reply", "summary": "Reply in the bot inbox", "description": "Send an authorized reply as the bot to someone present in this account's bot inbox. Does not reply in the owner's Business chat. Never automatically retry uncertain delivery.", "tags": [ "Bot inbox" ], "security": [ { "TelepathOAuth": [ "telegram.write" ] } ], "responses": { "200": { "description": "ok, chat_id, sent_as and message_id. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "ok": { "type": "boolean" }, "chat_id": { "type": "integer" }, "sent_as": { "type": "string" }, "message_id": { "type": "integer" } } }, "example": { "ok": true, "chat_id": 123456789, "sent_as": "the bot", "message_id": 43 } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/telegram_bot_dm_replyInput" }, "example": { "chat_id": 123456789, "text": "Thanks for your message." } } } } } }, "/api/v1/bot/reaction": { "post": { "operationId": "telegram_bot_dm_react", "summary": "React in the bot inbox", "description": "Set a reaction as the bot on a message in this account's separate bot inbox. Omit emoji to remove the reaction.", "tags": [ "Bot inbox" ], "security": [ { "TelepathOAuth": [ "telegram.write" ] } ], "responses": { "200": { "description": "ok, chat_id, message_id, reaction, removed and reacted_as. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "ok": { "type": "boolean" }, "chat_id": { "type": "integer" }, "message_id": { "type": "integer" }, "reaction": { "type": [ "string", "null" ] }, "removed": { "type": "boolean" }, "reacted_as": { "type": "string" } } }, "example": { "ok": true, "chat_id": 123456789, "message_id": 42, "reaction": "👍", "removed": false, "reacted_as": "the bot" } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/telegram_bot_dm_reactInput" }, "example": { "chat_id": 123456789, "message_id": 42, "emoji": "👍" } } } } } }, "/api/v1/archive/forget": { "post": { "operationId": "telegram_forget", "summary": "Delete archived messages", "description": "Permanently delete Telepath archived messages in the specified scope. Does not delete messages in Telegram. Requires the account's archive deletion capability and explicit confirmation. Provide chat_id, before, or both. Provide chat_id, before, or both; confirmed must be true. The scope is permanent archive deletion, not deletion from Telegram.", "tags": [ "Archive" ], "security": [ { "TelepathOAuth": [ "telegram.write" ] } ], "responses": { "200": { "description": "forgotten (row count), chat_id or null, before or null, and a note about retained copies. This removes archive data, not the Telegram conversation. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "forgotten": { "type": "integer" }, "chat_id": { "type": [ "integer", "null" ] }, "before": { "type": [ "string", "null" ] }, "note": { "type": "string" } } }, "example": { "forgotten": 3, "chat_id": 123456789, "before": null, "note": "Removed from the archive. Telegram retains its copy." } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/telegram_forgetInput" }, "example": { "chat_id": 123456789, "confirmed": true } } } } } }, "/api/v1/chats/list": { "post": { "operationId": "telegram_list_chats", "summary": "List Telegram chats", "description": "List archived chats, including connected channels. An empty archive is not proof that Telegram has no messages.", "tags": [ "Chats & groups" ], "security": [ { "TelepathOAuth": [ "telegram.read" ] } ], "responses": { "200": { "description": "count and chats; search can include query. Chat entries include chat_id, name, type, username and archive coverage fields. Session reads add source, coverage and partial metadata. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "count": { "type": "integer" }, "chats": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "query": { "type": "string" }, "source": { "type": "string" }, "history_archived": { "type": "boolean" }, "effective_limit": { "type": "integer" }, "coverage": { "type": "string" }, "partial": { "type": "boolean" }, "setup_required": { "type": "string" }, "history_notice": { "type": "string" } } }, "example": { "count": 1, "chats": [ { "chat_id": 123456789, "name": "Example contact", "type": "private", "username": null, "message_count": 1 } ] } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/telegram_list_chatsInput" }, "example": { "limit": 10 } } } } } }, "/api/v1/messages/recent": { "post": { "operationId": "telegram_recent_messages", "summary": "Read recent messages", "description": "Read recent saved messages across chats. New collection starts after Telegram connection; old history needs import.", "tags": [ "Chats & groups" ], "security": [ { "TelepathOAuth": [ "telegram.read" ] } ], "responses": { "200": { "description": "count and messages; single-chat reads include chat, search includes query, and date-filtered reads can include since. Message entries include chat_id, message_id, date, direction, text, text_source, sender and available media/transcript metadata. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "count": { "type": "integer" }, "messages": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "chat": { "type": "object", "additionalProperties": true }, "query": { "type": "string" }, "since": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "history_archived": { "type": "boolean" }, "effective_limit": { "type": "integer" }, "coverage": { "type": "string" }, "partial": { "type": "boolean" }, "setup_required": { "type": "string" }, "history_notice": { "type": "string" } } }, "example": { "count": 1, "messages": [ { "chat_id": 123456789, "message_id": 42, "chat_name": "Example contact", "date": "2026-11-05T08:00:00.000Z", "direction": "incoming", "text": "Could you send the details?", "text_source": "written", "message_type": "text" } ] } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/telegram_recent_messagesInput" }, "example": { "limit": 20 } } } } } }, "/api/v1/messages/file": { "post": { "operationId": "telegram_get_file", "summary": "Read an archived file", "description": "Retrieve file metadata, an expiring link and extracted text when supported. Imported files without stored Telegram file IDs may be unavailable. Do not share download links with other users.", "tags": [ "Chats & groups" ], "security": [ { "TelepathOAuth": [ "telegram.read" ] } ], "responses": { "200": { "description": "filename, mimeType, bytes, message_type, caption, expiring url and optional extracted text. Inspect text_error, text_truncated and line ranges; media in a text-only export may be unavailable. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "filename": { "type": "string" }, "mimeType": { "type": "string" }, "bytes": { "type": "integer" }, "message_type": { "type": "string" }, "caption": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "text_engine": { "type": [ "string", "null" ] }, "text_truncated": { "type": "boolean" }, "text_error": { "type": [ "string", "null" ] }, "from_line": { "type": [ "integer", "null" ] }, "to_line": { "type": [ "integer", "null" ] }, "total_lines": { "type": [ "integer", "null" ] } } }, "example": { "filename": "example.txt", "mimeType": "text/plain", "bytes": 7, "message_type": "document", "caption": null, "url": null, "text": "Example", "text_truncated": false, "text_error": null } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/telegram_get_fileInput" }, "example": { "chat_id": 123456789, "message_id": 42, "include_text": true } } } } } }, "/api/v1/messages/photo": { "post": { "operationId": "telegram_get_photo", "summary": "Get an archived photo", "description": "Return photo data and metadata through Telepath's existing media loader. Rendering or image understanding depends on the client; this is not an image-analysis endpoint.", "tags": [ "Chats & groups" ], "security": [ { "TelepathOAuth": [ "telegram.read" ] } ], "responses": { "200": { "description": "Base64 data, mimeType, bytes, caption and an expiring url when available. This retrieves an image; it does not analyze it. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "data": { "type": "string" }, "mimeType": { "type": "string" }, "bytes": { "type": "integer" }, "caption": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } }, "example": { "data": "", "mimeType": "image/jpeg", "bytes": 12345, "caption": null, "url": null } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/telegram_get_photoInput" }, "example": { "chat_id": 123456789, "message_id": 42 } } } } } }, "/api/v1/messages/send-media": { "post": { "operationId": "telegram_send_media", "summary": "Send a photo or document", "description": "Confirm recipient and media before sending. Supply exactly one source: public HTTP(S) URL or from_chat_id plus from_message_id in your archive. Private messages use Business permissions; groups send as the bot. Never retry automatically after uncertain delivery. Provide exactly one source: url OR both from_chat_id and from_message_id. A public URL must be HTTP(S); archive references must belong to this account. Caption maximum 1024 characters.", "tags": [ "Chats & groups" ], "security": [ { "TelepathOAuth": [ "telegram.write" ] } ], "responses": { "200": { "description": "sent, kind, chat_id, chat_name, message_id, filename, caption and sent_as. Delivery may be uncertain after a timeout. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "sent": { "type": "boolean" }, "kind": { "type": "string" }, "chat_id": { "type": "integer" }, "chat_name": { "type": "string" }, "message_id": { "type": "integer" }, "filename": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "sent_as": { "type": "string" } } }, "example": { "sent": true, "kind": "document", "chat_id": 123456789, "chat_name": "Example contact", "message_id": 44, "filename": "example.pdf", "caption": null, "sent_as": "you" } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/telegram_send_mediaInput" }, "example": { "chat_id": 123456789, "url": "https://example.com/example.pdf", "as_document": true } } } } } }, "/api/v1/messages/edit": { "post": { "operationId": "telegram_edit_message", "summary": "Edit a sent message", "description": "Confirm the exact replacement and recipient. Only eligible outgoing messages can be edited. Use dedicated post tools for channel posts.", "tags": [ "Chats & groups" ], "security": [ { "TelepathOAuth": [ "telegram.write" ] } ], "responses": { "200": { "description": "edited, chat_id, message_id and replacement text. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "edited": { "type": "boolean" }, "chat_id": { "type": "integer" }, "message_id": { "type": "integer" }, "text": { "type": "string" } } }, "example": { "edited": true, "chat_id": 123456789, "message_id": 43, "text": "Updated reply." } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/telegram_edit_messageInput" }, "example": { "chat_id": 123456789, "message_id": 43, "text": "Updated reply." } } } } } }, "/api/v1/messages/mark-read": { "post": { "operationId": "telegram_mark_read", "summary": "Mark a conversation read", "description": "Mark a Business conversation read through Telegram, up to the given message or the newest known message. This changes the unread state; ordinary archive reads do not.", "tags": [ "Chats & groups" ], "security": [ { "TelepathOAuth": [ "telegram.write" ] } ], "responses": { "200": { "description": "marked_read, chat_id, chat_name and up_to_message_id. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "marked_read": { "type": "boolean" }, "chat_id": { "type": "integer" }, "chat_name": { "type": "string" }, "up_to_message_id": { "type": "integer" } } }, "example": { "marked_read": true, "chat_id": 123456789, "chat_name": "Example contact", "up_to_message_id": 42 } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/telegram_mark_readInput" }, "example": { "chat_id": 123456789, "message_id": 42 } } } } } }, "/api/v1/messages/reaction": { "post": { "operationId": "telegram_set_reaction", "summary": "Set or remove a reaction", "description": "Confirm the target and emoji. Reacts as the bot in supported groups or authorized connected channels; private Business reactions are unsupported. Omit emoji to remove the bot's reaction.", "tags": [ "Chats & groups" ], "security": [ { "TelepathOAuth": [ "telegram.write" ] } ], "responses": { "200": { "description": "For a group: ok, chat_id, chat_name, message_id, reaction, removed and reacted_as. A channel result instead uses emoji and sent_as. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "ok": { "type": "boolean" }, "chat_id": { "type": "integer" }, "message_id": { "type": "integer" }, "reaction": { "type": [ "string", "null" ] }, "removed": { "type": "boolean" }, "reacted_as": { "type": "string" }, "emoji": { "type": [ "string", "null" ] }, "sent_as": { "type": "string" } } }, "example": { "ok": true, "chat_id": -1001234567890, "chat_name": "Example group", "message_id": 42, "reaction": "👍", "removed": false, "reacted_as": "the bot" } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/telegram_set_reactionInput" }, "example": { "chat_id": -1001234567890, "message_id": 42, "emoji": "👍" } } } } } }, "/api/v1/notes/search": { "post": { "operationId": "kb_search_notes", "summary": "Search notes", "description": "Search this account's Notes. Empty query lists recent notes. Optionally filter by tag.", "tags": [ "Notes" ], "security": [ { "TelepathOAuth": [ "telegram.read" ] } ], "responses": { "200": { "description": "count and notes; search also includes query. List/search entries are note summaries, without full body, links or backlinks; use notes/get for those. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "count": { "type": "integer" }, "query": { "type": "string" }, "notes": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "example": { "count": 1, "notes": [ { "id": 17, "title": "Follow up", "type": "note", "tags": [], "task_status": null, "reminder": null, "created_at": "2026-11-05T08:00:00.000Z", "updated_at": "2026-11-05T08:00:00.000Z" } ] } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/kb_search_notesInput" }, "example": { "query": "Follow up", "limit": 10 } } } } } }, "/api/v1/notes/get": { "post": { "operationId": "kb_get_note", "summary": "Read a note", "description": "Read one note, task, project or person with links and backlinks. Supply its ID or exact title. Provide id or exact title. If both are supplied, ID selects the note.", "tags": [ "Notes" ], "security": [ { "TelepathOAuth": [ "telegram.read" ] } ], "responses": { "200": { "description": "The note object: id, title, body, tags, type, task_status, reminder, created_at, updated_at, links and backlinks. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "body": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "type": { "type": "string" }, "task_status": { "type": [ "string", "null" ] }, "reminder": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "links": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "backlinks": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "example": { "id": 17, "title": "Follow up", "body": "Send the requested details.", "tags": [], "type": "note", "task_status": null, "reminder": null, "created_at": "2026-11-05T08:00:00.000Z", "updated_at": "2026-11-05T08:00:00.000Z", "links": [], "backlinks": [] } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/kb_get_noteInput" }, "example": { "id": 17 } } } } } }, "/api/v1/notes/list": { "post": { "operationId": "kb_list_notes", "summary": "List notes", "description": "List recent notes, tasks and projects. Filter by tag when needed.", "tags": [ "Notes" ], "security": [ { "TelepathOAuth": [ "telegram.read" ] } ], "responses": { "200": { "description": "count and notes; search also includes query. List/search entries are note summaries, without full body, links or backlinks; use notes/get for those. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "count": { "type": "integer" }, "query": { "type": "string" }, "notes": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "example": { "count": 1, "notes": [ { "id": 17, "title": "Follow up", "type": "note", "tags": [], "task_status": null, "reminder": null, "created_at": "2026-11-05T08:00:00.000Z", "updated_at": "2026-11-05T08:00:00.000Z" } ] } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/kb_list_notesInput" }, "example": { "limit": 10 } } } } } }, "/api/v1/notes/create": { "post": { "operationId": "kb_create_note", "summary": "Create a note or task", "description": "Save user-authorized content. Titles are unique; use [[Title]] links and tags. Types: note, project, person, task. Only explicitly authorized reminders on open tasks may be scheduled. A quota failure means the save did not happen. Search before creating duplicates. Titles are trimmed, unique and nonempty. A reminder is allowed only on an open task. A reminder time must be valid, in the future and within five years, with an IANA timezone. Reminder quota rejection means nothing was saved.", "tags": [ "Notes" ], "security": [ { "TelepathOAuth": [ "telegram.write" ] } ], "responses": { "200": { "description": "The note object: id, title, body, tags, type, task_status, reminder, created_at, updated_at, links and backlinks. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "body": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "type": { "type": "string" }, "task_status": { "type": [ "string", "null" ] }, "reminder": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "links": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "backlinks": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "example": { "id": 17, "title": "Follow up", "body": "Send the requested details.", "tags": [], "type": "note", "task_status": null, "reminder": null, "created_at": "2026-11-05T08:00:00.000Z", "updated_at": "2026-11-05T08:00:00.000Z", "links": [], "backlinks": [] } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/kb_create_noteInput" }, "example": { "title": "Follow up", "body": "Send the requested details." } } } } } }, "/api/v1/notes/update": { "post": { "operationId": "kb_update_note", "summary": "Update a note or task", "description": "Read before editing. Use ID when renaming; otherwise title addresses the existing note. Omitted fields are preserved, append adds body text, tags replaces tags. reminder:null cancels; completing a task cancels its reminder. Confirm destructive replacements. Do not automatically retry append operations. Provide id or exact title. With id, title renames the note; otherwise title selects it. Omitted fields are preserved. append=true appends body; tags replaces tags, including an empty array. A reminder is allowed only on an open task; reminder=null cancels it. Completing a task cancels its reminder.", "tags": [ "Notes" ], "security": [ { "TelepathOAuth": [ "telegram.write" ] } ], "responses": { "200": { "description": "The note object: id, title, body, tags, type, task_status, reminder, created_at, updated_at, links and backlinks. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "body": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "type": { "type": "string" }, "task_status": { "type": [ "string", "null" ] }, "reminder": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "links": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "backlinks": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "example": { "id": 17, "title": "Follow up", "body": "Send the requested details.", "tags": [], "type": "note", "task_status": null, "reminder": null, "created_at": "2026-11-05T08:00:00.000Z", "updated_at": "2026-11-05T08:00:00.000Z", "links": [], "backlinks": [] } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/kb_update_noteInput" }, "example": { "id": 17, "body": "Updated details." } } } } } }, "/api/v1/notes/delete": { "post": { "operationId": "kb_delete_note", "summary": "Delete a note", "description": "Permanently delete the chosen note after user confirmation. Also cancels its task reminder. Supply ID or exact title. Provide id or exact title. If both are supplied, ID selects the note. Confirm deletion before sending.", "tags": [ "Notes" ], "security": [ { "TelepathOAuth": [ "telegram.write" ] } ], "responses": { "200": { "description": "deleted, id and title. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "deleted": { "type": "boolean" }, "id": { "type": "integer" }, "title": { "type": "string" } } }, "example": { "deleted": true, "id": 17, "title": "Follow up" } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/kb_delete_noteInput" }, "example": { "id": 17 } } } } } }, "/api/v1/reminders/create": { "post": { "operationId": "create_reminder", "summary": "Create a reminder", "description": "Schedule a one-time reminder only to the authenticated account owner. Clarify time, timezone and text; only schedule when authorized. Reuse request_id and identical details on retry. Creation allowance is shared with task reminders. Scheduled does not mean delivered. Use a future ISO 8601 date with Z or an explicit offset, within five years, plus a valid IANA timezone. An optional request_id must be reused only with identical details. Creation allowance is shared with task reminders.", "tags": [ "Reminders" ], "security": [ { "TelepathOAuth": [ "telegram.write" ] } ], "responses": { "200": { "description": "reminder, created and quota. An identical request_id replay returns created=false. Scheduled is not delivered. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "reminder": { "type": "object", "additionalProperties": true }, "created": { "type": "boolean" }, "quota": { "type": "object", "additionalProperties": true } } }, "example": { "reminder": { "id": "r_example_reminder", "kind": "standalone", "note_id": null, "at": "2027-01-15T09:00:00.000Z", "timezone": "Europe/London", "text": "Follow up", "status": "scheduled" }, "created": true } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_reminderInput" }, "example": { "text": "Follow up", "at": "2027-01-15T09:00:00Z", "timezone": "Europe/London", "request_id": "reminder-example-001" } } } } } }, "/api/v1/reminders/list": { "post": { "operationId": "list_reminders", "summary": "List reminders", "description": "List standalone/task reminders and delivery states. Available regardless of remaining creation allowance. By default excludes done/cancelled. Uncertain is not delivered.", "tags": [ "Reminders" ], "security": [ { "TelepathOAuth": [ "telegram.read" ] } ], "responses": { "200": { "description": "count, total, reminders, next_offset (or null) and quota. This endpoint supports offset pagination. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "count": { "type": "integer" }, "total": { "type": "integer" }, "reminders": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "next_offset": { "type": [ "integer", "null" ] }, "quota": { "type": "object", "additionalProperties": true } } }, "example": { "count": 1, "total": 1, "reminders": [ { "id": "r_example_reminder", "kind": "standalone", "note_id": null, "at": "2027-01-15T09:00:00.000Z", "timezone": "Europe/London", "text": "Follow up", "status": "scheduled" } ], "next_offset": null } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_remindersInput" }, "example": { "limit": 10, "offset": 0 } } } } } }, "/api/v1/reminders/cancel": { "post": { "operationId": "cancel_reminder", "summary": "Cancel a reminder", "description": "Cancel by reminder ID at the owner's request; preserves linked task. Available even when Notes creation is disabled or allowance is exhausted. Cancellation does not restore creation allowance or recall an already sent message.", "tags": [ "Reminders" ], "security": [ { "TelepathOAuth": [ "telegram.write" ] } ], "responses": { "200": { "description": "reminder and cancelled. Inspect the returned status; cancellation does not recall a delivered message. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "reminder": { "type": "object", "additionalProperties": true }, "cancelled": { "type": "boolean" } } }, "example": { "reminder": { "id": "r_example_reminder", "kind": "standalone", "note_id": null, "at": "2027-01-15T09:00:00.000Z", "timezone": "Europe/London", "text": "Follow up", "status": "cancelled" }, "cancelled": true } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancel_reminderInput" }, "example": { "id": "r_example_reminder" } } } } } }, "/api/v1/channels/posts/create": { "post": { "operationId": "telegram_create_post", "summary": "Publish a channel post", "description": "Broadcast to a connected channel you currently own. Show channel, text, all media and button destinations and obtain explicit confirmation. Supports text, one photo/document, or 2–10 album items. Albums cannot have buttons or mix documents with photo/video. Captions max 1024. Requires bot Post messages permission. Reuse request_id for identical retries; never retry uncertain delivery with a new ID. Supply nonempty text, media or an album. Album cannot be combined with media or buttons; 2–10 items, and documents cannot be mixed with photo/video items. Captions max 1024; plain text max 4096. HTTPS media/buttons only. Requires channel ownership and Post messages permission.", "tags": [ "Channels" ], "security": [ { "TelepathOAuth": [ "telegram.write" ] } ], "responses": { "200": { "description": "ok, channel_id, channel_title, message_id and action. Album creation also includes message_ids and media_group_id. Successful identical request_id replays return the saved result. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "ok": { "type": "boolean" }, "channel_id": { "type": "integer" }, "channel_title": { "type": "string" }, "message_id": { "type": "integer" }, "action": { "type": "string" }, "message_ids": { "type": "array", "items": { "type": "integer" } }, "media_group_id": { "type": "string" } } }, "example": { "ok": true, "channel_id": -1001234567890, "channel_title": "Example channel", "message_id": 42, "action": "telegram_create_post" } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/telegram_create_postInput" }, "example": { "channel_id": -1001234567890, "request_id": "post-create-example-001", "confirmed": true, "text": "Example announcement." } } } } } }, "/api/v1/channels/posts/edit": { "post": { "operationId": "telegram_edit_post", "summary": "Edit a channel post", "description": "Read first, confirm channel and exact replacement. Omitted fields are preserved; empty buttons removes them. Requires current ownership and bot Edit messages permission. Targets one album item, not the whole album. Reuse request_id on identical retry. Provide a text, media or button change. Omitted fields are preserved; buttons=[] removes buttons. Captions max 1024. Target one album item; replacement must preserve its media category and album items cannot have buttons. Requires current ownership and Edit messages permission.", "tags": [ "Channels" ], "security": [ { "TelepathOAuth": [ "telegram.write" ] } ], "responses": { "200": { "description": "ok, channel_id, channel_title, message_id and action. Album creation also includes message_ids and media_group_id. Successful identical request_id replays return the saved result. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "ok": { "type": "boolean" }, "channel_id": { "type": "integer" }, "channel_title": { "type": "string" }, "message_id": { "type": "integer" }, "action": { "type": "string" }, "message_ids": { "type": "array", "items": { "type": "integer" } }, "media_group_id": { "type": "string" } } }, "example": { "ok": true, "channel_id": -1001234567890, "channel_title": "Example channel", "message_id": 42, "action": "telegram_edit_post" } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/telegram_edit_postInput" }, "example": { "channel_id": -1001234567890, "message_id": 42, "request_id": "post-edit-example-001", "confirmed": true, "text": "Updated announcement." } } } } } }, "/api/v1/channels/posts/delete": { "post": { "operationId": "telegram_delete_post", "summary": "Delete a channel post", "description": "Permanently delete one archived post from Telegram after confirmation. Requires current ownership and bot Delete messages permission, subject to Telegram's deletion window. Not an archive-only delete. Reuse request_id on identical retry. Requires current ownership, Delete messages permission and an eligible archived post; Telegram deletion restrictions still apply.", "tags": [ "Channels" ], "security": [ { "TelepathOAuth": [ "telegram.write" ] } ], "responses": { "200": { "description": "ok, channel_id, channel_title, message_id and action. Album creation also includes message_ids and media_group_id. Successful identical request_id replays return the saved result. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "ok": { "type": "boolean" }, "channel_id": { "type": "integer" }, "channel_title": { "type": "string" }, "message_id": { "type": "integer" }, "action": { "type": "string" }, "message_ids": { "type": "array", "items": { "type": "integer" } }, "media_group_id": { "type": "string" } } }, "example": { "ok": true, "channel_id": -1001234567890, "channel_title": "Example channel", "message_id": 42, "action": "telegram_delete_post" } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/telegram_delete_postInput" }, "example": { "channel_id": -1001234567890, "message_id": 42, "request_id": "post-delete-example-001", "confirmed": true } } } } } }, "/api/v1/channels/posts/pin": { "post": { "operationId": "telegram_set_post_pinned", "summary": "Pin or unpin a channel post", "description": "Confirm the channel, post and desired state. Pin/unpin this specific post only; requires current ownership and bot Edit messages permission. Reuse request_id on identical retry. Requires current ownership, Edit messages permission and an eligible archived post. pinned=false unpins this post only.", "tags": [ "Channels" ], "security": [ { "TelepathOAuth": [ "telegram.write" ] } ], "responses": { "200": { "description": "ok, channel_id, channel_title, message_id and action. Album creation also includes message_ids and media_group_id. Successful identical request_id replays return the saved result. Examples are illustrative subsets, not production data. Additional fields may be returned.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "ok": { "type": "boolean" }, "channel_id": { "type": "integer" }, "channel_title": { "type": "string" }, "message_id": { "type": "integer" }, "action": { "type": "string" }, "message_ids": { "type": "array", "items": { "type": "integer" } }, "media_group_id": { "type": "string" } } }, "example": { "ok": true, "channel_id": -1001234567890, "channel_title": "Example channel", "message_id": 42, "action": "telegram_set_post_pinned" } } } }, "400": { "description": "Invalid parameters or JSON; unsupported chat type; invalid reminder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "Invalid parameters or JSON; unsupported chat type; invalid reminder." } } } }, "401": { "description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_token", "error_description": "Missing, expired, revoked or otherwise invalid access token. Refresh through OAuth." } } } }, "403": { "description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "account_unavailable", "error_description": "Inactive account, missing scope, disabled capability or exhausted reminder allowance." } } } }, "404": { "description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "chat_not_found", "error_description": "Unknown route/method, unavailable item, or chat absent from the required archive/inbox." } } } }, "413": { "description": "JSON body exceeds 256 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "error_description": "JSON body exceeds 256 KB." } } } }, "415": { "description": "Use application/json; unsupported charset or encoding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unsupported_media_type", "error_description": "Use application/json; unsupported charset or encoding." } } } }, "429": { "description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "error_description": "Shared account rate limit or Telegram rejection. Respect Retry-After when present." } } } }, "500": { "description": "Unexpected request-processing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "server_error", "error_description": "Unexpected request-processing failure." } } } }, "502": { "description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "operation_failed", "error_description": "Operation failed or completion is uncertain. A write may have succeeded; inspect state before retrying." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/telegram_set_post_pinnedInput" }, "example": { "channel_id": -1001234567890, "message_id": 42, "request_id": "post-pin-example-001", "confirmed": true, "pinned": true } } } } } } }, "components": { "securitySchemes": { "TelepathOAuth": { "type": "oauth2", "description": "Register the exact callback URL at /register. S256 PKCE is required. Use resource=https://telepath.lemma.company/mcp for REST as well. Obtain/refresh access tokens through /token.", "flows": { "authorizationCode": { "authorizationUrl": "https://telepath.lemma.company/authorize", "tokenUrl": "https://telepath.lemma.company/token", "refreshUrl": "https://telepath.lemma.company/token", "scopes": { "telegram.read": "Read permitted Telegram content, Notes and reminders.", "telegram.write": "Perform permitted write actions." } } } } }, "schemas": { "telegram_find_chatInput": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Search text; Notes search also accepts an empty string." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum results; source-specific caps may be lower. No Return All or implicit pagination. Default 20 for archive reads." } }, "required": [ "query" ], "additionalProperties": false }, "telegram_search_messagesInput": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Search text; Notes search also accepts an empty string." }, "chat_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Nonzero safe integer identifying a chat. JSON bodies use numbers; GET parameters are decimal strings on the wire.", "not": { "const": 0 } }, "since": { "type": "string", "format": "date-time", "description": "ISO 8601 lower date bound, with Z or an explicit UTC offset." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum results; source-specific caps may be lower. No Return All or implicit pagination. Default 30 for archive reads." } }, "required": [ "query" ], "additionalProperties": false }, "telegram_get_messagesInput": { "type": "object", "properties": { "before": { "type": "string", "format": "date-time", "description": "ISO 8601 upper date bound, with Z or an explicit UTC offset." }, "since": { "$ref": "#/components/schemas/telegram_get_messagesInput/properties/before", "description": "ISO 8601 lower date bound, with Z or an explicit UTC offset." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum results; source-specific caps may be lower. No Return All or implicit pagination. Default 50 for archive reads." } }, "additionalProperties": false }, "telegram_send_messageInput": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Message, post or reminder text. Whitespace-only ordinary sends are rejected." }, "reply_to_message_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0, "description": "Optional message to reply to." }, "message_thread_id": { "$ref": "#/components/schemas/telegram_send_messageInput/properties/reply_to_message_id", "description": "Optional forum topic/thread ID." } }, "required": [ "text" ], "additionalProperties": false }, "telegram_get_photosInput": { "type": "object", "properties": { "chat_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Nonzero safe integer identifying a chat. JSON bodies use numbers; GET parameters are decimal strings on the wire.", "not": { "const": 0 } }, "message_ids": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 }, "minItems": 1, "maxItems": 5, "description": "1–5 positive message IDs from one chat." } }, "required": [ "chat_id", "message_ids" ], "additionalProperties": false }, "telegram_bot_direct_messagesInput": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum results; source-specific caps may be lower. No Return All or implicit pagination. Default 20 for archive reads." } }, "additionalProperties": false }, "telegram_bot_dm_replyInput": { "type": "object", "properties": { "chat_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Nonzero safe integer identifying a chat. JSON bodies use numbers; GET parameters are decimal strings on the wire.", "not": { "const": 0 } }, "text": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Message, post or reminder text. Whitespace-only ordinary sends are rejected." } }, "required": [ "chat_id", "text" ], "additionalProperties": false }, "telegram_bot_dm_reactInput": { "type": "object", "properties": { "chat_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Nonzero safe integer identifying a chat. JSON bodies use numbers; GET parameters are decimal strings on the wire.", "not": { "const": 0 } }, "message_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0, "description": "Positive safe integer identifying a message in the selected chat." }, "emoji": { "type": "string", "maxLength": 100, "description": "Telegram-supported reaction. Omit to remove the bot reaction." }, "big": { "type": "boolean", "description": "Request a large reaction animation." } }, "required": [ "chat_id", "message_id" ], "additionalProperties": false }, "telegram_forgetInput": { "type": "object", "properties": { "chat_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Nonzero safe integer identifying a chat. JSON bodies use numbers; GET parameters are decimal strings on the wire.", "not": { "const": 0 } }, "before": { "type": "string", "format": "date-time", "description": "ISO 8601 upper date bound, with Z or an explicit UTC offset." }, "confirmed": { "type": "boolean", "const": true, "description": "Must be true; caller must obtain authorization for this exact action." } }, "required": [ "confirmed" ], "additionalProperties": false, "anyOf": [ { "required": [ "chat_id" ] }, { "required": [ "before" ] } ] }, "telegram_list_chatsInput": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum results; source-specific caps may be lower. No Return All or implicit pagination. Default 20 for archive reads." } }, "additionalProperties": false }, "telegram_recent_messagesInput": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum results; source-specific caps may be lower. No Return All or implicit pagination. Default 20 for archive reads." }, "since": { "type": "string", "format": "date-time", "description": "ISO 8601 lower date bound, with Z or an explicit UTC offset." } }, "additionalProperties": false }, "telegram_get_fileInput": { "type": "object", "properties": { "chat_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Nonzero safe integer identifying a chat. JSON bodies use numbers; GET parameters are decimal strings on the wire.", "not": { "const": 0 } }, "message_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0, "description": "Positive safe integer identifying a message in the selected chat." }, "include_text": { "type": "boolean", "description": "Whether to attempt supported text extraction; this is not transcription." }, "max_chars": { "type": "integer", "minimum": 1, "maximum": 50000, "description": "Maximum extracted characters." }, "offset_lines": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "Starting line offset for extracted text." } }, "required": [ "chat_id", "message_id" ], "additionalProperties": false }, "telegram_get_photoInput": { "type": "object", "properties": { "chat_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Nonzero safe integer identifying a chat. JSON bodies use numbers; GET parameters are decimal strings on the wire.", "not": { "const": 0 } }, "message_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0, "description": "Positive safe integer identifying a message in the selected chat." } }, "required": [ "chat_id", "message_id" ], "additionalProperties": false }, "telegram_send_mediaInput": { "type": "object", "properties": { "chat_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Nonzero safe integer identifying a chat. JSON bodies use numbers; GET parameters are decimal strings on the wire.", "not": { "const": 0 } }, "from_chat_id": { "$ref": "#/components/schemas/telegram_send_mediaInput/properties/chat_id", "description": "Source chat in this account archive; pair with from_message_id." }, "from_message_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0, "description": "Source message in from_chat_id." }, "url": { "type": "string", "format": "uri", "pattern": "^https?:\\/\\/", "description": "Media or button URL. See the field constraints and operation rules." }, "caption": { "type": "string", "maxLength": 1024 }, "as_document": { "type": "boolean", "description": "Send the media as a document." }, "reply_to_message_id": { "$ref": "#/components/schemas/telegram_send_mediaInput/properties/from_message_id", "description": "Optional message to reply to." }, "message_thread_id": { "$ref": "#/components/schemas/telegram_send_mediaInput/properties/from_message_id", "description": "Optional forum topic/thread ID." } }, "required": [ "chat_id" ], "additionalProperties": false, "oneOf": [ { "required": [ "url" ], "not": { "anyOf": [ { "required": [ "from_chat_id" ] }, { "required": [ "from_message_id" ] } ] } }, { "required": [ "from_chat_id", "from_message_id" ], "not": { "required": [ "url" ] } } ] }, "telegram_edit_messageInput": { "type": "object", "properties": { "chat_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Nonzero safe integer identifying a chat. JSON bodies use numbers; GET parameters are decimal strings on the wire.", "not": { "const": 0 } }, "message_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0, "description": "Positive safe integer identifying a message in the selected chat." }, "text": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Message, post or reminder text. Whitespace-only ordinary sends are rejected." } }, "required": [ "chat_id", "message_id", "text" ], "additionalProperties": false }, "telegram_mark_readInput": { "type": "object", "properties": { "chat_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Nonzero safe integer identifying a chat. JSON bodies use numbers; GET parameters are decimal strings on the wire.", "not": { "const": 0 } }, "message_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0, "description": "Positive safe integer identifying a message in the selected chat." } }, "required": [ "chat_id" ], "additionalProperties": false }, "telegram_set_reactionInput": { "type": "object", "properties": { "chat_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Nonzero safe integer identifying a chat. JSON bodies use numbers; GET parameters are decimal strings on the wire.", "not": { "const": 0 } }, "message_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0, "description": "Positive safe integer identifying a message in the selected chat." }, "emoji": { "type": "string", "maxLength": 100, "description": "Telegram-supported reaction. Omit to remove the bot reaction." }, "big": { "type": "boolean", "description": "Request a large reaction animation." } }, "required": [ "chat_id", "message_id" ], "additionalProperties": false }, "kb_search_notesInput": { "type": "object", "properties": { "query": { "type": "string", "maxLength": 1000, "description": "Search text; Notes search also accepts an empty string." }, "tag": { "type": "string", "maxLength": 100, "description": "Optional exact tag filter." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum results; source-specific caps may be lower. No Return All or implicit pagination. Default 20 for archive reads." } }, "required": [ "query" ], "additionalProperties": false }, "kb_get_noteInput": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0, "description": "Note ID or reminder ID, as typed below." }, "title": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Note title (trimmed, 1–500 characters); exact-title selector when ID is omitted." } }, "additionalProperties": false, "anyOf": [ { "required": [ "id" ] }, { "required": [ "title" ] } ] }, "kb_list_notesInput": { "type": "object", "properties": { "tag": { "type": "string", "maxLength": 100, "description": "Optional exact tag filter." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum results; source-specific caps may be lower. No Return All or implicit pagination. Default 30 for archive reads." } }, "additionalProperties": false }, "kb_create_noteInput": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Note title (trimmed, 1–500 characters); exact-title selector when ID is omitted." }, "body": { "type": "string", "maxLength": 50000, "description": "Note body, up to 50,000 characters; an empty string is meaningful." }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 100, "description": "At most 100 strings, each up to 100 characters. On update this replaces all tags." }, "type": { "type": "string", "enum": [ "note", "project", "person", "task" ], "description": "Note type or media type, according to the enclosing object." }, "task_status": { "type": "string", "enum": [ "open", "done" ], "description": "open or done; completing a task cancels its reminder." }, "reminder": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 1500, "description": "Message, post or reminder text. Whitespace-only ordinary sends are rejected." }, "at": { "type": "string", "format": "date-time", "description": "Future ISO 8601 date/time with explicit offset, within five years." }, "timezone": { "type": "string", "minLength": 1, "maxLength": 80, "description": "IANA timezone, for example Europe/London." } }, "required": [ "text", "at", "timezone" ], "additionalProperties": false }, { "type": "null" } ], "description": "Optional task reminder object, or null to cancel. Valid only on an open task." } }, "required": [ "title" ], "additionalProperties": false }, "kb_update_noteInput": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0, "description": "Note ID or reminder ID, as typed below." }, "title": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Note title (trimmed, 1–500 characters); exact-title selector when ID is omitted." }, "body": { "type": "string", "maxLength": 50000, "description": "Note body, up to 50,000 characters; an empty string is meaningful." }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 100, "description": "At most 100 strings, each up to 100 characters. On update this replaces all tags." }, "type": { "type": "string", "enum": [ "note", "project", "person", "task" ], "description": "Note type or media type, according to the enclosing object." }, "task_status": { "type": "string", "enum": [ "open", "done" ], "description": "open or done; completing a task cancels its reminder." }, "reminder": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 1500, "description": "Message, post or reminder text. Whitespace-only ordinary sends are rejected." }, "at": { "type": "string", "format": "date-time", "description": "Future ISO 8601 date/time with explicit offset, within five years." }, "timezone": { "type": "string", "minLength": 1, "maxLength": 80, "description": "IANA timezone, for example Europe/London." } }, "required": [ "text", "at", "timezone" ], "additionalProperties": false }, { "type": "null" } ], "description": "Optional task reminder object, or null to cancel. Valid only on an open task." }, "append": { "type": "boolean", "description": "Append body rather than replace it." } }, "additionalProperties": false, "anyOf": [ { "required": [ "id" ] }, { "required": [ "title" ] } ] }, "kb_delete_noteInput": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0, "description": "Note ID or reminder ID, as typed below." }, "title": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Note title (trimmed, 1–500 characters); exact-title selector when ID is omitted." } }, "additionalProperties": false, "anyOf": [ { "required": [ "id" ] }, { "required": [ "title" ] } ] }, "create_reminderInput": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 1500, "description": "Message, post or reminder text. Whitespace-only ordinary sends are rejected." }, "at": { "type": "string", "format": "date-time", "description": "Future ISO 8601 date/time with explicit offset, within five years." }, "timezone": { "type": "string", "minLength": 1, "maxLength": 80, "description": "IANA timezone, for example Europe/London." }, "request_id": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[-a-zA-Z0-9_]+$", "description": "8–100 letters, digits, hyphens or underscores. Reuse only for the identical operation." } }, "required": [ "text", "at", "timezone" ], "additionalProperties": false }, "list_remindersInput": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "scheduled", "sending", "delivered", "failed", "uncertain", "cancelled", "done" ], "description": "Filter by reminder delivery state." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum results; source-specific caps may be lower. No Return All or implicit pagination. Default 30 for archive reads." }, "offset": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "Reminder list offset." } }, "additionalProperties": false }, "cancel_reminderInput": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Note ID or reminder ID, as typed below." } }, "required": [ "id" ], "additionalProperties": false }, "telegram_create_postInput": { "type": "object", "properties": { "channel_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMaximum": 0, "description": "Negative safe integer for a connected channel currently owned by this account." }, "request_id": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[-a-zA-Z0-9_]+$", "description": "8–100 letters, digits, hyphens or underscores. Reuse only for the identical operation." }, "confirmed": { "type": "boolean", "const": true, "description": "Must be true; caller must obtain authorization for this exact action." }, "text": { "type": "string", "maxLength": 4096, "description": "Message, post or reminder text. Whitespace-only ordinary sends are rejected." }, "media": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "photo", "document" ], "description": "Note type or media type, according to the enclosing object." }, "url": { "type": "string", "format": "uri", "pattern": "^https\\:\\/\\/", "description": "Media or button URL. See the field constraints and operation rules." } }, "required": [ "type", "url" ], "additionalProperties": false, "description": "One photo or document with an HTTPS URL." }, "buttons": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Message, post or reminder text. Whitespace-only ordinary sends are rejected." }, "url": { "$ref": "#/components/schemas/telegram_create_postInput/properties/media/properties/url", "description": "Media or button URL. See the field constraints and operation rules." } }, "required": [ "text", "url" ], "additionalProperties": false }, "minItems": 1, "maxItems": 4 }, "maxItems": 5, "description": "Up to five rows of 1–4 HTTPS link buttons; [] removes buttons on edit." }, "format": { "type": "string", "enum": [ "plain", "HTML" ], "description": "plain or HTML for channel content." }, "album": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "photo", "video", "document" ], "description": "Note type or media type, according to the enclosing object." }, "url": { "$ref": "#/components/schemas/telegram_create_postInput/properties/media/properties/url", "description": "Media or button URL. See the field constraints and operation rules." } }, "required": [ "type", "url" ], "additionalProperties": false }, "minItems": 2, "maxItems": 10, "description": "2–10 photo/video/document items; see album restrictions." } }, "required": [ "channel_id", "request_id", "confirmed" ], "additionalProperties": false }, "telegram_edit_postInput": { "type": "object", "properties": { "channel_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMaximum": 0, "description": "Negative safe integer for a connected channel currently owned by this account." }, "request_id": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[-a-zA-Z0-9_]+$", "description": "8–100 letters, digits, hyphens or underscores. Reuse only for the identical operation." }, "confirmed": { "type": "boolean", "const": true, "description": "Must be true; caller must obtain authorization for this exact action." }, "text": { "type": "string", "maxLength": 4096, "description": "Message, post or reminder text. Whitespace-only ordinary sends are rejected." }, "media": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "photo", "document" ], "description": "Note type or media type, according to the enclosing object." }, "url": { "type": "string", "format": "uri", "pattern": "^https\\:\\/\\/", "description": "Media or button URL. See the field constraints and operation rules." } }, "required": [ "type", "url" ], "additionalProperties": false, "description": "One photo or document with an HTTPS URL." }, "buttons": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Message, post or reminder text. Whitespace-only ordinary sends are rejected." }, "url": { "$ref": "#/components/schemas/telegram_edit_postInput/properties/media/properties/url", "description": "Media or button URL. See the field constraints and operation rules." } }, "required": [ "text", "url" ], "additionalProperties": false }, "minItems": 1, "maxItems": 4 }, "maxItems": 5, "description": "Up to five rows of 1–4 HTTPS link buttons; [] removes buttons on edit." }, "format": { "type": "string", "enum": [ "plain", "HTML" ], "description": "plain or HTML for channel content." }, "message_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0, "description": "Positive safe integer identifying a message in the selected chat." } }, "required": [ "channel_id", "request_id", "confirmed", "message_id" ], "additionalProperties": false }, "telegram_delete_postInput": { "type": "object", "properties": { "channel_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMaximum": 0, "description": "Negative safe integer for a connected channel currently owned by this account." }, "request_id": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[-a-zA-Z0-9_]+$", "description": "8–100 letters, digits, hyphens or underscores. Reuse only for the identical operation." }, "confirmed": { "type": "boolean", "const": true, "description": "Must be true; caller must obtain authorization for this exact action." }, "message_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0, "description": "Positive safe integer identifying a message in the selected chat." } }, "required": [ "channel_id", "request_id", "confirmed", "message_id" ], "additionalProperties": false }, "telegram_set_post_pinnedInput": { "type": "object", "properties": { "channel_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMaximum": 0, "description": "Negative safe integer for a connected channel currently owned by this account." }, "request_id": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[-a-zA-Z0-9_]+$", "description": "8–100 letters, digits, hyphens or underscores. Reuse only for the identical operation." }, "confirmed": { "type": "boolean", "const": true, "description": "Must be true; caller must obtain authorization for this exact action." }, "message_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0, "description": "Positive safe integer identifying a message in the selected chat." }, "pinned": { "type": "boolean", "description": "true to pin, false to unpin." } }, "required": [ "channel_id", "request_id", "confirmed", "message_id", "pinned" ], "additionalProperties": false }, "Error": { "type": "object", "additionalProperties": true, "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "quota": { "type": "object", "additionalProperties": true } }, "required": [ "error" ] } } } }