Build
Tools and plugins
Read pages directly, give models tools, or connect your own functions.
Choose who runs the tool
- Standalone Google Search — get titles, URLs and snippets directly.
- Standalone Read URL — retrieve page text directly, without a model request.
- Server tools — MiniRouter gets the current time, searches the web or reads a public web page, then returns the model's answer in one request.
- Your own functions — your app runs code, such as a database query, and sends the result back to the model.
- Plugins — MiniRouter shortens a long prompt or repairs JSON. The model does not call a plugin.
Model-driven server tools and plugins use Chat Completions (POST /) only.
Standalone tools use their own endpoints.
Model-driven tools require a model that supports function calling; check tools in its
supported_ in the catalog.
Standalone Read URL
Open the playground, or call POST / with your MiniRouter API key. Check GET / for current availability, price and limits before submitting. For search results, use standalone Google Search.
idempotency_key="$(uuidgen)"
curl https://api.minirouter.sh/v1/tools/web-fetch \
-H "Authorization: Bearer $MINIROUTER_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $idempotency_key" \
-d '{"url":"https://minirouter.sh/docs","max_content_tokens":10000}'The request accepts a public HTTP or HTTPS URL and optional max_.
The content limit must be between 100 and 10,000 tokens. Keys with model or provider restrictions cannot use this endpoint.
It returns readable text, without JavaScript rendering, PDF parsing, authenticated browsing or crawling.
The capability response owns the current limits; the initial maximum is 10,000 content tokens, a 4,096-character URL and a 15-second read deadline.
A completed response includes id, status, data, result_, usage and cost.
Page data includes url, optional title, content, retrieved_ and truncated.
Read cost. in USD for the settled charge. The initial paid price is $0.001 per successful read, using your existing balance and spending limits. Failed reads have no tool charge.
The public playground allows three free reads per UTC day on a network. Shared networks share this allowance; the capability response reports remaining reads and reset time. Sign in to continue with your account balance. The developer API requires an API key.
Receipts and retries
Send a fresh UUIDv4 Idempotency-Key for each new read. Reuse it only for the identical request if delivery is uncertain. A duplicate cannot create another charge; its response is a receipt with data: and result_.
After a timeout or disconnect, look up GET / or GET / with the same account credential. A running receipt is not a failed or free operation. Wait for a terminal receipt before starting another paid read. A missing receipt does not prove that a request failed. An explicit retry with the original UUID and identical input can safely finish a request that never reached admission. After a playground refresh, re-enter the URL and options; the saved UUID is reused. Different input under an existing UUID is rejected.
Page content is returned once and is not stored for replay. Receipts and idempotency records remain available for 30 days, without raw URLs or page content. The playground stores only the request UUID, tool kind and account context for recovery; refreshing the page loses the returned content. Reading again is a new operation at the current price.
Invalid URLs, private networks, unsupported content, rate limits and insufficient balance return bounded errors. Public and authenticated access use separate allowances; signing in does not spend the public trial.
Try a server tool
Create an API key, save its recovery link, and add credits. Replace the placeholder below and run it in your terminal before running the examples on this page.
export MINIROUTER_KEY='paste-your-api-key-here'Examples use paid models. For free requests, follow the Auto Free guide.
Run this in the same terminal. It asks Qwen 3.5 Flash to get the current year
with minirouter:.
curl https://api.minirouter.sh/v1/chat/completions \
-H "Authorization: Bearer $MINIROUTER_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "alibaba/qwen3.5-flash",
"messages": [
{
"role": "user",
"content": "Use the datetime tool to find the current year, then reply with only that four-digit year."
}
],
"max_tokens": 128,
"reasoning": {
"effort": "none"
},
"tools": [
{
"type": "minirouter:datetime"
}
],
"max_tool_calls": 2
}'Read the year in choices[0].. You do not need to write a
datetime function or send a tool result yourself.
How the tool loop works
- You send a prompt and a tool. The
toolsarray tells the model what it can use. - The model requests a tool call. MiniRouter runs the built-in tool and sends its result back to the model.
- The model answers. MiniRouter returns that answer in the same HTTP response. It can repeat step 2 within your
max_limit.tool_ calls
Listing a tool makes it available; the model may answer without using it.
Ask explicitly when the task needs a tool, as in the example above. In a
non-streaming response, x-minirouter-server-tool-rounds lists the model
request IDs. Two or more rounds show that the server tool loop continued.
You can mix built-in tools with your own function definitions. When the model requests one of your functions, MiniRouter returns that call for your app to handle using the function-calling flow.
Available server tools
| Tool | Use it for | Options |
|---|---|---|
minirouter: | Current date and time, no tool fee | parameters.: an IANA name such as Europe/. Default: UTC. |
minirouter: | Readable text from a public URL, $0.001 per successful fetch | Limit page size, domains and fetch count with parameters. Example below. |
minirouter: | Google results, $0.01 per completed search | Set search count, result count and region. Google search guide. |
minirouter: | Current results from the web, $0.01 per search | Filter sources, freshness and language; limit search context. Search options. |
minirouter: | News articles with publisher and date, about $0.012 per search | Filter by recency, date range and source. News options. |
To set the timezone, replace the example's tools field with:
{
"tools": [{
"type": "minirouter:datetime",
"parameters": { "timezone": "Europe/London" }
}]
}Read a web page. This request allows one fetch from example.:
curl https://api.minirouter.sh/v1/chat/completions \
-H "Authorization: Bearer $MINIROUTER_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "alibaba/qwen3.5-flash",
"messages": [
{
"role": "user",
"content": "Use web_fetch to read https://example.com and summarize the page in one sentence."
}
],
"max_tokens": 256,
"reasoning": {
"effort": "none"
},
"tools": [
{
"type": "minirouter:web_fetch",
"parameters": {
"allowed_domains": [
"example.com"
],
"max_uses": 1,
"max_content_tokens": 2000
}
}
],
"max_tool_calls": 2
}'Each successful fetch adds a $0.001 platform fee, plus model tokens.
Failed, blocked and timed-out fetches have no fetch fee. Redirects count as one fetch.
usage. reports the successful, billed count in web_.
Datetime has no tool fee.
Web fetch requires a supported paid route with authoritative billing. Free models, provider keys (BYOK), and routes without authoritative billing reject it.
Web fetch reads a URL; it does not search the web or sign in to a website. Private-network addresses are blocked. The page text is sent to the model as tool output, so treat it as untrusted input.
| Web fetch option | Meaning |
|---|---|
max_ | Fetch attempts per API request, from 1 to 50. The overall max_ limit also applies. |
max_ | Approximate limit on returned page text, from 100 to 100,000. Default: 10,000. |
allowed_ | Only allow these domains. Use hostnames, such as example., without a URL scheme or path. |
blocked_ | Block these domains, even if they also match the allowlist. |
Search the web
Search Formula 1's site for results published in the past month:
curl https://api.minirouter.sh/v1/chat/completions \
-H "Authorization: Bearer $MINIROUTER_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "zai/glm-5.3-flash",
"messages": [
{
"role": "user",
"content": "Search the web for the latest Formula 1 Grand Prix result. Give the winner and source URL."
}
],
"tools": [
{
"type": "minirouter:web_search",
"parameters": {
"max_uses": 1,
"max_results": 3,
"search_domain_filter": [
"formula1.com"
],
"search_recency_filter": "month",
"country": "GB",
"search_language_filter": [
"en"
],
"max_tokens": 4096,
"max_tokens_per_page": 1024
}
}
]
}'Searches cost $0.01 each, plus model tokens. usage. reports
the billed count in web_, capped at max_.
The model can exceed this allowance; extra searches cost about $0.005 each.
Web search is powered by Perplexity. It currently requires a model served through
Vercel; other routes return 400.
Set these options inside the search tool's parameters. All are optional;
numeric values must be integers.
| Search option | Meaning |
|---|---|
max_ | Billed allowance per API request: 1–10 searches at $0.01 each. Default: 3. The model can exceed it. |
max_ | Results per search, from 1 to 20. Omit to let the model choose. |
search_ | Up to 20 hostnames, without a scheme or path. Include with ["formula1. or exclude with ["-reddit.. Do not mix inclusion and exclusion. |
search_ | Publication recency: day, week, month or year. |
country | Regional results. Use an uppercase, two-letter ISO country code, such as GB or US. |
search_ | Up to 10 lowercase, two-letter ISO language codes, such as ["en",. |
max_ | Total search-result tokens per search, from 1 to 1,000,000. Default: 25,000. |
max_ | Search-result tokens per page, from 256 to 2,048. Default: 2,048. |
The tool's parameters. bounds retrieved search context.
The request's top-level max_ limits the model's output per round.
Search the news
Find this week's Federal Reserve coverage:
curl https://api.minirouter.sh/v1/chat/completions \
-H "Authorization: Bearer $MINIROUTER_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "zai/glm-5.3-flash",
"messages": [
{
"role": "user",
"content": "Find this week's news about the Federal Reserve. List each headline with its publisher, date and URL."
}
],
"tools": [
{
"type": "minirouter:news_search",
"parameters": {
"max_uses": 1,
"max_results": 5,
"search_recency_filter": "week"
}
}
]
}'News search is powered by Exa through Vercel and needs a Vercel-served model.
Each search costs $0.01 plus Exa's extra $0.002 at your usual markup, plus
model tokens. usage. reports the billed count in
news_, capped at max_. The model can exceed this allowance;
extra searches cost about $0.007 each. web_ and news_
share a limit of 10 searches per request.
| News option | Meaning |
|---|---|
max_ | Billed allowance per API request: 1–10 searches. Default: 3. |
max_ | Articles per search, from 1 to 10. Default: 5. |
search_ | Published within the last day, week, month or year. |
start_ | Published on or after this ISO 8601 date, such as 2026-10-01. |
end_ | Published on or before this ISO 8601 date. |
search_ | Up to 20 hostnames. Include with ["reuters. or exclude with ["-example.. |
Use either search_ or a date range, not both.
The model sends a query and receives up to max_ articles:
{
"results": [{
"title": "Fed holds rates steady",
"url": "https://www.reuters.com/markets/...",
"publishedDate": "2026-10-01T00:00:00.000Z",
"author": "Reuters staff",
"text": "The first 2,000 characters of the article..."
}]
}publishedDate and author are included when the source provides them;
the publisher is the URL's site. No matches return an empty results list.
A failed or timed-out search returns {"error":
to the model, which can retry or answer without it. Search results stay
with the model; your response contains its answer, not the raw articles.
Streaming, limits and cost
- Limit datetime and web-fetch calls:
max_accepts 1–30, defaults to 5, and requires at least one server tool. After reaching the limit, MiniRouter asks the model to finish without further tool calls. This does not cap web or news searches.tool_ calls - Reserve for fetches: each round holds enough credit for the remaining fetch allowance, bounded by
max_anduses max_; only successful fetches are charged.tool_ calls - Allow for multiple model rounds: the model reads the prompt, then reads the tool results. Each round is billed separately;
max_limits each round, not the whole loop.tokens - Read the total: non-streaming
usageandx-minirouter-cost-usdinclude all model rounds. For streaming totals, sendstream_and read the final usage chunk.options: {"include_ usage": true} - Keep the connection open: use
stream:andtrue curl -Nfor longer loops. MiniRouter sends keep-alives while tools run, then sends the completed answer as SSE events. Intermediate tool rounds are not streamed token by token. Handle error events as well as the final[DONE].
For example, add these fields to the datetime request:
{
"stream": true,
"stream_options": { "include_usage": true }
}Run your own functions
Use a function tool when the work belongs in your app, such as querying an order or calling a weather API. A function definition describes the input; it does not upload or run your code.
curl https://api.minirouter.sh/v1/chat/completions \
-H "Authorization: Bearer $MINIROUTER_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "alibaba/qwen3.5-flash",
"reasoning": {
"effort": "none"
},
"messages": [
{
"role": "user",
"content": "What is the weather in London?"
}
],
"max_tokens": 256,
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string"
}
},
"required": [
"city"
],
"additionalProperties": false
}
}
}
],
"tool_choice": "auto"
}'Then complete the conversation in your application:
- Read
choices[0].. Withmessage. tool_ calls tool_, the model may answer directly instead.choice: "auto" - Parse each function's
argumentsJSON, validate it, check permissions, and run your function. - Append the complete assistant message, including its
tool_, to your originalcalls messagesarray. Keep anyextra_a tool call carries, such as Gemini'scontent extra_: the model needs it to continue its reasoning on the next turn.content. google. thought_ signature - Append a
role:message for each result. Match its"tool" tool_to the actual call ID and encodecall_ id contentas a string. - Send the updated conversation to the same endpoint and model to get the answer. Repeat if the model requests another call.
An illustrative tool result message (replace the ID and content with your result):
{
"role": "tool",
"tool_call_id": "call_id_from_response",
"content": "18 C, cloudy"
}On models that support tool choice, tool_ forces a call
and "none" disables calls. parallel_ controls parallel
function calls where supported. Your app controls its own function-call limit;
max_ is for MiniRouter's built-in tools.
Plugins
Plugins are optional processing steps, enabled through plugins rather than
tools. They do not add functions for the model to call. You can include both
plugin IDs in one request; omit a plugin or set "enabled": to disable it.
Fit a long prompt
Add this field to a Chat Completions request with an explicit model ID:
{
"plugins": [{ "id": "context-compression" }]
}If the prompt is too long for the model's context window after allowing for output, MiniRouter removes conversation turns from the middle, then shortens long messages if needed. It preserves the system-message prefix and the first and latest turns from removal, but message content may still be shortened.
This can discard details; it does not create a summary. Keep essential facts
in a short system message or the latest prompt, and keep your own complete
history. A prompt that already fits is unchanged. Use a named model, not
minirouter/, so MiniRouter can look up its context window.
Repair JSON output
Add these fields to a non-streaming request and ask for JSON in your prompt:
{
"response_format": { "type": "json_object" },
"plugins": [{ "id": "response-healing" }],
"stream": false
}The plugin can remove code fences and surrounding text, and close unfinished
brackets in choices[0].. It also accepts a json_
response format; see structured output
for model support.
Valid JSON and output cut off by the token limit are returned unchanged.
Repair is best-effort, does not guarantee schema compliance, and does not run
with streaming. Check finish_, parse the JSON and validate it in your app.