Web search & fetch

AivoKey can search the web for you, for every model in the catalog — including models that have no search of their own. Claude Code's WebSearch and Codex's web search work out of the box.

How it works

The model decides when it needs the web. AivoKey runs the search, reads the most relevant pages, and gives the model the key facts with their source links. The model can search a few times, then answers and cites what it found.

In your agent it looks like normal tool activity: a "searching…" step, the sources, then the answer.

Which search does my agent use?

AivoKey only searches when the agent asks the server to search. If your agent has its own search tool, that one is used and AivoKey just passes the conversation through. A search never runs twice.

Turn it on

Claude Code — nothing to do. Once it is connected (Claude Code), WebSearch works with any model.

Codex — add one line at the top of ~/.codex/config.toml (Codex):

web_search = "live"

OpenCode — uses its own search, started like this:

OPENCODE_ENABLE_EXA=1 opencode

Pricing

• A search that fails or finds nothing is not charged.
• Searches are paid like the rest of the request (plan allowance or balance).
• Searches done by your agent's own tools are never charged by AivoKey.

Good to know

• A search takes about 20–40 seconds, because pages are actually read, not just listed. Your agent shows a "searching" step meanwhile.
• The same search repeated within an hour returns instantly.
• Web fetch only opens public http(s) pages that already appeared in the conversation (from you or from search results). Some sites block automated readers; the model then gets url_not_accessible and can search instead.

Use it from the API

Messages (Anthropic format)

Add the server tool web_search, and optionally web_fetch:

curl https://api.aivokey.dev/v1/messages \
  -H "x-api-key: sk-aivo_..." \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "What is the latest stable Python release?" }],
    "tools": [
      { "type": "web_search_20250305", "name": "web_search", "max_uses": 3 },
      { "type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 2 }
    ]
  }'

The reply contains server_tool_use blocks (the query), web_search_tool_result blocks (titles and links) and the model's text. usage.server_tool_use counts searches and fetches. Streaming is supported.

Options: max_uses (default 5, at most 20), allowed_domains, blocked_domains; for web_fetch also max_content_tokens.

Responses (OpenAI format)

Add the hosted tool web_search:

curl https://api.aivokey.dev/v1/responses \
  -H "Authorization: Bearer sk-aivo_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "input": "What is the latest stable Python release?",
    "tools": [{ "type": "web_search" }]
  }'

Each search appears in output as a web_search_call item with its query and sources, followed by the model's message. Up to 5 searches per request; filters.allowed_domains is supported.

Chat Completions

The Chat Completions format has no server-side search. Give the model your own search function, or use Messages or Responses.

Tool errors

Errors are handed to the model (not returned as an HTTP error) so it can carry on: max_uses_exceeded, unavailable, query_too_long, url_not_allowed, url_not_accessible.