Для AI-агентов: markdown этой страницы — /docs-content/search/run.md индекс документации — /llms.txt

Поиск

POST /v1/search

Выполняет поиск в интернете и возвращает синтезированный ответ со ссылками на источники. Поддерживает синхронный режим и потоковую передачу через Server-Sent Events (stream: true). Глубокое исследование с многошаговым агентным циклом — отдельный эндпоинт POST /v1/research.

Поля запроса (body)

Поле Тип Обяз. По умолч. Описание
Полеquery Типstring Обяз.да По умолч.— ОписаниеТекст запроса. От 1 до 400 символов
Полеsearch_depth Типstring Обяз.нет По умолч.basic ОписаниеГлубина поиска: basic или advanced. Режим advanced дороже — переходите на него, только когда в ответе basic нет нужных данных, см. Как выбрать глубину. Цена режима — в GET /v1/search/providers
Полеprovider Типstring Обяз.нет По умолч.каскад USER → PORTAL → движок по умолчанию инстанса ОписаниеПринудительный выбор движка: один из bitrix-search, tavily, brave, exa, you-com, linkup, perplexity, z-ai. jina доступен только в POST /v1/research
Полеtopic Типstring Обяз.нет По умолч.general ОписаниеТематика поиска: general или news. Режим news поддерживают не все движки — у поддерживающих он наполняет publishedDate для новостных результатов, у остальных игнорируется
Полеmax_results Типnumber Обяз.нет По умолч.5 ОписаниеКоличество результатов в ответе. От 1 до 20
Полеmax_steps Типnumber Обяз.нет По умолч.3 ОписаниеМаксимум шагов агентного режима. От 1 до 5. Учитывает только bitrix-search
Полеlang Типstring Обяз.нет По умолч.ru ОписаниеЯзык поиска: ru, en или auto
Полеinclude_answer Типboolean Обяз.нет По умолч.true ОписаниеВключить синтезированный ответ в поле answer
Полеinclude_raw_content Типboolean Обяз.нет По умолч.false ОписаниеЗапросить полный текст найденных страниц. У поддерживающих движков текст приходит в results[].rawContent
Полеinclude_images Типboolean Обяз.нет По умолч.false ОписаниеЗапросить изображения по запросу. У поддерживающих движков ссылки приходят в верхнеуровневом массиве images
Полеinclude_domains Типstring[] Обяз.нет По умолч.[] ОписаниеПоиск только по доменам из списка. До 10 имён хоста
Полеexclude_domains Типstring[] Обяз.нет По умолч.[] ОписаниеИсключить домены. До 10 имён хоста
Полеtime_range Типstring | null Обяз.нет По умолч.null ОписаниеОкно времени публикации: day, week, month, year
Полеstream Типboolean Обяз.нет По умолч.false Описаниеtrue — потоковая передача через SSE вместо JSON-ответа

Часть фильтров поддерживается не всеми провайдерами — см. таблицу в Web Search для AI. Неподдерживаемый фильтр игнорируется, в ответе появляется заголовок X-Search-Filters-Ignored со списком пропущенных полей.

Как выбрать глубину

Без поля search_depth запрос выполняется в режиме basic. Режим advanced дороже. Цены обоих режимов на вашем инстансе — в GET /v1/search/providers.

Задача Глубина
ЗадачаНайти факт, цену, дату, ссылку, свежую новость Глубинаbasic
ЗадачаДать языковой модели контекст для ответа пользователю Глубинаbasic
ЗадачаЗапросы в цикле, по расписанию, при каждом обновлении дашборда или виджета Глубинаbasic
ЗадачаРазовый запрос, когда в ответе basic нет нужных данных Глубинаadvanced
ЗадачаСводка по одной теме из многих источников Глубинаadvanced
ЗадачаМногошаговое исследование с отчётом ГлубинаPOST /v1/research, а не advanced в цикле

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

Запрос с advanced отличается от примеров ниже только значением search_depth:

JSON
{
  "query": "что нового в Cursor IDE",
  "search_depth": "advanced",
  "max_results": 5,
  "lang": "ru"
}

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

Примеры

curl — личный ключ

Terminal
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": "basic",
    "max_results": 5,
    "lang": "ru"
  }'

curl — OAuth-приложение

Terminal
curl -X POST https://vibecode.bitrix24.tech/v1/search \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "что нового в Cursor IDE",
    "search_depth": "basic",
    "max_results": 5,
    "lang": "ru"
  }'

JavaScript — личный ключ

javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'что нового в Cursor IDE',
    search_depth: 'basic',
    max_results: 5,
    lang: 'ru',
  }),
})

