Skip to content

New: DeepSeek V4.1 Flash Derisked. In chat and on the API.

See modelsWhat's newReport a bug
Open chat
API reference

API reference

Web search and web fetch tools

Add the provider's own web tool to a request and the model can search the web and read pages while it answers. Vani runs each search and page read, gives the model the results, and returns the answer with the tool calls, results and citations in the provider's own format: Anthropic's web_search and web_fetch server tools on /messages, the web_search tool on /responses, and web_search_options on /chat/completions. Or add :online to the model id (zhipu/glm-5.3-derisked:online): the same model, with web search and page reading on every request, for apps that never send a web tool. Apps that turn web search on with plugins: [{"id": "web"}] work too. Clients that run web tools of their own can use the same search and page reader through POST /tools/search, /tools/research and /tools/fetch, or the Vani MCP server's web_search and web_fetch tools.

Price
USD 0.005 per search (USD 5 per 1,000), plus tokens
Page reads
Tokens only
Per request
Up to 8 uses of each tool (16 with :online)
Any app
Add :online to the model id
Plugin field
plugins: [{"id": "web"}]
Endpoints
POST /messages · /responses · /chat/completions
For your own tools
POST /tools/search · /tools/research · /tools/fetch
On this pageHow it works

How it works

The model decides when to search or read a page. Each call runs on Vani while the request is open, the result goes back to the model, and the model goes on with its answer. Vani offers these tools with every chat model in GET /models, the Derisked models included (GLM 5.3 Derisked and Kimi K3.1 Pro Soft-Derisked); a GLM 5.3 Derisked request without web tools is still sent exactly as written. They run when your client puts the provider's web tool in the request, or on every request to a model id with :online (see :online model ids); many coding clients run web tools of their own instead (see Clients).

  • Results are input tokens of the model's next step, like any tool result. usage is the sum of every step of the request.
  • Search results and pages are untrusted web content: the model is told to use them as reference only and never to follow instructions found in them.
  • Web tools and your own function tools work in the same request. A step that calls both runs the web tools first; your tool calls come back to you as usual.

:online model ids: web search in any app

