Server tools

kenari has server tools: tools that run on the kenari server and can be used with any model. Add them to the tools array. The model decides when to call one, kenari runs it, then the result is inserted back into the conversation. This is similar to the openrouter:* pattern in OpenRouter.

Available tools

Tool	Type	Purpose	Cost
kenari:web_search	web search	Search the web, results are inserted into model context.	per search
kenari:x_search	X search	Live X (Twitter) search, an answer plus x.com sources are inserted.	per search
kenari:web_fetch	page fetch	Fetch the contents of a specific web page.	per fetch
kenari:datetime	current time	Current date and time.	free

How to use

Include a tool in the tools array with type kenari:<name>. The model sees the tool as a normal function and calls it when needed.

curl https://kenari.id/v1/chat/completions \
  -H "Authorization: Bearer kn-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "tools": [{"type": "kenari:web_search"}],
    "messages": [{"role": "user", "content": "Berita teknologi terbaru minggu ini?"}]
  }'

You can use several tools in one request:

curl https://kenari.id/v1/chat/completions \
  -H "Authorization: Bearer kn-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "tools": [{"type": "kenari:web_search"}, {"type": "kenari:datetime"}],
    "messages": [{"role": "user", "content": "Apa yang terjadi hari ini di dunia AI?"}]
  }'

kenari:web_search

Search the web, then insert the results (title, URL, content summary) as a tool result. The model can search several times before answering in a tool loop. It can be used with any model, not only models that have built-in search. Billed per search.

Works on both non-streaming and streaming responses. With stream: true, the model can elect to call this tool mid-stream. The gateway runs the search server-side, appends the result to the conversation, and opens the next turn until the model answers (or the two-round cap is reached). The customer still sees one coherent message with no tool call in it.

kenari:x_search

Live X (Twitter) search. kenari runs the search, then inserts a short answer plus x.com source links as a tool result. It can be used with any model, not only models with built-in search. Billed per search.

Like kenari:web_search, it works on both non-streaming and streaming responses through the same agentic loop (the model elects, the gateway executes).

Optional x_search_filter:

• allowed_x_handles or excluded_x_handles: scope to specific accounts (at most 20, not usable together).
• from_date, to_date: date range in YYYY-MM-DD.
• enable_image_understanding, enable_video_understanding: read media inside posts.

curl https://kenari.id/v1/chat/completions \
  -H "Authorization: Bearer kn-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "tools": [{"type": "kenari:x_search"}],
    "messages": [{"role": "user", "content": "What is X saying about the latest AI release?"}]
  }'

kenari:web_fetch

Fetch the contents of a web page from a specific URL. Useful when the model needs the full text from one page. The cost per fetch is the same as search and shares the subscription daily quota.

kenari:datetime

Returns the current date and time (UTC plus requested zone). Free. The model needs this so it can know “today” without guessing from training data.

Optional parameter: timezone (IANA zone, default Asia/Jakarta).

Server tools vs provider built-in tools

Besides kenari:*, you can also use provider built-in tools:

• web_search_preview (OpenAI) or web_search_20250305 (Anthropic): forwarded to the upstream. Only works if the upstream model supports built-in search.
• web_search_options (OpenAI field): same behavior, forwarded as-is.

Difference from kenari:web_search: kenari runs its own search, so it can be used with any model. Choose kenari:web_search if the upstream model does not have built-in search. Choose the provider built-in tool if the upstream model already has its own search and you want to use that.

Normal function tools that you define yourself (for example a function named web_search that your client executes) are still forwarded as-is. kenari does not intercept user-owned tools.

Billing

kenari:web_search and kenari:web_fetch are billed per call, outside request tokens. If you subscribe, your package includes a daily quota (search and page fetch count against one shared quota). After the quota runs out, the rest follows PAYG overflow. kenari:datetime is free.

kenari:x_search is billed per search at a flat rate, directly from your balance (not part of the subscription quota). If your balance is not enough, the search does not run and there is no charge.

See Billing for details on how tokens and extra costs are counted.

Direct calls

You can also call kenari search and page fetch directly, without including a model. The result is returned as JSON.

Search the web:

curl https://kenari.id/v1/web/search \
  -H "Authorization: Bearer kn-..." \
  -H "Content-Type: application/json" \
  -d '{"query":"versi stabil Rust terbaru","max_results":5}'

Fetch page contents:

curl https://kenari.id/v1/web/fetch \
  -H "Authorization: Bearer kn-..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://blog.rust-lang.org/2025/05/15/Rust-1.87.0.html"}'

Search X:

curl https://kenari.id/v1/x/search \
  -H "Authorization: Bearer kn-..." \
  -H "Content-Type: application/json" \
  -d '{"query":"latest AI release news","x_search_filter":{"from_date":"2026-01-01"}}'

The response has answer (a short answer) plus citations (x.com source links). All three endpoints need a kn- key and are billed at the per-call rate. If they fail, there is no charge.