{
  "openapi": "3.1.0",
  "info": {
    "title": "Davide Portfolio Data API",
    "version": "1.0.0",
    "description": "Read-only endpoints for current holdings and portfolio or asset history. All portfolio totals use CAD as the base currency."
  },
  "servers": [
    { "url": "https://pf.dav77h.com", "description": "Production" }
  ],
  "paths": {
    "/api/portfolio": {
      "get": {
        "operationId": "getCurrentPortfolio",
        "summary": "Get current portfolio holdings and totals",
        "parameters": [
          { "$ref": "#/components/parameters/Boost" }
        ],
        "responses": {
          "200": {
            "description": "Current holdings ranked by portfolio weight",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PortfolioResponse" }
              }
            }
          }
        }
      }
    },
    "/api/history": {
      "get": {
        "operationId": "getPortfolioHistory",
        "summary": "Get portfolio value history for a standard timeframe",
        "parameters": [
          { "$ref": "#/components/parameters/Range" },
          { "$ref": "#/components/parameters/Boost" }
        ],
        "responses": {
          "200": {
            "description": "Portfolio history and period summary",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HistoryResponse" }
              }
            }
          }
        }
      }
    },
    "/api/asset-history": {
      "get": {
        "operationId": "getAssetHistory",
        "summary": "Get value and price history for one current position",
        "parameters": [
          { "name": "ticker", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Ticker exactly as returned by /api/portfolio" },
          { "name": "currency", "in": "query", "required": true, "schema": { "type": "string", "enum": ["CAD", "USD"] } },
          { "$ref": "#/components/parameters/Range" },
          { "$ref": "#/components/parameters/Boost" }
        ],
        "responses": {
          "200": {
            "description": "Asset history and period summary",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AssetHistoryResponse" }
              }
            }
          },
          "404": { "description": "Position not found" }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Range": {
        "name": "range",
        "in": "query",
        "required": false,
        "schema": { "type": "string", "enum": ["1d", "1w", "1m", "3m", "6m", "ytd", "1y", "5y", "max"], "default": "1d" }
      },
      "Boost": {
        "name": "boost",
        "in": "query",
        "required": false,
        "description": "Hypothetical percentage adjustment applied to all non-cash quantities. Does not mutate stored holdings.",
        "schema": { "type": "number", "minimum": -100, "default": 0 }
      }
    },
    "schemas": {
      "Position": {
        "type": "object",
        "required": ["ticker", "qty", "currency", "price", "valCAD", "gCAD", "weight"],
        "properties": {
          "ticker": { "type": "string" },
          "qty": { "type": "number" },
          "currency": { "type": "string", "enum": ["CAD", "USD"] },
          "price": { "type": "number" },
          "previousClose": { "type": ["number", "null"] },
          "nativeValue": { "type": "number" },
          "valCAD": { "type": "number" },
          "gCAD": { "type": "number" },
          "dayPctCAD": { "type": "number" },
          "weight": { "type": "number" },
          "error": { "type": ["string", "null"] }
        }
      },
      "HistoryPoint": {
        "type": "object",
        "required": ["date", "totalCAD"],
        "properties": {
          "date": { "type": "string" },
          "label": { "type": "string" },
          "fullLabel": { "type": "string" },
          "totalCAD": { "type": "number" },
          "missingCount": { "type": "integer" },
          "isLive": { "type": "boolean" },
          "isPreviousClose": { "type": "boolean" }
        }
      },
      "PeriodSummary": {
        "type": ["object", "null"],
        "properties": {
          "startDate": { "type": "string" },
          "endDate": { "type": "string" },
          "startValueCAD": { "type": "number" },
          "endValueCAD": { "type": "number" },
          "gainCAD": { "type": "number" },
          "gainPct": { "type": "number" }
        }
      },
      "PortfolioResponse": {
        "type": "object",
        "required": ["portfolio", "totals", "gains", "fx", "timestamp"],
        "properties": {
          "portfolio": { "type": "array", "items": { "$ref": "#/components/schemas/Position" } },
          "totals": { "type": "object", "properties": { "CAD": { "type": "number" } } },
          "gains": { "type": "object", "properties": { "CAD": { "type": "number" }, "pct": { "type": "number" }, "previousTotalCAD": { "type": "number" } } },
          "fx": { "type": "object", "properties": { "USD_TO_CAD": { "type": "number" }, "PREVIOUS_USD_TO_CAD": { "type": "number" } } },
          "priceSource": { "type": "string" },
          "priceTimestamp": { "type": ["string", "null"] },
          "boostPct": { "type": "number" },
          "timestamp": { "type": "string" }
        }
      },
      "HistoryResponse": {
        "type": "object",
        "required": ["mode", "range", "points", "summary", "series"],
        "properties": {
          "mode": { "type": "string" },
          "range": { "type": "string" },
          "startDate": { "type": "string" },
          "snapshotDate": { "type": "string" },
          "points": { "type": "integer" },
          "summary": { "$ref": "#/components/schemas/PeriodSummary" },
          "series": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryPoint" } }
        }
      },
      "AssetHistoryResponse": {
        "allOf": [
          { "$ref": "#/components/schemas/HistoryResponse" },
          {
            "type": "object",
            "properties": {
              "ticker": { "type": "string" },
              "currency": { "type": "string" },
              "qty": { "type": "number" }
            }
          }
        ]
      }
    }
  }
}