Перейти к основному содержимому

project-tokens

Эндпоинтов: 31

GET /api/projects/{id}/tokens​

Список токенов (masked + botId)

Авторизация: Cookie (connect.sid) или Bearer PAT

toPublicBotToken + botId (префикс до :). Секреты вырезаны.

Auth: опционально getOwnerIdFromRequest — если сессия/PAT есть, проверяет hasProjectAccess (403/404); без auth всё равно отдаёт список.

Клиент: панель токенов проекта.

curl -s http://localhost:5000/api/projects/42/tokens -b cookies.txt

Operation ID: get_api_projects_id_tokens_443b3cd56ddc3127

Параметры​

ИмяInОбязательныйОписаниеПример
idpathдаЧисловой ID проекта"42"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Массив публичных токенов
401Глобальный requireApiAuth (если включён)
403Нет доступа (только при наличии ownerId)
404Проект не найден (при auth)

Пример ответа 200​

[
{
"id": 7,
"projectId": 42,
"ownerId": 123456789,
"name": "Основной бот",
"token": "7123456789:••••••••",
"isDefault": 1,
"isActive": 1,
"botUsername": "my_bot",
"botFirstName": "My Bot",
"messagesRetentionDays": 60,
"autoRestart": 0,
"maxRestartAttempts": 3,
"logLevel": "WARNING",
"protectContent": 0,
"saveIncomingMedia": 0,
"catchAllHandlers": 1,
"contentCache": 1,
"launchMode": "polling",
"webhookBaseUrl": null,
"webhookSecretToken": null,
"userbotEnabled": 0,
"userbotApiId": null,
"userbotApiHash": null,
"userbotSessionString": null,
"botId": "7123456789"
}
]

POST /api/projects/{id}/tokens​

Создать токен (или вернуть дубликат)

Авторизация: Cookie (connect.sid) или Bearer PAT

insertBotTokenSchema. ownerId из body игнорируется (сессия / owner проекта). При отсутствии botUsername — auto getMe. Дубликат того же token → 200 full. Новый → 201 full + WS token-created.

Риск: ответ содержит сырой Telegram token.

Auth: опционально getOwnerIdFromRequest + hasProjectAccess при сессии.

Клиент: модалка добавления бота; MCP db_add_bot_token (агенту отдаёт только безопасные поля без секрета).

curl -s -X POST http://localhost:5000/api/projects/42/tokens -b cookies.txt \
-H 'Content-Type: application/json' \
-d '{"name":"Основной","token":"7123…:AAH…"}'

Operation ID: post_api_projects_id_tokens_8bb6b54e450b52e2

Тело запроса: CreateBotTokenBody

Параметры​

ИмяInОбязательныйОписаниеПример
idpathдаЧисловой ID проекта"42"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Дубликат — существующая запись (полный token)
201Создан (полный token)
400Zod validation
401Глобальный requireApiAuth
403Нет доступа (при auth)
404Проект не найден (при auth)

Пример ответа 201​

{
"id": 7,
"projectId": 42,
"name": "Основной",
"token": "<TELEGRAM_BOT_TOKEN>",
"botUsername": "my_bot"
}

PUT /api/projects/{id}/tokens/{tokenId}​

Обновить токен (masked ответ)

Авторизация: Cookie (connect.sid) или Bearer PAT

insertBotTokenSchema.partial(). Маскированный/•••• token игнорируется (isMaskedOrPlaceholderToken). Ответ — toPublicBotToken. WS token-updated (source=api).

Auth: опционально getOwnerIdFromRequest + hasProjectAccess; при auth также сверка token.projectId.

Клиент: TokenDisplayEdit; MCP db_update_bot_token (агенту отдаёт только безопасные поля без секрета).

curl -s -X PUT http://localhost:5000/api/projects/42/tokens/7 -b cookies.txt \
-H 'Content-Type: application/json' -d '{"name":"Новое имя"}'

Operation ID: put_api_projects_id_tokens_tokenId_53fe45ccefb18209

Тело запроса: UpdateBotTokenBody

Параметры​

ИмяInОбязательныйОписаниеПример
idpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Публичный токен
400Zod validation
401Глобальный requireApiAuth
403Нет доступа (при auth)
404Проект/токен не найден

Пример ответа 200​

