# Genka

> Origin-price Indian markets REST API. Primary-source fundamentals, ratios, prices for the Nifty 500 plus a Screener-driven industry taxonomy and a curated private-company catalog with tag-ranked peer inference.

The machine-readable spec at [/openapi.json](https://genka.dev/openapi.json) is authoritative. This document orients humans and LLMs to the important parts.

## Quick facts

- **Base URL**: `https://genka.dev`
- **Canonical prefix**: `/latest/*`. Every published version (`info.version`, e.g. `2026-04-23-dingo`) is ALSO addressable at `/{version}/*` forever -- those URLs never break
- **Auth**: `X-API-Key: <key>` header on everything except `/latest/health`, `/openapi.json`, `/docs`
- **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`
- **Envelope**: every 2xx is `{ data, meta }`. `meta.sources[]` cites primary source per numeric field

## Core docs

- [OpenAPI 3.1 spec](https://genka.dev/openapi.json) -- the contract
- [Swagger UI](https://genka.dev/docs) -- interactive playground
- [Signup + dashboard](https://genka.dev/signup.html) -- self-serve API key

## Endpoints

### Company + ratios (Nifty 500)
- `GET /latest/meta` -- dataset metadata: date range, sector counts, sources
- `GET /latest/companies` -- list constituents, cursor-paginated
- `GET /latest/companies/{symbol}` -- profile; `?expand=sector` hydrates sector
- `GET /latest/companies/{symbol}/ratios?metric=pe&from=&to=` -- single-metric time series (supported metrics: `pe`, `p_s`, `p_b`, `ev_ebitda`, `ev_ebitda_approx`, `roe`, `roce`, `mcap_cr`, `revenue_ttm`, `pat_ttm`, `ebitda_ttm`)
- `GET /latest/companies/{symbol}/income-statements` -- wide-form, one row per period
- `GET /latest/companies/{symbol}/balance-sheets` -- same shape
- `GET /latest/companies/{symbol}/cash-flow-statements` -- same shape
- `GET /latest/companies/{symbol}/filings` -- XBRL download URLs
- `GET /latest/companies/{symbol}/coverage` -- which metrics/periods are populated

### Taxonomy + entities + tags (comparables)
- `GET /latest/taxonomy` -- 12 top-level sectors with entity counts
- `GET /latest/taxonomy/{code}` -- one node (e.g. `IN050103002`) + path + children + entities under it
- `GET /latest/entities/{id}` -- **one-call overview** for ticker or private-co slug. Returns taxonomy path, tag-ranked peers, brands, funding rounds, revenue history, tags
- `GET /latest/tags` -- browse tags; `?kind=index|theme|group|lifecycle|ownership|thesis|sub-leaf`
- `GET /latest/tags/{slug}` -- one tag + all member companies (listed + private)

### Concalls (earnings call transcripts)
- `GET /latest/concalls?symbol=TCS` -- list call meta for a symbol
- `GET /latest/concalls/{id}` -- one transcript
- `GET /latest/concalls/search?q=margin` -- full-text search
- `POST /latest/concalls/answer` -- ask a question grounded in the corpus

### Sectors + prices + search + screener
- `GET /latest/sectors` -- NSE macro-sector list
- `GET /latest/sectors/{slug}?include=members,aggregate&metric=ev_ebitda` -- sector profile
- `GET /latest/prices?symbols=A,B&metrics=pe,p_b&from=&to=` -- multi-symbol time series, max 50 symbols
- `GET /latest/search?q=mamaearth` -- brand/ticker fuzzy search
- `POST /latest/screener` -- filter Nifty 500 by metric thresholds

## Typical workflows

### "Everything about ITC in one call"
```
curl -H "X-API-Key: $KEY" https://genka.dev/latest/entities/ITC
```
Returns profile + taxonomy path (Industries -> FMCG -> Diversified FMCG) + peers (HINDUNILVR etc.) + tags (nifty-50, defensive, fmcg) + brands + rounds + revenue.

### "Who are Purplle's public peers?"
```
curl -H "X-API-Key: $KEY" https://genka.dev/latest/entities/purplle
```
Peers ranked DESC by shared-tag count. NYKAA ranks #1 via shared `beauty` + `beauty-ecommerce` + `d2c-born` tags.

### "Price the Private Banks large-cap basket on P/E"
```
curl -H "X-API-Key: $KEY" https://genka.dev/latest/tags/private-banks-large-cap
curl -H "X-API-Key: $KEY" "https://genka.dev/latest/prices?symbols=HDFCBANK,ICICIBANK,AXISBANK,KOTAKBANK&metrics=pe&from=2024-01-01"
```

### "Every listed specialty-coffee entity"
```
curl -H "X-API-Key: $KEY" https://genka.dev/latest/tags/specialty-coffee
```
Mixed listed + private: blue-tokai, third-wave-coffee, tata-starbucks, TATACONSUM.

### "Full FMCG subtree"
```
curl -H "X-API-Key: $KEY" https://genka.dev/latest/taxonomy/IN04
```
Returns all sub-sectors -> industries -> sub-industries under Fast Moving Consumer Goods, plus the 39 entities classified there.

## SDK generation

Repo ships `openapi-generator-config/` with ready configs for Python and TypeScript:
```
openapi-generator-cli generate -c openapi-generator-config/python.yaml
openapi-generator-cli generate -c openapi-generator-config/typescript.yaml
```

## Source + versioning

- Repo: https://github.com/ScaledFocus/indiamarketsapi
- **Version contract**: every deploy bumps `info.version` (date + next animal alphabetically: aardvark -> beluga -> caracal -> ...). `/latest/*` serves the current version. Every historical version is also live at `/{version}/*` and returns the same response shape forever -- pinning `/2026-04-23-beluga/entities/ITC` in your code is safe. Additive changes propagate to all versions; a breaking change would freeze the affected version at its final response shape.
- Design doc: https://github.com/ScaledFocus/indiamarketsapi/blob/main/docs/TAXONOMY_API_DESIGN.md