Справочник по Jenova Agent API

Базовый URL: https://api.jenova.ai/v1

Аутентификация: Bearer token в заголовке Authorization

Содержание

• Обзор
• Быстрый старт
• Основные понятия
• Аутентификация
• Конечные точки API
  • Сообщения
  • Сессии
  • Операции
  • Кредиты
  • Агенты
  • Модели
  • Документация
• Потоковая передача (SSE)
• Интеграция MCP-сервера
• Биллинг
• Ограничения скорости
• Обработка ошибок
• Пагинация
• Локализация
• Конфиденциальность и данные
• Поддержка

Обзор

Запускайте собственных агентов в вашем продукте или рабочем процессе за считаные минуты. Настройте агентов под любую задачу, выберите любую модель и инструменты, а Jenova обеспечит агентный харнесс, базу данных и масштабирование.

Полный агентный стек:

• Управляемый агентный харнесс: На входе один запрос — на выходе готовая работа. Ваш агент проводит исследование, рассуждает, вызывает инструменты и создаёт файлы — точно так, как вы указали.
• Безграничный контекст и память: Управление контекстом на основе RAG и собственный механизм отслеживания состояния сессии обеспечивают неограниченную память в рамках одного диалога.
• Библиотека инструментов и MCP: Подключайтесь к нашей библиотеке из 30+ инструментов и MCP-серверов, таких как поиск, генерация изображений, почта и многое другое, — или добавьте собственные MCP-серверы.
• Лёгкий переход на любую модель: Запускайте модели от OpenAI, Anthropic, Google, xAI или ведущих open-source-провайдеров и переключайтесь между ними одним параметром.
• Управляемые знания и RAG: Jenova берёт на себя сквозной RAG-конвейер — чанкинг, индексацию, хранение и поиск.
• Проверено в масштабе: Разворачивайте агентов на проверенной в бою инфраструктуре, где уже работают сотни агентов в продакшне. Ноль кластеров, которые нужно поднимать, масштабировать и обслуживать.

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

1. Получите ваш API-ключ

Сгенерируйте API-ключ в панели управления разработчика на www.jenova.ai/platform. Ключи имеют формат jnv_sk_* и передаются как Bearer token.

2. Выберите или создайте агента

Выберите готового агента на платформе или создайте собственного агента в панели управления с инструкциями, настройками модели, файлами базы знаний, инструментами и MCP-серверами.

3. Отправьте ваше первое сообщение

Создайте сессию и отправьте сообщение за один вызов:

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "What can you help me with?"
  }'

Ответ передаётся потоком в виде Server-Sent Events:

event: stream_started
data: {"session_id":"ses_xyz789","run_id":"run_abc123","agent":"my-support-agent"}

event: stream_delta
data: {"session_id":"ses_xyz789","run_id":"run_abc123","chunk_content":"I can help you with ","seq":1}

event: stream_ended
data: {"session_id":"ses_xyz789","run_id":"run_abc123","success":true,"stop_reason":"end_run","usage":{"cost":"0.0032"}}

Сохраните session_id из stream_started для последующих запросов. Синхронные JSON-ответы описаны в разделе Отправить сообщение.

Основные понятия

Агент

AI-агент, с которым вы взаимодействуете через API. У каждого агента есть уникальный slug (например, my-support-agent), используемый как значение agent в вызовах API.

• Готовые агенты: выбирайте из существующих агентов на платформе.
• Собственные агенты: настраивайте собственного агента в панели управления с инструкциями, моделью, базой знаний, инструментами и MCP-серверами.

Сессия

Независимый поток диалога между конечным пользователем и агентом.

• Идентификатор: ID с префиксом (например, ses_abc123).
• Область действия: для одного и того же агента и конечного пользователя может существовать несколько сессий, каждая с независимым состоянием диалога.
• Жизненный цикл: сессии сохраняются неограниченно долго, пока не будут удалены через API. Для одноразовых задач, которым не нужна сессия, используйте POST /messages с ephemeral: true.
• Изоляция платформы: сессии API отделены от диалогов в веб-приложении Jenova. Конечные пользователи, история сессий и биллинг независимы между API и веб-приложением.

Сообщение

Отдельная запись в истории диалога сессии, возвращаемая конечными точками Сообщений. Каждое сообщение включает структурированный объект from с полями type (user или agent) и name, а также type самого сообщения:

