Для 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:
{
"query": "что нового в Cursor IDE",
"search_depth": "advanced",
"max_results": 5,
"lang": "ru"
}
Приложения, которые обновляются сами, — дашборды, виджеты, запуски по расписанию — оплачивают каждый запрос. Расход за период — частота обновления × число виджетов × цена режима. Кэшируйте результат на своей стороне и не повторяйте одинаковый запрос чаще, чем меняются данные.
Примеры
curl — личный ключ
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-приложение
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 — личный ключ
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-приложение
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 сохраняет фактически списанную с кошелька сумму |
Пример ответа
{
"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 — недостаточно средств:
{
"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-ключе настройка не затрагивает.