{
  "openapi": "3.0.3",
  "info": {
    "title": "Mutual Fund API",
    "description": "API for accessing mutual fund data including NAV history, scheme information, and search functionality",
    "version": "1.0.0",
    "contact": {
      "name": "API Support",
      "url": "https://www.mfapi.in"
    }
  },
  "servers": [
    {
      "url": "https://api.mfapi.in",
      "description": "Production server"
    }
  ],
  "paths": {
    "/mf/search": {
      "get": {
        "summary": "Search mutual fund schemes",
        "description": "Search for mutual fund schemes by name using full-text search",
        "tags": ["Search"],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search query string",
            "schema": {
              "type": "string",
              "example": "HDFC"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with matching schemes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SchemeSearchResult"
                  }
                },
                "example": [
                  {
                    "schemeCode": 100119,
                    "schemeName": "HDFC Balanced Advantage Fund - Direct Plan - Growth"
                  },
                  {
                    "schemeCode": 100120,
                    "schemeName": "HDFC Banking and PSU Debt Fund - Direct Plan - Growth"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "Bad request - missing search query"
          }
        }
      }
    },
    "/mf": {
      "get": {
        "summary": "List all mutual fund schemes",
        "description": "Get a paginated list of all available mutual fund schemes with ISIN codes",
        "tags": ["Schemes"],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of results to return",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "example": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Number of results to skip for pagination",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0,
              "example": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with list of schemes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SchemeListItem"
                  }
                },
                "example": [
                  {
                    "schemeCode": 100119,
                    "schemeName": "HDFC Balanced Advantage Fund - Direct Plan - Growth",
                    "isinGrowth": "INF179K01BB2",
                    "isinDivReinvestment": "INF179K01BC0"
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/mf/{scheme_code}": {
      "get": {
        "summary": "Get NAV history for a scheme",
        "description": "Retrieve historical NAV data for a specific mutual fund scheme within a date range",
        "tags": ["NAV Data"],
        "parameters": [
          {
            "name": "scheme_code",
            "in": "path",
            "required": true,
            "description": "Unique scheme code",
            "schema": {
              "type": "integer",
              "example": 125497
            }
          },
          {
            "name": "startDate",
            "in": "query",
            "required": false,
            "description": "Start date for NAV history (ISO 8601 format)",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2023-01-01"
            }
          },
          {
            "name": "endDate",
            "in": "query",
            "required": false,
            "description": "End date for NAV history (ISO 8601 format)",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2023-12-31"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with NAV history",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NAVHistoryResponse"
                },
                "example": {
                  "meta": {
                    "fund_house": "HDFC Mutual Fund",
                    "scheme_type": "Open Ended Schemes",
                    "scheme_category": "Balanced Advantage Fund",
                    "scheme_code": 125497,
                    "scheme_name": "HDFC Balanced Advantage Fund - Direct Plan - Growth",
                    "isin_growth": "INF179K01BB2",
                    "isin_div_reinvestment": "INF179K01BC0"
                  },
                  "data": [
                    {
                      "date": "31-12-2023",
                      "nav": "45.12300"
                    },
                    {
                      "date": "30-12-2023",
                      "nav": "45.00100"
                    }
                  ],
                  "status": "SUCCESS"
                }
              }
            }
          },
          "404": {
            "description": "Scheme not found"
          }
        }
      }
    },
    "/mf/{scheme_code}/latest": {
      "get": {
        "summary": "Get latest NAV for a scheme",
        "description": "Retrieve the most recent NAV data for a specific mutual fund scheme",
        "tags": ["NAV Data"],
        "parameters": [
          {
            "name": "scheme_code",
            "in": "path",
            "required": true,
            "description": "Unique scheme code",
            "schema": {
              "type": "integer",
              "example": 125497
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with latest NAV",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NAVHistoryResponse"
                },
                "example": {
                  "meta": {
                    "fund_house": "HDFC Mutual Fund",
                    "scheme_type": "Open Ended Schemes",
                    "scheme_category": "Balanced Advantage Fund",
                    "scheme_code": 125497,
                    "scheme_name": "HDFC Balanced Advantage Fund - Direct Plan - Growth",
                    "isin_growth": "INF179K01BB2",
                    "isin_div_reinvestment": "INF179K01BC0"
                  },
                  "data": [
                    {
                      "date": "26-10-2024",
                      "nav": "48.56700"
                    }
                  ],
                  "status": "SUCCESS"
                }
              }
            }
          },
          "404": {
            "description": "Scheme not found"
          }
        }
      }
    },
    "/mf/latest": {
      "get": {
        "summary": "Get latest NAV for all schemes",
        "description": "Retrieve the most recent NAV data for all mutual fund schemes. Returns complete dataset from cache.",
        "tags": ["NAV Data"],
        "responses": {
          "200": {
            "description": "Successful response with latest NAV data for all schemes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/LatestNAVItem"
                  }
                },
                "example": [
                  {
                    "schemeCode": 125497,
                    "schemeName": "HDFC Balanced Advantage Fund - Direct Plan - Growth",
                    "fundHouse": "HDFC Mutual Fund",
                    "schemeType": "Open Ended Schemes",
                    "schemeCategory": "Balanced Advantage Fund",
                    "isinGrowth": "INF179K01BB2",
                    "isinDivReinvestment": "INF179K01BC0",
                    "nav": "48.56700",
                    "date": "26-10-2024"
                  },
                  {
                    "schemeCode": 100119,
                    "schemeName": "HDFC Banking and PSU Debt Fund - Direct Plan - Growth",
                    "fundHouse": "HDFC Mutual Fund",
                    "schemeType": "Open Ended Schemes",
                    "schemeCategory": "Debt Scheme - Banking and PSU Fund",
                    "isinGrowth": "INF179K01XY9",
                    "isinDivReinvestment": null,
                    "nav": "15.23400",
                    "date": "26-10-2024"
                  }
                ]
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SchemeSearchResult": {
        "type": "object",
        "properties": {
          "schemeCode": {
            "type": "integer",
            "description": "Unique identifier for the scheme"
          },
          "schemeName": {
            "type": "string",
            "description": "Full name of the mutual fund scheme"
          }
        },
        "required": ["schemeCode", "schemeName"]
      },
      "SchemeListItem": {
        "type": "object",
        "properties": {
          "schemeCode": {
            "type": "integer",
            "description": "Unique identifier for the scheme"
          },
          "schemeName": {
            "type": "string",
            "description": "Full name of the mutual fund scheme"
          },
          "isinGrowth": {
            "type": "string",
            "nullable": true,
            "description": "ISIN code for growth option"
          },
          "isinDivReinvestment": {
            "type": "string",
            "nullable": true,
            "description": "ISIN code for dividend reinvestment option"
          }
        },
        "required": ["schemeCode", "schemeName"]
      },
      "NAVData": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "description": "Date in DD-MM-YYYY format"
          },
          "nav": {
            "type": "string",
            "description": "Net Asset Value with 5 decimal precision"
          }
        },
        "required": ["date", "nav"]
      },
      "SchemeMeta": {
        "type": "object",
        "properties": {
          "fund_house": {
            "type": "string",
            "description": "Name of the fund house"
          },
          "scheme_type": {
            "type": "string",
            "description": "Type of the scheme (e.g., Open Ended Schemes)"
          },
          "scheme_category": {
            "type": "string",
            "description": "Category of the scheme"
          },
          "scheme_code": {
            "type": "integer",
            "description": "Unique identifier for the scheme"
          },
          "scheme_name": {
            "type": "string",
            "description": "Full name of the mutual fund scheme"
          },
          "isin_growth": {
            "type": "string",
            "nullable": true,
            "description": "ISIN code for growth option"
          },
          "isin_div_reinvestment": {
            "type": "string",
            "nullable": true,
            "description": "ISIN code for dividend reinvestment option"
          }
        },
        "required": ["scheme_code", "scheme_name"]
      },
      "NAVHistoryResponse": {
        "type": "object",
        "properties": {
          "meta": {
            "$ref": "#/components/schemas/SchemeMeta"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NAVData"
            }
          },
          "status": {
            "type": "string",
            "enum": ["SUCCESS", "ERROR"],
            "description": "Response status"
          }
        },
        "required": ["meta", "data", "status"]
      },
      "LatestNAVItem": {
        "type": "object",
        "properties": {
          "schemeCode": {
            "type": "integer",
            "description": "Unique identifier for the scheme"
          },
          "schemeName": {
            "type": "string",
            "description": "Full name of the mutual fund scheme"
          },
          "fundHouse": {
            "type": "string",
            "description": "Name of the fund house"
          },
          "schemeType": {
            "type": "string",
            "description": "Type of the scheme (e.g., Open Ended Schemes)"
          },
          "schemeCategory": {
            "type": "string",
            "description": "Category of the scheme"
          },
          "isinGrowth": {
            "type": "string",
            "nullable": true,
            "description": "ISIN code for growth option"
          },
          "isinDivReinvestment": {
            "type": "string",
            "nullable": true,
            "description": "ISIN code for dividend reinvestment option"
          },
          "nav": {
            "type": "string",
            "description": "Latest Net Asset Value with 5 decimal precision"
          },
          "date": {
            "type": "string",
            "description": "NAV date in DD-MM-YYYY format"
          }
        },
        "required": ["schemeCode", "schemeName", "nav", "date"]
      }
    }
  },
  "tags": [
    {
      "name": "Search",
      "description": "Search operations for mutual fund schemes"
    },
    {
      "name": "Schemes",
      "description": "Operations related to mutual fund schemes listing"
    },
    {
      "name": "NAV Data",
      "description": "Operations for retrieving NAV (Net Asset Value) data"
    }
  ]
}