Версии ассистента в API bota.chat: история изменений на графиках

Что такое версия

Версия отмечает, что и когда вы поменяли в ассистенте: подняли цены, добавили язык, переписали промпт, убрали источник трафика. Версии видны в визарде на слайде «Версии» и точками под графиками в обзоре. Глядя на скачок конверсии, сразу видно, какое изменение в этот день вышло. Панель сравнения в обзоре берёт две последние версии по дате и сравнивает периоды до и после.

Версия принадлежит ассистенту, а не пользователю: её видят и правят все, у кого есть доступ к ассистенту.

Удобный сценарий для скриптов и AI-агентов: после каждого значимого изменения ассистента создавайте версию с коротким описанием в Markdown.

Свойства версии

Свойство	Тип	Описание
`id`	integer	id версии
`project_id`	integer	id ассистента (имя поля историческое)
`number`	string	Номер или метка, до 64 символов: `"3"`, `"2.1-beta"`. Не передан — следующий по порядку (см. ниже)
`version_date`	string или null	Дата, к которой относится изменение, в виде `YYYY-MM-DD HH:MM:SS`. По ней ставится точка на графике. `null` — точка по `created_at`
`description`	string или null	Описание в Markdown, до 50 000 символов
`config`	object или null	Снимок настроек, зарезервировано. Сейчас нигде не используется
`created_at`, `updated_at`	string	ISO 8601, UTC

В списке версий приходят только id, number, version_date, description, created_at. Полный объект — при чтении одной версии, создании и изменении.

Автономер

Если number не передан или пустой, сервер берёт наибольший числовой номер среди версий ассистента и прибавляет единицу. Нечисловая часть номера отбрасывается: после "2.1-beta" следующей будет "3". Первая версия ассистента получает "1". Номера не обязаны быть уникальными — сервер это не проверяет.

Формат даты

date принимает любую строку, которую понимает разбор дат PHP. Надёжные варианты:

Передали	Записано в `version_date`
`2026-09-25`	`2026-09-25 00:00:00`
`2026-09-24 14:30`	`2026-09-24 14:30:00`
`null` или `""`	`null`

Время хранится без часового пояса и трактуется как UTC. На графике точка ставится по дню, время не учитывается.

Методы

Список версий

Все версии ассистента, новые сверху (по убыванию id). Пагинации нет.

GET /assistants/{assistantId}/versions

Параметр	Тип	Обяз.	Описание
`assistantId`	integer	да	id ассистента, в пути

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

{
  "success": true,
  "versions": [
    {
      "id": 39,
      "number": "3",
      "version_date": null,
      "description": "Убрали трафик из каталога GPT",
      "created_at": "2026-09-25T19:47:39.000000Z"
    },
    {
      "id": 38,
      "number": "2.1-beta",
      "version_date": "2026-09-24 14:30:00",
      "description": "## Цены\n\n- Неделя 490 ₽ вместо 390 ₽",
      "created_at": "2026-09-25T19:47:36.000000Z"
    }
  ]
}

HTTP	Когда
`404`	`{"error": "Project not found or access denied"}` — ассистент чужой или не существует, как во всех методах ассистента

Создать версию

POST /assistants/{assistantId}/versions

Параметр	Тип	Обяз.	Описание
`assistantId`	integer	да	id ассистента, в пути
`number`	string	нет	Номер, до 64 символов. Именно строка: число `123` не пройдёт валидацию. Не передан или пустой — автономер
`date`	string	нет	Дата изменения, см. «Формат даты». Не передана — `version_date` пустая
`description`	string	нет	Markdown, до 50 000 символов
`config`	object	нет	Снимок настроек, зарезервировано

Все поля необязательные: пустое тело создаст версию только с автономером.

curl -s -X POST "$BASE/assistants/$ASSISTANT/versions" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"date": "2026-09-25", "description": "## Цены\n\n- Неделя 490 ₽ вместо 390 ₽"}'

Ответ 201:

{
  "success": true,
  "version": {
    "project_id": 53,
    "number": "1",
    "version_date": "2026-09-25 00:00:00",
    "description": "## Цены\n\n- Неделя 490 ₽ вместо 390 ₽",
    "config": null,
    "updated_at": "2026-09-25T19:47:33.000000Z",
    "created_at": "2026-09-25T19:47:33.000000Z",
    "id": 37
  }
}

HTTP	Когда
`404`	`{"error": "Project not found or access denied"}` — ассистент чужой или не существует
`422`	Ошибка валидации, пример ниже

{
  "success": false,
  "errors": {
    "number": ["The number field must be a string."],
    "date": ["The date field must be a valid date."],
    "description": ["The description field must be a string."]
  }
}

Получить версию

GET /assistants/{assistantId}/versions/{versionId}

Параметр	Тип	Обяз.	Описание
`assistantId`	integer	да	id ассистента, в пути
`versionId`	integer	да	id версии, в пути

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

{
  "success": true,
  "version": {
    "id": 37,
    "project_id": 53,
    "number": "1",
    "version_date": "2026-09-25 00:00:00",
    "description": "## Цены\n\n- Неделя 490 ₽ вместо 390 ₽",
    "config": null,
    "created_at": "2026-09-25T19:47:33.000000Z",
    "updated_at": "2026-09-25T19:47:33.000000Z"
  }
}

HTTP	Когда
`404`	`{"error": "Project not found or access denied"}` — ассистент чужой или не существует; `{"error": "Version not found"}` — версия другого ассистента; `{"success": false, "error": "No query results for model …"}` — версии с таким id нет вовсе

Изменить версию

Частичное обновление: меняются только переданные поля.

PUT /assistants/{assistantId}/versions/{versionId}

Параметр	Тип	Обяз.	Описание
`assistantId`	integer	да	id ассистента, в пути
`versionId`	integer	да	id версии, в пути
`number`	string	нет	Новый номер, до 64 символов. Пустая строка игнорируется — номер остаётся прежним
`date`	string или null	нет	Новая дата. `null` или `""` очищает `version_date`
`description`	string или null	нет	Новое описание, до 50 000 символов. `null` очищает
`config`	object или null	нет	Снимок настроек

curl -s -X PUT "$BASE/assistants/$ASSISTANT/versions/37" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "## Цены\n\n- Неделя 490 ₽, месяц 1290 ₽"}'

Ответ — полный объект версии, как у «Получить версию», с новым updated_at.

HTTP	Когда
`404`	`{"error": "Project not found or access denied"}` — ассистент чужой или не существует; `{"error": "Version not found"}` — версия другого ассистента; `{"success": false, "error": "No query results for model …"}` — версии с таким id нет вовсе
`422`	Ошибка валидации, как при создании

Удалить версию

DELETE /assistants/{assistantId}/versions/{versionId}

Параметр	Тип	Обяз.	Описание
`assistantId`	integer	да	id ассистента, в пути
`versionId`	integer	да	id версии, в пути

curl -s -X DELETE "$BASE/assistants/$ASSISTANT/versions/37" \
  -H "Authorization: Bearer $KEY"

{ "success": true }

HTTP	Когда
`404`	`{"error": "Project not found or access denied"}` — ассистент чужой или не существует; `{"error": "Version not found"}` — версия другого ассистента; `{"success": false, "error": "No query results for model …"}` — версии с таким id нет вовсе