• external — сообщение диалога, предназначенное для отображения в качестве содержимого чата.
• internal — необязательное сообщение, представляющее рабочие шаги агента во время запуска, такие как вызовы инструментов или извлечение данных.

Запуск

Отдельное выполнение агента, создаваемое при отправке сообщения. У запуска есть run_id, он может передавать события потоком, пока активен, и может производить одно или несколько завершённых сообщений. У каждой сессии в любой момент времени может быть только один активный запуск.

Конечный пользователь

Поле user привязывает сессии к конечному пользователю в вашем приложении. Используйте стабильный непрозрачный идентификатор, например ваш внутренний ID пользователя или UUID. Избегайте использования email-адресов и другой личной информации, если это не требуется вашим приложением. Сессии, созданные с одинаковым значением user, группируются вместе, что позволяет получать списки сессий по конкретному пользователю.

Если user не указан, сессия привязывается к вашей учётной записи разработчика и позже не может быть отфильтрована по конечному пользователю. В продакшене передавайте user.

Для запросов к существующей сессии (любая конечная точка с {session_id} в пути) user является необязательным механизмом проверки владения. Если вы его укажете, значение должно совпадать со значением user, использованным при создании сессии; в противном случае API возвращает 404 session_not_owned. Передавайте его как параметр запроса в запросах GET и DELETE и в теле JSON в запросах POST и PATCH. Параметр запроса user в запросах POST или PATCH возвращает 400 bad_request.

Аутентификация

Аутентифицируйте каждый запрос с помощью Bearer token в заголовке Authorization:

Authorization: Bearer jnv_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API-ключи создаются в панели управления разработчика.

User-Agent необязателен. SDK могут задавать его для диагностики, но API этого не требует.

Формат ключа: ключи начинаются с префикса jnv_sk_, за которым следует случайная строка в кодировке base62.

Лимиты: каждая учётная запись разработчика может иметь до 10 активных API-ключей.

Конечные точки API

Сообщения

Отправка сообщений — основной путь API. Используйте POST /messages для первого сообщения; он создаёт сессию и запускает запуск в рамках одного запроса. Используйте POST /sessions/{session_id}/messages при продолжении сохранённого session_id.

Отправить сообщение

POST /messages

Создаёт постоянную сессию и отправляет первое сообщение в рамках одного запроса. Установите ephemeral: true для одноразового потокового запроса, который не возвращает ID сессии и не может быть продолжен. Его данные удаляются вскоре после завершения запроса.

Тело запроса

Пример — потоковая передача (по умолчанию)

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello, I need help with my account"
  }'

Ответ представляет собой SSE-поток (формат событий см. в разделе Потоковая передача (SSE)). Постоянные запросы включают новый session_id; запросы с ephemeral: true не содержат session_id и должны использовать потоковую передачу.

Пример — JSON (без потоковой передачи)

curl -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello, I need help with my account",
    "stream": false
  }'

Ответ

Потоковые ответы передают события SSE, описанные в разделе Потоковая передача (SSE). Ответы без потоковой передачи возвращают объект сообщения с stop_reason и usage для запроса, как показано в разделе Продолжить сессию. stop_reason имеет значение end_run или user_cancelled, если запуск был отменён после того, как агент создал сообщение.

Если запуск отменён до того, как агент создал сообщение, API возвращает 200 OK со значениями status: "cancelled", session_id, run_id, stop_reason: "user_cancelled" и usage.

Если запуск без потоковой передачи всё ещё обрабатывается спустя 90 секунд, API возвращает 202 Accepted со значением status: "processing", а также session_id, run_id и понятное человеку сообщение message. Запуск продолжается после завершения ответа или отключения клиента; проверяйте сообщения сессии либо используйте потоковую передачу для более длительных рабочих процессов.

Ошибки

Продолжить сессию

POST /sessions/{session_id}/messages

Отправляет сообщение в существующую постоянную сессию и получает ответ агента. По умолчанию ответы передаются потоково через SSE; установите stream: false для JSON.

Тело запроса

Пример — потоковая передача (по умолчанию)

curl -N -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?"
  }'

Пример — JSON (без потоковой передачи)

curl -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?",
    "stream": false
  }'

Ответ 200 OK

