Cormorant API v1
Search and fetch the web from your code and your agents.
One API for web search with automatic fallback, and for fetching pages, PDFs and documents through a ladder of tiers that escalates only when a site blocks — cached, with the exact bytes, and with the cost of every request.
QuickstartAPI referenceFor AI agents
Base URLhttps://api.cormorant.ch
POST /v1/fetch
Authorization: Bearer cmr_…
{"url": "https://example.com/report.pdf"}
200 OK
{
"tier": "direct",
"content_kind": "pdf",
"text": "Annual Report 2025\n\n…",
"body_url": "…/v1/bodies/a3f1…",
"cached": false,
"cost_usd": 0.0,
"error": null
}
- Get startedQuickstartYour first search and fetch in two minutes, in curl, Python and TypeScript.
- Get startedAuthentication & keysProject API keys, the Bearer header, rate limits and keeping keys safe.
- ReferenceInteractive API referenceEvery endpoint, field and error, with a built-in client to try requests with your key.
- GuidesSync vs batchWhen to use which, job lifecycle, paging results, callbacks and idempotency.
- GuidesFetching in depthTiers and escalation, text and exact bytes, content kinds, cache and per-request controls.
- GuidesSearch in depthProviders, fallback rules, merged snippets and engines, caching and freshness.
- GuidesErrors & retriesEvery error code, which ones to retry, and how to back off.
- GuidesLimits & politenessRate limits, robots.txt, per-domain politeness and what they mean for throughput.
- GuidesMonitoring & statusWatch Cormorant's health from your systems: the status API, polling and alert rules.
- GuidesCosts & billingWhat costs money, how to keep it at zero, budgets, usage, your plan and invoices.
- GuidesUsage, spending and quotasUsage and charges per key, project and day, the request ledger, CSV exports, limits, quotas and alerts.
- Company dataCompany dataThe company register: records with provenance, refresh on request, search, resolve, history and batch.
- Company dataThe company/v1 recordEvery field, claims and provenance, identifier schemes, legal forms, activities.
- Company dataCompany data sourcesSources by country, precedence, freshness classes, licences and health.
- Company dataSwitzerlandSwiss sources (Zefix, UID register, SOGC, cantonal excerpts): fields, identifiers, officers, freshness and activating Zefix REST.
- Company dataChange feeds and watchesFollow register changes with the change feed or signed webhooks.
- AgentsUsing Cormorant from AI agentsPatterns for agents: batch for many URLs, prefer text, small responses, polite retries.
- AgentsMCP serverCormorant as MCP tools for Claude and other MCP clients.
- ReferenceAPI contractThe canonical v1 contract: every endpoint, field and behaviour in one page.
- ReferenceChangelogWhat changed in the API, newest first.
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.
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.
Where next#
View as Markdown
