API Reference — BharatStock

Authentication

Every endpoint (other than key creation and checkout) requires an X-API-Key header. There is no OAuth flow, no session token, and no key rotation endpoint yet — treat your key like a password.

curl https://bharatstockapi.com/v1/stocks/RELIANCE \ -H "X-API-Key: bsk_live_yourkeyhere"

A missing or invalid key returns 401 Unauthorized.

Rate limits

Enforced per calendar day (UTC), per API key. Limits depend on your plan: 100/day on Free, 10,000/day on Developer, 100,000/day on Pro. Every plan has access to every endpoint — limits are the only difference.

{ "detail": "Daily rate limit of 100 requests exceeded for plan 'free'. Upgrade your plan for higher limits." }

Returned with HTTP status 429. The counter resets at UTC midnight.

Pagination

List endpoints share one envelope shape across the whole API: a data array plus a pagination object. Use the page and page_size query parameters to page through results.

{ "data": [ /* ... */ ], "pagination": { "page": 1, "page_size": 50, "total_items": 2410, "total_pages": 49 } }

Errors

Validation errors return 422 with a structured detail array. Not-found resources return 404. Everything else follows standard HTTP status codes.

{ "error": "validation_error", "detail": [{ "loc": ["query", "limit"], "msg": "Input should be less than or equal to 200" }] }

GET /v1/stocks

List all stocks, paginated and optionally filtered by search text or sector.

Param	Type	Description
page	int	Page number. Default 1.
page_size	int	Rows per page, max 200. Default 50.
q optional	string	Search by symbol or company name.
sector optional	string	Filter by exact sector name, e.g. "Financial Services".
active_only	bool	Exclude delisted stocks. Default true.

Request

GET /v1/stocks?q=reliance&page=1&page_size=10

Response

{ "data": [ { "symbol": "RELIANCE", "isin": "INE002A01018", "company_name": "Reliance Industries Limited", "sector": "Oil Gas & Consumable Fuels", "exchange": "NSE", "is_active": true } ], "pagination": { "page": 1, "page_size": 10, "total_items": 1, "total_pages": 1 } }

GET /v1/stocks/{ticker}

Company info plus the latest available EOD price for a ticker.

Request

GET /v1/stocks/RELIANCE

Response

{ "symbol": "RELIANCE", "company_name": "Reliance Industries Limited", "sector": "Oil Gas & Consumable Fuels", "exchange": "NSE", "industry": "Petroleum Products", "face_value": 10.0, "latest_price": { "trade_date": "2026-08-12", "close": 1421.35, "prev_close": 1408.90, "volume": 8452110, "delivery_pct": 42.6 } }

Unknown ticker returns 404.

GET /v1/stocks/{ticker}/prices

Historical daily prices, optionally bounded by date range. Includes a bonus/split-adjusted close so charts don't show a fake jump on an ex-date.

Param	Type	Description
from optional	date	Start date, e.g. 2026-01-01.
to optional	date	End date.
page, page_size	int	Standard pagination, most recent first.

Request

GET /v1/stocks/RELIANCE/prices?from=2026-08-01&to=2026-08-12

Response (one row)

{ "trade_date": "2026-08-12", "open": 1410.0, "high": 1428.5, "low": 1405.2, "close": 1421.35, "volume": 8452110, "delivery_pct": 42.6, "adjusted_close": 1421.35, "adjustment_factor": 1.0 }

GET /v1/stocks/quotes

Latest price snapshot for multiple tickers in one call — built for watchlists and dashboards. Unknown symbols come back with found: false instead of failing the whole request.

Param	Type	Description
symbols	string	Comma-separated tickers, e.g. RELIANCE,TCS,INFY. Max 50.

Request

GET /v1/stocks/quotes?symbols=RELIANCE,TCS,DOESNOTEXIST

Response

[ { "symbol": "RELIANCE", "close": 1421.35, "change_pct": 0.88, "found": true }, { "symbol": "TCS", "close": 3980.1, "change_pct": -0.42, "found": true }, { "symbol": "DOESNOTEXIST", "found": false } ]

GET /v1/stocks/{ticker}/financials

Quarterly or annual P&L, balance sheet, and cash flow, parsed directly from NSE XBRL filings — including bank/NBFC taxonomy handling and consolidated-vs-standalone filings.

Param	Type	Description
period_type	string	`quarterly` or `annual`. Default quarterly.
page, page_size	int	Standard pagination, most recent period first.

Request

GET /v1/stocks/RELIANCE/financials?period_type=annual

Response (one row)

{ "period_type": "annual", "fiscal_year": "FY25", "period_end_date": "2025-03-31", "revenue": 964693.0, "net_profit": 79020.0, "eps": 58.6, "net_profit_attributable_to_minority_interest": 6821.0, "consolidation_type": "consolidated", "source": "nse_xbrl" }

GET /v1/stocks/{ticker}/ratios

Valuation and profitability ratios, computed on read from the latest price and the latest annual filing (falling back to quarterly if no annual filing exists yet).

Request

GET /v1/stocks/RELIANCE/ratios

Response