{
"id": 7,
"projectId": 42,
"ownerId": 123456789,
"name": "Основной бот",
"token": "7123456789:••••••••",
"isDefault": 1,
"isActive": 1,
"botUsername": "my_bot",
"botFirstName": "My Bot",
"messagesRetentionDays": 60,
"autoRestart": 0,
"maxRestartAttempts": 3,
"logLevel": "WARNING",
"protectContent": 0,
"saveIncomingMedia": 0,
"catchAllHandlers": 1,
"contentCache": 1,
"launchMode": "polling",
"webhookBaseUrl": null,
"webhookSecretToken": null,
"userbotEnabled": 0,
"userbotApiId": null,
"userbotApiHash": null,
"userbotSessionString": null
}

PUT /api/projects/{id}/tokens/{tokenId}/bot-info​

Обновить name/description бота в Telegram

Авторизация: Cookie (connect.sid) или Bearer PAT

Body { field, value }. field: name → setMyName, description → setMyDescription, shortDescription → setMyShortDescription. Пишет в локальную БД после успеха Telegram.

Auth: requireTokenOwnership (владелец/collaborator + сверка projectId).

Клиент: настройки профиля бота.

curl -s -X PUT http://localhost:5000/api/projects/42/tokens/7/bot-info -b cookies.txt \
-H 'Content-Type: application/json' \
-d '{"field":"name","value":"Новое имя"}'

Operation ID: put_api_projects_id_tokens_tokenId_bot_info_ed828250482dec72

Тело запроса: BotInfoUpdateRequest

Параметры​

ИмяInОбязательныйОписаниеПример
idpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Обновлено
400Нет field/value / Invalid field / Telegram error
401Не авторизован
403Нет владения токеном
404Токен не найден в проекте

Пример ответа 200​

{
"success": true,
"field": "name",
"value": "Новое имя"
}

GET /api/projects/{id}/tokens/{tokenId}/settings​

Безопасные настройки бота без токена и ENV

Авторизация: Cookie (connect.sid) или Bearer PAT

Operation ID: get_api_projects_id_tokens_tokenId_settings_137e9b952e2b1d35

Параметры​

ИмяInОбязательныйОписаниеПример
idpathда——
tokenIdpathда——

Ответы​

КодОписание
200Настройки существующего бота проекта
400Некорректные параметры
401Нет авторизации
403Нет доступа к проекту
404Бот или пользователь не найдены
500Не удалось прочитать данные

GET /api/projects/{id}/tokens/first​

Дефолтный токен для codegen (.env)

Авторизация: Cookie (connect.sid) или Bearer PAT

Дефолтный токен проекта (getDefaultBotToken, иначе любой). Ответ: { hasToken, id, token } — сырой Telegram token + id.

Риск: не логировать тело. Cache-Control: no-store.

Auth: cookie / Bearer PAT + requireProjectAccess.

Клиент: use-code-generator (BOT_TOKEN + env-variables по id).

curl -s http://localhost:5000/api/projects/42/tokens/first -b cookies.txt

Operation ID: get_api_projects_id_tokens_first_7a1e2cd760b1063e

Параметры​

ИмяInОбязательныйОписаниеПример
idpathдаЧисловой ID проекта"42"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Сырой token + id, или hasToken=false
400Невалидный id проекта
401Нет session cookie и Bearer PAT
403Нет доступа к проекту

Пример ответа 200​

{
"hasToken": true,
"id": 7,
"token": "<TELEGRAM_BOT_TOKEN>"
}

GET /api/projects/{id}/tokens/list​

Безопасный whitelist список токенов

Авторизация: Cookie (connect.sid) или Bearer PAT

Только BotTokenListItem (без token и прочих секретов). MCP/агенты.

Auth: cookie / Bearer PAT + requireProjectAccess.

Клиент: MCP db_list_bot_tokens (не UI; UI — GET …/tokens).

curl -s http://localhost:5000/api/projects/42/tokens/list -b cookies.txt

Operation ID: get_api_projects_id_tokens_list_0139a121a4a86cd3

Параметры​

ИмяInОбязательныйОписаниеПример
idpathдаЧисловой ID проекта"42"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Whitelist-массив
400Невалидный id
401Нет session cookie и Bearer PAT
403Нет доступа к проекту