const data = await res.json()
console.log(data.answer)
data.results.forEach((r) => console.log(`[${r.id}] ${r.title} — ${r.url}`))

JavaScript — OAuth-приложение

javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'что нового в Cursor IDE',
    search_depth: 'basic',
    max_results: 5,
    lang: 'ru',
  }),
})

const data = await res.json()

Поля ответа

Поле Тип Описание
Полеquery Типstring ОписаниеТекст исходного запроса
Полеprovider Типstring ОписаниеИдентификатор провайдера, который обработал запрос (например, bitrix-search, tavily)
Полеsearch_depth Типstring ОписаниеПрименённая глубина поиска: basic или advanced
Полеanswer Типstring | null ОписаниеСинтезированный ответ с маркерами [N]. Приходит null при include_answer: false, а также у движков, которые синтез не поддерживают: признак capabilities.output.synthesizedAnswer в GET /v1/search/providers
Полеresults Типarray ОписаниеМассив найденных источников
Полеresults[].id Типnumber ОписаниеПорядковый номер. Совпадает с маркером [N] в answer
Полеresults[].url Типstring ОписаниеАдрес страницы
Полеresults[].title Типstring ОписаниеЗаголовок страницы
Полеresults[].content Типstring ОписаниеВсегда краткое описание или сниппет страницы. Полный текст приходит отдельным полем rawContent, а не здесь
Полеresults[].rawContent Типstring | null ОписаниеПолный текст страницы при include_raw_content: true у поддерживающих движков. Размер ограничен примерно 40 КБ на результат. null, если полный текст не запрашивался или движок его не отдаёт
Полеresults[].score Типnumber | null ОписаниеОценка релевантности от провайдера. Для tavily — число от 0 до 1, чем выше — тем релевантнее. Приходит null, если движок оценку не отдаёт: признак capabilities.output.relevanceScore в GET /v1/search/providers
Полеresults[].publishedDate Типstring | null ОписаниеДата публикации в формате ISO 8601. Приходит null, если движок дату не отдаёт: отдаёт он её или нет, говорит признак capabilities.output.publishedDate в GET /v1/search/providers. У движков с поддержкой topic: "news" заполняется для новостных результатов
Полеimages Типarray ОписаниеВерхнеуровневый массив изображений при include_images: true у поддерживающих движков. Каждый элемент — объект с полем url. Пустой массив, если изображения не запрашивались или движок их не отдаёт
Полеignored_filters Типstring[] ОписаниеПереданные фильтры и параметры, которые движок не смог применить. Дублирует заголовок X-Search-Filters-Ignored в теле ответа. Может содержать topic, include_images, include_domains, time_range и другие — состав зависит от движка
Полеsearch_id Типstring ОписаниеИдентификатор запроса в формате ws_<14 цифр>_<8 hex>
Полеupstream_search_id Типstring | null ОписаниеИдентификатор у внешнего провайдера. Полезен для разбора инцидентов
Полеbilling_source Типstring ОписаниеНеобязательное. Источник оплаты: wallet — кошелёк, включая оплату сверх квоты ИИ, quota — квота ИИ портала, cowork — квота места Коворк/Код, byok — собственный ключ провайдера. Для бесплатного запроса через платформенный ключ поле отсутствует
Полеcost_vibes Типnumber ОписаниеСколько Ꝟ фактически списано с кошелька. При billing_source, равном quota, cowork или byok, значение равно 0
Полеduration_ms Типnumber ОписаниеДлительность обработки запроса в миллисекундах
Полеpartial_charge Типboolean ОписаниеПрисутствует, когда параллельные запросы исчерпали остаток баланса до конца текущего списания. Запрос завершился успешно, фактически списано меньше номинальной стоимости — итог в cost_vibes
Полеcharge_log_failed Типboolean ОписаниеНеобязательное. true, если произошёл сбой списания или записи журнала использования. Успешный результат поиска возвращается клиенту. Если списание состоялось до сбоя журнала, cost_vibes сохраняет фактически списанную с кошелька сумму

Пример ответа

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

Значение provider в примере (bitrix-search) зависит от инстанса: без явного provider запрос обрабатывает движок по умолчанию, настроенный на инстансе. Его показывает поле defaultProvider в GET /v1/me, а тариф — GET /v1/search/providers. Пример показывает списание с кошелька. При оплате квотой ИИ или места Коворк/Код поле cost_vibes равно 0. Порядок выбора источника оплаты — в разделе Тарификация.

При include_raw_content: true у поддерживающего движка поле rawContent заполняется полным текстом страницы, при include_images: true верхнеуровневый массив images — ссылками на изображения. Если движок не поддерживает topic или include_images, эти параметры попадают в ignored_filters.

