# Genka

> Origin-price Indian markets REST API. Primary-source fundamentals, ratios, prices for the Nifty 500 (plus a tracked extras list of ~10 mid/small-caps + recent IPOs beyond the index), a Screener-driven industry taxonomy, and a curated private-company catalog with tag-ranked peer inference.

The machine-readable spec at [/docs/openapi.json](https://genka.dev/docs/openapi.json) is authoritative. This file is the orientation cheat-sheet; see the [REST playground](https://genka.dev/docs/rest/) and [MCP catalog](https://genka.dev/docs/mcp/) for full schemas.

## Quick facts

- **Base URL**: `https://genka.dev`. Canonical prefix `/latest/*`; every published version (e.g. `/2026-04-23-dingo/*`) stays live forever
- **Auth**: `X-API-Key: <key>` header. Public exceptions: `/latest/health`, `/docs/*`, `/llms.txt`, `/latest/mf/health`
- **Rate limit**: 60 req/min per key. Headers `X-RateLimit-Limit/Remaining/Reset`; `Retry-After` on 429
- **Errors**: RFC 7807 `application/problem+json` with `code`, `detail`, `instance`, `request_id`, often `hint`
- **Envelope**: every 2xx is `{ data, meta }`. `meta.sources[]` cites primary source per numeric field. Every list response carries top-level `count`, `has_more`, `next_cursor` — one generic paginator works across the surface (bounded responses emit `has_more=false`, `next_cursor=null`)
- **Consolidated contract** (fundamentals): every endpoint that touches `fundamentals` / `market` (`/coverage`, `/snapshot`, `/statements?type=`, `/ratios`, `/filings`, legacy `/income-statements` et al) takes optional `?consolidated=Consolidated|Standalone` (default `Consolidated`). When the requested variant has zero rows the handler auto-falls-back to the opposite so standalone-only filers (INDRAMEDCO, WAKEFIT, HATSUN, recent-IPO quarters of AGARWALEYE) respond without per-symbol knowledge. Response always echoes `data.consolidated`
- **Enum casing**: query-param enums are case-insensitive. `?consolidated=Consolidated`, `=consolidated`, `=STANDALONE`, `=non-consolidated` all normalise to the canonical form before validation
- **Discovery loop**: start at `GET /companies/{symbol}/coverage`. Response includes `data.endpoints[]` (URLs for every related sub-resource), `data.sector_hints` (industry → best top-line metric — banks `interest_earned`, insurers `gross_premium_income`, default `revenue`), and `data.latest_period` (most-recent `period_end` across any metric — useful as default `as_of`). One-call research bundle: `GET /companies/{symbol}/snapshot` returns coverage + last-4Q income/balance/cf + latest ratios + 30d prices in a single response (~8-12 KB). `?expand[]=income|balance|cash_flow|full_statements` swaps the 4-quarter cap for the full available series on that family; response echoes `data.expanded[]`

## Coverage windows

- **Fundamentals** (`/ratios`, `/statements`, `/coverage`, `/snapshot`): earliest `period_end` 2017-03-31 (NSE XBRL universal mandate per SEBI Circular CIR/CFD/CMD/15/2015). Pre-2017 is PDF-only.
- **Daily prices** (`/prices`): NSE bhavcopy back to **1995-01-02** (~7,750 trading days, ~10.8M rows). Daily cron 13:15 UTC. Note: prices are ~22 years deeper than fundamentals — backtests joining the two cap at the shorter window.
- **Corp actions** (`/prices/{symbol}/corp-actions`): ~42,000 events back to 1995. Splits/bonuses carry `factor` for price adjustment. Daily cron 14:30 UTC.
- **Mutual funds**: ~4,700 active funds, 20y daily NAV history (AMFI + mfapi.in seed), monthly risk-metric snapshots per fund. Holdings: PPFAS Flexi Cap has 124 monthly snapshots back to 2013-07; ~2,100 funds have a single live Tickertape snapshot; ~2,600 have nothing yet.
- **Concalls**: ~18,000 docs across 565 NSE issuers from 2018-08 (bulk 2024+). All Nifty 100 covered.

## Endpoints

**Discovery + single-symbol bundles** (start here)
- `GET /latest/companies/{symbol}/coverage` — discovery route, returns `endpoints[]` + `sector_hints` + the coverage matrix
- `GET /latest/companies/{symbol}/snapshot` — one-call research bundle (coverage + last-4Q statements + latest ratios + 30d prices). `?expand[]=income|balance|cash_flow|full_statements` returns the full available series instead of the 4Q cap
- `GET /latest/companies/{symbol}` — lean profile; `?expand=sector|ratios|recent|corp_actions|summary` to hydrate

**Statements + ratios**
- `GET /latest/companies/{symbol}/statements?type=income|balance|cash_flow` — canonical statement route (one of three families per call)
- `GET /latest/companies/{symbol}/ratios?metric=pe` — single-metric series. Metrics: `pe, p_s, p_b, ev_ebitda, ev_ebitda_approx, roe, roce, mcap_cr, ebitda_ttm, revenue_ttm, pat_ttm`
- `GET /latest/companies/{symbol}/filings` — XBRL download URLs
- *Deprecated, kept for back-compat*: `/income-statements`, `/balance-sheets`, `/cash-flow-statements` — use `/statements?type=` instead

**Prices**
- `GET /latest/prices?symbols=A,B&from=&to=&limit=` — bulk OHLCV bars (max 50 symbols). Paginate via `has_more` + `next_cursor` (oldest `trade_date` returned)
- `GET /latest/prices/{symbol}/latest` — pre-computed indicator panel + return flavours (raw / adjusted / total-return). `?expand[]=bars|corp_actions|adjusted`
- `GET /latest/prices/{symbol}/corp-actions` — splits, bonuses, dividends, rights, buybacks, mergers

**Comparables (taxonomy + entities + tags)**
- `GET /latest/entities/{id}` — one-call overview for ticker or private slug: taxonomy path + tag-ranked peers + brands + funding + private financials (unlisted) + tags
- `GET /latest/taxonomy[/{code}]` — sector tree; node returns path + children + member entities
- `GET /latest/tags[/{slug}]` — browse tags (`?kind=index|theme|group|lifecycle|ownership|thesis|sub-leaf`) or one tag's members

**Sectors + search + screener**
- `GET /latest/sectors[/{slug}]` — sector list; profile with `?include=members,aggregate&metric=`
- `GET /latest/search?q=` — cross-asset fuzzy search (`entity_type=ticker|private|mf`)
- `POST /latest/screener` — filter Nifty 500 by metric thresholds

**Concalls** — full-text transcripts + RAG answers
- `GET /latest/concalls?symbol=TCS&kind=NSE|TXN|IP|DRHP` — list call meta. Pass `q=<name>` to resolve a company name → ticker server-side
- `GET /latest/concalls/{id}` — one transcript
- `GET /latest/concalls/search?q=margin&symbol=TCS` — full-text BM25. **Always pass `symbol=`** for issuer-specific questions (q-only ranks generic mentions)
- `POST /latest/concalls/answer` — RAG over the corpus; citations carry `id`

**Mutual funds** (`/latest/mf/*`) — abbreviated; see [/docs/rest/](https://genka.dev/docs/rest/) for full param matrix
- `GET /mf/health` (public) — liveness, counts, latest NAV date
- `GET /mf?amc=&category=&theme=&factor=&cursor=&limit=` — list funds
- `GET /mf/{slug}` — one fund (AMC, SEBI category, TER, AUM, exit load, benchmark...)
- `GET /mf/{slug}/{nav|metrics|plans|holdings|overlap}` — per-fund views (`metrics?period=1y|3y|5y|7y|10y|si&as_of=`)
- `GET /mf/{search|screener|compare|amcs|themes|categories|snapshot/latest|export}` — discovery + bulk
- `POST /mf/{slug}/sip` — monthly SIP simulation
- `POST /mf/{portfolio/analyze|backtest}` — multi-fund portfolio operations

## MCP (recommended for agents)

`POST https://genka.dev/mcp` — JSON-RPC 2.0 over Streamable HTTP. Same auth, billing, rate limit. Tools mirror `/latest/mf/*` REST 1:1 (full catalog at [/docs/mcp/](https://genka.dev/docs/mcp/)). Self-describing schemas + upfront validation = lower context burn than REST.

Setup (Claude Code `~/.config/claude/mcp.json`):
```json
{"servers":{"genka":{"transport":"http","url":"https://genka.dev/mcp","headers":{"X-API-Key":"${GENKA_API_KEY}"}}}}
```

## Where Genka fits

Research layer, read-only, broker-agnostic. **Not** a brokerage. Routing for an agent:

- Order placement / live ticks / depth → a brokerage API (Zerodha Kite has first-party MCP at `mcp.kite.trade`; Groww / Dhan / INDstocks ship REST)
- Free OHLC for an IN ticker, no key → `yfinance` (`TCS.NS`, `500325.BO`)
- Free AMFI NAV history, no key → `mfapi.in`
- Quarterly XBRL fundamentals, concall RAG, MF screener with 20y NAV + factor metrics, 30y corp-action-adjusted prices → **Genka**
- Human-facing chart UI → Tickertape or Screener.in (no public API)

Composition: research on Genka via MCP, execute on a broker. Decision matrix at [/docs/ecosystem/](https://genka.dev/docs/ecosystem/).

## Worked examples

**"Give me everything about DODLA"** — one call. Cap-on default for tight context budget; opt into the full series only for the families you actually need:
```
curl -H "X-API-Key: $KEY" https://genka.dev/latest/companies/DODLA/snapshot
# 4 quarters each; payload ~8-12 KB

curl -H "X-API-Key: $KEY" "https://genka.dev/latest/companies/DODLA/snapshot?expand[]=income"
# Full income time-series (21 quarters), balance + cash-flow still capped at 4

curl -H "X-API-Key: $KEY" "https://genka.dev/latest/companies/DODLA/snapshot?expand[]=full_statements"
# Full series for all three families. Response includes `expanded: ["income","balance","cash_flow"]`
```

**"Discover then drill"** — coverage first surfaces what's available, which variant fronts it, and which endpoints to call next:
```
curl -H "X-API-Key: $KEY" https://genka.dev/latest/companies/INDRAMEDCO/coverage
# data.consolidated == "Standalone" (Apollo subsidiary, files Standalone only)
# data.latest_period == "2026-03-31"  (most-recent period_end across any metric)
# data.endpoints[] points at snapshot / statements / ratios / prices / corp_actions
# data.sector_hints says revenue_metric = "revenue" (default; would say "interest_earned" for a bank)
```

**"Page deeper than 100 rows of prices"** — `next_cursor` walks backwards by `trade_date`:
```
curl -H "X-API-Key: $KEY" "https://genka.dev/latest/prices?symbols=NYKAA&from=2018-01-01&limit=100"
# data.has_more=true, data.next_cursor="2024-08-12"  (oldest date in this window)
curl -H "X-API-Key: $KEY" "https://genka.dev/latest/prices?symbols=NYKAA&from=2018-01-01&to=2024-08-12&limit=100"
# Repeat until has_more=false.
```

**"What was the 3Y Sharpe of PPFAS Flexi Cap on the Covid trough?"**:
```
curl -H "X-API-Key: $KEY" "https://genka.dev/latest/mf/ppfas-parag-parikh-flexi-cap/metrics?period=3y&as_of=2020-04-01"
```
Closest snapshot ≤ that date. Returns absolute CAGR/Sharpe/Sortino/Max DD/Ulcer/UPI/Calmar + benchmark alpha/beta vs Nifty 500 + tail risk (VaR/CVaR/skew/kurt).

## Versioning + source

- Repo: https://github.com/ScaledFocus/genka
- **Version contract**: every deploy bumps `info.version` (date + next animal alphabetically). `/latest/*` serves the current; every historical version stays live at `/{version}/*` forever — pinning is safe. Additive changes propagate to all versions; a breaking change would freeze the affected version at its final shape.
- Design docs: [TAXONOMY_API_DESIGN.md](https://github.com/ScaledFocus/genka/blob/main/docs/TAXONOMY_API_DESIGN.md), [MF_API_DESIGN.md](https://github.com/ScaledFocus/genka/blob/main/docs/MF_API_DESIGN.md)
- SDK generation: configs in `openapi-generator-config/` for Python + TypeScript