REST API bota.chat: обзор, быстрый старт и карта разделов

Что это

REST API даёт то же, что дашборд и визард: создать ассистента, настроить бота и модели, завести агентов и первые экраны, собрать пейволл, подключить домен и Telegram, читать подписчиков, платежи, события и обращения. Всё, что вы делаете руками в интерфейсе, можно повторить скриптом, CI или AI-агентом.

API рассчитано на владельца ассистента и на тех, кому владелец открыл к нему доступ. Посетители чата с ним не работают, для них есть виджет и страница чата.

Базовый адрес всех методов:

https://framesuite.app/api/v1

Дальше в примерах пути пишутся от него: GET /assistants значит GET https://framesuite.app/api/v1/assistants. В примерах используются переменные окружения:

export BASE=https://framesuite.app/api/v1
export KEY=user_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX   # личный ключ
export ASSISTANT=53                                        # id ассистента

Ассистент

Всё в API строится вокруг ассистента: у каждого свой бот, агенты, пейволл, домен и подписчики. В путях его id — assistantId, это тот же id, что в дашборде в адресе /dashboard/assistants/{id}. В JSON поля по историческим причинам называются project, project_id и projects — это объект ассистента, его id и список ассистентов.

Где взять id:

Способ	Что сделать
Через API	`GET /assistants` — список ваших и расшаренных вам ассистентов, поле `id`
В дашборде	Откройте ассистента: адрес страницы `https://framesuite.app/dashboard/assistants/{id}`, число в адресе и есть id

Быстрый старт

Нужен личный ключ user_… — его выпускают в дашборде в разделе «Настройки → API ключ», подробно на странице Авторизация.

1. Найти своего ассистента

curl -s "$BASE/assistants" \
  -H "Authorization: Bearer $KEY"

{
  "success": true,
  "projects": [
    {
      "id": 53,
      "name": "bota.chat",
      "frame_slug": "x8OA7Azs4hBy",
      "custom_domain": "bota.chat",
      "bot_name": "Новый ассистент",
      "default_locale": "ru",
      …
    }
  ]
}

Полное описание объекта — на странице Ассистенты.

2. Прочитать настройки бота

curl -s "$BASE/assistants/$ASSISTANT/bot" \
  -H "Authorization: Bearer $KEY"

{
  "success": true,
  "name": "bota.chat",
  "bot_name": "Новый ассистент",
  "bot_avatar": "default",
  "avatar_type": "persona",
  "thinking_text": "Думаю...",
  "response_style": "text",
  "ai_model": "default-model",
  "currency": "RUB",
  "welcome_message": "Чем могу помочь?",
  …
}

Что здесь можно поменять — Настройки бота и шапка.

3. Создать агента

Агент — кнопка на первом экране со своим промптом, картинкой и вариантами ответа. Запрос ниже создаёт агента у ассистента, поэтому запускайте его на своём тестовом ассистенте.

curl -s -X POST "$BASE/assistants/$ASSISTANT/agents" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Составить резюме",
    "prompt": "Помоги составить резюме. Сначала спроси про опыт и желаемую должность.",
    "category": "Работа"
  }'

Все свойства агента, порядок и картинки — в разделе Агенты.

Как устроены ответы

Все ответы — JSON в UTF-8. Успешный ответ почти всегда содержит "success": true и данные рядом: объект (project, version), список (projects, versions) или поля настроек плоско.

Методы, которые сохраняют настройки ассистента (PUT на /bot, /onboarding, /features, /delay, /models, /paywall), дополнительно сообщают, что записано и что пропущено:

{
  "success": true,
  "applied": ["thinking_text"],
  "ignored": ["thinkng_text"],
  "warning": "Some fields were ignored: thinkng_text"
}

Незнакомое поле по умолчанию только попадает в ignored. С strict=true (в теле или в строке запроса) такой запрос отбивается ошибкой 422 и ничего не пишет.

Ошибка — HTTP-код 4xx или 5xx и тело с полем error (строка) или errors (поля валидации):

{ "error": "Project not found or access denied" }

{ "success": false, "errors": { "url": ["The url field must be a valid URL."] } }

Формы ошибок немного отличаются между разделами, все варианты собраны на странице Ошибки и ответы.

Ответ всегда JSON, заголовок Accept не обязателен. Тело, которое не разбирается как JSON, отбивается кодом 400 с "error": "invalid_json" и ничего не записывает.

Лимиты

Ограничения частоты запросов (rate limit) у API сейчас нет: ни на маршрутах, ни на уровне веб-сервера. Это не приглашение к тысячам запросов в секунду — массовые операции делайте последовательно или небольшими порциями.

Действуют ограничения на размер:

Что	Лимит
Тело запроса целиком	50 МБ (веб-сервер)
Картинка через `upload/image`	5 МБ; GIF 4 МБ; видео mp4/webm 8 МБ
Аватар бота	10 МБ
Файл базы знаний агента	10 МБ, до 200 файлов на агента
Вложение обращения	50 МБ, до 5 файлов за запрос

Подробнее — Загрузка файлов.

Разделы

Раздел	О чём
Авторизация	Личный ключ `user_…`, где выпустить, как передать, каких ассистентов он видит
Ошибки и ответы	Коды, формы ошибок, CORS, кодировки, частичные обновления
Ассистенты	Список, чтение, создание и удаление ассистента, полный объект ассистента, ключ ассистента
Доступ	Кому открыт ассистент, как расшарить и закрыть доступ
Версии	История изменений ассистента — точки на графиках обзора
Загрузка файлов	Картинки и видео для карточек и сообщений, сводка всех загрузок в API
Настройки бота и шапка	Имя, аватар, стиль ответа, логотипы, системный промпт
Модели	Каталог моделей, модели ассистента, модели картинок, маржа
Возможности, сайдбар и задержка	Картинки, поиск, голос, боковая панель, пауза перед ответом
Языки и переводы	Языки ассистента, язык по умолчанию, переводы интерфейса
Домены, Telegram, встраивание	Свой домен, Telegram-бот и Mini App, код встраивания, ссылки
Агенты	Создание, изменение, порядок и удаление агентов
Агенты → Свойства config	Все свойства агента: промпты, режимы, картинки, варианты ответа
Агенты → Экран-профиль и ссылки	Страница агента, ссылки `?agent=`, профиль
Агенты → База знаний	Файлы, по которым отвечает агент
Каталог «Помощники»	Витрина агентов в чате: тексты, теги, категории
Сценарии	Готовые последовательности запросов под частые задачи
Первые экраны (welcome)	Приветствие, секции карточек, несколько входов у одного ассистента
Онбординг	Слайды перед первым сообщением
Шаблоны и подвал	Подвал первого экрана, пункты боковой панели, тексты каталогов
Пейволл и тарифы	Тарифы, цены по языкам, тексты, способы оплаты
Свои HTML-шаблоны	Свой пейволл и другие экраны в HTML
Свои HTML-шаблоны → Фреймы агента	HTML-экраны внутри агента
Партнёрская программа	Процент партнёра, начисления, партнёрский агент
Подписчики, кредиты, платежи	Подписки, начисление кредитов, транзакции
События и аналитика	События, сводка, воронка
Поддержка и обращения	Лицо поддержки, обращения, ответы, вложения, переводы
Чаты по ключу ассистента	Создать чат и отправить сообщение по ключу `site_…`