openapi: 3.0.3
info:
  title: YONEPSE Static Data API
  version: 1.0.0
  description: |
    Developer-facing OpenAPI spec for the published YONEPSE JSON datasets.

    This API is static-file based and served from GitHub Pages. Data is refreshed
    by GitHub Actions schedules.

    Endpoint migration notice:
    New folder-based endpoints are canonical. Legacy endpoint paths are supported
    for six months, until November 18, 2026, and will be removed after that date.
    Please update integrations to the new endpoint paths during this support window.

    Quick start:
    1. Fetch `/data/market/status.json` to understand market state.
    2. Fetch `/data/nepse_data.json` for the main ticker feed.
    3. Optionally fetch `/data/OMF.json` for full open-ended mutual fund NAV detail.
    4. Fetch `/data/ltp/manifest.json`, monthly shards for daily LTP history,
       and daily shards for intraday LTP snapshots.
    5. Use `/data/proposed_dividend/latest_1y.json` and `/data/ipo/upcoming.json`
       for corporate action style datasets.

    Notes:
    - No authentication required.
    - Responses are JSON files, so pagination/filtering is done client-side.
    - `nepse_data.json` may contain mapped OMF entries marked with
      `asset_type: open_ended_mutual_fund`.
servers:
  - url: https://shubhamnpk.github.io/yonepse
    description: GitHub Pages (recommended)
tags:
  - name: Market
  - name: Mutual Funds
  - name: IPO
  - name: Dividends
  - name: Notices
  - name: Reference
