{
  "openapi": "3.0.3",
  "info": {
    "title": "IndexLovers Sovereign Fiscal Quality Index (SFQI-40) API",
    "version": "1.0.0",
    "description": "Institutional REST API providing systematic macroeconomic fundamentals, Fiscal Quality Scores (FQS), and debt-vs-discipline delta rebalancing weights across 40 major economies.",
    "contact": {
      "name": "IndexLovers Quantitative Research",
      "url": "https://indexlovers.com/indices/sovereign-fiscal-quality"
    }
  },
  "servers": [
    {
      "url": "https://indexlovers.com",
      "description": "Production API"
    }
  ],
  "paths": {
    "/v1/indices/sovereign-fiscal-quality": {
      "get": {
        "summary": "SFQI-40 Index Overview & Core Metrics",
        "description": "Returns aggregate portfolio metrics, weighted average yield, aggregate maturity duration, and top 5 overweight/underweight positions vs traditional debt-weighted benchmark.",
        "responses": {
          "200": {
            "description": "Successful index overview response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SFQISummary"
                }
              }
            }
          }
        }
      }
    },
    "/v1/indices/sovereign-fiscal-quality/constituents": {
      "get": {
        "summary": "SFQI-40 Sovereign Constituents & Scores",
        "description": "Returns array of 40 sovereign constituents with complete macroeconomic metrics, FQS scores, debt-to-revenue ratios, yields, and delta allocations.",
        "parameters": [
          {
            "name": "bucket",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "developed",
                "emerging"
              ],
              "default": "all"
            },
            "description": "Filter constituents by regional development bucket."
          },
          {
            "name": "sort_by",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "fqs",
                "weight_delta",
                "dsb",
                "weight"
              ],
              "default": "fqs"
            },
            "description": "Sort order of constituents."
          }
        ],
        "responses": {
          "200": {
            "description": "List of sovereign constituents",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SFQIConstituent"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/indices/sovereign-fiscal-quality/history": {
      "get": {
        "summary": "SFQI-40 Historical Backtest & Tracking Error",
        "description": "Daily historical time-series comparing SFQI-40 cumulative total return, drawdowns, and tracking spread against the Debt-Weighted Sovereign 40 Benchmark.",
        "parameters": [
          {
            "name": "range",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1M",
                "6M",
                "1Y",
                "3Y",
                "5Y",
                "10Y",
                "MAX"
              ],
              "default": "MAX"
            },
            "description": "Time horizon slice."
          }
        ],
        "responses": {
          "200": {
            "description": "Historical daily time-series array",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SFQITimeseriesPoint"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SFQISummary": {
        "type": "object",
        "properties": {
          "index_id": {
            "type": "string"
          },
          "ticker": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "benchmark_name": {
            "type": "string"
          },
          "benchmark_description": {
            "type": "string"
          },
          "benchmark_formula": {
            "type": "string"
          },
          "benchmark_source": {
            "type": "string"
          },
          "latest_value": {
            "type": "number"
          },
          "benchmark_latest_value": {
            "type": "number"
          },
          "performance_spread_pct": {
            "type": "number"
          },
          "weighted_avg_yield_10y": {
            "type": "number"
          },
          "bench_weighted_avg_yield_10y": {
            "type": "number"
          },
          "weighted_duration_years": {
            "type": "number"
          },
          "bench_weighted_duration_years": {
            "type": "number"
          },
          "top_overweights_vs_bench": {
            "type": "array"
          },
          "top_underweights_vs_bench": {
            "type": "array"
          }
        }
      },
      "SFQIConstituent": {
        "type": "object",
        "properties": {
          "iso_code": {
            "type": "string"
          },
          "country_name": {
            "type": "string"
          },
          "bucket": {
            "type": "string",
            "enum": [
              "developed",
              "emerging"
            ]
          },
          "fqs_score": {
            "type": "number"
          },
          "tier": {
            "type": "string"
          },
          "benchmark_weight_pct": {
            "type": "number"
          },
          "sfqi_weight_pct": {
            "type": "number"
          },
          "delta_pct": {
            "type": "number"
          },
          "interest_to_revenue_pct": {
            "type": "number"
          },
          "primary_balance_pct": {
            "type": "number"
          },
          "yield_10y": {
            "type": "number"
          },
          "duration_years": {
            "type": "number"
          }
        }
      },
      "SFQITimeseriesPoint": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "sfqi_value": {
            "type": "number"
          },
          "benchmark_value": {
            "type": "number"
          },
          "cumulative_spread_pct": {
            "type": "number"
          },
          "sfqi_drawdown_pct": {
            "type": "number"
          },
          "benchmark_drawdown_pct": {
            "type": "number"
          }
        }
      }
    }
  }
}