{
  "id": "msg_xyz789",
  "session_id": "ses_abc123",
  "sequence": 4,
  "from": {
    "type": "agent",
    "name": "my-support-agent"
  },
  "type": "external",
  "time": "2026-05-19T10:31:05Z",
  "content": "To reset your password, go to Settings > Security > Change Password...",
  "model": "claude-sonnet-5",
  "files": [],
  "stop_reason": "end_run",
  "usage": {
    "cost": "0.0015"
  }
}

Если в сессии уже есть активный запуск или сообщения в очереди, API возвращает JSON 202 Accepted со значениями status: "queued", session_id, run_id и message_id. Сообщение пользователя обрабатывается активным запуском. Запросы с additional_context вместо этого возвращают 409 busy.

Ответы без потоковой передачи подчиняются тем же правилам, что и в разделе Отправить сообщение, включая ответ status: "cancelled", когда запуск отменён до того, как агент создал сообщение.

Ошибки

Идемпотентность

POST /messages, POST /sessions/{session_id}/messages и POST /invoke принимают необязательный заголовок Idempotency-Key (максимум 255 символов). Используйте уникальный ключ для каждой логической отправки от пользователя, чтобы повторные попытки сети или повторные отправки не создавали дублирующиеся запуски. Ключи хранятся 24 часа.

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-user_12345-2026-05-19T10:30:00Z" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello"
  }'

Без потоковой передачи: повторная попытка возвращает сохранённый ответ с заголовком Idempotent-Replayed: true, включая ошибки, возвращённые после начала обработки запроса. Сохранённый ответ 202 Accepted воспроизводится без изменений; чтобы проверить результат, используйте Получить статус запуска или Список сообщений. Запросы, отклонённые до начала обработки, например из-за ошибок валидации или нехватки кредитов, не сохраняются, поэтому повторная попытка обрабатывается заново.

Потоковая передача: поток не воспроизводится повторно. Для POST /messages и POST /sessions/{session_id}/messages повторная попытка во время выполнения или после завершения возвращает ошибку идемпотентности с исходным run_id и, для персистентных запросов, session_id. Для персистентных запросов используйте Получить статус запуска для проверки активного запуска или Список сообщений для получения сохранённых результатов. Результаты потокового POST /invoke нельзя получить после закрытия потока. Повторные запросы POST /invoke возвращают исходный id вместо run_id и session_id.

Пример повторной попытки после завершённой потоковой передачи:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key has already completed. Streaming responses cannot be replayed; use the returned session_id and run_id to retrieve the result."
  },
  "idempotency": {
    "status": "completed",
    "session_id": "ses_abc123",
    "run_id": "run_abc123"
  }
}

Ошибки идемпотентности

Список сообщений

GET /sessions/{session_id}/messages

Возвращает постраничный список сообщений сессии. По умолчанию возвращаются только сообщения разговора типа external. Первая страница содержит самые последние сообщения; в рамках каждой страницы сообщения расположены в хронологическом порядке (от старых к новым). sequence — это порядковый номер сообщения в рамках сессии.

Параметры запроса

Пример

curl "https://api.jenova.ai/v1/sessions/ses_abc123/messages?limit=50" \
  -H "Authorization: Bearer jnv_sk_xxx"

Ответ 200 OK

{
  "items": [
    {
      "id": "msg_002",
      "session_id": "ses_abc123",
      "sequence": 4,
      "from": {
        "type": "agent",
        "name": "my-support-agent"
      },
      "type": "external",
      "time": "2026-05-19T10:31:05Z",
      "content": "To reset your password, go to Settings > Security...",
      "model": "claude-sonnet-5",
      "stop_reason": "end_run"
    }
  ],
  "next_cursor": "",
  "has_more": false
}

Объект сообщения

Объект файла

Ошибки

Получить сообщение

GET /sessions/{session_id}/messages/{message_id}

Получает одно сообщение по ID.

Параметры запроса

Ответ 200 OK

Возвращает объект одного сообщения с той же структурой, что и в ответе списка.

Ошибки

Вложения файлов

Передайте общедоступные URL-адреса HTTPS в поле file_urls.

Поддерживаемые форматы

• Изображения: JPG, JPEG, PNG, WebP
• Документы: PDF, DOCX, XLSX, PPTX, TXT, CSV, RTF, MD, HTML, XML, JSON, LOG
• Код: JS, TS, TSX, JSX, PY, Java, Go, C, CPP, H, HPP, CS, RB, PHP, RS, Swift, KT, Scala, SQL, CSS, YAML, YML