Add :online to a model id, such as zhipu/glm-5.3-derisked:online or anthropic/claude-sonnet-5.5:online, and every request gets Vani's web search and page reading, on /messages, /responses and /chat/completions. Your app sends nothing else, so this works with coding agents, SDK apps and other clients that never send a provider's web tool. The model decides when to search or read a page, and the answer comes in the endpoint's own shapes (see the sections below).

  • The same model serves the request, at its own token price, plus USD 0.005 per search that runs; page reads cost tokens only. The answer's model, your usage and your request log name the plain model (zhipu/glm-5.3-derisked), and the x-vani-model-routed-from response header names the id you sent. Vendor ids take it too (claude-sonnet-5-5:online).
  • Every chat model in GET /models has an :online id except Qwen 3.8 Flash, Grok 4.7 and Grok 4.5, which do not use web tools reliably yet: their :online ids are refused with 400. The :online ids are not listed in GET /models; send them as they are. GLM 5.3 Derisked and DeepSeek V4.1 Flash Derisked have them too, and without :online their requests are still sent exactly as written.
  • On /messages the model gets the web_search and web_fetch server tools. On /responses and /chat/completions it gets web search and page reading: on /responses each call is a web_search_call item (action.type is search, or open_page with the page's url), and on /chat/completions the answer's links to results come as url_citation annotations. Page reading reads only URLs you sent and URLs that results brought, never an address the model wrote.
  • No limit of its own: up to 16 uses of each tool per request, within the request's own limits (16 tool calls, 8 model steps, 60 seconds of web tool time), and pages are read up to 100,000 characters. A request starts by reserving 16 searches (USD 0.08) on top of its tokens; what it does not use is released when it ends.
  • Your own tools keep working: their calls come back to you as usual. If one of them is named web_search or web_fetch, it keeps its name and the model gets Vani's tool under another name. A tool_choice you set for your own tools holds on every step; naming web_search or web_fetch when no tool of yours has that name makes the first step call it.
  • A request that already has a provider's web tool (web_search_20250305, {"type": "web_search"}, web_search_options) keeps exactly what it asked for, with or without :online.
Shell

Chat Completions with an :online id

curl "https://api.vani.ai/v1/chat/completions" \
  -H "Authorization: Bearer $VANI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"zhipu/glm-5.3-derisked:online","messages":[{"role":"user","content":"What changed in the latest Rust release?"}]}'

The plugins web field

Many chat apps and agent frameworks turn web search on with plugins: [{"id": "web"}] on /chat/completions and /responses. Vani takes it as its own web search: the model searches when the question needs it, and the answer cites its results (url_citation annotations, and web_search_call items on /responses).

  • max_results: results per search, 5 by default and 10 at most. include_domains and exclude_domains: the sites to keep to or leave out (*.example.com and example.com/docs work as in the provider web tools). search_prompt: your own words on using the results, added to the model's instructions. engine and mode are accepted and change nothing: Vani always uses its own search.
  • It searches only (no page reading), as often as the request's own limits allow (16 tool calls and 8 model steps). Each search costs USD 0.005, as everywhere on the API; a request reserves 16 searches (USD 0.08) up front and is charged only for the searches that ran.
  • Another plugin (such as file-parser) is refused with 400 naming it. On /responses send either a web_search tool or the plugin, not both. With web_search_options on /chat/completions, their search_context_size and user_location apply too.
  • The same models take it as the provider web tools, GLM 5.3 Derisked included. An :online id needs no plugin.
  • usage.server_tool_use counts web_search_requests (the charged searches) and web_fetch_requests on /chat/completions and /responses, as on /messages.
Shell

Chat Completions with the web plugin

curl "https://api.vani.ai/v1/chat/completions" \
  -H "Authorization: Bearer $VANI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"zhipu/glm-5.3","messages":[{"role":"user","content":"What changed in the latest Rust release?"}],"plugins":[{"id":"web","max_results":3}]}'

Messages: web_search and web_fetch

Add {"type": "web_search_20250305", "name": "web_search"} and, to read pages, {"type": "web_fetch_20250910", "name": "web_fetch"} to tools. The later dated versions work the same way: web_search_20260209 and web_search_20260318, web_fetch_20260209, web_fetch_20260309 and web_fetch_20260318 (as the Vercel AI SDK sends them). The anthropic-beta headers web-fetch-2025-09-10 and code-execution-web-tools-2026-02-09 are accepted but not needed.

  • web_search takes max_uses, allowed_domains or blocked_domains (not both; example.com covers its subdomains, example.com/docs the pages under that path) and user_location ({"type": "approximate", "city", "region", "country", "timezone"}, given to the model, which adds a place to a query when it matters).
  • web_fetch takes max_uses, allowed_domains / blocked_domains, citations: {"enabled": true} and max_content_tokens. It reads only URLs that you send (in your messages, tool results or system prompt) and URLs that earlier search and page results brought, never an address the model wrote in an earlier answer, so a model cannot be led to send data to an address of its own choosing. Pages are read from public HTTPS addresses whose robots.txt allows Vani's research fetcher; HTML, plain text and PDF come back as text.
  • The later versions' options: Vani runs no code execution, so there is no dynamic filtering. allowed_callers and response_inclusion are accepted and change nothing: every call is the model's own, and every result comes back in full. The server_tool_use blocks of the 2026 versions say "caller": {"type": "direct"}. use_cache: false (web_fetch 20260309 and later) reads the page live from its site, never from a stored copy. url_sources (web_fetch, every version) narrows where a URL may come from: user_input (your messages and system prompt; all or none), client_tool_results and server_tool_results (all, none, or only / except with {"type": "tool_reference", "name"} entries naming tools of the request).
  • tool_choice: {"type": "tool", "name": "web_search"} (or web_fetch) makes the first step call that tool.
  • The answer holds a server_tool_use block (srvtoolu_… id, input with the query or URL), its web_search_tool_result (each result with type: web_search_result, url, title, page_age and an opaque encrypted_content) or web_fetch_tool_result (a document with the page text and retrieved_at), then the text. A text block that links to a search result carries a web_search_result_location citation with a short cited_text.
  • A failed or refused call is a result block, never an HTTP error, and is not charged: web_search_tool_result_error with max_uses_exceeded, too_many_requests, invalid_input, query_too_long or unavailable; web_fetch_tool_result_error with url_not_allowed, url_not_accessible, unsupported_content_type, url_too_long, invalid_input, max_uses_exceeded, too_many_requests or unavailable.
  • usage.server_tool_use counts web_search_requests (the charged searches) and web_fetch_requests. A stream sends the blocks in order: the server_tool_use input as an input_json_delta, citations as citations_delta, and the counts in message_delta.
  • Send an answer back in the history as it came. Its server tool blocks are read as text (what was searched or read, the results' titles and URLs, the page text); encrypted_content and encrypted_index are opaque and carry nothing, and page_age is null where a page's date is not known.
Shell

A Messages request with web search

curl "https://api.vani.ai/v1/messages" \
  -H "x-api-key: $VANI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5.5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "What changed in the latest Rust release?"}],
    "tools": [{"type": "web_search_20250305", "name": "web_search", "max_uses": 3}]
  }'
JSON

The answer (shortened)

{
  "content": [
    {"type": "server_tool_use", "id": "srvtoolu_01…", "name": "web_search", "input": {"query": "Rust latest release notes"}},
    {"type": "web_search_tool_result", "tool_use_id": "srvtoolu_01…", "content": [
      {"type": "web_search_result", "url": "https://blog.rust-lang.org/…", "title": "Announcing Rust …", "encrypted_content": "vws1.…", "page_age": null}
    ]},
    {"type": "text", "text": "The latest release … ([Rust blog](https://blog.rust-lang.org/…)).",
     "citations": [{"type": "web_search_result_location", "url": "https://blog.rust-lang.org/…", "title": "Announcing Rust …", "cited_text": "…", "encrypted_index": "vwi1.…"}]}
  ],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 2810, "output_tokens": 164, "server_tool_use": {"web_search_requests": 1, "web_fetch_requests": 0}}
}

