{"openapi":"3.1.0","info":{"title":"Cormorant API","summary":"Web search and fetch for research projects and AI agents.","description":"Cormorant is a web **search** and **fetch** API for research projects and AI agents.\nIt answers searches from its own SearXNG engines (with a Brave fallback) and fetches\npages, PDFs and other documents through a pipeline of routes — a shared cache, plain\nHTTP with a browser fingerprint, a headless browser, a residential network when a site\nblocks data-centre traffic, and archives and alternative copies — escalating only as far\nas a page needs. Every response says which route worked and how the call is billed.\n\n**Base URL:** `https://api.cormorant.ch` · **Auth:** `Authorization: Bearer cmr_…` (a standard\nkey) or `cma_…` (an account admin key); keys belong to a project and are issued by the\noperator. Authenticated responses carry `X-Cormorant-Key-Role`, the rate-limit headers\n`RateLimit-Policy` and `RateLimit`, and — when the key has limits —\n`X-Cormorant-Key-Budget-Remaining` and `X-Cormorant-Quota-Remaining`.\n**Debug requests** (available on request): with `X-Cormorant-Debug: 1`, a key the\noperator enabled for debugging gets `debug_url` in the answer of `POST /v1/search` and\n`POST /v1/fetch` — a link to the request's diagnostic record for support.\n\nUse the synchronous endpoints for a handful of requests and the **batch** endpoints for\nanything bigger (up to 50,000 items per job). Guides, examples and an MCP server for\nagents: [developer portal](/docs) · [llms.txt](/llms.txt).\n","version":"1.0.0","contact":{"name":"Cormorant developer portal","url":"https://api.cormorant.ch/docs"}},"servers":[{"url":"https://api.cormorant.ch","description":"Production"}],"paths":{"/v1/search":{"post":{"tags":["search"],"summary":"Search the web","description":"Runs a web search and waits for the answer (typically 1–5 s, up to 150 s).\n\nOrder: the shared search cache (7 days; `cache_ttl_s` sets the maximum\nacceptable age, `0` bypasses it) → Cormorant's SearXNG instances → the\nBrave Search API when SearXNG errors, times out, reports unresponsive\nengines or returns fewer than 3 usable results (`fallback_reason`).\nResults are deduplicated by normalised URL, keeping every snippet and\nengine. `cost_usd` is non-zero only when Brave was called. For many\nqueries use `POST /v1/batch/search`.","operationId":"search","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchBody"}}},"required":true},"responses":{"200":{"description":"Merged results; also returned (with `error`) when nothing was found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"invalid API key"}}}},"429":{"description":"A limit is reached. The project's rate limit (default 200 requests/s, one-second window; plain `detail`) or the key's own (`key_rate_limited`): retry after `Retry-After` (1 s). The key's monthly request quota (`key_quota_exhausted`) or spend cap (`key_budget_exhausted`): `Retry-After` is the time until the month resets; see `GET /v1/quota`.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policies (IETF draft): `\"project\";q=200;w=1` and, when the key has its own limit, `\"key\";q=10;w=1`.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window per policy: `\"project\";r=199;t=1`.","schema":{"type":"string"}}},"content":{"application/json":{"examples":{"rate_limited":{"summary":"Project rate limit","value":{"detail":"rate limit exceeded"}},"key_rate_limited":{"summary":"Key rate limit","value":{"detail":{"error":"key_rate_limited","message":"this API key may make 10 requests per second"}}},"key_quota_exhausted":{"summary":"Monthly request quota of the key used up","value":{"detail":{"error":"key_quota_exhausted","message":"this API key used its monthly fetch quota (100000 requests)","category":"fetch","limit":100000}}},"key_budget_exhausted":{"summary":"Monthly spend cap of the key reached","value":{"detail":{"error":"key_budget_exhausted","message":"this API key reached its monthly spend cap (50.00 USD)","limit":"50.00","currency":"USD"}}}}}}},"504":{"description":"No result within the synchronous wait (150 s, or `timeout_s` + 15 s). The request may still complete in the background; retry later (it is often a cache hit then) or use the batch endpoints.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"timeout","request_id":"req_6b1f2c0e9a7d4b5c8e3f1a2b3c4d5e6f"}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/fetch":{"post":{"tags":["fetch"],"summary":"Fetch a URL","description":"Fetches one URL and returns its text, metadata and provenance.\n\nA fresh entry of the shared page cache answers at once. Otherwise the\nladder runs: the standard routes `direct` (HTTP with a Chrome\nfingerprint) → `browser` (Chromium) → `archive` (Wayback Machine), then\nthe premium routes `proxy` (residential network) → `proxy_render`\n(rendering service), which are priced higher. It escalates only on\nblocking (403/429/451/5xx, bot challenges, network errors); thin text\nescalates `direct → browser` only.\nDefinitive answers such as 404 are returned as is (`error: http_404`).\n\n`text` is the retained main text (per page for PDFs in `pdf_text_pages`),\n`content_kind` classifies the document, and `body_url` downloads the exact\nbytes. Control cost and latency with `allow_premium`, `tiers` and `timeout_s`.","operationId":"fetch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FetchBody"}}},"required":true},"responses":{"200":{"description":"The fetch result. HTTP 200 also for unsuccessful fetches: check `error`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FetchResponse"}}}},"503":{"description":"`error: domain_busy`: the domain's polite slots are taken for longer than a synchronous call waits; retry after `Retry-After` / `retry_after_s` seconds, lower the parallelism per domain, or use a batch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FetchResponse"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"invalid API key"}}}},"403":{"description":"Not allowed: the key's customer account is suspended (`customer_suspended`, any `/v1` endpoint), a `user_agent` is not on the project's allowlist (`user_agent_not_allowed`, fetch endpoints), or the key may not use this category (`key_category_not_allowed`, search and fetch endpoints).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"examples":{"user_agent_not_allowed":{"summary":"User-Agent not on the project allowlist","value":{"detail":{"error":"user_agent_not_allowed","hint":"ask the operator to add this User-Agent to the project allowlist"}}},"customer_suspended":{"summary":"Account suspended","value":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}},"key_category_not_allowed":{"summary":"The key may not use this category","value":{"detail":{"error":"key_category_not_allowed","message":"this API key may not use fetch (allowed: search)"}}}}}}},"429":{"description":"A limit is reached. The project's rate limit (default 200 requests/s, one-second window; plain `detail`) or the key's own (`key_rate_limited`): retry after `Retry-After` (1 s). The key's monthly request quota (`key_quota_exhausted`) or spend cap (`key_budget_exhausted`): `Retry-After` is the time until the month resets; see `GET /v1/quota`.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policies (IETF draft): `\"project\";q=200;w=1` and, when the key has its own limit, `\"key\";q=10;w=1`.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window per policy: `\"project\";r=199;t=1`.","schema":{"type":"string"}}},"content":{"application/json":{"examples":{"rate_limited":{"summary":"Project rate limit","value":{"detail":"rate limit exceeded"}},"key_rate_limited":{"summary":"Key rate limit","value":{"detail":{"error":"key_rate_limited","message":"this API key may make 10 requests per second"}}},"key_quota_exhausted":{"summary":"Monthly request quota of the key used up","value":{"detail":{"error":"key_quota_exhausted","message":"this API key used its monthly fetch quota (100000 requests)","category":"fetch","limit":100000}}},"key_budget_exhausted":{"summary":"Monthly spend cap of the key reached","value":{"detail":{"error":"key_budget_exhausted","message":"this API key reached its monthly spend cap (50.00 USD)","limit":"50.00","currency":"USD"}}}}}}},"504":{"description":"No result within the synchronous wait (150 s, or `timeout_s` + 15 s). The request may still complete in the background; retry later (it is often a cache hit then) or use the batch endpoints.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"timeout","request_id":"req_6b1f2c0e9a7d4b5c8e3f1a2b3c4d5e6f"}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/batch/search":{"post":{"tags":["batch"],"summary":"Create a batch search job","description":"Queues up to 50,000 searches as one job and returns its `job_id` at once.\n\nItems run with the same logic as `POST /v1/search`, admitted fairly across\nrunning jobs and retried with backoff on transient problems. Poll\n`GET /v1/jobs/{job_id}` or pass `callback_url`. Re-posting the same\n`idempotency_key` returns the existing job instead of creating a new one.","operationId":"batchSearch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchSearchBody"}}},"required":true},"responses":{"202":{"description":"Job created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCreated"}}}},"200":{"description":"Existing job (same idempotency key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCreated"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"invalid API key"}}}},"409":{"description":"The `idempotency_key` was already used for a job of a different kind or size.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"idempotency_key already used for a different job"}}}},"413":{"description":"Too many items for one job (at most 50,000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"at most 50000 items per job"}}}},"429":{"description":"A limit is reached. The project's rate limit (default 200 requests/s, one-second window; plain `detail`) or the key's own (`key_rate_limited`): retry after `Retry-After` (1 s). The key's monthly request quota (`key_quota_exhausted`) or spend cap (`key_budget_exhausted`): `Retry-After` is the time until the month resets; see `GET /v1/quota`.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policies (IETF draft): `\"project\";q=200;w=1` and, when the key has its own limit, `\"key\";q=10;w=1`.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window per policy: `\"project\";r=199;t=1`.","schema":{"type":"string"}}},"content":{"application/json":{"examples":{"rate_limited":{"summary":"Project rate limit","value":{"detail":"rate limit exceeded"}},"key_rate_limited":{"summary":"Key rate limit","value":{"detail":{"error":"key_rate_limited","message":"this API key may make 10 requests per second"}}},"key_quota_exhausted":{"summary":"Monthly request quota of the key used up","value":{"detail":{"error":"key_quota_exhausted","message":"this API key used its monthly fetch quota (100000 requests)","category":"fetch","limit":100000}}},"key_budget_exhausted":{"summary":"Monthly spend cap of the key reached","value":{"detail":{"error":"key_budget_exhausted","message":"this API key reached its monthly spend cap (50.00 USD)","limit":"50.00","currency":"USD"}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/batch/fetch":{"post":{"tags":["batch"],"summary":"Create a batch fetch job","description":"Queues up to 50,000 fetches as one job and returns its `job_id` at once.\n\nItems run with the same logic as `POST /v1/fetch`. Admission is\ndomain-aware: a domain that dominates the batch drains at its polite rate\nwhile other domains proceed. Results are stored without HTML unless an\nitem sets `include_html: true`; the exact bytes stay available via\n`body_url`. A batch item blocked on the standard routes is retried once\nafter a cool-down before a premium route is used.","operationId":"batchFetch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchFetchBody"}}},"required":true},"responses":{"202":{"description":"Job created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCreated"}}}},"200":{"description":"Existing job (same idempotency key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCreated"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"invalid API key"}}}},"403":{"description":"Not allowed: the key's customer account is suspended (`customer_suspended`, any `/v1` endpoint), a `user_agent` is not on the project's allowlist (`user_agent_not_allowed`, fetch endpoints), or the key may not use this category (`key_category_not_allowed`, search and fetch endpoints).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"examples":{"user_agent_not_allowed":{"summary":"User-Agent not on the project allowlist","value":{"detail":{"error":"user_agent_not_allowed","hint":"ask the operator to add this User-Agent to the project allowlist"}}},"customer_suspended":{"summary":"Account suspended","value":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}},"key_category_not_allowed":{"summary":"The key may not use this category","value":{"detail":{"error":"key_category_not_allowed","message":"this API key may not use fetch (allowed: search)"}}}}}}},"409":{"description":"The `idempotency_key` was already used for a job of a different kind or size.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"idempotency_key already used for a different job"}}}},"413":{"description":"Too many items for one job (at most 50,000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"at most 50000 items per job"}}}},"429":{"description":"A limit is reached. The project's rate limit (default 200 requests/s, one-second window; plain `detail`) or the key's own (`key_rate_limited`): retry after `Retry-After` (1 s). The key's monthly request quota (`key_quota_exhausted`) or spend cap (`key_budget_exhausted`): `Retry-After` is the time until the month resets; see `GET /v1/quota`.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policies (IETF draft): `\"project\";q=200;w=1` and, when the key has its own limit, `\"key\";q=10;w=1`.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window per policy: `\"project\";r=199;t=1`.","schema":{"type":"string"}}},"content":{"application/json":{"examples":{"rate_limited":{"summary":"Project rate limit","value":{"detail":"rate limit exceeded"}},"key_rate_limited":{"summary":"Key rate limit","value":{"detail":{"error":"key_rate_limited","message":"this API key may make 10 requests per second"}}},"key_quota_exhausted":{"summary":"Monthly request quota of the key used up","value":{"detail":{"error":"key_quota_exhausted","message":"this API key used its monthly fetch quota (100000 requests)","category":"fetch","limit":100000}}},"key_budget_exhausted":{"summary":"Monthly spend cap of the key reached","value":{"detail":{"error":"key_budget_exhausted","message":"this API key reached its monthly spend cap (50.00 USD)","limit":"50.00","currency":"USD"}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/jobs/{job_id}":{"get":{"tags":["batch"],"summary":"Get a job's status and results","description":"Returns the job's state and item counts; with `include=items`, also one\npage of items with their stored results (same shape as the single\nendpoints). Page with `offset`/`limit` until `offset >= counts.total`, or\nfilter with `status=failed`. Jobs are visible only to their project and\nkept 30 days after they finish.","operationId":"getJob","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"include","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`items` to include a page of item results.","title":"Include"},"description":"`items` to include a page of item results."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Index of the first item of the page.","default":0,"title":"Offset"},"description":"Index of the first item of the page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Items per page (max 1000).","default":100,"title":"Limit"},"description":"Items per page (max 1000)."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only items in this state: `pending`, `queued`, `done`, `failed`, `cancelled`.","title":"Status"},"description":"Only items in this state: `pending`, `queued`, `done`, `failed`, `cancelled`."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatus"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this project.","content":{"application/json":{"example":{"detail":"job not found"},"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["batch"],"summary":"Cancel a job","description":"Stops admitting items (within a few seconds): pending items become\n`cancelled`, queued items skip themselves, finished results are kept.\nReturns the job status.","operationId":"cancelJob","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatus"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this project.","content":{"application/json":{"example":{"detail":"job not found"},"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/bodies/{sha256}":{"get":{"tags":["bodies"],"summary":"Download the exact retrieved bytes","description":"Streams the exact bytes of a fetch (`body_url` in fetch results) with the\norigin `Content-Type`, `Content-Length`, `ETag: \"<sha256>\"`, `X-Body-Kind`\nand `Cache-Control: immutable`. `If-None-Match` gives `304`; `HEAD` returns\nthe headers only. A project can download only bodies it has retrieved\nitself (fresh or from the shared cache); anything else is `404`. Bodies are\nkept while a cache entry points to them or a project retrieved them within\nthe last 30 days.","operationId":"getBody","parameters":[{"name":"sha256","in":"path","required":true,"schema":{"type":"string","title":"Sha256"}}],"responses":{"200":{"description":"The bytes, with the origin `Content-Type`.","content":{"*/*":{"schema":{"type":"string","format":"binary"}}},"headers":{"ETag":{"description":"`\"<sha256>\"`","schema":{"type":"string"}},"X-Body-Kind":{"description":"`origin` or `rendered_dom` (see `body_kind`).","schema":{"type":"string"}},"X-Content-SHA256":{"description":"SHA-256 of the bytes.","schema":{"type":"string"}}}},"304":{"description":"Not modified (`If-None-Match` matched)."},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this project.","content":{"application/json":{"example":{"detail":"job not found"},"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A dependency is unavailable (authentication not configured, object storage down). Transient: retry with backoff.","content":{"application/json":{"example":{"detail":"object storage unavailable"},"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]},"head":{"tags":["bodies"],"summary":"Body metadata (headers only)","description":"Streams the exact bytes of a fetch (`body_url` in fetch results) with the\norigin `Content-Type`, `Content-Length`, `ETag: \"<sha256>\"`, `X-Body-Kind`\nand `Cache-Control: immutable`. `If-None-Match` gives `304`; `HEAD` returns\nthe headers only. A project can download only bodies it has retrieved\nitself (fresh or from the shared cache); anything else is `404`. Bodies are\nkept while a cache entry points to them or a project retrieved them within\nthe last 30 days.","operationId":"headBody","parameters":[{"name":"sha256","in":"path","required":true,"schema":{"type":"string","title":"Sha256"}}],"responses":{"200":{"description":"The bytes, with the origin `Content-Type`.","content":{"*/*":{"schema":{"type":"string","format":"binary"}}},"headers":{"ETag":{"description":"`\"<sha256>\"`","schema":{"type":"string"}},"X-Body-Kind":{"description":"`origin` or `rendered_dom` (see `body_kind`).","schema":{"type":"string"}},"X-Content-SHA256":{"description":"SHA-256 of the bytes.","schema":{"type":"string"}}}},"304":{"description":"Not modified (`If-None-Match` matched)."},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this project.","content":{"application/json":{"example":{"detail":"job not found"},"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A dependency is unavailable (authentication not configured, object storage down). Transient: retry with backoff.","content":{"application/json":{"example":{"detail":"object storage unavailable"},"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/sec/companies/resolve":{"get":{"tags":["sec"],"summary":"Resolve a ticker, CIK or name to an SEC company","description":"Looks the company up in SEC's `company_tickers.json` and\n`company_tickers_exchange.json` (cached 12 h) and returns its `cik`,\n`cik_padded`, `title`, `tickers` and `exchanges`. Give exactly one of\n`ticker`, `cik`, `name` or `isin`. A name can match several companies:\nthen `ambiguous` is `true`, the company fields are `null` and\n`candidates` lists the matches. A CIK without a listed ticker is resolved\nfrom its submissions. Not an SEC identifier: `error: not_sec_filer` when\nthe company is known otherwise (a non-US listing, the company register,\nGLEIF) with `hint` (`company`, `listing`, and `sec_candidates`: SEC\nfilers with its name, e.g. the ADR), else `error: unknown_identifier`.","operationId":"secResolveCompany","parameters":[{"name":"ticker","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"US ticker, e.g. `TSN` (`BRK.B` = `BRK-B`); for a foreign private issuer its ADR ticker (`NVO`, `TM`). A listing elsewhere (`NESN.SW`, `XSWX:NESN`) answers `not_sec_filer` with what is known.","title":"Ticker"},"description":"US ticker, e.g. `TSN` (`BRK.B` = `BRK-B`); for a foreign private issuer its ADR ticker (`NVO`, `TM`). A listing elsewhere (`NESN.SW`, `XSWX:NESN`) answers `not_sec_filer` with what is known."},{"name":"cik","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"CIK, e.g. `100493` or `0000100493`.","title":"Cik"},"description":"CIK, e.g. `100493` or `0000100493`."},{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Company name or its beginning.","title":"Name"},"description":"Company name or its beginning."},{"name":"isin","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"description":"ISIN: the issuer (company register, GLEIF), then the SEC filer with its name, e.g. Novo Nordisk's `DK0062498333` → `NVO`.","title":"Isin"},"description":"ISIN: the issuer (company register, GLEIF), then the SEC filer with its name, e.g. Novo Nordisk's `DK0062498333` → `NVO`."},{"name":"project_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Your own reference, kept in usage.","title":"Project Ref"},"description":"Your own reference, kept in usage."},{"name":"timeout_s","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":150,"exclusiveMinimum":0},{"type":"null"}],"description":"Overall deadline in seconds.","title":"Timeout S"},"description":"Overall deadline in seconds."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecResolve"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed: the key's customer account is suspended (`customer_suspended`, any `/v1` endpoint), a `user_agent` is not on the project's allowlist (`user_agent_not_allowed`, fetch endpoints), or the key may not use this category (`key_category_not_allowed`, search and fetch endpoints).","content":{"application/json":{"examples":{"user_agent_not_allowed":{"summary":"User-Agent not on the project allowlist","value":{"detail":{"error":"user_agent_not_allowed","hint":"ask the operator to add this User-Agent to the project allowlist"}}},"customer_suspended":{"summary":"Account suspended","value":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}},"key_category_not_allowed":{"summary":"The key may not use this category","value":{"detail":{"error":"key_category_not_allowed","message":"this API key may not use fetch (allowed: search)"}}}},"schema":{"$ref":"#/components/schemas/ErrorWithCode"}}}},"429":{"description":"A limit is reached. The project's rate limit (default 200 requests/s, one-second window; plain `detail`) or the key's own (`key_rate_limited`): retry after `Retry-After` (1 s). The key's monthly request quota (`key_quota_exhausted`) or spend cap (`key_budget_exhausted`): `Retry-After` is the time until the month resets; see `GET /v1/quota`.","content":{"application/json":{"examples":{"rate_limited":{"summary":"Project rate limit","value":{"detail":"rate limit exceeded"}},"key_rate_limited":{"summary":"Key rate limit","value":{"detail":{"error":"key_rate_limited","message":"this API key may make 10 requests per second"}}},"key_quota_exhausted":{"summary":"Monthly request quota of the key used up","value":{"detail":{"error":"key_quota_exhausted","message":"this API key used its monthly fetch quota (100000 requests)","category":"fetch","limit":100000}}},"key_budget_exhausted":{"summary":"Monthly spend cap of the key reached","value":{"detail":{"error":"key_budget_exhausted","message":"this API key reached its monthly spend cap (50.00 USD)","limit":"50.00","currency":"USD"}}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policies (IETF draft): `\"project\";q=200;w=1` and, when the key has its own limit, `\"key\";q=10;w=1`.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window per policy: `\"project\";r=199;t=1`.","schema":{"type":"string"}}}},"504":{"description":"No result within the synchronous wait (150 s, or `timeout_s` + 15 s). The request may still complete in the background; retry later (it is often a cache hit then) or use the batch endpoints.","content":{"application/json":{"example":{"detail":{"error":"timeout","request_id":"req_6b1f2c0e9a7d4b5c8e3f1a2b3c4d5e6f"}},"schema":{"$ref":"#/components/schemas/ErrorWithCode"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/sec/companies/{cik}/submissions":{"get":{"tags":["sec"],"summary":"A company's filings (normalised submissions)","description":"Company details and filings from `data.sec.gov/submissions/CIK##########.json`\n(cached 12 h, revalidated with conditional requests), including the pages\nof older filings it lists under `files` (only those that can hold filings\nafter `since`). Filings are newest first with `accession`, `form`,\n`filing_date`, `report_date`, `primary_document`, `primary_document_url`,\n`index_url` and `is_amendment`. The raw SEC JSON: `body_url`.","operationId":"secSubmissions","parameters":[{"name":"cik","in":"path","required":true,"schema":{"type":"string","description":"CIK: `100493` or `0000100493`.","examples":["100493"],"title":"Cik"},"description":"CIK: `100493` or `0000100493`."},{"name":"forms","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated form types, e.g. `10-K,20-F,40-F,10-K/A`.","examples":["10-K,10-K/A"],"title":"Forms"},"description":"Comma-separated form types, e.g. `10-K,20-F,40-F,10-K/A`."},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filed on or after (YYYY-MM-DD).","title":"Since"},"description":"Filed on or after (YYYY-MM-DD)."},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filed on or before (YYYY-MM-DD).","title":"Until"},"description":"Filed on or before (YYYY-MM-DD)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Filings returned at most.","default":100,"title":"Limit"},"description":"Filings returned at most."},{"name":"history","in":"query","required":false,"schema":{"type":"boolean","description":"Also read the pages of older filings (`files`); `false` = SEC's recent list only (the last ~1000 filings).","default":true,"title":"History"},"description":"Also read the pages of older filings (`files`); `false` = SEC's recent list only (the last ~1000 filings)."},{"name":"project_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Your own reference, kept in usage.","title":"Project Ref"},"description":"Your own reference, kept in usage."},{"name":"timeout_s","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":150,"exclusiveMinimum":0},{"type":"null"}],"description":"Overall deadline in seconds.","title":"Timeout S"},"description":"Overall deadline in seconds."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecSubmissions"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed: the key's customer account is suspended (`customer_suspended`, any `/v1` endpoint), a `user_agent` is not on the project's allowlist (`user_agent_not_allowed`, fetch endpoints), or the key may not use this category (`key_category_not_allowed`, search and fetch endpoints).","content":{"application/json":{"examples":{"user_agent_not_allowed":{"summary":"User-Agent not on the project allowlist","value":{"detail":{"error":"user_agent_not_allowed","hint":"ask the operator to add this User-Agent to the project allowlist"}}},"customer_suspended":{"summary":"Account suspended","value":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}},"key_category_not_allowed":{"summary":"The key may not use this category","value":{"detail":{"error":"key_category_not_allowed","message":"this API key may not use fetch (allowed: search)"}}}},"schema":{"$ref":"#/components/schemas/ErrorWithCode"}}}},"429":{"description":"A limit is reached. The project's rate limit (default 200 requests/s, one-second window; plain `detail`) or the key's own (`key_rate_limited`): retry after `Retry-After` (1 s). The key's monthly request quota (`key_quota_exhausted`) or spend cap (`key_budget_exhausted`): `Retry-After` is the time until the month resets; see `GET /v1/quota`.","content":{"application/json":{"examples":{"rate_limited":{"summary":"Project rate limit","value":{"detail":"rate limit exceeded"}},"key_rate_limited":{"summary":"Key rate limit","value":{"detail":{"error":"key_rate_limited","message":"this API key may make 10 requests per second"}}},"key_quota_exhausted":{"summary":"Monthly request quota of the key used up","value":{"detail":{"error":"key_quota_exhausted","message":"this API key used its monthly fetch quota (100000 requests)","category":"fetch","limit":100000}}},"key_budget_exhausted":{"summary":"Monthly spend cap of the key reached","value":{"detail":{"error":"key_budget_exhausted","message":"this API key reached its monthly spend cap (50.00 USD)","limit":"50.00","currency":"USD"}}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policies (IETF draft): `\"project\";q=200;w=1` and, when the key has its own limit, `\"key\";q=10;w=1`.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window per policy: `\"project\";r=199;t=1`.","schema":{"type":"string"}}}},"504":{"description":"No result within the synchronous wait (150 s, or `timeout_s` + 15 s). The request may still complete in the background; retry later (it is often a cache hit then) or use the batch endpoints.","content":{"application/json":{"example":{"detail":{"error":"timeout","request_id":"req_6b1f2c0e9a7d4b5c8e3f1a2b3c4d5e6f"}},"schema":{"$ref":"#/components/schemas/ErrorWithCode"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/sec/companies/{cik}/filings/latest":{"get":{"tags":["sec"],"summary":"A company's latest annual report (or other form)","description":"The newest filing of `forms` (by filing date): `accession`, `form`,\n`filing_date`, `report_date`, `primary_document`, `primary_document_url`,\n`index_url`, `is_amendment`, with the company's `cik`, `name`, `tickers`.\nLooks through older filings when the recent list has none. None at all:\n`error: not_found`.","operationId":"secLatestFiling","parameters":[{"name":"cik","in":"path","required":true,"schema":{"type":"string","description":"CIK: `100493` or `0000100493`.","examples":["100493"],"title":"Cik"},"description":"CIK: `100493` or `0000100493`."},{"name":"forms","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated form types; default `10-K,20-F,40-F` (annual reports; add e.g. `10-K/A` to include amendments).","examples":["10-K,20-F,40-F"],"title":"Forms"},"description":"Comma-separated form types; default `10-K,20-F,40-F` (annual reports; add e.g. `10-K/A` to include amendments)."},{"name":"project_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Your own reference, kept in usage.","title":"Project Ref"},"description":"Your own reference, kept in usage."},{"name":"timeout_s","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":150,"exclusiveMinimum":0},{"type":"null"}],"description":"Overall deadline in seconds.","title":"Timeout S"},"description":"Overall deadline in seconds."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecLatestFiling"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed: the key's customer account is suspended (`customer_suspended`, any `/v1` endpoint), a `user_agent` is not on the project's allowlist (`user_agent_not_allowed`, fetch endpoints), or the key may not use this category (`key_category_not_allowed`, search and fetch endpoints).","content":{"application/json":{"examples":{"user_agent_not_allowed":{"summary":"User-Agent not on the project allowlist","value":{"detail":{"error":"user_agent_not_allowed","hint":"ask the operator to add this User-Agent to the project allowlist"}}},"customer_suspended":{"summary":"Account suspended","value":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}},"key_category_not_allowed":{"summary":"The key may not use this category","value":{"detail":{"error":"key_category_not_allowed","message":"this API key may not use fetch (allowed: search)"}}}},"schema":{"$ref":"#/components/schemas/ErrorWithCode"}}}},"429":{"description":"A limit is reached. The project's rate limit (default 200 requests/s, one-second window; plain `detail`) or the key's own (`key_rate_limited`): retry after `Retry-After` (1 s). The key's monthly request quota (`key_quota_exhausted`) or spend cap (`key_budget_exhausted`): `Retry-After` is the time until the month resets; see `GET /v1/quota`.","content":{"application/json":{"examples":{"rate_limited":{"summary":"Project rate limit","value":{"detail":"rate limit exceeded"}},"key_rate_limited":{"summary":"Key rate limit","value":{"detail":{"error":"key_rate_limited","message":"this API key may make 10 requests per second"}}},"key_quota_exhausted":{"summary":"Monthly request quota of the key used up","value":{"detail":{"error":"key_quota_exhausted","message":"this API key used its monthly fetch quota (100000 requests)","category":"fetch","limit":100000}}},"key_budget_exhausted":{"summary":"Monthly spend cap of the key reached","value":{"detail":{"error":"key_budget_exhausted","message":"this API key reached its monthly spend cap (50.00 USD)","limit":"50.00","currency":"USD"}}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policies (IETF draft): `\"project\";q=200;w=1` and, when the key has its own limit, `\"key\";q=10;w=1`.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window per policy: `\"project\";r=199;t=1`.","schema":{"type":"string"}}}},"504":{"description":"No result within the synchronous wait (150 s, or `timeout_s` + 15 s). The request may still complete in the background; retry later (it is often a cache hit then) or use the batch endpoints.","content":{"application/json":{"example":{"detail":{"error":"timeout","request_id":"req_6b1f2c0e9a7d4b5c8e3f1a2b3c4d5e6f"}},"schema":{"$ref":"#/components/schemas/ErrorWithCode"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/sec/companies/{cik}/facts":{"get":{"tags":["sec"],"summary":"A company's XBRL facts","description":"All XBRL facts SEC holds for the company\n(`data.sec.gov/api/xbrl/companyfacts/CIK##########.json`, cached 12 h).\nThe answer summarises it (`name`, concepts per taxonomy); download the\ncomplete JSON (often several MB) from `body_url`.","operationId":"secCompanyFacts","parameters":[{"name":"cik","in":"path","required":true,"schema":{"type":"string","description":"CIK: `100493` or `0000100493`.","examples":["100493"],"title":"Cik"},"description":"CIK: `100493` or `0000100493`."},{"name":"project_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Your own reference, kept in usage.","title":"Project Ref"},"description":"Your own reference, kept in usage."},{"name":"timeout_s","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":150,"exclusiveMinimum":0},{"type":"null"}],"description":"Overall deadline in seconds.","title":"Timeout S"},"description":"Overall deadline in seconds."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecFacts"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed: the key's customer account is suspended (`customer_suspended`, any `/v1` endpoint), a `user_agent` is not on the project's allowlist (`user_agent_not_allowed`, fetch endpoints), or the key may not use this category (`key_category_not_allowed`, search and fetch endpoints).","content":{"application/json":{"examples":{"user_agent_not_allowed":{"summary":"User-Agent not on the project allowlist","value":{"detail":{"error":"user_agent_not_allowed","hint":"ask the operator to add this User-Agent to the project allowlist"}}},"customer_suspended":{"summary":"Account suspended","value":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}},"key_category_not_allowed":{"summary":"The key may not use this category","value":{"detail":{"error":"key_category_not_allowed","message":"this API key may not use fetch (allowed: search)"}}}},"schema":{"$ref":"#/components/schemas/ErrorWithCode"}}}},"429":{"description":"A limit is reached. The project's rate limit (default 200 requests/s, one-second window; plain `detail`) or the key's own (`key_rate_limited`): retry after `Retry-After` (1 s). The key's monthly request quota (`key_quota_exhausted`) or spend cap (`key_budget_exhausted`): `Retry-After` is the time until the month resets; see `GET /v1/quota`.","content":{"application/json":{"examples":{"rate_limited":{"summary":"Project rate limit","value":{"detail":"rate limit exceeded"}},"key_rate_limited":{"summary":"Key rate limit","value":{"detail":{"error":"key_rate_limited","message":"this API key may make 10 requests per second"}}},"key_quota_exhausted":{"summary":"Monthly request quota of the key used up","value":{"detail":{"error":"key_quota_exhausted","message":"this API key used its monthly fetch quota (100000 requests)","category":"fetch","limit":100000}}},"key_budget_exhausted":{"summary":"Monthly spend cap of the key reached","value":{"detail":{"error":"key_budget_exhausted","message":"this API key reached its monthly spend cap (50.00 USD)","limit":"50.00","currency":"USD"}}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policies (IETF draft): `\"project\";q=200;w=1` and, when the key has its own limit, `\"key\";q=10;w=1`.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window per policy: `\"project\";r=199;t=1`.","schema":{"type":"string"}}}},"504":{"description":"No result within the synchronous wait (150 s, or `timeout_s` + 15 s). The request may still complete in the background; retry later (it is often a cache hit then) or use the batch endpoints.","content":{"application/json":{"example":{"detail":{"error":"timeout","request_id":"req_6b1f2c0e9a7d4b5c8e3f1a2b3c4d5e6f"}},"schema":{"$ref":"#/components/schemas/ErrorWithCode"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/sec/filings/{cik}/{accession}":{"get":{"tags":["sec"],"summary":"The documents of a filing","description":"The filing index: form, dates and every document (`sequence`,\n`description`, `document`, `type` such as `10-K` or `EX-21.1`, `size`,\n`url`), from the `-index.htm` page (or the folder's `index.json`).\nFilings never change, so this is cached for a year.","operationId":"secFilingIndex","parameters":[{"name":"cik","in":"path","required":true,"schema":{"type":"string","description":"CIK: `100493` or `0000100493`.","examples":["100493"],"title":"Cik"},"description":"CIK: `100493` or `0000100493`."},{"name":"accession","in":"path","required":true,"schema":{"type":"string","description":"Accession number, with or without dashes.","examples":["0000100493-25-000070"],"title":"Accession"},"description":"Accession number, with or without dashes."},{"name":"project_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Your own reference, kept in usage.","title":"Project Ref"},"description":"Your own reference, kept in usage."},{"name":"timeout_s","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":150,"exclusiveMinimum":0},{"type":"null"}],"description":"Overall deadline in seconds.","title":"Timeout S"},"description":"Overall deadline in seconds."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecFilingIndex"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed: the key's customer account is suspended (`customer_suspended`, any `/v1` endpoint), a `user_agent` is not on the project's allowlist (`user_agent_not_allowed`, fetch endpoints), or the key may not use this category (`key_category_not_allowed`, search and fetch endpoints).","content":{"application/json":{"examples":{"user_agent_not_allowed":{"summary":"User-Agent not on the project allowlist","value":{"detail":{"error":"user_agent_not_allowed","hint":"ask the operator to add this User-Agent to the project allowlist"}}},"customer_suspended":{"summary":"Account suspended","value":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}},"key_category_not_allowed":{"summary":"The key may not use this category","value":{"detail":{"error":"key_category_not_allowed","message":"this API key may not use fetch (allowed: search)"}}}},"schema":{"$ref":"#/components/schemas/ErrorWithCode"}}}},"429":{"description":"A limit is reached. The project's rate limit (default 200 requests/s, one-second window; plain `detail`) or the key's own (`key_rate_limited`): retry after `Retry-After` (1 s). The key's monthly request quota (`key_quota_exhausted`) or spend cap (`key_budget_exhausted`): `Retry-After` is the time until the month resets; see `GET /v1/quota`.","content":{"application/json":{"examples":{"rate_limited":{"summary":"Project rate limit","value":{"detail":"rate limit exceeded"}},"key_rate_limited":{"summary":"Key rate limit","value":{"detail":{"error":"key_rate_limited","message":"this API key may make 10 requests per second"}}},"key_quota_exhausted":{"summary":"Monthly request quota of the key used up","value":{"detail":{"error":"key_quota_exhausted","message":"this API key used its monthly fetch quota (100000 requests)","category":"fetch","limit":100000}}},"key_budget_exhausted":{"summary":"Monthly spend cap of the key reached","value":{"detail":{"error":"key_budget_exhausted","message":"this API key reached its monthly spend cap (50.00 USD)","limit":"50.00","currency":"USD"}}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policies (IETF draft): `\"project\";q=200;w=1` and, when the key has its own limit, `\"key\";q=10;w=1`.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window per policy: `\"project\";r=199;t=1`.","schema":{"type":"string"}}}},"504":{"description":"No result within the synchronous wait (150 s, or `timeout_s` + 15 s). The request may still complete in the background; retry later (it is often a cache hit then) or use the batch endpoints.","content":{"application/json":{"example":{"detail":{"error":"timeout","request_id":"req_6b1f2c0e9a7d4b5c8e3f1a2b3c4d5e6f"}},"schema":{"$ref":"#/components/schemas/ErrorWithCode"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/sec/search":{"get":{"tags":["sec"],"summary":"EDGAR full-text search","description":"Searches the text of filings since 2001 with EDGAR full-text search\n(`efts.sec.gov`, cached 1 h): `total` and up to 100 `hits` per page, each\nwith the filing's `accession`, `ciks`, `form`, the matching document and\nits `url`.","operationId":"secSearch","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","description":"Query (EDGAR syntax: `\"exact phrase\"`, `OR`, `-exclude`).","examples":["\"poultry\" \"avian influenza\""],"title":"Q"},"description":"Query (EDGAR syntax: `\"exact phrase\"`, `OR`, `-exclude`)."},{"name":"forms","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated form types, e.g. `10-K,20-F,40-F,10-K/A`.","examples":["10-K,10-K/A"],"title":"Forms"},"description":"Comma-separated form types, e.g. `10-K,20-F,40-F,10-K/A`."},{"name":"dateRange","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`all`, `10y`, `5y`, `1y`, `30d`, or `custom` with `startdt`/`enddt`.","title":"Daterange"},"description":"`all`, `10y`, `5y`, `1y`, `30d`, or `custom` with `startdt`/`enddt`."},{"name":"startdt","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filed on or after (YYYY-MM-DD).","title":"Startdt"},"description":"Filed on or after (YYYY-MM-DD)."},{"name":"enddt","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filed on or before (YYYY-MM-DD).","title":"Enddt"},"description":"Filed on or before (YYYY-MM-DD)."},{"name":"from","in":"query","required":false,"schema":{"type":"integer","maximum":9900,"minimum":0,"description":"Offset of the first hit (pages of 100).","default":0,"title":"From"},"description":"Offset of the first hit (pages of 100)."},{"name":"project_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Your own reference, kept in usage.","title":"Project Ref"},"description":"Your own reference, kept in usage."},{"name":"timeout_s","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":150,"exclusiveMinimum":0},{"type":"null"}],"description":"Overall deadline in seconds.","title":"Timeout S"},"description":"Overall deadline in seconds."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecSearch"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed: the key's customer account is suspended (`customer_suspended`, any `/v1` endpoint), a `user_agent` is not on the project's allowlist (`user_agent_not_allowed`, fetch endpoints), or the key may not use this category (`key_category_not_allowed`, search and fetch endpoints).","content":{"application/json":{"examples":{"user_agent_not_allowed":{"summary":"User-Agent not on the project allowlist","value":{"detail":{"error":"user_agent_not_allowed","hint":"ask the operator to add this User-Agent to the project allowlist"}}},"customer_suspended":{"summary":"Account suspended","value":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}},"key_category_not_allowed":{"summary":"The key may not use this category","value":{"detail":{"error":"key_category_not_allowed","message":"this API key may not use fetch (allowed: search)"}}}},"schema":{"$ref":"#/components/schemas/ErrorWithCode"}}}},"429":{"description":"A limit is reached. The project's rate limit (default 200 requests/s, one-second window; plain `detail`) or the key's own (`key_rate_limited`): retry after `Retry-After` (1 s). The key's monthly request quota (`key_quota_exhausted`) or spend cap (`key_budget_exhausted`): `Retry-After` is the time until the month resets; see `GET /v1/quota`.","content":{"application/json":{"examples":{"rate_limited":{"summary":"Project rate limit","value":{"detail":"rate limit exceeded"}},"key_rate_limited":{"summary":"Key rate limit","value":{"detail":{"error":"key_rate_limited","message":"this API key may make 10 requests per second"}}},"key_quota_exhausted":{"summary":"Monthly request quota of the key used up","value":{"detail":{"error":"key_quota_exhausted","message":"this API key used its monthly fetch quota (100000 requests)","category":"fetch","limit":100000}}},"key_budget_exhausted":{"summary":"Monthly spend cap of the key reached","value":{"detail":{"error":"key_budget_exhausted","message":"this API key reached its monthly spend cap (50.00 USD)","limit":"50.00","currency":"USD"}}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policies (IETF draft): `\"project\";q=200;w=1` and, when the key has its own limit, `\"key\";q=10;w=1`.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window per policy: `\"project\";r=199;t=1`.","schema":{"type":"string"}}}},"504":{"description":"No result within the synchronous wait (150 s, or `timeout_s` + 15 s). The request may still complete in the background; retry later (it is often a cache hit then) or use the batch endpoints.","content":{"application/json":{"example":{"detail":{"error":"timeout","request_id":"req_6b1f2c0e9a7d4b5c8e3f1a2b3c4d5e6f"}},"schema":{"$ref":"#/components/schemas/ErrorWithCode"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/sec/documents/fetch":{"post":{"tags":["sec"],"summary":"Fetch a filing document","description":"Fetches one document of a filing — the primary HTML/iXBRL document, a\nPDF or an exhibit — and returns exactly what `POST /v1/fetch` returns\n(`text`, `pdf_text_pages`, `content_kind`, `body_url`, `sha256`, …), so\nthe same artifact handling applies. Only documents under\n`/Archives/edgar/data/{cik}/{accession}/` can be fetched; filing documents\nare immutable and cached for a year.","operationId":"secFetchDocument","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SecDocumentFetchBody"}}},"required":true},"responses":{"200":{"description":"The fetch result (same shape as `POST /v1/fetch`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FetchResponse"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"invalid API key"}}}},"403":{"description":"Not allowed: the key's customer account is suspended (`customer_suspended`, any `/v1` endpoint), a `user_agent` is not on the project's allowlist (`user_agent_not_allowed`, fetch endpoints), or the key may not use this category (`key_category_not_allowed`, search and fetch endpoints).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"examples":{"user_agent_not_allowed":{"summary":"User-Agent not on the project allowlist","value":{"detail":{"error":"user_agent_not_allowed","hint":"ask the operator to add this User-Agent to the project allowlist"}}},"customer_suspended":{"summary":"Account suspended","value":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}},"key_category_not_allowed":{"summary":"The key may not use this category","value":{"detail":{"error":"key_category_not_allowed","message":"this API key may not use fetch (allowed: search)"}}}}}}},"429":{"description":"A limit is reached. The project's rate limit (default 200 requests/s, one-second window; plain `detail`) or the key's own (`key_rate_limited`): retry after `Retry-After` (1 s). The key's monthly request quota (`key_quota_exhausted`) or spend cap (`key_budget_exhausted`): `Retry-After` is the time until the month resets; see `GET /v1/quota`.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policies (IETF draft): `\"project\";q=200;w=1` and, when the key has its own limit, `\"key\";q=10;w=1`.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window per policy: `\"project\";r=199;t=1`.","schema":{"type":"string"}}},"content":{"application/json":{"examples":{"rate_limited":{"summary":"Project rate limit","value":{"detail":"rate limit exceeded"}},"key_rate_limited":{"summary":"Key rate limit","value":{"detail":{"error":"key_rate_limited","message":"this API key may make 10 requests per second"}}},"key_quota_exhausted":{"summary":"Monthly request quota of the key used up","value":{"detail":{"error":"key_quota_exhausted","message":"this API key used its monthly fetch quota (100000 requests)","category":"fetch","limit":100000}}},"key_budget_exhausted":{"summary":"Monthly spend cap of the key reached","value":{"detail":{"error":"key_budget_exhausted","message":"this API key reached its monthly spend cap (50.00 USD)","limit":"50.00","currency":"USD"}}}}}}},"504":{"description":"No result within the synchronous wait (150 s, or `timeout_s` + 15 s). The request may still complete in the background; retry later (it is often a cache hit then) or use the batch endpoints.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"timeout","request_id":"req_6b1f2c0e9a7d4b5c8e3f1a2b3c4d5e6f"}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/batch/sec":{"post":{"tags":["batch"],"summary":"Create a batch SEC EDGAR job","description":"Queues up to 50,000 SEC EDGAR operations as one job (kind `sec`) and\nreturns its `job_id` at once: `resolve`, `submissions`, `latest`, `facts`\nand `filing` (results as from the matching `/v1/sec/...` endpoint, plus\n`op`) and `document` (the result of `POST /v1/sec/documents/fetch`,\nwithout `html` unless `include_html`). `submissions`, `latest` and `facts`\ntake a `ticker` instead of a `cik`. Items share the cluster-wide SEC rate\nlimit (at most 10 requests per second per egress, as SEC allows) with\nevery other SEC request: a full limiter or a SEC backoff puts an item back\nin the queue instead of failing it. Each item is metered once as kind\n`sec` (counted like a fetch for key limits). Identifiers are checked when\nthe job is created (`422 invalid_item`). Poll `GET /v1/jobs/{job_id}` or\npass `callback_url`.","operationId":"batchSec","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchSecBody"}}},"required":true},"responses":{"202":{"description":"Job created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCreated"}}}},"200":{"description":"Existing job (same idempotency key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCreated"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"invalid API key"}}}},"403":{"description":"Not allowed: the key's customer account is suspended (`customer_suspended`, any `/v1` endpoint), a `user_agent` is not on the project's allowlist (`user_agent_not_allowed`, fetch endpoints), or the key may not use this category (`key_category_not_allowed`, search and fetch endpoints).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"examples":{"user_agent_not_allowed":{"summary":"User-Agent not on the project allowlist","value":{"detail":{"error":"user_agent_not_allowed","hint":"ask the operator to add this User-Agent to the project allowlist"}}},"customer_suspended":{"summary":"Account suspended","value":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}},"key_category_not_allowed":{"summary":"The key may not use this category","value":{"detail":{"error":"key_category_not_allowed","message":"this API key may not use fetch (allowed: search)"}}}}}}},"409":{"description":"The `idempotency_key` was already used for a job of a different kind or size.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"idempotency_key already used for a different job"}}}},"413":{"description":"Too many items for one job (at most 50,000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"at most 50000 items per job"}}}},"429":{"description":"A limit is reached. The project's rate limit (default 200 requests/s, one-second window; plain `detail`) or the key's own (`key_rate_limited`): retry after `Retry-After` (1 s). The key's monthly request quota (`key_quota_exhausted`) or spend cap (`key_budget_exhausted`): `Retry-After` is the time until the month resets; see `GET /v1/quota`.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policies (IETF draft): `\"project\";q=200;w=1` and, when the key has its own limit, `\"key\";q=10;w=1`.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window per policy: `\"project\";r=199;t=1`.","schema":{"type":"string"}}},"content":{"application/json":{"examples":{"rate_limited":{"summary":"Project rate limit","value":{"detail":"rate limit exceeded"}},"key_rate_limited":{"summary":"Key rate limit","value":{"detail":{"error":"key_rate_limited","message":"this API key may make 10 requests per second"}}},"key_quota_exhausted":{"summary":"Monthly request quota of the key used up","value":{"detail":{"error":"key_quota_exhausted","message":"this API key used its monthly fetch quota (100000 requests)","category":"fetch","limit":100000}}},"key_budget_exhausted":{"summary":"Monthly spend cap of the key reached","value":{"detail":{"error":"key_budget_exhausted","message":"this API key reached its monthly spend cap (50.00 USD)","limit":"50.00","currency":"USD"}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/account":{"get":{"tags":["account"],"summary":"Account, plan and current estimate","description":"The key's project usage this month by billing category, and — when the\nproject belongs to a customer — the customer's usage, price plan and an\nestimate of the month's charges (rated now, not persisted). Usage is\naggregated every 5 minutes (`usage_refreshed_at`). Projects without a customer get\n`customer`, `plan` and `estimate` as `null`.\n\n`keys` breaks the month down per API key: with an account admin key\n(`cma_…`) every key of the customer's projects (or of this project without\na customer) plus usage from before per-key attribution; with an additional\nkey (`cmr_…`) only that key. Prefix, label and role only, usage by category\nand the key's share of the usage charges.","operationId":"getAccount","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"invalid API key"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/account/invoices":{"get":{"tags":["account"],"summary":"List invoices","description":"The customer's issued, paid and void invoices (never drafts); an empty\nlist for projects without a customer.","operationId":"listInvoices","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceList"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"invalid API key"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/account/invoices/{number}":{"get":{"tags":["account"],"summary":"Get an invoice with its lines","description":"One invoice with its priced lines and the volume tiers applied. Another\ncustomer's invoice number, or a draft, is `404`.","operationId":"getInvoice","parameters":[{"name":"number","in":"path","required":true,"schema":{"type":"string","title":"Number"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceDetail"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this project.","content":{"application/json":{"example":{"detail":"job not found"},"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/account/invoices/{number}/pdf":{"get":{"tags":["account"],"summary":"Download an invoice as PDF","description":"The invoice as a PDF file. Another customer's invoice number, or a\ndraft, is `404`.","operationId":"getInvoicePdf","parameters":[{"name":"number","in":"path","required":true,"schema":{"type":"string","title":"Number"}}],"responses":{"200":{"description":"The PDF (`Content-Disposition: attachment`).","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this project.","content":{"application/json":{"example":{"detail":"job not found"},"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/status":{"get":{"tags":["status"],"summary":"Service status","description":"Overall status, every component's status with aggregate metrics, and\nopen or recent incidents and maintenance. No authentication. Refreshed at\nmost every 15 s (`Cache-Control: public, max-age=15`; `ETag` /\n`If-None-Match` supported). Always `200` while Cormorant answers: alert on\n`status`, not on the HTTP code. See the monitoring guide.","operationId":"getStatus","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__api__models__Status"}}}},"429":{"description":"More than `STATUS_RATE_LIMIT_PER_MIN` (default 120) status requests per minute from this IP address. Retry after `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"rate limit exceeded"}}}}},"security":[]}},"/v1/status/summary":{"get":{"tags":["status"],"summary":"Service status (summary)","description":"Only the overall `status` and `updated_at`: a tiny body for uptime\nmonitors (match on `\"status\":\"operational\"`). No authentication; always\n`200` while Cormorant answers.","operationId":"getStatusSummary","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusSummary"}}}},"429":{"description":"More than `STATUS_RATE_LIMIT_PER_MIN` (default 120) status requests per minute from this IP address. Retry after `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"rate limit exceeded"}}}}},"security":[]}},"/v1/status/components/{component_id}":{"get":{"tags":["status"],"summary":"One component's status","description":"The status, reasons and metrics of one component, with the incidents\nand maintenance that name it. No authentication.","operationId":"getStatusComponent","parameters":[{"name":"component_id","in":"path","required":true,"schema":{"type":"string","maxLength":40,"description":"Component id, e.g. `fetch` (see `GET /v1/status`).","title":"Component Id"},"description":"Component id, e.g. `fetch` (see `GET /v1/status`)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusComponentDetail"}}}},"404":{"description":"No such component in this deployment (see the component list of `GET /v1/status`).","content":{"application/json":{"example":{"detail":"unknown component"},"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than `STATUS_RATE_LIMIT_PER_MIN` (default 120) status requests per minute from this IP address. Retry after `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"example":{"detail":"rate limit exceeded"},"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/v1/status/history":{"get":{"tags":["status"],"summary":"Status history","description":"The worst status of every component per time bucket, oldest first, and\nits uptime over the period (`partial_outage` counts 30 % downtime,\n`major_outage` 100 %; buckets without data are `null` and not counted).\nThe overall status is the component `_overall`. Kept 7 days. No\nauthentication.","operationId":"getStatusHistory","parameters":[{"name":"hours","in":"query","required":false,"schema":{"type":"integer","maximum":168,"minimum":1,"description":"How far back, in hours (1–168). Up to 24 h the buckets are 5 minutes; beyond, 1 hour (the worst status within the hour).","default":24,"title":"Hours"},"description":"How far back, in hours (1–168). Up to 24 h the buckets are 5 minutes; beyond, 1 hour (the worst status within the hour)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusHistory"}}}},"429":{"description":"More than `STATUS_RATE_LIMIT_PER_MIN` (default 120) status requests per minute from this IP address. Retry after `Retry-After` seconds.","headers":{"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"example":{"detail":"rate limit exceeded"},"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[]}},"/v1/keys":{"get":{"tags":["usage"],"summary":"API keys visible to this key","description":"The keys the caller may see, by prefix, label, role and limits — never\nthe keys themselves. An account admin key (`cma_…`) sees every key of its\ncustomer's projects (or of its project without a customer), revoked keys\nincluded; a standard key (`cmr_…`) sees only itself.","operationId":"listKeys","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyList"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"invalid API key"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/keys/self":{"get":{"tags":["usage"],"summary":"The calling key and its quota","description":"Prefix, label, role, project, status and limits of the calling key, with\nits current quota state (`quota`: each limit's use this month, as in\n`GET /v1/quota`).","operationId":"getKeySelf","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeySelf"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"invalid API key"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/usage":{"get":{"tags":["usage"],"summary":"Usage, charges and statistics","description":"Usage of the caller's scope with what it costs: requests, successes,\ncache hits, failures by error, latency p50/p95, bytes, the share of\npremium-route fetches and — for projects with a customer — billable quantities,\nincluded units used and the **charge at the customer's plan price** in the\ninvoice currency (the same rating as the invoice; groups add up exactly to\nthe estimate's usage lines).\n\nA standard key (`cmr_…`) sees only its own usage; an account admin key\n(`cma_…`) sees every key and project of the customer, revoked keys and\nusage from before per-key attribution (`key: null`) included. Combine\n`group_by` dimensions and filter by `key`, `project` and `category`. Figures\ncome from aggregates refreshed every 5 minutes (`as_of`); `final` marks\nclosed days. Provider cost (`cost_usd`, `budget`) appears only for projects\nwithout an external customer. `Accept: text/csv` returns the groups as CSV.","operationId":"getUsage","parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"First day, `YYYY-MM-DD` (UTC). Default: the first of the current month.","title":"From"},"description":"First day, `YYYY-MM-DD` (UTC). Default: the first of the current month."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last day (inclusive), `YYYY-MM-DD`. Default: today.","title":"To"},"description":"Last day (inclusive), `YYYY-MM-DD`. Default: today."},{"name":"group_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated dimensions to group by, combinable: `key`, `project`, `category`, `day`, `hour` (hourly data is kept 35 days). Example: `group_by=key,day`.","title":"Group By"},"description":"Comma-separated dimensions to group by, combinable: `key`, `project`, `category`, `day`, `hour` (hourly data is kept 35 days). Example: `group_by=key,day`."},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only these keys (comma-separated prefixes, e.g. `cmr_AbCdEf`). A key the caller cannot see is `404`.","title":"Key"},"description":"Only these keys (comma-separated prefixes, e.g. `cmr_AbCdEf`). A key the caller cannot see is `404`."},{"name":"project","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only these projects (comma-separated names).","title":"Project"},"description":"Only these projects (comma-separated names)."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only these billing categories (comma-separated): `search`, `search_fallback`, `search_cached`, `fetch_own`, `fetch_premium`, `fetch_cached`, `company`, `company_cached`, `sec`, `sec_cached`, `company_profile`, `company_profile_cached`.","title":"Category"},"description":"Only these billing categories (comma-separated): `search`, `search_fallback`, `search_cached`, `fetch_own`, `fetch_premium`, `fetch_cached`, `company`, `company_cached`, `sec`, `sec_cached`, `company_profile`, `company_profile_cached`."},{"name":"format","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`csv` instead of `Accept: text/csv`; default `json`.","title":"Format"},"description":"`csv` instead of `Accept: text/csv`; default `json`."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}},"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this project.","content":{"application/json":{"example":{"detail":"job not found"},"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/usage/timeseries":{"get":{"tags":["usage"],"summary":"Usage over time, for charts","description":"The metrics of `GET /v1/usage` (requests, failures, latency, premium share,\ncharges, …) per hour or day, one point per bucket — buckets without usage\nare zero — for charts. Same scope and filters as `GET /v1/usage`; `final`\nper point marks closed days. CSV with `Accept: text/csv`.","operationId":"getUsageTimeseries","parameters":[{"name":"granularity","in":"query","required":false,"schema":{"type":"string","pattern":"^(hour|day)$","description":"`hour` (last 35 days) or `day`.","default":"day","title":"Granularity"},"description":"`hour` (last 35 days) or `day`."},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"First day, `YYYY-MM-DD` (UTC). Default: today with `granularity=hour`, the first of the month with `day`.","title":"From"},"description":"First day, `YYYY-MM-DD` (UTC). Default: today with `granularity=hour`, the first of the month with `day`."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last day (inclusive), `YYYY-MM-DD`. Default: today.","title":"To"},"description":"Last day (inclusive), `YYYY-MM-DD`. Default: today."},{"name":"group_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"One series per value of these dimensions (comma-separated): `key`, `project`, `category`. Default: one series.","title":"Group By"},"description":"One series per value of these dimensions (comma-separated): `key`, `project`, `category`. Default: one series."},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only these keys (comma-separated prefixes, e.g. `cmr_AbCdEf`). A key the caller cannot see is `404`.","title":"Key"},"description":"Only these keys (comma-separated prefixes, e.g. `cmr_AbCdEf`). A key the caller cannot see is `404`."},{"name":"project","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only these projects (comma-separated names).","title":"Project"},"description":"Only these projects (comma-separated names)."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only these billing categories (comma-separated): `search`, `search_fallback`, `search_cached`, `fetch_own`, `fetch_premium`, `fetch_cached`, `company`, `company_cached`, `sec`, `sec_cached`, `company_profile`, `company_profile_cached`.","title":"Category"},"description":"Only these billing categories (comma-separated): `search`, `search_fallback`, `search_cached`, `fetch_own`, `fetch_premium`, `fetch_cached`, `company`, `company_cached`, `sec`, `sec_cached`, `company_profile`, `company_profile_cached`."},{"name":"format","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`csv` instead of `Accept: text/csv`; default `json`.","title":"Format"},"description":"`csv` instead of `Accept: text/csv`; default `json`."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageTimeseries"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this project.","content":{"application/json":{"example":{"detail":"job not found"},"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/usage/domains":{"get":{"tags":["usage"],"summary":"Top fetched domains","description":"The busiest fetched domains of the caller's keys: requests, successes,\nsuccess rate, premium-route fetches and premium share. Built from each key's\n100 busiest domains per day, kept 90 days. Usage recorded before per-key\nattribution is not included. CSV with `Accept: text/csv`.","operationId":"getUsageDomains","parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"First day, `YYYY-MM-DD` (UTC). Default: the first of the current month (90 days kept).","title":"From"},"description":"First day, `YYYY-MM-DD` (UTC). Default: the first of the current month (90 days kept)."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last day (inclusive), `YYYY-MM-DD`. Default: today.","title":"To"},"description":"Last day (inclusive), `YYYY-MM-DD`. Default: today."},{"name":"group_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`key`: a top list per key instead of one list.","title":"Group By"},"description":"`key`: a top list per key instead of one list."},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only these keys (comma-separated prefixes, e.g. `cmr_AbCdEf`). A key the caller cannot see is `404`.","title":"Key"},"description":"Only these keys (comma-separated prefixes, e.g. `cmr_AbCdEf`). A key the caller cannot see is `404`."},{"name":"project","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only these projects (comma-separated names).","title":"Project"},"description":"Only these projects (comma-separated names)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Domains per list (max 500).","default":50,"title":"Limit"},"description":"Domains per list (max 500)."},{"name":"format","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`csv` instead of `Accept: text/csv`; default `json`.","title":"Format"},"description":"`csv` instead of `Accept: text/csv`; default `json`."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageDomains"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this project.","content":{"application/json":{"example":{"detail":"job not found"},"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/requests":{"get":{"tags":["usage"],"summary":"Request ledger","description":"Every request of the caller's scope, newest first, in real time:\nrequest id, time, key, project, `project_ref`, kind, domain, tier, status,\nerror, latency, cache hit, billing category and — for customers — its\n`charge` (its share of the day's charges for its key and category; `null`\nuntil aggregated, within 5 minutes). Page with `next_cursor` (also in the\n`Link` header). Kept as long as the request log (90 days). A standard key\nsees only its own requests. CSV with `Accept: text/csv`.","operationId":"listRequests","parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"First day, `YYYY-MM-DD` (UTC). Default: 29 days before today (kept 90 days).","title":"From"},"description":"First day, `YYYY-MM-DD` (UTC). Default: 29 days before today (kept 90 days)."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last day (inclusive), `YYYY-MM-DD`. Default: today.","title":"To"},"description":"Last day (inclusive), `YYYY-MM-DD`. Default: today."},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only these keys (comma-separated prefixes, e.g. `cmr_AbCdEf`). A key the caller cannot see is `404`.","title":"Key"},"description":"Only these keys (comma-separated prefixes, e.g. `cmr_AbCdEf`). A key the caller cannot see is `404`."},{"name":"project","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only these projects (comma-separated names).","title":"Project"},"description":"Only these projects (comma-separated names)."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only these billing categories (comma-separated): `search`, `search_fallback`, `search_cached`, `fetch_own`, `fetch_premium`, `fetch_cached`, `company`, `company_cached`, `sec`, `sec_cached`, `company_profile`, `company_profile_cached`.","title":"Category"},"description":"Only these billing categories (comma-separated): `search`, `search_fallback`, `search_cached`, `fetch_own`, `fetch_premium`, `fetch_cached`, `company`, `company_cached`, `sec`, `sec_cached`, `company_profile`, `company_profile_cached`."},{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(search|fetch|company|sec|company_profile)$"},{"type":"null"}],"description":"`search`, `fetch`, `company`, `sec` (SEC EDGAR) or `company_profile` (extended company profiles).","title":"Kind"},"description":"`search`, `fetch`, `company`, `sec` (SEC EDGAR) or `company_profile` (extended company profiles)."},{"name":"outcome","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(succeeded|failed)$"},{"type":"null"}],"description":"`succeeded` or `failed`.","title":"Outcome"},"description":"`succeeded` or `failed`."},{"name":"error","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only this error code, e.g. `http_404`.","title":"Error"},"description":"Only this error code, e.g. `http_404`."},{"name":"domain","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only fetches of this host.","title":"Domain"},"description":"Only fetches of this host."},{"name":"cached","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Only cache hits (`true`) or misses.","title":"Cached"},"description":"Only cache hits (`true`) or misses."},{"name":"job_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only items of this batch job.","title":"Job Id"},"description":"Only items of this batch job."},{"name":"project_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only this `project_ref`.","title":"Project Ref"},"description":"Only this `project_ref`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Rows per page (max 1000).","default":100,"title":"Limit"},"description":"Rows per page (max 1000)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`next_cursor` of the previous page.","title":"Cursor"},"description":"`next_cursor` of the previous page."},{"name":"format","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`csv` instead of `Accept: text/csv`; default `json`.","title":"Format"},"description":"`csv` instead of `Accept: text/csv`; default `json`."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLedger"}},"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this project.","content":{"application/json":{"example":{"detail":"job not found"},"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/requests/{request_id}":{"get":{"tags":["usage"],"summary":"One request of the ledger","description":"One request by its `request_id` (`req_…`, or `<job_id>:<index>` for batch\nitems) with the tiers tried (`attempts`). A request of another key (for a\nstandard key) or another customer is `404`.","operationId":"getRequest","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LedgerRequestDetail"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this project.","content":{"application/json":{"example":{"detail":"job not found"},"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/quota":{"get":{"tags":["usage"],"summary":"Limits, allowances and what is left","description":"Every limit that applies to the caller, with `limit`, `used`,\n`reserved`, `remaining`, `resets_at`, `projected_end_of_period` and `status`\n(`ok`, `warning` from 80 %, `exhausted`): the key's monthly spend cap (in the\ninvoice currency) and request quotas, its and the project's requests per\nsecond, and — for account admin keys — every key of the account and the\nplan's included units. A standard key sees only itself.","operationId":"getQuota","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quota"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"invalid API key"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/alerts":{"get":{"tags":["usage"],"summary":"List alert webhooks","description":"The webhooks the caller may see (never their secrets): a standard key its\nown, an account admin key every webhook of the account.","operationId":"listAlerts","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertHookList"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"invalid API key"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]},"post":{"tags":["usage"],"summary":"Register an alert webhook","description":"Registers a webhook that receives an event whenever a key, project or\nthe account crosses 50, 80 or 100 % of a limit or allowance this month\n(spend cap, request quotas, provider budget, plan included units). The\nresponse contains the signing `secret` **once**; deliveries carry\n`X-Cormorant-Signature: t=<unix>,v1=<HMAC-SHA256 of \"<t>.<body>\">`. Standard\nkeys can register alerts for themselves only; account admin keys for any\nkey, project or the whole account (`403 account_admin_required`).","operationId":"createAlert","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertIn"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertHookCreated"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"invalid API key"}}}},"404":{"description":"Not found, or not visible to this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"job not found"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/alerts/{alert_id}":{"delete":{"tags":["usage"],"summary":"Delete an alert webhook","description":"Deletes a webhook the caller can see; anything else is `404`.","operationId":"deleteAlert","parameters":[{"name":"alert_id","in":"path","required":true,"schema":{"type":"integer","title":"Alert Id"}}],"responses":{"204":{"description":"Deleted."},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this project.","content":{"application/json":{"example":{"detail":"job not found"},"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/companies/search":{"get":{"tags":["companies"],"summary":"Search companies","description":"Searches the register (trigram and full-text over current, former and\ntrading names; exact on identifiers) plus the live sources covering\n`country` on the first page. Live hits (`in_register: false`) carry a `ref`\nto fetch them with `GET /v1/companies/{ref}`, which adds them to the\nregister. Needs `q` or `identifier`. Live sources are asked concurrently\nand waited for at most 2.5 s; `live_sources` says per source what happened\n(`ok`, `failed`, `timeout`, or `skipped` while a source backs off or its\ncanaries fail) and how long it took. A near-exact register match\n(score ≥ 0.95) answers without asking the live sources unless\n`live=true`; `live=false` searches the register only.","operationId":"searchCompanies","parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"description":"Name (any language, legal-form words ignored).","examples":["UBS Group"],"title":"Q"},"description":"Name (any language, legal-form words ignored)."},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[A-Za-z]{2}$"},{"type":"null"}],"description":"ISO 3166-1 alpha-2; also routes live search to that country's sources.","examples":["CH"],"title":"Country"},"description":"ISO 3166-1 alpha-2; also routes live search to that country's sources."},{"name":"identifier","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`scheme:value` exact match.","examples":["ch_uid:CHE-101.329.561"],"title":"Identifier"},"description":"`scheme:value` exact match."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Register status, e.g. `active`.","title":"Status"},"description":"Register status, e.g. `active`."},{"name":"legal_form","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Legal-form category, e.g. `corporation`.","title":"Legal Form"},"description":"Legal-form category, e.g. `corporation`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Results per page.","default":20,"title":"Limit"},"description":"Results per page."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`next_cursor` of the previous page.","title":"Cursor"},"description":"`next_cursor` of the previous page."},{"name":"live","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Also search the live sources (first page). Default: unless the register already has a near-exact match (score ≥ 0.95); `true` always, `false` never.","title":"Live"},"description":"Also search the live sources (first page). Default: unless the register already has a near-exact match (score ≥ 0.95); `true` always, `false` never."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanySearch"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed: the key's customer account is suspended (`customer_suspended`, any `/v1` endpoint), a `user_agent` is not on the project's allowlist (`user_agent_not_allowed`, fetch endpoints), or the key may not use this category (`key_category_not_allowed`, search and fetch endpoints).","content":{"application/json":{"examples":{"user_agent_not_allowed":{"summary":"User-Agent not on the project allowlist","value":{"detail":{"error":"user_agent_not_allowed","hint":"ask the operator to add this User-Agent to the project allowlist"}}},"customer_suspended":{"summary":"Account suspended","value":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}},"key_category_not_allowed":{"summary":"The key may not use this category","value":{"detail":{"error":"key_category_not_allowed","message":"this API key may not use fetch (allowed: search)"}}}},"schema":{"$ref":"#/components/schemas/ErrorWithCode"}}}},"429":{"description":"A limit is reached. The project's rate limit (default 200 requests/s, one-second window; plain `detail`) or the key's own (`key_rate_limited`): retry after `Retry-After` (1 s). The key's monthly request quota (`key_quota_exhausted`) or spend cap (`key_budget_exhausted`): `Retry-After` is the time until the month resets; see `GET /v1/quota`.","content":{"application/json":{"examples":{"rate_limited":{"summary":"Project rate limit","value":{"detail":"rate limit exceeded"}},"key_rate_limited":{"summary":"Key rate limit","value":{"detail":{"error":"key_rate_limited","message":"this API key may make 10 requests per second"}}},"key_quota_exhausted":{"summary":"Monthly request quota of the key used up","value":{"detail":{"error":"key_quota_exhausted","message":"this API key used its monthly fetch quota (100000 requests)","category":"fetch","limit":100000}}},"key_budget_exhausted":{"summary":"Monthly spend cap of the key reached","value":{"detail":{"error":"key_budget_exhausted","message":"this API key reached its monthly spend cap (50.00 USD)","limit":"50.00","currency":"USD"}}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policies (IETF draft): `\"project\";q=200;w=1` and, when the key has its own limit, `\"key\";q=10;w=1`.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window per policy: `\"project\";r=199;t=1`.","schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/companies/resolve":{"post":{"tags":["companies"],"summary":"Resolve a company (entity resolution)","description":"Best match plus ranked candidates. Identifiers are tried first (exact,\n`match_score` 1); then name, country and city are scored over the register\nand the live sources. `match` is set only for a confident match, and is\nadded to the register unless `persist` is `false`: its `id` is the\n`cmp_` id and `in_register` is `true`, so no second call is needed.\nA confident register match answers without asking any source; otherwise\nthe live sources are asked concurrently (at most 2.5 s, `live_sources`\nas for search) and the other sources' data about a newly stored match is\nfetched in the background.","operationId":"resolveCompany","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyResolved"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"invalid API key"}}}},"403":{"description":"Not allowed: the key's customer account is suspended (`customer_suspended`, any `/v1` endpoint), a `user_agent` is not on the project's allowlist (`user_agent_not_allowed`, fetch endpoints), or the key may not use this category (`key_category_not_allowed`, search and fetch endpoints).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"examples":{"user_agent_not_allowed":{"summary":"User-Agent not on the project allowlist","value":{"detail":{"error":"user_agent_not_allowed","hint":"ask the operator to add this User-Agent to the project allowlist"}}},"customer_suspended":{"summary":"Account suspended","value":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}},"key_category_not_allowed":{"summary":"The key may not use this category","value":{"detail":{"error":"key_category_not_allowed","message":"this API key may not use fetch (allowed: search)"}}}}}}},"429":{"description":"A limit is reached. The project's rate limit (default 200 requests/s, one-second window; plain `detail`) or the key's own (`key_rate_limited`): retry after `Retry-After` (1 s). The key's monthly request quota (`key_quota_exhausted`) or spend cap (`key_budget_exhausted`): `Retry-After` is the time until the month resets; see `GET /v1/quota`.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policies (IETF draft): `\"project\";q=200;w=1` and, when the key has its own limit, `\"key\";q=10;w=1`.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window per policy: `\"project\";r=199;t=1`.","schema":{"type":"string"}}},"content":{"application/json":{"examples":{"rate_limited":{"summary":"Project rate limit","value":{"detail":"rate limit exceeded"}},"key_rate_limited":{"summary":"Key rate limit","value":{"detail":{"error":"key_rate_limited","message":"this API key may make 10 requests per second"}}},"key_quota_exhausted":{"summary":"Monthly request quota of the key used up","value":{"detail":{"error":"key_quota_exhausted","message":"this API key used its monthly fetch quota (100000 requests)","category":"fetch","limit":100000}}},"key_budget_exhausted":{"summary":"Monthly spend cap of the key reached","value":{"detail":{"error":"key_budget_exhausted","message":"this API key reached its monthly spend cap (50.00 USD)","limit":"50.00","currency":"USD"}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/companies/changes":{"get":{"tags":["companies"],"summary":"Change feed of the register","description":"Every change of the register, oldest first: which company and which\ntop-level fields (fetch the record for the values). Poll with\n`next_cursor`; or register a webhook with `POST /v1/companies/watches`.","operationId":"companyChanges","parameters":[{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 time to start from (first call).","title":"Since"},"description":"ISO 8601 time to start from (first call)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`next_cursor` of the previous call.","title":"Cursor"},"description":"`next_cursor` of the previous call."},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[A-Za-z]{2}$"},{"type":"null"}],"description":"Only this country.","title":"Country"},"description":"Only this country."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Changes per page.","default":100,"title":"Limit"},"description":"Changes per page."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyChanges"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed: the key's customer account is suspended (`customer_suspended`, any `/v1` endpoint), a `user_agent` is not on the project's allowlist (`user_agent_not_allowed`, fetch endpoints), or the key may not use this category (`key_category_not_allowed`, search and fetch endpoints).","content":{"application/json":{"examples":{"user_agent_not_allowed":{"summary":"User-Agent not on the project allowlist","value":{"detail":{"error":"user_agent_not_allowed","hint":"ask the operator to add this User-Agent to the project allowlist"}}},"customer_suspended":{"summary":"Account suspended","value":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}},"key_category_not_allowed":{"summary":"The key may not use this category","value":{"detail":{"error":"key_category_not_allowed","message":"this API key may not use fetch (allowed: search)"}}}},"schema":{"$ref":"#/components/schemas/ErrorWithCode"}}}},"429":{"description":"A limit is reached. The project's rate limit (default 200 requests/s, one-second window; plain `detail`) or the key's own (`key_rate_limited`): retry after `Retry-After` (1 s). The key's monthly request quota (`key_quota_exhausted`) or spend cap (`key_budget_exhausted`): `Retry-After` is the time until the month resets; see `GET /v1/quota`.","content":{"application/json":{"examples":{"rate_limited":{"summary":"Project rate limit","value":{"detail":"rate limit exceeded"}},"key_rate_limited":{"summary":"Key rate limit","value":{"detail":{"error":"key_rate_limited","message":"this API key may make 10 requests per second"}}},"key_quota_exhausted":{"summary":"Monthly request quota of the key used up","value":{"detail":{"error":"key_quota_exhausted","message":"this API key used its monthly fetch quota (100000 requests)","category":"fetch","limit":100000}}},"key_budget_exhausted":{"summary":"Monthly spend cap of the key reached","value":{"detail":{"error":"key_budget_exhausted","message":"this API key reached its monthly spend cap (50.00 USD)","limit":"50.00","currency":"USD"}}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policies (IETF draft): `\"project\";q=200;w=1` and, when the key has its own limit, `\"key\";q=10;w=1`.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window per policy: `\"project\";r=199;t=1`.","schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/companies/watches":{"get":{"tags":["companies"],"summary":"List company watches","description":"The project's watches (without secrets).","operationId":"listCompanyWatches","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyWatches"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"invalid API key"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]},"post":{"tags":["companies"],"summary":"Watch companies (webhook)","description":"Registers a webhook: changes of these companies are POSTed as\n`company.changed` (signed like usage alerts: `X-Cormorant-Signature:\nt=<unix>,v1=<HMAC-SHA256 of \"<t>.<body>\">`). Identifiers not yet in the\nregister are looked up first; unknown ones are `404`. The `secret` is\nreturned only here.","operationId":"createCompanyWatch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchBody"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyWatch"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"invalid API key"}}}},"403":{"description":"Not allowed: the key's customer account is suspended (`customer_suspended`, any `/v1` endpoint), a `user_agent` is not on the project's allowlist (`user_agent_not_allowed`, fetch endpoints), or the key may not use this category (`key_category_not_allowed`, search and fetch endpoints).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"examples":{"user_agent_not_allowed":{"summary":"User-Agent not on the project allowlist","value":{"detail":{"error":"user_agent_not_allowed","hint":"ask the operator to add this User-Agent to the project allowlist"}}},"customer_suspended":{"summary":"Account suspended","value":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}},"key_category_not_allowed":{"summary":"The key may not use this category","value":{"detail":{"error":"key_category_not_allowed","message":"this API key may not use fetch (allowed: search)"}}}}}}},"404":{"description":"Not found, or not visible to this project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"job not found"}}}},"429":{"description":"A limit is reached. The project's rate limit (default 200 requests/s, one-second window; plain `detail`) or the key's own (`key_rate_limited`): retry after `Retry-After` (1 s). The key's monthly request quota (`key_quota_exhausted`) or spend cap (`key_budget_exhausted`): `Retry-After` is the time until the month resets; see `GET /v1/quota`.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policies (IETF draft): `\"project\";q=200;w=1` and, when the key has its own limit, `\"key\";q=10;w=1`.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window per policy: `\"project\";r=199;t=1`.","schema":{"type":"string"}}},"content":{"application/json":{"examples":{"rate_limited":{"summary":"Project rate limit","value":{"detail":"rate limit exceeded"}},"key_rate_limited":{"summary":"Key rate limit","value":{"detail":{"error":"key_rate_limited","message":"this API key may make 10 requests per second"}}},"key_quota_exhausted":{"summary":"Monthly request quota of the key used up","value":{"detail":{"error":"key_quota_exhausted","message":"this API key used its monthly fetch quota (100000 requests)","category":"fetch","limit":100000}}},"key_budget_exhausted":{"summary":"Monthly spend cap of the key reached","value":{"detail":{"error":"key_budget_exhausted","message":"this API key reached its monthly spend cap (50.00 USD)","limit":"50.00","currency":"USD"}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/companies/watches/{watch_id}":{"delete":{"tags":["companies"],"summary":"Delete a company watch","description":"Stops deliveries and removes the watch.","operationId":"deleteCompanyWatch","parameters":[{"name":"watch_id","in":"path","required":true,"schema":{"type":"string","description":"Watch id (`wch_…`).","examples":["wch_12"],"title":"Watch Id"},"description":"Watch id (`wch_…`)."}],"responses":{"204":{"description":"Deleted."},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this project.","content":{"application/json":{"example":{"detail":"job not found"},"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/companies/sources":{"get":{"tags":["companies"],"summary":"Company data sources","description":"Every source with countries, identifier schemes, capabilities,\nprecedence, licence/terms URL, freshness classes and live health (the\nsame status as the status page's \"Company data\" group). Not metered.","operationId":"companySources","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanySources"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"invalid API key"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/companies/batch":{"post":{"tags":["companies","batch"],"summary":"Create a company batch job","description":"Queues companies as a job of kind `company`: `get` (records, refreshing\nstale data), `refresh` (re-fetch everything) or `resolve`. Each item is\nmetered as one `company` request when it runs. Poll `GET /v1/jobs/{job_id}`\n(item results have the shape of `GET /v1/companies/{id}` under `record`,\nor of `POST /v1/companies/resolve`), or download\n`GET /v1/companies/batch/{job_id}.csv`. CSV input: `POST\n/v1/companies/batch/csv`.","operationId":"batchCompanies","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyBatchBody"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCreated"}}}},"200":{"description":"Existing job (same idempotency key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCreated"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"invalid API key"}}}},"403":{"description":"Not allowed: the key's customer account is suspended (`customer_suspended`, any `/v1` endpoint), a `user_agent` is not on the project's allowlist (`user_agent_not_allowed`, fetch endpoints), or the key may not use this category (`key_category_not_allowed`, search and fetch endpoints).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"examples":{"user_agent_not_allowed":{"summary":"User-Agent not on the project allowlist","value":{"detail":{"error":"user_agent_not_allowed","hint":"ask the operator to add this User-Agent to the project allowlist"}}},"customer_suspended":{"summary":"Account suspended","value":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}},"key_category_not_allowed":{"summary":"The key may not use this category","value":{"detail":{"error":"key_category_not_allowed","message":"this API key may not use fetch (allowed: search)"}}}}}}},"409":{"description":"The `idempotency_key` was already used for a job of a different kind or size.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"idempotency_key already used for a different job"}}}},"413":{"description":"Too many items for one job (at most 50,000).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"at most 50000 items per job"}}}},"429":{"description":"A limit is reached. The project's rate limit (default 200 requests/s, one-second window; plain `detail`) or the key's own (`key_rate_limited`): retry after `Retry-After` (1 s). The key's monthly request quota (`key_quota_exhausted`) or spend cap (`key_budget_exhausted`): `Retry-After` is the time until the month resets; see `GET /v1/quota`.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policies (IETF draft): `\"project\";q=200;w=1` and, when the key has its own limit, `\"key\";q=10;w=1`.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window per policy: `\"project\";r=199;t=1`.","schema":{"type":"string"}}},"content":{"application/json":{"examples":{"rate_limited":{"summary":"Project rate limit","value":{"detail":"rate limit exceeded"}},"key_rate_limited":{"summary":"Key rate limit","value":{"detail":{"error":"key_rate_limited","message":"this API key may make 10 requests per second"}}},"key_quota_exhausted":{"summary":"Monthly request quota of the key used up","value":{"detail":{"error":"key_quota_exhausted","message":"this API key used its monthly fetch quota (100000 requests)","category":"fetch","limit":100000}}},"key_budget_exhausted":{"summary":"Monthly spend cap of the key reached","value":{"detail":{"error":"key_budget_exhausted","message":"this API key reached its monthly spend cap (50.00 USD)","limit":"50.00","currency":"USD"}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/companies/batch/csv":{"post":{"tags":["companies","batch"],"summary":"Create a company batch job from CSV","description":"The same job as `POST /v1/companies/batch`, from a CSV upload.","operationId":"batchCompaniesCsv","parameters":[{"name":"idempotency_key","in":"query","required":true,"schema":{"type":"string","maxLength":200,"description":"Re-posting returns the same job.","title":"Idempotency Key"},"description":"Re-posting returns the same job."},{"name":"action","in":"query","required":false,"schema":{"enum":["get","refresh","resolve"],"type":"string","description":"What to do per row.","default":"get","title":"Action"},"description":"What to do per row."},{"name":"include","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated sub-resources (`get`/`refresh`).","title":"Include"},"description":"Comma-separated sub-resources (`get`/`refresh`)."},{"name":"max_age","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"As for `GET /v1/companies/{id}`.","title":"Max Age"},"description":"As for `GET /v1/companies/{id}`."},{"name":"persist","in":"query","required":false,"schema":{"type":"boolean","description":"`resolve`: add confident matches to the register.","default":true,"title":"Persist"},"description":"`resolve`: add confident matches to the register."},{"name":"callback_url","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"POSTed when the job finishes.","title":"Callback Url"},"description":"POSTed when the job finishes."}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCreated"}}}},"200":{"description":"Existing job (same idempotency key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCreated"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed: the key's customer account is suspended (`customer_suspended`, any `/v1` endpoint), a `user_agent` is not on the project's allowlist (`user_agent_not_allowed`, fetch endpoints), or the key may not use this category (`key_category_not_allowed`, search and fetch endpoints).","content":{"application/json":{"examples":{"user_agent_not_allowed":{"summary":"User-Agent not on the project allowlist","value":{"detail":{"error":"user_agent_not_allowed","hint":"ask the operator to add this User-Agent to the project allowlist"}}},"customer_suspended":{"summary":"Account suspended","value":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}},"key_category_not_allowed":{"summary":"The key may not use this category","value":{"detail":{"error":"key_category_not_allowed","message":"this API key may not use fetch (allowed: search)"}}}},"schema":{"$ref":"#/components/schemas/ErrorWithCode"}}}},"409":{"description":"The `idempotency_key` was already used for a job of a different kind or size.","content":{"application/json":{"example":{"detail":"idempotency_key already used for a different job"},"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Too many items for one job (at most 50,000).","content":{"application/json":{"example":{"detail":"at most 50000 items per job"},"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A limit is reached. The project's rate limit (default 200 requests/s, one-second window; plain `detail`) or the key's own (`key_rate_limited`): retry after `Retry-After` (1 s). The key's monthly request quota (`key_quota_exhausted`) or spend cap (`key_budget_exhausted`): `Retry-After` is the time until the month resets; see `GET /v1/quota`.","content":{"application/json":{"examples":{"rate_limited":{"summary":"Project rate limit","value":{"detail":"rate limit exceeded"}},"key_rate_limited":{"summary":"Key rate limit","value":{"detail":{"error":"key_rate_limited","message":"this API key may make 10 requests per second"}}},"key_quota_exhausted":{"summary":"Monthly request quota of the key used up","value":{"detail":{"error":"key_quota_exhausted","message":"this API key used its monthly fetch quota (100000 requests)","category":"fetch","limit":100000}}},"key_budget_exhausted":{"summary":"Monthly spend cap of the key reached","value":{"detail":{"error":"key_budget_exhausted","message":"this API key reached its monthly spend cap (50.00 USD)","limit":"50.00","currency":"USD"}}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policies (IETF draft): `\"project\";q=200;w=1` and, when the key has its own limit, `\"key\";q=10;w=1`.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window per policy: `\"project\";r=199;t=1`.","schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"requestBody":{"required":true,"description":"CSV with a header row: `ref,name,country,city,isin,identifiers` (any subset of these columns; identifiers separated by `;`).","content":{"text/csv":{"schema":{"type":"string"},"example":"ref,name,country,city,isin,identifiers\nlei:BFM8T61CT2L1QCEMIK50,,,,,\n,Nestlé,CH,Vevey,CH0038863350,\n"}}},"security":[{"bearerAuth":[]}]}},"/v1/companies/batch/{job_id}.csv":{"get":{"tags":["companies","batch"],"summary":"Company batch results as CSV","description":"One row per item: `index, input, status, company_id, name, country,\ncompany_status, legal_form, match_score, identifiers, error`.","operationId":"companyBatchCsv","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","description":"Job id.","title":"Job Id"},"description":"Job id."}],"responses":{"200":{"description":"CSV","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or not visible to this project.","content":{"application/json":{"example":{"detail":"job not found"},"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/schemas/company":{"get":{"tags":["companies"],"summary":"JSON Schema of company/v1","description":"The JSON Schema (2020-12) of the `company/v1` record, with the\nidentifier scheme catalogue in `x-identifier-schemes`.","operationId":"companySchema","responses":{"200":{"description":"JSON Schema (2020-12).","content":{"application/json":{"schema":{}},"application/schema+json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"detail":"invalid API key"}}}},"403":{"description":"The key's customer account is suspended (`customer_suspended`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWithCode"},"example":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/companies/{company_ref}":{"get":{"tags":["companies"],"summary":"Get a company record","description":"The full record from the register. A company not yet in the register is\nfetched from the sources that know the identifier and added. Each source's\ndata older than its freshness class (or `max_age`) is re-fetched first,\nconcurrently, for at most 2 s: a slower source, or one whose canaries\nfail, finishes in the background (`pending`; the record has its data on\nthe next call) and a source backing off is not asked (`skipped`), so the\nstored record is served at once with its `freshness`. `refresh` says per\nsource and group what was refreshed, fresh, pending, skipped or failed (a\nfailing source never fails the answer). Fields carry `provenance`; `include=claims` adds every\nclaim. A merged `cmp_` id answers with the surviving record\n(`redirected_from`).","operationId":"getCompany","parameters":[{"name":"company_ref","in":"path","required":true,"schema":{"type":"string","description":"`cmp_…` (merged ids redirect) or `scheme:value`, e.g. `ch_uid:CHE-101.329.561`, `lei:BFM8T61CT2L1QCEMIK50`, `us_cik:320193`, `isin:CH0038863350` (the issuer, via GLEIF's ISIN-to-LEI mapping).","examples":["lei:BFM8T61CT2L1QCEMIK50"],"title":"Company Ref"},"description":"`cmp_…` (merged ids redirect) or `scheme:value`, e.g. `ch_uid:CHE-101.329.561`, `lei:BFM8T61CT2L1QCEMIK50`, `us_cik:320193`, `isin:CH0038863350` (the issuer, via GLEIF's ISIN-to-LEI mapping)."},{"name":"max_age","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"Maximum acceptable age of each source's data in seconds; older data is re-fetched first. Default: the source's freshness class (e.g. registry core 24 h, people 7 days).","title":"Max Age"},"description":"Maximum acceptable age of each source's data in seconds; older data is re-fetched first. Default: the source's freshness class (e.g. registry core 24 h, people 7 days)."},{"name":"refresh","in":"query","required":false,"schema":{"type":"boolean","description":"`true` re-fetches from every source now.","default":false,"title":"Refresh"},"description":"`true` re-fetches from every source now."},{"name":"include","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated: `people`, `ownership`, `filings`, `financials`, `events`, `claims`.","examples":["people,ownership"],"title":"Include"},"description":"Comma-separated: `people`, `ownership`, `filings`, `financials`, `events`, `claims`."},{"name":"sources","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated source names: use (and show values from) only these.","examples":["gleif"],"title":"Sources"},"description":"Comma-separated source names: use (and show values from) only these."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyRecord"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed: the key's customer account is suspended (`customer_suspended`, any `/v1` endpoint), a `user_agent` is not on the project's allowlist (`user_agent_not_allowed`, fetch endpoints), or the key may not use this category (`key_category_not_allowed`, search and fetch endpoints).","content":{"application/json":{"examples":{"user_agent_not_allowed":{"summary":"User-Agent not on the project allowlist","value":{"detail":{"error":"user_agent_not_allowed","hint":"ask the operator to add this User-Agent to the project allowlist"}}},"customer_suspended":{"summary":"Account suspended","value":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}},"key_category_not_allowed":{"summary":"The key may not use this category","value":{"detail":{"error":"key_category_not_allowed","message":"this API key may not use fetch (allowed: search)"}}}},"schema":{"$ref":"#/components/schemas/ErrorWithCode"}}}},"404":{"description":"Not found, or not visible to this project.","content":{"application/json":{"example":{"detail":"job not found"},"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A limit is reached. The project's rate limit (default 200 requests/s, one-second window; plain `detail`) or the key's own (`key_rate_limited`): retry after `Retry-After` (1 s). The key's monthly request quota (`key_quota_exhausted`) or spend cap (`key_budget_exhausted`): `Retry-After` is the time until the month resets; see `GET /v1/quota`.","content":{"application/json":{"examples":{"rate_limited":{"summary":"Project rate limit","value":{"detail":"rate limit exceeded"}},"key_rate_limited":{"summary":"Key rate limit","value":{"detail":{"error":"key_rate_limited","message":"this API key may make 10 requests per second"}}},"key_quota_exhausted":{"summary":"Monthly request quota of the key used up","value":{"detail":{"error":"key_quota_exhausted","message":"this API key used its monthly fetch quota (100000 requests)","category":"fetch","limit":100000}}},"key_budget_exhausted":{"summary":"Monthly spend cap of the key reached","value":{"detail":{"error":"key_budget_exhausted","message":"this API key reached its monthly spend cap (50.00 USD)","limit":"50.00","currency":"USD"}}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policies (IETF draft): `\"project\";q=200;w=1` and, when the key has its own limit, `\"key\";q=10;w=1`.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window per policy: `\"project\";r=199;t=1`.","schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/companies/{company_ref}/history":{"get":{"tags":["companies"],"summary":"Field history of a company (claims timeline)","description":"Every value each source asserted, newest observation first: when it\nwas first seen (`observed_at`), confirmed, and when it stopped being\ncurrent (`valid_to`, `current: false`). Claims are never overwritten.","operationId":"companyHistory","parameters":[{"name":"company_ref","in":"path","required":true,"schema":{"type":"string","description":"`cmp_…` (merged ids redirect) or `scheme:value`, e.g. `ch_uid:CHE-101.329.561`, `lei:BFM8T61CT2L1QCEMIK50`, `us_cik:320193`, `isin:CH0038863350` (the issuer, via GLEIF's ISIN-to-LEI mapping).","examples":["lei:BFM8T61CT2L1QCEMIK50"],"title":"Company Ref"},"description":"`cmp_…` (merged ids redirect) or `scheme:value`, e.g. `ch_uid:CHE-101.329.561`, `lei:BFM8T61CT2L1QCEMIK50`, `us_cik:320193`, `isin:CH0038863350` (the issuer, via GLEIF's ISIN-to-LEI mapping)."},{"name":"field","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only this field, e.g. `names.legal` or `addresses`.","title":"Field"},"description":"Only this field, e.g. `names.legal` or `addresses`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Claims per page.","default":100,"title":"Limit"},"description":"Claims per page."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`next_cursor` of the previous page.","title":"Cursor"},"description":"`next_cursor` of the previous page."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyPage"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed: the key's customer account is suspended (`customer_suspended`, any `/v1` endpoint), a `user_agent` is not on the project's allowlist (`user_agent_not_allowed`, fetch endpoints), or the key may not use this category (`key_category_not_allowed`, search and fetch endpoints).","content":{"application/json":{"examples":{"user_agent_not_allowed":{"summary":"User-Agent not on the project allowlist","value":{"detail":{"error":"user_agent_not_allowed","hint":"ask the operator to add this User-Agent to the project allowlist"}}},"customer_suspended":{"summary":"Account suspended","value":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}},"key_category_not_allowed":{"summary":"The key may not use this category","value":{"detail":{"error":"key_category_not_allowed","message":"this API key may not use fetch (allowed: search)"}}}},"schema":{"$ref":"#/components/schemas/ErrorWithCode"}}}},"404":{"description":"Not found, or not visible to this project.","content":{"application/json":{"example":{"detail":"job not found"},"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A limit is reached. The project's rate limit (default 200 requests/s, one-second window; plain `detail`) or the key's own (`key_rate_limited`): retry after `Retry-After` (1 s). The key's monthly request quota (`key_quota_exhausted`) or spend cap (`key_budget_exhausted`): `Retry-After` is the time until the month resets; see `GET /v1/quota`.","content":{"application/json":{"examples":{"rate_limited":{"summary":"Project rate limit","value":{"detail":"rate limit exceeded"}},"key_rate_limited":{"summary":"Key rate limit","value":{"detail":{"error":"key_rate_limited","message":"this API key may make 10 requests per second"}}},"key_quota_exhausted":{"summary":"Monthly request quota of the key used up","value":{"detail":{"error":"key_quota_exhausted","message":"this API key used its monthly fetch quota (100000 requests)","category":"fetch","limit":100000}}},"key_budget_exhausted":{"summary":"Monthly spend cap of the key reached","value":{"detail":{"error":"key_budget_exhausted","message":"this API key reached its monthly spend cap (50.00 USD)","limit":"50.00","currency":"USD"}}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policies (IETF draft): `\"project\";q=200;w=1` and, when the key has its own limit, `\"key\";q=10;w=1`.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window per policy: `\"project\";r=199;t=1`.","schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/companies/{company_ref}/{resource}":{"get":{"tags":["companies"],"summary":"A company's events, people, ownership, relationships, filings, financials or sources","description":"One sub-resource with paging, refreshed like the record (the field\ngroup of the sub-resource, e.g. `people` 7 days). `sources` lists the raw\ndocuments with `body_url`.","operationId":"companySubresource","parameters":[{"name":"company_ref","in":"path","required":true,"schema":{"type":"string","description":"`cmp_…` (merged ids redirect) or `scheme:value`, e.g. `ch_uid:CHE-101.329.561`, `lei:BFM8T61CT2L1QCEMIK50`, `us_cik:320193`, `isin:CH0038863350` (the issuer, via GLEIF's ISIN-to-LEI mapping).","examples":["lei:BFM8T61CT2L1QCEMIK50"],"title":"Company Ref"},"description":"`cmp_…` (merged ids redirect) or `scheme:value`, e.g. `ch_uid:CHE-101.329.561`, `lei:BFM8T61CT2L1QCEMIK50`, `us_cik:320193`, `isin:CH0038863350` (the issuer, via GLEIF's ISIN-to-LEI mapping)."},{"name":"resource","in":"path","required":true,"schema":{"enum":["events","people","ownership","relationships","filings","financials","sources"],"type":"string","description":"Sub-resource.","title":"Resource"},"description":"Sub-resource."},{"name":"max_age","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"Maximum acceptable age of each source's data in seconds; older data is re-fetched first. Default: the source's freshness class (e.g. registry core 24 h, people 7 days).","title":"Max Age"},"description":"Maximum acceptable age of each source's data in seconds; older data is re-fetched first. Default: the source's freshness class (e.g. registry core 24 h, people 7 days)."},{"name":"refresh","in":"query","required":false,"schema":{"type":"boolean","description":"`true` re-fetches from every source now.","default":false,"title":"Refresh"},"description":"`true` re-fetches from every source now."},{"name":"include_former","in":"query","required":false,"schema":{"type":"boolean","description":"`people`: also former officers.","default":false,"title":"Include Former"},"description":"`people`: also former officers."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Items per page.","default":100,"title":"Limit"},"description":"Items per page."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`next_cursor` of the previous page.","title":"Cursor"},"description":"`next_cursor` of the previous page."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyPage"}}}},"401":{"description":"Missing or invalid API key (`WWW-Authenticate: Bearer`).","content":{"application/json":{"example":{"detail":"invalid API key"},"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed: the key's customer account is suspended (`customer_suspended`, any `/v1` endpoint), a `user_agent` is not on the project's allowlist (`user_agent_not_allowed`, fetch endpoints), or the key may not use this category (`key_category_not_allowed`, search and fetch endpoints).","content":{"application/json":{"examples":{"user_agent_not_allowed":{"summary":"User-Agent not on the project allowlist","value":{"detail":{"error":"user_agent_not_allowed","hint":"ask the operator to add this User-Agent to the project allowlist"}}},"customer_suspended":{"summary":"Account suspended","value":{"detail":{"error":"customer_suspended","message":"this account is suspended; contact the operator"}}},"key_category_not_allowed":{"summary":"The key may not use this category","value":{"detail":{"error":"key_category_not_allowed","message":"this API key may not use fetch (allowed: search)"}}}},"schema":{"$ref":"#/components/schemas/ErrorWithCode"}}}},"404":{"description":"Not found, or not visible to this project.","content":{"application/json":{"example":{"detail":"job not found"},"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A limit is reached. The project's rate limit (default 200 requests/s, one-second window; plain `detail`) or the key's own (`key_rate_limited`): retry after `Retry-After` (1 s). The key's monthly request quota (`key_quota_exhausted`) or spend cap (`key_budget_exhausted`): `Retry-After` is the time until the month resets; see `GET /v1/quota`.","content":{"application/json":{"examples":{"rate_limited":{"summary":"Project rate limit","value":{"detail":"rate limit exceeded"}},"key_rate_limited":{"summary":"Key rate limit","value":{"detail":{"error":"key_rate_limited","message":"this API key may make 10 requests per second"}}},"key_quota_exhausted":{"summary":"Monthly request quota of the key used up","value":{"detail":{"error":"key_quota_exhausted","message":"this API key used its monthly fetch quota (100000 requests)","category":"fetch","limit":100000}}},"key_budget_exhausted":{"summary":"Monthly spend cap of the key reached","value":{"detail":{"error":"key_budget_exhausted","message":"this API key reached its monthly spend cap (50.00 USD)","limit":"50.00","currency":"USD"}}}}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Rate-limit policies (IETF draft): `\"project\";q=200;w=1` and, when the key has its own limit, `\"key\";q=10;w=1`.","schema":{"type":"string"}},"RateLimit":{"description":"What is left in the current window per policy: `\"project\";r=199;t=1`.","schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/health":{"get":{"tags":["health"],"summary":"Liveness","description":"`200 {\"status\": \"ok\"}` while the API process is up.","operationId":"health","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health","additionalProperties":{"type":"string"},"type":"object","title":"Response Health"}}}}}}},"/ready":{"get":{"tags":["health"],"summary":"Readiness","description":"`200` when PostgreSQL and Redis answer and at least one SearXNG instance is\nregistered, else `503`. Object storage is reported but does not gate\nreadiness.","operationId":"ready","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ready"}}}},"503":{"description":"A required dependency is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ready"}}}}}}}},"webhooks":{"job-completed":{"post":{"tags":["batch"],"summary":"Job completed (callback)","description":"Sent as `POST <callback_url>` with this JSON body when a batch job finishes\n(completed or cancelled). Delivered up to 3 times with backoff; any 2xx\nanswer counts as delivered (`callback_status` on the job). Private and\nloopback addresses are refused. Treat it as a hint and read the job with\n`GET /v1/jobs/{job_id}`; poll as a fallback.","operationId":"jobCompleted","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallbackPayload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"usage-threshold":{"post":{"tags":["usage"],"summary":"Usage threshold crossed (alert webhook)","description":"Sent as `POST <url>` of a webhook registered with `POST /v1/alerts` when a\nkey, project or the account crosses 50, 80 or 100 % of a limit or allowance\nin a month (each threshold once per month). Headers: `X-Cormorant-Event:\nusage.threshold`, `X-Cormorant-Delivery: dlv_…` and `X-Cormorant-Signature:\nt=<unix seconds>,v1=<hex>` where `v1` is HMAC-SHA256 of `\"<t>.<raw body>\"`\nunder the webhook's secret — compare in constant time and reject old `t`.\nAny 2xx counts as delivered; otherwise retried after 1, 5, 15, 60, 180, 360\nand 720 minutes. Treat the id (`evt_…`) as idempotency key.","operationId":"usageThreshold","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertEvent"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"company-changed":{"post":{"tags":["companies"],"summary":"Watched companies changed (webhook)","description":"Sent as `POST <url>` of a watch registered with `POST\n/v1/companies/watches` when watched companies change (checked every\nminute; up to 500 changes per delivery, oldest first). Headers:\n`X-Cormorant-Event: company.changed`, `X-Cormorant-Delivery: dlv_…` and\n`X-Cormorant-Signature: t=<unix seconds>,v1=<hex>` (HMAC-SHA256 of\n`\"<t>.<raw body>\"` under the watch's secret). Any 2xx counts as\ndelivered; otherwise retried after 1, 5, 15, 60 and 180 minutes, then\nhourly, without skipping changes. Use `id` as idempotency key and fetch\nthe records for the new values.","operationId":"companyChanged","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyChangedEvent"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Account":{"properties":{"project":{"$ref":"#/components/schemas/AccountProject","description":"Project of the API key."},"period":{"$ref":"#/components/schemas/AccountPeriod","description":"Current billing period."},"usage_refreshed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage Refreshed At","description":"When usage was last aggregated (every 5 minutes).","examples":["2026-10-19T11:00:04+00:00"]},"project_usage":{"additionalProperties":{"$ref":"#/components/schemas/CategoryUsage"},"type":"object","title":"Project Usage","description":"This project's usage this period, by billing category."},"customer":{"anyOf":[{"$ref":"#/components/schemas/AccountCustomer"},{"type":"null"}],"description":"The owning customer; `null` for projects without one."},"customer_usage":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/CategoryUsage"},"type":"object"},{"type":"null"}],"title":"Customer Usage","description":"The customer's usage (all its projects); absent without a customer."},"plan":{"anyOf":[{"$ref":"#/components/schemas/PlanSummary"},{"type":"null"}],"description":"Price plan of the period; `null` without one."},"estimate":{"anyOf":[{"$ref":"#/components/schemas/Estimate"},{"type":"null"}],"description":"Charges so far this period; `null` without a customer."},"keys":{"items":{"$ref":"#/components/schemas/AccountKey"},"type":"array","title":"Keys","description":"This period per API key. Account admin key: all keys of the customer's projects (or of this project without a customer), plus usage recorded before per-key attribution (`prefix` null). Additional key: only itself."}},"type":"object","required":["project","period","usage_refreshed_at","project_usage","customer","plan","estimate","keys"],"title":"Account","description":"Answer of `GET /v1/account`."},"AccountCustomer":{"properties":{"name":{"type":"string","title":"Name","description":"Customer name.","examples":["Acme"]},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Legal company name.","examples":["Acme Research AG"]},"currency":{"type":"string","enum":["USD","CHF","EUR"],"title":"Currency","description":"Invoice currency.","examples":["USD"]},"status":{"type":"string","enum":["active","suspended"],"title":"Status","description":"Account status; keys of suspended accounts get `403 customer_suspended`.","examples":["active"]},"complimentary":{"type":"boolean","title":"Complimentary","description":"Complimentary accounts are rated at list price and then discounted 100 %.","examples":[true]}},"type":"object","required":["name","company_name","currency","status","complimentary"],"title":"AccountCustomer","description":"The billed account that owns the project."},"AccountKey":{"properties":{"prefix":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prefix","description":"First 10 characters of the key; `null` for usage recorded before per-key attribution.","examples":["cmr_AbCdEf"]},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label","description":"Label set by the operator.","examples":["crawler"]},"role":{"anyOf":[{"type":"string","enum":["account_admin","standard"]},{"type":"null"}],"title":"Role","description":"`account_admin` (prefix `cma_`) or `standard` (`cmr_`); `null` for usage recorded before per-key attribution.","examples":["standard"]},"project":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project","description":"Project of the key.","examples":["acme-crawler"]},"active":{"type":"boolean","title":"Active","description":"The key is not revoked.","examples":[true]},"requests":{"type":"integer","title":"Requests","description":"Requests this period.","examples":[9120]},"succeeded":{"type":"integer","title":"Succeeded","description":"Successful requests.","examples":[8800]},"usage":{"additionalProperties":{"$ref":"#/components/schemas/CategoryUsage"},"type":"object","title":"Usage","description":"Usage by billing category."},"amount":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Amount","description":"The key's share of the period's usage charges at list price (before account-level fees, discounts and the complimentary credit; Decimal as a string, in the invoice currency.) — `null` without a customer.","examples":["12.40"]}},"type":"object","required":["prefix","label","role","project","active","requests","succeeded","usage","amount"],"title":"AccountKey","description":"Month-to-date usage of one API key of the customer (or of the project\nwithout a customer). Keys are identified by prefix and label only."},"AccountLine":{"properties":{"kind":{"type":"string","title":"Kind","description":"`base_fee`, `minimum`, `discount` or `complimentary`.","examples":["complimentary"]},"description":{"type":"string","title":"Description","description":"Line text.","examples":["Complimentary plan: 100 % discount"]},"amount":{"type":"string","title":"Amount","description":"Decimal string in `currency`.","examples":["-15.60"]}},"type":"object","required":["kind","description","amount"],"title":"AccountLine","description":"An account-level line of a period (not attributed to keys)."},"AccountPeriod":{"properties":{"period":{"type":"string","title":"Period","description":"`YYYY-MM`.","examples":["2026-10"]},"from":{"type":"string","title":"From","description":"First day.","examples":["2026-10-01"]},"to":{"type":"string","title":"To","description":"Last day.","examples":["2026-10-31"]}},"type":"object","required":["period","from","to"],"title":"AccountPeriod","description":"The current billing period (calendar month, UTC)."},"AccountProject":{"properties":{"id":{"type":"integer","title":"Id","description":"Project id.","examples":[7]},"name":{"type":"string","title":"Name","description":"Project name.","examples":["acme-crawler"]}},"type":"object","required":["id","name"],"title":"AccountProject","description":"The key's project."},"Activity":{"properties":{"scheme":{"type":"string","enum":["nace","noga","wz","sic","naics","isic"],"title":"Scheme","description":"Classification.","examples":["nace"]},"code":{"type":"string","title":"Code","description":"Code as published.","examples":["62.01"]},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label","description":"Label of the code (English)."},"primary":{"type":"boolean","title":"Primary","description":"Main activity.","default":false},"nace":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nace","description":"NACE Rev. 2 class of a NOGA/WZ code."}},"additionalProperties":false,"type":"object","required":["scheme","code"],"title":"Activity","description":"An economic activity classification."},"Address":{"properties":{"type":{"type":"string","enum":["registered","business","postal","branch","other"],"title":"Type","description":"Kind of address.","examples":["registered"]},"lines":{"items":{"type":"string"},"type":"array","title":"Lines","description":"Address lines as published."},"street":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Street","description":"Street."},"house_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"House Number","description":"House number."},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Postal Code","description":"Postal code."},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City","description":"City or locality."},"municipality_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Municipality Code","description":"Official municipality code (e.g. Swiss BFS number)."},"region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region","description":"Region (ISO 3166-2 when known)."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"ISO 3166-1 alpha-2."},"geo":{"anyOf":[{"$ref":"#/components/schemas/Geo"},{"type":"null"}],"description":"Coordinates, if the source gives them."},"valid_from":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Valid From","description":"Start of validity (date)."},"valid_to":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Valid To","description":"End of validity (date)."}},"additionalProperties":false,"type":"object","required":["type"],"title":"Address","description":"A postal address of the company."},"AlertEvent":{"properties":{"id":{"type":"string","title":"Id","description":"Event id (`evt_…`); deliveries may repeat it.","examples":["evt_42"]},"created_at":{"type":"string","title":"Created At","description":"When it fired.","examples":["2026-10-19T11:05:03+00:00"]},"type":{"type":"string","const":"usage.threshold","title":"Type","description":"Event type.","examples":["usage.threshold"]},"scope":{"type":"string","enum":["key","project","customer"],"title":"Scope","description":"What crossed the threshold.","examples":["key"]},"customer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer","description":"Customer.","examples":["Acme"]},"project":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project","description":"Project (key and project events).","examples":["acme-crawler"]},"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key","description":"Key prefix (key events).","examples":["cmr_AbCdEf"]},"key_role":{"anyOf":[{"type":"string","enum":["account_admin","standard"]},{"type":"null"}],"title":"Key Role","description":"Role of that key.","examples":["standard"]},"limit":{"$ref":"#/components/schemas/AlertLimit","description":"The limit and its use."}},"type":"object","required":["id","created_at","type","scope","customer","project","key","key_role","limit"],"title":"AlertEvent","description":"A threshold crossed: in `GET /v1/quota` `events` and the body of webhook\ndeliveries."},"AlertHook":{"properties":{"id":{"type":"integer","title":"Id","description":"Webhook id.","examples":[7]},"url":{"type":"string","title":"Url","description":"Delivery URL.","examples":["https://hooks.example.com/cormorant"]},"scope":{"type":"string","enum":["key","project","customer"],"title":"Scope","description":"What it watches: one key, one project (and its keys) or the whole account.","examples":["key"]},"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key","description":"With `scope=key`: key prefix.","examples":["cmr_AbCdEf"]},"project":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project","description":"With `scope=project`: project name.","examples":[null]},"thresholds":{"items":{"type":"integer"},"type":"array","title":"Thresholds","description":"Percentages delivered.","examples":[[50,80,100]]},"created_at":{"type":"string","title":"Created At","description":"Registration time.","examples":["2026-10-19T11:00:00+00:00"]},"last_delivery_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Delivery At","description":"Last delivery attempt.","examples":[null]},"last_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Status","description":"`delivered_<status>`, `http_<status>`, `error_<type>` or `blocked_destination`.","examples":["delivered_200"]}},"type":"object","required":["id","url","scope","key","project","thresholds","created_at","last_delivery_at","last_status"],"title":"AlertHook","description":"A registered alert webhook (never its secret)."},"AlertHookCreated":{"properties":{"id":{"type":"integer","title":"Id","description":"Webhook id.","examples":[7]},"url":{"type":"string","title":"Url","description":"Delivery URL.","examples":["https://hooks.example.com/cormorant"]},"scope":{"type":"string","enum":["key","project","customer"],"title":"Scope","description":"What it watches: one key, one project (and its keys) or the whole account.","examples":["key"]},"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key","description":"With `scope=key`: key prefix.","examples":["cmr_AbCdEf"]},"project":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project","description":"With `scope=project`: project name.","examples":[null]},"thresholds":{"items":{"type":"integer"},"type":"array","title":"Thresholds","description":"Percentages delivered.","examples":[[50,80,100]]},"created_at":{"type":"string","title":"Created At","description":"Registration time.","examples":["2026-10-19T11:00:00+00:00"]},"last_delivery_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Delivery At","description":"Last delivery attempt.","examples":[null]},"last_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Status","description":"`delivered_<status>`, `http_<status>`, `error_<type>` or `blocked_destination`.","examples":["delivered_200"]},"secret":{"type":"string","title":"Secret","description":"Signing secret (`whsec_…`), shown **only here**: verify `X-Cormorant-Signature` with it.","examples":["whsec_9f2c…"]}},"type":"object","required":["id","url","scope","key","project","thresholds","created_at","last_delivery_at","last_status","secret"],"title":"AlertHookCreated","description":"Answer of `POST /v1/alerts`."},"AlertHookList":{"properties":{"alerts":{"items":{"$ref":"#/components/schemas/AlertHook"},"type":"array","title":"Alerts","description":"Webhooks visible to the caller."}},"type":"object","required":["alerts"],"title":"AlertHookList","description":"Answer of `GET /v1/alerts`."},"AlertIn":{"properties":{"url":{"type":"string","maxLength":2000,"title":"Url","description":"HTTPS endpoint that receives `POST` deliveries (public address).","examples":["https://hooks.example.com/cormorant"]},"scope":{"anyOf":[{"type":"string","enum":["key","project","customer"]},{"type":"null"}],"title":"Scope","description":"`key` (default for standard keys; their own key only), `project` or `customer` (default for account admin keys: the whole account)."},"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key","description":"With `scope=key`: the key's prefix (account admin keys); default the calling key.","examples":["cmr_AbCdEf"]},"project":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project","description":"With `scope=project`: project name.","examples":["acme-crawler"]},"thresholds":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Thresholds","description":"Any of 50, 80, 100 (percent); default all three.","examples":[[80,100]]}},"additionalProperties":false,"type":"object","required":["url"],"title":"AlertIn"},"AlertLimit":{"properties":{"name":{"type":"string","title":"Name","description":"`monthly_spend`, `monthly_requests.<category>`, `monthly_provider_budget` or `included.<meter>`.","examples":["monthly_spend"]},"unit":{"type":"string","title":"Unit","description":"Currency, `requests` or the meter's unit.","examples":["USD"]},"limit":{"anyOf":[{"type":"integer"},{"type":"string"}],"title":"Limit","description":"The limit (money as a decimal string).","examples":["50.00"]},"used":{"anyOf":[{"type":"integer"},{"type":"string"}],"title":"Used","description":"Used when the event fired.","examples":["40.12"]},"threshold":{"type":"integer","title":"Threshold","description":"Percent crossed: 50, 80 or 100.","examples":[80]},"period":{"type":"string","title":"Period","description":"Month (`YYYY-MM`, UTC).","examples":["2026-10"]},"resets_at":{"type":"string","title":"Resets At","description":"When the limit resets.","examples":["2026-11-01T00:00:00+00:00"]}},"type":"object","required":["name","unit","limit","used","threshold","period","resets_at"],"title":"AlertLimit","description":"The limit an alert is about."},"ApiKeyInfo":{"properties":{"prefix":{"type":"string","title":"Prefix","description":"First 10 characters; `cma_…` = account admin key, `cmr_…` = standard key.","examples":["cmr_AbCdEf"]},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label","description":"Label set by the operator.","examples":["crawler"]},"role":{"type":"string","enum":["account_admin","standard"],"title":"Role","description":"`account_admin` sees the whole customer account; `standard` only itself.","examples":["standard"]},"project":{"type":"string","title":"Project","description":"Project the key belongs to.","examples":["acme-crawler"]},"status":{"type":"string","enum":["active","revoked"],"title":"Status","description":"Key status.","examples":["active"]},"created_at":{"type":"string","title":"Created At","description":"Creation time.","examples":["2026-09-01T08:00:00+00:00"]},"revoked_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revoked At","description":"Revocation time.","examples":[null]},"last_used_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Used At","description":"Last authenticated request (accurate to about a minute).","examples":["2026-10-19T11:02:00+00:00"]},"is_self":{"type":"boolean","title":"Is Self","description":"This is the calling key.","examples":[true]},"limits":{"anyOf":[{"$ref":"#/components/schemas/KeyLimitsInfo"},{"type":"null"}],"description":"Limits set by the operator; `null` = none (only the project's)."}},"type":"object","required":["prefix","label","role","project","status","created_at","revoked_at","last_used_at","is_self","limits"],"title":"ApiKeyInfo","description":"An API key as its customer sees it: prefix, label and role, never the key."},"ApiKeyList":{"properties":{"role":{"type":"string","enum":["account_admin","standard"],"title":"Role","description":"Role of the calling key.","examples":["account_admin"]},"keys":{"items":{"$ref":"#/components/schemas/ApiKeyInfo"},"type":"array","title":"Keys","description":"Account admin key: every key of the customer's projects (or of the project without a customer), revoked keys included. Standard key: only itself."}},"type":"object","required":["role","keys"],"title":"ApiKeyList","description":"Answer of `GET /v1/keys`."},"ApiKeySelf":{"properties":{"prefix":{"type":"string","title":"Prefix","description":"First 10 characters; `cma_…` = account admin key, `cmr_…` = standard key.","examples":["cmr_AbCdEf"]},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label","description":"Label set by the operator.","examples":["crawler"]},"role":{"type":"string","enum":["account_admin","standard"],"title":"Role","description":"`account_admin` sees the whole customer account; `standard` only itself.","examples":["standard"]},"project":{"type":"string","title":"Project","description":"Project the key belongs to.","examples":["acme-crawler"]},"status":{"type":"string","enum":["active","revoked"],"title":"Status","description":"Key status.","examples":["active"]},"created_at":{"type":"string","title":"Created At","description":"Creation time.","examples":["2026-09-01T08:00:00+00:00"]},"revoked_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revoked At","description":"Revocation time.","examples":[null]},"last_used_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Used At","description":"Last authenticated request (accurate to about a minute).","examples":["2026-10-19T11:02:00+00:00"]},"is_self":{"type":"boolean","title":"Is Self","description":"This is the calling key.","examples":[true]},"limits":{"anyOf":[{"$ref":"#/components/schemas/KeyLimitsInfo"},{"type":"null"}],"description":"Limits set by the operator; `null` = none (only the project's)."},"usage":{"anyOf":[{"$ref":"#/components/schemas/QuotaKeyUsage"},{"type":"null"}],"description":"Use this month."},"quota":{"items":{"$ref":"#/components/schemas/QuotaEntry"},"type":"array","title":"Quota","description":"Each limit of the key, as in `GET /v1/quota`."}},"type":"object","required":["prefix","label","role","project","status","created_at","revoked_at","last_used_at","is_self","limits","usage","quota"],"title":"ApiKeySelf","description":"Answer of `GET /v1/keys/self`: the calling key and its quota state."},"ArticleMeta":{"properties":{"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author","description":"Author name(s); several are separated by `; `.","examples":["Anna Muster; Beat Beispiel"]},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published At","description":"Publication date, ISO 8601: `YYYY-MM-DDTHH:MM:SSZ` (UTC) when the page gives a time zone, without zone when it gives a time but no zone, `YYYY-MM-DD` (or `YYYY-MM`, `YYYY`) when it gives only a date.","examples":["2026-03-19T08:30:00Z"]},"modified_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modified At","description":"Last modification date (same format as `published_at`).","examples":["2026-03-19T10:05:12Z"]},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"Language tag (BCP 47), e.g. from JSON-LD `inLanguage` or `<html lang>`.","examples":["de-CH"]},"canonical_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Url","description":"Canonical URL the page declares (`<link rel=canonical>`, else JSON-LD `url` / `og:url`), absolute.","examples":["https://www.example.com/news/central-bank-cuts-rates"]},"publisher":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publisher","description":"Publishing organisation.","examples":["Example Media AG"]},"site_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Site Name","description":"Name of the site or periodical (`og:site_name`, JSON-LD `WebSite`, `citation_journal_title`).","examples":["Example News"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Summary the page gives of itself (at most 2,000 characters).","examples":["The central bank cut its policy rate by 0.25 percentage points."]},"section":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Section","description":"Section or category (first `articleSection` / `article:section`).","examples":["Economy"]},"word_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Word Count","description":"Words in `text` (what was retrieved, not what the page declares).","examples":[1240]}},"type":"object","required":["author","published_at","modified_at","language","canonical_url","publisher","site_name","description","section","word_count"],"title":"ArticleMeta","description":"Article metadata of an HTML page, from JSON-LD, OpenGraph/`article:*`,\n`citation_*` meta tags and the HTML itself. Each field is `null` when the\npage does not say."},"Attempt":{"properties":{"tier":{"type":"string","title":"Tier","description":"Tier name (`direct`, `browser`, `archive`, `proxy`, `proxy_render`), `source` for the alternative-source steps, or a pseudo-step such as `request_timeout` or `dns` (the host name does not exist, see `domain_dead`).","examples":["direct"]},"status":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status","description":"HTTP status seen, if any.","examples":[200]},"reason":{"type":"string","title":"Reason","description":"Outcome: `ok`, `thin_content`, `not_modified`, `challenge_<vendor>`, `http_<status>`, `timeout`, `tls_error`, `dns_error`, `dns_nxdomain`, `domain_dead`, `network_*`, `not_configured`, `budget_exhausted`, `premium_skipped_domain_refuses`, `hard_domain_skip`, `archive_not_found`, premium-route reasons (`…_captcha_rejected`, `…_no_credits`, `…_render_503`), `paywall`, `paywall_skip_premium`, `archive_blocked_paywall`, `alternate_<source>`, `syndication_candidates_<n>`, …","examples":["ok"]},"ms":{"type":"integer","title":"Ms","description":"Time spent on this attempt in milliseconds.","examples":[412]},"premium_bytes":{"type":"integer","title":"Premium Bytes","description":"Bytes the residential network billed for this attempt (premium route `proxy`; `0` for standard routes and `proxy_render`, which bills per call).","default":0,"examples":[0]},"wait_ms":{"type":"integer","title":"Wait Ms","description":"Part of `ms` spent waiting for a polite per-domain slot (busy domain).","default":0,"examples":[0]},"upstream_ms":{"type":"integer","title":"Upstream Ms","description":"Part of `ms` spent on the tier itself: the site, the browser, the archive or the premium route's provider (`ms - wait_ms`).","default":0,"examples":[412]},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail","description":"Present only when set: for `proxy_render`, the rendering difficulty used (`low`, `medium`, `high`); for `alternate_<source>`, the copy's URL.","examples":["medium"]}},"type":"object","required":["tier","status","reason","ms"],"title":"Attempt","description":"One tier tried while answering the request, in order."},"BatchFetchBody":{"properties":{"items":{"items":{"$ref":"#/components/schemas/FetchBody"},"type":"array","minItems":1,"title":"Items","description":"Fetch requests, same fields as `POST /v1/fetch` (`include_html` defaults to `false` here)."},"idempotency_key":{"type":"string","maxLength":200,"minLength":1,"title":"Idempotency Key","description":"Your unique key for this job. Re-posting the same key returns the existing job (`200`, `created: false`); the same key with a different kind or item count is `409`.","examples":["chipiron-run-2026-10-20-fetch-0001"]},"callback_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Callback Url","description":"Optional http(s) URL that receives a `POST` with the job summary when the job completes (3 attempts; private addresses are refused).","examples":["https://chipiron.example/hooks/cormorant"]}},"type":"object","required":["items","idempotency_key"],"title":"BatchFetchBody","description":"Up to 50,000 fetches processed asynchronously as one job.","examples":[{"callback_url":"https://chipiron.example/hooks/cormorant","idempotency_key":"chipiron-run-2026-10-20-fetch-0001","items":[{"url":"https://example.com"},{"url":"https://example.org"}]}]},"BatchItem":{"properties":{"ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ref","description":"`cmp_…` or `scheme:value` (for `get`/`refresh`)."},"name":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Name","description":"Name (for `resolve`)."},"country":{"anyOf":[{"type":"string","pattern":"^[A-Za-z]{2}$"},{"type":"null"}],"title":"Country","description":"ISO 3166-1 alpha-2."},"city":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"City","description":"City (for `resolve`)."},"identifiers":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Identifiers","description":"`scheme:value` (for `resolve`)."},"isin":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Isin","description":"ISIN (for `resolve`; same as `isin:<value>` in `identifiers`)."}},"type":"object","title":"BatchItem"},"BatchSearchBody":{"properties":{"items":{"items":{"$ref":"#/components/schemas/SearchBody"},"type":"array","minItems":1,"title":"Items","description":"Search requests, same fields as `POST /v1/search`."},"idempotency_key":{"type":"string","maxLength":200,"minLength":1,"title":"Idempotency Key","description":"Your unique key for this job. Re-posting the same key returns the existing job (`200`, `created: false`); the same key with a different kind or item count is `409`.","examples":["chipiron-run-2026-10-20-search-0001"]},"callback_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Callback Url","description":"Optional http(s) URL that receives a `POST` with the job summary when the job completes (3 attempts; private addresses are refused).","examples":["https://chipiron.example/hooks/cormorant"]}},"type":"object","required":["items","idempotency_key"],"title":"BatchSearchBody","description":"Up to 50,000 searches processed asynchronously as one job.","examples":[{"idempotency_key":"chipiron-run-2026-10-20-search-0001","items":[{"query":"Holcim annual report 2025"},{"country":"CH","query":"Nestlé sustainability report 2025"}]}]},"BatchSecBody":{"properties":{"items":{"items":{"$ref":"#/components/schemas/SecBatchItem"},"type":"array","minItems":1,"title":"Items","description":"Operations."},"idempotency_key":{"type":"string","maxLength":200,"minLength":1,"title":"Idempotency Key","description":"Re-posting returns the same job."},"callback_url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Callback Url","description":"POSTed when the job finishes."}},"type":"object","required":["items","idempotency_key"],"title":"BatchSecBody","description":"Up to 50,000 SEC EDGAR operations processed asynchronously as one job.","examples":[{"idempotency_key":"chipiron-run-2026-10-20-sec-0001","items":[{"op":"resolve","ticker":"TSN"},{"forms":"10-K","op":"latest","ticker":"TSN"},{"cik":100493,"op":"latest"},{"accession":"0000100493-25-000070","cik":100493,"document":"tsn-20250927.htm","op":"document"}]}]},"Billing":{"properties":{"category":{"type":"string","title":"Category","description":"Billing category (same as `billing_category`).","examples":["fetch_premium"]},"billable":{"type":"boolean","title":"Billable","description":"The request counts on the invoice (failed requests do not, unless the plan bills them).","examples":[true]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"Invoice currency; `null` for projects without a customer plan.","examples":["CHF"]},"charge":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Charge","description":"Charge for this request at your plan price: tiers, included units, contract discount (decimal string, 6 places). `0.000000` inside the allowance. Excludes the monthly base fee, minimum top-up and VAT. `null` without a customer plan.","examples":["0.004000"]},"within_allowance":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Within Allowance","description":"`true` when every unit fell inside the plan's included units (charge 0); `null` when nothing was priced (not billable, or no meter counts this category).","examples":[false]},"units":{"items":{"$ref":"#/components/schemas/BillingUnit"},"type":"array","title":"Units","description":"Per plan meter."}},"type":"object","required":["category","billable","currency","charge","within_allowance","units"],"title":"Billing","description":"What this request is charged under your plan (never provider cost)."},"BillingUnit":{"properties":{"meter":{"type":"string","title":"Meter","description":"Plan meter (`search`, `fetch_own`, `fetch_premium`, `premium_gb`, `delivered_gb`, `sec`, `company_profile`, `company`, …).","examples":["fetch_premium"]},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit","description":"Unit of the meter (`search`, `fetch`, `request`, `GB`); `null` for pass-through meters.","examples":["fetch"]},"quantity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quantity","description":"Units this request adds (decimal string); `null` for pass-through meters.","examples":["1"]},"included":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Included","description":"Of those, units inside the plan's included allowance (charged 0).","examples":["0"]},"charge":{"type":"string","title":"Charge","description":"Charge for these units (decimal string, 6 places, plan currency).","examples":["0.004000"]}},"type":"object","required":["meter","unit","quantity","included","charge"],"title":"BillingUnit","description":"One meter of your plan that this request counts toward."},"Budget":{"properties":{"period":{"type":"string","title":"Period","description":"Budget month (`YYYY-MM`).","examples":["2026-10"]},"budget_usd":{"type":"number","title":"Budget Usd","description":"Monthly budget.","examples":[300.0]},"spent_usd":{"type":"number","title":"Spent Usd","description":"Settled spend this month.","examples":[0.37]},"reserved_usd":{"type":"number","title":"Reserved Usd","description":"Reserved for provider calls in flight.","examples":[0.0]},"remaining_usd":{"type":"number","title":"Remaining Usd","description":"Budget left.","examples":[299.63]}},"type":"object","required":["period","budget_usd","spent_usd","reserved_usd","remaining_usd"],"title":"Budget","description":"The project's monthly budget for third-party providers (calendar month, UTC)."},"CallbackPayload":{"properties":{"job_id":{"type":"string","title":"Job Id","description":"Job identifier.","examples":["1d0c5b8e-6f7a-4c1b-9e2d-3a4b5c6d7e8f"]},"kind":{"type":"string","title":"Kind","description":"Kind of items.","examples":["search","fetch","company","sec"]},"status":{"type":"string","title":"Status","description":"Final job status.","examples":["completed"]},"total":{"type":"integer","title":"Total","description":"Items in the job.","examples":[3000]},"succeeded":{"type":"integer","title":"Succeeded","description":"Items done.","examples":[2970]},"failed":{"type":"integer","title":"Failed","description":"Items failed or cancelled.","examples":[30]},"finished_at":{"type":"string","title":"Finished At","description":"When the callback was sent (ISO 8601).","examples":["2026-10-19T09:41:02.123456+00:00"]}},"type":"object","required":["job_id","kind","status","total","succeeded","failed","finished_at"],"title":"CallbackPayload","description":"Body of the `POST` sent to `callback_url` when a job completes (3 attempts)."},"Capital":{"properties":{"type":{"type":"string","enum":["nominal","paid_in","authorised"],"title":"Type","description":"Nominal, paid-in or authorised capital."},"amount":{"type":"number","title":"Amount","description":"Amount.","examples":[100000.0]},"currency":{"type":"string","title":"Currency","description":"ISO 4217.","examples":["CHF"]},"since":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since","description":"Date of the amount."}},"additionalProperties":false,"type":"object","required":["type","amount","currency"],"title":"Capital","description":"Share capital."},"CategoryUsage":{"properties":{"requests":{"type":"integer","title":"Requests","description":"Requests.","examples":[9120]},"succeeded":{"type":"integer","title":"Succeeded","description":"Successful requests.","examples":[8800]},"bytes":{"type":"integer","title":"Bytes","description":"Bytes retrieved.","examples":[812345678]},"bytes_ok":{"type":"integer","title":"Bytes Ok","description":"Bytes of successful requests.","examples":[800000000]},"premium_bytes":{"type":"integer","title":"Premium Bytes","description":"Bytes through premium routes.","examples":[0]},"premium_bytes_ok":{"type":"integer","title":"Premium Bytes Ok","description":"Bytes through premium routes, successful requests only.","examples":[0]},"cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cost Usd","description":"Provider cost in USD (decimal string); `null` for projects of an external customer, who see their charges instead.","examples":["0"]},"cost_ok_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cost Ok Usd","description":"Provider cost of successful requests in USD (decimal string); `null` for projects of an external customer.","examples":["0"]}},"type":"object","required":["requests","succeeded","bytes","bytes_ok","premium_bytes","premium_bytes_ok","cost_usd","cost_ok_usd"],"title":"CategoryUsage","description":"Metered usage of one billing category (`search`, `search_fallback`,\n`search_cached`, `fetch_own`, `fetch_premium`, `fetch_cached`, `sec`, `sec_cached`,\n`company_profile`, `company_profile_cached`)."},"Claim":{"properties":{"field":{"type":"string","title":"Field","description":"Field the claim is about (`names.legal`, `addresses`, …).","examples":["status"]},"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key","description":"Item key within a list field (e.g. the address type).","examples":["registered"]},"value":{"title":"Value","description":"The claimed value (shape of the field or list item)."},"source":{"type":"string","title":"Source","description":"Source making the claim.","examples":["gleif"]},"observed_at":{"type":"string","title":"Observed At","description":"First time Cormorant saw this value (ISO 8601)."},"confirmed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Confirmed At","description":"Last time the source still said so (ISO 8601)."},"valid_from":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Valid From","description":"Start of validity the source states (date)."},"valid_to":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Valid To","description":"End of validity: stated by the source, or the day a newer observation replaced it."},"current":{"type":"boolean","title":"Current","description":"True while the source still asserts this value."},"confidence":{"type":"number","title":"Confidence","description":"0–1; parsing and matching certainty.","examples":[1.0]},"document_ref":{"anyOf":[{"$ref":"#/components/schemas/DocumentRef"},{"type":"null"}],"description":"Raw document behind the claim."}},"additionalProperties":false,"type":"object","required":["field","value","source","observed_at","current","confidence"],"title":"Claim","description":"One source's statement about one field, with its validity."},"CompanyBatchBody":{"properties":{"action":{"type":"string","enum":["get","refresh","resolve"],"title":"Action","description":"`get`: the record (refreshing stale data), `refresh`: re-fetch from every source, `resolve`: entity resolution of `name`/`country`/`city`/`identifiers`.","default":"get"},"items":{"items":{"$ref":"#/components/schemas/BatchItem"},"type":"array","minItems":1,"title":"Items","description":"Up to 50,000 items."},"include":{"items":{"type":"string","enum":["people","ownership","filings","financials","events"]},"type":"array","title":"Include","description":"Sub-resources to include in each record (`get`/`refresh`)."},"max_age":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Max Age","description":"As `max_age` of `GET /v1/companies/{id}`."},"persist":{"type":"boolean","title":"Persist","description":"`resolve`: add confident matches to the register (as `POST /v1/companies/resolve`).","default":true},"idempotency_key":{"type":"string","maxLength":200,"minLength":1,"title":"Idempotency Key","description":"Re-posting returns the same job."},"callback_url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Callback Url","description":"POSTed when the job finishes."}},"type":"object","required":["items","idempotency_key"],"title":"CompanyBatchBody","description":"Many companies resolved, enriched or refreshed as one job.","examples":[{"action":"get","idempotency_key":"crm-sync-2026-10-20","items":[{"ref":"ch_uid:CHE-101.329.561"},{"ref":"lei:HWUPKR0MPOU8FGXBT394"}]}]},"CompanyChange":{"properties":{"seq":{"type":"integer","title":"Seq","description":"Position in the feed (use as cursor).","examples":[812]},"company_id":{"type":"string","title":"Company Id","description":"Cormorant id."},"kind":{"type":"string","enum":["created","updated","merged","split"],"title":"Kind","description":"`merged`: the record was merged into another (follow the id: it redirects); `split`: a merge was undone.","examples":["updated"]},"fields":{"items":{"type":"string"},"type":"array","title":"Fields","description":"Top-level fields that changed.","examples":[["names","status"]]},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Country of the company.","examples":["CH"]},"changed_at":{"type":"string","title":"Changed At","description":"When (ISO 8601)."}},"type":"object","required":["seq","company_id","kind","fields","country","changed_at"],"title":"CompanyChange","description":"One change of the register."},"CompanyChangedEvent":{"properties":{"event":{"type":"string","const":"company.changed","title":"Event","description":"Always `company.changed`."},"id":{"type":"string","title":"Id","description":"Delivery id (`dlv_…`); use as idempotency key."},"watch_id":{"type":"string","title":"Watch Id","description":"The watch."},"changes":{"items":{"$ref":"#/components/schemas/CompanyChange"},"type":"array","title":"Changes","description":"Changes of watched companies, oldest first."}},"type":"object","required":["event","id","watch_id","changes"],"title":"CompanyChangedEvent","description":"Body of a `company.changed` webhook delivery."},"CompanyChanges":{"properties":{"items":{"items":{"$ref":"#/components/schemas/CompanyChange"},"type":"array","title":"Items","description":"Oldest first."},"next_cursor":{"type":"string","title":"Next Cursor","description":"Pass as `cursor` to continue (poll with it)."},"billing":{"anyOf":[{"$ref":"#/components/schemas/Billing"},{"type":"null"}],"description":"What this request is charged under your plan (`charge`, `currency`, `within_allowance`, units per meter), priced like the invoice. Absent on answers that were not recorded (invalid input, limits)."}},"type":"object","required":["items","next_cursor"],"title":"CompanyChanges","description":"Answer of `GET /v1/companies/changes`."},"CompanyPage":{"properties":{"company_id":{"type":"string","title":"Company Id","description":"Cormorant id.","examples":["cmp_01JA2B3C4D5E6F7G8H9J0KMNPQ"]},"items":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Items","description":"Items in the shape of the matching company/v1 field (`events`, `people`, `ownership`, …); history items are claims."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as `cursor` for the next page."},"refresh":{"items":{"$ref":"#/components/schemas/CompanyRefresh"},"type":"array","title":"Refresh","description":"What this request refreshed."},"billing":{"anyOf":[{"$ref":"#/components/schemas/Billing"},{"type":"null"}],"description":"What this request is charged under your plan (`charge`, `currency`, `within_allowance`, units per meter), priced like the invoice. Absent on answers that were not recorded (invalid input, limits)."}},"type":"object","required":["company_id","items","next_cursor","refresh"],"title":"CompanyPage","description":"A page of a company sub-resource or of its history."},"CompanyRecord":{"properties":{"schema_version":{"type":"string","const":"company/v1","title":"Schema Version","description":"Always `company/v1`.","default":"company/v1"},"id":{"type":"string","title":"Id","description":"Stable Cormorant id (`cmp_<ulid>`); survives merges (redirects).","examples":["cmp_01JA2B3C4D5E6F7G8H9J0KMNPQ"]},"identifiers":{"items":{"$ref":"#/components/schemas/app__companies__model__Identifier"},"type":"array","title":"Identifiers","description":"Identifiers in every known scheme."},"names":{"$ref":"#/components/schemas/Names","description":"Names."},"legal_form":{"anyOf":[{"$ref":"#/components/schemas/LegalForm"},{"type":"null"}],"description":"Legal form."},"status":{"anyOf":[{"$ref":"#/components/schemas/app__companies__model__Status"},{"type":"null"}],"description":"Register status."},"jurisdiction":{"anyOf":[{"$ref":"#/components/schemas/Jurisdiction"},{"type":"null"}],"description":"Jurisdiction and register."},"addresses":{"items":{"$ref":"#/components/schemas/Address"},"type":"array","title":"Addresses","description":"Addresses."},"dates":{"$ref":"#/components/schemas/Dates","description":"Incorporation, registration and deregistration dates."},"purpose":{"additionalProperties":{"type":"string"},"type":"object","title":"Purpose","description":"Purpose text per language (ISO 639-1)."},"activities":{"items":{"$ref":"#/components/schemas/Activity"},"type":"array","title":"Activities","description":"Activity codes."},"capital":{"items":{"$ref":"#/components/schemas/Capital"},"type":"array","title":"Capital","description":"Share capital."},"size":{"anyOf":[{"$ref":"#/components/schemas/Size"},{"type":"null"}],"description":"Size (official/filing data only)."},"people":{"anyOf":[{"items":{"$ref":"#/components/schemas/Person"},"type":"array"},{"type":"null"}],"title":"People","description":"Officers (`include=people`)."},"ownership":{"anyOf":[{"items":{"$ref":"#/components/schemas/Ownership"},"type":"array"},{"type":"null"}],"title":"Ownership","description":"Ownership (`include=ownership`)."},"relationships":{"items":{"$ref":"#/components/schemas/Relationship"},"type":"array","title":"Relationships","description":"Links to other companies."},"filings":{"anyOf":[{"items":{"$ref":"#/components/schemas/Filing"},"type":"array"},{"type":"null"}],"title":"Filings","description":"Filings (`include=filings`)."},"financials":{"anyOf":[{"items":{"$ref":"#/components/schemas/Financials"},"type":"array"},{"type":"null"}],"title":"Financials","description":"Financials (`include=financials`)."},"events":{"anyOf":[{"items":{"$ref":"#/components/schemas/Event"},"type":"array"},{"type":"null"}],"title":"Events","description":"Timeline (`include=events`)."},"securities":{"items":{"$ref":"#/components/schemas/Security"},"type":"array","title":"Securities","description":"Listed securities."},"web":{"anyOf":[{"$ref":"#/components/schemas/Web"},{"type":"null"}],"description":"Web presence."},"sources":{"items":{"$ref":"#/components/schemas/SourceDocument"},"type":"array","title":"Sources","description":"Raw documents behind the record (newest first)."},"freshness":{"items":{"$ref":"#/components/schemas/SourceFreshness"},"type":"array","title":"Freshness","description":"Per source and field group."},"quality":{"$ref":"#/components/schemas/Quality","description":"Completeness score and source conflicts."},"provenance":{"additionalProperties":{"$ref":"#/components/schemas/Provenance"},"type":"object","title":"Provenance","description":"Claim behind each resolved field."},"claims":{"anyOf":[{"items":{"$ref":"#/components/schemas/Claim"},"type":"array"},{"type":"null"}],"title":"Claims","description":"Every claim (`include=claims`)."},"redirected_from":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Redirected From","description":"Id that was asked for, when it was merged into this record."},"updated_at":{"type":"string","title":"Updated At","description":"Last change of the record (ISO 8601)."},"refresh":{"items":{"$ref":"#/components/schemas/CompanyRefresh"},"type":"array","title":"Refresh","description":"Per source and field group: refreshed, fresh or failed."},"billing":{"anyOf":[{"$ref":"#/components/schemas/Billing"},{"type":"null"}],"description":"What this request is charged under your plan (`charge`, `currency`, `within_allowance`, units per meter), priced like the invoice. Absent on answers that were not recorded (invalid input, limits)."}},"additionalProperties":false,"type":"object","required":["id","quality","updated_at"],"title":"CompanyRecord","description":"A company record (`company/v1`) plus what this request refreshed."},"CompanyRef":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Cormorant id, when the company is in the register."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Name as the source gives it."},"identifiers":{"items":{"$ref":"#/components/schemas/app__companies__model__Identifier"},"type":"array","title":"Identifiers","description":"Identifiers given by the source."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"ISO 3166-1 alpha-2."}},"additionalProperties":false,"type":"object","title":"CompanyRef","description":"Another company, by Cormorant id and/or identifiers."},"CompanyRefresh":{"properties":{"source":{"type":"string","title":"Source","description":"Source name.","examples":["gleif"]},"group":{"type":"string","title":"Group","description":"Field group: `core`, `people`, `ownership`, `relationships`, `filings`, `financials`, `events`.","examples":["core"]},"status":{"type":"string","enum":["refreshed","fresh","failed","not_found","in_progress","pending","skipped"],"title":"Status","description":"`refreshed` (fetched now), `fresh` (register data within the source's freshness class or your `max_age`), `failed` (source error; the register still answers), `not_found` (the source does not know the company), `in_progress` (another request is refreshing it right now), `pending` (too slow for this answer or the source's canaries fail: it finishes in the background, the next request sees the data; `error` `deadline` or `canary_failed`), `skipped` (the source is backing off after repeated failures; `error` `backoff`).","examples":["fresh"]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error class when `failed` (`http_503`, `timeout`, …); `cached` with `not_found` when the source said so recently and was not asked again."},"at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"At","description":"When it was refreshed (ISO 8601)."}},"type":"object","required":["source","group","status"],"title":"CompanyRefresh","description":"What one source did for this request (refresh-on-request)."},"CompanyResolved":{"properties":{"match":{"anyOf":[{"$ref":"#/components/schemas/CompanySummary"},{"type":"null"}],"description":"The best candidate when it is a confident match (score ≥ 0.85 and clearly ahead of the next), else `null`. Added to the register unless `persist` was `false`: `id` is then the `cmp_` id and `in_register` is `true`."},"candidates":{"items":{"$ref":"#/components/schemas/CompanySummary"},"type":"array","title":"Candidates","description":"Ranked candidates."},"billing":{"anyOf":[{"$ref":"#/components/schemas/Billing"},{"type":"null"}],"description":"What this request is charged under your plan (`charge`, `currency`, `within_allowance`, units per meter), priced like the invoice. Absent on answers that were not recorded (invalid input, limits)."},"live_sources":{"items":{"$ref":"#/components/schemas/LiveSource"},"type":"array","title":"Live Sources","description":"Sources searched live (empty when the register or an identifier answered)."}},"type":"object","required":["match","candidates"],"title":"CompanyResolved","description":"Answer of `POST /v1/companies/resolve`."},"CompanySearch":{"properties":{"results":{"items":{"$ref":"#/components/schemas/CompanySummary"},"type":"array","title":"Results","description":"Ranked by `match_score`."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as `cursor` for more register results; `null` at the end."},"live_sources":{"items":{"$ref":"#/components/schemas/LiveSource"},"type":"array","title":"Live Sources","description":"Sources searched live (first page only, routed by `country`)."},"billing":{"anyOf":[{"$ref":"#/components/schemas/Billing"},{"type":"null"}],"description":"What this request is charged under your plan (`charge`, `currency`, `within_allowance`, units per meter), priced like the invoice. Absent on answers that were not recorded (invalid input, limits)."}},"type":"object","required":["results","next_cursor","live_sources"],"title":"CompanySearch","description":"Answer of `GET /v1/companies/search`."},"CompanySource":{"properties":{"name":{"type":"string","title":"Name","description":"Source name (as in `sources[]` and `provenance`).","examples":["gleif"]},"label":{"type":"string","title":"Label","description":"Display name.","examples":["GLEIF (LEI)"]},"description":{"type":"string","title":"Description","description":"What it provides."},"countries":{"items":{"type":"string"},"type":"array","title":"Countries","description":"ISO 3166-1 alpha-2 (`*` = global).","examples":[["*"]]},"schemes":{"items":{"type":"string"},"type":"array","title":"Schemes","description":"Identifier schemes it can be asked by.","examples":[["lei","ch_uid"]]},"capabilities":{"items":{"type":"string"},"type":"array","title":"Capabilities","description":"`search`, `get`, `people`, `filings`, `events`, `relationships`, `ownership`, `financials`, `changes`."},"source_class":{"type":"string","title":"Source Class","description":"Precedence class: `official_register` > `official_gazette` > `gleif` > `regulatory` > `crosswalk` > `commercial` > `other`.","examples":["gleif"]},"precedence":{"type":"integer","title":"Precedence","description":"Numeric precedence (higher wins conflicts).","examples":[80]},"licence_url":{"type":"string","title":"Licence Url","description":"Licence/terms of the source's data."},"freshness":{"additionalProperties":{"type":"integer"},"type":"object","title":"Freshness","description":"Freshness class per field group in seconds: older data is re-fetched when requested.","examples":[{"core":86400}]},"active":{"type":"boolean","title":"Active","description":"Enabled and configured by the operator."},"health":{"$ref":"#/components/schemas/CompanySourceHealth","description":"Live health."}},"type":"object","required":["name","label","description","countries","schemes","capabilities","source_class","precedence","licence_url","freshness","active","health"],"title":"CompanySource","description":"A company data source."},"CompanySourceHealth":{"properties":{"status":{"type":"string","title":"Status","description":"Status-page status of the source.","examples":["operational"]},"success_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Success Rate","description":"Last hour; `null` with too few calls."},"latency_p95_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latency P95 Ms","description":"Recent p95 latency."},"canary_ok":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Canary Ok","description":"Last canary result (known companies)."},"last_success_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Success At","description":"Last successful call (ISO 8601)."}},"type":"object","required":["status","success_rate","latency_p95_ms","canary_ok","last_success_at"],"title":"CompanySourceHealth","description":"Live health of a company data source."},"CompanySources":{"properties":{"sources":{"items":{"$ref":"#/components/schemas/CompanySource"},"type":"array","title":"Sources","description":"Every source, active first."}},"type":"object","required":["sources"],"title":"CompanySources","description":"Answer of `GET /v1/companies/sources`."},"CompanySummary":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Cormorant id when the company is in the register, else `null`.","examples":["cmp_01JA2B3C4D5E6F7G8H9J0KMNPQ"]},"ref":{"type":"string","title":"Ref","description":"What to pass to `GET /v1/companies/{id}`: the `cmp_` id, or `scheme:value` for a live hit not yet in the register.","examples":["lei:BFM8T61CT2L1QCEMIK50"]},"in_register":{"type":"boolean","title":"In Register","description":"Whether the company is already in the register."},"match_score":{"type":"number","title":"Match Score","description":"0–1 relevance (name similarity).","examples":[0.93]},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Legal name.","examples":["UBS AG"]},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"ISO 3166-1 alpha-2.","examples":["CH"]},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City","description":"City of the first address.","examples":["Zurich"]},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Register status.","examples":["active"]},"legal_form":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Legal Form","description":"Legal-form category.","examples":["corporation"]},"identifiers":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Identifiers","description":"`{scheme, value}` identifiers.","examples":[[{"scheme":"lei","value":"BFM8T61CT2L1QCEMIK50"}]]},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Source of a live hit (`null` for register hits).","examples":[null]},"reasons":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Reasons","description":"`POST /v1/companies/resolve`: what the score is based on (`name`, `country`, `city`, `identifier`)."}},"type":"object","required":["id","ref","in_register","match_score","name","country","city","status","legal_form","identifiers","source"],"title":"CompanySummary","description":"A search or resolve hit."},"CompanyWatch":{"properties":{"id":{"type":"string","title":"Id","description":"Watch id.","examples":["wch_12"]},"url":{"type":"string","title":"Url","description":"Your HTTPS endpoint.","examples":["https://example.org/hooks/companies"]},"companies":{"items":{"type":"string"},"type":"array","title":"Companies","description":"Watched Cormorant ids."},"created_at":{"type":"string","title":"Created At","description":"ISO 8601."},"last_delivery_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Delivery At","description":"Last delivery attempt."},"last_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Status","description":"`delivered`, `http_<code>` or an error class."},"secret":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Secret","description":"HMAC secret to verify `X-Cormorant-Signature`; returned only when the watch is created."}},"type":"object","required":["id","url","companies","created_at","last_delivery_at","last_status"],"title":"CompanyWatch","description":"A webhook watching a list of companies."},"CompanyWatches":{"properties":{"watches":{"items":{"$ref":"#/components/schemas/CompanyWatch"},"type":"array","title":"Watches","description":"The project's watches."}},"type":"object","required":["watches"],"title":"CompanyWatches","description":"Answer of `GET /v1/companies/watches`."},"Conflict":{"properties":{"field":{"type":"string","title":"Field","description":"Field."},"values":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Values","description":"`{source, value}` per source."}},"additionalProperties":false,"type":"object","required":["field","values"],"title":"Conflict","description":"A field where sources currently disagree."},"Dates":{"properties":{"incorporated":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Incorporated","description":"Founding/incorporation date."},"registered":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Registered","description":"Entry into the register."},"deregistered":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deregistered","description":"Deletion from the register."},"fiscal_year_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Year End","description":"Fiscal year end (`MM-DD`).","examples":["12-31"]}},"additionalProperties":false,"type":"object","title":"Dates","description":"Key dates."},"DocumentRef":{"properties":{"source":{"type":"string","title":"Source","description":"Source that served the document.","examples":["gleif"]},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Where the source published it.","examples":["https://api.gleif.org/api/v1/lei-records/HWUPKR0MPOU8FGXBT394"]},"retrieved_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retrieved At","description":"When Cormorant retrieved it (ISO 8601).","examples":["2026-10-19T08:00:00+00:00"]},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sha256","description":"SHA-256 of the exact bytes."},"body_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body Url","description":"Download link of the exact bytes (`GET /v1/bodies/{sha256}`).","examples":["/v1/bodies/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"]}},"additionalProperties":false,"type":"object","required":["source"],"title":"DocumentRef","description":"The raw document a claim was read from."},"DomainUsage":{"properties":{"domain":{"type":"string","title":"Domain","description":"Host name.","examples":["www.example.com"]},"requests":{"type":"integer","title":"Requests","description":"Fetches.","examples":[1200]},"succeeded":{"type":"integer","title":"Succeeded","description":"Successful fetches.","examples":[1150]},"success_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Success Rate","description":"`succeeded / requests`.","examples":[0.9583]},"premium_requests":{"type":"integer","title":"Premium Requests","description":"Fetches served by the premium routes.","examples":[40]},"premium_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Premium Share","description":"`premium_requests / requests`.","examples":[0.0333]},"cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Usd","description":"Provider spend in USD — only for projects without an external customer.","examples":[0.01]}},"type":"object","required":["domain","requests","succeeded","success_rate","premium_requests","premium_share"],"title":"DomainUsage","description":"Fetches of one domain."},"Error":{"properties":{"detail":{"type":"string","title":"Detail","description":"Human-readable reason.","examples":["job not found"]}},"type":"object","required":["detail"],"title":"Error","description":"Error with a plain message (FastAPI's `detail`)."},"ErrorCode":{"properties":{"error":{"type":"string","title":"Error","description":"Error code, e.g. `user_agent_not_allowed`, `timeout`.","examples":["user_agent_not_allowed"]},"hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hint","description":"What to do about it.","examples":["ask the operator to add this User-Agent to the project allowlist"]},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Human-readable message."},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id","description":"Request id (on `504 timeout`): the request may still finish; quote it when asking the operator."}},"type":"object","required":["error"],"title":"ErrorCode","description":"Machine-readable error object."},"ErrorWithCode":{"properties":{"detail":{"$ref":"#/components/schemas/ErrorCode","description":"Error code and hint."}},"type":"object","required":["detail"],"title":"ErrorWithCode","description":"Error whose `detail` is a machine-readable object."},"Estimate":{"properties":{"period":{"type":"string","title":"Period","description":"`YYYY-MM`.","examples":["2026-10"]},"from":{"type":"string","title":"From","description":"First day.","examples":["2026-10-01"]},"to":{"type":"string","title":"To","description":"Last day.","examples":["2026-10-31"]},"currency":{"type":"string","title":"Currency","description":"Currency.","examples":["USD"]},"lines":{"items":{"$ref":"#/components/schemas/EstimateLine"},"type":"array","title":"Lines","description":"Priced lines."},"subtotal":{"type":"string","title":"Subtotal","description":"Decimal as a string, in the invoice currency.","examples":["15.60"]},"discount_total":{"type":"string","title":"Discount Total","description":"Decimal as a string, in the invoice currency.","examples":["15.60"]},"net_total":{"type":"string","title":"Net Total","description":"Decimal as a string, in the invoice currency.","examples":["0.00"]},"vat_rate":{"type":"string","title":"Vat Rate","description":"VAT rate in percent.","examples":["8.1"]},"vat_amount":{"type":"string","title":"Vat Amount","description":"Decimal as a string, in the invoice currency.","examples":["0.00"]},"total":{"type":"string","title":"Total","description":"Decimal as a string, in the invoice currency.","examples":["0.00"]},"complimentary":{"type":"boolean","title":"Complimentary","description":"Complimentary account or plan (billed at list price, then discounted 100 %).","examples":[true]},"list_total":{"type":"string","title":"List Total","description":"Net before the complimentary discount: the list value of what was used.","examples":["15.60"]}},"type":"object","required":["period","from","to","currency","lines","subtotal","discount_total","net_total","vat_rate","vat_amount","total","complimentary","list_total"],"title":"Estimate","description":"Current-period charges, rated now and not persisted."},"EstimateLine":{"properties":{"kind":{"type":"string","title":"Kind","description":"`usage`, `pass_through`, `base_fee`, `minimum`, `discount` or `complimentary`.","examples":["usage"]},"component":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Component","description":"Meter the line prices, e.g. `fetch_own`.","examples":["fetch_own"]},"description":{"type":"string","title":"Description","description":"Human-readable line.","examples":["Page fetches (1,000 included)"]},"quantity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quantity","description":"Quantity (decimal string).","examples":["8800"]},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit","description":"Unit, e.g. `fetch`, `GB`.","examples":["fetch"]},"unit_price":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit Price","description":"Unit price when flat; `null` for tiered lines.","examples":[null]},"amount":{"type":"string","title":"Amount","description":"Decimal as a string, in the invoice currency.","examples":["15.60"]},"detail":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Detail","description":"Breakdown: `included`, `billable` and the volume `tiers` applied.","examples":[{"billable":"7800","included":"1000"}]}},"type":"object","required":["kind","component","description","quantity","unit","unit_price","amount","detail"],"title":"EstimateLine","description":"One priced line of an estimate."},"Event":{"properties":{"type":{"type":"string","title":"Type","description":"`incorporation`, `name_change`, `seat_change`, `purpose_change`, `capital_change`, `officer_change`, `merger`, `liquidation`, `deletion`, `registration`, `other`.","examples":["name_change"]},"date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date","description":"Date of the event or publication."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Short description."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Publication link."},"source":{"type":"string","title":"Source","description":"Source of the event."},"data":{"additionalProperties":true,"type":"object","title":"Data","description":"Source-specific details (publication id …)."}},"additionalProperties":false,"type":"object","required":["type","source"],"title":"Event","description":"A dated event of the company's history (from gazettes and registers)."},"FetchBody":{"properties":{"url":{"type":"string","maxLength":4096,"minLength":1,"title":"Url","description":"http(s) URL to fetch. Private, loopback and link-local destinations are refused (`blocked_destination`).","examples":["https://www.example.com/annual-report-2025.pdf"]},"render":{"type":"string","enum":["auto","never","always"],"title":"Render","description":"`auto`: start with plain HTTP and use a browser when needed; `never`: no browser (direct → archive → proxy); `always`: browser only (browser → proxy_render).","default":"auto","examples":["auto"]},"max_bytes":{"type":"integer","maximum":52428800.0,"minimum":1.0,"title":"Max Bytes","description":"Maximum body size in bytes (enforced while streaming); larger bodies give `too_large`. Default 15 MB, max 50 MB. Batch items that leave it unset accept PDFs up to 200 MB.","default":15728640,"examples":[15728640]},"accept_pdf":{"type":"boolean","title":"Accept Pdf","description":"Accept PDF documents; `false` turns them into `pdf_not_accepted`.","default":true,"examples":[true]},"cache_ttl_s":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Cache Ttl S","description":"Maximum acceptable age of a cached answer in seconds; `0` bypasses the cache. Default: the cache's own TTL.","examples":[604800]},"min_text_chars":{"type":"integer","maximum":1000000.0,"minimum":0.0,"title":"Min Text Chars","description":"HTML main text shorter than this counts as thin and escalates direct → browser (never to the premium routes).","default":500,"examples":[500]},"project_ref":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Project Ref","description":"Your own text stored with your usage (e.g. the entity this request is for).","examples":["company:4711"]},"allow_archive":{"type":"boolean","title":"Allow Archive","description":"Allow a recent Wayback Machine snapshot (≤ 365 days) when the live site blocks Cormorant's own tiers, answers 404/410, or its host name does not exist (`served_from_archive_because`).","default":true,"examples":[true]},"allow_alternates":{"type":"boolean","title":"Allow Alternates","description":"When the page is a paywall teaser, disallowed by robots.txt, gone (404/410) or blocked on every tier, look for a verified open copy elsewhere (publisher API, open-access version via DOI, the same wire story on another site). The result then carries `alternate_of`, `alternate_source` and `match_score`. Never circumvents a paywall.","default":true,"examples":[true]},"allow_premium":{"type":"boolean","title":"Allow Premium","description":"`false`: never use the premium routes (`proxy`: residential network, `proxy_render`: rendering service), which are priced higher.","default":true,"examples":[true]},"tiers":{"anyOf":[{"items":{"type":"string","enum":["direct","browser","archive","proxy","proxy_render"]},"type":"array","minItems":1},{"type":"null"}],"title":"Tiers","description":"Allowlist of tiers to try (in ladder order). An empty intersection with the plan gives `no_tier_allowed`; cache hits from other tiers are not used.","examples":[["direct","browser","archive"]]},"timeout_s":{"anyOf":[{"type":"number","maximum":150.0,"minimum":5.0},{"type":"null"}],"title":"Timeout S","description":"Deadline for the whole fetch across tiers, 5–150 s. When it runs out the result is `error: timeout` (or the best page so far).","examples":[60]},"country":{"anyOf":[{"type":"string","pattern":"^[A-Za-z]{2}$"},{"type":"null"}],"title":"Country","description":"Geotargeting for the premium routes (ISO 3166-1 alpha-2).","examples":["CH"]},"domain_concurrency":{"anyOf":[{"type":"integer","maximum":8.0,"minimum":1.0},{"type":"null"}],"title":"Domain Concurrency","description":"How many requests to this URL's domain may run at the same time, counting this one (default 2 per Cormorant egress address). Up to 4 (the operator's `POLITENESS_BURST_MAX`) for a short, polite burst on a site you fetch several pages of, e.g. a company's own site; higher values are capped. Ignored while the site is pushing back (429s, challenges) and for hosts with their own site-wide limits (e.g. Wikimedia).","examples":[4]},"user_agent":{"anyOf":[{"type":"string","maxLength":300,"minLength":1},{"type":"null"}],"title":"User Agent","description":"User-Agent for `direct`, `browser` and `proxy` (not Web Render). Must be on the project's allowlist (set by the operator), else `403 user_agent_not_allowed`.","examples":["Example Research contact@example.org"]},"accept_language":{"anyOf":[{"type":"string","maxLength":100,"pattern":"^[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*(;q=[01](\\.\\d{1,3})?)?(\\s*,\\s*[A-Za-z*]{1,8}(-[A-Za-z0-9]{1,8})*(;q=[01](\\.\\d{1,3})?)?)*$"},{"type":"null"}],"title":"Accept Language","description":"Accept-Language header / browser locale.","examples":["de-CH,de;q=0.9"]},"include_html":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Include Html","description":"Return the decoded HTML in `html`. Default `true` for `/v1/fetch`, `false` for batch items (the exact bytes are always available via `body_url`).","examples":[false]}},"type":"object","required":["url"],"title":"FetchBody","description":"Fetch one URL: cache, then the standard routes (direct → browser →\narchive) and the premium routes (residential network → rendering service),\nescalating only when blocked.","examples":[{"url":"https://www.example.com/annual-report-2025.pdf"},{"allow_premium":false,"include_html":false,"render":"auto","timeout_s":60,"url":"https://www.holcim.com/investors"}]},"FetchResponse":{"properties":{"url":{"type":"string","title":"Url","description":"The URL as requested.","examples":["https://www.example.com/annual-report-2025.pdf"]},"final_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final Url","description":"URL after redirects. For `tier = archive` the archived copy's URL; `null` when unknown (`proxy_render`).","examples":["https://www.example.com/annual-report-2025.pdf"]},"redirects":{"items":{"$ref":"#/components/schemas/Redirect"},"type":"array","title":"Redirects","description":"Redirect hops before `final_url`."},"status":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status","description":"HTTP status of the returned page (on `all_tiers_failed`: the last status seen).","examples":[200]},"content_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Type","description":"What the body is (rendered pages: `text/html`).","examples":["application/pdf"]},"origin_content_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origin Content Type","description":"Content type the origin sent; `null` when unknown.","examples":["application/pdf"]},"headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Headers","description":"Allowlisted headers of the origin's final response (content type/length/language/disposition, ETag, Last-Modified, Cache-Control, Expires, Date, Link, X-Robots-Tag). Never cookies. Empty for `proxy_render`.","examples":[{"content-type":"application/pdf"}]},"tier":{"anyOf":[{"type":"string","enum":["direct","browser","archive","proxy","proxy_render","source"]},{"type":"null"}],"title":"Tier","description":"Tier that produced the page; `null` when none did.","examples":["direct"]},"attempts":{"items":{"$ref":"#/components/schemas/Attempt"},"type":"array","title":"Attempts","description":"Every tier tried, in order."},"timing":{"$ref":"#/components/schemas/FetchTiming","description":"Latency components: queue, polite per-domain waits, upstream."},"html":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Html","description":"Decoded HTML for HTML pages. Present on `/v1/fetch` unless `include_html=false`; omitted from batch item results unless the item set `include_html=true`.","examples":[null]},"text":{"type":"string","title":"Text","description":"Retained text (main text for HTML, pages joined for PDFs, decoded document for JSON/XML/plain text, empty for binary). Identical on cache hits.","examples":["Annual Report 2025\n\n..."]},"pdf_text_pages":{"anyOf":[{"items":{"$ref":"#/components/schemas/PdfPage"},"type":"array"},{"type":"null"}],"title":"Pdf Text Pages","description":"Per-page text for PDFs; `null` otherwise. Stops early when `text_truncated`."},"pdf_page_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pdf Page Count","description":"Number of pages of a PDF (all of them, also when the text stops early); `null` otherwise.","examples":[148]},"text_truncated":{"type":"boolean","title":"Text Truncated","description":"True when PDF text extraction stopped at its limits (pages or characters): `text` and `pdf_text_pages` cover the first pages only.","examples":[false]},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Document title, if found.","examples":["Annual Report 2025"]},"meta":{"anyOf":[{"$ref":"#/components/schemas/ArticleMeta"},{"type":"null"}],"description":"Article metadata for HTML pages (also on cache hits and batch results); `null` for other content kinds and on errors."},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sha256","description":"SHA-256 of the retrieved bytes (see `body_kind`).","examples":["a3f1000000000000000000000000000000000000000000000000000000000000"]},"bytes":{"type":"integer","title":"Bytes","description":"Size of the retrieved bytes.","examples":[2483112]},"cached":{"type":"boolean","title":"Cached","description":"True when served from the shared page cache.","examples":[false]},"revalidated":{"type":"boolean","title":"Revalidated","description":"True when an expired cache entry was confirmed unchanged by the origin (conditional GET on the direct tier answered 304, attempt reason `not_modified`): the cached content is returned with `cached: true` and no cost, and its freshness is renewed.","examples":[false]},"retrieved_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retrieved At","description":"When the bytes were retrieved (ISO 8601, UTC).","examples":["2026-10-19T08:12:44.120Z"]},"etag":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Etag","description":"Origin ETag, if any.","examples":["\"5f2-1a\""]},"last_modified":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Modified","description":"Origin Last-Modified, if any.","examples":["Tue, 03 Mar 2026 09:00:00 GMT"]},"cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Usd","description":"Cormorant's provider spend caused by this request in USD (search fallback and premium routes; cache hits and standard routes cause no provider cost). `null` for keys of an external customer: what you are charged is in `GET /v1/usage` and `GET /v1/requests`.","examples":[0.0]},"billing_category":{"type":"string","title":"Billing Category","description":"The billing category the request counts toward (`search`, `search_fallback`, `search_cached`, `fetch_own`, `fetch_premium`, `fetch_cached`, `company`, `company_cached`, `sec`, `sec_cached`, `company_profile`, `company_profile_cached`): it maps the request to the meters and charges of your plan.","examples":["fetch_own"]},"billing":{"anyOf":[{"$ref":"#/components/schemas/Billing"},{"type":"null"}],"description":"What this request is charged under your plan (`charge`, `currency`, `within_allowance`, units per meter), priced like the invoice. Absent on answers that were not recorded (invalid input, limits)."},"archived_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Archived At","description":"Snapshot time when `tier = archive`; capture time of a `common_crawl` copy (`tier = source`).","examples":[null]},"served_from_archive_because":{"anyOf":[{"type":"string","enum":["domain_dead","not_found"]},{"type":"null"}],"title":"Served From Archive Because","description":"Set when the archived copy (`tier = archive`) stands in for a page the live site cannot give: `domain_dead` (the host name does not exist) or `not_found` (the site answered 404/410; `attempts` shows it). Only with `allow_archive`. `null` otherwise.","examples":[null]},"body_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body Url","description":"Where the exact retrieved bytes can be downloaded with the same key (`GET /v1/bodies/{sha256}`); `null` when not stored.","examples":["https://api.cormorant.ch/v1/bodies/a3f1000000000000000000000000000000000000000000000000000000000000"]},"body_kind":{"anyOf":[{"type":"string","enum":["origin","rendered_dom"]},{"type":"null"}],"title":"Body Kind","description":"What `sha256` covers: `origin` = the entity body the origin (or archive) sent; `rendered_dom` = the document serialized by a browser after scripts ran.","examples":["origin"]},"content_kind":{"anyOf":[{"type":"string","enum":["html","pdf","text","json","xml","binary"]},{"type":"null"}],"title":"Content Kind","description":"Classification of the content (from the content type, sniffed when missing or generic).","examples":["pdf"]},"paywall":{"anyOf":[{"type":"string","enum":["none","metered","hard","unknown"]},{"type":"null"}],"title":"Paywall","description":"Paywall verdict for HTML pages (`null` otherwise): `hard` = `text` is only the teaser; `metered` = a meter or a declared paywall, but the full text came through; `unknown` = weak signals only; `none`. Cormorant detects paywalls and never circumvents them.","examples":[null]},"paywall_evidence":{"items":{"type":"string"},"type":"array","title":"Paywall Evidence","description":"Signals behind the verdict, e.g. `jsonld_not_free`, `vendor_piano`, `paywall_markup`, `truncation_markup`, `phrase_de`, `metered_fr`, `length_mismatch`.","examples":[[]]},"alternate_of":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alternate Of","description":"Set when the content is a verified open copy found elsewhere (`tier: source`): the URL that was asked for. `final_url` is the copy's URL.","examples":[null]},"alternate_source":{"anyOf":[{"type":"string","enum":["publisher_feed","guardian_api","open_access","syndication","common_crawl"]},{"type":"null"}],"title":"Alternate Source","description":"Where the copy came from: `publisher_feed` (the item in the publisher's own full-text RSS/Atom feed; `final_url` is the feed), `guardian_api` (Guardian Content API), `open_access` (open-access version of the DOI via OpenAlex), `syndication` (the same story on another site, e.g. wire copy), `common_crawl` (batch fetches only: the newest Common Crawl capture of a gone or blocked page; `archived_at` is the capture time).","examples":[null]},"match_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Match Score","description":"How the copy was verified: 1.0 for exact identifiers (DOI, Guardian path, feed item link, Common Crawl capture of the same URL); for `syndication` and title-matched `publisher_feed` items the share of the original lead's word 5-grams found in the copy (≥ 0.5).","examples":[null]},"primary_sources":{"items":{"$ref":"#/components/schemas/PrimarySource"},"type":"array","title":"Primary Sources","description":"For paywalled or unavailable pages: links on the page to primary documents (court decisions, government/regulator pages, press releases, DOIs, PDFs).","examples":[[]]},"hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hint","description":"For known hard domains (sites that block automated access, see Fetching → Known hard domains): the recommended route for the site, on errors and when an archive or alternative copy stands in. `null` otherwise.","examples":[null]},"alternative_urls":{"items":{"type":"string"},"type":"array","title":"Alternative Urls","description":"With `hint` on errors: other places to look for this page (e.g. its Wayback Machine URL, an OpenAlex search for a ResearchGate paper).","examples":[[]]},"text_complete":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Text Complete","description":"`false` when `text` is only the teaser of a paywalled article (`paywall: hard`); `null` for non-HTML content.","examples":[null]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"`null` on success, else an error code such as `invalid_url`, `blocked_destination`, `robots_disallowed`, `too_large`, `pdf_not_accepted`, `http_<status>`, `all_tiers_failed`, `domain_unavailable`, `domain_dead`, `timeout`, `no_tier_allowed`, `politeness_timeout`, `domain_busy` (synchronous calls, HTTP 503: the domain is busy for longer than a synchronous call waits; see `retry_after_s`); for SEC EDGAR URLs also `sec_not_configured`, `rate_limited`, `sec_unavailable`, `redirect_not_allowed`.","examples":[null]},"error_detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Detail","description":"With an error: one line listing every attempt (tier, reason, premium bytes) and which premium routes were tried, or why none was (e.g. skipped because the domain refused them on recent fetches). For humans and logs; match on `error` and `attempts` in code.","examples":[null]},"premium_routes_tried":{"items":{"type":"string"},"type":"array","title":"Premium Routes Tried","description":"Premium routes (`proxy`, `proxy_render`) actually tried for this request, in order (skipped ones excluded). Their bytes are in `attempts[].premium_bytes`.","examples":[[]]},"retry_after_s":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Retry After S","description":"With `error: domain_unavailable`: seconds until the domain is tried again. Retrying earlier answers the same error at once. With `domain_busy`: the expected wait for one of the domain's polite slots. Also set with `rate_limited` and `sec_unavailable` (SEC EDGAR).","examples":[null]},"request_id":{"type":"string","title":"Request Id","description":"Identifier of this request (`req_…`; batch items use `<job_id>:<index>`). Quote it when asking the operator about a request.","examples":["req_6b1f2c0e9a7d4b5c8e3f1a2b3c4d5e6f"]},"debug_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Debug Url","description":"Only in the answer to a debug request (header `X-Cormorant-Debug: 1` with a key enabled for debugging; available on request): a link to this request's diagnostic record for Cormorant support. Quote it when you report a problem; it cannot be opened with an API key.","examples":[null]}},"type":"object","required":["url","final_url","redirects","status","content_type","origin_content_type","headers","tier","attempts","timing","text","pdf_text_pages","pdf_page_count","text_truncated","title","meta","sha256","bytes","cached","revalidated","retrieved_at","etag","last_modified","cost_usd","billing_category","archived_at","served_from_archive_because","body_url","body_kind","content_kind","paywall","paywall_evidence","alternate_of","alternate_source","match_score","primary_sources","text_complete","error","error_detail","premium_routes_tried","retry_after_s","request_id"],"title":"FetchResponse","description":"Answer of `POST /v1/fetch` (and of each batch fetch item). Returned with\nHTTP 200 also for unsuccessful fetches: check `error`.","examples":[{"alternative_urls":[],"attempts":[{"ms":412,"premium_bytes":0,"reason":"ok","status":200,"tier":"direct"}],"billing_category":"fetch_own","body_kind":"origin","body_url":"https://api.cormorant.ch/v1/bodies/a3f1000000000000000000000000000000000000000000000000000000000000","bytes":2483112,"cached":false,"content_kind":"pdf","content_type":"application/pdf","cost_usd":0.0,"etag":"\"5f2-1a\"","final_url":"https://www.example.com/annual-report-2025.pdf","headers":{"content-type":"application/pdf"},"last_modified":"Tue, 03 Mar 2026 09:00:00 GMT","origin_content_type":"application/pdf","pdf_page_count":148,"pdf_text_pages":[{"page":1,"text":"Annual Report 2025"}],"premium_routes_tried":[],"redirects":[],"request_id":"req_91c2d0e1f2a3b4c5d6e7f8091a2b3c4d","retrieved_at":"2026-10-19T08:12:44.120Z","revalidated":false,"sha256":"a3f1000000000000000000000000000000000000000000000000000000000000","status":200,"text":"Annual Report 2025\n\n...","text_truncated":false,"tier":"direct","title":"Annual Report 2025","url":"https://www.example.com/annual-report-2025.pdf"}]},"FetchTiming":{"properties":{"queue_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Queue Ms","description":"Waiting in Cormorant's queues before a worker ran the request (synchronous: from the API to a worker; batch: since the item was admitted, politeness requeues included; plus the render queue after a browser handoff). `null` for cache hits answered by the API.","examples":[35]},"politeness_wait_ms":{"type":"integer","title":"Politeness Wait Ms","description":"Waiting for polite per-domain slots (sum of `attempts[].wait_ms`).","examples":[0]},"upstream_ms":{"type":"integer","title":"Upstream Ms","description":"Time in tier attempts and alternative sources (sum of `attempts[].upstream_ms`).","examples":[412]}},"type":"object","required":["queue_ms","politeness_wait_ms","upstream_ms"],"title":"FetchTiming","description":"Where the time of a fetch went (milliseconds)."},"Filing":{"properties":{"type":{"type":"string","title":"Type","description":"Normalised type (`annual_report`, `financial_statements`, `10-K`, …)."},"date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date","description":"Filing date."},"period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period","description":"Reporting period."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Title."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Where the source publishes it."},"document_ref":{"anyOf":[{"$ref":"#/components/schemas/DocumentRef"},{"type":"null"}],"description":"Stored copy, if retrieved."}},"additionalProperties":false,"type":"object","required":["type"],"title":"Filing","description":"A filed document."},"Financials":{"properties":{"period":{"type":"string","title":"Period","description":"Period, e.g. `2025` or `2025-12-31`."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"ISO 4217."},"revenue":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Revenue","description":"Revenue."},"net_income":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Net Income","description":"Net income."},"total_assets":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Assets","description":"Total assets."},"equity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Equity","description":"Equity."},"employees":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Employees","description":"Employees."},"source_filing":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Filing","description":"Filing the figures come from."}},"additionalProperties":false,"type":"object","required":["period"],"title":"Financials","description":"Figures of one period, only when published by an official source/XBRL."},"Geo":{"properties":{"lat":{"type":"number","title":"Lat","description":"Latitude (WGS 84)."},"lon":{"type":"number","title":"Lon","description":"Longitude (WGS 84)."}},"additionalProperties":false,"type":"object","required":["lat","lon"],"title":"Geo"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail","description":"One entry per invalid field."}},"type":"object","title":"HTTPValidationError"},"Health":{"properties":{"status":{"type":"string","const":"ok","title":"Status","description":"Always `ok` when the process answers."}},"type":"object","required":["status"],"title":"Health","description":"Liveness."},"Invoice":{"properties":{"number":{"type":"string","title":"Number","description":"Invoice number.","examples":["CORM-2026-0001"]},"status":{"type":"string","enum":["issued","paid","void"],"title":"Status","description":"State.","examples":["issued"]},"period":{"type":"string","title":"Period","description":"Billed month.","examples":["2026-09"]},"period_start":{"type":"string","title":"Period Start","description":"First day.","examples":["2026-09-01"]},"period_end":{"type":"string","title":"Period End","description":"Last day.","examples":["2026-09-30"]},"currency":{"type":"string","title":"Currency","description":"Currency.","examples":["USD"]},"plan_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan Label","description":"Plan name.","examples":["Standard (USD)"]},"complimentary":{"type":"boolean","title":"Complimentary","description":"Invoice of a complimentary plan (total 0).","examples":[true]},"subtotal":{"type":"string","title":"Subtotal","description":"Decimal as a string, in the invoice currency.","examples":["15.60"]},"discount_total":{"type":"string","title":"Discount Total","description":"Decimal as a string, in the invoice currency.","examples":["15.60"]},"net_total":{"type":"string","title":"Net Total","description":"Decimal as a string, in the invoice currency.","examples":["0.00"]},"vat_rate":{"type":"string","title":"Vat Rate","description":"VAT rate in percent.","examples":["8.1"]},"vat_amount":{"type":"string","title":"Vat Amount","description":"Decimal as a string, in the invoice currency.","examples":["0.00"]},"total":{"type":"string","title":"Total","description":"Decimal as a string, in the invoice currency.","examples":["0.00"]},"vat_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vat Note","description":"VAT note printed on the invoice.","examples":[null]},"issued_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Issued At","description":"Issue time.","examples":["2026-10-02T09:00:00+00:00"]},"due_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Due At","description":"Due date.","examples":["2026-11-01"]},"paid_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Paid At","description":"Payment date.","examples":[null]},"voided_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Voided At","description":"Void time.","examples":[null]},"pdf_url":{"type":"string","title":"Pdf Url","description":"Relative URL of the PDF.","examples":["/v1/account/invoices/CORM-2026-0001/pdf"]}},"type":"object","required":["number","status","period","period_start","period_end","currency","plan_label","complimentary","subtotal","discount_total","net_total","vat_rate","vat_amount","total","vat_note","issued_at","due_at","paid_at","voided_at","pdf_url"],"title":"Invoice","description":"An issued, paid or void invoice (drafts are never shown)."},"InvoiceDetail":{"properties":{"number":{"type":"string","title":"Number","description":"Invoice number.","examples":["CORM-2026-0001"]},"status":{"type":"string","enum":["issued","paid","void"],"title":"Status","description":"State.","examples":["issued"]},"period":{"type":"string","title":"Period","description":"Billed month.","examples":["2026-09"]},"period_start":{"type":"string","title":"Period Start","description":"First day.","examples":["2026-09-01"]},"period_end":{"type":"string","title":"Period End","description":"Last day.","examples":["2026-09-30"]},"currency":{"type":"string","title":"Currency","description":"Currency.","examples":["USD"]},"plan_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan Label","description":"Plan name.","examples":["Standard (USD)"]},"complimentary":{"type":"boolean","title":"Complimentary","description":"Invoice of a complimentary plan (total 0).","examples":[true]},"subtotal":{"type":"string","title":"Subtotal","description":"Decimal as a string, in the invoice currency.","examples":["15.60"]},"discount_total":{"type":"string","title":"Discount Total","description":"Decimal as a string, in the invoice currency.","examples":["15.60"]},"net_total":{"type":"string","title":"Net Total","description":"Decimal as a string, in the invoice currency.","examples":["0.00"]},"vat_rate":{"type":"string","title":"Vat Rate","description":"VAT rate in percent.","examples":["8.1"]},"vat_amount":{"type":"string","title":"Vat Amount","description":"Decimal as a string, in the invoice currency.","examples":["0.00"]},"total":{"type":"string","title":"Total","description":"Decimal as a string, in the invoice currency.","examples":["0.00"]},"vat_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vat Note","description":"VAT note printed on the invoice.","examples":[null]},"issued_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Issued At","description":"Issue time.","examples":["2026-10-02T09:00:00+00:00"]},"due_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Due At","description":"Due date.","examples":["2026-11-01"]},"paid_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Paid At","description":"Payment date.","examples":[null]},"voided_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Voided At","description":"Void time.","examples":[null]},"pdf_url":{"type":"string","title":"Pdf Url","description":"Relative URL of the PDF.","examples":["/v1/account/invoices/CORM-2026-0001/pdf"]},"lines":{"items":{"$ref":"#/components/schemas/InvoiceLine"},"type":"array","title":"Lines","description":"Priced lines."}},"type":"object","required":["number","status","period","period_start","period_end","currency","plan_label","complimentary","subtotal","discount_total","net_total","vat_rate","vat_amount","total","vat_note","issued_at","due_at","paid_at","voided_at","pdf_url","lines"],"title":"InvoiceDetail","description":"An invoice with its lines."},"InvoiceLine":{"properties":{"position":{"type":"integer","title":"Position","description":"Line number.","examples":[1]},"kind":{"type":"string","title":"Kind","description":"Line kind (see the estimate).","examples":["usage"]},"description":{"type":"string","title":"Description","description":"Line text.","examples":["Page fetches (1,000 included)"]},"quantity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quantity","description":"Quantity (decimal string).","examples":["8800"]},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit","description":"Unit.","examples":["fetch"]},"unit_price":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit Price","description":"Flat unit price, if any.","examples":[null]},"amount":{"type":"string","title":"Amount","description":"Decimal as a string, in the invoice currency.","examples":["15.60"]},"tiers":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Tiers","description":"Volume tiers applied (`from`, `to`, `quantity`, `unit_price`, `amount`)."}},"type":"object","required":["position","kind","description","quantity","unit","unit_price","amount","tiers"],"title":"InvoiceLine","description":"One line of an invoice."},"InvoiceList":{"properties":{"invoices":{"items":{"$ref":"#/components/schemas/Invoice"},"type":"array","title":"Invoices","description":"Issued, paid and void invoices of the customer."}},"type":"object","required":["invoices"],"title":"InvoiceList","description":"Answer of `GET /v1/account/invoices`."},"JobCounts":{"properties":{"total":{"type":"integer","title":"Total","description":"Items in the job.","examples":[3000]},"pending":{"type":"integer","title":"Pending","description":"Waiting for admission to the queues.","examples":[1200]},"queued":{"type":"integer","title":"Queued","description":"Admitted and queued or running.","examples":[380]},"done":{"type":"integer","title":"Done","description":"Finished successfully.","examples":[1390]},"failed":{"type":"integer","title":"Failed","description":"Finished with an error (result and error kept).","examples":[30]},"cancelled":{"type":"integer","title":"Cancelled","description":"Cancelled before running.","examples":[0]}},"type":"object","required":["total","pending","queued","done","failed","cancelled"],"title":"JobCounts","description":"Item counts by state."},"JobCreated":{"properties":{"job_id":{"type":"string","title":"Job Id","description":"Job identifier (UUID).","examples":["1d0c5b8e-6f7a-4c1b-9e2d-3a4b5c6d7e8f"]},"created":{"type":"boolean","title":"Created","description":"`true` (HTTP 202) for a new job, `false` (HTTP 200) when the `idempotency_key` matched an existing job, which is returned instead.","examples":[true]}},"type":"object","required":["job_id","created"],"title":"JobCreated","description":"Answer of `POST /v1/batch/search` and `POST /v1/batch/fetch`."},"JobItem":{"properties":{"index":{"type":"integer","title":"Index","description":"0-based position in the submitted `items`.","examples":[0]},"status":{"type":"string","enum":["pending","queued","done","failed","cancelled"],"title":"Status","description":"Item state.","examples":["done"]},"input":{"additionalProperties":true,"type":"object","title":"Input","description":"The item as submitted (defaults omitted).","examples":[{"url":"https://example.com"}]},"result":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result","description":"The search or fetch response (same shape as the single endpoint); `null` while not finished or when the stored result is unavailable.","examples":[{"text":"Example Domain ...","url":"https://example.com"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error code of a failed item; `result_unavailable` when the stored result cannot be read right now (retry later); `cancelled` for cancelled items.","examples":[null]}},"type":"object","required":["index","status","input","result","error"],"title":"JobItem","description":"One item of a job with its stored result."},"JobStatus":{"properties":{"job_id":{"type":"string","title":"Job Id","description":"Job identifier (UUID).","examples":["1d0c5b8e-6f7a-4c1b-9e2d-3a4b5c6d7e8f"]},"kind":{"type":"string","title":"Kind","description":"Kind of items.","examples":["search","fetch","company","sec"]},"status":{"type":"string","enum":["queued","running","completed","cancelled"],"title":"Status","description":"Job state.","examples":["running"]},"counts":{"$ref":"#/components/schemas/JobCounts","description":"Number of items in each state."},"created_at":{"type":"string","title":"Created At","description":"Creation time (ISO 8601).","examples":["2026-10-19T08:00:00.000000+00:00"]},"updated_at":{"type":"string","title":"Updated At","description":"Last change (ISO 8601).","examples":["2026-10-19T08:05:12.000000+00:00"]},"finished_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Finished At","description":"When the job completed or was cancelled.","examples":[null]},"callback_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Callback Url","description":"Callback URL given at creation.","examples":["https://chipiron.example/hooks/cormorant"]},"callback_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Callback Status","description":"Outcome of the completion callback (`delivered_<status>`, `http_<status>`, `blocked_destination`, `error_<type>`); `null` before delivery.","examples":[null]},"items_url":{"type":"string","title":"Items Url","description":"Relative URL of the first page of items.","examples":["/v1/jobs/1d0c5b8e-6f7a-4c1b-9e2d-3a4b5c6d7e8f?include=items&offset=0&limit=100"]},"items":{"anyOf":[{"items":{"$ref":"#/components/schemas/JobItem"},"type":"array"},{"type":"null"}],"title":"Items","description":"Present with `include=items`: one page of items."},"offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Offset","description":"Present with `include=items`: offset of this page.","examples":[0]},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit","description":"Present with `include=items`: page size.","examples":[100]}},"type":"object","required":["job_id","kind","status","counts","created_at","updated_at","finished_at","callback_url","callback_status","items_url"],"title":"JobStatus","description":"Status of a batch job; with `?include=items` also a page of items."},"Jurisdiction":{"properties":{"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"ISO 3166-1 alpha-2.","examples":["CH"]},"subdivision":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subdivision","description":"ISO 3166-2 (US state, Swiss canton …).","examples":["CH-VD"]},"register":{"anyOf":[{"$ref":"#/components/schemas/Register"},{"type":"null"}],"description":"Register entry."}},"additionalProperties":false,"type":"object","title":"Jurisdiction","description":"Legal jurisdiction."},"KeyDomains":{"properties":{"key":{"type":"string","title":"Key","description":"Key prefix.","examples":["cmr_AbCdEf"]},"key_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key Label","description":"Label.","examples":["crawler"]},"key_role":{"type":"string","enum":["account_admin","standard"],"title":"Key Role","description":"Role.","examples":["standard"]},"key_status":{"type":"string","enum":["active","revoked"],"title":"Key Status","description":"Status.","examples":["active"]},"project":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project","description":"Project.","examples":["acme-crawler"]},"domains":{"items":{"$ref":"#/components/schemas/DomainUsage"},"type":"array","title":"Domains","description":"Busiest first."}},"type":"object","required":["key","key_label","key_role","key_status","project","domains"],"title":"KeyDomains","description":"Top domains of one key (`group_by=key`)."},"KeyLimitsInfo":{"properties":{"monthly_spend_cap":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Monthly Spend Cap","description":"Charges per calendar month (UTC) in `currency` (provider cost in USD for projects without a customer).","examples":["50.00"]},"currency":{"type":"string","title":"Currency","description":"Currency of the cap.","examples":["USD"]},"monthly_requests":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"title":"Monthly Requests","description":"Requests per month per category (`search`, `fetch`, `fetch_premium`, `company`).","examples":[{"fetch":100000,"fetch_premium":1000}]},"rate_limit_rps":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rate Limit Rps","description":"Requests per second.","examples":[10]},"allowed_categories":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Categories","description":"What the key may do (`search`, `fetch`, `fetch_premium`, `company`); `null` = all. Without `fetch_premium`, fetches run without the premium routes.","examples":[["search"]]}},"type":"object","required":["monthly_spend_cap","currency","monthly_requests","rate_limit_rps","allowed_categories"],"title":"KeyLimitsInfo","description":"Limits the operator set on a key (`null` fields: no such limit)."},"LedgerAttempt":{"properties":{"tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tier","description":"Tier or provider.","examples":["direct"]},"status":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status","description":"HTTP status.","examples":[403]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Outcome.","examples":["http_403"]},"ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ms","description":"Duration.","examples":[640]}},"type":"object","required":["tier","status","reason"],"title":"LedgerAttempt","description":"One tier tried."},"LedgerRequest":{"properties":{"request_id":{"type":"string","title":"Request Id","description":"`req_…`, or `<job_id>:<index>` for batch items.","examples":["req_6b1f2c0e9a7d4b5c8e3f1a2b3c4d5e6f"]},"time":{"type":"string","title":"Time","description":"When it was recorded.","examples":["2026-10-19T11:02:13+00:00"]},"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key","description":"Prefix of the key that made it; `null` before per-key attribution.","examples":["cmr_AbCdEf"]},"key_role":{"anyOf":[{"type":"string","enum":["account_admin","standard"]},{"type":"null"}],"title":"Key Role","description":"Role of that key.","examples":["standard"]},"project":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project","description":"Project.","examples":["acme-crawler"]},"project_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Ref","description":"Your `project_ref`.","examples":["company:4711"]},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Id","description":"Batch job of the item.","examples":[null]},"kind":{"type":"string","enum":["search","fetch","company","sec","company_profile"],"title":"Kind","description":"Request kind (`company_profile`: extended company profiles).","examples":["fetch"]},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"Fetched host.","examples":["www.example.com"]},"tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tier","description":"Fetch: the tier that answered; search: the provider.","examples":["direct"]},"status":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status","description":"HTTP status of the origin.","examples":[200]},"ok":{"type":"boolean","title":"Ok","description":"Succeeded.","examples":[true]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error code.","examples":[null]},"latency_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latency Ms","description":"Latency in ms.","examples":[840]},"cached":{"type":"boolean","title":"Cached","description":"Served from the shared cache.","examples":[false]},"bytes":{"type":"integer","title":"Bytes","description":"Bytes retrieved.","examples":[48211]},"premium":{"type":"boolean","title":"Premium","description":"Served by (or charged for) a premium route.","examples":[false]},"category":{"type":"string","title":"Category","description":"Billing category.","examples":["fetch_own"]},"charge":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Charge","description":"Customers: the request's share of its key's charges for that day and category (their average price; 6 decimals, `currency`). `null` until aggregated (within 5 minutes); settles when the day is final.","examples":["0.001842"]},"cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Usd","description":"Provider spend in USD — only for projects without an external customer.","examples":[0.0]}},"type":"object","required":["request_id","time","key","key_role","project","project_ref","job_id","kind","domain","tier","status","ok","error","latency_ms","cached","bytes","premium","category"],"title":"LedgerRequest","description":"One request of the ledger."},"LedgerRequestDetail":{"properties":{"request_id":{"type":"string","title":"Request Id","description":"`req_…`, or `<job_id>:<index>` for batch items.","examples":["req_6b1f2c0e9a7d4b5c8e3f1a2b3c4d5e6f"]},"time":{"type":"string","title":"Time","description":"When it was recorded.","examples":["2026-10-19T11:02:13+00:00"]},"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key","description":"Prefix of the key that made it; `null` before per-key attribution.","examples":["cmr_AbCdEf"]},"key_role":{"anyOf":[{"type":"string","enum":["account_admin","standard"]},{"type":"null"}],"title":"Key Role","description":"Role of that key.","examples":["standard"]},"project":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project","description":"Project.","examples":["acme-crawler"]},"project_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Ref","description":"Your `project_ref`.","examples":["company:4711"]},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Id","description":"Batch job of the item.","examples":[null]},"kind":{"type":"string","enum":["search","fetch","company","sec","company_profile"],"title":"Kind","description":"Request kind (`company_profile`: extended company profiles).","examples":["fetch"]},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"Fetched host.","examples":["www.example.com"]},"tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tier","description":"Fetch: the tier that answered; search: the provider.","examples":["direct"]},"status":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status","description":"HTTP status of the origin.","examples":[200]},"ok":{"type":"boolean","title":"Ok","description":"Succeeded.","examples":[true]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error code.","examples":[null]},"latency_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latency Ms","description":"Latency in ms.","examples":[840]},"cached":{"type":"boolean","title":"Cached","description":"Served from the shared cache.","examples":[false]},"bytes":{"type":"integer","title":"Bytes","description":"Bytes retrieved.","examples":[48211]},"premium":{"type":"boolean","title":"Premium","description":"Served by (or charged for) a premium route.","examples":[false]},"category":{"type":"string","title":"Category","description":"Billing category.","examples":["fetch_own"]},"charge":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Charge","description":"Customers: the request's share of its key's charges for that day and category (their average price; 6 decimals, `currency`). `null` until aggregated (within 5 minutes); settles when the day is final.","examples":["0.001842"]},"cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Usd","description":"Provider spend in USD — only for projects without an external customer.","examples":[0.0]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Why it ended as it did.","examples":["ok"]},"attempts":{"items":{"$ref":"#/components/schemas/LedgerAttempt"},"type":"array","title":"Attempts","description":"The tiers tried, in order."}},"type":"object","required":["request_id","time","key","key_role","project","project_ref","job_id","kind","domain","tier","status","ok","error","latency_ms","cached","bytes","premium","category","reason","attempts"],"title":"LedgerRequestDetail","description":"Answer of `GET /v1/requests/{request_id}`."},"LegalForm":{"properties":{"local_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Local Code","description":"Local abbreviation.","examples":["AG"]},"local_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Local Name","description":"Local name.","examples":["Aktiengesellschaft"]},"elf_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Elf Code","description":"ISO 20275 Entity Legal Form code.","examples":["MVII"]},"category":{"type":"string","enum":["corporation","partnership","sole_trader","cooperative","foundation","association","public_body","branch","other"],"title":"Category","description":"Normalised category.","default":"other"}},"additionalProperties":false,"type":"object","title":"LegalForm","description":"Legal form, mapped to ISO 20275 (ELF) and a category."},"LiveSource":{"properties":{"source":{"type":"string","title":"Source","description":"Source name.","examples":["gleif"]},"ok":{"type":"boolean","title":"Ok","description":"Whether it answered."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error class when it did not (`timeout`, `http_503`, `backoff`, `canary_failed`, …).","examples":[null]},"status":{"anyOf":[{"type":"string","enum":["ok","failed","timeout","skipped"]},{"type":"null"}],"title":"Status","description":"`ok`; `failed` (source error); `timeout` (slower than the answer's deadline — it finishes in the background); `skipped` (not asked: backing off after repeated failures, or its canaries fail).","examples":["ok"]},"ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ms","description":"Time the source took (ms).","examples":[412]}},"type":"object","required":["source","ok","error"],"title":"LiveSource","description":"A source searched live for this request."},"MeterUsage":{"properties":{"quantity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quantity","description":"Measured quantity (decimal string: requests or GB); `null` for meters billed on provider cost.","examples":["8800"]},"included":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Included","description":"Included units used by this group: its pro-rata share of the account's included units of the period.","examples":["1000"]},"billable":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Billable","description":"`quantity - included`.","examples":["7800"]},"amount":{"type":"string","title":"Amount","description":"Charge of this meter for the group, at the plan price in the customer's currency (decimal string).","examples":["15.60"]}},"type":"object","required":["quantity","included","billable","amount"],"title":"MeterUsage","description":"One price-plan meter of a group: how much counted, how much of it was\ncovered by the plan's included units, and what it costs."},"Name":{"properties":{"name":{"type":"string","title":"Name","description":"The name as registered.","examples":["Nestlé S.A."]},"lang":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lang","description":"ISO 639-1 language, when the source says."},"valid_from":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Valid From","description":"Start of use (date)."},"valid_to":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Valid To","description":"End of use (date)."},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Source that published this form (`translations`, `alternates`).","examples":["uid_register"]}},"additionalProperties":false,"type":"object","required":["name"],"title":"Name","description":"A name with its validity and language."},"Names":{"properties":{"legal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Legal","description":"Current legal name: the official national register's primary entry in its official form and language when a register source has the company (in Switzerland Zefix, then the UID register), else GLEIF's, else other sources'. Never depends on the order of refreshes.","examples":["Nestlé AG"]},"previous":{"items":{"$ref":"#/components/schemas/Name"},"type":"array","title":"Previous","description":"Former legal names."},"trading":{"items":{"$ref":"#/components/schemas/Name"},"type":"array","title":"Trading","description":"Trading names, brands, `doing business as`."},"translations":{"items":{"$ref":"#/components/schemas/Name"},"type":"array","title":"Translations","description":"The legal name in other languages (e.g. Swiss multilingual names)."},"alternates":{"items":{"$ref":"#/components/schemas/Name"},"type":"array","title":"Alternates","description":"Other sources' current forms of the legal name that differ from `legal` (e.g. GLEIF's `NESTLÉ S.A.` next to the commercial register's `Nestlé AG`), best-ranked source first, each with its `source`."}},"additionalProperties":false,"type":"object","title":"Names","description":"Legal name and other names."},"Ownership":{"properties":{"type":{"type":"string","enum":["shareholder","ultimate_parent","direct_parent","beneficial_owner"],"title":"Type","description":"Kind of ownership."},"holder":{"anyOf":[{"$ref":"#/components/schemas/CompanyRef"},{"type":"null"}],"description":"Holder, when a company."},"holder_person":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Holder Person","description":"Holder's name, when a natural person."},"share_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Share Pct","description":"Share in percent."},"since":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since","description":"Start (date)."},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Source of the link."}},"additionalProperties":false,"type":"object","required":["type"],"title":"Ownership","description":"An ownership link."},"PdfPage":{"properties":{"page":{"type":"integer","title":"Page","description":"1-based page number.","examples":[1]},"text":{"type":"string","title":"Text","description":"Text of the page.","examples":["Annual Report 2025"]}},"type":"object","required":["page","text"],"title":"PdfPage","description":"Extracted text of one PDF page."},"Percentiles":{"properties":{"p50":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"P50","description":"Median (ms, estimated).","examples":[40]},"p95":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"P95","description":"95th percentile (ms, estimated).","examples":[900]}},"type":"object","required":["p50","p95"],"title":"Percentiles"},"Person":{"properties":{"name":{"type":"string","title":"Name","description":"Name as published."},"role":{"type":"string","title":"Role","description":"Normalised role: `director`, `chair`, `ceo`, `managing_director`, `secretary`, `auditor`, `liquidator`, `partner`, `signatory`, `member`, `other`.","examples":["director"]},"local_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Local Role","description":"Role as worded by the source."},"function":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Function","description":"Further function text."},"signing_authority":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signing Authority","description":"`individual`, `joint_two`, `none`, or the local wording."},"since":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since","description":"Start (date)."},"until":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Until","description":"End (date)."},"residence_city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Residence City","description":"Place of residence, as published."},"residence_country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Residence Country","description":"ISO 3166-1 alpha-2."},"nationality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nationality","description":"Nationality, as published."},"origin":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origin","description":"Place of origin (Swiss registers)."},"company":{"anyOf":[{"$ref":"#/components/schemas/CompanyRef"},{"type":"null"}],"description":"When the function holder is a company."},"source":{"type":"string","title":"Source","description":"Source of the entry."},"person_id":{"type":"string","title":"Person Id","description":"Stable key of this person within Cormorant (`prs_…`)."}},"additionalProperties":false,"type":"object","required":["name","role","source","person_id"],"title":"Person","description":"An officer, signatory or other function holder as published by the register."},"PlanSummary":{"properties":{"id":{"type":"integer","title":"Id","description":"Plan version id.","examples":[1]},"code":{"type":"string","title":"Code","description":"Plan code.","examples":["standard-usd"]},"version":{"type":"integer","title":"Version","description":"Plan version.","examples":[1]},"name":{"type":"string","title":"Name","description":"Plan name.","examples":["Standard (USD)"]},"currency":{"type":"string","title":"Currency","description":"Plan currency.","examples":["USD"]},"complimentary":{"type":"boolean","title":"Complimentary","description":"A complimentary plan.","examples":[false]}},"type":"object","required":["id","code","version","name","currency","complimentary"],"title":"PlanSummary","description":"The price plan version that prices the period."},"PrimarySource":{"properties":{"url":{"type":"string","title":"Url","description":"Absolute URL of the linked document."},"kind":{"type":"string","enum":["court","government","press_release","doi","pdf"],"title":"Kind","description":"What the link points to."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text","description":"The link text, if any."}},"type":"object","required":["url","kind","text"],"title":"PrimarySource"},"Provenance":{"properties":{"source":{"type":"string","title":"Source","description":"Source of the chosen claim.","examples":["gleif"]},"observed_at":{"type":"string","title":"Observed At","description":"When the value was first observed."},"confirmed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Confirmed At","description":"Last confirmation by the source."},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sha256","description":"Raw document of the claim, if any."},"conflict":{"type":"boolean","title":"Conflict","description":"True when another source currently claims a different value.","default":false}},"additionalProperties":false,"type":"object","required":["source","observed_at"],"title":"Provenance","description":"Which claim the resolved value of a field comes from."},"Quality":{"properties":{"completeness":{"type":"number","title":"Completeness","description":"0–1 share of core fields filled.","examples":[0.82]},"conflicts":{"items":{"$ref":"#/components/schemas/Conflict"},"type":"array","title":"Conflicts","description":"Fields where sources disagree."}},"additionalProperties":false,"type":"object","required":["completeness"],"title":"Quality","description":"Completeness and conflicts."},"Quota":{"properties":{"key":{"type":"string","title":"Key","description":"Prefix of the calling key.","examples":["cmr_AbCdEf"]},"role":{"type":"string","enum":["account_admin","standard"],"title":"Role","description":"Role of the calling key.","examples":["standard"]},"period":{"type":"string","title":"Period","description":"Current month (`YYYY-MM`, UTC).","examples":["2026-10"]},"resets_at":{"type":"string","title":"Resets At","description":"Start of the next month.","examples":["2026-11-01T00:00:00+00:00"]},"as_of":{"type":"string","title":"As Of","description":"Now.","examples":["2026-10-19T11:05:02+00:00"]},"usage_refreshed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage Refreshed At","description":"Last aggregation (spend is exact up to it).","examples":["2026-10-19T11:05:00+00:00"]},"keys":{"items":{"$ref":"#/components/schemas/QuotaKey"},"type":"array","title":"Keys","description":"The calling key (standard key) or every active key of the account (account admin key)."},"project":{"$ref":"#/components/schemas/QuotaProject","description":"Limits of the calling key's project."},"customer":{"anyOf":[{"$ref":"#/components/schemas/QuotaCustomer"},{"type":"null"}],"description":"Account admin keys of a customer: plan allowances."},"events":{"items":{"$ref":"#/components/schemas/AlertEvent"},"type":"array","title":"Events","description":"Thresholds (50 / 80 / 100 %) crossed this month in the caller's scope, newest first."},"spend_budget":{"anyOf":[{"$ref":"#/components/schemas/SpendBudget"},{"type":"null"}],"description":"This month's spend against the spend caps, per key and per customer (`cap: null` when no cap is set)."},"alert_email":{"anyOf":[{"$ref":"#/components/schemas/QuotaAlertEmail"},{"type":"null"}],"description":"Alert e-mail deliverability (\"alert e-mail undeliverable\" after a hard bounce or complaint). Webhooks are not affected."}},"type":"object","required":["key","role","period","resets_at","as_of","usage_refreshed_at","keys","project","events"],"title":"Quota","description":"Answer of `GET /v1/quota`."},"QuotaAlertEmail":{"properties":{"status":{"type":"string","enum":["deliverable","partially_undeliverable","undeliverable","not_set"],"title":"Status","description":"`undeliverable`: every alert address hard-bounced or reported a mail as spam; `partially_undeliverable`: some did. No further alert mails go to those addresses until they are changed or cleared (contact us).","examples":["deliverable"]},"addresses":{"type":"integer","title":"Addresses","description":"Alert addresses set.","default":0,"examples":[2]},"undeliverable":{"type":"integer","title":"Undeliverable","description":"How many of them are undeliverable.","default":0,"examples":[0]},"reason":{"anyOf":[{"type":"string","enum":["bounced","complained"]},{"type":"null"}],"title":"Reason","description":"With `undeliverable`: why.","examples":[null]},"since":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since","description":"With `undeliverable`: since when.","examples":[null]}},"type":"object","required":["status"],"title":"QuotaAlertEmail","description":"Whether usage alert e-mails reach the account's alert address."},"QuotaCustomer":{"properties":{"customer":{"type":"string","title":"Customer","description":"Customer name.","examples":["Acme"]},"currency":{"type":"string","title":"Currency","description":"Invoice currency.","examples":["USD"]},"allowances":{"items":{"$ref":"#/components/schemas/QuotaEntry"},"type":"array","title":"Allowances","description":"The plan's included units per meter this month (`included.<meter>`)."}},"type":"object","required":["customer","currency","allowances"],"title":"QuotaCustomer","description":"The customer account (account admin keys)."},"QuotaEntry":{"properties":{"name":{"type":"string","title":"Name","description":"`monthly_spend`, `monthly_requests.<category>`, `rate_limit`, `monthly_provider_budget` or `included.<meter>`.","examples":["monthly_requests.fetch"]},"unit":{"type":"string","title":"Unit","description":"Currency, `requests`, `requests/s` or the meter's unit.","examples":["requests"]},"limit":{"anyOf":[{"type":"integer"},{"type":"string"}],"title":"Limit","description":"The limit (money as a decimal string).","examples":[100000]},"used":{"anyOf":[{"type":"integer"},{"type":"string"}],"title":"Used","description":"Used this period (or this second).","examples":[81234]},"reserved":{"anyOf":[{"type":"integer"},{"type":"string"}],"title":"Reserved","description":"Spend estimated since the last aggregation (5 minutes), or provider spend held for calls in flight.","examples":[0]},"remaining":{"anyOf":[{"type":"integer"},{"type":"string"}],"title":"Remaining","description":"`limit - used - reserved`, at least 0.","examples":[18766]},"resets_at":{"type":"string","title":"Resets At","description":"When the period (or the one-second window) resets.","examples":["2026-11-01T00:00:00+00:00"]},"projected_end_of_period":{"anyOf":[{"type":"integer"},{"type":"string"},{"type":"null"}],"title":"Projected End Of Period","description":"`used + reserved` extrapolated linearly to the end of the month; `null` for rate limits.","examples":[132550]},"status":{"type":"string","enum":["ok","warning","exhausted"],"title":"Status","description":"`warning` from 80 %, `exhausted` at 100 %.","examples":["warning"]}},"type":"object","required":["name","unit","limit","used","reserved","remaining","resets_at","projected_end_of_period","status"],"title":"QuotaEntry","description":"One limit or allowance and how much of it is used."},"QuotaKey":{"properties":{"key":{"type":"string","title":"Key","description":"Key prefix.","examples":["cmr_AbCdEf"]},"key_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key Label","description":"Label.","examples":["crawler"]},"key_role":{"type":"string","enum":["account_admin","standard"],"title":"Key Role","description":"Role.","examples":["standard"]},"project":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project","description":"Project.","examples":["acme-crawler"]},"is_self":{"type":"boolean","title":"Is Self","description":"The calling key.","examples":[true]},"allowed_categories":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Categories","description":"What the key may do; `null` = all.","examples":[null]},"usage":{"$ref":"#/components/schemas/QuotaKeyUsage","description":"Use this month."},"limits":{"items":{"$ref":"#/components/schemas/QuotaEntry"},"type":"array","title":"Limits","description":"Each limit set on the key."}},"type":"object","required":["key","key_label","key_role","project","is_self","allowed_categories","usage","limits"],"title":"QuotaKey","description":"One key's limits."},"QuotaKeyUsage":{"properties":{"requests":{"additionalProperties":{"type":"integer"},"type":"object","title":"Requests","description":"Requests per category (`search`, `fetch`, `fetch_premium`, `company`).","examples":[{"fetch":81234,"fetch_premium":412,"search":120}]},"spend":{"type":"string","title":"Spend","description":"Charges (or provider cost without a customer) including the estimate since the last aggregation.","examples":["38.12"]},"currency":{"type":"string","title":"Currency","description":"Currency of `spend`.","examples":["USD"]}},"type":"object","required":["requests","spend","currency"],"title":"QuotaKeyUsage","description":"What a key used this month."},"QuotaProject":{"properties":{"project":{"type":"string","title":"Project","description":"Project name.","examples":["acme-crawler"]},"limits":{"items":{"$ref":"#/components/schemas/QuotaEntry"},"type":"array","title":"Limits","description":"Requests per second; the provider budget for projects without an external customer."}},"type":"object","required":["project","limits"],"title":"QuotaProject","description":"The calling key's project."},"Ready":{"properties":{"status":{"type":"string","enum":["ready","not_ready"],"title":"Status","description":"Overall readiness."},"checks":{"additionalProperties":{"type":"string"},"type":"object","title":"Checks","description":"Result per dependency (never secrets).","examples":[{"object_storage":"ok","postgres":"ok","redis":"ok","searxng":"2 instance(s)"}]},"version":{"type":"string","title":"Version","description":"API version.","examples":["1.0.0"]}},"type":"object","required":["status","checks","version"],"title":"Ready","description":"Readiness: PostgreSQL, Redis and at least one SearXNG instance."},"Redirect":{"properties":{"url":{"type":"string","title":"Url","description":"URL that answered with a redirect.","examples":["http://example.com/ar25"]},"status":{"type":"integer","title":"Status","description":"Redirect status code.","examples":[301]},"location":{"type":"string","title":"Location","description":"Resolved target of the `Location` header.","examples":["https://www.example.com/annual-report-2025.pdf"]}},"type":"object","required":["url","status","location"],"title":"Redirect","description":"One redirect hop before `final_url`."},"Register":{"properties":{"authority":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authority","description":"Register authority (name or GLEIF RA code)."},"court":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Court","description":"Register court (Germany) or cantonal office."},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id","description":"The company's id in that register."}},"additionalProperties":false,"type":"object","title":"Register","description":"Register the company is entered in."},"Relationship":{"properties":{"type":{"type":"string","enum":["subsidiary","branch_of","branch","head_office","merged_into","absorbed","predecessor","successor","auditor","fund_manager","other"],"title":"Type","description":"Kind of link."},"company":{"$ref":"#/components/schemas/CompanyRef","description":"The other company."},"since":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since","description":"Start (date)."},"until":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Until","description":"End (date)."}},"additionalProperties":false,"type":"object","required":["type","company"],"title":"Relationship","description":"A link to another company."},"RequestLedger":{"properties":{"project":{"type":"string","title":"Project","description":"Project of the API key.","examples":["acme-crawler"]},"key":{"type":"string","title":"Key","description":"Prefix of the calling key.","examples":["cmr_AbCdEf"]},"role":{"type":"string","enum":["account_admin","standard"],"title":"Role","description":"Role of the calling key.","examples":["standard"]},"scope":{"$ref":"#/components/schemas/UsageScope","description":"The customer, projects and keys covered."},"from":{"type":"string","title":"From","description":"First day.","examples":["2026-09-20"]},"to":{"type":"string","title":"To","description":"Last day.","examples":["2026-10-19"]},"as_of":{"type":"string","title":"As Of","description":"Now: the ledger is real time.","examples":["2026-10-19T11:05:02+00:00"]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"Currency of `charge`.","examples":["USD"]},"limit":{"type":"integer","title":"Limit","description":"Page size.","examples":[100]},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as `cursor` for the next (older) page; `null` on the last page.","examples":["MjAyNi0xMC0xOVQxMTowMjoxMyswMDowMHw5ODc2"]},"requests":{"items":{"$ref":"#/components/schemas/LedgerRequest"},"type":"array","title":"Requests","description":"Newest first."}},"type":"object","required":["project","key","role","scope","from","to","as_of","currency","limit","next_cursor","requests"],"title":"RequestLedger","description":"Answer of `GET /v1/requests`."},"ResolveBody":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Name","description":"Company name."},"country":{"anyOf":[{"type":"string","pattern":"^[A-Za-z]{2}$"},{"type":"null"}],"title":"Country","description":"ISO 3166-1 alpha-2."},"city":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"City","description":"City."},"identifiers":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Identifiers","description":"`scheme:value` identifiers (exact; tried first)."},"isin":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Isin","description":"ISIN of a security the company issued; the same as adding `isin:<value>` to `identifiers` (check digit verified, `422 invalid_identifier`).","examples":["CH0038863350"]},"limit":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Limit","description":"Candidates to return.","default":5},"persist":{"type":"boolean","title":"Persist","description":"Add the `match` to the register when it was found only at a live source, so it comes back with its `cmp_` id and `in_register: true` (as `GET /v1/companies/{ref}` would). `false`: leave the register untouched; the match then may have `id: null` and a `scheme:value` `ref`.","default":true}},"type":"object","title":"ResolveBody","description":"What you know about a company.","examples":[{"city":"Zürich","country":"CH","name":"UBS AG"}]},"SearchBody":{"properties":{"query":{"type":"string","maxLength":1000,"minLength":1,"title":"Query","description":"Search query (whitespace and case are normalised for caching).","examples":["Nestlé sustainability report 2025"]},"language":{"anyOf":[{"type":"string","pattern":"^[A-Za-z]{2,3}(-[A-Za-z]{2})?$"},{"type":"null"}],"title":"Language","description":"Result language, ISO 639-1 (optionally with region, e.g. `de-CH`).","examples":["en"]},"country":{"anyOf":[{"type":"string","pattern":"^[A-Za-z]{2}$"},{"type":"null"}],"title":"Country","description":"Country bias, ISO 3166-1 alpha-2.","examples":["CH"]},"max_results":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Max Results","description":"Maximum number of results.","default":20,"examples":[20]},"freshness":{"anyOf":[{"type":"string","enum":["day","week","month","year","pd","pw","pm","py"]},{"type":"null"}],"title":"Freshness","description":"Only results from the last day, week, month or year (`pd`/`pw`/`pm`/`py` are accepted as aliases).","examples":["month"]},"cache_ttl_s":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Cache Ttl S","description":"Maximum acceptable age of a cached answer in seconds; `0` bypasses the cache. Default: the cache's own TTL.","examples":[86400]},"project_ref":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Project Ref","description":"Your own text stored with your usage (e.g. the entity this request is for).","examples":["company:4711"]}},"type":"object","required":["query"],"title":"SearchBody","description":"A web search. Cached for 7 days per normalised query and options.","examples":[{"country":"CH","language":"en","query":"Nestlé sustainability report 2025"}]},"SearchResponse":{"properties":{"query":{"type":"string","title":"Query","description":"The query as sent.","examples":["Nestlé sustainability report 2025"]},"results":{"items":{"$ref":"#/components/schemas/SearchResult"},"type":"array","title":"Results","description":"Merged, deduplicated results; empty when nothing was found or on error."},"provider":{"anyOf":[{"type":"string","enum":["searxng","brave"]},{"type":"null"}],"title":"Provider","description":"Who answered: Cormorant's SearXNG instances, or the Brave Search API fallback. `null` when no provider answered.","examples":["searxng"]},"fallback_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fallback Reason","description":"Why the Brave fallback was considered (`searxng_error`, `searxng_timeout`, `no_searxng_instance`, `unresponsive_engines`, `captcha_engines`, `too_few_results`); `null` when SearXNG's answer was good enough.","examples":[null]},"unresponsive_engines":{"items":{"type":"string"},"type":"array","title":"Unresponsive Engines","description":"SearXNG engines that failed for this query.","examples":[["yandex"]]},"cached":{"type":"boolean","title":"Cached","description":"True when served from the shared search cache.","examples":[false]},"cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Usd","description":"Cormorant's provider spend caused by this request in USD (search fallback and premium routes; cache hits and standard routes cause no provider cost). `null` for keys of an external customer: what you are charged is in `GET /v1/usage` and `GET /v1/requests`.","examples":[0.0]},"billing_category":{"type":"string","title":"Billing Category","description":"The billing category the request counts toward (`search`, `search_fallback`, `search_cached`, `fetch_own`, `fetch_premium`, `fetch_cached`, `company`, `company_cached`, `sec`, `sec_cached`, `company_profile`, `company_profile_cached`): it maps the request to the meters and charges of your plan.","examples":["fetch_own"]},"billing":{"anyOf":[{"$ref":"#/components/schemas/Billing"},{"type":"null"}],"description":"What this request is charged under your plan (`charge`, `currency`, `within_allowance`, units per meter), priced like the invoice. Absent on answers that were not recorded (invalid input, limits)."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Set only when the providers could not answer (e.g. `budget_exhausted`, `brave_http_429`, `searxng_timeout`). A search that found nothing has `results: []` and `error: null`.","examples":[null]},"request_id":{"type":"string","title":"Request Id","description":"Identifier of this request (`req_…`; batch items use `<job_id>:<index>`). Quote it when asking the operator about a request.","examples":["req_6b1f2c0e9a7d4b5c8e3f1a2b3c4d5e6f"]},"debug_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Debug Url","description":"Only in the answer to a debug request (header `X-Cormorant-Debug: 1` with a key enabled for debugging; available on request): a link to this request's diagnostic record for Cormorant support. Quote it when you report a problem; it cannot be opened with an API key.","examples":[null]}},"type":"object","required":["query","results","provider","fallback_reason","unresponsive_engines","cached","cost_usd","billing_category","error","request_id"],"title":"SearchResponse","description":"Answer of `POST /v1/search` (and of each batch search item)."},"SearchResult":{"properties":{"url":{"type":"string","title":"Url","description":"Result URL as returned by the engines.","examples":["https://www.nestle.com/sustainability/reporting"]},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Result title (whitespace-normalised).","examples":["Creating Shared Value and Sustainability Report 2025"]},"snippets":{"items":{"type":"string"},"type":"array","title":"Snippets","description":"All distinct snippets for this URL across engines and providers.","examples":[["Our 2025 report covers ...","Download the full report ..."]]},"engines":{"items":{"type":"string"},"type":"array","title":"Engines","description":"Engines that returned this URL (`brave_api` for the Brave Search API).","examples":[["bing","yahoo","brave_api"]]},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published At","description":"Publication date reported by an engine (ISO 8601), if any.","examples":["2026-03-02T00:00:00"]},"rank":{"type":"integer","title":"Rank","description":"1-based position after merging.","examples":[1]}},"type":"object","required":["url","title","snippets","engines","published_at","rank"],"title":"SearchResult","description":"One deduplicated result. Every distinct snippet and engine seen for the\nURL is kept, in order of first appearance."},"SecBatchItem":{"properties":{"op":{"type":"string","enum":["resolve","submissions","latest","filing","facts","document"],"title":"Op","description":"`resolve` (`ticker`, `cik` or `name`), `submissions` / `latest` / `facts` (`cik` or `ticker`), `filing` (`cik`, `accession`), `document` (`cik`, `accession`, `document`).","examples":["latest"]},"ticker":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Ticker","description":"Ticker (`BRK.B` = `BRK-B`).","examples":["TSN"]},"cik":{"anyOf":[{"type":"integer"},{"type":"string"},{"type":"null"}],"title":"Cik","description":"CIK: `100493` or `0000100493`.","examples":[100493]},"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Name","description":"`resolve` by name."},"forms":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Forms","description":"`submissions` / `latest`: form types (`latest` default `10-K,20-F,40-F`).","examples":["10-K,20-F,40-F"]},"since":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since","description":"`submissions`: filed on or after."},"until":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Until","description":"`submissions`: filed on or before."},"limit":{"type":"integer","maximum":10000.0,"minimum":1.0,"title":"Limit","description":"`submissions`: filings.","default":100},"history":{"type":"boolean","title":"History","description":"`submissions`: read older pages too.","default":true},"isin":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Isin","description":"`resolve` / `submissions` / `latest` / `facts`: ISIN instead of a CIK.","examples":["DK0062498333"]},"accession":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accession","description":"`filing` / `document`: accession number, with or without dashes.","examples":["0000100493-25-000070"]},"document":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document","description":"`document`: file name within the filing.","examples":["tsn-20250927.htm"]},"max_bytes":{"anyOf":[{"type":"integer","maximum":52428800.0,"minimum":1.0},{"type":"null"}],"title":"Max Bytes","description":"`document`: largest body."},"accept_pdf":{"type":"boolean","title":"Accept Pdf","description":"`document`: accept PDF documents.","default":true},"include_html":{"type":"boolean","title":"Include Html","description":"`document`: keep `html` in the stored result.","default":false},"project_ref":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Project Ref","description":"Your own reference, kept in usage."}},"additionalProperties":false,"type":"object","required":["op"],"title":"SecBatchItem","description":"One SEC operation: `op` plus the parameters of the matching\n`/v1/sec/...` endpoint."},"SecCompany":{"properties":{"cik":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cik","description":"Central Index Key.","examples":[100493]},"cik_padded":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cik Padded","description":"CIK as 10 digits.","examples":["0000100493"]},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Company name (SEC's conformed name).","examples":["TYSON FOODS, INC."]},"tickers":{"items":{"type":"string"},"type":"array","title":"Tickers","description":"Ticker symbols, primary first.","examples":[["TSN"]]},"exchanges":{"items":{"type":"string"},"type":"array","title":"Exchanges","description":"Exchanges of the tickers (from company_tickers_exchange.json).","examples":[["NYSE"]]}},"type":"object","title":"SecCompany","description":"A company as SEC lists it."},"SecDocument":{"properties":{"sequence":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sequence","description":"Sequence number in the filing.","examples":[1]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description.","examples":["10-K"]},"document":{"type":"string","title":"Document","description":"File name.","examples":["tsn-20250927.htm"]},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type","description":"Document type (form or exhibit).","examples":["10-K"]},"size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Size","description":"Size in bytes.","examples":[2563419]},"url":{"type":"string","title":"Url","description":"URL (fetch it with `POST /v1/sec/documents/fetch`)."}},"type":"object","required":["sequence","description","document","type","size","url"],"title":"SecDocument","description":"A document of a filing."},"SecDocumentFetchBody":{"properties":{"cik":{"anyOf":[{"type":"integer"},{"type":"string"}],"title":"Cik","description":"CIK: 100493 or \"0000100493\".","examples":[100493]},"accession":{"type":"string","title":"Accession","description":"Accession number, with or without dashes.","examples":["0000100493-25-000070"]},"document":{"type":"string","title":"Document","description":"File name within the filing (`primary_document` or a document of the filing index).","examples":["tsn-20250927.htm"]},"max_bytes":{"type":"integer","maximum":52428800.0,"minimum":1.0,"title":"Max Bytes","description":"Largest body accepted.","default":52428800},"include_html":{"type":"boolean","title":"Include Html","description":"Return `html` for HTML documents.","default":true},"accept_pdf":{"type":"boolean","title":"Accept Pdf","description":"Accept PDF documents.","default":true},"cache_ttl_s":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Cache Ttl S","description":"Maximum acceptable age of a cached copy; filing documents are immutable and cached a year, so set this only to force a revalidation."},"timeout_s":{"anyOf":[{"type":"number","maximum":150.0,"exclusiveMinimum":0.0},{"type":"null"}],"title":"Timeout S","description":"Overall deadline."},"project_ref":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Project Ref","description":"Your own reference, kept in usage."}},"additionalProperties":false,"type":"object","required":["cik","accession","document"],"title":"SecDocumentFetchBody","description":"Body of `POST /v1/sec/documents/fetch`."},"SecFacts":{"properties":{"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"`null` on success, else `unknown_identifier` (SEC knows no company by this ticker, CIK, name or ISIN, and neither does Cormorant), `not_sec_filer` (the company is known — a non-US listing, the company register, GLEIF — but not registered with the SEC under it; see `hint`), `not_found` (no such filing, document or filing of the requested forms), `ambiguous`, `invalid_identifier`, `rate_limited`, `sec_unavailable`, `sec_not_configured`, or a fetch error (`timeout`, `too_large`, `robots_disallowed`, …).","examples":[null]},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Human-readable detail of `error`.","examples":[null]},"hint":{"anyOf":[{"$ref":"#/components/schemas/SecHint"},{"type":"null"}],"description":"With `not_sec_filer` (and on a resolve by ISIN): what Cormorant knows — `company` (`id`, `name`, `country`, `listings`, `lei`, `isins`), `listing` (the home listing, `MIC:SYMBOL`) and `sec_candidates` (SEC filers with the company's name, e.g. the ADR of a foreign private issuer: retry with that ticker).","examples":[null]},"retry_after_s":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Retry After S","description":"With `rate_limited` / `sec_unavailable`: seconds before a retry makes sense.","examples":[null]},"cached":{"type":"boolean","title":"Cached","description":"`true` when every SEC document came from Cormorant's cache.","default":false,"examples":[true]},"retrieved_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retrieved At","description":"When the oldest SEC document used was retrieved (ISO 8601).","examples":["2026-10-19T08:12:03+00:00"]},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url","description":"The main SEC document the answer is built from.","examples":["https://data.sec.gov/submissions/CIK0000100493.json"]},"body_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body Url","description":"Exact bytes of that document (the raw SEC JSON/HTML), like `body_url` of a fetch.","examples":["https://api.cormorant.ch/v1/bodies/9f2c…"]},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sha256","description":"SHA-256 of those bytes.","examples":["9f2c…"]},"billing":{"anyOf":[{"$ref":"#/components/schemas/Billing"},{"type":"null"}],"description":"What this request is charged under your plan (`charge`, `currency`, `within_allowance`, units per meter), priced like the invoice. Absent on answers that were not recorded (invalid input, limits)."},"request_id":{"type":"string","title":"Request Id","description":"Request id.","examples":["req_7c1e…"]},"cik":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cik","description":"Central Index Key.","examples":[100493]},"cik_padded":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cik Padded","description":"CIK as 10 digits.","examples":["0000100493"]},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Entity name.","examples":["TYSON FOODS, INC."]},"taxonomies":{"additionalProperties":{"type":"integer"},"type":"object","title":"Taxonomies","description":"Concepts per taxonomy.","examples":[{"dei":2,"us-gaap":512}]},"concepts":{"type":"integer","title":"Concepts","description":"Concepts in total.","default":0,"examples":[514]},"bytes":{"type":"integer","title":"Bytes","description":"Size of the JSON.","default":0,"examples":[4801233]}},"type":"object","required":["request_id"],"title":"SecFacts","description":"Answer of `GET /v1/sec/companies/{cik}/facts`: a summary; the complete\nXBRL company facts JSON is at `body_url`."},"SecFiling":{"properties":{"accession":{"type":"string","title":"Accession","description":"Accession number.","examples":["0000100493-25-000070"]},"form":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Form","description":"Form type.","examples":["10-K"]},"filing_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filing Date","description":"Filing date.","examples":["2025-11-13"]},"report_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Date","description":"Period of report (fiscal period end).","examples":["2025-09-27"]},"acceptance_datetime":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Acceptance Datetime","description":"When EDGAR accepted it.","examples":["2025-11-13T21:05:11.000Z"]},"act":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Act","description":"Securities act.","examples":["34"]},"file_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Number","description":"SEC file number.","examples":["001-14704"]},"film_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Film Number","description":"Film number.","examples":["251480433"]},"items":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Items","description":"8-K items.","examples":[null]},"core_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Core Type","description":"Core form type.","examples":["10-K"]},"size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Size","description":"Size of the submission in bytes.","examples":[11873456]},"is_xbrl":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Xbrl","description":"Has XBRL data.","examples":[true]},"is_inline_xbrl":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Inline Xbrl","description":"Primary document is inline XBRL.","examples":[true]},"primary_document":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Document","description":"File name of the primary document.","examples":["tsn-20250927.htm"]},"primary_document_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Document Description","description":"Its description.","examples":["10-K"]},"primary_document_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Document Url","description":"URL of the primary document (fetch it with `POST /v1/sec/documents/fetch`).","examples":["https://www.sec.gov/Archives/edgar/data/100493/000010049325000070/tsn-20250927.htm"]},"index_url":{"type":"string","title":"Index Url","description":"Filing index page.","examples":["https://www.sec.gov/Archives/edgar/data/100493/000010049325000070/0000100493-25-000070-index.htm"]},"is_amendment":{"type":"boolean","title":"Is Amendment","description":"An amendment (`…/A` form).","examples":[false]}},"type":"object","required":["accession","form","filing_date","report_date","acceptance_datetime","act","file_number","film_number","items","core_type","size","is_xbrl","is_inline_xbrl","primary_document","primary_document_description","primary_document_url","index_url","is_amendment"],"title":"SecFiling","description":"One filing of a company."},"SecFilingIndex":{"properties":{"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"`null` on success, else `unknown_identifier` (SEC knows no company by this ticker, CIK, name or ISIN, and neither does Cormorant), `not_sec_filer` (the company is known — a non-US listing, the company register, GLEIF — but not registered with the SEC under it; see `hint`), `not_found` (no such filing, document or filing of the requested forms), `ambiguous`, `invalid_identifier`, `rate_limited`, `sec_unavailable`, `sec_not_configured`, or a fetch error (`timeout`, `too_large`, `robots_disallowed`, …).","examples":[null]},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Human-readable detail of `error`.","examples":[null]},"hint":{"anyOf":[{"$ref":"#/components/schemas/SecHint"},{"type":"null"}],"description":"With `not_sec_filer` (and on a resolve by ISIN): what Cormorant knows — `company` (`id`, `name`, `country`, `listings`, `lei`, `isins`), `listing` (the home listing, `MIC:SYMBOL`) and `sec_candidates` (SEC filers with the company's name, e.g. the ADR of a foreign private issuer: retry with that ticker).","examples":[null]},"retry_after_s":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Retry After S","description":"With `rate_limited` / `sec_unavailable`: seconds before a retry makes sense.","examples":[null]},"cached":{"type":"boolean","title":"Cached","description":"`true` when every SEC document came from Cormorant's cache.","default":false,"examples":[true]},"retrieved_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retrieved At","description":"When the oldest SEC document used was retrieved (ISO 8601).","examples":["2026-10-19T08:12:03+00:00"]},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url","description":"The main SEC document the answer is built from.","examples":["https://data.sec.gov/submissions/CIK0000100493.json"]},"body_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body Url","description":"Exact bytes of that document (the raw SEC JSON/HTML), like `body_url` of a fetch.","examples":["https://api.cormorant.ch/v1/bodies/9f2c…"]},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sha256","description":"SHA-256 of those bytes.","examples":["9f2c…"]},"billing":{"anyOf":[{"$ref":"#/components/schemas/Billing"},{"type":"null"}],"description":"What this request is charged under your plan (`charge`, `currency`, `within_allowance`, units per meter), priced like the invoice. Absent on answers that were not recorded (invalid input, limits)."},"request_id":{"type":"string","title":"Request Id","description":"Request id.","examples":["req_7c1e…"]},"cik":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cik","description":"Central Index Key.","examples":[100493]},"cik_padded":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cik Padded","description":"CIK as 10 digits.","examples":["0000100493"]},"accession":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accession","description":"Accession number.","examples":["0000100493-25-000070"]},"accession_nodash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accession Nodash","description":"Accession number without dashes.","examples":["000010049325000070"]},"company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company","description":"Filer name from the index page.","examples":["TYSON FOODS, INC."]},"form":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Form","description":"Form type.","examples":["10-K"]},"filing_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filing Date","description":"Filing date.","examples":["2025-11-13"]},"report_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Date","description":"Period of report.","examples":["2025-09-27"]},"accepted":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accepted","description":"Acceptance time as SEC shows it.","examples":["2025-11-13 16:05:11"]},"is_amendment":{"type":"boolean","title":"Is Amendment","description":"An amendment (`…/A` form).","default":false},"index_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Index Url","description":"Filing index page."},"folder_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Folder Url","description":"Filing folder."},"index_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Index Source","description":"`index_htm` (with types and descriptions) or `index_json` (the folder listing, when the index page has no document table).","examples":["index_htm"]},"documents":{"items":{"$ref":"#/components/schemas/SecDocument"},"type":"array","title":"Documents","description":"Documents of the filing."}},"type":"object","required":["request_id"],"title":"SecFilingIndex","description":"Answer of `GET /v1/sec/filings/{cik}/{accession}`."},"SecHint":{"properties":{"listing":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Listing","description":"The home listing (`MIC:SYMBOL`), when known.","examples":["XCSE:NOVO-B"]},"company":{"anyOf":[{"$ref":"#/components/schemas/SecHintCompany"},{"type":"null"}],"description":"The company in Cormorant's company register."},"sec_candidates":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Sec Candidates","description":"SEC filers with the company's name (`cik`, `cik_padded`, `title`, `tickers`, `exchanges`), e.g. the ADR of a foreign private issuer: retry with that ticker."},"same_symbol_on_sec":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Same Symbol On Sec","description":"A non-US listing whose symbol SEC also lists (maybe, not surely, the same company)."},"candidates":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Candidates","description":"With `ambiguous`: the SEC companies that match."}},"type":"object","title":"SecHint","description":"What Cormorant knows about a company SEC does not know by the given identifier."},"SecHintCompany":{"properties":{"id":{"type":"string","title":"Id","description":"Register id.","examples":["cmp_01JA2B3C4D5E6F7G8H9J0KMNPQ"]},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Legal name.","examples":["Novo Nordisk A/S"]},"other_names":{"items":{"type":"string"},"type":"array","title":"Other Names","description":"Other forms of the name (other sources, languages)."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"ISO 3166-1 alpha-2.","examples":["DK"]},"listings":{"items":{"type":"string"},"type":"array","title":"Listings","description":"Listings as `MIC:SYMBOL`.","examples":[["XCSE:NOVO-B"]]},"lei":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lei","description":"LEI.","examples":[null]},"isins":{"items":{"type":"string"},"type":"array","title":"Isins","description":"ISINs.","examples":[["DK0062498333"]]}},"type":"object","required":["id","name","country"],"title":"SecHintCompany","description":"The company as Cormorant's company register knows it."},"SecHistoryFile":{"properties":{"name":{"type":"string","title":"Name","description":"Page file name.","examples":["CIK0000100493-submissions-001.json"]},"filing_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Filing Count","description":"Filings on the page.","examples":[1180]},"filing_from":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filing From","description":"Oldest filing date on the page.","examples":["1994-01-26"]},"filing_to":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filing To","description":"Newest filing date on the page.","examples":["2015-05-11"]},"url":{"type":"string","title":"Url","description":"The page on data.sec.gov."},"fetched":{"type":"boolean","title":"Fetched","description":"Whether its filings are included in this answer."},"body_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body Url","description":"Exact bytes of the page, when fetched."}},"type":"object","required":["name","filing_count","filing_from","filing_to","url","fetched","body_url"],"title":"SecHistoryFile","description":"A page of a company's older filings (SEC's `filings.files`)."},"SecLatestFiling":{"properties":{"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"`null` on success, else `unknown_identifier` (SEC knows no company by this ticker, CIK, name or ISIN, and neither does Cormorant), `not_sec_filer` (the company is known — a non-US listing, the company register, GLEIF — but not registered with the SEC under it; see `hint`), `not_found` (no such filing, document or filing of the requested forms), `ambiguous`, `invalid_identifier`, `rate_limited`, `sec_unavailable`, `sec_not_configured`, or a fetch error (`timeout`, `too_large`, `robots_disallowed`, …).","examples":[null]},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Human-readable detail of `error`.","examples":[null]},"hint":{"anyOf":[{"$ref":"#/components/schemas/SecHint"},{"type":"null"}],"description":"With `not_sec_filer` (and on a resolve by ISIN): what Cormorant knows — `company` (`id`, `name`, `country`, `listings`, `lei`, `isins`), `listing` (the home listing, `MIC:SYMBOL`) and `sec_candidates` (SEC filers with the company's name, e.g. the ADR of a foreign private issuer: retry with that ticker).","examples":[null]},"retry_after_s":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Retry After S","description":"With `rate_limited` / `sec_unavailable`: seconds before a retry makes sense.","examples":[null]},"cached":{"type":"boolean","title":"Cached","description":"`true` when every SEC document came from Cormorant's cache.","default":false,"examples":[true]},"retrieved_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retrieved At","description":"When the oldest SEC document used was retrieved (ISO 8601).","examples":["2026-10-19T08:12:03+00:00"]},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url","description":"The main SEC document the answer is built from.","examples":["https://data.sec.gov/submissions/CIK0000100493.json"]},"body_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body Url","description":"Exact bytes of that document (the raw SEC JSON/HTML), like `body_url` of a fetch.","examples":["https://api.cormorant.ch/v1/bodies/9f2c…"]},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sha256","description":"SHA-256 of those bytes.","examples":["9f2c…"]},"billing":{"anyOf":[{"$ref":"#/components/schemas/Billing"},{"type":"null"}],"description":"What this request is charged under your plan (`charge`, `currency`, `within_allowance`, units per meter), priced like the invoice. Absent on answers that were not recorded (invalid input, limits)."},"request_id":{"type":"string","title":"Request Id","description":"Request id.","examples":["req_7c1e…"]},"accession":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accession","description":"Accession number.","examples":["0000100493-25-000070"]},"form":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Form","description":"Form type.","examples":["10-K"]},"filing_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filing Date","description":"Filing date.","examples":["2025-11-13"]},"report_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Date","description":"Period of report.","examples":["2025-09-27"]},"acceptance_datetime":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Acceptance Datetime","description":"When EDGAR accepted it."},"act":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Act","description":"Securities act."},"file_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Number","description":"SEC file number."},"film_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Film Number","description":"Film number."},"items":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Items","description":"8-K items."},"core_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Core Type","description":"Core form type."},"size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Size","description":"Size of the submission in bytes."},"is_xbrl":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Xbrl","description":"Has XBRL data."},"is_inline_xbrl":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Inline Xbrl","description":"Primary document is inline XBRL."},"primary_document":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Document","description":"File name of the primary document.","examples":["tsn-20250927.htm"]},"primary_document_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Document Description","description":"Its description."},"primary_document_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Document Url","description":"URL of the primary document."},"index_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Index Url","description":"Filing index page."},"is_amendment":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Amendment","description":"An amendment (`…/A` form).","examples":[false]},"cik":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cik","description":"Central Index Key.","examples":[100493]},"cik_padded":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cik Padded","description":"CIK as 10 digits.","examples":["0000100493"]},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Company name.","examples":["TYSON FOODS, INC."]},"tickers":{"items":{"type":"string"},"type":"array","title":"Tickers","description":"Ticker symbols.","examples":[["TSN"]]},"exchanges":{"items":{"type":"string"},"type":"array","title":"Exchanges","description":"Exchanges.","examples":[["NYSE"]]}},"type":"object","required":["request_id"],"title":"SecLatestFiling","description":"Answer of `GET /v1/sec/companies/{cik}/filings/latest`: the newest\nfiling of the requested forms, with its company."},"SecResolve":{"properties":{"cik":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cik","description":"Central Index Key.","examples":[100493]},"cik_padded":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cik Padded","description":"CIK as 10 digits.","examples":["0000100493"]},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Company name (SEC's conformed name).","examples":["TYSON FOODS, INC."]},"tickers":{"items":{"type":"string"},"type":"array","title":"Tickers","description":"Ticker symbols, primary first.","examples":[["TSN"]]},"exchanges":{"items":{"type":"string"},"type":"array","title":"Exchanges","description":"Exchanges of the tickers (from company_tickers_exchange.json).","examples":[["NYSE"]]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"`null` on success, else `unknown_identifier` (SEC knows no company by this ticker, CIK, name or ISIN, and neither does Cormorant), `not_sec_filer` (the company is known — a non-US listing, the company register, GLEIF — but not registered with the SEC under it; see `hint`), `not_found` (no such filing, document or filing of the requested forms), `ambiguous`, `invalid_identifier`, `rate_limited`, `sec_unavailable`, `sec_not_configured`, or a fetch error (`timeout`, `too_large`, `robots_disallowed`, …).","examples":[null]},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Human-readable detail of `error`.","examples":[null]},"hint":{"anyOf":[{"$ref":"#/components/schemas/SecHint"},{"type":"null"}],"description":"With `not_sec_filer` (and on a resolve by ISIN): what Cormorant knows — `company` (`id`, `name`, `country`, `listings`, `lei`, `isins`), `listing` (the home listing, `MIC:SYMBOL`) and `sec_candidates` (SEC filers with the company's name, e.g. the ADR of a foreign private issuer: retry with that ticker).","examples":[null]},"retry_after_s":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Retry After S","description":"With `rate_limited` / `sec_unavailable`: seconds before a retry makes sense.","examples":[null]},"cached":{"type":"boolean","title":"Cached","description":"`true` when every SEC document came from Cormorant's cache.","default":false,"examples":[true]},"retrieved_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retrieved At","description":"When the oldest SEC document used was retrieved (ISO 8601).","examples":["2026-10-19T08:12:03+00:00"]},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url","description":"The main SEC document the answer is built from.","examples":["https://data.sec.gov/submissions/CIK0000100493.json"]},"body_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body Url","description":"Exact bytes of that document (the raw SEC JSON/HTML), like `body_url` of a fetch.","examples":["https://api.cormorant.ch/v1/bodies/9f2c…"]},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sha256","description":"SHA-256 of those bytes.","examples":["9f2c…"]},"billing":{"anyOf":[{"$ref":"#/components/schemas/Billing"},{"type":"null"}],"description":"What this request is charged under your plan (`charge`, `currency`, `within_allowance`, units per meter), priced like the invoice. Absent on answers that were not recorded (invalid input, limits)."},"request_id":{"type":"string","title":"Request Id","description":"Request id.","examples":["req_7c1e…"]},"ambiguous":{"type":"boolean","title":"Ambiguous","description":"More than one company matches (see `candidates`).","default":false,"examples":[false]},"candidates":{"items":{"$ref":"#/components/schemas/SecCompany"},"type":"array","title":"Candidates","description":"Every match (at most 10), best first."}},"type":"object","required":["request_id"],"title":"SecResolve","description":"Answer of `GET /v1/sec/companies/resolve`. The company fields are those\nof the single match; `null` when the query is ambiguous."},"SecSearch":{"properties":{"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"`null` on success, else `unknown_identifier` (SEC knows no company by this ticker, CIK, name or ISIN, and neither does Cormorant), `not_sec_filer` (the company is known — a non-US listing, the company register, GLEIF — but not registered with the SEC under it; see `hint`), `not_found` (no such filing, document or filing of the requested forms), `ambiguous`, `invalid_identifier`, `rate_limited`, `sec_unavailable`, `sec_not_configured`, or a fetch error (`timeout`, `too_large`, `robots_disallowed`, …).","examples":[null]},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Human-readable detail of `error`.","examples":[null]},"hint":{"anyOf":[{"$ref":"#/components/schemas/SecHint"},{"type":"null"}],"description":"With `not_sec_filer` (and on a resolve by ISIN): what Cormorant knows — `company` (`id`, `name`, `country`, `listings`, `lei`, `isins`), `listing` (the home listing, `MIC:SYMBOL`) and `sec_candidates` (SEC filers with the company's name, e.g. the ADR of a foreign private issuer: retry with that ticker).","examples":[null]},"retry_after_s":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Retry After S","description":"With `rate_limited` / `sec_unavailable`: seconds before a retry makes sense.","examples":[null]},"cached":{"type":"boolean","title":"Cached","description":"`true` when every SEC document came from Cormorant's cache.","default":false,"examples":[true]},"retrieved_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retrieved At","description":"When the oldest SEC document used was retrieved (ISO 8601).","examples":["2026-10-19T08:12:03+00:00"]},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url","description":"The main SEC document the answer is built from.","examples":["https://data.sec.gov/submissions/CIK0000100493.json"]},"body_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body Url","description":"Exact bytes of that document (the raw SEC JSON/HTML), like `body_url` of a fetch.","examples":["https://api.cormorant.ch/v1/bodies/9f2c…"]},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sha256","description":"SHA-256 of those bytes.","examples":["9f2c…"]},"billing":{"anyOf":[{"$ref":"#/components/schemas/Billing"},{"type":"null"}],"description":"What this request is charged under your plan (`charge`, `currency`, `within_allowance`, units per meter), priced like the invoice. Absent on answers that were not recorded (invalid input, limits)."},"request_id":{"type":"string","title":"Request Id","description":"Request id.","examples":["req_7c1e…"]},"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query","description":"The query.","examples":["\"poultry\""]},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total","description":"Matching documents.","examples":[2241]},"total_relation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Total Relation","description":"`eq` (exact) or `gte` (at least).","examples":["eq"]},"hits":{"items":{"$ref":"#/components/schemas/SecSearchHit"},"type":"array","title":"Hits","description":"This page of hits."}},"type":"object","required":["request_id"],"title":"SecSearch","description":"Answer of `GET /v1/sec/search` (EDGAR full-text search, 100 hits per page)."},"SecSearchHit":{"properties":{"accession":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accession","description":"Accession number.","examples":["0000100493-12-000065"]},"ciks":{"items":{"type":"integer"},"type":"array","title":"Ciks","description":"Filer CIKs.","examples":[[100493]]},"display_names":{"items":{"type":"string"},"type":"array","title":"Display Names","description":"Filer names as EDGAR shows them."},"form":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Form","description":"Form type of the filing.","examples":["10-K"]},"root_forms":{"items":{"type":"string"},"type":"array","title":"Root Forms","description":"Base form types.","examples":[["10-K"]]},"file_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Type","description":"Type of the matching document.","examples":["EX-10.14"]},"file_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Description","description":"Its description."},"file_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Date","description":"Filing date.","examples":["2012-11-19"]},"period_ending":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period Ending","description":"Period of report.","examples":["2012-09-29"]},"document":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document","description":"File name of the matching document."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"URL of the matching document."},"index_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Index Url","description":"Filing index page."},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score","description":"Relevance score."}},"type":"object","required":["accession","ciks","display_names","form","root_forms","file_type","file_description","file_date","period_ending","document","url","index_url","score"],"title":"SecSearchHit","description":"A document found by EDGAR full-text search."},"SecSubmissions":{"properties":{"cik":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cik","description":"Central Index Key.","examples":[100493]},"cik_padded":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cik Padded","description":"CIK as 10 digits.","examples":["0000100493"]},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Company name (SEC's conformed name).","examples":["TYSON FOODS, INC."]},"tickers":{"items":{"type":"string"},"type":"array","title":"Tickers","description":"Ticker symbols, primary first.","examples":[["TSN"]]},"exchanges":{"items":{"type":"string"},"type":"array","title":"Exchanges","description":"Exchanges of the tickers (from company_tickers_exchange.json).","examples":[["NYSE"]]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"`null` on success, else `unknown_identifier` (SEC knows no company by this ticker, CIK, name or ISIN, and neither does Cormorant), `not_sec_filer` (the company is known — a non-US listing, the company register, GLEIF — but not registered with the SEC under it; see `hint`), `not_found` (no such filing, document or filing of the requested forms), `ambiguous`, `invalid_identifier`, `rate_limited`, `sec_unavailable`, `sec_not_configured`, or a fetch error (`timeout`, `too_large`, `robots_disallowed`, …).","examples":[null]},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Human-readable detail of `error`.","examples":[null]},"hint":{"anyOf":[{"$ref":"#/components/schemas/SecHint"},{"type":"null"}],"description":"With `not_sec_filer` (and on a resolve by ISIN): what Cormorant knows — `company` (`id`, `name`, `country`, `listings`, `lei`, `isins`), `listing` (the home listing, `MIC:SYMBOL`) and `sec_candidates` (SEC filers with the company's name, e.g. the ADR of a foreign private issuer: retry with that ticker).","examples":[null]},"retry_after_s":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Retry After S","description":"With `rate_limited` / `sec_unavailable`: seconds before a retry makes sense.","examples":[null]},"cached":{"type":"boolean","title":"Cached","description":"`true` when every SEC document came from Cormorant's cache.","default":false,"examples":[true]},"retrieved_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retrieved At","description":"When the oldest SEC document used was retrieved (ISO 8601).","examples":["2026-10-19T08:12:03+00:00"]},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url","description":"The main SEC document the answer is built from.","examples":["https://data.sec.gov/submissions/CIK0000100493.json"]},"body_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body Url","description":"Exact bytes of that document (the raw SEC JSON/HTML), like `body_url` of a fetch.","examples":["https://api.cormorant.ch/v1/bodies/9f2c…"]},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sha256","description":"SHA-256 of those bytes.","examples":["9f2c…"]},"billing":{"anyOf":[{"$ref":"#/components/schemas/Billing"},{"type":"null"}],"description":"What this request is charged under your plan (`charge`, `currency`, `within_allowance`, units per meter), priced like the invoice. Absent on answers that were not recorded (invalid input, limits)."},"request_id":{"type":"string","title":"Request Id","description":"Request id.","examples":["req_7c1e…"]},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Company name.","examples":["TYSON FOODS, INC."]},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type","description":"Entity type.","examples":["operating"]},"sic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sic","description":"SIC code.","examples":["2011"]},"sic_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sic Description","description":"SIC description.","examples":["Meat Packing Plants"]},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Filer category.","examples":["Large accelerated filer"]},"fiscal_year_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Year End","description":"Fiscal year end (MMDD).","examples":["1003"]},"state_of_incorporation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State Of Incorporation","description":"State or country of incorporation.","examples":["DE"]},"ein":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ein","description":"Employer identification number.","examples":["710225165"]},"lei":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lei","description":"Legal entity identifier.","examples":[null]},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website","description":"Website, when SEC lists one.","examples":[null]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone","description":"Business phone.","examples":["479-290-4000"]},"business_address":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":"object"},{"type":"null"}],"title":"Business Address","description":"`street1`, `street2`, `city`, `state_or_country`, `state_or_country_description`, `zip_code`."},"former_names":{"items":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":"object"},"type":"array","title":"Former Names","description":"Earlier names: `name`, `from`, `to`."},"filings":{"items":{"$ref":"#/components/schemas/SecFiling"},"type":"array","title":"Filings","description":"Filings matching the filters, newest first (at most `limit`), from the recent list and the history pages."},"filings_total":{"type":"integer","title":"Filings Total","description":"Matching filings before `limit`.","default":0,"examples":[214]},"truncated":{"type":"boolean","title":"Truncated","description":"`limit` cut the list.","default":false,"examples":[false]},"files":{"items":{"$ref":"#/components/schemas/SecHistoryFile"},"type":"array","title":"Files","description":"Pages of older filings and whether they were read."}},"type":"object","required":["request_id"],"title":"SecSubmissions","description":"Answer of `GET /v1/sec/companies/{cik}/submissions`."},"Security":{"properties":{"isin":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Isin","description":"ISIN."},"ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ticker","description":"Ticker symbol."},"mic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mic","description":"ISO 10383 market identifier."},"listing_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Listing Status","description":"`listed` or `delisted`."}},"additionalProperties":false,"type":"object","title":"Security","description":"A listed security of the company."},"Size":{"properties":{"employees_range":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Employees Range","description":"Employee range, e.g. `50-249`."},"employees":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Employees","description":"Employee count, when filed."},"revenue":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Revenue","description":"Revenue, when filed."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"Currency of the revenue."},"as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"As Of","description":"Reference date."},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Source of the figures."}},"additionalProperties":false,"type":"object","title":"Size","description":"Size, only from official or filing data."},"SourceDocument":{"properties":{"source":{"type":"string","title":"Source","description":"Source name.","examples":["gleif"]},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Source URL."},"retrieved_at":{"type":"string","title":"Retrieved At","description":"Retrieval time (ISO 8601)."},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sha256","description":"SHA-256 of the exact bytes."},"body_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body Url","description":"Download link of the exact bytes."},"content_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Type","description":"Content type."},"licence":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Licence","description":"Licence/terms URL of the source."},"parser_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parser Version","description":"Parser version that read it."}},"additionalProperties":false,"type":"object","required":["source","retrieved_at"],"title":"SourceDocument","description":"A raw document a source served about the company."},"SourceFreshness":{"properties":{"source":{"type":"string","title":"Source","description":"Source name."},"group":{"type":"string","title":"Group","description":"Field group (`core`, `people`, `relationships`, `filings`, `events`, …)."},"last_checked":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Checked","description":"Last fetch from the source."},"last_changed":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Changed","description":"Last time the source's data changed."},"next_refresh_due":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Refresh Due","description":"When it counts as stale."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error of the last attempt, if it failed."}},"additionalProperties":false,"type":"object","required":["source","group"],"title":"SourceFreshness","description":"Freshness of one source's data about the company."},"SpendBudget":{"properties":{"period":{"type":"string","title":"Period","description":"Current month.","examples":["2026-10"]},"currency":{"type":"string","title":"Currency","description":"Currency of the amounts.","examples":["CHF"]},"basis":{"type":"string","enum":["charges","provider_cost"],"title":"Basis","description":"`charges` at your plan price (projects with a customer), or `provider_cost` in USD (projects without one).","examples":["charges"]},"resets_at":{"type":"string","title":"Resets At","description":"Start of the next month."},"keys":{"items":{"$ref":"#/components/schemas/SpendBudgetKey"},"type":"array","title":"Keys","description":"The calling key (standard key) or every active key (account admin key)."},"customer":{"anyOf":[{"$ref":"#/components/schemas/SpendBudgetCustomer"},{"type":"null"}],"description":"Account admin keys of a customer: the whole account. `cap` is always `null`: spend caps are set per key."}},"type":"object","required":["period","currency","basis","resets_at","keys"],"title":"SpendBudget","description":"This month against the spend caps, per key and per customer."},"SpendBudgetCustomer":{"properties":{"cap":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cap","description":"Monthly spend cap (set by the operator per key); `null`: no cap is set.","examples":["100.00"]},"spent":{"type":"string","title":"Spent","description":"Spent this month: charges at your plan price as of the last refresh plus the estimate since (`pending`). Provider cost in USD for projects without a customer.","examples":["12.34"]},"pending":{"type":"string","title":"Pending","description":"Per-request estimate since the last refresh (part of `spent`).","examples":["0.04"]},"remaining":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Remaining","description":"`cap - spent` (never below 0); `null` without a cap.","examples":["87.66"]},"status":{"type":"string","enum":["ok","warning","exhausted","no_cap"],"title":"Status","description":"`warning` from 80 % of the cap, `exhausted` at the cap (requests of the key answer `429 key_budget_exhausted`), `no_cap` when none is set.","examples":["ok"]},"by_kind":{"$ref":"#/components/schemas/SpendByKind","description":"`spent` by request kind (without `pending`)."},"customer":{"type":"string","title":"Customer","description":"Customer name.","examples":["Chipiron"]},"currency":{"type":"string","title":"Currency","description":"Invoice currency.","examples":["CHF"]},"account_charges":{"type":"string","title":"Account Charges","description":"Account-level lines this month: base fee, minimum top-up, contract discount, complimentary credit (not part of `spent`).","examples":["0.00"]},"net_estimate":{"type":"string","title":"Net Estimate","description":"The month's estimate before VAT (`spent` without `pending`, plus `account_charges`).","examples":["12.30"]}},"type":"object","required":["cap","spent","pending","remaining","status","by_kind","customer","currency","account_charges","net_estimate"],"title":"SpendBudgetCustomer"},"SpendBudgetKey":{"properties":{"cap":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cap","description":"Monthly spend cap (set by the operator per key); `null`: no cap is set.","examples":["100.00"]},"spent":{"type":"string","title":"Spent","description":"Spent this month: charges at your plan price as of the last refresh plus the estimate since (`pending`). Provider cost in USD for projects without a customer.","examples":["12.34"]},"pending":{"type":"string","title":"Pending","description":"Per-request estimate since the last refresh (part of `spent`).","examples":["0.04"]},"remaining":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Remaining","description":"`cap - spent` (never below 0); `null` without a cap.","examples":["87.66"]},"status":{"type":"string","enum":["ok","warning","exhausted","no_cap"],"title":"Status","description":"`warning` from 80 % of the cap, `exhausted` at the cap (requests of the key answer `429 key_budget_exhausted`), `no_cap` when none is set.","examples":["ok"]},"by_kind":{"$ref":"#/components/schemas/SpendByKind","description":"`spent` by request kind (without `pending`)."},"key":{"type":"string","title":"Key","description":"Key prefix.","examples":["cmr_AbCdEf"]},"key_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key Label","description":"Key label.","examples":["research"]},"project":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project","description":"Project of the key.","examples":["chipiron"]},"is_self":{"type":"boolean","title":"Is Self","description":"The calling key.","examples":[true]},"currency":{"type":"string","title":"Currency","description":"Currency of the amounts.","examples":["CHF"]}},"type":"object","required":["cap","spent","pending","remaining","status","by_kind","key","key_label","project","is_self","currency"],"title":"SpendBudgetKey"},"SpendByKind":{"properties":{"search":{"type":"string","title":"Search","description":"Decimal string in `currency`.","examples":["1.20"]},"fetch":{"type":"string","title":"Fetch","description":"Decimal string in `currency`.","examples":["11.14"]},"sec":{"type":"string","title":"Sec","description":"Decimal string in `currency`.","examples":["0.00"]},"company_profile":{"type":"string","title":"Company Profile","description":"Decimal string in `currency`. Extended company profiles.","examples":["0.00"]},"company":{"type":"string","title":"Company","description":"Decimal string in `currency`.","examples":["0.00"]}},"type":"object","required":["search","fetch","sec","company_profile","company"],"title":"SpendByKind","description":"`spent` (aggregated part) by request kind."},"StatusComponent":{"properties":{"id":{"type":"string","title":"Id","description":"Stable component id: `api`, `search`, `fetch`, `browser_rendering`, `archive`, `premium_routes`, `batch_jobs`, `storage`, and `company_<source>` for each active company data source (e.g. `company_gleif`).","examples":["fetch"]},"group":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Group","description":"Set for grouped components: `company_data` for the company data sources. A company source counts at most as `degraded` for the overall status.","examples":[null]},"name":{"type":"string","title":"Name","description":"Display name.","examples":["Fetch"]},"description":{"type":"string","title":"Description","description":"What the component covers."},"status":{"type":"string","enum":["operational","maintenance","degraded","partial_outage","major_outage"],"title":"Status","description":"Current status.","examples":["operational"]},"reasons":{"items":{"type":"string"},"type":"array","title":"Reasons","description":"Stable codes saying why the component is not operational (empty when it is): `no_workers`, `queue_lag`, `low_success_rate`, `high_latency`, `engines_reduced`, `engines_unavailable`, `tier_errors`, `scheduler_stalled`, `jobs_waiting`, `database_unreachable`, `cache_unreachable`, `object_storage_unreachable`, `sec_backoff`, `throttled`, `incident`, `maintenance`; company data sources also `canary_failed`, `source_backoff`, `schema_drift`, `parse_failures`.","examples":[[]]},"metrics":{"additionalProperties":true,"type":"object","title":"Metrics","description":"Aggregate numbers behind the status (rates 0–1). Counts and rates cover the last `window_s` seconds (600); a component with fewer than its minimum sample there uses the last hour instead, and its `metrics.window_s` (or `<tier>_window_s`) says which. `success_rate` is `null` only when even that window is short of the minimum; `requests`/`attempts` and `failures` are always given. Keys per component are listed in the API contract; new keys may be added.","examples":[{"batch_queue_backlog":412,"latency_p95_ms":8420,"requests":1873,"success_rate":0.9731,"sync_queue_backlog":0,"sync_queue_lag_s":0.0,"workers_alive":6}]}},"type":"object","required":["id","name","description","status","reasons","metrics"],"title":"StatusComponent","description":"One subsystem. Components that are not part of the deployment (e.g.\npremium routes when none is configured) are not listed."},"StatusComponentDetail":{"properties":{"id":{"type":"string","title":"Id","description":"Stable component id: `api`, `search`, `fetch`, `browser_rendering`, `archive`, `premium_routes`, `batch_jobs`, `storage`, and `company_<source>` for each active company data source (e.g. `company_gleif`).","examples":["fetch"]},"group":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Group","description":"Set for grouped components: `company_data` for the company data sources. A company source counts at most as `degraded` for the overall status.","examples":[null]},"name":{"type":"string","title":"Name","description":"Display name.","examples":["Fetch"]},"description":{"type":"string","title":"Description","description":"What the component covers."},"status":{"type":"string","enum":["operational","maintenance","degraded","partial_outage","major_outage"],"title":"Status","description":"Current status.","examples":["operational"]},"reasons":{"items":{"type":"string"},"type":"array","title":"Reasons","description":"Stable codes saying why the component is not operational (empty when it is): `no_workers`, `queue_lag`, `low_success_rate`, `high_latency`, `engines_reduced`, `engines_unavailable`, `tier_errors`, `scheduler_stalled`, `jobs_waiting`, `database_unreachable`, `cache_unreachable`, `object_storage_unreachable`, `sec_backoff`, `throttled`, `incident`, `maintenance`; company data sources also `canary_failed`, `source_backoff`, `schema_drift`, `parse_failures`.","examples":[[]]},"metrics":{"additionalProperties":true,"type":"object","title":"Metrics","description":"Aggregate numbers behind the status (rates 0–1). Counts and rates cover the last `window_s` seconds (600); a component with fewer than its minimum sample there uses the last hour instead, and its `metrics.window_s` (or `<tier>_window_s`) says which. `success_rate` is `null` only when even that window is short of the minimum; `requests`/`attempts` and `failures` are always given. Keys per component are listed in the API contract; new keys may be added.","examples":[{"batch_queue_backlog":412,"latency_p95_ms":8420,"requests":1873,"success_rate":0.9731,"sync_queue_backlog":0,"sync_queue_lag_s":0.0,"workers_alive":6}]},"updated_at":{"type":"string","title":"Updated At","description":"When the status was computed (ISO 8601, UTC)."},"incidents":{"items":{"$ref":"#/components/schemas/StatusIncident"},"type":"array","title":"Incidents","description":"Incidents naming this component."},"maintenance":{"items":{"$ref":"#/components/schemas/StatusMaintenance"},"type":"array","title":"Maintenance","description":"Maintenance naming this component, or the whole service."}},"type":"object","required":["id","name","description","status","reasons","metrics","updated_at","incidents","maintenance"],"title":"StatusComponentDetail","description":"One component with the notes that concern it."},"StatusHistory":{"properties":{"hours":{"type":"integer","title":"Hours","description":"Period covered, in hours.","examples":[24]},"bucket_s":{"type":"integer","title":"Bucket S","description":"Bucket size in seconds (300 or 3600).","examples":[300]},"start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start","description":"Start of the first bucket (ISO 8601, UTC).","examples":["2026-10-18T09:45:00Z"]},"components":{"additionalProperties":{"$ref":"#/components/schemas/StatusSeries"},"type":"object","title":"Components","description":"Per component id, plus `_overall` for the overall status."}},"type":"object","required":["hours","bucket_s","start","components"],"title":"StatusHistory","description":"Status history per component."},"StatusIncident":{"properties":{"id":{"type":"string","title":"Id","description":"Incident id.","examples":["inc_3f9a1c0b7e"]},"title":{"type":"string","title":"Title","description":"Short title.","examples":["Elevated fetch failures"]},"status":{"type":"string","enum":["investigating","identified","monitoring","resolved"],"title":"Status","description":"Incident status."},"impact":{"type":"string","enum":["none","degraded","partial_outage","major_outage"],"title":"Impact","description":"Impact while unresolved: the named components show at least this status."},"components":{"items":{"type":"string"},"type":"array","title":"Components","description":"Affected component ids.","examples":[["fetch"]]},"created_at":{"type":"string","title":"Created At","description":"Opened (ISO 8601, UTC)."},"updated_at":{"type":"string","title":"Updated At","description":"Last update (ISO 8601, UTC)."},"resolved_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolved At","description":"Resolved (ISO 8601, UTC), or `null`."},"updates":{"items":{"$ref":"#/components/schemas/StatusUpdate"},"type":"array","title":"Updates","description":"Timeline, newest first."}},"type":"object","required":["id","title","status","impact","components","created_at","updated_at","resolved_at","updates"],"title":"StatusIncident","description":"An incident posted by the operator."},"StatusMaintenance":{"properties":{"id":{"type":"string","title":"Id","description":"Maintenance id.","examples":["mnt_8c2d4e1f0a"]},"title":{"type":"string","title":"Title","description":"Short title.","examples":["Database upgrade"]},"status":{"type":"string","enum":["scheduled","in_progress","completed"],"title":"Status","description":"`scheduled` before `starts_at`, `in_progress` until `ends_at` (or until completed early), then `completed`."},"components":{"items":{"type":"string"},"type":"array","title":"Components","description":"Affected component ids (empty: the whole service)."},"starts_at":{"type":"string","title":"Starts At","description":"Planned start (ISO 8601, UTC)."},"ends_at":{"type":"string","title":"Ends At","description":"Planned end (ISO 8601, UTC)."},"created_at":{"type":"string","title":"Created At","description":"Announced (ISO 8601, UTC)."},"updated_at":{"type":"string","title":"Updated At","description":"Last update (ISO 8601, UTC)."},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At","description":"Completed (ISO 8601, UTC), or `null`."},"updates":{"items":{"$ref":"#/components/schemas/StatusUpdate"},"type":"array","title":"Updates","description":"Timeline, newest first."}},"type":"object","required":["id","title","status","components","starts_at","ends_at","created_at","updated_at","completed_at","updates"],"title":"StatusMaintenance","description":"A maintenance window posted by the operator."},"StatusSeries":{"properties":{"uptime":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Uptime","description":"Uptime over the period, 0–1 (`partial_outage` buckets count 30 % downtime, `major_outage` 100 %); `null` without data.","examples":[0.99965]},"statuses":{"items":{"anyOf":[{"type":"string","enum":["operational","maintenance","degraded","partial_outage","major_outage"]},{"type":"null"}]},"type":"array","title":"Statuses","description":"Worst status per bucket, oldest first; `null` where nothing was recorded.","examples":[["operational","operational","degraded","operational"]]}},"type":"object","required":["uptime","statuses"],"title":"StatusSeries","description":"History of one component."},"StatusSummary":{"properties":{"status":{"type":"string","enum":["operational","maintenance","degraded","partial_outage","major_outage"],"title":"Status","description":"Overall status.","examples":["operational"]},"description":{"type":"string","title":"Description","description":"Human-readable overall status.","examples":["All systems operational"]},"updated_at":{"type":"string","title":"Updated At","description":"When the status was computed (ISO 8601, UTC)."}},"type":"object","required":["status","description","updated_at"],"title":"StatusSummary","description":"Overall status only, for uptime monitors."},"StatusUpdate":{"properties":{"at":{"type":"string","title":"At","description":"When it was posted (ISO 8601, UTC)."},"status":{"type":"string","title":"Status","description":"Status set by this update.","examples":["monitoring"]},"message":{"type":"string","title":"Message","description":"What the operator said."}},"type":"object","required":["at","status","message"],"title":"StatusUpdate","description":"One entry of an incident's or maintenance's timeline."},"Usage":{"properties":{"project":{"type":"string","title":"Project","description":"Project of the API key.","examples":["chipiron-research"]},"key":{"type":"string","title":"Key","description":"Prefix of the calling key.","examples":["cmr_AbCdEf"]},"role":{"type":"string","enum":["account_admin","standard"],"title":"Role","description":"Role of the calling key.","examples":["standard"]},"scope":{"$ref":"#/components/schemas/UsageScope","description":"The customer, projects and keys the figures cover (after filters)."},"from":{"type":"string","title":"From","description":"First day (inclusive, UTC).","examples":["2026-10-01"]},"to":{"type":"string","title":"To","description":"Last day (inclusive, UTC).","examples":["2026-10-19"]},"as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"As Of","description":"The figures include every request recorded before this time (aggregates are refreshed every 5 minutes); `null` before the first refresh.","examples":["2026-10-19T11:05:02+00:00"]},"final":{"type":"boolean","title":"Final","description":"Every day of the range is closed: the figures will not change.","examples":[false]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"Currency of `charge` (the customer's invoice currency); `null` without a customer.","examples":["USD"]},"totals":{"$ref":"#/components/schemas/UsageMetrics","description":"Everything in the scope and filters."},"search":{"$ref":"#/components/schemas/UsageKind","description":"Search usage (compatibility block)."},"fetch":{"$ref":"#/components/schemas/UsageKind","description":"Fetch usage, sync and batch (compatibility block)."},"company":{"anyOf":[{"$ref":"#/components/schemas/UsageKind"},{"type":"null"}],"description":"Company data requests (`/v1/companies/*`, category and meter `company`); present when there are any."},"sec":{"$ref":"#/components/schemas/UsageKind","description":"SEC EDGAR usage: `/v1/sec/…` and fetches of SEC hosts (kind `sec`; categories `sec`, `sec_cached`). Empty when there was none."},"company_profile":{"$ref":"#/components/schemas/UsageKind","description":"Extended company profile usage (kind `company_profile`; categories `company_profile`, `company_profile_cached`). Empty when there was none."},"cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Usd","description":"Provider spend in USD — only for projects without an external customer.","examples":[0.37]},"budget":{"anyOf":[{"$ref":"#/components/schemas/Budget"},{"type":"null"}],"description":"The project's monthly provider budget — only for projects without an external customer."},"spend_budget":{"anyOf":[{"$ref":"#/components/schemas/SpendBudget"},{"type":"null"}],"description":"This month's spend against the spend caps, per key and per customer (`cap: null` when no cap is set)."},"group_by":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Group By","description":"The dimensions of `groups`.","examples":[["key","day"]]},"groups":{"anyOf":[{"items":{"$ref":"#/components/schemas/UsageGroup"},"type":"array"},{"type":"null"}],"title":"Groups","description":"One entry per combination of the `group_by` dimensions with usage, oldest first for time dimensions, then busiest first."},"keys":{"anyOf":[{"items":{"$ref":"#/components/schemas/UsageKey"},"type":"array"},{"type":"null"}],"title":"Keys","description":"With `group_by` containing `key`: per API key, busiest first (compatibility list; `groups` has the full metrics)."},"account":{"anyOf":[{"items":{"$ref":"#/components/schemas/UsageAccountPeriod"},"type":"array"},{"type":"null"}],"title":"Account","description":"Account admin keys of a customer: per billing period of the range, the account-level lines and totals."}},"type":"object","required":["project","key","role","scope","from","to","as_of","final","currency","totals","search","fetch","sec","company_profile"],"title":"Usage","description":"Answer of `GET /v1/usage`."},"UsageAccountPeriod":{"properties":{"period":{"type":"string","title":"Period","description":"`YYYY-MM`.","examples":["2026-10"]},"from":{"type":"string","title":"From","description":"First day rated.","examples":["2026-10-01"]},"to":{"type":"string","title":"To","description":"Last day rated (today while open).","examples":["2026-10-19"]},"currency":{"type":"string","title":"Currency","description":"Currency.","examples":["USD"]},"complimentary":{"type":"boolean","title":"Complimentary","description":"Complimentary account or plan (billed at list price, then discounted 100 %).","examples":[true]},"usage_charges":{"type":"string","title":"Usage Charges","description":"Sum of the usage lines: what the keys' `charge` add up to (for the whole period, all keys).","examples":["15.60"]},"account_level_amount":{"type":"string","title":"Account Level Amount","description":"Sum of `account_lines`.","examples":["-15.60"]},"account_lines":{"items":{"$ref":"#/components/schemas/AccountLine"},"type":"array","title":"Account Lines","description":"Base fee, minimum, discounts, credit."},"list_total":{"type":"string","title":"List Total","description":"Net before the complimentary credit (what the period is worth at list price).","examples":["15.60"]},"net_total":{"type":"string","title":"Net Total","description":"Net total before VAT.","examples":["0.00"]}},"type":"object","required":["period","from","to","currency","complimentary","usage_charges","account_level_amount","account_lines","list_total","net_total"],"title":"UsageAccountPeriod","description":"One billing period of the range at account level (account admin keys)."},"UsageBreakdown":{"properties":{"requests":{"type":"integer","title":"Requests","description":"Uncached requests.","examples":[840]},"succeeded":{"type":"integer","title":"Succeeded","description":"Successful requests.","examples":[838]},"premium_bytes":{"type":"integer","title":"Premium Bytes","description":"Bytes transferred through premium routes.","examples":[0]},"cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Usd","description":"Cormorant's provider spend in USD — only for projects without an external customer (internal use); customers see `charge` instead.","examples":[0.0]},"latency_ms_p50":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latency Ms P50","description":"Median latency (estimated, see the guide).","examples":[900]},"latency_ms_p95":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latency Ms P95","description":"95th percentile latency (estimated).","examples":[5100]},"queue_ms_p50":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Queue Ms P50","description":"Median queue time."},"queue_ms_p95":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Queue Ms P95","description":"95th percentile queue time."},"politeness_wait_ms_p50":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Politeness Wait Ms P50","description":"Median wait for polite per-domain slots."},"politeness_wait_ms_p95":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Politeness Wait Ms P95","description":"95th percentile wait for polite per-domain slots."},"upstream_ms_p50":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Upstream Ms P50","description":"Median time in tier attempts (site / provider)."},"upstream_ms_p95":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Upstream Ms P95","description":"95th percentile time in tier attempts."}},"type":"object","required":["requests","succeeded","premium_bytes"],"title":"UsageBreakdown","description":"Requests of one provider (search) or tier (fetch); cache hits excluded."},"UsageDomains":{"properties":{"project":{"type":"string","title":"Project","description":"Project of the API key.","examples":["acme-crawler"]},"key":{"type":"string","title":"Key","description":"Prefix of the calling key.","examples":["cmr_AbCdEf"]},"role":{"type":"string","enum":["account_admin","standard"],"title":"Role","description":"Role of the calling key.","examples":["standard"]},"scope":{"$ref":"#/components/schemas/UsageScope","description":"The customer, projects and keys covered."},"from":{"type":"string","title":"From","description":"First day.","examples":["2026-10-01"]},"to":{"type":"string","title":"To","description":"Last day.","examples":["2026-10-19"]},"domains":{"anyOf":[{"items":{"$ref":"#/components/schemas/DomainUsage"},"type":"array"},{"type":"null"}],"title":"Domains","description":"Without `group_by`: the busiest domains, busiest first."},"keys":{"anyOf":[{"items":{"$ref":"#/components/schemas/KeyDomains"},"type":"array"},{"type":"null"}],"title":"Keys","description":"With `group_by=key`: a top list per key, busiest key first."}},"type":"object","required":["project","key","role","scope","from","to"],"title":"UsageDomains","description":"Answer of `GET /v1/usage/domains`."},"UsageGroup":{"properties":{"requests":{"type":"integer","title":"Requests","description":"All requests (cache hits included).","examples":[9120]},"succeeded":{"type":"integer","title":"Succeeded","description":"Successful requests.","examples":[8800]},"failed":{"type":"integer","title":"Failed","description":"`requests - succeeded`.","examples":[320]},"success_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Success Rate","description":"`succeeded / requests`.","examples":[0.9649]},"cached":{"type":"integer","title":"Cached","description":"Served from the shared cache.","examples":[1200]},"cache_hit_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cache Hit Rate","description":"`cached / requests`.","examples":[0.1316]},"errors":{"additionalProperties":{"type":"integer"},"type":"object","title":"Errors","description":"Failures by error code (top 50), e.g. `http_404`, `all_tiers_failed`.","examples":[{"all_tiers_failed":110,"http_404":210}]},"latency_ms_p50":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latency Ms P50","description":"Median latency of uncached requests in ms, estimated from the latency histogram (exact to the bucket); `null` without uncached requests.","examples":[900]},"latency_ms_p95":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latency Ms P95","description":"95th percentile latency of uncached requests in ms (estimated).","examples":[7400]},"bytes":{"type":"integer","title":"Bytes","description":"Bytes retrieved.","examples":[812345678]},"premium_requests":{"type":"integer","title":"Premium Requests","description":"Fetches served by (or charged for) the premium routes.","examples":[90]},"premium_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Premium Share","description":"`premium_requests / uncached fetches`: how often the premium routes were needed.","examples":[0.0113]},"charge":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Charge","description":"Charges at the customer's plan price in `currency` (decimal string): the group's share of the usage lines of the estimate or invoice. Account-level lines (base fee, minimum, discounts, complimentary credit) are under `account`. Only for projects with a customer.","examples":["15.60"]},"billable":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/MeterUsage"},"type":"object"},{"type":"null"}],"title":"Billable","description":"Per price-plan meter (`search`, `fetch_own`, `fetch_premium`, `premium_gb`, …): quantity, included units used, billable quantity and amount. Only for projects with a customer."},"cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Usd","description":"Cormorant's provider spend in USD — only for projects without an external customer (internal use).","examples":[0.07]},"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key","description":"With `group_by=key`: key prefix (`cma_…` account admin, `cmr_…` standard); `null` for usage recorded before per-key attribution.","examples":["cmr_AbCdEf"]},"key_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key Label","description":"With `group_by=key`: the key's label.","examples":["crawler"]},"key_role":{"anyOf":[{"type":"string","enum":["account_admin","standard"]},{"type":"null"}],"title":"Key Role","description":"With `group_by=key`: the key's role.","examples":["standard"]},"key_status":{"anyOf":[{"type":"string","enum":["active","revoked"]},{"type":"null"}],"title":"Key Status","description":"With `group_by=key`: `revoked` keys stay in the history.","examples":["active"]},"project":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project","description":"With `group_by=project` (or `key`): project name.","examples":["acme-crawler"]},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"With `group_by=category`: billing category (`search`, `search_fallback`, `search_cached`, `fetch_own`, `fetch_premium`, `fetch_cached`, `company`, `company_cached`, `sec`, `sec_cached`, `company_profile`, `company_profile_cached`).","examples":["fetch_own"]},"day":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Day","description":"With `group_by=day`: UTC day.","examples":["2026-10-18"]},"hour":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hour","description":"With `group_by=hour`: start of the UTC hour.","examples":["2026-10-18T14:00:00+00:00"]},"final":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Final","description":"With `group_by=day` or `hour`: the day is closed and its figures will not change.","examples":[true]}},"type":"object","required":["requests","succeeded","failed","success_rate","cached","cache_hit_rate","errors","latency_ms_p50","latency_ms_p95","bytes","premium_requests","premium_share"],"title":"UsageGroup","description":"One group of `GET /v1/usage?group_by=…`: the dimension values, then the metrics."},"UsageKey":{"properties":{"prefix":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prefix","description":"First 10 characters of the key (`cma_…` account admin, `cmr_…` standard); `null` for requests recorded before per-key attribution.","examples":["cmr_AbCdEf"]},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label","description":"Label set by the operator.","examples":["crawler"]},"role":{"anyOf":[{"type":"string","enum":["account_admin","standard"]},{"type":"null"}],"title":"Role","description":"`account_admin` (prefix `cma_`) or `standard` (`cmr_`); `null` for requests recorded before per-key attribution.","examples":["standard"]},"project":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project","description":"Project of the key.","examples":["acme-crawler"]},"active":{"type":"boolean","title":"Active","description":"The key is not revoked.","examples":[true]},"requests":{"type":"integer","title":"Requests","description":"All requests.","examples":[900]},"cached":{"type":"integer","title":"Cached","description":"Cache hits.","examples":[120]},"succeeded":{"type":"integer","title":"Succeeded","description":"Successful requests.","examples":[890]},"search_requests":{"type":"integer","title":"Search Requests","description":"Searches.","examples":[300]},"fetch_requests":{"type":"integer","title":"Fetch Requests","description":"Fetches.","examples":[600]},"company_requests":{"type":"integer","title":"Company Requests","description":"Company data requests (`/v1/companies/*`).","examples":[0]},"sec_requests":{"type":"integer","title":"Sec Requests","description":"SEC EDGAR requests (`/v1/sec/…` and fetches of SEC hosts).","examples":[0]},"company_profile_requests":{"type":"integer","title":"Company Profile Requests","description":"Extended company profile requests (kind `company_profile`).","examples":[0]},"premium_bytes":{"type":"integer","title":"Premium Bytes","description":"Bytes through premium routes.","examples":[0]},"charge":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Charge","description":"Charges at the customer's plan price (decimal string, `currency`); only for projects with a customer.","examples":["1.80"]},"cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Usd","description":"Provider spend in USD — only for projects without an external customer.","examples":[0.12]}},"type":"object","required":["prefix","label","role","project","active","requests","cached","succeeded","search_requests","fetch_requests","company_requests","sec_requests","company_profile_requests","premium_bytes"],"title":"UsageKey","description":"Usage of one API key (`GET /v1/usage?group_by=key`, compatibility list)."},"UsageKind":{"properties":{"requests":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Requests","description":"All requests.","examples":[1200]},"cached":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cached","description":"Cache hits.","examples":[300]},"cache_hit_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cache Hit Rate","description":"`cached / requests`.","examples":[0.25]},"succeeded":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Succeeded","description":"Successful requests.","examples":[1198]},"success_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Success Rate","description":"`succeeded / requests`.","examples":[0.998]},"bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bytes","description":"Bytes retrieved.","examples":[812345678]},"premium_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Premium Bytes","description":"Bytes through premium routes.","examples":[9123456]},"latency_ms_p50":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latency Ms P50","description":"Median latency of uncached requests (estimated from a latency histogram, see the guide).","examples":[1100]},"latency_ms_p95":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latency Ms P95","description":"95th percentile latency of uncached requests (estimated).","examples":[3900]},"cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Usd","description":"Provider spend in USD — only for projects without an external customer (internal use).","examples":[0.3]},"fallbacks":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fallbacks","description":"Search only: requests answered by the fallback.","examples":[60]},"fallback_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fallback Rate","description":"Search only: `fallbacks / uncached requests`.","examples":[0.0667]},"providers":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/UsageBreakdown"},"type":"object"},{"type":"null"}],"title":"Providers","description":"Search only: breakdown by provider (`searxng`, `brave`)."},"tiers":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/UsageBreakdown"},"type":"object"},{"type":"null"}],"title":"Tiers","description":"Fetch only: breakdown by tier."},"latency_components":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/Percentiles"},"type":"object"},{"type":"null"}],"title":"Latency Components","description":"p50/p95 (ms, estimated) of the latency components of uncached requests: `queue_ms` (Cormorant's queues), `politeness_wait_ms` (polite per-domain slots), `upstream_ms` (the site or provider). Requests from before these were recorded are not included."},"by_outcome":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/UsageOutcome"},"propertyNames":{"enum":["succeeded","failed"]},"type":"object"},{"type":"null"}],"title":"By Outcome","description":"The same requests split by outcome: `succeeded` and `failed`, each with requests, bytes, premium bytes and (fetch) premium requests. Shows what failed fetches cost in premium bytes."},"errors":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"title":"Errors","description":"Error codes and their counts (top 50).","examples":[{"all_tiers_failed":25,"http_404":40}]}},"type":"object","title":"UsageKind","description":"Usage of one request kind (search or fetch) in the caller's scope. Empty\nobject when unused."},"UsageMetrics":{"properties":{"requests":{"type":"integer","title":"Requests","description":"All requests (cache hits included).","examples":[9120]},"succeeded":{"type":"integer","title":"Succeeded","description":"Successful requests.","examples":[8800]},"failed":{"type":"integer","title":"Failed","description":"`requests - succeeded`.","examples":[320]},"success_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Success Rate","description":"`succeeded / requests`.","examples":[0.9649]},"cached":{"type":"integer","title":"Cached","description":"Served from the shared cache.","examples":[1200]},"cache_hit_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cache Hit Rate","description":"`cached / requests`.","examples":[0.1316]},"errors":{"additionalProperties":{"type":"integer"},"type":"object","title":"Errors","description":"Failures by error code (top 50), e.g. `http_404`, `all_tiers_failed`.","examples":[{"all_tiers_failed":110,"http_404":210}]},"latency_ms_p50":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latency Ms P50","description":"Median latency of uncached requests in ms, estimated from the latency histogram (exact to the bucket); `null` without uncached requests.","examples":[900]},"latency_ms_p95":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latency Ms P95","description":"95th percentile latency of uncached requests in ms (estimated).","examples":[7400]},"bytes":{"type":"integer","title":"Bytes","description":"Bytes retrieved.","examples":[812345678]},"premium_requests":{"type":"integer","title":"Premium Requests","description":"Fetches served by (or charged for) the premium routes.","examples":[90]},"premium_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Premium Share","description":"`premium_requests / uncached fetches`: how often the premium routes were needed.","examples":[0.0113]},"charge":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Charge","description":"Charges at the customer's plan price in `currency` (decimal string): the group's share of the usage lines of the estimate or invoice. Account-level lines (base fee, minimum, discounts, complimentary credit) are under `account`. Only for projects with a customer.","examples":["15.60"]},"billable":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/MeterUsage"},"type":"object"},{"type":"null"}],"title":"Billable","description":"Per price-plan meter (`search`, `fetch_own`, `fetch_premium`, `premium_gb`, …): quantity, included units used, billable quantity and amount. Only for projects with a customer."},"cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Usd","description":"Cormorant's provider spend in USD — only for projects without an external customer (internal use).","examples":[0.07]}},"type":"object","required":["requests","succeeded","failed","success_rate","cached","cache_hit_rate","errors","latency_ms_p50","latency_ms_p95","bytes","premium_requests","premium_share"],"title":"UsageMetrics","description":"Metrics of a group (or of the totals)."},"UsageOutcome":{"properties":{"requests":{"type":"integer","title":"Requests","description":"Requests.","examples":[1198]},"bytes":{"type":"integer","title":"Bytes","description":"Bytes retrieved.","examples":[812000000]},"premium_bytes":{"type":"integer","title":"Premium Bytes","description":"Bytes billed by the premium routes (residential proxy) for these requests. On `failed`: what blocked pages cost before the fetch gave up.","examples":[9000000]},"premium_requests":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Premium Requests","description":"Fetch only: requests that used a premium route (billing category `fetch_premium`).","examples":[40]},"cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Usd","description":"Provider spend in USD — only for projects without an external customer (internal use).","examples":[0.07]}},"type":"object","required":["requests","bytes","premium_bytes"],"title":"UsageOutcome","description":"Requests of one kind that ended with this outcome (cache hits included)."},"UsagePoint":{"properties":{"requests":{"type":"integer","title":"Requests","description":"All requests (cache hits included).","examples":[9120]},"succeeded":{"type":"integer","title":"Succeeded","description":"Successful requests.","examples":[8800]},"failed":{"type":"integer","title":"Failed","description":"`requests - succeeded`.","examples":[320]},"success_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Success Rate","description":"`succeeded / requests`.","examples":[0.9649]},"cached":{"type":"integer","title":"Cached","description":"Served from the shared cache.","examples":[1200]},"cache_hit_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cache Hit Rate","description":"`cached / requests`.","examples":[0.1316]},"errors":{"additionalProperties":{"type":"integer"},"type":"object","title":"Errors","description":"Failures by error code (top 50), e.g. `http_404`, `all_tiers_failed`.","examples":[{"all_tiers_failed":110,"http_404":210}]},"latency_ms_p50":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latency Ms P50","description":"Median latency of uncached requests in ms, estimated from the latency histogram (exact to the bucket); `null` without uncached requests.","examples":[900]},"latency_ms_p95":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latency Ms P95","description":"95th percentile latency of uncached requests in ms (estimated).","examples":[7400]},"bytes":{"type":"integer","title":"Bytes","description":"Bytes retrieved.","examples":[812345678]},"premium_requests":{"type":"integer","title":"Premium Requests","description":"Fetches served by (or charged for) the premium routes.","examples":[90]},"premium_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Premium Share","description":"`premium_requests / uncached fetches`: how often the premium routes were needed.","examples":[0.0113]},"charge":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Charge","description":"Charges at the customer's plan price in `currency` (decimal string): the group's share of the usage lines of the estimate or invoice. Account-level lines (base fee, minimum, discounts, complimentary credit) are under `account`. Only for projects with a customer.","examples":["15.60"]},"billable":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/MeterUsage"},"type":"object"},{"type":"null"}],"title":"Billable","description":"Per price-plan meter (`search`, `fetch_own`, `fetch_premium`, `premium_gb`, …): quantity, included units used, billable quantity and amount. Only for projects with a customer."},"cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Usd","description":"Cormorant's provider spend in USD — only for projects without an external customer (internal use).","examples":[0.07]},"t":{"type":"string","title":"T","description":"Start of the hour or day (UTC).","examples":["2026-10-18T14:00:00+00:00"]},"final":{"type":"boolean","title":"Final","description":"The bucket's day is closed.","examples":[true]}},"type":"object","required":["requests","succeeded","failed","success_rate","cached","cache_hit_rate","errors","latency_ms_p50","latency_ms_p95","bytes","premium_requests","premium_share","t","final"],"title":"UsagePoint","description":"One bucket of a time series: its start, whether it is final, the metrics."},"UsageScope":{"properties":{"customer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer","description":"Customer name; `null` for projects without a customer.","examples":["Acme"]},"projects":{"items":{"type":"string"},"type":"array","title":"Projects","description":"Projects covered.","examples":[["acme-crawler"]]},"keys":{"type":"string","enum":["self","all"],"title":"Keys","description":"`self`: only the calling key (standard keys); `all`: every key of the account, revoked keys and unattributed usage included (account admin keys).","examples":["self"]}},"type":"object","required":["customer","projects","keys"],"title":"UsageScope","description":"What the figures cover."},"UsageSeries":{"properties":{"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key","description":"With `group_by=key`: key prefix.","examples":["cmr_AbCdEf"]},"key_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key Label","description":"With `group_by=key`: label.","examples":["crawler"]},"key_role":{"anyOf":[{"type":"string","enum":["account_admin","standard"]},{"type":"null"}],"title":"Key Role","description":"With `group_by=key`: role.","examples":["standard"]},"key_status":{"anyOf":[{"type":"string","enum":["active","revoked"]},{"type":"null"}],"title":"Key Status","description":"With `group_by=key`: status.","examples":["active"]},"project":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project","description":"With `group_by=project` or `key`.","examples":["acme-crawler"]},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"With `group_by=category`.","examples":["fetch_own"]},"points":{"items":{"$ref":"#/components/schemas/UsagePoint"},"type":"array","title":"Points","description":"Every bucket of the range up to now, oldest first; zero where unused."}},"type":"object","required":["points"],"title":"UsageSeries","description":"One series: the `group_by` values, then one point per bucket."},"UsageTimeseries":{"properties":{"project":{"type":"string","title":"Project","description":"Project of the API key.","examples":["acme-crawler"]},"key":{"type":"string","title":"Key","description":"Prefix of the calling key.","examples":["cmr_AbCdEf"]},"role":{"type":"string","enum":["account_admin","standard"],"title":"Role","description":"Role of the calling key.","examples":["standard"]},"scope":{"$ref":"#/components/schemas/UsageScope","description":"The customer, projects and keys covered."},"from":{"type":"string","title":"From","description":"First day.","examples":["2026-10-19"]},"to":{"type":"string","title":"To","description":"Last day.","examples":["2026-10-19"]},"granularity":{"type":"string","enum":["hour","day"],"title":"Granularity","description":"Bucket size.","examples":["hour"]},"as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"As Of","description":"Every request recorded before this time is included.","examples":["2026-10-19T11:05:02+00:00"]},"final":{"type":"boolean","title":"Final","description":"Every bucket is closed.","examples":[false]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"Currency of `charge`.","examples":["USD"]},"group_by":{"items":{"type":"string"},"type":"array","title":"Group By","description":"Dimensions of the series.","examples":[["key"]]},"series":{"items":{"$ref":"#/components/schemas/UsageSeries"},"type":"array","title":"Series","description":"One series per `group_by` value."}},"type":"object","required":["project","key","role","scope","from","to","granularity","as_of","final","currency","group_by","series"],"title":"UsageTimeseries","description":"Answer of `GET /v1/usage/timeseries`."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location","description":"Where the problem is, e.g. `[\"body\", \"max_results\"]`."},"msg":{"type":"string","title":"Message","description":"Human-readable message."},"type":{"type":"string","title":"Error Type","description":"Error type, e.g. `less_than_equal`."},"input":{"title":"Input","description":"The rejected value."},"ctx":{"type":"object","title":"Context","description":"Extra context, e.g. the limit that was exceeded."}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WatchBody":{"properties":{"companies":{"items":{"type":"string"},"type":"array","maxItems":1000,"minItems":1,"title":"Companies","description":"`cmp_…` ids or `scheme:value` identifiers."},"url":{"type":"string","maxLength":2000,"title":"Url","description":"HTTPS endpoint receiving `company.changed` POSTs."}},"type":"object","required":["companies","url"],"title":"WatchBody","description":"A webhook for changes of some companies.","examples":[{"companies":["lei:BFM8T61CT2L1QCEMIK50"],"url":"https://example.org/hooks/companies"}]},"Web":{"properties":{"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website","description":"Main website."},"domains":{"items":{"type":"string"},"type":"array","title":"Domains","description":"Domains of the company."}},"additionalProperties":false,"type":"object","title":"Web","description":"Web presence (official sources or verified)."},"app__api__models__Status":{"properties":{"status":{"type":"string","enum":["operational","maintenance","degraded","partial_outage","major_outage"],"title":"Status","description":"Overall status: the worst component status, where a major outage of a non-core component (anything but api, search, fetch, storage) counts as a partial outage; `maintenance` when the only components not operational are under maintenance.","examples":["operational"]},"description":{"type":"string","title":"Description","description":"Human-readable overall status.","examples":["All systems operational"]},"updated_at":{"type":"string","title":"Updated At","description":"When this snapshot was computed (ISO 8601, UTC; at most ~15 s old).","examples":["2026-10-19T09:41:15+00:00"]},"window_s":{"type":"integer","title":"Window S","description":"Window of the recent-request metrics, in seconds.","examples":[600]},"components":{"items":{"$ref":"#/components/schemas/StatusComponent"},"type":"array","title":"Components","description":"Every component, in display order."},"incidents":{"items":{"$ref":"#/components/schemas/StatusIncident"},"type":"array","title":"Incidents","description":"Unresolved incidents and those resolved within 7 days, newest first."},"maintenance":{"items":{"$ref":"#/components/schemas/StatusMaintenance"},"type":"array","title":"Maintenance","description":"Scheduled and in-progress maintenance, and windows completed within 7 days, soonest first."}},"type":"object","required":["status","description","updated_at","window_s","components","incidents","maintenance"],"title":"Status","description":"Service status for monitoring (no authentication)."},"app__companies__model__Identifier":{"properties":{"scheme":{"type":"string","title":"Scheme","description":"Identifier scheme (`ch_uid`, `lei`, `us_cik`, …).","examples":["lei"]},"value":{"type":"string","title":"Value","description":"Canonical value.","examples":["HWUPKR0MPOU8FGXBT394"]},"issuer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Issuer","description":"Body that issues identifiers of this scheme."},"status":{"type":"string","title":"Status","description":"`active` or `inactive` (retired, lapsed).","default":"active"},"parts":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Parts","description":"Structured parts (`de_register`: court, type, number; `ticker`: mic, symbol)."},"sources":{"items":{"type":"string"},"type":"array","title":"Sources","description":"Sources that reported it."}},"additionalProperties":false,"type":"object","required":["scheme","value"],"title":"Identifier","description":"An identifier of the company in some scheme (canonical form)."},"app__companies__model__Status":{"properties":{"value":{"type":"string","enum":["active","inactive","in_liquidation","dissolved","merged","struck_off","unknown"],"title":"Value","description":"Normalised status.","examples":["active"]},"local_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Local Value","description":"Status as the source words it."},"since":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since","description":"Date the status took effect."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Reason, e.g. merger or bankruptcy."}},"additionalProperties":false,"type":"object","required":["value"],"title":"Status","description":"Register status."}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"cmr_… or cma_…","description":"Project API key: `Authorization: Bearer cmr_…` (standard key) or `cma_…` (account admin key, sees the whole customer account where an endpoint offers it). Keys are issued and revoked by the operator; each belongs to exactly one project, and its role never changes. Authenticated responses carry `X-Cormorant-Key-Role: account_admin|standard`."}}},"tags":[{"name":"search","description":"Web search: shared cache → Cormorant's SearXNG instances → Brave Search API fallback. Results are merged and deduplicated; no snippet is lost.","x-displayName":"Search"},{"name":"fetch","description":"Fetch one URL with tier escalation (direct → browser → archive → proxy → proxy_render), extraction of the main text, provenance and the exact retrieved bytes.","x-displayName":"Fetch"},{"name":"batch","description":"Asynchronous jobs of up to 50,000 searches or fetches: create with an idempotency key, poll or receive a callback, page through item results. Jobs are kept 30 days after they finish.","x-displayName":"Batch jobs"},{"name":"bodies","description":"The exact bytes behind a fetch result (`body_url`), content-addressed by SHA-256 and visible only to projects that retrieved them.","x-displayName":"Exact bytes"},{"name":"sec","description":"Company and filing data from SEC EDGAR (www.sec.gov, data.sec.gov, efts.sec.gov) under SEC's fair-access policy: Cormorant's own declared identity, one shared rate limit and backoff, cached. Do not send your own User-Agent.","x-displayName":"SEC EDGAR"},{"name":"usage","description":"Usage, charges at the plan price and statistics per key, project, category and day, from aggregates refreshed every 5 minutes (JSON or CSV), and the API keys visible to the caller. Standard keys (`cmr_…`) see only themselves; account admin keys (`cma_…`) the whole customer account.","x-displayName":"Usage & keys"},{"name":"account","description":"The key's project usage plus the plan, current-period estimate and issued invoices of the customer that owns the project. Money is a decimal string in the invoice currency.","x-displayName":"Account & invoices"},{"name":"companies","description":"The company register (`company/v1`): records with field-level provenance from official registers, GLEIF and other sources, refreshed on request per source freshness class; search, entity resolution, history, sub-resources, batch jobs, a change feed and signed webhooks. Metered as `company`.","x-displayName":"Company data"},{"name":"status","description":"Public service status for your monitoring: overall and per-component status with aggregate metrics, incidents, maintenance and a 7-day history. No authentication; always `200` with the status in the body. Human-readable page: [/status](/status).","x-displayName":"Service status"},{"name":"health","description":"Liveness and readiness probes. No authentication.","x-displayName":"Health"}],"externalDocs":{"description":"Guides and examples","url":"https://api.cormorant.ch/docs"}}