Web Search для AI

REST-эндпоинты для веб-поиска от имени AI-агентов и приложений. Один запрос возвращает синтезированный ответ со ссылками на источники, потоковый режим — по мере готовности. Для глубокого исследования с многошаговым агентным циклом — отдельный эндпоинт POST /v1/research.

Скоуп: vibe:search (добавляется автоматически при создании ключа) | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

Быстрый старт | Справочник эндпоинтов | Тарификация | Коды ошибок | Рецепт RAG с LLM

Разделы документации

• Поиск — синхронный запрос и потоковая передача (SSE) через POST /v1/search
• Глубокий поиск — многошаговое агентное исследование POST /v1/research
• Провайдеры — список поисковых движков и их возможностей
• Свои ключи (BYOK) — добавление личных ключей для бесплатного поиска

Какой ключ выбрать

Web Search работает с двумя типами ключей. Выбор определяется тем, от чьего имени отправляется запрос.

Подробнее о форматах ключей и получении session_token — Ключи и авторизация.

Провайдеры

Платформа предоставляет платформенные движки с тарификацией в Вайбах и BYOK-провайдеры с оплатой напрямую у поставщика. Какие именно движки доступны на конкретном инстансе, какой из них платформенный и какова его цена — зависит от настроек инстанса. Актуальный список возвращает GET /v1/search/providers.

Актуальный список с матрицей возможностей и ценами — GET /v1/search/providers. Какой провайдер платформенный, его цена и движок по умолчанию различаются от инстанса к инстансу. Для всех BYOK-провайдеров нужен ваш собственный ключ — добавляется через Свои ключи (BYOK). BYOK-провайдеры всегда стоят 0 Ꝟ на стороне платформы.

Поддерживаемые возможности провайдеров

Полная матрица возможностей доступна в GET /v1/search/providers — capabilities у каждого провайдера. Ключевые срезы — ниже тремя таблицами по группам.

Режимы и потоковая передача

Прогрессивный поток отправляет промежуточные события thinking / tool_call / answer_delta. Буферизованный шлёт только start и done.

Синтезированный ответ и оформление

У brave поле answer приходит только при search_depth: "advanced" через опциональный суммаризатор. В basic — null.

Фильтры

Когда выбранный провайдер не поддерживает переданный фильтр, запрос завершается без ошибки — фильтр игнорируется. В ответе появляется заголовок X-Search-Filters-Ignored со списком пропущенных полей:

X-Search-Filters-Ignored: include_domains,time_range

Для brave при include_answer: true и search_depth: "basic" дополнительно приходит заголовок X-Answer-Not-Supported: brave-search-does-not-synthesize-answers, а поле answer в JSON — null. В режиме advanced тот же провайдер подмешивает суммаризатор и возвращает заполненный answer.

Когда какой провайдер выбрать

Короткие ориентиры:

• bitrix-search — платформенный веб-поиск, не требует своего ключа (тарифицируется в Вайбах). Возвращает синтезированный answer с источниками — готовый RAG-вывод для AI-агентов без отдельной сборки результата. Конкретные возможности (режим research, прогрессивный поток SSE, фильтры) зависят от инстанса — точная матрица в GET /v1/search/providers.
• tavily — фильтры по доменам (include_domains / exclude_domains), окно времени публикации (time_range), числовая оценка релевантности (score). Универсальный выбор для англоязычных задач.
• brave — веб-поиск без синтеза answer по умолчанию, синтезатор включается на advanced. Подходит для англоязычной выдачи и приватных запросов.
• exa — нейросетевой/семантический поиск. Подходит для исследовательских задач, где нужны связанные по смыслу страницы, а не точное совпадение ключевых слов.
• you-com — единственный провайдер с уточняющими вопросами в режиме research.
• linkup — обход веба в реальном времени (liveData: true), подходит для запросов про события последних часов.
• perplexity — модели Sonar, OpenAI-совместимый формат, глубокое исследование с цитатами.
• jina — только режим research, итеративный цикл «искать → читать → думать». Через POST /v1/search недоступен.
• z-ai — поиск без синтезированного ответа, отдаёт результаты с датами публикации.

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

Минимальный вызов POST /v1/search: текст вопроса в поле query и режим advanced для агентного поиска с цитированием источников. В ответ приходит синтезированный answer с маркерами [N] и массив results с найденными страницами.

curl -X POST https://vibecode.bitrix24.tech/v1/search \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "что нового в Cursor IDE",
    "search_depth": "advanced",
    "max_results": 5
  }'

Ответ:

{
  "query": "что нового в Cursor IDE",
  "provider": "bitrix-search",
  "search_depth": "advanced",
  "answer": "Cursor 3 — переработка интерфейса IDE [1]. Появилось окно агентов [2].",
  "results": [
    {
      "id": 1,
      "url": "https://cursor.com/blog/cursor-3",
      "title": "Meet the new Cursor",
      "content": "...",
      "score": null,
      "publishedDate": null
    },
    {
      "id": 2,
      "url": "https://cursor.com/changelog",
      "title": "Changelog",
      "content": "...",
      "score": null,
      "publishedDate": null
    }
  ],
  "search_id": "ws_20260430113025_a1b2c3d4",
  "upstream_search_id": "AG_xyz",
  "cost_vibes": 5,
  "duration_ms": 8523
}

