Документация по API

Публичный API платформы EvoAI подключает агента к вашему приложению или сервису и позволяет управлять базами знаний без интерфейса платформы. Здесь описаны все методы API, формат запросов и ответов, ошибки и ограничения.

Видеоинструкция по подключению агента и базы знаний через API

Базовый URL

https://api.evo-ai.ru/v1

В описании методов путь указан целиком, вместе с /v1: POST /v1/chat — это запрос POST https://api.evo-ai.ru/v1/chat.

API-ключи

Ключ передаётся в заголовке Authorization каждого запроса:

Authorization: Bearer {ваш_API_ключ}

У API два вида ключей, и каждый открывает только свою часть методов:

Ключ агента не подходит к методам баз знаний, а ключ баз знаний — к методам агента: API ответит 401 с кодом invalid_api_key. Ключи, созданные до перехода на префиксы evo_agent_ и evo_kb_, продолжают работать.

Доступ по API у агента включается и выключается в блоке API на вкладке Управление; у базы знаний он включён по умолчанию. Пока доступ выключен, запросы получают 403 с кодом api_disabled.

Формат запросов и ответов

• Тело запросов и ответов — JSON в кодировке UTF-8. Файлы загружаются как multipart/form-data.

• Идентификаторы объектов — строки в формате UUID.

• Время — строка ISO 8601 в UTC, например 2026-09-24T10:15:00Z.

• Создание объекта возвращает 201 и созданный объект. Удаление и действия без результата возвращают 204 без тела.

• API строго проверяет запрос: параметр, которого нет в описании метода, обязательный параметр, который не передан, значение неверного типа или вне допустимых границ — ошибка 400 с кодом invalid_request. Когда параметр известен, поле error.details называет его и причину.

• PATCH меняет только переданные поля. null допустим только там, где значение можно очистить, — например, в описании базы знаний: оно станет пустой строкой. В остальных полях null — ошибка invalid_request.

• Идентификатор в пути, который не является UUID, — ответ 404 с кодом not_found: такого пути в API нет.

• DELETE можно повторять: если объекта уже нет, ответ тоже 204.

Списки

Списки баз знаний, документов, фрагментов и оценок — постраничные:

{
  "items": [ ... ],
  "total": 42,
  "has_more": true
}

Списки диалогов и сообщений диалога — с курсором: вместо номера страницы передайте в cursor значение next_cursor из предыдущего ответа. limit — от 1 до 100, по умолчанию 20. Когда has_more — false, список закончился.

{
  "items": [ ... ],
  "has_more": true,
  "next_cursor": "8f1c2e4a-6b0d-4f7e-9a3c-2d5b7e9f1a04"
}

Ошибки

Ответ с ошибкой содержит объект error с кодом и текстом:

{
  "error": {
    "code": "invalid_request",
    "message": "Неверный запрос",
    "details": {
      "limit": "Значение вне допустимых границ"
    }
  }
}

Поле details бывает только у кода invalid_request. Опирайтесь в коде на error.code: текст message предназначен для человека и может меняться. Все коды — на странице Ошибки.

Ограничения

• Частота запросов. У отправки сообщений агенту ограничено число одновременных запросов и число запусков по тарифу, у баз знаний — число запросов, которые меняют базы знаний, документы и фрагменты, по тарифу. Сверх лимита API отвечает 429 с кодом rate_limited — повторите запрос позже.

• e^кредиты. Сообщение агенту через API расходует столько же e^кредитов, сколько такое же сообщение в чате по ссылке. Когда e^кредиты пространства закончились, API отвечает 429 с кодом credits_exhausted, и текст ошибки называет время, когда доступ восстановится.

• Лимиты тарифа для баз знаний. Сверх лимита документов или объёма тарифа добавление документа получает 403 с кодом document_limit_reached или storage_limit_reached.

Прежняя версия API

Разделы API

Агенты

Работа с одним агентом: его настройки, отправка сообщений и поток ответа, диалоги, оценки, файлы.

Базы знаний

Управление базами знаний рабочего пространства: создание и настройка, документы, фрагменты, теги.

Ошибки

Формат ошибки и все коды ошибок API.

Спецификация OpenAPI

Машиночитаемое описание всех методов в формате Swagger 2.0: evo-ai-api.yaml. Поток событий ответа агента и формат ошибок описаны на страницах Отправка сообщений и Ошибки.