# Overview

Cormorant is a web **search** and **fetch** API shared by research projects and
AI agents. You send a query or a URL; Cormorant does the hard parts — engines
that rate-limit, sites that block bots, PDFs, caching, politeness, cost
control — and answers with clean text, metadata and provenance.

## What you can do

| You want to… | Use | Typical latency |
|---|---|---|
| Find pages about a topic | `POST /v1/search` | 1–5 s (cache hit: ms) |
| Read one page, PDF or document | `POST /v1/fetch` | 0.5–15 s (cache hit: ms) |
| Search or fetch hundreds to 50,000 items | `POST /v1/batch/search`, `POST /v1/batch/fetch` | minutes, asynchronous |
| Get the exact bytes behind a fetch | `GET /v1/bodies/{sha256}` | streaming |
| See your plan, this month's estimate and invoices | `GET /v1/account`, `GET /v1/account/invoices` | ms |
| See requests, cache hits, spend and budget | `GET /v1/usage` | ms |

## Base URL and authentication

```text
https://api.cormorant.ch
```

Every `/v1` request carries your project's key:

```text
Authorization: Bearer cmr_…
```

Keys are issued by the operator, one project per key. See
[Authentication & keys](/docs/authentication.md).

## Concepts in one minute

- **Search** asks Cormorant's own SearXNG engines first and falls back to the
  paid Brave Search API only when they fail or find too little. Results from
  all engines are merged; no snippet is lost.
- **Fetch** climbs a ladder of **tiers** — `direct` (HTTP with a browser
  fingerprint), `browser` (real Chromium), `archive` (Wayback Machine), then
  the paid `proxy` and `proxy_render` — and escalates only when a site blocks.
  A page that is simply short never costs money.
- **The cache is shared** across projects: a page or search someone fetched
  recently is answered at once, for free.
- **Text first, bytes on demand.** `text` is the extracted main text; the exact
  retrieved bytes are one request away at `body_url`.
- **Every response says what it cost** (`cost_usd`) and carries a
  `request_id` you can quote to the operator.
- **Fetch problems are results, not HTTP errors.** `/v1/fetch` answers `200`
  with `error` set (for example `http_404` or `robots_disallowed`). HTTP error
  statuses mean something is wrong with the request itself (key, limits,
  validation, timeouts).

## Versioning

The API is `v1`. Within v1, fields are only ever **added** — nothing is renamed
or removed — so ignore fields you do not know. Changes are listed in the
[changelog](/docs/changelog.md).

## Where next

- [Quickstart](/docs/quickstart.md): a first search and fetch in two minutes.
- [Sync vs batch](/docs/sync-vs-batch.md): pick the right endpoint for your volume.
- [Using Cormorant from AI agents](/docs/agents.md) and the [MCP server](/docs/mcp.md).
- The [interactive API reference](/docs/reference) and the
  [API contract](/docs/api.md).