# Web Search для AI

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

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

[Быстрый старт](#быстрый-старт) | [Справочник эндпоинтов](#справочник-эндпоинтов) | [Тарификация](#тарификация) | [Коды ошибок](#коды-ошибок) | [Рецепт RAG с LLM](/docs/recipes/web-search-with-llm)

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

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

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

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

| Сценарий | Ключ | Заголовки запроса |
|---------|------|-------------------|
| Свой портал, личный скрипт или сервер | Личный API-ключ `vibe_api_…` | `X-Api-Key: vibe_api_…` |
| Запрос от имени конечного пользователя в OAuth-приложении | Ключ авторизации `vibe_app_…` | `X-Api-Key: vibe_app_…` + `Authorization: Bearer <session_token>` |

Подробнее о форматах ключей и получении `session_token` — [Ключи и авторизация](/docs/keys-auth).

## Провайдеры

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

| Провайдер | Назначение | Тарификация |
|-----------|-----------|-----------|
| `bitrix-search` | Платформенный веб-поиск. Конкретный движок и его возможности зависят от инстанса — см. [`GET /v1/search/providers`](/docs/search/providers) | платформенный, тариф в Вайбах — см. [`GET /v1/search/providers`](/docs/search/providers) |
| `tavily` | Tavily — англоязычный поиск с фильтрами по доменам и времени, оценкой релевантности | 0 Ꝟ (BYOK) |
| `brave` | Brave Search — приватный веб-поиск, опциональный суммаризатор в `advanced` | 0 Ꝟ (BYOK) |
| `exa` | Exa — нейросетевой/семантический поиск с извлечением полного контента | 0 Ꝟ (BYOK) |
| `you-com` | You.com — поиск с цитатами и уточняющими вопросами | 0 Ꝟ (BYOK) |
| `linkup` | Linkup — обход веба в реальном времени с режимом deep research | 0 Ꝟ (BYOK) |
| `perplexity` | Perplexity Sonar — модели Sonar для поиска и глубокого исследования | 0 Ꝟ (BYOK) |
| `jina` | Jina DeepSearch — итеративный цикл «искать → читать → думать», только research | 0 Ꝟ (BYOK) |
| `z-ai` | Z.AI Web Search — поиск без синтезированного ответа с датами публикации | 0 Ꝟ (BYOK) |

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

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

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

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

| Провайдер | `basic` | `advanced` | `research` | Поток |
|-----------|:-------:|:----------:|:----------:|:------|
| `bitrix-search` | ✓ | ✓ | зависит от инстанса | зависит от инстанса |
| `tavily` | ✓ | ✓ | ✓ | буферизованный |
| `brave` | ✓ | ✓ | ✗ | буферизованный |
| `exa` | ✓ | ✓ | ✓ | буферизованный |
| `you-com` | ✓ | ✓ | ✓ | буферизованный |
| `linkup` | ✓ | ✓ | ✓ | буферизованный |
| `perplexity` | ✓ | ✓ | ✓ | буферизованный |
| `jina` | ✗ | ✗ | ✓ | буферизованный |
| `z-ai` | ✓ | ✓ | ✗ | буферизованный |

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

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

| Провайдер | `answer` | Цитаты `[N]` | `score` | `publishedDate` | Уточняющие вопросы |
|-----------|:--------:|:------------:|:-------:|:----------------:|:-------------------:|
| `bitrix-search` | ✓ | зависит от инстанса | зависит от инстанса | зависит от инстанса | ✗ |
| `tavily` | ✓ | ✗ | ✓ | ✓ | ✗ |
| `brave` | в `advanced` | ✗ | ✗ | ✓ | ✗ |
| `exa` | ✓ | ✓ | ✓ | ✓ | ✗ |
| `you-com` | ✓ | ✓ | ✗ | ✓ | ✓ |
| `linkup` | ✓ | ✓ | ✗ | ✓ | ✗ |
| `perplexity` | ✓ | ✓ | ✗ | ✗ | ✗ |
| `jina` | ✓ | ✓ | ✗ | ✓ | ✗ |
| `z-ai` | ✗ | ✗ | ✗ | ✓ | ✗ |

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

### Фильтры

| Провайдер | `include_domains` | `exclude_domains` | `time_range` |
|-----------|:-----------------:|:-----------------:|:------------:|
| `bitrix-search` | зависит от инстанса | зависит от инстанса | зависит от инстанса |
| `tavily` | ✓ | ✓ | ✓ |
| `brave` | ✗ | ✗ | ✓ |
| `exa` | ✓ | ✓ | ✗ |
| `you-com` | ✗ | ✗ | ✗ |
| `linkup` | ✗ | ✗ | ✗ |
| `perplexity` | ✗ | ✗ | ✗ |
| `jina` | ✓ | ✓ | ✗ |
| `z-ai` | ✓ | ✗ | ✓ |

Когда выбранный провайдер не поддерживает переданный фильтр, запрос завершается без ошибки — фильтр игнорируется. В ответе появляется заголовок `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`](/docs/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`](/docs/search/run) недоступен.
- **`z-ai`** — поиск без синтезированного ответа, отдаёт результаты с датами публикации.

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

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

```bash
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
  }'