paths:
  /data/market/status.json:
    get:
      tags: [Market]
      summary: Market open/closed status
      operationId: getMarketStatus
      responses:
        '200':
          description: Current market status snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketStatus'
              example:
                is_open: false
                last_checked: "2026-03-27T14:05:27.294832"

  /data/nepse_data.json:
    get:
      tags: [Market]
      summary: Main market dataset
      description: |
        Aggregated market rows with one item per symbol.
        Includes mapped OMF entries when available.
      operationId: getNepseData
      responses:
        '200':
          description: Array of market rows
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NepseDataRow'

  /data/OMF.json:
    get:
      tags: [Mutual Funds]
      summary: Open-ended mutual fund NAV dataset
      operationId: getOpenEndedMutualFundData
      responses:
        '200':
          description: Array of open-ended mutual fund rows
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OmfRow'

  /data/market/indices.json:
    get:
      tags: [Market]
      summary: Main NEPSE indices
      operationId: getIndices
      responses:
        '200':
          description: Index data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObjectArray'

  /data/market/sector_indices.json:
    get:
      tags: [Market]
      summary: Sector-wise indices
      operationId: getSectorIndices
      responses:
        '200':
          description: Sector index data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObjectArray'

  /data/market/top_stocks.json:
    get:
      tags: [Market]
      summary: Top movers and activity buckets
      operationId: getTopStocks
      responses:
        '200':
          description: Top gainer/loser/turnover/trade/transaction buckets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopStocks'

  /data/market/summary.json:
    get:
      tags: [Market]
      summary: Latest market summary
      operationId: getMarketSummary
      responses:
        '200':
          description: Market summary object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'

  /data/market/history.json:
    get:
      tags: [Market]
      summary: Historical market summary
      operationId: getMarketSummaryHistory
      responses:
        '200':
          description: Historical market summary rows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObjectArray'

  /data/market/live.json:
    get:
      tags: [Market]
      summary: Live market rows
      description: Alias dataset containing the same current market rows as `/data/nepse_data.json`.
      operationId: getMarketLive
      responses:
        '200':
          description: Array of current market rows
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NepseDataRow'

  /data/ltp/manifest.json:
    get:
      tags: [Market]
      summary: LTP history manifest
      operationId: getLtpHistoryManifest
      responses:
        '200':
          description: Available monthly and daily LTP history shards
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LtpHistoryManifest'

  /data/ltp/monthly/{month}.json:
    get:
      tags: [Market]
      summary: Monthly daily LTP history shard
      operationId: getMonthlyLtpHistory
      parameters:
        - name: month
          in: path
          required: true
          description: Month in YYYY-MM format.
          schema:
            type: string
            pattern: '^\d{4}-\d{2}$'
          example: "2026-05"
      responses:
        '200':
          description: Sparse per-symbol daily LTP, volume, turnover, and trades history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LtpHistoryMonth'

  /data/ltp/daily/{date}.json:
    get:
      tags: [Market]
      summary: Daily intraday LTP history shard
      operationId: getDailyIntradayLtpHistory
      parameters:
        - name: date
          in: path
          required: true
          description: Trading date in YYYY-MM-DD format.
          schema:
            type: string
            pattern: '^\d{4}-\d{2}-\d{2}$'
          example: "2026-05-20"
      responses:
        '200':
          description: Sparse per-symbol intraday LTP, volume, turnover, and trades snapshots
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LtpHistoryDay'

  /data/market/supply_demand.json:
    get:
      tags: [Market]
      summary: Supply and demand snapshot
      operationId: getSupplyDemand
      responses:
        '200':
          description: Supply and demand object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'

  /data/ipo/upcoming.json:
    get:
      tags: [IPO]
      summary: Active/recent upcoming IPO records
      operationId: getUpcomingIpo
      responses:
        '200':
          description: Upcoming IPO records
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UpcomingIpoRow'

  /data/ipo/old.json:
    get:
      tags: [IPO]
      summary: Archived IPO history
      operationId: getOldIpo
      responses:
        '200':
          description: Archived IPO rows
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UpcomingIpoRow'

  /data/proposed_dividend/latest_1y.json:
    get:
      tags: [Dividends]
      summary: Latest 1-year proposed dividends
      operationId: getProposedDividendLatest1y
      responses:
        '200':
          description: Latest proposed dividend rows
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProposedDividendRow'

  /data/proposed_dividend/history_all_years.json:
    get:
      tags: [Dividends]
      summary: All-years proposed dividend history
      operationId: getProposedDividendHistoryAllYears
      responses:
        '200':
          description: Historical proposed dividend rows
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProposedDividendRow'

  /data/proposed_dividend/meta.json:
    get:
      tags: [Dividends]
      summary: Proposed dividend scraper metadata
      operationId: getProposedDividendMeta
      responses:
        '200':
          description: Last run metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProposedDividendMeta'

  /data/notify/notices.json:
    get:
      tags: [Notices]
      summary: General notices bundle
      operationId: getNotices
      responses:
        '200':
          description: Notice object with `general` list and metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoticesResponse'

  /data/notify/disclosures.json:
    get:
      tags: [Notices]
      summary: Company disclosures
      operationId: getDisclosures
      responses:
        '200':
          description: Disclosure rows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObjectArray'

  /data/notify/exchange_messages.json:
    get:
      tags: [Notices]
      summary: Exchange messages
      operationId: getExchangeMessages
      responses:
        '200':
          description: Exchange message rows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObjectArray'

  /data/other/brokers.json:
    get:
      tags: [Reference]
      summary: Broker directory
      operationId: getBrokers
      responses:
        '200':
          description: Broker rows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObjectArray'

  /data/other/securities.json:
    get:
      tags: [Reference]
      summary: Full securities list
      operationId: getAllSecurities
      responses:
        '200':
          description: Securities metadata rows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObjectArray'

  /data/company/financials.json:
    get:
      tags: [Reference]
      summary: Company financial reports
      operationId: getCompanyFinancials
      responses:
        '200':
          description: Financial report rows grouped by company
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObjectArray'

  /data/company/profiles.json:
    get:
      tags: [Reference]
      summary: Company profiles
      operationId: getCompanyProfiles
      responses:
        '200':
          description: Brief company profiles and contact facts from NEPSE
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObjectArray'

  /data/company/metadata.json:
    get:
      tags: [Reference]
      summary: Company financial metadata
      operationId: getCompanyFinancialMetadata
      responses:
        '200':
          description: Metadata for company financial reports
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /data/company/field_descriptions.json:
    get:
      tags: [Reference]
      summary: Company financial field descriptions
      operationId: getCompanyFinancialFieldDescriptions
      responses:
        '200':
          description: Full forms and descriptions for financial fields
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /data/other/sector_codes.json:
    get:
      tags: [Reference]
      summary: Sector-to-symbol mapping
      operationId: getSectorWiseCodes
      responses:
        '200':
          description: Sector map object
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: object
                    properties:
                      symbol:
                        type: string
                      name:
                        type: string