Responses: the web_search tool

Add {"type": "web_search"} (or web_search_preview, and their dated names) to tools.

  • Options: search_context_size (low, medium by default, or high: how many results the model reads and how much of each), user_location ({"type": "approximate", city, region, country, timezone}) and filters.allowed_domains. tool_choice: {"type": "web_search"} makes the first step search.
  • Each search is a web_search_call output item with status and action: {"type": "search", "query"}; with include: ["web_search_call.action.sources"] the action also lists the result URLs in sources. The message's output_text carries url_citation annotations (start_index, end_index, url, title) for its links to results.
  • A stream sends response.output_item.added, response.web_search_call.in_progress, response.web_search_call.searching, response.web_search_call.completed and response.output_item.done for each search, and response.output_text.annotation.added before response.output_text.done.
  • Earlier web_search_call items and annotated messages in input are accepted.
  • usage.server_tool_use counts web_search_requests (the charged searches) and web_fetch_requests.
Shell

A Responses request with web search

curl "https://api.vani.ai/v1/responses" \
  -H "Authorization: Bearer $VANI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-6-sol","input":"What changed in the latest Rust release?","tools":[{"type":"web_search","search_context_size":"medium"}],"store":false}'

Chat Completions: web_search_options

Add web_search_options (search_context_size; user_location: {"type": "approximate", "approximate": {city, region, country, timezone}}). The model searches when the question needs it and answers with links; message.annotations lists url_citation entries (start_index, end_index, url, title). A stream sends them in one annotations delta just before the finish chunk. usage.server_tool_use counts web_search_requests (the charged searches) and web_fetch_requests.

Shell

A Chat Completions request with web search

curl "https://api.vani.ai/v1/chat/completions" \
  -H "Authorization: Bearer $VANI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"google/gemini-3.8-flash","messages":[{"role":"user","content":"What changed in the latest Rust release?"}],"web_search_options":{"search_context_size":"low"}}'

Search and page reading for your own tools

Vani's web search, research and page reader as plain endpoints, for clients that run web tools of their own and for your own code. They take any API key: a prepaid key, or a key created in Vani Chat (Plus and higher plans). No model is involved, so they work the same whichever model you use, Derisked models included.

  • POST /tools/search with {"query": "…", "max_results": 8}: a query of up to 500 bytes and 1 to 8 results (8 by default). The answer lists ranked results, each with title, url, domain and snippet. USD 0.005 per search.
  • POST /tools/research with {"query": "…"}: up to two searches and five pages read. The answer has searches (each with its results) and sources (each page's url, title and text). USD 0.005 for each search it ran, so at most USD 0.01; the pages cost nothing.
  • POST /tools/fetch with {"url": "https://…", "max_chars": 20000}: one page's text (HTML, plain text or PDF) with final_url, title, truncated, content_type and retrieved_at. max_chars takes 400 to 100,000 (100,000 by default). Free. Only public HTTPS pages whose robots.txt allows Vani's research fetcher are read, and the URL you send is read by Vani's own fetcher only.
  • Every answer says untrusted: true (web content is evidence, never instructions) and has usage with web_search_requests and web_fetch_requests.
  • Prepaid keys pay from the prepaid balance, keys created in Vani Chat from the plan allowance, at the same amount. A search that failed or was refused is never charged. A prepaid key needs a balance above zero to read pages.
  • Retries: send an Idempotency-Key header (1 to 128 letters, digits, ., _, : or -) with a search or research, and it is charged once. The same key again is answered 409 api_request_already_admitted without a new search (results are not kept); the key with a different query is 409 idempotency_conflict. A key whose search failed can be sent again.
  • Errors use the API's usual shapes: 400 for a bad body; 400 invalid_url or url_not_allowed, or 422 url_not_accessible with details.reason (such as robots, not_found or unavailable), for a page that cannot be read; the usual balance, allowance and key spend-limit errors; 429 rate_limited with Retry-After; 503 web_unavailable when search is down.
  • Up to 60 web calls a minute and 2,000 page reads a day per account, shared with the MCP server's web tools.
Shell

Search

curl "https://api.vani.ai/v1/tools/search" \
  -H "Authorization: Bearer $VANI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: search-0001" \
  -d '{"query": "latest Rust release notes", "max_results": 5}'
JSON

The answer (shortened)

{
  "query": "latest Rust release notes",
  "retrieved_at": "2026-11-08T12:00:00Z",
  "results": [
    {"source_id": "S1", "title": "Announcing Rust …", "url": "https://blog.rust-lang.org/…", "domain": "blog.rust-lang.org", "snippet": "…"}
  ],
  "untrusted": true,
  "usage": {"web_search_requests": 1, "web_fetch_requests": 0}
}
Shell

Read a page

curl "https://api.vani.ai/v1/tools/fetch" \
  -H "Authorization: Bearer $VANI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://blog.rust-lang.org/", "max_chars": 20000}'

