{"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 paid Brave fallback) and\nfetches pages, PDFs and other documents through a ladder of tiers — plain HTTP with\na browser fingerprint, a real browser, an archived copy and, only when a site blocks\nthe free tiers, paid residential proxies. Results are cached and shared, and every\nresponse says what it cost.\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\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 (free). Otherwise\nthe tier ladder runs: `direct` (HTTP with a Chrome fingerprint) →\n`browser` (Chromium) → `archive` (Wayback Machine) → `proxy` →\n`proxy_render` (paid). It escalates only on blocking (403/429/451/5xx, bot\nchallenges, network errors); thin text escalates `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_paid`, `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"}}}},"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 free tiers is retried once after a\ncool-down before a paid tier 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` or `name`. A name can match several companies: then\n`ambiguous` is `true`, the company fields are `null` and `candidates`\nlists the matches. A CIK without a listed ticker is resolved from its\nsubmissions. Unknown: `error: not_found`.","operationId":"secResolveCompany","parameters":[{"name":"ticker","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Ticker, e.g. `TSN` (`BRK.B` = `BRK-B`).","title":"Ticker"},"description":"Ticker, e.g. `TSN` (`BRK.B` = `BRK-B`)."},{"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":"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/northdata/suggest":{"post":{"tags":["northdata"],"summary":"North Data autocomplete","description":"Calls `GET https://www.northdata.com/suggest.json?query=…&countries=CC` and returns\nthe company items only (`{name, url, type}`, absolute URLs); persons are dropped.\nThe raw answer is downloadable via `fetch.body_url`. Cached for 24 h.\n\nNorth Data is fetched only through Massive (residential proxy with a sticky session per `session_key`, then Web Render when blocked), never from Cormorant's own addresses, under a cluster-wide throttle (2 in flight, 1 s between starts by default). Upstream failures are HTTP 200 with `error`.","operationId":"northdataSuggest","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NorthdataSuggestBody"}}},"required":true},"responses":{"200":{"description":"Company items; HTTP 200 also on failure: check `error`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NorthdataSuggestResponse"}}}},"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/northdata/discover":{"post":{"tags":["northdata"],"summary":"Find a company's North Data profile URL","description":"Suggest first: the company item with the highest name similarity wins if it\nreaches `min_similarity` (default 70; `score` = similarity / 100). Otherwise (or\nwhen suggest fails) Cormorant's own web search with up to four queries; profile\nURLs are scored 0..1, the search stops at ≥ 0.75 and rejects < 0.35. No match:\n`error: not_found`.\n\nNorth Data is fetched only through Massive (residential proxy with a sticky session per `session_key`, then Web Render when blocked), never from Cormorant's own addresses, under a cluster-wide throttle (2 in flight, 1 s between starts by default). Upstream failures are HTTP 200 with `error`.","operationId":"northdataDiscover","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NorthdataDiscoverBody"}}},"required":true},"responses":{"200":{"description":"The profile URL with scores; HTTP 200 also on failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NorthdataDiscoverResponse"}}}},"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/northdata/profile":{"post":{"tags":["northdata"],"summary":"A parsed North Data company profile","description":"Fetches the profile page (by `url`, or discovered from `company_name` +\n`country` + `headquarters`), parses it (parser version 3, HTML or Web Render\nMarkdown) and, with `include_graph`, fetches the network graph and merges it.\n`fetch` has the provenance (`body_url` and `sha256` of the exact page bytes).\nProfile pages are served from the cache for 24 h, then revalidated.\n\nNorth Data is fetched only through Massive (residential proxy with a sticky session per `session_key`, then Web Render when blocked), never from Cormorant's own addresses, under a cluster-wide throttle (2 in flight, 1 s between starts by default). Upstream failures are HTTP 200 with `error`.","operationId":"northdataProfile","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NorthdataProfileBody"}}},"required":true},"responses":{"200":{"description":"The profile and its provenance; HTTP 200 also on failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NorthdataProfileResponse"}}}},"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/northdata/graph":{"post":{"tags":["northdata"],"summary":"North Data network graph","description":"Calls `POST https://www.northdata.com/data.json` with\n    `{\"options\":[{\"domain\":\"company\",\"id\":\"<entity_id>\",\"type\":\"graph\"}]}` and returns\nthe nodes split into companies, persons and others. Raw answer via\n`fetch.body_url`; cached for 24 h.\n\nNorth Data is fetched only through Massive (residential proxy with a sticky session per `session_key`, then Web Render when blocked), never from Cormorant's own addresses, under a cluster-wide throttle (2 in flight, 1 s between starts by default). Upstream failures are HTTP 200 with `error`.","operationId":"northdataGraph","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NorthdataGraphBody"}}},"required":true},"responses":{"200":{"description":"Graph nodes by type; HTTP 200 also on failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NorthdataGraphResponse"}}}},"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/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 paid\n(premium) 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_paid`, `fetch_cached`, `company`, `company_cached`, `sec`, `sec_cached`.","title":"Category"},"description":"Only these billing categories (comma-separated): `search`, `search_fallback`, `search_cached`, `fetch_own`, `fetch_paid`, `fetch_cached`, `company`, `company_cached`, `sec`, `sec_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, paid 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_paid`, `fetch_cached`, `company`, `company_cached`, `sec`, `sec_cached`.","title":"Category"},"description":"Only these billing categories (comma-separated): `search`, `search_fallback`, `search_cached`, `fetch_own`, `fetch_paid`, `fetch_cached`, `company`, `company_cached`, `sec`, `sec_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, paid (premium) fetches and paid 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_paid`, `fetch_cached`, `company`, `company_cached`, `sec`, `sec_cached`.","title":"Category"},"description":"Only these billing categories (comma-separated): `search`, `search_fallback`, `search_cached`, `fetch_own`, `fetch_paid`, `fetch_cached`, `company`, `company_cached`, `sec`, `sec_cached`."},{"name":"kind","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(search|fetch|sec)$"},{"type":"null"}],"description":"`search`, `fetch` or `sec` (SEC EDGAR).","title":"Kind"},"description":"`search`, `fetch` or `sec` (SEC EDGAR)."},{"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`.","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":{"type":"boolean","description":"Also search the live sources (first page).","default":true,"title":"Live"},"description":"Also search the live sources (first page)."}],"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.","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":"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,identifiers` (identifiers separated by `;`).","content":{"text/csv":{"schema":{"type":"string"},"example":"ref,name,country,city,identifiers\nlei:BFM8T61CT2L1QCEMIK50,,,,\n,Nestlé,CH,Vevey,\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;\n`refresh` says what was refreshed, fresh or failed (a failing source never\nfails 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`.","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`."},{"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`.","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`."},{"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`.","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`."},{"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"]},"free":{"type":"boolean","title":"Free","description":"Free accounts are rated at list price and then discounted 100 %.","examples":[true]}},"type":"object","required":["name","company_name","currency","status","free"],"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 free 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 `free`.","examples":["free"]},"description":{"type":"string","title":"Description","description":"Line text.","examples":["Free 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`, `archive_not_found`, `massive_captcha_rejected`, `massive_no_credits`, `massive_render_503`, `paywall`, `paywall_skip_paid`, `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]},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail","description":"Present only when set: for `proxy_render`, the Web Render 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`)."}},"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"}]}]},"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 paid 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 paid 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","enum":["search","fetch"],"title":"Kind","description":"Kind of items.","examples":["fetch"]},"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]},"paid_bytes":{"type":"integer","title":"Paid Bytes","description":"Bytes through paid tiers.","examples":[0]},"paid_bytes_ok":{"type":"integer","title":"Paid Bytes Ok","description":"Bytes through paid tiers, 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","paid_bytes","paid_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_paid`, `fetch_cached`, `sec`, `sec_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}`."},"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)."}},"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."}},"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/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."}},"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/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"],"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).","examples":["fresh"]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error class when `failed` (`http_503`, `timeout`, …)."},"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`."},"candidates":{"items":{"$ref":"#/components/schemas/CompanySummary"},"type":"array","title":"Candidates","description":"Ranked candidates."}},"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`)."}},"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]},"paid_requests":{"type":"integer","title":"Paid Requests","description":"Fetches served by the paid tiers.","examples":[40]},"paid_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Paid Share","description":"`paid_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","paid_requests","paid_share"],"title":"DomainUsage","description":"Fetches of one domain."},"EntityRef":{"properties":{"name":{"type":"string","title":"Name","description":"Name as shown on North Data."},"relation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Relation","description":"Section it came from: `subsidiaries`, `parent_companies`, `shareholders` or `related` (network graph). Never invented."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Link as on the page (usually relative, e.g. `/Foo%20AG`)."},"absolute_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Absolute Url","description":"The same link as an absolute https://www.northdata.com URL."}},"type":"object","required":["name"],"title":"EntityRef","description":"A company or person named on the profile (or in the network graph)."},"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"]},"free":{"type":"boolean","title":"Free","description":"Free account or plan.","examples":[true]},"list_total":{"type":"string","title":"List Total","description":"Net before the free 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","free","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 `free`.","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 paid tiers).","default":500,"examples":[500]},"project_ref":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Project Ref","description":"Free 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_paid":{"type":"boolean","title":"Allow Paid","description":"`false`: never use the paid tiers (`proxy`, `proxy_render`).","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 paid tiers (ISO 3166-1 alpha-2).","examples":["CH"]},"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 tier ladder (direct → browser → archive →\npaid proxy → paid render), escalating only when blocked.","examples":[{"url":"https://www.example.com/annual-report-2025.pdf"},{"allow_paid":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 (Web 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 Web 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."},"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 (Brave, Massive; cache hits and own tiers cost 0). `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_paid`, `fetch_cached`, `company`, `company_cached`, `sec`, `sec_cached`): it maps the request to the meters and charges of your plan.","examples":["fetch_own"]},"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":[[]]},"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`; for SEC EDGAR URLs also `sec_not_configured`, `rate_limited`, `sec_unavailable`, `redirect_not_allowed`.","examples":[null]},"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. 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"]}},"type":"object","required":["url","final_url","redirects","status","content_type","origin_content_type","headers","tier","attempts","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","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":[{"attempts":[{"ms":412,"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"}],"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"}]},"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."},"HistoryEvent":{"properties":{"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Event category (`cat`)."},"date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date","description":"Event date as given."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Short description (`desc`)."},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text","description":"Event text."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Linked document, if any."}},"type":"object","title":"HistoryEvent","description":"One event of the register history (`figure[data-data]`)."},"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)."},"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)"]},"free":{"type":"boolean","title":"Free","description":"Free invoice (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","free","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)"]},"free":{"type":"boolean","title":"Free","description":"Free invoice (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","free","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","enum":["search","fetch"],"title":"Kind","description":"Kind of items.","examples":["fetch"]},"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_paid`, `company`).","examples":[{"fetch":100000,"fetch_paid":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_paid`, `company`); `null` = all. Without `fetch_paid`, fetches run without the paid tiers.","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"],"title":"Kind","description":"Request kind.","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]},"paid":{"type":"boolean","title":"Paid","description":"Served by (or charged for) a paid tier.","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","paid","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"],"title":"Kind","description":"Request kind.","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]},"paid":{"type":"boolean","title":"Paid","description":"Served by (or charged for) a paid tier.","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","paid","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.","examples":[null]}},"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)."}},"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.","examples":["Nestlé S.A."]},"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)."}},"additionalProperties":false,"type":"object","title":"Names","description":"Legal name and other names."},"NetworkGraph":{"properties":{"company_connections":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Company Connections","description":"Company nodes (type `c`) as North Data returns them."},"person_connections":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Person Connections","description":"Person nodes (type `p`)."},"other_connections":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Other Connections","description":"Nodes of any other type."}},"type":"object","title":"NetworkGraph","description":"Nodes of North Data's network graph (`POST /data.json`), by type."},"NorthdataCandidate":{"properties":{"url":{"type":"string","title":"Url","description":"Profile URL."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Company name (suggest) or the URL's name part."},"score":{"type":"number","title":"Score","description":"Suggest candidates: name similarity 0..100 (as in Chipiron); search candidates: URL score 0..1."},"query":{"type":"string","title":"Query","description":"Query that produced it."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Suggest name or search result title."}},"type":"object","required":["url","name","score","query","title"],"title":"NorthdataCandidate","description":"A profile URL considered during discovery."},"NorthdataDiscoverBody":{"properties":{"session_key":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Session Key","description":"Sticky residential session (e.g. the ISIN): suggest, profile and graph requests with the same key share one Massive exit for 15 minutes. Letters, digits and `_ @ . -`; other characters become `_` (at most 64).","examples":["CH0012005267"]},"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]},"allow_paid":{"type":"boolean","title":"Allow Paid","description":"North Data is fetched only through Massive (paid). `false` answers `error: paid_tier_required` at once.","default":true,"examples":[true]},"project_ref":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Project Ref","description":"Free text stored with your usage (e.g. the entity this request is for).","examples":["isin:CH0012005267"]},"company_name":{"type":"string","maxLength":300,"minLength":1,"title":"Company Name","description":"Company name.","examples":["Novartis Pharma AG"]},"headquarters":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Headquarters","description":"Headquarters; the part before the first comma is used as the city.","examples":["Basel, Switzerland"]},"country":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Country","description":"Country of the company or research market: ISO 3166-1 alpha-2 (`CH`) or an English or German country name (`Switzerland`). Filters suggest results (`countries=`) and geotargets the Massive exit. Unknown names are ignored, never truncated.","examples":["CH"]},"min_similarity":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Min Similarity","description":"Minimum name similarity (0–100) for a suggest match.","default":70.0,"examples":[70]},"search_fallback":{"type":"boolean","title":"Search Fallback","description":"Fall back to Cormorant's web search when suggest finds no match.","default":true,"examples":[true]}},"type":"object","required":["company_name"],"title":"NorthdataDiscoverBody","description":"Find a company's North Data profile URL (suggest, then search).","examples":[{"company_name":"Novartis Pharma AG","country":"CH","headquarters":"Basel, Switzerland","session_key":"CH0012005267"}]},"NorthdataDiscoverResponse":{"properties":{"op":{"type":"string","enum":["suggest","discover","profile","graph"],"title":"Op","description":"The operation (`suggest`, `discover`, `profile`, `graph`)."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"The chosen profile URL (null: not found)."},"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query","description":"Query that found it."},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score","description":"Discovery score 0..1."},"name_similarity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Name Similarity","description":"Name similarity 0..100 (suggest only)."},"discovery_method":{"anyOf":[{"type":"string","enum":["suggest","search"]},{"type":"null"}],"title":"Discovery Method","description":"`suggest` or `search`."},"candidates":{"items":{"$ref":"#/components/schemas/NorthdataCandidate"},"type":"array","title":"Candidates","description":"Up to 10, best first."},"suggest_fetch":{"anyOf":[{"$ref":"#/components/schemas/NorthdataFetch"},{"type":"null"}],"description":"Provenance of the suggest.json request."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"`null` on success, else: `not_found`, `blocked`, `rate_limited` (with `retry_after_s`), `all_tiers_failed`, `parse_failed`, `invalid_identifier`, `paid_tier_required`, `budget_exhausted`, `robots_disallowed`, `timeout`, `politeness_timeout`. Upstream failures never produce an HTTP 5xx.","examples":[null]},"retry_after_s":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Retry After S","description":"Seconds after which a retry makes sense (`rate_limited`, `blocked` while the site is skipped), else null.","examples":[null]},"cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Usd","description":"Provider spend of the whole operation in USD (Massive, Brave for the search fallback); null for keys of an external customer.","examples":[0.00031]},"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"]}},"type":"object","required":["op","url","query","score","name_similarity","discovery_method","candidates","suggest_fetch","error","retry_after_s","cost_usd","request_id"],"title":"NorthdataDiscoverResponse"},"NorthdataDiscovery":{"properties":{"url":{"type":"string","title":"Url","description":"The chosen profile URL."},"query":{"type":"string","title":"Query","description":"Query that found it."},"score":{"type":"number","title":"Score","description":"Discovery score 0..1."},"name_similarity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Name Similarity","description":"Name similarity 0..100 (suggest), null for search."},"discovery_method":{"type":"string","enum":["suggest","search"],"title":"Discovery Method","description":"`suggest` or `search`."},"candidates":{"items":{"$ref":"#/components/schemas/NorthdataCandidate"},"type":"array","title":"Candidates","description":"Up to 10, best first."}},"type":"object","required":["url","query","score","name_similarity","discovery_method","candidates"],"title":"NorthdataDiscovery","description":"How the profile URL was found."},"NorthdataFetch":{"properties":{"url":{"type":"string","title":"Url","description":"Requested URL."},"final_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final Url","description":"URL after redirects (null when unknown)."},"status":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status","description":"Last HTTP status seen.","examples":[200]},"tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tier","description":"Tier that answered: `proxy` (Massive residential) or `proxy_render` (Massive Web Render). North Data is never fetched from Cormorant's own egress.","examples":["proxy"]},"body_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body Url","description":"Download of the exact bytes (`GET /v1/bodies/{sha256}`)."},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sha256","description":"SHA-256 of the exact bytes."},"body_kind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body Kind","description":"`origin` (bytes North Data sent) or `rendered_dom` (Web Render).","examples":["origin"]},"retrieved_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retrieved At","description":"When the bytes were retrieved (ISO 8601)."},"cached":{"type":"boolean","title":"Cached","description":"Answered from Cormorant's cache."},"revalidated":{"type":"boolean","title":"Revalidated","description":"A stale cached page was confirmed unchanged (conditional request)."},"attempts":{"items":{"$ref":"#/components/schemas/Attempt"},"type":"array","title":"Attempts","description":"Tiers tried, in order."},"cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Usd","description":"Provider spend of this request in USD (null for external customers)."},"parser_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parser Version","description":"Profile parser version (`3`) for profile pages, else null."}},"type":"object","required":["url","final_url","status","tier","body_url","sha256","body_kind","retrieved_at","cached","revalidated","attempts","cost_usd","parser_version"],"title":"NorthdataFetch","description":"Provenance of one North Data request (page, suggest.json or data.json)."},"NorthdataGraphBody":{"properties":{"session_key":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Session Key","description":"Sticky residential session (e.g. the ISIN): suggest, profile and graph requests with the same key share one Massive exit for 15 minutes. Letters, digits and `_ @ . -`; other characters become `_` (at most 64).","examples":["CH0012005267"]},"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]},"allow_paid":{"type":"boolean","title":"Allow Paid","description":"North Data is fetched only through Massive (paid). `false` answers `error: paid_tier_required` at once.","default":true,"examples":[true]},"project_ref":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Project Ref","description":"Free text stored with your usage (e.g. the entity this request is for).","examples":["isin:CH0012005267"]},"entity_id":{"type":"string","maxLength":128,"minLength":1,"title":"Entity Id","description":"North Data entity id (`entity_id` of a profile).","examples":["1234567"]},"country":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Country","description":"Country of the company or research market: ISO 3166-1 alpha-2 (`CH`) or an English or German country name (`Switzerland`). Filters suggest results (`countries=`) and geotargets the Massive exit. Unknown names are ignored, never truncated.","examples":["CH"]}},"type":"object","required":["entity_id"],"title":"NorthdataGraphBody","description":"North Data's network graph of one company.","examples":[{"entity_id":"1234567"}]},"NorthdataGraphResponse":{"properties":{"op":{"type":"string","enum":["suggest","discover","profile","graph"],"title":"Op","description":"The operation (`suggest`, `discover`, `profile`, `graph`)."},"entity_id":{"type":"string","title":"Entity Id","description":"The entity id requested."},"company_connections":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Company Connections","description":"Company nodes (type `c`)."},"person_connections":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Person Connections","description":"Person nodes (type `p`)."},"other_connections":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Other Connections","description":"Other nodes."},"fetch":{"anyOf":[{"$ref":"#/components/schemas/NorthdataFetch"},{"type":"null"}],"description":"Provenance of the data.json request."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"`null` on success, else: `not_found`, `blocked`, `rate_limited` (with `retry_after_s`), `all_tiers_failed`, `parse_failed`, `invalid_identifier`, `paid_tier_required`, `budget_exhausted`, `robots_disallowed`, `timeout`, `politeness_timeout`. Upstream failures never produce an HTTP 5xx.","examples":[null]},"retry_after_s":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Retry After S","description":"Seconds after which a retry makes sense (`rate_limited`, `blocked` while the site is skipped), else null.","examples":[null]},"cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Usd","description":"Provider spend of the whole operation in USD (Massive, Brave for the search fallback); null for keys of an external customer.","examples":[0.00031]},"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"]}},"type":"object","required":["op","entity_id","company_connections","person_connections","other_connections","fetch","error","retry_after_s","cost_usd","request_id"],"title":"NorthdataGraphResponse"},"NorthdataProfile":{"properties":{"name":{"type":"string","title":"Name","description":"Company name (sanitised; never search-page chrome)."},"legal_form":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Legal Form","description":"Legal form from the company's own name or register block (e.g. `AG`, `GmbH`, `plc`, `Ltd`)."},"register_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Id","description":"Register number: `HRB 412761`, `BR 925942480`, `CHE-101.049.653`, a Companies House number, or the register block's text."},"court":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Court","description":"Register court, e.g. `Amtsgericht Freiburg`."},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Register status as shown (e.g. `Active`, `Dissolved`)."},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address","description":"Current address (free text)."},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City","description":"City from the address (free text, not normalised)."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Country from structured data or the address (free text: `CH`, `Switzerland`, ...; not normalised)."},"path_country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Path Country","description":"ISO country code in the profile URL (`/{Name}, {City}, {CC}/...`), if any."},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id","description":"North Data entity id (needed for the network graph)."},"lei":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lei","description":"Legal Entity Identifier, if shown."},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry","description":"Industry, if shown."},"former_names":{"items":{"type":"string"},"type":"array","title":"Former Names","description":"Former company names."},"former_addresses":{"items":{"type":"string"},"type":"array","title":"Former Addresses","description":"Former addresses."},"corporate_purpose":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Corporate Purpose","description":"Corporate purpose text."},"additional_info":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Additional Info","description":"Additional information (e.g. `VAT CHE-101.049.653 MWST`)."},"history":{"items":{"$ref":"#/components/schemas/HistoryEvent"},"type":"array","title":"History","description":"Register history."},"publications":{"items":{"$ref":"#/components/schemas/Publication"},"type":"array","title":"Publications","description":"Register publications."},"mentions":{"items":{"$ref":"#/components/schemas/Publication"},"type":"array","title":"Mentions","description":"Mentions."},"network_graph":{"anyOf":[{"$ref":"#/components/schemas/NetworkGraph"},{"type":"null"}],"description":"The network graph when it was fetched; else null."},"officers":{"items":{"$ref":"#/components/schemas/Officer"},"type":"array","title":"Officers","description":"Officers from the page, then graph persons."},"shareholders":{"items":{"$ref":"#/components/schemas/EntityRef"},"type":"array","title":"Shareholders","description":"Shareholders."},"subsidiaries":{"items":{"$ref":"#/components/schemas/EntityRef"},"type":"array","title":"Subsidiaries","description":"Subsidiaries."},"parent_companies":{"items":{"$ref":"#/components/schemas/EntityRef"},"type":"array","title":"Parent Companies","description":"Parent companies."},"related":{"items":{"$ref":"#/components/schemas/EntityRef"},"type":"array","title":"Related","description":"Page entities of the three lists above, then graph companies not already listed (relation `related`)."},"financials":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Financials","description":"Always null (not parsed)."},"source_url":{"type":"string","title":"Source Url","description":"Absolute URL of the profile page."},"discovery_query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Discovery Query","description":"Query that found the URL (discovery), else null."},"discovery_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Discovery Score","description":"Discovery score 0..1 (discovery), else null."},"discovery_method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Discovery Method","description":"`suggest` or `search` when discovery was used."},"name_similarity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Name Similarity","description":"Name similarity 0..100 of the suggest match, else null."},"scraped_at":{"type":"string","format":"date-time","title":"Scraped At","description":"When the page was retrieved (UTC)."},"fetch_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fetch Tier","description":"Tier that retrieved the page: `proxy` (Massive residential) or `web_render` (Massive Web Render; `proxy_render` in fetch provenance)."},"parser_version":{"type":"string","title":"Parser Version","description":"Parser version (`3`).","default":"3"},"provider":{"type":"string","title":"Provider","description":"Always `northdata`.","default":"northdata"}},"type":"object","required":["name","source_url","scraped_at"],"title":"NorthdataProfile","description":"A parsed North Data company profile (parser version 3)."},"NorthdataProfileBody":{"properties":{"session_key":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Session Key","description":"Sticky residential session (e.g. the ISIN): suggest, profile and graph requests with the same key share one Massive exit for 15 minutes. Letters, digits and `_ @ . -`; other characters become `_` (at most 64).","examples":["CH0012005267"]},"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]},"allow_paid":{"type":"boolean","title":"Allow Paid","description":"North Data is fetched only through Massive (paid). `false` answers `error: paid_tier_required` at once.","default":true,"examples":[true]},"project_ref":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Project Ref","description":"Free text stored with your usage (e.g. the entity this request is for).","examples":["isin:CH0012005267"]},"company_name":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Company Name","description":"Company name to discover when `url` is not given.","examples":["Novartis Pharma AG"]},"headquarters":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Headquarters","description":"Headquarters; the part before the first comma is used as the city.","examples":["Basel, Switzerland"]},"country":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Country","description":"Country of the company or research market: ISO 3166-1 alpha-2 (`CH`) or an English or German country name (`Switzerland`). Filters suggest results (`countries=`) and geotargets the Massive exit. Unknown names are ignored, never truncated.","examples":["CH"]},"min_similarity":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Min Similarity","description":"Minimum name similarity (0–100) for a suggest match.","default":70.0,"examples":[70]},"search_fallback":{"type":"boolean","title":"Search Fallback","description":"Fall back to Cormorant's web search when suggest finds no match.","default":true,"examples":[true]},"url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Url","description":"Profile URL (absolute, or a path such as `/Unilever+plc`). Without it, `company_name` is discovered first.","examples":["https://www.northdata.com/Unilever+plc"]},"include_graph":{"type":"boolean","title":"Include Graph","description":"Also fetch the network graph (`data.json`) and merge it: graph companies into `related`, persons into `officers`. A graph failure keeps the profile (`graph_error`).","default":true,"examples":[true]}},"type":"object","title":"NorthdataProfileBody","description":"A parsed North Data profile, by URL or by discovery.","examples":[{"country":"CH","session_key":"CH0012005267","url":"https://www.northdata.com/Novartis%20Pharma%20AG,%20Basel,%20CH/BR%20925942480"},{"company_name":"Novartis Pharma AG","country":"CH","headquarters":"Basel, Switzerland","session_key":"CH0012005267"}]},"NorthdataProfileResponse":{"properties":{"op":{"type":"string","enum":["suggest","discover","profile","graph"],"title":"Op","description":"The operation (`suggest`, `discover`, `profile`, `graph`)."},"profile":{"anyOf":[{"$ref":"#/components/schemas/NorthdataProfile"},{"type":"null"}],"description":"The parsed profile (with the graph merged), null on error."},"fetch":{"anyOf":[{"$ref":"#/components/schemas/NorthdataFetch"},{"type":"null"}],"description":"Provenance of the profile page."},"discovery":{"anyOf":[{"$ref":"#/components/schemas/NorthdataDiscovery"},{"type":"null"}],"description":"Discovery result when the request gave no `url`."},"graph_fetch":{"anyOf":[{"$ref":"#/components/schemas/NorthdataFetch"},{"type":"null"}],"description":"Provenance of the data.json request (with `include_graph`)."},"graph_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Graph Error","description":"Why the graph is missing (the profile is returned anyway): an error code, or `no_entity_id`."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"`null` on success, else: `not_found`, `blocked`, `rate_limited` (with `retry_after_s`), `all_tiers_failed`, `parse_failed`, `invalid_identifier`, `paid_tier_required`, `budget_exhausted`, `robots_disallowed`, `timeout`, `politeness_timeout`. Upstream failures never produce an HTTP 5xx.","examples":[null]},"retry_after_s":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Retry After S","description":"Seconds after which a retry makes sense (`rate_limited`, `blocked` while the site is skipped), else null.","examples":[null]},"cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Usd","description":"Provider spend of the whole operation in USD (Massive, Brave for the search fallback); null for keys of an external customer.","examples":[0.00031]},"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"]}},"type":"object","required":["op","profile","fetch","discovery","graph_fetch","graph_error","error","retry_after_s","cost_usd","request_id"],"title":"NorthdataProfileResponse"},"NorthdataSuggestBody":{"properties":{"session_key":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Session Key","description":"Sticky residential session (e.g. the ISIN): suggest, profile and graph requests with the same key share one Massive exit for 15 minutes. Letters, digits and `_ @ . -`; other characters become `_` (at most 64).","examples":["CH0012005267"]},"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]},"allow_paid":{"type":"boolean","title":"Allow Paid","description":"North Data is fetched only through Massive (paid). `false` answers `error: paid_tier_required` at once.","default":true,"examples":[true]},"project_ref":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Project Ref","description":"Free text stored with your usage (e.g. the entity this request is for).","examples":["isin:CH0012005267"]},"query":{"type":"string","maxLength":300,"minLength":1,"title":"Query","description":"Company name to look up.","examples":["Novartis"]},"country":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Country","description":"Country of the company or research market: ISO 3166-1 alpha-2 (`CH`) or an English or German country name (`Switzerland`). Filters suggest results (`countries=`) and geotargets the Massive exit. Unknown names are ignored, never truncated.","examples":["CH"]}},"type":"object","required":["query"],"title":"NorthdataSuggestBody","description":"North Data autocomplete (`suggest.json`), company items only.","examples":[{"country":"CH","query":"Novartis Pharma"}]},"NorthdataSuggestItem":{"properties":{"name":{"type":"string","title":"Name","description":"Company name as North Data shows it."},"url":{"type":"string","title":"Url","description":"Absolute profile URL."},"type":{"type":"string","const":"company","title":"Type","description":"Always `company` (persons are dropped)."}},"type":"object","required":["name","url","type"],"title":"NorthdataSuggestItem","description":"One company of North Data's autocomplete."},"NorthdataSuggestResponse":{"properties":{"op":{"type":"string","enum":["suggest","discover","profile","graph"],"title":"Op","description":"The operation (`suggest`, `discover`, `profile`, `graph`)."},"query":{"type":"string","title":"Query","description":"The query sent."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"ISO code sent as `countries=`, if any."},"items":{"items":{"$ref":"#/components/schemas/NorthdataSuggestItem"},"type":"array","title":"Items","description":"Company items, in North Data's order."},"fetch":{"$ref":"#/components/schemas/NorthdataFetch","description":"Provenance of the suggest.json request."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"`null` on success, else: `not_found`, `blocked`, `rate_limited` (with `retry_after_s`), `all_tiers_failed`, `parse_failed`, `invalid_identifier`, `paid_tier_required`, `budget_exhausted`, `robots_disallowed`, `timeout`, `politeness_timeout`. Upstream failures never produce an HTTP 5xx.","examples":[null]},"retry_after_s":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Retry After S","description":"Seconds after which a retry makes sense (`rate_limited`, `blocked` while the site is skipped), else null.","examples":[null]},"cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Usd","description":"Provider spend of the whole operation in USD (Massive, Brave for the search fallback); null for keys of an external customer.","examples":[0.00031]},"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"]}},"type":"object","required":["op","query","country","items","fetch","error","retry_after_s","cost_usd","request_id"],"title":"NorthdataSuggestResponse"},"Officer":{"properties":{"name":{"type":"string","title":"Name","description":"Person's name."},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Role","description":"Role when the page states one (e.g. `Managing Director`); `officers` when only the section is known, `person` for graph persons."},"since":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since","description":"Start date when the page shows one."},"until":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Until","description":"End date when the page shows one."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Link as on the page or in the graph."},"absolute_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Absolute Url","description":"The link as an absolute URL."}},"type":"object","required":["name"],"title":"Officer","description":"A person in a management section of the page or in the network graph."},"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."},"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"]},"free":{"type":"boolean","title":"Free","description":"A free plan.","examples":[false]}},"type":"object","required":["id","code","version","name","currency","free"],"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."},"Publication":{"properties":{"date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date","description":"Date as shown."},"summary":{"type":"string","title":"Summary","description":"Summary text (soft hyphens and NBSP removed)."},"company_name":{"type":"string","title":"Company Name","description":"The profile's company name."}},"type":"object","required":["summary","company_name"],"title":"Publication","description":"A register publication or a mention of the company."},"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."}},"type":"object","required":["key","role","period","resets_at","as_of","usage_refreshed_at","keys","project","events"],"title":"Quota","description":"Answer of `GET /v1/quota`."},"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_paid`, `company`).","examples":[{"fetch":81234,"fetch_paid":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)."},"limit":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Limit","description":"Candidates to return.","default":5}},"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":"Free 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 (Brave, Massive; cache hits and own tiers cost 0). `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_paid`, `fetch_cached`, `company`, `company_cached`, `sec`, `sec_cached`): it maps the request to the meters and charges of your plan.","examples":["fetch_own"]},"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"]}},"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","duckduckgo","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."},"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 `not_found`, `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]},"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.baselcapital.ch/v1/bodies/9f2c…"]},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sha256","description":"SHA-256 of those bytes.","examples":["9f2c…"]},"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 `not_found`, `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]},"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.baselcapital.ch/v1/bodies/9f2c…"]},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sha256","description":"SHA-256 of those bytes.","examples":["9f2c…"]},"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}`."},"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 `not_found`, `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]},"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.baselcapital.ch/v1/bodies/9f2c…"]},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sha256","description":"SHA-256 of those bytes.","examples":["9f2c…"]},"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 `not_found`, `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]},"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.baselcapital.ch/v1/bodies/9f2c…"]},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sha256","description":"SHA-256 of those bytes.","examples":["9f2c…"]},"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 `not_found`, `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]},"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.baselcapital.ch/v1/bodies/9f2c…"]},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sha256","description":"SHA-256 of those bytes.","examples":["9f2c…"]},"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 `not_found`, `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]},"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.baselcapital.ch/v1/bodies/9f2c…"]},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sha256","description":"SHA-256 of those bytes.","examples":["9f2c…"]},"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."},"StatusComponent":{"properties":{"id":{"type":"string","title":"Id","description":"Stable component id: `api`, `search`, `fetch`, `browser_rendering`, `archive`, `paid_tiers`, `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, over the last `window_s` seconds (rates 0–1, `null` when there were too few requests to judge). 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.\npaid tiers when none is configured) are not listed."},"StatusComponentDetail":{"properties":{"id":{"type":"string","title":"Id","description":"Stable component id: `api`, `search`, `fetch`, `browser_rendering`, `archive`, `paid_tiers`, `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, over the last `window_s` seconds (rates 0–1, `null` when there were too few requests to judge). 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."},"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."},"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"],"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"]},"free":{"type":"boolean","title":"Free","description":"Free account or plan.","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 free 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","free","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]},"paid_bytes":{"type":"integer","title":"Paid Bytes","description":"Bytes transferred through paid tiers.","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]}},"type":"object","required":["requests","succeeded","paid_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]},"paid_requests":{"type":"integer","title":"Paid Requests","description":"Fetches served by (or charged for) the paid premium tiers.","examples":[90]},"paid_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Paid Share","description":"`paid_requests / uncached fetches`: how often the premium tiers 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, free 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_paid`, `paid_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_paid`, `fetch_cached`, `company`, `company_cached`, `sec`, `sec_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","paid_requests","paid_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]},"paid_bytes":{"type":"integer","title":"Paid Bytes","description":"Bytes through paid tiers.","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","paid_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]},"paid_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Paid Bytes","description":"Bytes through paid tiers.","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."},"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]},"paid_requests":{"type":"integer","title":"Paid Requests","description":"Fetches served by (or charged for) the paid premium tiers.","examples":[90]},"paid_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Paid Share","description":"`paid_requests / uncached fetches`: how often the premium tiers 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, free 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_paid`, `paid_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","paid_requests","paid_share"],"title":"UsageMetrics","description":"Metrics of a group (or of the totals)."},"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]},"paid_requests":{"type":"integer","title":"Paid Requests","description":"Fetches served by (or charged for) the paid premium tiers.","examples":[90]},"paid_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Paid Share","description":"`paid_requests / uncached fetches`: how often the premium tiers 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, free 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_paid`, `paid_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","paid_requests","paid_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__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":"northdata","description":"Company profiles, discovery and network graphs from North Data (northdata.com / northdata.de), fetched only through Massive (residential proxy, then Web Render) under a site-wide throttle, parsed into structured JSON with provenance.","x-displayName":"North Data"},{"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"}}