For Developers

API reference & integration

FilingsIQ is a thin FastAPI service over a retrieval pipeline -- every endpoint below returns real, cited data from the same corpus the web demo uses.

Ask a question

POST /ask
Content-Type: application/json

{"question": "What are NVIDIA's main risk factors?"}

curl -X POST https://theriskfactors.com/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "What are NVIDIA'"'"'s main risk factors?"}'

Returns {"answer": "...", "sources": [...], "routed_to": "filings"} -- each source includes ticker, form, filing_date, section, and a source_url pointing at the original SEC document.

ticker is optional: omitted, the company is inferred from the question text (multi-company questions stay corpus-wide). Pass "ticker": "NVDA" to pin the scope explicitly, or "ticker": "" to force corpus-wide search with no inference. Check what a question resolves to via GET /resolve?q=....

Raw retrieval, no generation

POST /search
{"query": "supply chain risk", "ticker": "AAPL", "k": 6}

Returns retrieved chunks directly -- for a caller that wants to reason over evidence itself rather than a generated answer.

Check what's actually ingested

GET /coverage

One row per (ticker, form, filing_year) actually in the corpus, with chunk counts and last-ingested timestamps. Check this before assuming a ticker or year is covered.

IPO brief (pre-IPO / S-1 tickers only)

POST /brief
{"ticker": "SCTX", "max_peers": 5}

Returns a narrative (business overview, risk factors, use of proceeds -- generated the same way as /ask, with the same citations) plus a peer_comparison table: exact, SEC-reported financials (revenue, margins, cash, R&D) for already-public companies in the same industry, including each peer's trailing EPS beat/miss track record against analyst consensus where available. 404 if the ticker was never ingested as an S-1. A pre-IPO filer has no structured financials or analyst coverage of its own, so every exact-number comparison in the response is against peers, never the filer itself -- see the limitations field on the response for what's missing on a given request. Expensive (three generation calls plus several peer data fetches) -- rate-limited tighter than /ask at 3/minute, 10/hour, and cached for 24h per (ticker, max_peers).

Other endpoints

GET /resolve?q=... -- which covered company a question resolves to, or null
GET /health -- liveness check
GET /llms.txt -- plain-text summary for AI agents/crawlers

Rate limits

/ask: 5 requests/minute, 20/hour per IP. /search: 15/minute, 60/hour per IP. /brief: 3/minute, 10/hour per IP. This is a demo deployment without an SLA -- for sustained or bulk use, self-host from the source below rather than relying on rate-limited access here.

MCP server

Add FilingsIQ directly to Claude Desktop, Claude Code, or any MCP-compatible client as a callable tool:

{
  "mcpServers": {
    "sec-analyst": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/absolute/path/to/sec-analyst-agent"
    }
  }
}

Exposes three tools: ask_sec_analyst, search_filings, list_coverage. Runs as a local process against whichever database your own .env points at -- see the source repo for setup.

Architecture & design decisions

Full system architecture (component diagrams, control flow, ingestion pipeline), every real production bug found and fixed along the way, and the tradeoffs behind each design decision are documented in the source repository's README. The repository is currently private -- contact the maintainer for access.