Безопасность вывода. rawContent — это неочищенный текст из открытого интернета, а images[] — сторонние URL. Перед показом в браузере очищайте текст и проксируйте или проверяйте ссылки изображений — не вставляйте их в DOM как есть.

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

При stream: true ответ приходит как поток событий text/event-stream. Каждое событие — это пара event: <type> + data: <JSON>, разделённая пустой строкой.

Возможные события:

Событие Когда возникает Поля data
Событиеstart Когда возникаетВ начале запроса Поля datasearch_id, provider, search_depth
Событиеthinking Когда возникаетПромежуточные размышления агента Поля datacontent — текстовый фрагмент
Событиеtool_call Когда возникаетАгент вызвал внутренний инструмент Поля datatool (web_search / content_extraction / external_tool), description
Событиеtool_result Когда возникаетИнструмент вернул результат Поля datadescription, items_count
Событиеanswer_delta Когда возникаетОчередной фрагмент финального ответа Поля datacontent — кусок текста
Событиеdone Когда возникаетФинальный блок Поля dataТе же поля, что в синхронном ответе, включая billing_source и cost_vibes
Событиеerror Когда возникаетСбой во время обработки Поля dataerror.code, error.message

Пример потока:

event: start
data: {"search_id":"ws_20260430113025_a1b2c3d4","provider":"bitrix-search","search_depth":"basic"}

event: thinking
data: {"content":"Сейчас посмотрим в источниках"}

event: tool_call
data: {"tool":"web_search","description":"web search query"}

event: tool_result
data: {"description":"got 5 sources","items_count":5}

event: answer_delta
data: {"content":"Cursor 3 — "}

event: answer_delta
data: {"content":"переработка интерфейса IDE [1]."}

event: done
data: {"query":"что нового в Cursor IDE","provider":"bitrix-search","search_depth":"basic","answer":"Cursor 3 — переработка интерфейса IDE [1].","results":[{"id":1,"url":"https://cursor.com/blog/cursor-3","title":"Meet the new Cursor","content":"...","rawContent":null,"score":null,"publishedDate":null}],"images":[],"ignored_filters":[],"search_id":"ws_20260430113025_a1b2c3d4","upstream_search_id":"AG_xyz","billing_source":"wallet","cost_vibes":5,"duration_ms":8523}

Реальный поток событий с промежуточными thinking / tool_call / answer_delta отправляет только bitrix-search. Для остальных провайдеров поток буферизованный — приходит только start и done. Признак прогрессивного потока — поле capabilities.modes.streaming в GET /v1/search/providers.

Пример ответа при ошибке

402 — недостаточно средств:

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
  }
}

Поле required — сумма в Ꝟ, необходимая для запроса. Остальные ситуации перечислены в таблице ошибок ниже.

Ошибки

Квотные отказы возвращаются обычным HTTP-ответом с объектом error до открытия потока SSE. Проверьте HTTP-статус и error.code до чтения событий потока.