URL файлов загружаются, когда агент читает их во время запуска, а не при принятии запроса. URL, который не удаётся загрузить, или файл размером более 20 МБ не читается; сам запрос при этом не отклоняется.

При получении списка сообщений прикреплённые файлы отображаются в массиве files сообщения.

Дополнительный контекст

Передайте в additional_context именованный контекст для одного сообщения, например сведения об учётной записи конечного пользователя. Он не сохраняется в истории сообщений.

Используйте описательное имя, например customer_profile или order_details.

Элемент с отсутствующим или нестроковым name или content возвращает 400 invalid_payload. Другие недопустимые элементы возвращают 400 bad_request.

curl -N -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?",
    "additional_context": [
      {
        "name": "customer_profile",
        "content": "Plan: Pro. Last login: 2026-05-18."
      }
    ]
  }'

Сессии

Сессии — это постоянные разговоры между конечным пользователем и агентом. Большинство интеграций может создавать их неявно с помощью POST /messages.

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

POST /sessions

Создаёт пустую постоянную сессию, привязанную к определённому агенту. Используйте этот метод, когда вам нужен ID сессии до отправки первого сообщения; в остальных случаях предпочтительнее использовать POST /messages.

Примечание: параметр ephemeral не принимается в POST /sessions; используйте POST /messages с ephemeral: true для одноразовых запросов.

Тело запроса

Пример

curl -X POST https://api.jenova.ai/v1/sessions \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "session_name": "Billing inquiry"
  }'

Ответ 201 Created

{
  "id": "ses_abc123",
  "session_name": "Billing inquiry",
  "agent": "my-support-agent",
  "user": "user_12345",
  "model": "claude-sonnet-5",
  "created_at": "2026-05-19T10:30:00Z",
  "updated_at": "2026-05-19T10:30:00Z"
}

Объект сессии

Ошибки

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

GET /sessions

Возвращает разбитый на страницы список ваших сессий, упорядоченный по времени последнего обновления.

Параметры запроса

Пример

curl "https://api.jenova.ai/v1/sessions?user=user_12345&limit=10" \
  -H "Authorization: Bearer jnv_sk_xxx"

Ответ 200 OK

{
  "items": [
    {
      "id": "ses_abc123",
      "session_name": "Billing inquiry",
      "agent": "my-support-agent",
      "user": "user_12345",
      "model": "claude-sonnet-5",
      "created_at": "2026-05-19T10:30:00Z",
      "updated_at": "2026-05-19T11:15:00Z"
    }
  ],
  "next_cursor": "2026-05-19T11:15:00Z|ses_abc123",
  "has_more": true
}

Ошибки

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

GET /sessions/{session_id}

Возвращает одну сессию по ID.

Параметры запроса

Ответ 200 OK

Возвращает объект сессии.

Ошибки

Переименовать сессию

PATCH /sessions/{session_id}

Обновляет отображаемое имя сессии.

Тело запроса

Ответ 200 OK

Возвращает обновлённый объект сессии.

Ошибки

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

DELETE /sessions/{session_id}

Безвозвратно удаляет сессию и все её сообщения. У сессии не должно быть активного запуска.

Ответ 204 No Content

Ошибки

Операции

Эти конечные точки предназначены для восстановления и редактирования постоянных сессий. В большинстве интеграций требуется только отмена активного запуска; остальные операции используются, когда вы намеренно хотите изменить или восстановить состояние сессии. Все операции поддерживают необязательную защиту владения через параметр user, описанную в разделе Конечный пользователь.

Отменить активный запуск

POST /sessions/{session_id}/cancel

Отменяет активный запуск агента. Сообщения, уже завершённые до отмены, не удаляются.

Тело запроса

Ответ 204 No Content

Ошибки

Откатить активный запуск

POST /sessions/{session_id}/undo

Отменяет активный запуск, ожидает его остановки, а затем удаляет все сообщения, которые он уже добавил. После выдачи команды отката никакие дополнительные выходные данные не сохраняются.

Тело запроса

Ответ 200 OK

{
  "session_id": "ses_abc123",
  "run_id": "run_abc123",
  "deleted": ["msg_002", "msg_001"]
}

Если запуск отменяется до завершения хотя бы одного сообщения, deleted будет пустым массивом.

Ошибки

Удалить последние сообщения

POST /sessions/{session_id}/messages/delete

