# 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.183.

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`, ...).
JSON results carry `date` (publication date) and, when the publisher declares a
verified later substantive update, an optional `dateModified` — never a
substitute for `date`.

### 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`, optional `date_modified`,
`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. Choose which arrays you get with `types`.

### Agent-first results (`metadata=agent`)

You're reading this because you're an agent — so results already come back agent-ready.
Requests via MCP, the CLI, or `format=context` get this automatically; a plain JSON caller
can ask for it with `metadata=agent`. What changes:

- Each result may carry a compact `agent` object: which `.md` version of that page exists,
  the llms.txt index covering its path (with the links matching your query), the site's
  permissions for AI use, and the origin it belongs to — plus a `quickstart` summary
  (MCP URL, install command, docs link) computed with no extra fetch.
- Top-level `extracts` (query-relevant passages) is on by default for agent requesters.
- Three extra arrays group agent-relevant results the same way `news`/`videos` do:
  `tools`, `docs`, `agents`. `agents` holds one entry per site in the results that
  publishes anything for agents: the ranked result itself, in the ordinary result shape, plus
  that site's FULL catalogue — llms.txt tree, MCP server card, OpenAPI/API catalog, skills,
  install and auth guides, permissions and sitemaps — so you never fetch them yourself.
- `metadata=agent` also keeps a small `reader` object per result and never page bodies
  unless you ask for `content=true`. It carries what the page itself states in structured
  data: word count and access class, authors, keywords, alternate formats (including the
  `.md` twin), FAQs, listing items with ratings, how-to steps, breadcrumbs, `sameAs` links
  and named entities.
- With `extracts=true` (the default for agent requests) each site's own agent files —
  llms.txt, install.md, skills — come back with query-relevant passages of their own, and with
  `content=true` with their full markdown, inside the `agents` entry for that site. Ask for
  neither and those files stay listed but empty.
- In `format=context`, an `<agent_index>` block appears once near the top of the response
  (one line per site in `agents`, plus each requested file's passages and body), and a
  per-result `<agent>` block appears after `<extracts>` with that page's own agent facts.
  Articles carry the full frontmatter, and `<faq>`, `<items>` and `<breadcrumbs>` blocks
  render the page's structured data.

Requests via MCP, the CLI, `format=context`, `Accept: text/markdown`,
`intent=AgentToolsIntent` or a `types` value naming `tools`/`docs`/`agents` are agent
requests: `metadata` defaults to `agent` and the media arrays other than `images` come back
with the items already in `results` removed. A plain JSON caller's response shape is
unchanged.

## 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` | default `auto` determines what each query needs (compute, models, depth) — recommended for most agents. Pin a mode only for explicit control: `fast` ~1s; `deep` ~2-3s adds spell correction + wider source coverage; `exhaustive` multi-round (up to ~15s) |
| `effort` | `low` \| `medium` \| `high` \| `max` | thoroughness dial — an alternative to pinning `searchMode`; omit for adaptive default |
| `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 |
| `types` | comma-separated: `web`, `news`, `videos`, `images`, `social`, `academic`, `places`, `profiles`, `tools`, `docs`, `agents`, `all` | which result arrays come back. Shapes the response only — never which sources run or how results rank. Omit `web` for an empty `results`. Naming `tools`/`docs`/`agents` makes it an agent request |
| `metadata` | `basic` \| `full` \| `agent` | `agent` adds the agent objects and a compact `reader`; defaults to `agent` on agent requests |

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
- Skills + plugins repo (Claude Code marketplace, Codex plugin): https://github.com/andisearch/andi-agent-skills
- 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/