# Exa

Web search and content retrieval

- Package: @bijectionhq/exa
- Category: Web & Search
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/exa/tree/7a8fe51042379faa6aed864b6fc0fe13ba2b3130
- Upstream: https://github.com/exa-labs/exa-convex/tree/e91a5f8ce5a8ff710dbc2ab5ca90cd62d3851291
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/exa

## Get the source

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

```sh
git clone https://github.com/bijectionhq/exa.git
cd exa
git checkout 7a8fe51042379faa6aed864b6fc0fe13ba2b3130
```

## 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 @exalabs/convex-exa; check the Bijection adaptation separately.

The Exa component brings real-time web intelligence to Convex applications through the Exa API. It provides three core functions: web search with optional highlights, structured deep search, and direct URL content fetching. Developers can power AI agents, research workflows, content monitoring, and knowledge-base updates with fresh web context in just a few backend calls.

### Use cases

- **AI agents and assistants**: Give LLM-powered features fresh web context for companies, products, markets, news, and user-specific research
- **Structured research workflows**: Turn broad web searches into typed, schema-validated outputs for funding rounds, product launches, industry reports, and competitive analysis
- **Content monitoring**: Watch domains, topics, or recent activity windows with `maxAgeHours` filtering for alerts, dashboards, and internal workflows
- **Knowledge base enrichment**: Pull content from trusted URLs to keep docs, datasets, and internal context up to date with external sources
- **News and market intelligence**: Search recent coverage, extract highlights, and summarize relevant articles for feeds, briefings, and reports

### How it works

The component runs Exa from your Convex backend through the `ExaClient` class. Add it to your Convex app, set `EXA_API_KEY`, and create an `ExaClient` instance pointed at your component configuration.

Use `search()` for web search with optional highlights, summaries, or extracted text; `deepSearch()` for structured research with typed outputs; and `contents()` to fetch content from specific URLs. Each method runs as a Convex action, so your Exa API key stays server-side.

For schema-based research, `deepSearch()` converts your Zod schema into JSON Schema for Exa’s deep search API, then returns typed results that fit naturally into the rest of your Convex functions.

### Upstream README

# convex-exa

Web search and content extraction for Convex applications. Search the web, pull clean page content, and return structured answers.

## Quick Start

### 1. Install the Component

```bash
npm install @exalabs/convex-exa zod
```

`zod` is required when you pass a Zod `schema` to `deepSearch`.

### 2. Configure Convex

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

```typescript
import { defineApp } from "convex/server";
import { v } from "convex/values";
import exa from "@exalabs/convex-exa/convex.config";

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

app.use(exa, {
  name: "exa",
  env: {
    EXA_API_KEY: app.env.EXA_API_KEY,
  },
});

export default app;
```

### 3. Set Up Environment Variables

Add this to your [Convex Dashboard](https://dashboard.convex.dev) → Settings → Environment Variables:

| Variable | Description |
|----------|-------------|
| `EXA_API_KEY` | Your [Exa](https://dashboard.exa.ai) API key |

You can also set it from the CLI: `npx convex env set EXA_API_KEY <your-key>`.

### 4. Use the Component

```typescript
import { action } from "./_generated/server";
import { ExaClient } from "@exalabs/convex-exa";
import { components } from "./_generated/api";
import { z } from "zod";

const exa = new ExaClient(components.exa);

export const searchNews = action({
  handler: async (ctx) => {
    return await exa.search(ctx, {
      query: "recent llm launches",
      contents: {
        highlights: true,
        maxAgeHours: 24,
      },
    });
  },
});

export const summarizeFunding = action({
  handler: async (ctx) => {
    return await exa.deepSearch(ctx, {
      query: "recent AI startup funding announcements",
      systemPrompt: "Prefer official sources and avoid duplicate reporting.",
      schema: z.object({
        summary: z.string(),
        companies: z.array(z.string()),
      }),
    });
  },
});

export const fetchKnownPage = action({
  handler: async (ctx) => {
    return await exa.contents(ctx, {
      urls: ["https://exa.ai/docs"],
      highlights: true,
      maxAgeHours: 12,
    });
  },
});
```

## API Reference

### `search(ctx, args)`

Run Exa `/search` with `type: "auto"` by default. Use for general retrieval; pass nested `contents` when you want highlights or text on result URLs.

```typescript
await exa.search(ctx, {
  query: "battery recycling policy changes in the EU",
  contents: {
    highlights: true,
  },
});
```

**Parameters:**
- `query` - Search query
- `contents` - Optional nested options for text, highlights, summary, `maxAgeHours`, etc.
- Other fields are forwarded to the Exa search API (filters, `numResults`, `type`, etc.)

---

### `deepSearch(ctx, args)`

Run Exa `/search` with `type: "deep"` by default. Use when you want structured or synthesized output.

```typescript
await exa.deepSearch(ctx, {
  query: "Compare recent frontier model launches",
  schema: z.object({
    summary: z.string(),
    models: z.array(z.string()),
  }),
});
```

**Parameters:**
- `query` - Search query
- `schema` - Zod schema for structured output (converted to JSON Schema for Exa)
- `outputSchema` - Raw JSON Schema instead of Zod
- `systemPrompt` - Optional guidance for the deep search model
- `type` - One of `deep-lite`, `deep`, `deep-reasoning`

**Returns:** Exa search response; structured fields follow your schema when provided

---

### `contents(ctx, args)`

Fetch content for URLs you already know via Exa `/contents`.

```typescript
await exa.contents(ctx, {
  urls: ["https://exa.ai/docs"],
  highlights: true,
  maxAgeHours: 12,
});
```

**Parameters:**
- `urls` - URLs to fetch
- `text`, `highlights`, `summary` - Top-level content options (not nested under `contents` like on `/search`)

---

## Requirements

- [Exa](https://exa.ai) account and API key
- Convex 1.39.1 or later
- `zod` when using schemas with `deepSearch`

## How It Works

This component wraps the Exa API inside a Convex component. Your actions call `ExaClient`, which runs component actions that:

1. Read `EXA_API_KEY` from component environment configuration
2. Call Exa `/search` or `/contents` with your arguments
3. Return typed results to your Convex action

The API key stays in Convex env—not in client-visible code.

## Development

### Building the Component

To build the component locally:

```bash
# Install dependencies
npm install
cd example && npm install && cd ..

# Build with Convex codegen (generates component API)
npm run build:codegen

# Or just build TypeScript
npm run build:esm

# Run tests
npm test
```

The component requires a Convex deployment to generate proper component API types (`_generated/component.ts`).

### Example App

Work against a live deployment with the example app:

```bash
npm run dev
```

This runs the example Convex backend and rebuilds the component when `src/` changes.

See [example/README.md](/example/README.md) for a walkthrough of the example app, which demonstrates:

- `searchNews`: Retrieve general web results based on queries.
- `deepResearch`: Perform structured and schema-driven deep search.
- `fetchKnownPage`: Extract contents from a specific, known URL.

These example actions highlight key parameters you’ll likely want to adjust in your own application, such as:

- Filtering by domain
- Including or excluding text via text filters
- Setting the number of results to return
- Choosing a search mode
- Selecting a content mode (`highlights`, `text`, or `summary`)
- Limiting document recency with `maxAgeHours`

See [the Exa API Docs](https://docs.exa.ai) for full reference on the available parameters and capabilities.