HTTP Код Описание
HTTP400 КодINVALID_REQUEST ОписаниеПустой query, query длиннее 400 символов, max_results вне диапазона 1..20, max_steps вне диапазона 1..5, provider не из списка поддерживаемых провайдеров, неизвестное значение search_depth, topic, lang или time_range, include_domains / exclude_domains длиннее 10 элементов
HTTP402 КодINSUFFICIENT_BALANCE ОписаниеНа балансе портала недостаточно Ꝟ для выбранного режима
HTTP402 КодBILLING_FROZEN ОписаниеБиллинг-аккаунт заморожен
HTTP402 КодAI_QUOTA_EXHAUSTED ОписаниеКвота ИИ исчерпана, оплата сверх квоты недоступна. Причина — в error.reason, время сброса — в error.resetAt. Дождитесь сброса, разрешите перерасход в кабинете и пополните кошелёк или используйте свой ключ провайдера. Необязательное поле error.learnMore содержит дополнительные сведения
HTTP429 КодAI_PACING_LIMITED ОписаниеДостигнут лимит равномерного расходования квоты ИИ. Ответ содержит error.reason, error.overageDenied, error.resetAt и заголовок Retry-After в секундах. Дождитесь указанного времени или используйте свой ключ провайдера
HTTP402 КодCOWORK_QUOTA_EXHAUSTED ОписаниеИсчерпано окно квоты места Коворк/Код. Поле error.window принимает fiveHour, week или month. Дождитесь error.resetAt или задержки из заголовка Retry-After в секундах, либо используйте свой ключ провайдера
HTTP402 КодCOWORK_SUBSCRIPTION_INACTIVE ОписаниеНет активного места Коворк/Код. Активируйте или возобновите место, либо используйте свой ключ провайдера
HTTP402 Кодcompany_budget_exhausted ОписаниеИсчерпан месячный бюджет расхода компании, который задаёт администратор портала. Поле scope называет пробитый бюджет: USER — личный бюджет вызывающего, PORTAL — бюджет всего портала. Поле canRequest говорит, можно ли запросить увеличение: у личного бюджета true, у портального false — его поднимает только администратор. Отказ приходит при оплате из кошелька, включая оплату сверх квоты ИИ. Поиск на своём BYOK-ключе бесплатен и продолжает работать
HTTP403 КодSCOPE_DENIED ОписаниеКлючу не хватает скоупа vibe:search
HTTP404 КодPROVIDER_NOT_FOUND ОписаниеПередан provider, которого нет в системе или он отключён
HTTP404 КодCREDENTIAL_NOT_FOUND ОписаниеДля провайдера нет ни USER, ни PORTAL, ни PLATFORM-ключа
HTTP404 КодPROVIDER_DOES_NOT_SUPPORT_SEARCH ОписаниеЗапрошен provider: "jina" — Jina работает только в POST /v1/research. Поле search_id присутствует в ответе
HTTP429 КодRATE_LIMITED ОписаниеПревышен лимит 60 запросов в минуту на портал — общий для всех его API-ключей. Действующее значение — в заголовке x-ratelimit-limit
HTTP429 КодSEARCH_DAILY_CAP_REACHED ОписаниеС этим запросом суммарный расход поиска из кошелька, квоты ИИ и квоты места Коворк/Код за текущие сутки по московскому времени превысил бы потолок, который задал администратор портала. Провайдер не вызывается, списания нет. Потолок общий для /v1/search и POST /v1/research. Ответ несёт заголовок Retry-After, а тело ошибки — поля resetAt с началом следующих суток по московскому времени и hint. Поиск на своём BYOK-ключе потолок не ограничивает
HTTP500 КодINTERNAL_ERROR ОписаниеВнутренняя ошибка сервера. В ответе присутствует search_id
HTTP401/403/429/502 КодUPSTREAM_ERROR ОписаниеПровайдер вернул ошибку, списания нет. Поле upstream_status в ответе несёт исходный статус провайдера. Для BYOK-ключа ответы провайдера 401 и 403 приходят с тем же статусом — провайдер отверг ваш ключ, повтор без его замены не поможет. Ответ провайдера 429 сохраняет статус для любого ключа и несёт заголовок Retry-After — повторите позже. Остальные ошибки провайдера, включая отказ ключа платформенного движка, приходят как 502 — повторите запрос
HTTP503 КодFEATURE_NOT_ENABLED ОписаниеWeb Search недоступен на этой платформе
HTTP503 КодUPSTREAM_TIMEOUT ОписаниеПровайдер превысил время ожидания запроса. Списания нет. Ответ содержит заголовок Retry-After: 30 — повторите запрос через указанное в нём время

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

Известные особенности

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

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

lang: "auto" для bitrix-search приводится к ru. Значения ru и en передаются движку как есть — для англоязычной выдачи передайте lang: "en". Поле не отбрасывается и в X-Search-Filters-Ignored не попадает.

Пустая выдача оплачивается. Когда провайдер не нашёл ни одного источника и вернул results: [], успешный запрос расходует квоту или кошелёк по выбранному источнику оплаты. Оплачивается обработка запроса провайдером, а не количество результатов.

Сбой учёта не отменяет результат поиска. При charge_log_failed: true не отправляйте запрос заново только ради записи журнала: повторный поиск — отдельный запрос с отдельной оплатой.

provider: "jina" доступен только в /v1/research. Запрос с provider: "jina" в текущем эндпоинте возвращает 404 PROVIDER_DOES_NOT_SUPPORT_SEARCH. Список провайдеров, поддерживающих /v1/search, проверяется по полю capabilities.modes.search.basic или capabilities.modes.search.advanced в GET /v1/search/providers.

Администратор портала может выключить режим advanced. Тогда платный поиск через платформенный движок с search_depth: "advanced" выполняется как basic, и запрос не отклоняется. В ответе и в событиях SSE start и done приходит search_depth: "basic", в заголовках ответа — синхронного и потокового — X-Search-Depth-Downgraded: advanced. Списание идёт по цене basic, по ней же запрос учитывается в суточном потолке расхода. Поиск на своём BYOK-ключе настройка не затрагивает.

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