Маркеры [1], [2] в поле answer соответствуют значениям results[].id. Значение provider в ответе (здесь bitrix-search) зависит от инстанса — без явного provider запрос идёт через движок по умолчанию, настроенный на инстансе. Текущий дефолт показывает поле defaultProvider в GET /v1/me.

Полный сценарий: RAG с LLM

Связка /v1/search + /v1/ai/chat/completions для ответов LLM, опирающихся на свежие источники с маркерами цитирования [N] — готовый рецепт интеграции:

→ Веб-поиск + LLM (RAG)

Тарификация

Стоимость указывается в виртуальной валюте платформы — Вайбы (Ꝟ). Списание происходит после успешного ответа провайдера, при ошибке провайдера баланс не меняется.

Тариф платформенного провайдера различается от инстанса к инстансу — какой движок платформенный и сколько Ꝟ стоят его режимы basic / advanced / research, возвращает GET /v1/search/providers в поле pricing. BYOK-провайдеры (tavily, brave, exa, you-com, linkup, perplexity, jina, z-ai) всегда стоят 0 Ꝟ на стороне платформы — вы оплачиваете запросы напрямую у поставщика по его тарифу.

Поле cost_vibes в ответе показывает фактически списанную сумму.

История запросов с разбивкой по провайдерам, расход Вайбов по периодам и средняя длительность доступны в кабинете на странице /search. Там же можно добавить, проверить и удалить BYOK-ключи через визуальный интерфейс. Кнопка «Использовать» рядом с каждым провайдером открывает диалог с готовыми сниппетами на cURL, JavaScript, Python, TypeScript SDK и текстовым промптом для AI-ассистентов.

Лимит частоты

• 60 запросов в минуту на портал для POST /v1/search.
• 20 запросов в минуту на портал для POST /v1/research — глубокое исследование длится в десятки раз дольше обычного поиска.

Лимит общий для всех API-ключей портала — они делят его между собой. Распределение нагрузки по нескольким ключам портала предел не поднимает.

При превышении возвращается 429 RATE_LIMITED.

Справочник эндпоинтов

Каскад выбора ключа

Когда в запросе POST /v1/search не передан provider, платформа подбирает его в порядке: ключ пользователя (USER BYOK) → ключ портала (PORTAL BYOK) → движок по умолчанию, настроенный на инстансе (его показывает поле defaultProvider в GET /v1/me).

Для POST /v1/research каскад работает иначе. Если поле provider опущено, сервер сразу подставляет research-движок по умолчанию, настроенный на инстансе, — USER/PORTAL-дефолт по другому провайдеру (например, exa) здесь не учитывается. Если для этого движка нет ни USER, ни PORTAL, ни PLATFORM-ключа, возвращается 404 CREDENTIAL_NOT_FOUND. Каскад USER → PORTAL → PLATFORM применяется уже внутри выбранного провайдера. Чтобы пойти через другой research-провайдер, передавайте provider явно.

После добавления своего BYOK-ключа с isDefault: true платформа использует его автоматически — параметр provider можно не указывать.

Миграция с Tavily

Схема запроса повторяет Tavily Search API. Различия:

• Адрес: https://api.tavily.com/search → https://vibecode.bitrix24.tech/v1/search.
• Авторизация: поле api_key в теле → заголовок X-Api-Key: YOUR_API_KEY.
• Добавлено опциональное поле provider — выбор движка из списка доступных.
• Добавлены опциональные поля topic (general или news) и include_images — запрос изображений. У Tavily есть эти возможности, у других движков — нет. Неподдерживаемые поля игнорируются и попадают в ignored_filters.

При наличии своего ключа Tavily добавьте его через POST /v1/search/credentials и используйте provider: "tavily" или сделайте ключ дефолтным. Остальные поля запроса работают идентично.

Коды ошибок

Ошибки веб-поиска

Ошибки BYOK-ключей

Системные ошибки

Полный список общих ошибок API — Ошибки.

Структура ответа об ошибке

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient vibes for this search.",
    "userMessage": "Недостаточно vibes — пополните баланс или добавьте свой BYOK-ключ (см. GET /v1/search/providers).",
    "hint": "Add a BYOK key to search for free — see GET /v1/search/providers",
    "required": 5
  }
}

Поля userMessage и required приходят при биллинговых ошибках INSUFFICIENT_BALANCE и BILLING_FROZEN. Поле required — сумма в Ꝟ, необходимая для запроса. Поле hint приходит при этих же биллинговых ошибках, а также при CREDENTIAL_NOT_FOUND — там оно подсказывает, как добавить свой BYOK-ключ для выбранного провайдера.

Смотрите также

• Поиск (POST /v1/search)
• Глубокий поиск (POST /v1/research)
• Провайдеры
• Свои ключи (BYOK)
• Веб-поиск + LLM (RAG)
• Ключи и авторизация
• AI Router
• Лимиты и оптимизация
• Ошибки