Пример ответа 200​

[
{
"id": 7,
"name": "Основной бот",
"botUsername": "my_bot",
"botFirstName": "My Bot",
"isDefault": 1,
"isActive": 1,
"projectId": 42,
"messagesRetentionDays": 60
}
]

POST /api/projects/{id}/tokens/parse​

Распарсить bot token через Telegram getMe

Авторизация: Cookie (connect.sid) или Bearer PAT

Body { token }. Вызывает getMe, getMyDescription, getMyShortDescription, опционально фото. Нет middleware requireProjectAccess / ownership — только глобальный requireApiAuth (если включён). :id в URL не влияет на Telegram.

Невалидный / отозванный token Telegram → 400 (Invalid bot token or failed to get bot info), не 500.

Клиент: форма добавления токена (превью @username); MCP PostApiProjectsTokensParse / эквивалент превью перед db_add_bot_token.

curl -s -X POST http://localhost:5000/api/projects/42/tokens/parse -b cookies.txt \
-H 'Content-Type: application/json' \
-d '{"token":"7123…:AAH…"}'

Operation ID: post_api_projects_id_tokens_parse_06b82c0d03ea7222

Тело запроса: ParseTokenRequest

Параметры​

ИмяInОбязательныйОписаниеПример
idpathдаЧисловой ID проекта"42"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Поля бота для формы
400Нет token в body; либо Telegram отклонил token (ok:false / HTTP не 200) — Invalid bot token or failed to get bot info
500Сеть / Telegram недоступен (Failed to connect…). Ошибка логирования при пустом result больше не отдаёт 500.

Пример ответа 200​

{
"botFirstName": "My Bot",
"botUsername": "my_bot",
"botDescription": "Описание бота",
"botShortDescription": "Кратко",
"botPhotoUrl": null,
"botCanJoinGroups": 1,
"botCanReadAllGroupMessages": 0,
"botSupportsInlineQueries": 0,
"botHasMainWebApp": 0
}

DELETE /api/projects/{projectId}/tokens/{tokenId}​

Удалить токен бота проекта

Авторизация: Cookie (connect.sid) или Bearer PAT

Останавливает бота и удаляет токен. Сверка token.projectId с :projectId.

Auth: requireTokenOwnership → hasProjectAccess.

Side-effect: WS token-deleted.

curl -s -X DELETE http://localhost:5000/api/projects/42/tokens/7 -b cookies.txt

Operation ID: delete_api_projects_projectId_tokens_tokenId_8327d9448fe4c0e6

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Токен удалён
400Некорректный projectId или tokenId
401Не авторизован
403Нет доступа к проекту токена
404Токен не найден в этом проекте

Пример ответа 200​

{
"message": "Token deleted successfully"
}

PUT /api/projects/{projectId}/tokens/{tokenId}/auto-restart​

Автоперезапуск бота

Авторизация: Cookie (connect.sid) или Bearer PAT

autoRestart 0|1, maxRestartAttempts 1–10.

Auth: requireTokenOwnership. WS token-updated. Флаги попадают в env бота при следующем запуске.

curl -s -X PUT http://localhost:5000/api/projects/42/tokens/7/auto-restart \
-b cookies.txt -H 'Content-Type: application/json' \
-d '{"autoRestart":1,"maxRestartAttempts":3}'

Operation ID: put_api_projects_projectId_tokens_tokenId_auto_restart_478ff1a315c6e4eb

Тело запроса: AutoRestartRequest

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Сохранено
400Флаг не 0/1 или значение вне диапазона
401Не авторизован
403Нет владения токеном
404Токен не найден

Пример ответа 200​

{
"success": true,
"autoRestart": 1,
"maxRestartAttempts": 3
}

PUT /api/projects/{projectId}/tokens/{tokenId}/catch-all-handlers​

Catch-all обработчики (CATCH_ALL_HANDLERS)

Авторизация: Cookie (connect.sid) или Bearer PAT

catchAllHandlers 0|1 — генерация handle_unhandled_* / fallback_callback.

Auth: requireTokenOwnership. WS token-updated. В env бота (при следующем запуске) — 0/1.

curl -s -X PUT http://localhost:5000/api/projects/42/tokens/7/catch-all-handlers \
-b cookies.txt -H 'Content-Type: application/json' -d '{"catchAllHandlers":1}'

