InvestSights API & MCP

Authentication

Every request authenticates with an X-API-Key header (key format isk_…, provisioned by the InvestSights team). One key works on the REST endpoints and on the MCP connection URL below, for the products and sub-modules it includes.

What a key includes

A key is issued for one or more products, or for sub-modules inside a product. GET /api/v2/mcp/tools (and tools/list on the MCP connection) lists exactly the tools your key includes. A call to a tool outside them is refused. On the REST endpoint POST /api/v2/mcp/call it returns 403. When the tool's product or sub-module is not in the key, the message names them, for example Tool 'get_stock_financials' is in Equity & Market / Financials & Fundamentals, which is not enabled for your API key. When the product is included but the key also has its own list of tools and the tool is not on it, the message is shorter, for example Tool 'get_dividends' not enabled for your API key. On the MCP connection URL a tools/call for such a tool returns JSON-RPC error -32601 (Tool not found), the same answer as for a tool that does not exist.

A key can also carry an expiry date, its own rate limits and a list of symbols. After the expiry date every request returns 401.

Evaluation keys

To try the API, write to [email protected] with who you are, what you are building, the products you need and the number of calls you expect to make. An evaluation key normally runs for 14 days. It is for testing and building, not for a service offered to customers. Use of any key is governed by the API Terms.

All 58 tools are read-only / ANALYTICS-only: they return data, scores, and analysis — never buy/sell/target recommendations.

REST API

Two endpoints. List the tools, then call any of them with a JSON body.

curl -s https://investsights.in/api/v2/mcp/tools \
  -H "X-API-Key: isk_your_api_key"

{ "tool": "<tool_name>", "arguments": { ... } }

curl -s -X POST https://investsights.in/api/v2/mcp/call \
  -H "X-API-Key: isk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"tool":"get_forensic_score","arguments":{"symbol":"RELIANCE"}}'

import requests
H = {"X-API-Key": "isk_your_api_key"}

# institutional valuation (DCF + relative + VaR)
r = requests.post("https://investsights.in/api/v2/mcp/call", headers=H,
    json={"tool": "get_valuation", "arguments": {"symbol": "TCS"}})
print(r.json()["result"])

Connect via MCP

https://investsights.in/api/v2/mcp-public/mcp

Broker / B2B connection

Business integrations use a scoped isk_ key instead of OAuth, for clients that only accept a URL. The key sits in the connection URL path:

https://investsights.in/api/v2/mcp/{your_key}/mcp

• In your client: Settings → Connectors / MCP → Add custom / remote server → paste the URL above. This path carries its own credential, so there are no OAuth fields to fill in.
• The tools appear automatically — then ask in plain English (e.g. "Get the forensic score and valuation for Reliance").

Examples

Portfolio analytics (stateless)

Pass a list of holdings — InvestSights returns aggregate value & P&L, value-weighted quality and forensic scores, sector allocation, concentration (HHI + top-holding %), and flagged holdings. Nothing is stored; the holdings are supplied per call.

import requests
H = {"X-API-Key": "isk_your_api_key"}
r = requests.post("https://investsights.in/api/v2/mcp/call", headers=H, json={
    "tool": "analyze_portfolio",
    "arguments": {"holdings": [
        {"symbol": "RELIANCE", "quantity": 50, "avg_price": 1200},
        {"symbol": "TCS",      "quantity": 20, "avg_price": 3100},
        {"symbol": "INFY",     "quantity": 80, "avg_price": 1500}
    ]}})
print(r.json()["result"])

{
  "total_value": 250120.0,
  "total_pnl": -10152.5,
  "total_pnl_pct": -3.9,
  "weighted_quality_score": 68.4,
  "weighted_piotroski": 6.1,
  "sector_allocation_pct": {"Technology": 51.9, "Energy": 48.1},
  "concentration": {"hhi": 0.367, "top_holding": "INFY", "top_holding_pct": 48.1},
  "flagged_holdings": [],
  "disclaimer": "Analytics only. Not investment advice."
}

Tool Catalog

All 58 tools, grouped by category — the 46 core tools first, then the 3 forensic and 9 mutual-fund tools in the optional section below. symbol = NSE ticker (e.g. RELIANCE, TCS) — uppercase, no suffix. * marks a required argument; NEW marks the Fourteen tools were added in June 2026.

The 3 forensic and 9 mutual-fund tools that complete the 58 are listed separately in the optional section at the end: they are flag-gated per deployment (both switched on for investsights.in keys) and are not part of the 46 core tools. The free public connector exposes a smaller curated pack of 26 public research tools.

Valuation & Forensics

Financials & Fundamentals

Screening & Comparison

Market, Sectors & Technicals

News, Sentiment & Calendar

IPO

Investors

Portfolio Analytics

AI Research (deep, ~30–60s)

Knowledge Graph

Optional Forensic Tools optional · enabled on investsights.in

Three forensic-relationship tools gated by a deployment flag. They are not part of the 46 core tools above, but they are switched on for investsights.in Enterprise keys (part of the 58-tool catalog). They are not included in the free public connector pack. (The optional mutual-fund tools further down are in the public pack.) Check GET /api/v2/mcp/tools for the tools your own key actually returns — that response is the authoritative list for your deployment.

