Live Web Search with Tavily

tavily-web-search is a Hybrid gene that searches the web through the Tavily API. It takes the same input and returns the same output as genesis-web-search. The difference is that genesis-web-search is a demo that returns made-up example.com results, and these results are real.

What you need

A Tavily API key. Sign up at tavily.com. The free tier is 1,000 searches a month and needs no card.
A Rotifer project. Run the commands below in one; rotifer init creates one.

Install it

rotifer install tavily-web-search

This downloads the compiled gene from Rotifer Cloud into genes/tavily-web-search/ and checks the module’s SHA-256 before saving it. Nothing needs building.

Set your key

Type the key without it showing on screen or landing in your shell history:

read -rs TAVILY_API_KEY && export TAVILY_API_KEY

Paste the key and press Enter. It stays set for this terminal session.

Search

rotifer run tavily-web-search --input '{"query":"WebAssembly component model","maxResults":3}'

{
  "results": [
    { "title": "…", "url": "https://…", "snippet": "…" }
  ],
  "totalResults": 3,
  "searchTime": 840
}

maxResults can be 1–20 (default 5). searchTime is the response time Tavily reports, in milliseconds.

Where your key goes

The gene’s phenotype.json declares the key by name:

"externalDependencies": [
  {
    "apiType": "rest",
    "semanticTag": "tavily-search",
    "domains": ["api.tavily.com"],
    "credentials": ["TAVILY_API_KEY"],
    "degradationBehavior": "FAIL"
  }
]

The CLI reads TAVILY_API_KEY from your environment because the gene declares that name. It reads no other variable, and there is no key file.
The gene never sees the key. Its request carries the text Authorization: Bearer ${env:TAVILY_API_KEY}, and the CLI puts the key in as the request leaves the sandbox.
The request can go only to api.tavily.com. Any other host is refused before anything is sent.
The key is not printed, and it is not written to the output, the logs or the audit log.

When something goes wrong

What you see	What it means
`missing credential: the environment variable TAVILY_API_KEY is not set`	The key is not set in this terminal. Set it as above. The gene did not run.
`gene returned error code: -2` on every run, with or without a key	Your CLI is older than 0.31.0. Upgrade as in the note at the top.
`gene returned error code: -201`	Tavily rejected the key. Check it on your Tavily dashboard.
`gene returned error code: -202`	Tavily’s rate limit, or your plan’s monthly limit, was reached.
`gene returned error code: -203`	Tavily returned another error.
`gene returned error code: -204`	Tavily answered, but not in a form the gene can read.
`gene returned error code: -4` or `-5`	The request timed out, or the network failed.
`INVALID_INPUT: …`	`query` is missing or empty, or `maxResults` is outside 1–20, e.g. `INVALID_INPUT: maxResults must be an integer from 1 to 20`. No search was made.

Build it from source (optional)

The gene’s Rust source is in the rotifer-playground repository. To build it yourself instead of installing it, copy genes/tavily-web-search into your project’s genes/ directory, then from the project root:

rustup target add wasm32-unknown-unknown

cargo build --release --target wasm32-unknown-unknown --manifest-path genes/tavily-web-search/Cargo.toml

rotifer compile tavily-web-search --wasm genes/tavily-web-search/target/wasm32-unknown-unknown/release/tavily_web_search.wasm

compile keeps the gene Hybrid and writes genes/tavily-web-search/gene.ir.wasm; then set your key and search as above. This also needs 0.31.0 or later: on 0.30.x, compile says Hybrid gene — runs under Node.js with the network gateway; no WASM artifact is produced and no gene.ir.wasm is written.

For how API keys work in any Hybrid gene, see the Hybrid Gene Development Guide.