Operation ID: put_api_projects_projectId_tokens_tokenId_catch_all_handlers_3153b56724d52fb7

Тело запроса: CatchAllHandlersRequest

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Сохранено
400Флаг не 0/1 или значение вне диапазона
401Не авторизован
403Нет владения токеном
404Токен не найден

Пример ответа 200​

{
"success": true,
"catchAllHandlers": 1
}

PUT /api/projects/{projectId}/tokens/{tokenId}/content-cache​

Живое обновление _content (CONTENT_CACHE)

Авторизация: Cookie (connect.sid) или Bearer PAT

contentCache 0|1 — load/reload_content / redis subscribe. get_content всегда.

Auth: requireTokenOwnership. WS token-updated. В env бота (при следующем запуске) — 0/1.

curl -s -X PUT http://localhost:5000/api/projects/42/tokens/7/content-cache \
-b cookies.txt -H 'Content-Type: application/json' -d '{"contentCache":1}'

Operation ID: put_api_projects_projectId_tokens_tokenId_content_cache_0dd5845b6ce1af87

Тело запроса: ContentCacheRequest

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Сохранено
400Флаг не 0/1 или значение вне диапазона
401Не авторизован
403Нет владения токеном
404Токен не найден

Пример ответа 200​

{
"success": true,
"contentCache": 1
}

PUT /api/projects/{projectId}/tokens/{tokenId}/env-batch​

Batch-обновление env / системных ключей

Авторизация: Cookie (connect.sid) или Bearer PAT

changes[]: create/update/delete. Системные KEY → bot_tokens / project (BOT_TOKEN, ADMIN_IDS, USER_DATABASE, LOG_LEVEL, PROTECT_CONTENT, …). Остальные → bot_env_variables. WS token-updated при обновлении полей токена.

Маскированные секреты не пишутся в БД. Значение BOT_TOKEN вида 123456:•••••••• / с • * … / не digits:secret → skipped:BOT_TOKEN:masked (тот же isMaskedOrPlaceholderToken, что у PUT токена). WEBHOOK_SECRET_TOKEN с символами маски → skipped:WEBHOOK_SECRET_TOKEN:masked. Иначе Studio могла затереть реальный токен маской из GET и бот стартовал бы с Not Found.

Auth: requireTokenOwnership.

Клиент: BotEnvPanel / use-env-pending-changes (save / saveAndRestart).

curl -s -X PUT http://localhost:5000/api/projects/42/tokens/7/env-batch \
-b cookies.txt -H 'Content-Type: application/json' \
-d '{"changes":[{"action":"update","key":"LOG_LEVEL","value":"WARNING"}]}'

Маскированный BOT_TOKEN (не меняет БД):

curl -s -X PUT http://localhost:5000/api/projects/42/tokens/7/env-batch \
-b cookies.txt -H 'Content-Type: application/json' \
-d '{"changes":[{"action":"update","key":"BOT_TOKEN","value":"7123456789:••••••••"}]}'
# → {"success":true,"applied":1,"results":["skipped:BOT_TOKEN:masked"]}

Operation ID: put_api_projects_projectId_tokens_tokenId_env_batch_6e67cadfc1554597

Тело запроса: ProjectTokenEnvBatchRequest

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Применено (в results могут быть skipped:*:masked)
400Пустой changes
401Не авторизован
403Нет владения

Пример ответа 200​

{
"success": true,
"applied": 1,
"results": [
"updated:LOG_LEVEL"
]
}

GET /api/projects/{projectId}/tokens/{tokenId}/env-variables​

Список env токена (секреты маскируются)

Авторизация: Cookie (connect.sid) или Bearer PAT

{ items, count }. Секреты → ••••••••.

Auth: requireTokenOwnership. Reveal — отдельный path.

Клиент: use-env-variables / BotEnvRow.

curl -s http://localhost:5000/api/projects/42/tokens/7/env-variables -b cookies.txt

Operation ID: get_api_projects_projectId_tokens_tokenId_env_variables_b074e217d24e5578

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Список
401Не авторизован
403Нет владения токеном

Пример ответа 200​

{
"items": [
{
"id": 15,
"tokenId": 7,
"key": "API_KEY",
"value": "••••••••",
"isSecret": 1
}
],
"count": 1
}