Удаляет count самых последних сообщений из неактивной сессии, включая сообщения internal. Чтобы увидеть их, используйте include=all в запросе Список сообщений. Сессия не должна иметь активного запуска.

Тело запроса

Ответ 200 OK

{
  "deleted": ["msg_002", "msg_001"]
}

Ошибки

Форк сессии

POST /sessions/{session_id}/fork

Создаёт новую сессию, копируя исходную сессию до определённого сообщения. У исходной сессии не должно быть активного запуска.

Тело запроса (необязательно)

Ответ 201 Created

Возвращает объект новой созданной сессии с той же структурой, что и при создании сессии.

Ошибки

Получить статус запуска

GET /sessions/{session_id}/runs/{run_id}

Возвращает текущее состояние активного запуска. Используйте этот метод после разрыва SSE-соединения или после ответа на идемпотентный запрос, который вернул run_id. После завершения запуска получите результаты с помощью GET /sessions/{session_id}/messages.

Ответ 200 OK

{
  "session_id": "ses_abc123",
  "run_id": "run_abc123",
  "status": "streaming",
  "started_at": "2026-05-19T10:30:00Z",
  "updated_at": "2026-05-19T10:30:06Z",
  "content": "Partial visible response text so far"
}

status имеет значение running, пока агент работает, streaming, когда формируется текст ответа, или ended в течение короткого времени после завершения запуска. Ответ также может включать progress_events с последней активностью в том же формате, что и stream_progress. Если status равен ended или запрос возвращает 404 not_found, получите сообщения сессии.

Ошибки

Кредиты

Получить баланс

GET /credits/balance

Возвращает ваш текущий баланс кредитов.

Ответ 200 OK

{
  "balance": "123.45"
}

Агенты

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

Запланированные/фоновые рабочие процессы в настоящее время не поддерживаются через API. Поддержка появится в ближайшее время.

Список агентов

GET /agents

Возвращает агентов, доступных для вашего аккаунта. Используйте значение agent при создании сессий или отправке сообщений.

Ответ 200 OK

{
  "agents": [
    {
      "agent": "jenova",
      "display_name": "Jenova",
      "description": "General-purpose Jenova agent"
    },
    {
      "agent": "my-support-agent",
      "display_name": "Support Agent",
      "description": "Answers customer questions"
    }
  ]
}

Модели

Список моделей

GET /models

Возвращает все модели, доступные для использования в поле model при отправке сообщений или вызове POST /invoke.

Ответ 200 OK

{
  "models": [
    {
      "id": "claude-opus-4-8",
      "name": "Claude Opus 4.8",
      "thinking_variant": "claude-opus-4-8-thinking"
    },
    {
      "id": "claude-opus-4-8-thinking",
      "name": "Claude Opus 4.8 (Thinking)"
    },
    {
      "id": "claude-sonnet-5",
      "name": "Claude Sonnet 5",
      "thinking_variant": "claude-sonnet-5-thinking"
    }
  ]
}

Модели с thinking_variant поддерживают расширенные рассуждения. Чтобы включить их, используйте идентификатор варианта непосредственно в поле model.

Если при отправке сообщения model не указана, используется model сессии. При создании сессии ей присваивается модель агента по умолчанию.

Вызов модели

POST /invoke

Отправляет промпт напрямую в модель, без агента, сессии и инструментов. По умолчанию ответы передаются потоково через SSE; установите stream: false для JSON.

Тело запроса

Пример

curl -X POST https://api.jenova.ai/v1/invoke \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "content": "Describe a forest in one sentence.",
    "stream": false
  }'

Ответ 200 OK

{
  "id": "inv_abc123",
  "model": "claude-sonnet-5",
  "content": "Sunlight filters through tall pines onto a quiet, mossy floor.",
  "usage": {
    "cost": "0.0004"
  }
}

Потоковые ответы отправляют stream_started, затем события stream_delta по мере генерации текста моделью и завершаются событием stream_ended, содержащим usage. Объедините значения chunk_content в порядке seq, чтобы получить потоковый ответ. Если запрос завершается ошибкой, перед stream_ended отправляется stream_error. События содержат id вместо session_id и run_id.

usage.cost равен null, если стоимость недоступна. Если запрос без потоковой передачи завершается ошибкой после начала вызова модели, ответ с ошибкой содержит поля id и usage верхнего уровня.