```

Ответ:

```json
{
  "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`](/docs/keys-auth).

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

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

→ [Веб-поиск + LLM (RAG)](/docs/recipes/web-search-with-llm)

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

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

Тариф платформенного провайдера различается от инстанса к инстансу — какой движок платформенный и сколько Ꝟ стоят его режимы `basic` / `advanced` / `research`, возвращает [`GET /v1/search/providers`](/docs/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`](/docs/search/run).
- 20 запросов в минуту на портал для [`POST /v1/research`](/docs/search/research) — глубокое исследование длится в десятки раз дольше обычного поиска.

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

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

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

| Метод | Путь | Описание |
|-------|------|----------|
| POST | [`/v1/search`](/docs/search/run) | Синхронный запрос или потоковая передача |
| POST | [`/v1/research`](/docs/search/research) | Глубокое исследование с многошаговым агентным циклом, только SSE |
| GET | [`/v1/search/providers`](/docs/search/providers) | Список провайдеров с матрицей возможностей и тарифами |
| GET | [`/v1/search/credentials`](/docs/search/credentials/list) | Список своих BYOK-ключей |
| POST | [`/v1/search/credentials`](/docs/search/credentials/create) | Добавить BYOK-ключ выбранного провайдера |
| DELETE | [`/v1/search/credentials/:id`](/docs/search/credentials/delete) | Удалить BYOK-ключ |
| POST | [`/v1/search/credentials/:id/test`](/docs/search/credentials/test) | Проверить BYOK-ключ |

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

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

Для [`POST /v1/research`](/docs/search/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`](/docs/search/credentials/create) и используйте `provider: "tavily"` или сделайте ключ дефолтным. Остальные поля запроса работают идентично.

## Коды ошибок

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

| Код | HTTP | Описание |
|-----|------|---------|
| `INVALID_REQUEST` | 400 | Не пройдена валидация — пустой `query`, `query` длиннее лимита, неизвестное значение `provider`, `search_depth`, `topic`, `lang` или `time_range`, превышены лимиты `include_domains` / `exclude_domains` |
| `INSUFFICIENT_BALANCE` | 402 | На балансе портала недостаточно Ꝟ для выбранного режима. Переключитесь на BYOK или пополните баланс |
| `BILLING_FROZEN` | 402 | Биллинг-аккаунт заморожен — пополните баланс и снимите блокировку в кабинете |
| `PROVIDER_NOT_FOUND` | 404 | Передан `provider`, которого нет в системе или он недоступен |
| `CREDENTIAL_NOT_FOUND` | 404 | Для запрошенного провайдера у пользователя или портала нет BYOK-ключа, а платформенного ключа нет |
| `PROVIDER_DOES_NOT_SUPPORT_SEARCH` | 404 | Запрошен `provider: "jina"` в [`POST /v1/search`](/docs/search/run) — Jina работает только в [`POST /v1/research`](/docs/search/research) |
| `PROVIDER_DOES_NOT_SUPPORT_RESEARCH` | 404 | Запрошен `brave` или `z-ai` — либо `bitrix-search`, когда у движка инстанса нет режима research — в [`POST /v1/research`](/docs/search/research). Эти провайдеры работают только в [`POST /v1/search`](/docs/search/run). На инстансе, где `bitrix-search` привязан к движку с research, `/v1/research` его принимает |
| `RATE_LIMITED` | 429 | Превышен лимит запросов в минуту на портал |
| `UPSTREAM_ERROR` | 401/403/429/502 | Провайдер вернул ошибку, списания нет; поле `upstream_status` в ответе несёт исходный статус провайдера. Для BYOK-ключа ответы провайдера `401` и `403` приходят с тем же статусом — провайдер отверг ваш ключ, повтор без его замены не поможет. Ответ провайдера `429` сохраняет статус для любого ключа и несёт заголовок `Retry-After` — повторите позже. Остальные ошибки провайдера, включая отказ ключа платформенного движка, приходят как `502` — повторите запрос |
| `FEATURE_NOT_ENABLED` | 503 | Web Search или глубокое исследование недоступно на этой платформе |
| `UPSTREAM_TIMEOUT` | 503 | Провайдер превысил время ожидания запроса. Ответ содержит заголовок `Retry-After: 30` — повторите запрос через указанное в нём время |

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

| Код | HTTP | Описание |
|-----|------|---------|
| `INVALID_CREDENTIAL` | 400 | При создании BYOK-ключа провайдер отклонил его на этапе предварительной проверки. Запись не сохранена |
| `INVALID_REQUEST` | 400 | Не указан `apiKey`, неверный `provider`, имя длиннее 64 символов |

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

| Код | HTTP | Описание |
|-----|------|---------|
| `MISSING_API_KEY` | 401 | Отсутствует заголовок `X-Api-Key` |
| `INVALID_API_KEY` | 401 | Неверный API-ключ |
| `KEY_INACTIVE` | 401 | API-ключ деактивирован, заблокирован или истёк |
| `SCOPE_DENIED` | 403 | Ключу не хватает скоупа `vibe:search` |
| `INTERNAL_ERROR` | 500 | Внутренняя ошибка сервера |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

```json
{
  "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)](/docs/search/run)
- [Глубокий поиск (POST /v1/research)](/docs/search/research)
- [Провайдеры](/docs/search/providers)
- [Свои ключи (BYOK)](/docs/search/credentials)
- [Веб-поиск + LLM (RAG)](/docs/recipes/web-search-with-llm)
- [Ключи и авторизация](/docs/keys-auth)
- [AI Router](/docs/ai)
- [Лимиты и оптимизация](/docs/optimization)
- [Ошибки](/docs/errors)