POST /api/projects/{projectId}/tokens/{tokenId}/env-variables​

Создать env-переменную

Авторизация: Cookie (connect.sid) или Bearer PAT

key regex ^[A-Z][A-Z0-9_]*$. 409 если ключ есть.

Auth: requireTokenOwnership. Reveal — отдельный path.

curl -s -X POST http://localhost:5000/api/projects/42/tokens/7/env-variables \
-b cookies.txt -H 'Content-Type: application/json' \
-d '{"key":"API_KEY","value":"secret","isSecret":1}'

Operation ID: post_api_projects_projectId_tokens_tokenId_env_variables_e6e25ab93f4c5c20

Тело запроса: ProjectTokenEnvCreateBody

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
201Создана (сырое value)
400Некорректный key
401Не авторизован
403Нет владения
409Ключ уже существует

Пример ответа 201​

{
"id": 15,
"tokenId": 7,
"key": "API_KEY",
"value": "secret",
"isSecret": 1
}

DELETE /api/projects/{projectId}/tokens/{tokenId}/env-variables/{id}​

Удалить env-переменную

Авторизация: Cookie (connect.sid) или Bearer PAT

Auth: requireTokenOwnership.

curl -s -X DELETE http://localhost:5000/api/projects/42/tokens/7/env-variables/15 \
-b cookies.txt

Operation ID: delete_api_projects_projectId_tokens_tokenId_env_variables_id_09470447009b2e93

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
idpathдаID переменной env"15"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Удалена
401Не авторизован
403Нет владения
404Не найдена

Пример ответа 200​

{
"success": true
}

PUT /api/projects/{projectId}/tokens/{tokenId}/env-variables/{id}​

Обновить env-переменную

Авторизация: Cookie (connect.sid) или Bearer PAT

Partial { key?, value?, isSecret? }. Чужой id → 404 (сверка tokenId).

Auth: requireTokenOwnership.

curl -s -X PUT http://localhost:5000/api/projects/42/tokens/7/env-variables/15 \
-b cookies.txt -H 'Content-Type: application/json' -d '{"value":"new"}'

Operation ID: put_api_projects_projectId_tokens_tokenId_env_variables_id_74553502a626c604

Тело запроса: ProjectTokenEnvUpdateBody

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
idpathдаID переменной env"15"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Обновлена
400Некорректный id/key
401Не авторизован
403Нет владения
404Не найдена / чужой tokenId
409Конфликт key

GET /api/projects/{projectId}/tokens/{tokenId}/env-variables/{id}/reveal​

Раскрыть секретное значение env токена

Авторизация: Cookie (connect.sid) или Bearer PAT

Риск: ответ содержит сырое значение env. В списке секреты маскируются. Не логируйте тело ответа.

Сверка variable.tokenId с :tokenId (чужой id → 404).

Auth: requireTokenOwnership (владелец/collaborator + IDOR-check projectId).

Клиент: use-env-variables / BotEnvRow (кнопка «показать»).

curl -s http://localhost:5000/api/projects/42/tokens/7/env-variables/15/reveal \
-b cookies.txt

Operation ID: get_api_projects_projectId_tokens_tokenId_env_variables_id_reveal_aabc67f8558f15a9

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаID проекта"42"
tokenIdpathдаID токена бота"7"
idpathдаID переменной env"15"
connect.sidcookieнетSession cookie Studio. Не нужна при Bearer PAT. Без обоих — 401."s%3Axxxx.yyyy"

Ответы​

КодОписание
200Сырое значение
401Не авторизован
403Нет владения токеном
404Не найдено / чужой tokenId

Пример ответа 200​

{
"value": "super-secret-api-key"
}

PUT /api/projects/{projectId}/tokens/{tokenId}/launch-settings​

Режим запуска polling/webhook

Авторизация: Cookie (connect.sid) или Bearer PAT

launchMode polling|webhook; опционально webhookBaseUrl, webhookSecretToken. При смене webhook→polling вызывается Telegram deleteWebhook. Риск: ответ может вернуть webhookSecretToken.

Auth: requireTokenOwnership. WS token-updated.