Optional Mutual Fund Tools optional · enabled on investsights.in

Nine mutual-fund tools built on monthly portfolio disclosures (AMC factsheets) for ~14,000 schemes and ~2,200 distinct portfolios. They are gated by a deployment flag and are not part of the 46 core tools above, but they are switched on for investsights.in keys (part of the 58-tool catalog) and are included in the free public connector pack. All outputs are descriptive (ANALYTICS mode): rankings state the definition they used and every number is a row from the latest factsheet month. Fund references accept an AMFI scheme code, an ISIN, or a name ("parag parikh flexi cap"). Every result carries the same meta block — logic_version (semver of the definitions behind the numbers; bumped whenever a figure could change for the same factsheet month), data_source, holdings_as_of, previous_month, returns_as_of, plan_scope, methodology — plus one top-level disclaimer, so a renderer never has to special-case a tool. Holdings counts are one object everywhere: holdings.equity (distinct listed equity lines), holdings.instruments_total (incl. cash/TREPS/debt), holdings.reported_by_factsheet (the AMC's own count).

Rate Limits & Notes

Internal Data API separate API · X-Internal-Key

The endpoints below are a separate bulk-JSON data API (base /api/internal/v1) authenticated with an X-Internal-Key header — distinct from the MCP/REST tools above. Use it for raw data pipelines (agent-context bundles, OHLCV, screener dumps). It is open to a key with no tool or symbol restriction that holds all products or the whole Equity & Market product. Other products granted alongside it do not block access. Existing partner keys are of this kind and continue unchanged. A key with a tool or symbol restriction, or one that holds only some Equity & Market sub-modules or no Equity & Market at all, receives 403: This API key does not include the internal REST API.

Authentication

All Internal Data API requests require an X-Internal-Key header with your API key. Keys are provisioned by the InvestSights admin team.

X-Internal-Key: isk_your_api_key_here

Example Request

curl -H "X-Internal-Key: isk_your_api_key_here" \
  https://investsights.in/api/internal/v1/market/macro

import requests

API_KEY = "isk_your_api_key_here"
BASE    = "https://investsights.in/api/internal/v1"
HEADERS = {"X-Internal-Key": API_KEY}

resp = requests.get(f"{BASE}/market/macro", headers=HEADERS)
print(resp.json())

const API_KEY = "isk_your_api_key_here";
const BASE = "https://investsights.in/api/internal/v1";

const resp = await fetch(`${BASE}/market/macro`, {
  headers: { "X-Internal-Key": API_KEY }
});
const data = await resp.json();
console.log(data);

Base URL

https://investsights.in/api/internal/v1

All endpoint paths below are relative to this base URL.

Rate Limits

Error Handling

The API uses standard HTTP status codes. Errors return a JSON body with a detail field.

{
  "detail": "Invalid internal API key"
}

Endpoints

curl -X POST https://investsights.in/api/internal/v1/agent-context/RELIANCE \
  -H "X-Internal-Key: isk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "include_sections": ["fundamental", "technical", "risk"],
    "price_days": 252,
    "news_limit": 5
  }'

{
  "symbol": "RELIANCE",
  "exchange": "NSE",
  "company_name": "Reliance Industries Limited",
  "last_updated": "2026-03-11T18:30:00+05:30",

  "fundamental": {
    "current_price": 1245.50,
    "market_cap_cr": 1682340.5,
    "pe_ratio": 26.8,
    "pb_ratio": 2.1,
    "ev_ebitda": 14.3,
    "roe": 8.9,
    "debt_to_equity": 0.38,
    "current_ratio": 1.22,
    "altman_z_score": 3.41,
    "altman_zone": "SAFE",
    "piotroski_f_score": 7,
    "piotroski_rating": "STRONG",
    "promoter_holding": 50.3,
    "fii_holding": 23.1,
    // ... 30+ more fields
  },

  "statements": {
    "income": [{"period": "FY2025", "revenue": 985060, ...}],
    "balance_sheet": [{"period": "FY2025", "total_assets": 1520000, ...}],
    "cashflow": [{"period": "FY2025", "free_cashflow": 42000, ...}]
  },

  "shareholding_history": [
    {"quarter": "Q3FY2026", "promoter": 50.3, "fii": 23.1, "dii": 14.2}
  ],

  "technical": {
    "current_price": 1245.50,
    "rsi_14": 58.3,
    "sma_50": 1220.0,
    "sma_200": 1180.5,
    "macd_bullish": true,
    "golden_cross_active": true,
    "adx_trend_strength": "STRONG",
    "overall_bias": "BULLISH",
    // ... 30+ more fields
  },

  "risk": {
    "var_95_1d": -2.14,
    "max_drawdown": -18.5,
    "annualized_volatility": 22.3,
    "sharpe_ratio": 1.24,
    "sortino_ratio": 1.78,
    "risk_rating": "MODERATE"
  },

  "response_time_ms": 85.3,
  "cache_hit": false
}

