# Tavily

Tavily web search and content extraction for Bijection applications

- Package: @bijectionhq/tavily
- Category: AI & Agents
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/tavily/tree/09a5a5feeb54da1dc1d1534a275cfaa93e32644e
- Upstream: https://github.com/tavily-ai/convex-tavily/tree/e910659f7f7bf78fa758cb5d6a3305d268b3494a
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/tavily

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/tavily.git
cd tavily
git checkout 09a5a5feeb54da1dc1d1534a275cfaa93e32644e
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Upstream package documentation

Recorded 2026-10-23. This describes @tavily/convex-tavily; check the Bijection adaptation separately.

convex-tavily installs Tavily web search and content extraction as an isolated Convex component. It exposes a typed `TavilyClient` that wraps Tavily's search and extract APIs, routing calls through component actions so the `TAVILY_API_KEY` stays in Convex environment configuration rather than scattered across application code. The component is stateless and owns no database tables.

### Use cases

- Adding real-time web search to an AI agent or chatbot that needs up-to-date information beyond its training data
- Extracting structured content from a known list of URLs for ingestion into a Convex-backed RAG pipeline
- Building a research tool that needs both discovery (search) and content retrieval (extract) in the same Convex action
- Centralizing Tavily API key management across a team so individual developers do not handle credentials directly
- Wrapping search or extraction calls in application-owned actions to enforce authentication, authorization, or rate limiting before hitting the Tavily API

### How it works

The component is registered in `convex/convex.config.ts` using `app.use(tavily, ...)`, which scopes the `TAVILY_API_KEY` environment variable to the component rather than the top-level app. This keeps credential handling isolated and typed via Convex's environment configuration system.

Application code instantiates a `TavilyClient` with `new TavilyClient(components.tavily)` and calls it from within application-owned Convex actions. The client provides two methods: `search(ctx, args)` for web search with options like `searchDepth` (`basic` or `advanced`), `maxResults`, `timeRange`, and image/favicon toggles, and `extract(ctx, args)` for fetching and processing up to 20 URLs with query-focused chunking, image extraction, and markdown formatting.

The request flow goes from the application action through `TavilyClient` to `ctx.runAction(components.tavily.lib.search)` or `.extract`, which then makes the outbound POST request to `api.tavily.com`. Keeping the wrapper action in the application layer gives developers a natural place to add auth checks or rate limiting before the external call is made.

The component is stateless and does not write to any Convex tables, so there is no schema migration or data lifecycle to manage.

### Upstream README

# convex-tavily

Tavily web search and content extraction for Convex applications.

This package installs Tavily as an isolated Convex component. Application actions call a typed `TavilyClient`, which delegates to component actions and keeps `TAVILY_API_KEY` in typed Convex environment configuration.

## Install

```bash
npm install @tavily/convex-tavily
```

## Configure Convex

Add the component to `convex/convex.config.ts`:

```ts
import { defineApp } from "convex/server";
import { v } from "convex/values";
import tavily from "@tavily/convex-tavily/convex.config";

const app = defineApp({
  env: {
    TAVILY_API_KEY: v.string(),
  },
});

app.use(tavily, {
  name: "tavily",
  env: {
    TAVILY_API_KEY: app.env.TAVILY_API_KEY,
  },
});

export default app;
```

Set your key:

```bash
npx convex env set TAVILY_API_KEY tvly-your-key
```

## Search the web

Call the component from an application-owned action. Keeping this wrapper in the app gives you a place to add authentication, authorization, and rate limiting.

```ts
import { action } from "./_generated/server";
import { components } from "./_generated/api";
import { TavilyClient } from "@tavily/convex-tavily";
import { v } from "convex/values";

const tavily = new TavilyClient(components.tavily);

export const searchWeb = action({
  args: { query: v.string() },
  handler: async (ctx, args) => {
    return await tavily.search(ctx, {
      query: args.query,
      searchDepth: "advanced",
      maxResults: 5,
      includeAnswer: false,
      includeFavicon: true,
    });
  },
});
```

## Extract known pages

```ts
export const extractPages = action({
  args: {
    urls: v.array(v.string()),
    query: v.optional(v.string()),
  },
  handler: async (ctx, args) => {
    return await tavily.extract(ctx, {
      urls: args.urls,
      query: args.query,
      chunksPerSource: args.query ? 3 : undefined,
      extractDepth: "advanced",
      format: "markdown",
    });
  },
});
```

## Request flow

```text
App client
  -> application Convex action
  -> TavilyClient.search/extract
  -> ctx.runAction(components.tavily.lib.search/extract)
  -> POST https://api.tavily.com/search or /extract
```

## Current API

- `search(ctx, args)` — Search (`basic`/`advanced` depth, `timeRange`, images/favicon/usage knobs).
- `extract(ctx, args)` — Extract up to 20 URLs, including query-focused chunks, images, timeout.

The component is stateless and owns no database tables.

## Development

```bash
npm install
cd example && npm install && cd ..
npm run build:codegen
npm test
npm run lint
npm run typecheck
```

Component code generation may require a configured Convex development deployment.