# Cormorant

> Cormorant is a web search and fetch API for research projects and AI agents: SearXNG-first search with a Brave fallback, and page/PDF/document fetching through a ladder of tiers (HTTP with a browser fingerprint, a real browser, an archived copy, paid proxies only when blocked), with a shared cache, exact bytes, batch jobs of up to 50,000 items and per-request cost reporting.

- Base URL: `https://cormorant.ch`. Every `/v1` request needs `Authorization: Bearer cmr_…` (a project
  key issued by the operator; `cma_…` is an account admin key, see the response header
  `X-Cormorant-Key-Role`), except the public service status `GET /v1/status`.
- `POST /v1/search` and `POST /v1/fetch` are synchronous (wait up to 150 s). For more than
  ~20 items use `POST /v1/batch/search` or `POST /v1/batch/fetch` and poll
  `GET /v1/jobs/{job_id}?include=items`.
- Fetch failures are HTTP 200 with `error` set; HTTP errors (401/403/404/409/413/422/429/
  503/504) are about the request itself. Retry only transient errors, with backoff.
- `error: domain_unavailable` comes with `retry_after_s`: do not request that domain
  again before then.
- Prefer `text` over `html` (`include_html: false`) and download the exact bytes from
  `body_url` only when you need them.
- SEC EDGAR: use `/v1/sec/...` (resolve, submissions, filings/latest, filing index,
  documents/fetch, facts, search). Never send your own User-Agent for SEC: Cormorant
  sends its declared identity and shares SEC's rate limit across all clients; honour
  `retry_after_s` on `rate_limited` / `sec_unavailable`.
- MCP server for agents: see the MCP page below.

## Get started

- [Overview](https://cormorant.ch/docs/overview.md): What Cormorant does, the base URL, and the concepts you need.
- [Quickstart](https://cormorant.ch/docs/quickstart.md): Your first search and fetch in two minutes, in curl, Python and TypeScript.
- [Authentication & keys](https://cormorant.ch/docs/authentication.md): Project API keys, the Bearer header, rate limits and keeping keys safe.

## Guides

- [Sync vs batch](https://cormorant.ch/docs/sync-vs-batch.md): When to use which, job lifecycle, paging results, callbacks and idempotency.
- [Fetching in depth](https://cormorant.ch/docs/fetching.md): Tiers and escalation, text and exact bytes, content kinds, cache and per-request controls.
- [Search in depth](https://cormorant.ch/docs/search.md): Providers, fallback rules, merged snippets and engines, caching and freshness.
- [Errors & retries](https://cormorant.ch/docs/errors.md): Every error code, which ones to retry, and how to back off.
- [Limits & politeness](https://cormorant.ch/docs/limits.md): Rate limits, robots.txt, per-domain politeness and what they mean for throughput.
- [Monitoring & status](https://cormorant.ch/docs/monitoring.md): Watch Cormorant's health from your systems: the status API, polling and alert rules.
- [SEC EDGAR via Cormorant](https://cormorant.ch/docs/sec-edgar.md): Company and filing data from SEC EDGAR: resolve, filings, latest annual report, documents, facts and search under SEC's fair-access rules.
- [Costs & billing](https://cormorant.ch/docs/billing.md): What costs money, how to keep it at zero, budgets, usage, your plan and invoices.
- [Usage, spending and quotas](https://cormorant.ch/docs/usage.md): Usage and charges per key, project and day, the request ledger, CSV exports, limits, quotas and alerts.

## Company data

- [Company data](https://cormorant.ch/docs/companies.md): The company register: records with provenance, refresh on request, search, resolve, history and batch.
- [The company/v1 record](https://cormorant.ch/docs/companies-model.md): Every field, claims and provenance, identifier schemes, legal forms, activities.
- [Company data sources](https://cormorant.ch/docs/companies-sources.md): Sources by country, precedence, freshness classes, licences and health.
- [Switzerland](https://cormorant.ch/docs/companies-switzerland.md): Swiss sources (Zefix, UID register, SOGC, cantonal excerpts): fields, identifiers, officers, freshness and activating Zefix REST.
- [Change feeds and watches](https://cormorant.ch/docs/companies-changes.md): Follow register changes with the change feed or signed webhooks.

## Agents

- [Using Cormorant from AI agents](https://cormorant.ch/docs/agents.md): Patterns for agents: batch for many URLs, prefer text, small responses, polite retries.
- [MCP server](https://cormorant.ch/docs/mcp.md): Cormorant as MCP tools for Claude and other MCP clients.

## Reference

- [OpenAPI 3.1 document](https://cormorant.ch/openapi.json): machine-readable schema of every endpoint, field and error
- [API contract](https://cormorant.ch/docs/api.md): The canonical v1 contract: every endpoint, field and behaviour in one page.

## Optional

- [All documentation in one file](https://cormorant.ch/llms-full.txt): every page below and above plus a compact endpoint reference
- [Changelog](https://cormorant.ch/docs/changelog.md): What changed in the API, newest first.