{ "as_of_date": "2026-08-12", "price": 1421.35, "pe_ratio": 24.3, "pb_ratio": 2.1, "roe": 8.9, "roce": 10.4, "dividend_yield": 0.35, "week_52_high": 1551.0, "week_52_low": 1201.6, "financials_period_type": "annual", "financials_fiscal_year": "FY25" }

GET /v1/stocks/{ticker}/technical-indicators

SMA, EMA, RSI, and MACD, computed server-side from daily closes. Values are null wherever there isn't enough price history yet to compute them.

Param	Type	Description
sma_period	int	Default 20.
ema_period	int	Default 20.
rsi_period	int	Default 14 (Wilder's smoothing).
from, to optional	date	Bound the returned window.

Request

GET /v1/stocks/RELIANCE/technical-indicators?sma_period=20&rsi_period=14

Response (one row)

{ "trade_date": "2026-08-12", "close": 1421.35, "sma": 1398.42, "ema": 1405.11, "rsi": 58.3, "macd": 6.2, "macd_signal": 4.8, "macd_histogram": 1.4 }

GET /v1/stocks/{ticker}/corporate-actions

Dividends, bonus issues, splits, and rights issues for a ticker, most recent ex-date first.

Param	Type	Description
action_type optional	string	dividend, bonus, split, rights, buyback, or other.

Request

GET /v1/stocks/RELIANCE/corporate-actions?action_type=bonus

Response (one row)

{ "action_type": "bonus", "subject": "Bonus issue 1:1", "ex_date": "2024-10-28", "ratio_from": 1, "ratio_to": 1, "source": "nse_corporate_actions" }

GET /v1/stocks/{ticker}/shareholding

Quarterly shareholding pattern (promoter / public / employee-trust split, with FII/DII/mutual-fund sub-splits where NSE's filing reports them).

Request

GET /v1/stocks/RELIANCE/shareholding

Response (one row)

{ "as_on_date": "2026-06-30", "promoter_pct": 50.48, "public_pct": 49.52, "employee_trust_pct": 0.0, "source": "nse_shareholding_pattern" }

GET /v1/stocks/compare

Compare valuation and profitability ratios across every active stock in a sector — computed in bulk rather than looping the single-ticker ratios endpoint.

Param	Type	Description
sector	string	Exact sector name, e.g. "Financial Services".
sort	string	market_cap, pe_ratio, pb_ratio, roe, or roce. Default market_cap.
limit	int	Max 100. Default 20.

Request

GET /v1/stocks/compare?sector=Financial Services&sort=pe_ratio&limit=5

Response (one row)

{ "symbol": "AAVAS", "company_name": "Aavas Financiers Limited", "sector": "Financial Services", "price": 1711.7, "pe_ratio": 27.8, "roe": 14.2 }

GET /v1/movers

Top gainers, losers, or most-active-by-volume stocks for the most recent trading day with price data. Uses the latest date present in the data, not today's calendar date, so it stays correct on weekends and holidays.

Param	Type	Description
category	string	gainers, losers, or active. Default gainers.
limit	int	Max 100. Default 20.

Request

GET /v1/movers?category=gainers&limit=5

Response (one row)

{ "symbol": "SWARAJ", "company_name": "Swaraj Engines Limited", "trade_date": "2026-08-12", "close": 2840.0, "prev_close": 2607.5, "change_pct": 8.92, "volume": 312440 }

GET /v1/price-shockers

Stocks whose price moved by at least a given percent versus the previous close. Unlike /movers (always a top-N ranking), this is a threshold filter — it can return zero rows on a quiet day, or more than limit on a volatile one.

Param	Type	Description
min_change_pct	float	Minimum absolute % move. Default 5.0.
direction	string	up, down, or both. Default both.
limit	int	Max 200. Default 50.

Request

GET /v1/price-shockers?min_change_pct=5&direction=both

Response (one row)

{ "symbol": "SWARAJ", "company_name": "Swaraj Engines Limited", "trade_date": "2026-08-12", "close": 2840.0, "prev_close": 2607.5, "change_pct": 8.92, "volume": 312440 }

GET /v1/search

Fuzzy search across ticker symbol and company name. Ranks exact/prefix symbol matches above substring/company-name matches, active stocks first.

Param	Type	Description
q	string	Search text, e.g. "reliance".
limit	int	Max 50. Default 10.

Request

GET /v1/search?q=reliance

Response

[ { "symbol": "RELIANCE", "company_name": "Reliance Industries Limited", "is_active": true } ]

GET /v1/indices

List all tracked NSE indices, paginated and optionally filtered by category (e.g. broad-market vs. sectoral).

Param	Type	Description
category optional	string	e.g. "BROAD MARKET INDICES", "SECTORAL INDICES".

Request

GET /v1/indices?category=BROAD MARKET INDICES

Response (one row)

{ "name": "NIFTY 50", "category": "BROAD MARKET INDICES", "is_active": true }

GET /v1/indices/{name}/prices

Historical daily EOD levels for an index, optionally bounded by date range.

Request

GET /v1/indices/NIFTY 50/prices?from=2026-08-01

Response (one row)

{ "trade_date": "2026-08-12", "open": 24580.2, "high": 24710.9, "low": 24540.0, "close": 24695.4 }

Every endpoint, with real requests and real responses.

Authentication

Rate limits

Pagination

Errors