#Web Search for AI

REST endpoints for web search on behalf of AI agents and applications. A single request returns a synthesized answer with links to sources; streaming mode delivers results as they become ready. For deep research with a multi-step agentic loop — a separate endpoint `POST /v1/research`.

Scope: vibe:search (added automatically when a key is created) | Base URL: https://vibecode.bitrix24.tech/v1 | Authorization: X-Api-Key

Quickstart | Endpoint reference | Pricing | Error codes | RAG recipe with LLM

#Documentation sections

• Search — synchronous request and streaming (SSE) via POST /v1/search
• Deep search — multi-step agentic research POST /v1/research
• Providers — list of search engines and their capabilities
• Bring your own keys (BYOK) — adding personal keys for free search

#Which key to choose

Web Search works with two types of keys. The choice is determined by whose behalf the request is sent on.

More on key formats and obtaining a session_token — Keys and authorization.

#Providers

The platform provides nine search engines: one platform-managed with billing in Vibes and eight BYOK providers paid directly with the vendor.

The current list with the capability matrix and prices — `GET /v1/search/providers`. All BYOK providers require your own key — added via Bring your own keys (BYOK).

#Supported provider capabilities

The full capability matrix is available in `GET /v1/search/providers` — capabilities for each provider. Key slices are below in three tables by group.

#Modes and streaming

Progressive streaming emits intermediate thinking / tool_call / answer_delta events. Buffered sends only start and done.

#Synthesized answer and formatting

For brave the answer field arrives only when search_depth: "advanced" via the optional summarizer; in basic — null.

#Filters

When the selected provider does not support a passed filter, the request completes without error — the filter is ignored. The response carries an X-Search-Filters-Ignored header with the list of skipped fields:

X-Search-Filters-Ignored: include_domains,time_range

For brave with include_answer: true and search_depth: "basic", an additional X-Answer-Not-Supported: brave-search-does-not-synthesize-answers header arrives, and the answer field in JSON is null. In advanced mode the same provider mixes in the summarizer and returns a populated answer.

#When to choose which provider

Quick guidelines:

• bitrix-search — a synthesized answer with [N] markers and source links in a single output. Suitable for AI agents that need RAG output out of the box without assembling the result separately. The only provider with progressive SSE streaming.
• tavily — domain filters (include_domains / exclude_domains), publication time window (time_range), numeric relevance score (score). A universal choice for English-language tasks.
• brave — web search without answer synthesis by default; the synthesizer is enabled on advanced. Suitable for English-language output and private queries.
• exa — neural/semantic search. Suitable for research tasks that need semantically related pages rather than an exact keyword match.
• you-com — the only provider with follow-up questions in research mode.
• linkup — real-time web crawl (liveData: true), suitable for queries about events from the last few hours.
• perplexity — Sonar models, OpenAI-compatible format, deep research with citations.
• jina — research mode only, an iterative "search → read → think" loop. Not available via `POST /v1/search`.
• z-ai — search without a synthesized answer, returns results with publication dates.

#Quickstart

A minimal call to `POST /v1/search`: the question text in the query field and the advanced mode for agentic search with source citations. The response returns a synthesized answer with [N] markers and a results array of found pages.

curl -X POST https://vibecode.bitrix24.tech/v1/search \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "what is new in Cursor IDE",
    "search_depth": "advanced",
    "max_results": 5
  }'

Response:

{
  "query": "what is new in Cursor IDE",
  "provider": "bitrix-search",
  "search_depth": "advanced",
  "answer": "Cursor 3 — a redesign of the IDE interface [1]. An agents window has appeared [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
}

The [1], [2] markers in the answer field correspond to results[].id values.

#Full scenario: RAG with LLM

Pairing /v1/search + /v1/ai/chat/completions for LLM answers grounded in fresh sources with [N] citation markers — a ready-made integration recipe:

→ Web search + LLM (RAG)

#Pricing

Cost is expressed in the platform's virtual currency — Vibes (Ꝟ). The charge occurs after a successful provider response; on a provider error the balance is unchanged.

Current values are returned by `GET /v1/search/providers`. The cost_vibes field in the response shows the amount actually charged.

Request history broken down by provider, Vibes spend by period, and average duration are available in the cabinet on the /search page. There you can also add, test, and delete BYOK keys through a visual interface. The "Use" button next to each provider opens a dialog with ready-made snippets in cURL, JavaScript, Python, the TypeScript SDK, and a text prompt for AI assistants.

#Rate limit

• 60 requests per minute per API key for `POST /v1/search`.
• 20 requests per minute per API key for `POST /v1/research` — deep research takes tens of times longer than a regular search.

When exceeded, 429 RATE_LIMITED is returned.

#Endpoint reference

#Key selection cascade

When provider is not passed in the `POST /v1/search` request, the platform selects it in the order: user key (USER BYOK) → portal key (PORTAL BYOK) → platform key (PLATFORM, bitrix-search).

For `POST /v1/research` the cascade works differently. If the provider field is omitted, the server immediately substitutes tavily — a USER/PORTAL default for a different provider (e.g. exa) is not considered here. If tavily has neither a USER, PORTAL, nor PLATFORM key, 404 CREDENTIAL_NOT_FOUND is returned with the message CREDENTIAL_NOT_FOUND: tavily. The USER → PORTAL → PLATFORM cascade is applied within the selected provider. To go through a different research provider, pass provider explicitly.

After adding your own BYOK key with isDefault: true, the platform uses it automatically — the provider parameter can be omitted.

#Migration from Tavily

The request schema mirrors the Tavily Search API. Differences:

• Address: https://api.tavily.com/search → https://vibecode.bitrix24.tech/v1/search.
• Authorization: the api_key field in the body → the X-Api-Key: YOUR_API_KEY header.
• Added an optional provider field — choice of engine from nine.

If you have your own Tavily key, add it via `POST /v1/search/credentials` and use provider: "tavily" or make the key the default. All other request fields work identically.

#Error codes

#Web search errors

#BYOK key errors

#System errors

The full list of common API errors — Errors.

#Error response structure

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient vibes for this search.",
    "userMessage": "Not enough vibes — top up the balance or add a BYOK Tavily/Brave credential.",
    "hint": "POST /v1/search/credentials with a tavily- or brave- key to switch to BYOK (free)."
  }
}

The userMessage and hint fields arrive on billing errors (INSUFFICIENT_BALANCE, BILLING_FROZEN). For other codes the response carries only code and message.

#See also

• Search (POST /v1/search) — request parameters, streaming format, response fields
• Deep search (POST /v1/research) — multi-step agentic research
• Providers — table of providers with the capability matrix
• Bring your own keys (BYOK) — adding and testing BYOK keys
• Web search + LLM (RAG) — recipe pairing /v1/search with /v1/ai/chat/completions
• Keys and authorization — personal key and authorization key, obtaining a session_token
• AI Router — a unified interface to chat models
• Limits and optimization — common request rate rules
• Errors — API error code reference