Продолжительность потоковых запросов ограничена 120 минутами. Запросы без потоковой передачи ожидают результат до 30 минут вместо возврата 202 Accepted и возвращают ошибку, если к этому времени результат не готов.

Ошибки

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

GET /docs?lang=en
GET /doc?lang=en

Возвращает этот справочник в формате Markdown. Используйте lang, чтобы выбрать язык.

Потоковая передача (SSE)

Если stream не указан или равен true (значение по умолчанию), ответы на сообщения доставляются в виде Server-Sent Events. Используйте события message_completed, чтобы определить, какие сообщения готовы к получению или отображению.

Тайм-аут: соединения SSE остаются открытыми до завершения запуска. Продолжительность запуска ограничена 120 минутами. Запросы сообщений без потоковой передачи ожидают до 90 секунд, после чего возвращают 202 Accepted, пока запуск продолжается. Для POST /invoke без потоковой передачи см. Вызов модели.

Заголовки подключения

Потоки сообщений устанавливают следующие заголовки:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Accel-Buffering: no
X-Run-Id: run_abc123

X-Run-Id доступен до первого события SSE. Потоки POST /invoke не устанавливают X-Run-Id; используйте id из stream_started.

Переподключение и восстановление

Потоки SSE не воспроизводятся повторно. Если соединение прерывается при персистентном запросе, используйте сохранённые session_id и run_id, чтобы восстановить состояние:

curl "https://api.jenova.ai/v1/sessions/ses_abc123/runs/run_abc123" \
  -H "Authorization: Bearer jnv_sk_xxx"

Если запуск ещё активен, этот запрос возвращает текущий статус, частичный текст и последние данные о ходе выполнения. Если возвращается status: "ended" или 404 not_found, запуск больше не активен; получите сообщения сессии, чтобы сверить завершённый результат:

curl "https://api.jenova.ai/v1/sessions/ses_abc123/messages?limit=20" \
  -H "Authorization: Bearer jnv_sk_xxx"

Формат кадра

Каждый SSE-кадр следует стандартному формату:

event: <event_type>
data: <json_payload>

Каждый кадр завершается двумя символами новой строки.

Типы событий

Потоки включают события жизненного цикла, текстовые дельты, рассуждения, прогресс, предупреждения, завершение сообщения, подключение MCP, ошибки, финальные события и ping. Некоторые типы событий отправляются только когда они релевантны.

Для эфемерных запросов (ephemeral: true) в каждом SSE-событии отсутствует session_id. Используйте только run_id для сопоставления событий внутри этого одного потока.

Для окончательной сверки при постоянных запросах дождитесь события stream_ended, а затем вызовите Список сообщений.

Общие поля событий, привязанных к запуску:

stream_started

Отправляется один раз при начале запуска.

stream_delta

Отправляется многократно по мере генерации агентом видимого текста ответа. Объедините значения chunk_content в порядке seq, чтобы получить потоковый ответ.

event: stream_delta
data: {"session_id":"ses_abc123","run_id":"run_abc123","chunk_content":"To reset your ","seq":1}

stream_thinking

Отправляется многократно, пока агент выдаёт результат размышлений. Используйте это для отдельного индикатора размышлений или представления трассировки; не объединяйте это с финальным текстом ответа.

stream_progress

Сообщает о видимой пользователю активности во время генерации, например о чтении документа, поиске в интернете или ожидании действия пользователя. Эти события предназначены для временного отображения в интерфейсе; игнорируйте неизвестные поля. Используйте завершенные сообщения как авторитетную историю сообщений.

Укажите include_progress: false в запросе сообщения, чтобы опустить только stream_progress. События жизненного цикла, ping, message_completed, ошибки и финальные события всё равно отправляются, когда это уместно.

Некоторые события прогресса могут включать url, file_name или server_name как необязательные подсказки для отображения.

message_completed

Отправляется каждый раз, когда сообщение завершено и готово для получения или отображения.

Это маркер границы, а не полный объект сообщения. Получите сообщение, если вам нужны содержимое или метаданные.

event: message_completed
data: {"session_id":"ses_abc123","run_id":"run_abc123","message_id":"msg_abc123","sequence":4,"from":{"type":"agent","name":"my-support-agent"},"type":"external"}

mcp_connection

Отправляется, когда агенту нужно, чтобы конечный пользователь подключил или авторизовал один или несколько MCP-серверов, прежде чем агент сможет продолжить. Это событие доступно только в режиме streaming.