components:
  schemas:
    GenericObject:
      type: object
      additionalProperties: true

    GenericObjectArray:
      type: array
      items:
        type: object
        additionalProperties: true

    LtpHistoryManifest:
      type: object
      required:
        - version
        - latestDate
        - availableMonths
        - retention
      properties:
        version:
          type: integer
          example: 1
        latestDate:
          type: string
          example: "2026-05-18"
        availableMonths:
          type: array
          items:
            type: string
          example: ["2026-05"]
        availableDays:
          type: array
          items:
            type: string
          example: ["2026-05-20"]
        retention:
          type: string
          example: "no-limit"

    LtpHistoryMonth:
      type: object
      required:
        - version
        - market
        - currency
        - month
        - updatedAt
        - dates
        - columns
        - series
      properties:
        version:
          type: integer
          example: 1
        market:
          type: string
          example: NEPSE
        currency:
          type: string
          example: NPR
        month:
          type: string
          example: "2026-05"
        updatedAt:
          type: string
          example: "2026-05-18T19:23:40+05:45"
        dates:
          type: array
          items:
            type: string
          example: ["2026-05-18"]
        columns:
          type: array
          items:
            type: string
          example: ["dateIndex", "ltp", "volume", "turnover", "trades"]
        series:
          type: object
          additionalProperties:
            type: array
            items:
              type: array
              items:
                type: number
          description: Symbol-keyed sparse rows. Row values follow `columns`; `dateIndex` references `dates`.
          example:
            NABIL:
              - [0, 526, 44305, 23313421.6, 463]

    LtpHistoryDay:
      type: object
      required:
        - version
        - market
        - currency
        - date
        - updatedAt
        - times
        - columns
        - series
      properties:
        version:
          type: integer
          example: 1
        market:
          type: string
          example: NEPSE
        currency:
          type: string
          example: NPR
        date:
          type: string
          example: "2026-05-20"
        updatedAt:
          type: string
          example: "2026-05-20T13:30:00+05:45"
        times:
          type: array
          items:
            type: string
          example: ["11:00", "11:30", "12:00"]
        columns:
          type: array
          items:
            type: string
          example: ["timeIndex", "ltp", "volume", "turnover", "trades"]
        series:
          type: object
          additionalProperties:
            type: array
            items:
              type: array
              items:
                type: number
          description: Symbol-keyed sparse rows. Row values follow `columns`; `timeIndex` references `times`.
          example:
            NABIL:
              - [0, 526, 44305, 23313421.6, 463]
              - [1, 528, 51840, 27371520, 512]

    MarketStatus:
      type: object
      required:
        - is_open
        - last_checked
      properties:
        is_open:
          type: boolean
        last_checked:
          type: string

    NepseDataRow:
      type: object
      required:
        - symbol
        - name
      properties:
        symbol:
          type: string
        name:
          type: string
        ltp:
          type: number
          nullable: true
        previous_close:
          type: number
          nullable: true
        change:
          type: number
          nullable: true
        percent_change:
          type: number
          nullable: true
        high:
          type: number
          nullable: true
        low:
          type: number
          nullable: true
        volume:
          type: integer
          nullable: true
        turnover:
          type: number
          nullable: true
        trades:
          type: integer
          nullable: true
        last_updated:
          type: string
          nullable: true
        market_cap:
          type: number
          nullable: true
        asset_type:
          type: string
          nullable: true
          description: Present on mapped OMF rows.
          enum:
            - open_ended_mutual_fund

    OmfRow:
      type: object
      required:
        - symbol
        - fund_name
      properties:
        company_id:
          type: integer
          nullable: true
        symbol:
          type: string
        fund_name:
          type: string
        fund_size:
          type: integer
          nullable: true
        daily_nav:
          type: number
          nullable: true
        daily_nav_date:
          type: string
          nullable: true
        weekly_nav:
          type: number
          nullable: true
        weekly_nav_date:
          type: string
          nullable: true
        monthly_nav:
          type: number
          nullable: true
        monthly_nav_date:
          type: string
          nullable: true
        ltp:
          type: number
          nullable: true
        price_as_of:
          type: string
          nullable: true
        premium_discount_percent:
          type: number
          nullable: true
        refund_nav:
          type: number
          nullable: true
        scraped_at:
          type: string

    UpcomingIpoRow:
      type: object
      properties:
        company:
          type: string
        units:
          type: string
        date_range:
          type: string
        announcement_date:
          type: string
        full_text:
          type: string
        url:
          type: string
        is_reserved_share:
          type: boolean
        reserved_for:
          type: string
        scraped_at:
          type: string

    ProposedDividendRow:
      type: object
      properties:
        id:
          type: integer
        symbol:
          type: string
        company_name:
          type: string
        bonus_share:
          type: string
        cash_dividend:
          type: string
        total_dividend:
          type: string
        announcement_date:
          type: string
        bookclose_date:
          type: string
        distribution_date:
          type: string
        bonus_listing_date:
          type: string
        fiscal_year:
          type: string
        ltp:
          type: string
        price_as_of:
          type: string
        scraped_at:
          type: string

    ProposedDividendMeta:
      type: object
      properties:
        last_run_at:
          type: string
        mode:
          type: string
        latest_count:
          type: integer
        history_count:
          type: integer
        smoke_passed:
          type: boolean

    TopStocks:
      type: object
      properties:
        top_gainer:
          $ref: '#/components/schemas/GenericObjectArray'
        top_loser:
          $ref: '#/components/schemas/GenericObjectArray'
        top_turnover:
          $ref: '#/components/schemas/GenericObjectArray'
        top_trade:
          $ref: '#/components/schemas/GenericObjectArray'
        top_transaction:
          $ref: '#/components/schemas/GenericObjectArray'

    NoticesResponse:
      type: object
      properties:
        general:
          $ref: '#/components/schemas/GenericObjectArray'
        last_updated:
          type: string