curl -s -X PUT http://localhost:5000/api/projects/42/tokens/7/launch-settings \
-b cookies.txt -H 'Content-Type: application/json' \
-d '{"launchMode":"polling"}'

Operation ID: put_api_projects_projectId_tokens_tokenId_launch_settings_3a62d04ebc675e80

Тело запроса: LaunchSettingsRequest

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Сохранено
400Недопустимое значение
401Не авторизован
403Нет владения токеном
404Токен не найден

Пример ответа 200​

{
"success": true,
"launchMode": "polling",
"webhookBaseUrl": null,
"webhookSecretToken": null
}

PUT /api/projects/{projectId}/tokens/{tokenId}/log-level​

Уровень логирования бота

Авторизация: Cookie (connect.sid) или Bearer PAT

logLevel: DEBUG|INFO|WARNING|ERROR. LOG_LEVEL попадёт в env бота при следующем запуске. WS token-updated.

Auth: requireTokenOwnership.

curl -s -X PUT http://localhost:5000/api/projects/42/tokens/7/log-level \
-b cookies.txt -H 'Content-Type: application/json' -d '{"logLevel":"WARNING"}'

Operation ID: put_api_projects_projectId_tokens_tokenId_log_level_139232e1cf093e3d

Тело запроса: LogLevelRequest

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Сохранено
400Недопустимое значение
401Не авторизован
403Нет владения токеном
404Токен не найден

Пример ответа 200​

{
"success": true,
"logLevel": "WARNING"
}

DELETE /api/projects/{projectId}/tokens/{tokenId}/logs​

Очистить live-логи токена

Авторизация: Cookie (connect.sid) или Bearer PAT

Удаляет live-логи (без launch_id) из БД и буфера.

Auth: cookie / Bearer PAT + requireProjectAccess.

curl -s -X DELETE http://localhost:5000/api/projects/42/tokens/7/logs -b cookies.txt

Operation ID: delete_api_projects_projectId_tokens_tokenId_logs_a12504887a7f7a5c

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Очищено
400Некорректные id
401Не авторизован
403Нет доступа

Пример ответа 200​

{
"success": true
}

GET /api/projects/{projectId}/tokens/{tokenId}/logs​

Live-логи бота (bot_logs)

Авторизация: Cookie (connect.sid) или Bearer PAT

Без from/to — последние строки текущего запуска (default limit=500, максимум 1000).

С from/to — сохранённые логи всех запусков токена за период [from, to). Даты ISO с часовым поясом. Для следующей страницы передайте beforeId, равный минимальному id предыдущей страницы. Страницы выбираются по id, строки ответа отсортированы по времени.

Auth: cookie / Bearer PAT + requireProjectAccess.

Клиент: терминал логов бота.

curl -s 'http://localhost:5000/api/projects/42/tokens/7/logs?limit=100' -b cookies.txt

Operation ID: get_api_projects_projectId_tokens_tokenId_logs_b816ce9e34988bf0

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
fromqueryнетНачало периода ISO; требуется вместе с to—
toqueryнетКонец периода ISO; должен быть позже from—
beforeIdqueryнетЗагрузить id меньше курсора; только при заданном периоде—
limitqueryнетМаксимум строк логов: 1–1000 (по умолчанию 500)"500"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Массив строк логов
400Некорректные id, границы периода, лимит или курсор
401Не авторизован
403Нет доступа к проекту

Пример ответа 200​

[
{
"id": 1001,
"projectId": 42,
"tokenId": 7,
"launchId": null,
"content": "Bot started successfully",
"type": "stdout",
"timestamp": "2026-08-11T12:00:00.000Z"
}
]

PUT /api/projects/{projectId}/tokens/{tokenId}/messages-retention​

Срок хранения сообщений диалога

Авторизация: Cookie (connect.sid) или Bearer PAT

Обновляет messagesRetentionDays. 0 — без автоочистки; иначе раз в час чистит bot_messages старше N дней. message_activity_daily не трогается.

Auth: requireTokenOwnership. Side-effect: WS token-updated.

Клиент: настройки токена / retention.

curl -s -X PUT http://localhost:5000/api/projects/42/tokens/7/messages-retention \
-b cookies.txt -H 'Content-Type: application/json' -d '{"messagesRetentionDays":60}'

Operation ID: put_api_projects_projectId_tokens_tokenId_messages_retention_2d9a7efacabdac9a