curl -H "X-Internal-Key: isk_your_api_key_here" \
  https://investsights.in/api/internal/v1/screener/full/TCS

{
  "symbol": "TCS",
  "company_name": "Tata Consultancy Services",
  "sector": "Technology",
  "industry": "Information Technology Services",
  "market_cap": 1435200.0,
  "close_price": 3920.50,
  "pe_ratio": 31.2,
  "pb_ratio": 14.8,
  "roe": 47.5,
  "roce": 62.1,
  "revenue_growth_yoy": 5.8,
  "net_profit_margin": 19.2,
  "debt_to_equity": 0.05,
  "piotroski_score": 8,
  "altman_z_score": 12.5,
  "rs_rating": 75,
  // ... 150+ more fields
}

curl -H "X-Internal-Key: isk_your_api_key_here" \
  "https://investsights.in/api/internal/v1/stocks/ohlcv/INFY?days=10"

[
  {
    "date": "2026-03-11",
    "open": 1825.00,
    "high": 1842.50,
    "low": 1818.30,
    "close": 1835.75,
    "adj_close": 1835.75,
    "volume": 4523100
  },
  {
    "date": "2026-03-10",
    "open": 1810.00,
    "high": 1830.00,
    "low": 1805.50,
    "close": 1825.00,
    "adj_close": 1825.00,
    "volume": 3891200
  }
]

curl -H "X-Internal-Key: isk_your_api_key_here" \
  https://investsights.in/api/internal/v1/market/macro

{
  "fii_net_today_cr": -1250.3,
  "dii_net_today_cr": 1820.5,
  "fii_net_30d_cr": -18500.0,
  "dii_net_30d_cr": 22400.0,
  "fiidii_history": [
    {"date": "2026-03-11", "fii_net": -1250.3, "dii_net": 1820.5}
  ],
  "indices": {
    "nifty_50": {"close": 22450.5, "change_pct": 0.65, "trade_date": "2026-03-11"},
    "sensex": {"close": 73850.0, "change_pct": 0.58, "trade_date": "2026-03-11"}
  },
  "inr_usd": 83.25,
  "sectors": [
    {"sector": "Technology", "return_1w": 2.3, "rs_ratio": 105.2, "quadrant": "Leading"}
  ]
}

curl -H "X-Internal-Key: isk_your_api_key_here" \
  "https://investsights.in/api/internal/v1/stocks/peers/HDFCBANK?limit=5"

{
  "symbol": "HDFCBANK",
  "sector": "Financial Services",
  "target": {
    "symbol": "HDFCBANK",
    "company_name": "HDFC Bank Limited",
    "market_cap": 1150000.0,
    "pe_ratio": 19.5,
    "roe": 16.8,
    "debt_to_equity": 7.2
  },
  "peers": [
    {
      "symbol": "ICICIBANK",
      "company_name": "ICICI Bank Limited",
      "market_cap": 850000.0,
      "pe_ratio": 17.2,
      "roe": 18.1,
      "debt_to_equity": 6.8,
      "net_profit_margin": 28.5,
      "revenue_growth_yoy": 22.3,
      "close_price": 1285.50
    }
  ]
}

curl -H "X-Internal-Key: isk_your_api_key_here" \
  "https://investsights.in/api/internal/v1/news/agent/RELIANCE?limit=5"

[
  {
    "headline": "Reliance Jio adds 5 million subscribers in February",
    "published_at": "2026-03-10T14:30:00",
    "category": "sector",
    "sentiment": 0.72,
    "source": "Economic Times"
  },
  {
    "headline": "RIL to invest Rs 75,000 crore in green energy",
    "published_at": "2026-03-09T09:15:00",
    "category": "sector",
    "sentiment": 0.85,
    "source": "Moneycontrol"
  }
]

Quick Start (Python)

A complete Python example to pull data for any stock:

import requests

API_KEY = "isk_your_api_key_here"
BASE    = "https://investsights.in/api/internal/v1"
HEADERS = {"X-Internal-Key": API_KEY}

# 1. Get comprehensive stock data
resp = requests.post(
    f"{BASE}/agent-context/RELIANCE",
    json={
        "include_sections": ["fundamental", "technical", "risk", "macro", "news"],
        "price_days": 252,
    },
    headers=HEADERS,
)
data = resp.json()
print(f"PE Ratio: {data['fundamental']['pe_ratio']}")
print(f"RSI: {data['technical']['rsi_14']}")
print(f"Risk Rating: {data['risk']['risk_rating']}")

# 2. Get OHLCV history
prices = requests.get(
    f"{BASE}/stocks/ohlcv/RELIANCE?days=30",
    headers=HEADERS,
).json()
print(f"Latest close: {prices[0]['close']}")

# 3. Get sector peers
peers = requests.get(
    f"{BASE}/stocks/peers/RELIANCE?limit=5",
    headers=HEADERS,
).json()
for p in peers["peers"]:
    print(f"  {p['symbol']}: PE={p['pe_ratio']}, ROE={p['roe']}")

Support

For API key provisioning, rate limit increases, or technical questions:

• Email: [email protected]
• Website: investsights.in