librechat.ai/content/docs/features/web_search.mdx

---
title: "Web Search"
icon: Search
---

LibreChat's web search feature allows you to search the internet and retrieve relevant information to enhance your conversations. The feature consists of three main components that work together to provide comprehensive search results.

## Quick Start

To get started with web search, you'll need to configure API keys for all three components to ensure effective search results. You can do this in two ways:

1. **Environment Variables** (Recommended for admins):
   ```bash
   # Search Provider (Required)
   SERPER_API_KEY=your_serper_api_key
   # or
   SEARXNG_INSTANCE_URL=your_searxng_instance_url
   SEARXNG_API_KEY=your_searxng_api_key  # Optional

   # Scraper (Required)
   FIRECRAWL_API_KEY=your_firecrawl_api_key
   # Optional: Custom Firecrawl API URL
   FIRECRAWL_API_URL=your_firecrawl_api_url
   # Optional: Firecrawl API version (v0 or v1)
   # FIRECRAWL_VERSION=v1

   # Reranker (Required)
   JINA_API_KEY=your_jina_api_key
   # Optional: Custom Jina API URL
   JINA_API_URL=your_jina_api_url
   # or
   COHERE_API_KEY=your_cohere_api_key
   ```

2. **User Interface** (If environment variables are not set):
   - Users will be prompted to enter the required API keys when they first use the web search feature
   - They can choose which search provider (Serper or SearXNG) and which reranker service to use (Jina or Cohere)

## Obtaining API Keys

Each component of the web search feature requires its own API key. Here's how to obtain them:

### Search Providers