Тело запроса: UpdateMessagesRetentionRequest

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Настройка сохранена
400Неверный ID или значение вне whitelist
401Не авторизован
403Нет доступа к проекту токена
404Токен не найден

Пример ответа 200​

{
"success": true,
"messagesRetentionDays": 60
}

PUT /api/projects/{projectId}/tokens/{tokenId}/protect-content​

Защита контента (PROTECT_CONTENT)

Авторизация: Cookie (connect.sid) или Bearer PAT

protectContent 0|1 → env бота PROTECT_CONTENT=true/false.

Auth: requireTokenOwnership. WS token-updated. Флаги попадают в env бота при следующем запуске.

curl -s -X PUT http://localhost:5000/api/projects/42/tokens/7/protect-content \
-b cookies.txt -H 'Content-Type: application/json' -d '{"protectContent":1}'

Operation ID: put_api_projects_projectId_tokens_tokenId_protect_content_8eafec40dcda8ea9

Тело запроса: ProtectContentRequest

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Сохранено
400Флаг не 0/1 или значение вне диапазона
401Не авторизован
403Нет владения токеном
404Токен не найден

Пример ответа 200​

{
"success": true,
"protectContent": 1
}

PUT /api/projects/{projectId}/tokens/{tokenId}/save-incoming-media​

Сохранять входящие медиа

Авторизация: Cookie (connect.sid) или Bearer PAT

saveIncomingMedia 0|1 → env бота SAVE_INCOMING_MEDIA.

Auth: requireTokenOwnership. WS token-updated. Флаги попадают в env бота при следующем запуске.

curl -s -X PUT http://localhost:5000/api/projects/42/tokens/7/save-incoming-media \
-b cookies.txt -H 'Content-Type: application/json' -d '{"saveIncomingMedia":1}'

Operation ID: put_api_projects_projectId_tokens_tokenId_save_incoming_media_42e0d27e5f4c3f3c

Тело запроса: SaveIncomingMediaRequest

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Сохранено
400Флаг не 0/1 или значение вне диапазона
401Не авторизован
403Нет владения токеном
404Токен не найден

Пример ответа 200​

{
"success": true,
"saveIncomingMedia": 1
}

PUT /api/projects/{projectId}/tokens/{tokenId}/track-group-membership​

Сохранить слежение за участием бота в группах

Авторизация: Cookie (connect.sid) или Bearer PAT

Настройка сохранена, token-updated публикуется отдельно; применение ENV при следующем запуске.

Operation ID: put_api_projects_projectId_tokens_tokenId_track_group_membership_f066ec46aa06032c

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathда——
tokenIdpathда——

Ответы​

КодОписание
200Настройка записана
400Флаг не 0/1 или значение вне диапазона
401Не авторизован
403Нет владения токеном
404Токен не найден
500Ошибка обновления

PUT /api/projects/{projectId}/tokens/{tokenId}/track-user-blocks​

Отслеживание блокировок пользователей

Авторизация: Cookie (connect.sid) или Bearer PAT

trackUserBlocks 0|1 — обработчик Telegram my_chat_member и системные события в диалогах.

Auth: requireTokenOwnership. WS token-updated. В env бота (при следующем запуске) — 0/1.

Operation ID: put_api_projects_projectId_tokens_tokenId_track_user_blocks_7dbf340b04c2dffa

Тело запроса: TrackUserBlocksRequest

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Сохранено
400Флаг не 0/1 или значение вне диапазона
401Не авторизован
403Нет владения токеном
404Токен не найден

Пример ответа 200​

{
"success": true,
"trackUserBlocks": 1
}

PUT /api/projects/{projectId}/tokens/{tokenId}/userbot​

Настройки Telethon userbot

Авторизация: Cookie (connect.sid) или Bearer PAT

Сохраняет userbotEnabled 0|1 и apiId/hash/session; USERBOT_* попадут в env бота при следующем запуске. Пропущенные поля не меняются. API ID: null или пустая строка очищают значение; API Hash и session string: null, пустая строка или маска сохраняют секрет. MCP: db_set_userbot_settings. Автоматического перезапуска нет. WS token-updated (changedFields: userbotEnabled).

Auth: requireTokenOwnership.

