#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`. Для всех BYOK-провайдеров нужен ваш собственный ключ — добавляется через Свои ключи (BYOK).

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

Полная матрица возможностей доступна в `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 — синтезированный ответ с маркерами [N] и ссылками на источники в одной выдаче. Подходит для AI-агентов, которым нужен RAG-вывод «из коробки» без отдельной сборки результата. Единственный провайдер с прогрессивным потоком SSE.
• 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,
      "published_date": null
    },
    {
      "id": 2,
      "url": "https://cursor.com/changelog",
      "title": "Changelog",
      "content": "...",
      "score": null,
      "published_date": null
    }
  ],
  "search_id": "ws_20260430113025_a1b2c3d4",
  "upstream_search_id": "AG_xyz",
  "cost_vibes": 5,
  "duration_ms": 8523
}

Маркеры [1], [2] в поле answer соответствуют значениям results[].id.

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

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

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

#Тарификация

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

Актуальные значения возвращает `GET /v1/search/providers`. Поле cost_vibes в ответе показывает фактически списанную сумму.

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

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

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

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

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

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

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

Для `POST /v1/research` каскад работает иначе. Если поле provider опущено, сервер сразу подставляет tavily — USER/PORTAL-дефолт по другому провайдеру (например, exa) здесь не учитывается. Если у tavily нет ни USER, ни PORTAL, ни PLATFORM-ключа, возвращается 404 CREDENTIAL_NOT_FOUND с сообщением CREDENTIAL_NOT_FOUND: tavily. Каскад 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 — выбор движка из девяти.

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

#Коды ошибок

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

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

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

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

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

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient vibes for this search.",
    "userMessage": "Недостаточно vibes — пополните баланс или добавьте BYOK Tavily/Brave credential.",
    "hint": "POST /v1/search/credentials with a tavily- or brave- key to switch to BYOK (free)."
  }
}

Поля userMessage и hint приходят при биллинговых ошибках (INSUFFICIENT_BALANCE, BILLING_FROZEN). Для остальных кодов в ответе только code и message.

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

• Поиск (POST /v1/search) — параметры запроса, формат потоковой передачи, поля ответа
• Глубокий поиск (POST /v1/research) — многошаговое агентное исследование
• Провайдеры — таблица провайдеров с матрицей возможностей
• Свои ключи (BYOK) — добавление и проверка BYOK-ключей
• Веб-поиск + LLM (RAG) — рецепт связки /v1/search с /v1/ai/chat/completions
• Ключи и авторизация — личный ключ и ключ авторизации, получение session_token
• AI Router — единый интерфейс к чат-моделям
• Лимиты и оптимизация — общие правила частоты запросов
• Ошибки — справочник кодов ошибок API