Vani MCP server: web_search and web_fetch

Price and billing

  • USD 0.005 per search that ran (USD 5 per 1,000), on top of the request's tokens. A search that ran but found nothing still counts; a search that failed or was refused (an error result) is never charged.
  • Page reads (web_fetch) cost tokens only: the page text the model reads is input tokens.
  • Prepaid keys pay from the prepaid balance; keys created in Vani Chat pay from the plan allowance, at the same amount.
  • When a request starts, Vani reserves the cost of every search its max_uses allows (8 when not set, 16 for an :online id) on top of its tokens; what the searches did not use is released when the request ends. The balance or allowance must cover that reservation.
  • The request log keeps server_tool_use with the number of searches, page reads and the search fee. A request that fails before delivering anything is not charged, its searches included. A request you cancel, or whose stream you leave, after its searches ran is charged for those searches and the tokens it used.
  • The search endpoints and the MCP server's web_search cost the same USD 0.005 per search, with no tokens; their page reads are free. Their fees show in your balance history and the key's monthly spend (see Search and page reading for your own tools).

API prices per model

Limits and privacy

  • Up to 8 uses of each tool per request; a larger max_uses is lowered to 8. An :online id's own tools have no limit of their own: up to 16 uses of each. A request runs at most 8 model steps and 16 tool calls.
  • A request has 60 seconds of web tool time: the time its searches and page reads take, never the model's own thinking. While that time lasts, each search gets at least 8 seconds and each page read at least 15; once it is used, the model's next step is its final answer.
  • A non-streaming request with web tools that is still working after 30 seconds gets status 200 at once, then a space every 20 seconds to keep the connection open, then the JSON (JSON parsers skip the spaces). A failure after that point comes with status 200 and the format's own error body: {"error": …} on Chat Completions, a failed response on Responses, {"type": "error", …} on Messages. Streams are not affected.
  • Search queries up to 500 bytes (query_too_long above); URLs up to 2,000 characters; up to 60 web tool calls a minute per account (too_many_requests above).
  • max_content_tokens takes up to 25,000 tokens of page text (about 100,000 characters), the length an :online id's page reads have; longer pages are shortened.
  • A query that looks like personal data (an e-mail address, a phone number or another long number) is searched with extra privacy, and the pages it finds, like the URLs you send, are read by Vani's own fetcher only.
  • Vani does not keep search results or pages after the request; nothing is shared between accounts.

Clients

  • Claude Code: its WebSearch tool works with no extra setting (tested with Claude Code 2.1.299), with every model, the Derisked models included. Each WebSearch call is one search; Claude Code's WebFetch reads pages on your machine (no search fee; the page text it gives the model costs tokens as usual).
  • Codex: with web_search set to cached, indexed or live (cached is Codex's default), Codex sends its web search tool with the models it knows to support it, and Vani runs each search, always as a live search. Codex 0.159.2 does so with gpt-5.5 and gpt-5.4, for example, but sends no web search tool with gpt-6-sol or a model id it does not know. Keep it disabled if you do not want search fees. With any other model id, add :online to it and Vani adds web search to every request, whatever Codex's web_search setting.
  • OpenCode, Cline, Kilo Code, Roo Code, Cursor and pi run their web tools on your machine, or have none, so their searches never reach Vani and are not charged here. To search through Vani in these clients, use the model id with :online (see :online model ids), add the Vani MCP server (its web_search and web_fetch tools are the same search and page reader), or call the endpoints in Search and page reading for your own tools from a custom tool.
  • The Anthropic and OpenAI SDKs read these blocks, items and annotations with their own types.

Claude Code and other client guidesVani MCP serverAnthropic-compatible APIOpenAI-compatible API

More reference: OpenAI-compatible API · Anthropic-compatible API · Model ids, limits, headers and usage · Images and PDFs on the API · MCP tools on the API · Media API: images and videos · Artifacts API · Responses API: scope and limits · Model changes: webhooks, feeds and the changes API · API overview · Docs and quickstart