curl -s -X PUT http://localhost:5000/api/projects/42/tokens/7/userbot \
-b cookies.txt -H 'Content-Type: application/json' \
-d '{"userbotEnabled":1,"userbotApiId":"123","userbotApiHash":"abc","userbotSessionString":null}'

Operation ID: put_api_projects_projectId_tokens_tokenId_userbot_fd8b7550187fae6d

Тело запроса: UserbotPutRequest

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Сохранено
400userbotEnabled не 0/1
401Не авторизован
403Нет владения токеном
404Токен не найден

Пример ответа 200​

{
"success": true,
"userbotEnabled": 1
}

POST /api/projects/{projectId}/tokens/{tokenId}/userbot/send-code​

Userbot auth: отправить код

Авторизация: Cookie (connect.sid) или Bearer PAT

Шаг 1: { apiId, apiHash?, phone } → Python userbotAuth. При пропуске, пустой строке или маске apiHash используется сохранённый API Hash. MCP: db_userbot_send_code. Сначала сохраните API ID и Hash через настройки userbot. При успешной отправке кода WS userbot-auth-progress передаёт шаг code и телефон вкладкам с доступом к проекту; код и секреты не передаются.

Auth: requireTokenOwnership.

curl -s -X POST http://localhost:5000/api/projects/42/tokens/7/userbot/send-code \
-b cookies.txt -H 'Content-Type: application/json' \
-d '{"apiId":"123","apiHash":"abc","phone":"+79001234567"}'

Operation ID: post_api_projects_projectId_tokens_tokenId_userbot_send_code_8a3615c3873252ee

Тело запроса: UserbotSendCodeRequest

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Результат send_code
400Валидация body
401Не авторизован
403Нет владения токеном

Пример ответа 200​

{
"ok": true
}

POST /api/projects/{projectId}/tokens/{tokenId}/userbot/sign-in​

Userbot auth: код из SMS/Telegram

Авторизация: Cookie (connect.sid) или Bearer PAT

Шаг 2: { phone, code }. При needs_2fa WS userbot-auth-progress передаёт шаг 2fa и телефон. При session_string — сохраняет в БД + userbotEnabled=1 и отправляет WS token-updated всем вкладкам с доступом к проекту. Секрет сессии в событие не включается. WS userbot-auth-progress передаёт шаг done после входа.

Auth: requireTokenOwnership.

curl -s -X POST http://localhost:5000/api/projects/42/tokens/7/userbot/sign-in \
-b cookies.txt -H 'Content-Type: application/json' \
-d '{"phone":"+79001234567","code":"12345"}'

Operation ID: post_api_projects_projectId_tokens_tokenId_userbot_sign_in_9eaeee4d1d08853f

Тело запроса: UserbotSignInRequest

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Результат / needs_2fa / session
400Валидация body
401Не авторизован
403Нет владения токеном

POST /api/projects/{projectId}/tokens/{tokenId}/userbot/sign-in-2fa​

Userbot auth: пароль 2FA

Авторизация: Cookie (connect.sid) или Bearer PAT

Шаг 3: { password }. При успехе сохраняет session + userbotEnabled=1 и отправляет WS token-updated всем вкладкам с доступом к проекту. Секрет сессии в событие не включается. WS userbot-auth-progress передаёт шаг done после входа.

Auth: requireTokenOwnership.

curl -s -X POST http://localhost:5000/api/projects/42/tokens/7/userbot/sign-in-2fa \
-b cookies.txt -H 'Content-Type: application/json' -d '{"password":"…"}'

Operation ID: post_api_projects_projectId_tokens_tokenId_userbot_sign_in_2fa_7831afac81178311

Тело запроса: UserbotSignIn2faRequest

Параметры​

ИмяInОбязательныйОписаниеПример
projectIdpathдаЧисловой ID проекта"42"
tokenIdpathдаЧисловой ID токена бота"7"
AuthorizationheaderнетAuthorization: Bearer mcp_… — PAT агента (альтернатива cookie)"Bearer mcp_xxxxxxxx"
connect.sidcookieнетSession cookie после login. Не нужна при Authorization: Bearer mcp_…"s%3Axxxx.yyyy"

Ответы​

КодОписание
200Результат 2FA
400Валидация body
401Не авторизован
403Нет владения токеном