Request options
A request is one JSON object with a required version and query. Everything else is optional and passes straight through to the router.
The fields
| field | value |
|---|---|
version | 1, required. |
query | The search, required. |
tier | "fast", "balanced" or "max". Absent, the request carries your band, or no tier at all and the router applies your key's default. |
recency | "day", "week", "month" or "year". A preference. |
domain_filter | Up to 16 bare hostnames, no scheme or path. A preference. |
max_results | 1 to 25. A cap. |
providers | Up to 16 provider names: restrict the fan-out, or reach an arm that fires only when named. Needs balanced or max. |
view | "full" (default) or "merged", which drops the per-provider candidates. |
A malformed value in any of them answers fix_input before the request reaches the router.
Examples
A plain search. The band you set with /jevlin tier, if any, applies:
{"version":1,"query":"array flatten method"}
Several sources, each attributed:
{"version":1,"query":"compare agent frameworks","tier":"balanced"}
Anything time-bound: a release, a price, the news:
{"version":1,"query":"latest stable Kubernetes release","recency":"month"}
When the answer lives on known sites: documentation, a standard, a vendor:
{"version":1,"query":"array flatten method","domain_filter":["developer.mozilla.org"]}
To read less:
{"version":1,"query":"quick fact check","max_results":3}
To restrict the fan-out to named arms, or to reach one that fires only when named:
{"version":1,"query":"compare agent frameworks","providers":["exa","brave"]}
To save tokens, keeping merged and dropping each provider's own list:
{"version":1,"query":"what is proof of authority consensus","view":"merged"}
Preferences and caps
recency and domain_filter are preferences. The router passes them to its providers, and not every provider honors them, so results from other dates or other hosts can still come back. That is not a failure. If the answer must come from one host or one period, check each citation's url host or date and use only what qualifies. The skill tells the agent the same.
max_results is a cap and is applied.
providers needs tier set to balanced or max; on fast the router answers 400 invalid_request, because the fast set is its own to choose. A named set is recorded as decision.requested and earns nothing under mining. The list is the router's: an unknown name is its call, not refused by the client. The core and named-only arms are listed under Providers and tiers.
view is also sent to the router, which adds its own merged and indexes to its raw answer; the envelope's merged stays the client's own merge. The human form's -view merged with -format json shows that raw answer.
Where the request goes
The agent pipes the object to jevlin search --stdin and reads one envelope back. See Search from a shell for the heredoc and PowerShell forms, The stdin request for the contract, and Choosing a band for how tier interacts with the band you set.