# API reference
Source: https://docs.andiai.com/api-reference/introduction

Technical reference for the Andi AI Search API endpoint.

The Andi AI Search API has a single endpoint that handles all search operations.

## Base URL

```text theme={null}
https://search-api.andisearch.com
```

## Authentication

Pass your API key in the `x-api-key` header with every request:

```bash theme={null}
curl "https://search-api.andisearch.com/api/v1/search?q=test" \
  -H "x-api-key: YOUR_API_KEY"
```

Get an API key from the [API Console](https://console.andiai.com).

## Endpoint

| Method | Path             | Description    |
| ------ | ---------------- | -------------- |
| `GET`  | `/api/v1/search` | Search the web |

The endpoint supports two search modes (`fast` and `deep`), multiple output formats, and filtering by domain, date, content type, and more.

Browse the **Endpoints** section in the sidebar to try the search endpoint in the interactive playground.


# Search the web
Source: https://docs.andiai.com/api-reference/search-the-web

api-reference/openapi.json get /api/v1/search
Performs a web search and returns structured results. Supports fast (default) and deep search modes, domain and date filtering, query operators, and multiple output formats.



# Filtering
Source: https://docs.andiai.com/features/filtering

Filter Andi AI Search API results by domain, date range, file type, and content location.

The API supports filtering through both query parameters and in-query operators. This page covers the parameter-based approach — see [query operators](/features/query-operators) for inline syntax.

## Domain filtering

Restrict results to specific domains or exclude unwanted ones.

### Include domains

Return results only from the specified domains:

```bash theme={null}
curl "https://search-api.andisearch.com/api/v1/search?q=python+tutorials&includeDomains=docs.python.org,realpython.com" \
  -H "x-api-key: YOUR_API_KEY"
```

### Exclude domains

Remove specific domains from results:

```bash theme={null}
curl "https://search-api.andisearch.com/api/v1/search?q=python+tutorials&excludeDomains=w3schools.com,pinterest.com" \
  -H "x-api-key: YOUR_API_KEY"
```

### Wildcards

Match all subdomains with `*`:

```bash theme={null}
# Include all subdomains of example.com
?includeDomains=*.example.com

# Exclude all subdomains of example.com
?excludeDomains=*.example.com
```

## Date filtering

Filter results by publication date using relative ranges or absolute dates.

### Relative date ranges

Use `dateRange` for common time windows:

```bash theme={null}
# Results from the past week
curl "https://search-api.andisearch.com/api/v1/search?q=tech+news&dateRange=week" \
  -H "x-api-key: YOUR_API_KEY"
```

Available values: `day`, `week`, `month`, `year`, `24h`, `7d`, `30d`, `90d`, `1y`.

### Absolute date ranges

Use `dateFrom` and `dateTo` for specific date boundaries:

```bash theme={null}
# Results from Q1 2025
curl "https://search-api.andisearch.com/api/v1/search?q=quarterly+earnings&dateFrom=2025-01-01&dateTo=2025-03-31" \
  -H "x-api-key: YOUR_API_KEY"
```

You can use one or both:

* `dateFrom` alone — results from that date onward
* `dateTo` alone — results up to that date
* Both — results within the range

## Content filtering

Filter by file type or where terms appear on the page.

### File type

```bash theme={null}
curl "https://search-api.andisearch.com/api/v1/search?q=annual+report&filetype=pdf" \
  -H "x-api-key: YOUR_API_KEY"
```

### Title, URL, and body text

```bash theme={null}
# Term must appear in the page title
?intitle=tutorial

# Term must appear in the URL
?inurl=api

# Term must appear in the body text
?intext=benchmarks
```

## Combined filtering

Filters stack — combine them to narrow results precisely:

```bash theme={null}
curl "https://search-api.andisearch.com/api/v1/search?q=machine+learning&includeDomains=arxiv.org,github.com&dateRange=month&filetype=pdf&limit=20" \
  -H "x-api-key: YOUR_API_KEY"
```

This searches for machine learning PDFs on arxiv.org and github.com from the past month.


# Query operators
Source: https://docs.andiai.com/features/query-operators

Use in-query operators to refine search results directly in the query string.

Query operators let you control search behavior directly in the `q` parameter. They work when `parseOperators` is enabled (the default).

## Site operators

Restrict or exclude results from specific domains:

| Operator | Description                      | Example                                |
| -------- | -------------------------------- | -------------------------------------- |
| `site:`  | Results only from this domain    | `site:github.com python libraries`     |
| `-site:` | Exclude results from this domain | `machine learning -site:wikipedia.org` |

```bash theme={null}
curl "https://search-api.andisearch.com/api/v1/search?q=site:github.com+python+libraries" \
  -H "x-api-key: YOUR_API_KEY"
```

## Term operators

Require or exclude specific terms:

| Operator | Description                     | Example                 |
| -------- | ------------------------------- | ----------------------- |
| `+term`  | Term must appear in results     | `+python web framework` |
| `-term`  | Term must not appear in results | `apple -fruit`          |

## Content operators

Filter by where terms appear:

| Operator    | Description                                      | Example                             |
| ----------- | ------------------------------------------------ | ----------------------------------- |
| `filetype:` | Filter by file extension (alias: `ext:`)         | `filetype:pdf machine learning`     |
| `intitle:`  | Term must be in the page title                   | `intitle:tutorial react hooks`      |
| `inurl:`    | Term must be in the URL                          | `inurl:api documentation`           |
| `intext:`   | Term must be in the body text (alias: `inbody:`) | `intext:benchmarks LLM performance` |

```bash theme={null}
curl "https://search-api.andisearch.com/api/v1/search?q=filetype:pdf+machine+learning+survey" \
  -H "x-api-key: YOUR_API_KEY"
```

## Date operators

Filter results by publication date:

| Operator  | Description                        | Example                            |
| --------- | ---------------------------------- | ---------------------------------- |
| `after:`  | Results published after this date  | `after:2025-01-01 AI news`         |
| `before:` | Results published before this date | `before:2024-06-01 product launch` |

Dates use `YYYY-MM-DD` format.

## Language operator

Filter results by language:

| Operator | Description                                   | Example                           |
| -------- | --------------------------------------------- | --------------------------------- |
| `lang:`  | Results in this language (alias: `language:`) | `lang:es inteligencia artificial` |

Uses ISO 639-1 two-letter language codes.

## Combining operators

Operators can be combined in a single query:

```bash theme={null}
curl "https://search-api.andisearch.com/api/v1/search?q=site:github.com+filetype:md+intitle:readme+machine+learning+after:2025-01-01" \
  -H "x-api-key: YOUR_API_KEY"
```

This searches GitHub for markdown README files about machine learning published after January 2025.

## Disabling operator parsing

If your query contains text that looks like an operator but shouldn't be treated as one, set `parseOperators=false`:

```bash theme={null}
curl "https://search-api.andisearch.com/api/v1/search?q=how+to+use+site:+prefix+in+DNS&parseOperators=false" \
  -H "x-api-key: YOUR_API_KEY"
```

When disabled, the entire query is treated as literal text.


# Query parameters
Source: https://docs.andiai.com/features/query-parameters

Complete reference for all Andi AI Search API query parameters.

All parameters are passed as query string parameters on the `GET /api/v1/search` endpoint.

## Core parameters

| Parameter | Type    | Default      | Description                                                                                             |
| --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------- |
| `q`       | string  | **required** | Search query string. Also accepts a JSON array of up to 5 queries (e.g., `["query one", "query two"]`). |
| `limit`   | integer | `10`         | Maximum results to return (1–100)                                                                       |
| `offset`  | integer | `0`          | Results to skip for pagination                                                                          |
| `depth`   | string  | `fast`       | Search mode: `fast` or `deep`                                                                           |
| `intent`  | string  | auto         | Force search intent. See [intent values](#intent-values) below.                                         |

### Intent values

When not set, the API auto-detects intent from the query. You can force a specific intent using common aliases:

| Alias       | Description         | Alias       | Description         |
| ----------- | ------------------- | ----------- | ------------------- |
| `search`    | General web search  | `news`      | Latest news results |
| `video`     | Video search        | `images`    | Image search        |
| `weather`   | Weather data        | `calculate` | Math computation    |
| `wiki`      | Wikipedia/knowledge | `knowledge` | Academic knowledge  |
| `code`      | Programming results | `recipe`    | Recipe results      |
| `place`     | Business search     | `places`    | Location search     |
| `questions` | Q\&A results        | `time`      | Time queries        |

The API also accepts full intent names (e.g., `FallbackSearchIntent`, `VideoSearchIntent`) and resolves matches flexibly through exact match, case-insensitive match, and substring match.

## Output parameters

| Parameter  | Type    | Default | Description                                                                                                                           |
| ---------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `format`   | string  | `json`  | Response format: `json` or `context`. The `context` format returns results as markdown text, suitable for passing to language models. |
| `metadata` | string  | `basic` | Metadata level: `basic` or `full`. With `full`, results include `contentType` and `reader` data.                                      |
| `extracts` | boolean | `false` | Include longer text extracts from result pages                                                                                        |

## Filtering parameters

| Parameter  | Type   | Default | Description                                                                                                                             |
| ---------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `safe`     | string | `off`   | Safe search level: `off`, `moderate`, or `strict`                                                                                       |
| `country`  | string | `US`    | ISO 3166-1 country code (e.g., `US`, `GB`, `DE`)                                                                                        |
| `language` | string | `en`    | ISO 639-1 language code (e.g., `en`, `es`, `fr`)                                                                                        |
| `units`    | string | auto    | Unit system for weather/calculations: `metric`, `imperial`. Defaults based on `country` — `imperial` for `US`, `metric` for all others. |

## Date filtering

| Parameter   | Type   | Description                                                                     |
| ----------- | ------ | ------------------------------------------------------------------------------- |
| `dateRange` | string | Relative range: `day`, `week`, `month`, `year`, `24h`, `7d`, `30d`, `90d`, `1y` |
| `dateFrom`  | date   | Results published on or after this date (`YYYY-MM-DD`)                          |
| `dateTo`    | date   | Results published on or before this date (`YYYY-MM-DD`)                         |

Use either `dateRange` for relative filtering or `dateFrom`/`dateTo` for absolute date ranges. See [filtering](/features/filtering) for details.

## Domain filtering

| Parameter        | Type   | Description                                     |
| ---------------- | ------ | ----------------------------------------------- |
| `includeDomains` | string | Comma-separated domains to restrict results to  |
| `excludeDomains` | string | Comma-separated domains to exclude from results |

Both support wildcards: `*.example.com` matches all subdomains. See [filtering](/features/filtering) for details.

## Term filtering

| Parameter      | Type   | Description                                       |
| -------------- | ------ | ------------------------------------------------- |
| `includeTerms` | string | Comma-separated terms that must appear in results |
| `excludeTerms` | string | Comma-separated terms to exclude from results     |

## Content filtering

| Parameter  | Type   | Description                                      |
| ---------- | ------ | ------------------------------------------------ |
| `filetype` | string | File extension to filter by (e.g., `pdf`, `doc`) |
| `intitle`  | string | Term that must appear in the page title          |
| `inurl`    | string | Term that must appear in the page URL            |
| `intext`   | string | Term that must appear in the page body           |

## Behavior parameters

| Parameter        | Type    | Default | Description                                                              |
| ---------------- | ------- | ------- | ------------------------------------------------------------------------ |
| `noCache`        | boolean | `false` | Bypass cached results                                                    |
| `parseOperators` | boolean | `true`  | Parse [query operators](/features/query-operators) from the query string |

## Examples

### Paginated search

```bash theme={null}
# First page
curl "https://search-api.andisearch.com/api/v1/search?q=machine+learning&limit=10" \
  -H "x-api-key: YOUR_API_KEY"

# Second page
curl "https://search-api.andisearch.com/api/v1/search?q=machine+learning&limit=10&offset=10" \
  -H "x-api-key: YOUR_API_KEY"
```

### Deep search with extracts

```bash theme={null}
curl "https://search-api.andisearch.com/api/v1/search?q=climate+change+effects&depth=deep&extracts=true" \
  -H "x-api-key: YOUR_API_KEY"
```

### Filtered by date and domain

```bash theme={null}
curl "https://search-api.andisearch.com/api/v1/search?q=product+launch&dateRange=month&includeDomains=techcrunch.com,theverge.com" \
  -H "x-api-key: YOUR_API_KEY"
```

### Multi-query search

```bash theme={null}
curl -G "https://search-api.andisearch.com/api/v1/search" \
  --data-urlencode 'q=["artificial intelligence", "machine learning"]' \
  -H "x-api-key: YOUR_API_KEY"
```


# Response format
Source: https://docs.andiai.com/features/response-format

Structure of the Andi AI Search API response, including result types and instant answers.

All responses are JSON objects. The `format=context` option returns markdown text instead — see [query parameters](/features/query-parameters) for details.

## Top-level fields

| Field              | Type   | Always present | Description                                                         |
| ------------------ | ------ | -------------- | ------------------------------------------------------------------- |
| `results_type`     | string | Yes            | Category of results (e.g., `search`, `news`, `images`)              |
| `answer`           | string | Yes            | Generated answer for the query (may be empty)                       |
| `type`             | string | Yes            | Same as `results_type`                                              |
| `title`            | string | Yes            | Title summarizing the search results                                |
| `results`          | array  | Yes            | Search results                                                      |
| `metrics`          | object | Yes            | Search performance metrics                                          |
| `correctedQuery`   | string | No             | Spell-corrected query (deep search only, when a correction is made) |
| `related_searches` | array  | No             | Related search suggestions                                          |
| `topics`           | array  | No             | Related topics                                                      |

### Type-specific arrays

Depending on the query intent, the response may include additional arrays alongside `results`:

| Field       | Present when              |
| ----------- | ------------------------- |
| `videos`    | Video intent queries      |
| `images`    | Image intent queries      |
| `news`      | News intent queries       |
| `places`    | Location/business queries |
| `profiles`  | People-related queries    |
| `socials`   | Social media queries      |
| `academics` | Scholarly queries         |

## Search results

Each result in the `results` array has this structure:

| Field         | Type   | Always present | Description                                                        |
| ------------- | ------ | -------------- | ------------------------------------------------------------------ |
| `title`       | string | Yes            | Page title                                                         |
| `link`        | string | Yes            | Page URL                                                           |
| `desc`        | string | Yes            | Page description or summary                                        |
| `source`      | string | Yes            | Domain name                                                        |
| `type`        | string | Yes            | Result type (see [result types](#result-types))                    |
| `date`        | string | No             | Publication date                                                   |
| `image`       | string | No             | Preview image URL                                                  |
| `snippet`     | string | No             | Query-relevant text excerpt (distinct from `desc`)                 |
| `answer`      | string | No             | Inline answer for instant answer results                           |
| `extracts`    | array  | No             | Text extracts from the page, when available (when `extracts=true`) |
| `contentType` | string | No             | Content type (when `metadata=full`)                                |
| `reader`      | object | No             | Extracted page content (when `metadata=full`)                      |

## Result types

The `type` field indicates the kind of result:

| Type             | Description                      |
| ---------------- | -------------------------------- |
| `website`        | Standard web page                |
| `news`           | News article                     |
| `video`          | Video content                    |
| `image`          | Image content                    |
| `place`          | Business or place                |
| `profile`        | Person or entity profile         |
| `social`         | Social media content             |
| `academic`       | Scholarly or research content    |
| `calculation`    | Math computation result          |
| `weather`        | Weather data                     |
| `computation`    | Computed answer                  |
| `instant answer` | Direct answer to a factual query |

## Instant answers

Some queries trigger instant answers alongside regular results.

### Weather

Queries about weather return a `weather` object:

```json theme={null}
{
  "results_type": "weather",
  "answer": "",
  "type": "weather",
  "title": "Weather in San Francisco",
  "results": [],
  "weather": {
    "location": {
      "name": "San Francisco",
      "country": "US",
      "coordinates": {
        "latitude": 37.7749,
        "longitude": -122.4194
      }
    },
    "temperature": 62,
    "feelsLike": 59,
    "units": "imperial",
    "description": "Partly Cloudy",
    "humidity": 72,
    "windSpeed": 12,
    "windDirection": 270,
    "pressure": 1013,
    "icon": "partly-cloudy",
    "cloudiness": 40,
    "visibility": 10000,
    "timestamp": "2025-03-15T14:00:00Z"
  },
  "metrics": {
    "query": "weather san francisco",
    "intent": "WeatherIntent",
    "timestamp": "2025-03-15T14:00:01Z",
    "duration": 850,
    "queries_executed": 1,
    "api_requests_count": 2,
    "results_returned": 0,
    "total_results_found": 0
  }
}
```

Use the `units` parameter to get results in `metric` or `imperial`. The default is auto-detected from the `country` parameter.

### Calculation

Mathematical queries return a `calculation` object:

```json theme={null}
{
  "results_type": "computation",
  "answer": "",
  "type": "computation",
  "title": "150 * 1.08",
  "results": [],
  "calculation": {
    "expression": "150 * 1.08",
    "result": "162"
  },
  "metrics": { ... }
}
```

### Images

Image queries return an `images` array:

```json theme={null}
{
  "results_type": "images",
  "answer": "",
  "type": "images",
  "title": "Mountain landscape images",
  "results": [],
  "images": [
    {
      "title": "Mountain landscape",
      "link": "https://example.com/photo",
      "image": "https://example.com/photo.jpg",
      "source": "example.com",
      "type": "image",
      "thumbnail": "https://example.com/photo_thumb.jpg",
      "width": "1920",
      "height": "1080"
    }
  ],
  "metrics": { ... }
}
```

Image results include `thumbnail` (thumbnail URL), `width`, and `height` as string values.

## Search intents

The `results_type` and `type` fields reflect what kind of search was performed. You can force an intent with the `intent` parameter, or let the API auto-detect it.

Common intent aliases:

| Alias       | Intent              | Extra fields  |
| ----------- | ------------------- | ------------- |
| `search`    | General web search  | —             |
| `news`      | News articles       | `news`        |
| `video`     | Video content       | `videos`      |
| `images`    | Image search        | `images`      |
| `weather`   | Weather queries     | `weather`     |
| `calculate` | Math expressions    | `calculation` |
| `wiki`      | Wikipedia/knowledge | —             |
| `code`      | Programming queries | —             |
| `recipe`    | Recipe search       | —             |
| `place`     | Business search     | `places`      |
| `time`      | Time queries        | —             |

See [query parameters](/features/query-parameters#intent-values) for the full list of intent aliases.

## Metrics

The response always includes a `metrics` object with search performance data:

```json theme={null}
{
  "results": [...],
  "metrics": {
    "query": "machine learning",
    "intent": "FallbackSearchIntent",
    "timestamp": "2025-03-15T14:00:01Z",
    "duration": 234,
    "queries_executed": 1,
    "api_requests_count": 3,
    "results_returned": 10,
    "total_results_found": 42
  }
}
```

| Field                 | Type    | Description                                                  |
| --------------------- | ------- | ------------------------------------------------------------ |
| `query`               | string  | The query as processed                                       |
| `intent`              | string  | Detected or forced search intent                             |
| `timestamp`           | string  | Timestamp of the request                                     |
| `duration`            | number  | Total request time in milliseconds                           |
| `queries_executed`    | integer | Number of queries executed                                   |
| `api_requests_count`  | integer | Number of API requests made                                  |
| `results_returned`    | integer | Results returned in this response                            |
| `total_results_found` | integer | Total results found across sources                           |
| `cached`              | boolean | Whether response was from cache (only present on cache hits) |


# Authentication
Source: https://docs.andiai.com/getting-started/authentication

Authenticate with the Andi AI Search API using API keys in the x-api-key header.

Every request to the Andi AI Search API must include an API key in the `x-api-key` header.

<Snippet />

## Getting an API key

1. Sign in to the [API Console](https://console.andiai.com)
2. Go to **API Keys**
3. Click **Create Key**
4. Copy the key — it's only shown once

## Managing keys

The API Console lets you:

* **Create** multiple keys for different applications or environments
* **Rename** keys to identify their purpose
* **Enable/disable** keys without deleting them
* **Revoke** keys that are no longer needed

Each key tracks its own usage. You can monitor request counts and credit consumption per key in the console.

## Security practices

<Warning>
  Treat API keys like passwords. Never commit them to version control or expose them in client-side code.
</Warning>

* Store keys in environment variables or a secrets manager
* Use separate keys for development and production
* Rotate keys periodically
* Revoke keys immediately if compromised
* Restrict key access to team members who need it

```bash theme={null}
# Store your key in an environment variable
export ANDI_API_KEY="your-api-key"

# Reference it in requests
curl "https://search-api.andisearch.com/api/v1/search?q=test" \
  -H "x-api-key: $ANDI_API_KEY"
```


# Quickstart
Source: https://docs.andiai.com/getting-started/quickstart

Make your first Andi AI Search API call in minutes.

<Info>You need an API key to follow this guide. Get one from the [API Console](https://console.andiai.com).</Info>

<Steps>
  <Step title="Get your API key">
    Sign in to the [API Console](https://console.andiai.com) and create an API key. Copy it — you'll need it for the next step.
  </Step>

  <Step title="Make your first request">
    Send a search query using the `x-api-key` header:

    <CodeGroup>
      ```bash curl theme={null}
      curl "https://search-api.andisearch.com/api/v1/search?q=what+is+RAG" \
        -H "x-api-key: YOUR_API_KEY"
      ```

      ```python Python theme={null}
      import requests

      response = requests.get(
          "https://search-api.andisearch.com/api/v1/search",
          params={"q": "what is RAG"},
          headers={"x-api-key": "YOUR_API_KEY"}
      )

      data = response.json()
      for result in data["results"]:
          print(result["title"], result["link"])
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch(
        "https://search-api.andisearch.com/api/v1/search?q=what+is+RAG",
        { headers: { "x-api-key": "YOUR_API_KEY" } }
      );

      const data = await response.json();
      data.results.forEach(r => console.log(r.title, r.link));
      ```
    </CodeGroup>
  </Step>

  <Step title="Read the response">
    The API returns a JSON object with top-level fields and a `results` array. Each result includes a `title`, `link`, `desc`, and `source`:

    ```json theme={null}
    {
      "results_type": "search",
      "answer": "",
      "type": "search",
      "title": "what is RAG",
      "results": [
        {
          "title": "Retrieval-Augmented Generation (RAG) Explained",
          "link": "https://example.com/rag-explained",
          "desc": "RAG combines a retrieval system with a language model to generate responses grounded in retrieved documents.",
          "source": "example.com",
          "type": "website"
        }
      ],
      "metrics": {
        "query": "what is RAG",
        "intent": "FallbackSearchIntent",
        "duration": 234,
        "results_returned": 10,
        "total_results_found": 42
      }
    }
    ```
  </Step>
</Steps>

## Next steps

<CardGroup>
  <Card title="Fast search" icon="bolt" href="/search/fast-search">
    Default search mode for real-time applications.
  </Card>

  <Card title="Deep search" icon="microscope" href="/search/deep-search">
    Enhanced search with spell correction and more sources.
  </Card>

  <Card title="Query parameters" icon="sliders" href="/features/query-parameters">
    Full parameter reference for the search endpoint.
  </Card>

  <Card title="Authentication" icon="key" href="/getting-started/authentication">
    API key management and security practices.
  </Card>
</CardGroup>


# Andi AI Search API
Source: https://docs.andiai.com/index

Web search API for AI agents, RAG pipelines, and search applications. Structured, accurate results from a large-scale web index.

The Andi AI Search API gives your applications access to web search results scored for accuracy and relevance, drawn from a large-scale index. Responses are structured for direct use in AI agents, RAG pipelines, and search interfaces — ranked #1 for accuracy in independent benchmarks.

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/getting-started/quickstart">
    Make your first API call in minutes.
  </Card>

  <Card title="Fast search" icon="bolt" href="/search/fast-search">
    Default mode — results in \~1 second.
  </Card>

  <Card title="Deep search" icon="microscope" href="/search/deep-search">
    Enhanced analysis with more sources.
  </Card>

  <Card title="Build with AI agents" icon="robot" href="/resources/ai-agents">
    MCP server, llms.txt, and markdown access.
  </Card>
</CardGroup>

## Base URL

```text theme={null}
https://search-api.andisearch.com
```

## Authentication

All requests require an API key passed in the `x-api-key` header. Get your key from the [API Console](https://console.andiai.com).

```bash theme={null}
curl "https://search-api.andisearch.com/api/v1/search?q=hello+world" \
  -H "x-api-key: YOUR_API_KEY"
```

## What you can build

* **AI agents** that retrieve current information from the web
* **RAG applications** with real-time search grounding
* **Research tools** that gather and synthesize web sources
* **Search features** embedded in your own products


# Build with AI agents
Source: https://docs.andiai.com/resources/ai-agents

Connect AI agents to the Andi docs via MCP, llms.txt, and markdown content negotiation. Optimized for Claude Code, Cursor, VS Code, and other AI tools.

This documentation site is built for AI agents. Every page is available as clean markdown, and the site exposes an MCP server and llms.txt for programmatic discovery.

## MCP server

The docs site runs a [Model Context Protocol](https://modelcontextprotocol.io/) server that lets AI tools search and read documentation directly.

**Server URL:** `https://docs.andiai.com/mcp`

### Claude Code

```bash theme={null}
claude mcp add andi-docs --transport streamable-http https://docs.andiai.com/mcp
```

### Claude web and desktop

Add this to your MCP server settings:

```json theme={null}
{
  "mcpServers": {
    "andi-docs": {
      "url": "https://docs.andiai.com/mcp"
    }
  }
}
```

### Cursor

Add to your `.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "andi-docs": {
      "url": "https://docs.andiai.com/mcp"
    }
  }
}
```

### VS Code

Add to your VS Code settings (JSON):

```json theme={null}
{
  "mcp": {
    "servers": {
      "andi-docs": {
        "type": "http",
        "url": "https://docs.andiai.com/mcp"
      }
    }
  }
}
```

## llms.txt

The site publishes [llms.txt](https://llmstxt.org/) files that list all documentation pages with direct markdown URLs.

| File                                                      | Contents                                         |
| --------------------------------------------------------- | ------------------------------------------------ |
| [`/llms.txt`](https://docs.andiai.com/llms.txt)           | Page titles and descriptions with markdown links |
| [`/llms-full.txt`](https://docs.andiai.com/llms-full.txt) | Full page content inlined as markdown            |

Use `/llms.txt` for discovery and navigation. Use `/llms-full.txt` when you need the complete documentation in a single request.

## Markdown content negotiation

Any docs page returns clean markdown when requested with the `Accept: text/markdown` header. The markdown response is \~30x smaller than HTML and includes YAML frontmatter.

```bash theme={null}
curl -H "Accept: text/markdown" https://docs.andiai.com/getting-started/quickstart
```

The response includes headers for automated discovery:

* `Link` headers pointing to `/llms.txt` and `/llms-full.txt`
* `X-Llms-Txt` header with the llms.txt URL

## LLM-ready search responses

The Search API supports a `format=context` parameter that returns results as markdown optimized for LLM context windows. See [response format](/features/response-format) for details.

## AI crawler access

The site's `robots.txt` explicitly allows AI crawlers including GPTBot, ClaudeBot, and PerplexityBot.


# Error handling
Source: https://docs.andiai.com/resources/error-handling

Error response format, status codes, and retry strategies for the Andi AI Search API.

When a request fails, the API returns an error response with an HTTP status code and a JSON body describing the problem.

## Error response format

All errors return both an `error` field and a `message` field:

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid API key"
}
```

## Status codes

| Code  | Error                   | Message                                                                  | Description                                                                         |
| ----- | ----------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| `400` | Varies                  | Varies                                                                   | Missing or invalid parameters. Check the `error` field for details.                 |
| `401` | `Unauthorized`          | `Missing x-api-key header` or `Invalid API key`                          | Missing or invalid API key. Verify your `x-api-key` header.                         |
| `402` | `Insufficient Credits`  | `Your account has insufficient credits. Please add credits to continue.` | Account balance depleted. [Add credits](https://console.andiai.com) to continue.    |
| `429` | `Too Many Requests`     | `Rate limit of N requests per second exceeded`                           | Too many requests. Back off and retry after the period in the `Retry-After` header. |
| `500` | `Internal server error` | Varies                                                                   | Something went wrong on our end. Retry with backoff.                                |

## Handling errors

Check the HTTP status code before parsing the response body:

```python theme={null}
import requests

response = requests.get(
    "https://search-api.andisearch.com/api/v1/search",
    params={"q": "test"},
    headers={"x-api-key": "YOUR_API_KEY"}
)

if response.status_code == 200:
    data = response.json()
elif response.status_code == 429:
    retry_after = response.headers.get("Retry-After", 1)
    print(f"Rate limited. Retry after {retry_after} seconds.")
elif response.status_code == 402:
    print("Out of credits. Add credits at console.andiai.com")
else:
    error = response.json()
    print(f"Error {response.status_code}: {error['error']}")
```

## Retry strategy

For transient errors (`429`, `500`), use exponential backoff:

1. Wait 1 second after the first failure
2. Double the wait time on each subsequent retry
3. Cap at 60 seconds
4. Stop after 5 retries

<Warning>
  Do not retry `400`, `401`, or `402` errors — these indicate problems that won't resolve by retrying. Fix the request or account issue first.
</Warning>

For `429` responses, prefer the `Retry-After` header value over your own backoff timer if it's present.


# Rate limits
Source: https://docs.andiai.com/resources/rate-limits

Rate limit configuration and handling for the Andi AI Search API.

Rate limits control how many requests an API key can make within a time window. They protect the service and ensure fair usage across all consumers.

## Default limits

Rate limits are configured per API key through the [API Console](https://console.andiai.com). Limits use a per-second sliding window. The default limit is set when you create a key and can be adjusted based on your needs.

<Info>
  Contact [support](mailto:hello+api@andiai.com) if you need higher rate limits than what's available in the console.
</Info>

## Rate limit headers

The API includes rate limit headers on every response:

| Header                  | Description                                               |
| ----------------------- | --------------------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed per second                       |
| `X-RateLimit-Remaining` | Requests remaining in the current window                  |
| `X-RateLimit-Reset`     | Unix timestamp (seconds) when the window resets           |
| `Retry-After`           | Seconds to wait before retrying (only on `429` responses) |

## Handling 429 responses

When you exceed your rate limit, the API returns a `429` status code:

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit of N requests per second exceeded"
}
```

Use the rate limit headers to monitor usage and the `Retry-After` header to pace retries:

```python theme={null}
import time
import requests

response = requests.get(
    "https://search-api.andisearch.com/api/v1/search",
    params={"q": "test"},
    headers={"x-api-key": "YOUR_API_KEY"}
)

# Check remaining quota on any response
remaining = int(response.headers.get("X-RateLimit-Remaining", 0))

if response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", 1))
    time.sleep(retry_after)
    # Retry the request
```

## Monitoring usage

Use the `X-RateLimit-Remaining` header to track how close you are to your limit in real time. For aggregate usage and credit consumption, see the [API Console](https://console.andiai.com).


# Deep search
Source: https://docs.andiai.com/search/deep-search

Enhanced search mode with spell correction, more sources, and deeper analysis in ~2–3 seconds.

Deep search provides enhanced analysis with spell correction, broader source coverage, and more detailed results. Responses take approximately 2–3 seconds.

Enable deep search by setting `depth=deep`:

<CodeGroup>
  ```bash curl theme={null}
  curl "https://search-api.andisearch.com/api/v1/search?q=quantm+computing+applications&depth=deep" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://search-api.andisearch.com/api/v1/search",
      params={"q": "quantm computing applications", "depth": "deep"},
      headers={"x-api-key": "YOUR_API_KEY"}
  )
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://search-api.andisearch.com/api/v1/search?q=quantm+computing+applications&depth=deep",
    { headers: { "x-api-key": "YOUR_API_KEY" } }
  );
  ```
</CodeGroup>

<Note>
  The example query intentionally misspells "quantum" — deep search corrects it automatically.
</Note>

## What deep search adds

* **Spell correction** — fixes typos and misspellings in the query
* **Extended source coverage** — searches a broader set of sources
* **Enhanced analysis** — applies deeper relevance scoring to results

## When to use deep search

* Research queries where completeness matters
* Queries from user input that may contain typos
* Applications that prioritize result quality over speed
* Complex or multi-faceted topics

## Example response

```json theme={null}
{
  "results_type": "search",
  "answer": "",
  "type": "search",
  "title": "quantum computing applications",
  "results": [
    {
      "title": "Quantum Computing: Current Applications and Future Potential",
      "link": "https://example.com/quantum-applications",
      "desc": "Quantum computing is being applied in cryptography, drug discovery, and optimization problems...",
      "source": "example.com",
      "type": "website"
    }
  ],
  "correctedQuery": "quantum computing applications",
  "metrics": {
    "query": "quantum computing applications",
    "intent": "FallbackSearchIntent",
    "duration": 2340,
    "results_returned": 10,
    "total_results_found": 85
  }
}
```

Note that the `correctedQuery` field shows the corrected spelling.


# Fast search
Source: https://docs.andiai.com/search/fast-search

Default search mode optimized for speed, returning results in ~1 second.

Fast search is the default mode. It returns results in approximately 1 second, making it suitable for real-time applications and high-volume workloads.

<CodeGroup>
  ```bash curl theme={null}
  curl "https://search-api.andisearch.com/api/v1/search?q=latest+AI+news" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://search-api.andisearch.com/api/v1/search",
      params={"q": "latest AI news"},
      headers={"x-api-key": "YOUR_API_KEY"}
  )
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://search-api.andisearch.com/api/v1/search?q=latest+AI+news",
    { headers: { "x-api-key": "YOUR_API_KEY" } }
  );
  ```
</CodeGroup>

Fast search is the default — no `depth` parameter is needed. Setting `depth=fast` explicitly has the same effect.

## When to use fast search

* Real-time search in user-facing applications
* High-volume automated queries
* AI agents that need quick answers
* Applications where latency matters more than exhaustive coverage

## Example response

```json theme={null}
{
  "results_type": "news",
  "answer": "",
  "type": "news",
  "title": "latest AI news",
  "results": [
    {
      "title": "Latest AI News and Developments",
      "link": "https://example.com/ai-news",
      "desc": "A roundup of the latest developments in artificial intelligence...",
      "source": "example.com",
      "type": "news"
    }
  ],
  "metrics": {
    "query": "latest AI news",
    "intent": "LatestNewsIntent",
    "duration": 890,
    "results_returned": 10,
    "total_results_found": 50
  }
}
```

## Fast search vs. deep search

|                  | Fast search | Deep search   |
| ---------------- | ----------- | ------------- |
| Response time    | \~1 second  | \~2–3 seconds |
| Spell correction | No          | Yes           |
| Source coverage  | Standard    | Extended      |
| Analysis depth   | Standard    | Enhanced      |

<Tip>
  Start with fast search. Switch to deep search only when you need spell correction, broader coverage, or enhanced analysis.
</Tip>