openapi: 3.1.0
info:
  title: FII/DII Activity API
  version: 0.3.0
  description: >-
    Daily FII (Foreign Institutional Investors) and DII (Domestic Institutional
    Investors) net buy/sell activity for Indian equity markets. Scraped from NSE,
    Groww, and Moneycontrol by GitHub Actions and served as static JSON. All
    monetary values are in INR crores. No authentication required.


    The canonical host is GitHub Pages; the other servers are equivalent mirrors
    of the same committed data.
  license:
    name: MIT
    url: https://github.com/chirag127/fii-dii-activity-api/blob/main/LICENSE
  contact:
    name: FII/DII Activity API
    url: https://github.com/chirag127/fii-dii-activity-api

servers:
  - url: https://chirag127.github.io/fii-dii-activity-api/data
    description: GitHub Pages (canonical — never expires)
  - url: https://raw.githubusercontent.com/chirag127/fii-dii-activity-api/main/data
    description: raw.githubusercontent.com (mirror, no Pages dependency)
  - url: https://cdn.jsdelivr.net/gh/chirag127/fii-dii-activity-api@main/data
    description: jsDelivr CDN (mirror, cached/fast)
  - url: https://cdn.statically.io/gh/chirag127/fii-dii-activity-api/main/data
    description: Statically CDN (mirror)

paths:
  /latest.json:
    get:
      operationId: getLatest
      summary: Most recent FII/DII scrape
      description: Returns the newest available daily FII/DII activity payload.
      tags: [activity]
      responses:
        "200":
          description: The most recent daily payload.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Payload"
              examples:
                sample:
                  $ref: "#/components/examples/PayloadExample"

  /{date}.json:
    get:
      operationId: getByDate
      summary: FII/DII activity for a specific day
      description: >-
        Returns the daily FII/DII activity payload for a given date. Dates use
        `YYYY-MM-DD`. Only trading days on which a scrape ran are available;
        unknown dates return 404.
      tags: [activity]
      parameters:
        - name: date
          in: path
          required: true
          description: Trading date in ISO `YYYY-MM-DD` form.
          schema:
            type: string
            pattern: "^\\d{4}-\\d{2}-\\d{2}$"
          example: "2026-07-21"
      responses:
        "200":
          description: The daily payload for the requested date.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Payload"
              examples:
                sample:
                  $ref: "#/components/examples/PayloadExample"
        "404":
          description: No data for that date (non-trading day or before coverage began).

components:
  schemas:
    Block:
      type: object
      description: One institutional activity block. All values are INR crores.
      required: [fii_buy, fii_sell, fii_net, dii_buy, dii_sell, dii_net]
      additionalProperties: false
      properties:
        fii_buy: { type: number, description: FII gross buy (INR cr). }
        fii_sell: { type: number, description: FII gross sell (INR cr). }
        fii_net: { type: number, description: FII net (buy − sell; negative = net selling). }
        dii_buy: { type: number, description: DII gross buy (INR cr). }
        dii_sell: { type: number, description: DII gross sell (INR cr). }
        dii_net: { type: number, description: DII net (buy − sell; negative = net selling). }
    Payload:
      type: object
      required: [date, source, equity, derivative]
      additionalProperties: false
      properties:
        date:
          type: string
          pattern: "^\\d{4}-\\d{2}-\\d{2}$"
          description: Trading date (ISO `YYYY-MM-DD`).
        source:
          type: string
          enum: [nse, groww, moneycontrol, placeholder]
          description: >-
            Data origin. `nse` = NSE official API, `groww` = Groww server-rendered
            cash data (primary working source), `moneycontrol` = fallback scrape,
            `placeholder` = all upstreams failed (all zeros).
        equity:
          $ref: "#/components/schemas/Block"
        derivative:
          $ref: "#/components/schemas/Block"
          description: >-
            Derivatives (F&O) block. Currently always zero — the NSE fiidii
            endpoint provides Capital Market (cash) data only.
  examples:
    PayloadExample:
      summary: A day with real NSE data
      value:
        date: "2026-07-21"
        source: nse
        equity:
          fii_buy: 5917.71
          fii_sell: 5004.12
          fii_net: 913.59
          dii_buy: 6440.88
          dii_sell: 5165.66
          dii_net: 1275.22
        derivative:
          fii_buy: 0
          fii_sell: 0
          fii_net: 0
          dii_buy: 0
          dii_sell: 0
          dii_net: 0