#### Serper
1. Visit [Serper.dev](https://serper.dev)
2. Sign up for an account
3. Navigate to the API Key section
4. Copy your API key
5. Set it in your environment variables or provide it through the UI

#### SearXNG
1. Follow the setup instructions in the [Web Search Configuration](/docs/configuration/librechat_yaml/object_structure/web_search#setting-up-searxng) documentation
2. Set `SEARXNG_INSTANCE_URL` to your instance URL
3. Optionally set `SEARXNG_API_KEY` if your instance requires authentication

### Scraper: Firecrawl

1. Visit [Firecrawl.dev](https://docs.firecrawl.dev/introduction#api-key)
2. Sign up for an account
3. Navigate to the API Key section
4. Copy your API key
5. Set it in your environment variables or provide it through the UI
6. (Optional) If you're using a custom Firecrawl instance, you'll also need to set the API URL

### Rerankers

#### Jina
1. Visit [Jina.ai](https://jina.ai/api-dashboard/)
2. Sign up for an account
3. Navigate to the API Dashboard
4. Copy your API key
5. Set it in your environment variables or provide it through the UI

#### Cohere
1. Visit [Cohere Dashboard](https://dashboard.cohere.com/welcome/login)
2. Sign up for an account
3. Navigate to the API Keys section
4. Copy your API key
5. Set it in your environment variables or provide it through the UI

## Components

### 1. Search Providers

Search providers are responsible for performing the initial web search and returning relevant results.

**Available Providers:**
- **Serper**: A Google Search API that provides high-quality search results
  - Get your API key from [Serper.dev](https://serper.dev/api-key)
- **SearXNG**: Open-source, self-hosted meta search engine
  - Self-host your own instance
  - Privacy-focused search results

### 2. Scrapers

Scrapers extract the actual content from web pages returned by the search provider.

**Available Scrapers:**
- **Firecrawl**: A powerful web scraping service that extracts content from web pages
  - Get your API key from [Firecrawl.dev](https://docs.firecrawl.dev/introduction#api-key)
  - API URL is optional (defaults to Firecrawl's hosted service)

**Planned Scrapers:**
- **Local Firecrawl**: Self-hosted version of Firecrawl
- Additional third-party scraping services

### 3. Rerankers

Rerankers analyze the scraped content to determine the most relevant parts and reorder them for better results.

**Available Rerankers:**
- **Jina**: AI-powered reranking service
  - Get your API key from [Jina.ai](https://jina.ai/api-dashboard/)
  - API URL is optional (defaults to Jina's hosted service)
- **Cohere**: Advanced reranking service
  - Get your API key from [Cohere Dashboard](https://dashboard.cohere.com/welcome/login)

**Planned Rerankers:**
- **RAG API**: Open-source reranking using RAG (Retrieval-Augmented Generation)
- Additional third-party reranking services

## Configuration

### Admin Configuration

Admins can configure the web search feature using environment variables. The YAML configuration allows you to specify custom environment variable names for each component.

⚠️ **Important: Never put actual API keys or values in the YAML file (they won't work)- only use environment variable names.**

```yaml
webSearch:
  # Search Provider Configuration
  serperApiKey: "${CUSTOM_SERPER_API_KEY}"  # ✅ Correct: Using environment variable name
  # serperApiKey: "sk-123..."               # ❌ Wrong: Never put actual API keys here
  # or
  searxngInstanceUrl: "${CUSTOM_SEARXNG_INSTANCE_URL}"  # ✅ Correct: Using environment variable name
  searxngApiKey: "${CUSTOM_SEARXNG_API_KEY}"            # ✅ Correct: Using environment variable name
  # searxngInstanceUrl: "http://..."        # ❌ Wrong: Never put actual URLs here
  # searxngApiKey: "sk-123..."              # ❌ Wrong: Never put actual API keys here

  # Scraper Configuration
  firecrawlApiKey: "${CUSTOM_FIRECRAWL_API_KEY}"
  firecrawlApiUrl: "${CUSTOM_FIRECRAWL_API_URL}"
  # firecrawlApiKey: "fc-123..."            # ❌ Wrong: Never put actual API keys here
  # firecrawlApiUrl: "https://..."          # ❌ Wrong: Never put actual URLs here

  # Reranker Configuration
  jinaApiKey: "${CUSTOM_JINA_API_KEY}"
  jinaApiUrl: "${CUSTOM_JINA_API_URL}"
  cohereApiKey: "${CUSTOM_COHERE_API_KEY}"
  # jinaApiKey: "jn-123..."                 # ❌ Wrong: Never put actual API keys here
  # jinaApiUrl: "https://..."               # ❌ Wrong: Never put actual URLs here
  # cohereApiKey: "ch-123..."               # ❌ Wrong: Never put actual API keys here

  # General Settings
  safeSearch: 1 # Options: 0 (OFF), 1 (MODERATE - default), 2 (STRICT)
```

**Note:** The YAML configuration should only contain environment variable names (in the format `${VARIABLE_NAME}`). This flexibility enables:
- Using different variable names in different environments
- Supporting multiple configurations for different user groups
- Future integration with role-based configurations

If you want to restrict the system to use only specific services, you can specify the service types:

```yaml
webSearch:
  # ... variable configurations ...
  searchProvider: "serper"    # Only use Serper for search
  # searchProvider: "searxng" # Only use SearXNG for search
  scraperProvider: "firecrawl"    # Only use Firecrawl for scraping
  rerankerType: "jina"        # Only use Jina for reranking
```

### User Configuration

If the admin hasn't configured all the necessary API keys, users will be prompted to provide them through the UI. The interface allows users to:

1. Choose their preferred reranker (Jina or Cohere)
2. Enter API keys for the required services
3. Configure the Firecrawl API URL if needed (optional)
4. Configure the Jina API URL if needed (optional)

## Usage

Once configured, you can use web search in two ways:

1. **Chat Interface**: Click the web search button in the chat interface to enable web search for your conversation
2. **Agents**: Use the `web_search` capability in agents to allow them to search the web

## Notes

- All three components (search provider, scraper, and reranker) are required for effective search results
- The Firecrawl API URL is optional and defaults to their hosted service
- The Jina API URL is optional and defaults to their hosted service
- Safe search provides three levels of content filtering: OFF (0), MODERATE (1 - default), and STRICT (2)
- The scraper timeout is set to 7.5 seconds (7500ms) by default
- API keys can be revoked at any time through the UI
- Future updates will include more open-source, self-hosted options for all components
- Additional customization options are planned, including:
  - Control over the number of links to scrape
  - Domain allowlist/blocklist for scraping
  - Custom scraping rules and filters
  - Advanced result filtering and ranking options
  - Rate limiting and request throttling controls