mcp_connection_resolved

Отправляется, когда действие пользователя для подключения MCP было выполнено или истекло.

Дополнительных полей, помимо общих полей, привязанных к запуску, нет.

warning

Отправляется для некритичных предупреждений во время запуска.

stream_error

Отправляется при сбое запуска. За этим может следовать финальное событие stream_ended со значениями success: false и stop_reason: "error".

stream_ended

Отправляется один раз при завершении запуска. Это последнее событие в потоке.

event: stream_ended
data: {"session_id":"ses_abc123","run_id":"run_abc123","success":true,"stop_reason":"end_run","usage":{"cost":"0.0032"}}

Пример отменённого запуска:

event: stream_ended
data: {"session_id":"ses_abc123","run_id":"run_abc123","success":false,"stop_reason":"user_cancelled","usage":{"cost":"0.0012"}}

ping

Кадры поддержания активности, отправляемые каждые 15 секунд для предотвращения тайм-аутов на прокси/CDN. Игнорируйте их на стороне клиента.

Интеграция MCP-сервера

Подключайте ваших агентов к внешним инструментам через Model Context Protocol (MCP):

• MCP-серверы, управляемые Jenova: серверы, размещённые Jenova, для поиска, получения контента, генерации документов и других встроенных возможностей
• Удалённые MCP-серверы: другие удалённые MCP-серверы, настроенные для вашего агента

MCP-серверы должны быть настроены в панели управления при создании или редактировании агента. Чтобы использовать собственный MCP-сервер, добавьте его в кастомного агента, а затем вызывайте этого агента через API. API выполняет инструменты, включённые в конфигурации агента; дополнительная настройка в запросах API не требуется.

Когда агент использует инструменты MCP во время формирования ответа, в поток отправляются события о ходе выполнения по мере их возникновения:

event: stream_progress
data: {"session_id":"ses_...","run_id":"run_...","state":"running","label":"Searching Google"}

Если агенту во время запуска нужно, чтобы конечный пользователь подключился к MCP-серверу или авторизовал его, streaming-ответы могут включать события mcp_connection и mcp_connection_resolved. Покажите конечному пользователю список серверов для подключения и откройте предоставленный auth_url, если он есть. Держите SSE-поток открытым, пока конечный пользователь подключает или авторизует сервер.

После авторизации Jenova сохраняет token, окно авторизации показывает страницу завершения, и тот же запуск автоматически продолжается. Конечному пользователю не нужно повторно отправлять сообщение.

Если конечный пользователь не подключится, не авторизует, не пропустит или не отключит напоминания до user_action_deadline_unix, запуск завершится с stop_reason: "user_action_timeout". Вы также можете отменить активный запуск с помощью POST /sessions/{session_id}/cancel.

Сохраните auth_url на стороне клиента. Если клиент отключится во время авторизации, URL останется действительным до user_action_deadline_unix. Для постоянных запросов проверьте запуск через Получить статус запуска или получите сообщения после завершения запуска.

Нестриминговые запросы (stream: false) не поддерживают пользовательские действия подключения MCP; используйте streaming для агентов, которым может понадобиться это взаимодействие.

Пропустить подключение MCP

POST /sessions/{session_id}/mcp/connection/skip

Отклоняет ожидающее действие пользователя для подключения MCP и позволяет запуску продолжиться без этого подключения.

Чтобы отключить будущие запросы подключения для одного сервера для того же конечного пользователя и агента, укажите mcp_server_id и mute. mute принимает длительность, например 30m, 24h или 7d, либо forever.

Тело запроса

Ответ 204 No Content

Поток отправляет mcp_connection_resolved, после чего запуск продолжается с тем же run_id.

Ошибки

Биллинг

Все расходы списываются с баланса кредитов разработчика. Просматривайте использование и пополняйте кредиты на www.jenova.ai/platform.

Тарифы

Стоимость сообщения зависит от:

• Модель — разные модели имеют разную стоимость за токен
• Длина контекста — более длинные сессии потребляют больше входных токенов на запрос
• Сложность рабочего процесса — более длинные рабочие процессы и более интенсивное использование инструментов (веб-поиск, генерация файлов, анализ документов) увеличивают общее потребление токенов

Фактическая стоимость возвращается как stream_ended.usage.cost для потоковых запросов и usage.cost для непотоковых JSON-запросов.

Удержания кредитов

