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.

Other endpoints

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. 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.