{
  "openapi": "3.1.0",
  "info": {
    "title": "InvestX Public API",
    "version": "1.0.0",
    "description": "Read-only Indian equity research API for InvestX Alpha 20, breakout watchlist, stock screener, and fundamentals. No authentication required."
  },
  "servers": [{ "url": "https://investx.world" }],
  "paths": {
    "/api/v1/signals/momentum/portfolios": {
      "get": {
        "operationId": "getInvestxAlphaPortfolio",
        "summary": "InvestX Alpha 20 holdings",
        "description": "Latest InvestX Alpha 20 basket: 20 NSE stocks from the NIFTY 500 universe with symbol, sector, entry data. Pair with getInvestxAlphaPortfolioSummary for MTD/YTD.",
        "parameters": [
          {
            "name": "strategy",
            "in": "query",
            "schema": { "type": "string", "default": "monthly_rank_sum_momentum_n500" }
          },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1, "maximum": 2 } }
        ],
        "responses": {
          "200": {
            "description": "Portfolio blocks with symbols and as_of_date",
            "content": {
              "application/json": {
                "example": {
                  "strategy": "monthly_rank_sum_momentum_n500",
                  "as_of_date": "2026-07-01",
                  "portfolios": [{ "open_date": "2026-07-01", "symbols": [{ "symbol": "HFCL", "sector": "Technology" }] }]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/signals/momentum/summary": {
      "get": {
        "operationId": "getInvestxAlphaPortfolioSummary",
        "summary": "InvestX Alpha 20 MTD/YTD performance",
        "description": "Month-to-date and year-to-date returns for InvestX Alpha 20 vs NIFTY 500 benchmark.",
        "parameters": [
          {
            "name": "strategy",
            "in": "query",
            "schema": { "type": "string", "default": "monthly_rank_sum_momentum_n500" }
          }
        ],
        "responses": {
          "200": {
            "description": "Strategy and benchmark performance metrics",
            "content": {
              "application/json": {
                "example": {
                  "strategy": "monthly_rank_sum_momentum_n500",
                  "as_of_date": "2026-07-01",
                  "summary": { "strategy_mtd_pct": 2.69, "strategy_ytd_pct": 12.55, "benchmark_mtd_pct": 1.2, "benchmark_ytd_pct": 8.1 }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/signals/postgres/breakout-watchlist": {
      "get": {
        "operationId": "getBreakoutWatchlist",
        "summary": "InvestX Breakout Watchlist",
        "description": "Stocks flagged for potential breakout setups. Filter by open, candidate, closed, or all.",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": { "type": "string", "enum": ["open", "closed", "candidate", "all"], "default": "open" }
          },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 2000 } }
        ],
        "responses": {
          "200": {
            "description": "Breakout watchlist positions",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    },
    "/api/v1/equity/screen": {
      "get": {
        "operationId": "screenStocks",
        "summary": "Screen NSE stocks",
        "description": "Filter Indian equities by sector, RS rating (1-99), market cap, P/E, ROCE%, and profit growth%.",
        "parameters": [
          { "name": "sector", "in": "query", "schema": { "type": "string" } },
          { "name": "min_rs_rating", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 99 } },
          { "name": "max_rs_rating", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 99 } },
          { "name": "min_market_cap", "in": "query", "schema": { "type": "integer" } },
          { "name": "max_market_cap", "in": "query", "schema": { "type": "integer" } },
          { "name": "max_pe", "in": "query", "schema": { "type": "number" } },
          { "name": "min_roce_pct", "in": "query", "schema": { "type": "number" } },
          { "name": "min_profit_growth_pct", "in": "query", "schema": { "type": "number" } },
          {
            "name": "sort_by",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["rs_rating", "market_cap", "pe", "roce_pct", "profit_growth_pct"],
              "default": "rs_rating"
            }
          },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 } }
        ],
        "responses": {
          "200": {
            "description": "Ranked screener matches",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    },
    "/api/v1/equity/fundamentals-batch": {
      "get": {
        "operationId": "getStockFundamentals",
        "summary": "Batch stock fundamentals",
        "description": "P/E, market cap, ROCE%, and profit growth% for comma-separated NSE symbols.",
        "parameters": [
          {
            "name": "symbols",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "example": "HFCL,RELIANCE,TCS"
          }
        ],
        "responses": {
          "200": {
            "description": "Fundamentals per symbol",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    }
  }
}