Каждый запрос POST /messages, POST /sessions/{session_id}/messages и POST /invoke устанавливает удержание $0.50 на балансе кредитов перед началом выполнения. Это резервирует средства для запроса. Сообщение, поставленное в очередь в рамках активного запуска (202 Accepted со значением status: "queued"), не создаёт дополнительного удержания; использование активного запуска проверяется относительно вашего оставшегося баланса.

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

Из-за удержаний доступный баланс может временно выглядеть ниже во время выполнения запросов. Вам нужно как минимум $0.50 доступного баланса для запроса POST /sessions/{session_id}/messages, эфемерного POST /messages или POST /invoke. Персистентный запрос POST /messages также создаёт сессию и требует как минимум $0.51 для покрытия удержания плюс платы за создание сессии.

Ограничения скорости

На каждую учётную запись разработчика распространяются три измерения ограничения скорости:

Запуск занимает слот параллельных запросов до своего завершения, в том числе после ответа 202 Accepted или отключения клиента. Запрос POST /invoke занимает слот до своего завершения, даже если клиент отключился.

Запросы GET и HEAD не занимают слоты параллельных запросов. cancel, undo и mcp/connection/skip также не занимают слоты параллельных запросов, поэтому эти операции остаются доступными, когда все слоты заняты. Эти запросы по-прежнему учитываются в RPM и RPD.

Отдельный лимит на IP-адрес в 1,200 запросов за 60 секунд также применяется ко всем запросам и возвращает ту же ошибку 429 rate_limit_exceeded.

Заголовки ответа

Аутентифицированные ответы API включают заголовки ограничения скорости:

При превышении дневного лимита X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset вместо этого описывают дневное окно.

При превышении лимита API возвращает 429 Too Many Requests:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please try again later."
  }
}

Обработка ошибок

Немедленные ошибки HTTP и ошибки запусков без потоковой передачи следуют единому формату:

{
  "error": {
    "code": "error_code_string",
    "message": "Human-readable description"
  }
}

Сообщения об ошибках локализуются в зависимости от lang или Accept-Language (см. Локализация).

Ошибки потоковых запусков передаются в виде событий stream_error. Неудачный запуск может также отправить финальное событие stream_ended со значением success: false и установленным stop_reason. Ошибки запусков без потоковой передачи включают объект usage верхнего уровня; cost равен null, если стоимость недоступна.

Эти ошибки могут возникать на любой конечной точке:

Ошибки, специфичные для конкретных конечных точек, документируются непосредственно в описании каждой конечной точки.

Ошибки запуска после старта

Ошибки запуска возникают после того, как запрос сообщения уже принят. В режиме потоковой передачи они отображаются как события stream_error и могут сопровождаться событием stream_ended со значением success: false. В режиме без потоковой передачи они возвращаются как JSON-ответ с ошибкой и указанным ниже статусом HTTP.

Пагинация

Конечные точки списка сессий и списка сообщений используют пагинацию на основе курсора:

{
  "items": [],
  "next_cursor": "2026-05-19T11:15:00Z|ses_abc123",
  "has_more": true
}

Передайте next_cursor в качестве параметра запроса cursor, чтобы получить следующую страницу, предварительно закодировав значение для URL. Если has_more равно false, дальнейших результатов нет. Значение limit вне диапазона 1-100 или недопустимый курсор возвращают 400 bad_request.

Локализация

Все конечные точки принимают необязательный параметр запроса lang для управления языком сообщений об ошибках и любого локализованного контента.

Вы можете добавить ?lang=xx к URL любого запроса:

POST /sessions?lang=zh
GET /sessions/ses_abc123/messages?lang=ja

Поддерживаемые языки: en, zh, ja, ko, es, fr, de, it, pt, ru, id, th, vi

Конфиденциальность и данные

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

Для сторонних провайдеров моделей Jenova использует коммерческие каналы API, настройки учётных записей, договорные обязательства или механизмы отказа, предназначенные для предотвращения использования контента клиентов при обучении моделей провайдеров.

Jenova хранит и обрабатывает данные API с использованием инфраструктуры США. Сторонние провайдеры могут обрабатывать данные в других юрисдикциях, как описано в Политике конфиденциальности и Условиях использования.

Полную информацию см. в Условиях использования, Политике конфиденциальности и Политике использования.

Поддержка

• Панель управления: www.jenova.ai/platform
• Email: [email protected]