# Andi Search API

> Real-time web search for AI agents and apps, built on Andi's own index of tens of billions
> of pages. Returns ranked results, instant answers, and LLM-ready markdown. Version 1.6.142.

Trantora, Andi's index, scores pages for meaning, credibility, and quality at ingestion, so
results are ranked on what a page actually says rather than how well it is optimized. Beyond
the index, Andi predicts the right sources for a query and goes straight to them — vertical
searches and APIs such as GitHub or Wikipedia — with fallback web searches where our own
indexes do not have coverage.

Two ways to use it:

1. **In the agents and apps you build** — call the REST API below (search + fetch).
2. **In your own coding tools** (Claude Code, Cursor, Codex, or any MCP client) —
   connect the MCP server as a better web-search + page-fetch tool. See the MCP
   section below.

## Quick start

1. Get an API key: https://console.andiai.com/signup (free tier available)
2. Send it as the `x-api-key` header on every request.

```bash
curl "https://api.andiai.com/api/v1/search?q=your+query&format=context" \
  -H "x-api-key: YOUR_API_KEY"
```

`format=context` returns LLM-ready markdown. Omit it for structured JSON
(`results`, `answer`, `images`, `news`, `related_searches`, ...).

### format=context response contract (`andi-context/v1`)

Document YAML frontmatter: `format`, `query`, `results_count`, `timestamp`,
`intent`, `results_type`, `corrected_query` (spelling suggestion; deep-mode
searches may also retrieve results for it — otherwise results are ranked for
the original query), `related_searches`, `search_mode`,
`cost_dollars` (amount charged for THIS call), `cached` (+ `cache_age_seconds`
entry age on cache hits), `response_time_ms`.
Then one `<article source="domain" rank="N">` block per result: per-article
YAML frontmatter (`title`, `url`, `date`, `source`, `author`), description
body, and optional `**Answer:**`, `<infobox>`, `> snippet`, and
`<extracts>` blocks (query-relevant passages — on by default for
format=context; `extracts=false` opts out).
When the query surfaces them, trailing sections follow the articles —
`## Academic results`, `## News results`, `## Video results`,
`## Social results`, `## Place results`, `## Profile results` — each wrapping
a `<academic>`/`<news>`/`<videos>`/`<social>`/`<places>`/`<profiles>` list
whose items carry the same `title`, `url`, `date`, `source` field names, plus
a one-line `desc`. These are the markdown counterpart of the JSON
`academic`/`news`/`videos`/`social`/`places`/`profiles` arrays; items already
present as an article above are not repeated.

## Key parameters (GET https://api.andiai.com/api/v1/search)

| Param | Values | Notes |
|---|---|---|
| `q` | string | required; supports `site:`, `-term`, `filetype:` operators |
| `limit` | 1-100 | default 10 |
| `searchMode` | `auto` \| `fast` \| `low-cost` \| `balanced` \| `deep` \| `exhaustive` | cost/speed/coverage dial; default `auto`. `fast` ~1s; `deep` ~2-3s adds spell correction + wider source coverage; `exhaustive` multi-round (up to ~15s) |
| `depth` | `fast` \| `deep` | deprecated alias for `searchMode` (subset of its values); `searchMode` wins when both are set |
| `format` | `json` \| `context` | `context` = markdown for LLM consumption |
| `safe` | `off` \| `moderate` \| `strict` | safe search |
| `country` / `language` | ISO codes | localization |
| `dateRange` | `24h` `7d` `30d` `90d` `1y` | recency filter |
| `includeDomains` / `excludeDomains` | comma-separated | domain filters |

Full reference: https://docs.andiai.com/features/query-parameters

## Fetch a page (GET https://api.andiai.com/api/v1/fetch)

Read any web page as clean extracted content (the companion to search):

```bash
curl "https://api.andiai.com/api/v1/fetch?url=https%3A%2F%2Fexample.com%2Farticle&format=context" \
  -H "x-api-key: YOUR_API_KEY"
```

Params: `url` (required), `format` (`json` | `context`), `maxContentLength`.

## Curated news feeds (GET https://api.andiai.com/api/v1/news/:topic)

Ranked, freshly-reranked headlines for a topic — no query needed:

```bash
curl "https://api.andiai.com/api/v1/news/technology" \
  -H "x-api-key: YOUR_API_KEY"
```

Returns the standard JSON SERP plus a strictly date-descending `news` array.
Params: `limit` (1-50, default 20), `noCache`. An unknown topic returns 404
with the full `valid_topics` list — call it once to discover the slugs.

## Use Andi as your agent's web search tool (MCP)

Remote MCP server (Streamable HTTP), authenticated with the same `x-api-key` header:

```bash
claude mcp add --transport http andi https://api.andiai.com/mcp --header "x-api-key: YOUR_API_KEY"
```

(add `--scope user` for system-wide use across all projects)

Cursor (`.cursor/mcp.json` for the project, `~/.cursor/mcp.json` for system-wide):

```json
{ "mcpServers": { "andi": { "url": "https://api.andiai.com/mcp", "headers": { "x-api-key": "YOUR_API_KEY" } } } }
```

Codex CLI (`~/.codex/config.toml`; export `ANDI_API_KEY` in your shell):

```toml
[mcp_servers.andi]
url = "https://api.andiai.com/mcp"
env_http_headers = { "x-api-key" = "ANDI_API_KEY" }
```

Any other MCP client: streamable-http transport, URL `https://api.andiai.com/mcp`,
`x-api-key` header.

Tools: `andi_web_search` (web search, LLM-ready markdown) and `andi_fetch_url`
(read a specific web page as markdown).

## Resources

- One-step agent setup guide: https://api.andiai.com/install.md
- CLI: `npm install -g @andiai/cli` — search, fetch, and a local stdio MCP server from your terminal
- Documentation: https://docs.andiai.com
- OpenAPI spec: https://api.andiai.com/openapi.json
- Auth guide for agents: https://api.andiai.com/auth.md
- Installable Agent Skill (SKILL.md): https://api.andiai.com/.well-known/skills/andi-web-search/SKILL.md
- llms.txt: https://api.andiai.com/llms.txt
- API catalog (RFC 9727): https://api.andiai.com/.well-known/api-catalog
- integrations.json: https://api.andiai.com/.well-known/integrations.json
- Get an API key: https://console.andiai.com/signup
- Status: https://status.andiai.com/