API · Filings

Semantic content search (RAG)

Semantic search across the full text of every filing.

POST/api/v1/data/filings/content-search

Returns the most relevant passages from filings ranked by vector similarity to the query. Each result includes an excerpt of the page text, the source filing (docid), a ready-made citation, and a page_id you can resolve to cite the original PDF or EDGAR page.

When to use this

"What does Neste say about renewable-diesel capacity in 2024?"
"Find any mention of supply-chain risk in Nokia's 2023 annual report."
"Show me Apple's dividend policy language."

This is the right tool whenever the answer lives in prose rather than in a financial line item.

Body

Field	Type	Description
queryrequired	string	Natural-language search query, in any major language.
company	string	Optionally restrict to a specific company (name or ticker).
year	integer	Optionally restrict to a specific fiscal year.
quarter	integer	Optionally restrict to a fiscal quarter (1–4). The quarter field is not populated for every filing, so use it only for questions about one interim report.
document_type	string	annual_report \| interim_report \| stock_exchange_release \| 10-K \| 10-Q \| 8-K. Related types are matched too (annual_report also matches 10-K and 20-F).
topic_tags	string[]	Restrict to pages tagged with any of these topics, e.g. ["leases", "goodwill", "risks_uncertainty"]. Unknown tags are ignored and reported back.
ifrs_tags	string[]	Restrict to pages tagged with any of these standards, e.g. ["IFRS 16", "IAS 36"]. Nordic filings only; skipped on US searches.
auto_detect_tags	boolean default: true	When no tags are passed, detect them from the query text and apply them. Set false for a pure vector search.
limit	integer default: 5	Number of passages to return (1–20).

Example

curl

curl https://api.clarifo.com/api/v1/data/filings/content-search \
  -H "Authorization: Bearer $CLARIFO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "renewable diesel production capacity 2024",
    "company": "Neste",
    "document_type": "annual_report",
    "limit": 3
  }'

Response

json

{
  "results": [
    {
      "company_name": "Neste Oyj",
      "year": "2023",
      "period": "FY2023",
      "document_title": "Neste Oyj 2023 Annual Report",
      "document_type": "annual_report",
      "content": "Renewable Products segment produced 3.3 million tonnes…",
      "content_title": "Renewable Products",
      "docid": "722df34e9f191a97518a8560755cb9e9",
      "page_id": "722df34e9f191a97518a8560755cb9e9_20",
      "page_number": 20,
      "page_number_kind": "pdf_render",
      "page_reference": "p. 20",
      "page_reference_type": "page",
      "source_url": "https://…",
      "citation_label": "Neste Oyj 2023 Annual Report (FY2023), p. 20",
      "citation_markdown": "[Neste Oyj 2023 Annual Report (FY2023), p. 20](https://…)",
      "evidence_type": "filing_passage",
      "supports": "direct",
      "confidence": "high",
      "evidence": {"excerpt": "…", "source_kind": "s3_pdf", "…": "…"},
      "score": 0.8921
    }
  ],
  "sources": [
    {"id": "src_1", "page_id": "722df34e9f191a97518a8560755cb9e9_20", "citation_markdown": "…", "…": "…"}
  ],
  "source_policy": {
    "citation_mode": "claim_level",
    "require_excerpt": true,
    "require_page_number": true,
    "require_source_url": true,
    "max_sources_per_claim": 3,
    "display": {"user_facing_citation": "citation_markdown", "…": "…"}
  },
  "total": 1,
  "has_more": false,
  "query": "renewable diesel production capacity 2024",
  "resolution": {"input_company": "Neste", "resolved_name": "Neste Oyj", "market": "nordic", "ticker": "NESTE"},
  "tag_filters": {"topic_tags": ["segment_performance"], "applied": true, "source": "auto_detected"}
}

Response fields

Field	Description
`results[].content`	Page text excerpt, up to 500 characters (1,500 for financial tables). Use the snapshot endpoint for the page itself.
`results[].citation_label`, `citation_markdown`	Ready-made citation. Show these to users instead of the raw `page_id`.
`results[].page_reference`, `page_reference_type`	Citation anchor: `"p. 20"` (`page`) for Nordic PDFs, a section heading such as `"Item 7. MD&A"` (`section`) for SEC filings, or the document type (`document`).
`results[].evidence`	Full evidence card for the hit (a longer `excerpt`, `source_kind`, `resource_uri`, ...).
`sources`	Deduplicated evidence cards, one per distinct page.
`source_policy`	How Clarifo expects citations to be rendered.
`has_more`	`true` when the result list filled `limit`, so more relevant passages may exist.
`resolution`	How `company` was resolved.
`tag_filters`	The topic/IFRS tag filter that was applied and whether it came from you (`caller`) or was auto-detected. `applied: false` means the tag filter matched nothing and the results come from an unfiltered retry.
`diagnostic`	Present when a company-scoped search returned no passages, with the reason.
`suggestion`	Present when a company name was detected in the query but `company` was not set.

Empty fields are omitted rather than sent as null. If the search backend fails, the response is HTTP 200 with "error", "failure_kind": "search_upstream" and an empty results list.

Tips

The query is natural language in any major language. A Finnish passage is retrievable with an English query and vice versa.
Cap limit to what your downstream LLM context can handle. Five passages is usually enough.
Combine with the filings search endpoint when you need a deterministic scope.