{
  "openapi": "3.1.0",
  "info": {
    "title": "Silk API",
    "description": "Scores an investment portfolio for crash resilience. Send holdings with weights; get back a resilience score from 0 to 100, five subscores, the portfolio's return in two historical crash windows and how much of the portfolio could be scored. Nothing about a request is stored.",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.aegoralabs.de"
    }
  ],
  "paths": {
    "/v1/analysis": {
      "post": {
        "summary": "Score a portfolio",
        "description": "Scores the submitted holdings: the resilience score from 0 to 100 (higher is better), five subscores, the portfolio's return in two historical crash windows, the metrics behind them and how much of the portfolio could be scored. Safe to retry: nothing is stored.",
        "operationId": "analyse",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnalysisRequest"
              },
              "examples": {
                "standard": {
                  "summary": "Five holdings, one excluded",
                  "value": {
                    "holdings": [
                      {
                        "identifier": "AAPL.XNAS",
                        "identifier_type": "symbol",
                        "weight": 0.4
                      },
                      {
                        "identifier": "SAP.XETR",
                        "identifier_type": "symbol",
                        "weight": 0.35
                      },
                      {
                        "identifier": "IWDA.XAMS",
                        "identifier_type": "symbol",
                        "weight": 0.14
                      },
                      {
                        "identifier": "XAU.COMMODITY",
                        "identifier_type": "symbol",
                        "weight": 0.03
                      },
                      {
                        "identifier": "NEWCO.XNAS",
                        "identifier_type": "symbol",
                        "weight": 0.08
                      }
                    ],
                    "currency": "EUR"
                  }
                },
                "edgeCase": {
                  "summary": "A fund without holdings data",
                  "value": {
                    "holdings": [
                      {
                        "identifier": "AAPL.XNAS",
                        "identifier_type": "symbol",
                        "weight": 0.5
                      },
                      {
                        "identifier": "NEWFUND.XETR",
                        "identifier_type": "symbol",
                        "weight": 0.2
                      },
                      {
                        "identifier": "ETH.CRYPTO",
                        "identifier_type": "symbol",
                        "weight": 0.3
                      }
                    ],
                    "currency": "EUR"
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalysisResponse"
                },
                "examples": {
                  "standard": {
                    "summary": "Five holdings, one excluded",
                    "value": {
                      "schema_version": "1.0",
                      "methodology_version": "0.3",
                      "result_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
                      "computed_at": "2026-10-27T18:00:00Z",
                      "currency": "EUR",
                      "history_window": {
                        "start_date": "2009-09-28",
                        "end_date": "2026-10-23"
                      },
                      "resilience_score": 44,
                      "rating": "average",
                      "subscores": {
                        "scenario_survival": {
                          "score": 48,
                          "rating": "average"
                        },
                        "drawdown_resistance": {
                          "score": 34,
                          "rating": "weak"
                        },
                        "concentration": {
                          "score": 45,
                          "rating": "average"
                        },
                        "correlation_fragility": {
                          "score": 41,
                          "rating": "average"
                        },
                        "volatility": {
                          "score": 72,
                          "rating": "good"
                        }
                      },
                      "scenario_losses": {
                        "covid_2020": -0.24,
                        "rate_shock_2022": -0.17
                      },
                      "metrics": {
                        "concentration": {
                          "largest_exposure_label": "Apple Inc.",
                          "largest_exposure_weight": 0.442,
                          "top_three_weight": 0.855
                        },
                        "volatility": {
                          "annualized_volatility": 0.17,
                          "sharpe_ratio": 0.48,
                          "sortino_ratio": 0.67
                        },
                        "drawdown": {
                          "max_drawdown": -0.29,
                          "max_drawdown_recovery_days": 412
                        }
                      },
                      "coverage": {
                        "scored_weight": 0.92,
                        "excluded_weight": 0.08
                      },
                      "resolved_holdings": [
                        {
                          "identifier": "AAPL.XNAS",
                          "identifier_type": "symbol",
                          "label": "Apple Inc.",
                          "exclusion_reason": null
                        },
                        {
                          "identifier": "SAP.XETR",
                          "identifier_type": "symbol",
                          "label": "SAP SE",
                          "exclusion_reason": null
                        },
                        {
                          "identifier": "IWDA.XAMS",
                          "identifier_type": "symbol",
                          "label": "iShares Core MSCI World UCITS ETF",
                          "exclusion_reason": null
                        },
                        {
                          "identifier": "XAU.COMMODITY",
                          "identifier_type": "symbol",
                          "label": "Gold Spot",
                          "exclusion_reason": null
                        },
                        {
                          "identifier": "NEWCO.XNAS",
                          "identifier_type": "symbol",
                          "label": "NewCo Holdings Inc.",
                          "exclusion_reason": "insufficient_history"
                        }
                      ]
                    }
                  },
                  "edgeCase": {
                    "summary": "A fund without holdings data",
                    "value": {
                      "schema_version": "1.0",
                      "methodology_version": "0.3",
                      "result_id": "3f2b8c1e-5a7d-4e9b-9c0a-1d2e3f4a5b6c",
                      "computed_at": "2026-10-27T18:05:00Z",
                      "currency": "EUR",
                      "history_window": {
                        "start_date": "2015-08-10",
                        "end_date": "2026-10-23"
                      },
                      "resilience_score": 24,
                      "rating": "weak",
                      "subscores": {
                        "scenario_survival": {
                          "score": 22,
                          "rating": "weak"
                        },
                        "drawdown_resistance": {
                          "score": 18,
                          "rating": "weak"
                        },
                        "concentration": {
                          "score": 30,
                          "rating": "weak"
                        },
                        "correlation_fragility": {
                          "score": 35,
                          "rating": "weak"
                        },
                        "volatility": {
                          "score": 20,
                          "rating": "weak"
                        }
                      },
                      "scenario_losses": {
                        "covid_2020": -0.31,
                        "rate_shock_2022": -0.39
                      },
                      "metrics": {
                        "concentration": {
                          "largest_exposure_label": "Apple Inc.",
                          "largest_exposure_weight": 0.625,
                          "top_three_weight": 1.0
                        },
                        "volatility": {
                          "annualized_volatility": 0.41,
                          "sharpe_ratio": 0.71,
                          "sortino_ratio": 1.02
                        },
                        "drawdown": {
                          "max_drawdown": -0.58,
                          "max_drawdown_recovery_days": null
                        }
                      },
                      "coverage": {
                        "scored_weight": 0.8,
                        "excluded_weight": 0.2
                      },
                      "resolved_holdings": [
                        {
                          "identifier": "AAPL.XNAS",
                          "identifier_type": "symbol",
                          "label": "Apple Inc.",
                          "exclusion_reason": null
                        },
                        {
                          "identifier": "NEWFUND.XETR",
                          "identifier_type": "symbol",
                          "label": "NewFund Global Equity UCITS ETF",
                          "exclusion_reason": "holdings_unavailable"
                        },
                        {
                          "identifier": "ETH.CRYPTO",
                          "identifier_type": "symbol",
                          "label": "Ethereum",
                          "exclusion_reason": null
                        }
                      ]
                    }
                  }
                }
              }
            },
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            }
          },
          "400": {
            "description": "Problem body. code: INVALID_REQUEST",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            }
          },
          "401": {
            "description": "Problem body. code: INVALID_API_KEY",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "WWW-Authenticate": {
                "$ref": "#/components/headers/WWW-Authenticate"
              }
            }
          },
          "403": {
            "description": "Problem body. code: TIER_NOT_ENTITLED",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            }
          },
          "415": {
            "description": "Problem body. code: UNSUPPORTED_MEDIA_TYPE",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            }
          },
          "422": {
            "description": "Problem body. code: EMPTY_PORTFOLIO, INSUFFICIENT_COVERAGE, INVALID_WEIGHTS, SCHEMA_VIOLATION, TOO_MANY_HOLDINGS, UNSUPPORTED_CURRENCY, UNSUPPORTED_IDENTIFIER_TYPE",
            "content": {
              "application/problem+json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/ValidationProblem"
                    },
                    {
                      "$ref": "#/components/schemas/Problem"
                    }
                  ],
                  "title": "Response 422 Analyse"
                },
                "examples": {
                  "invalidWeights": {
                    "summary": "Weights that do not sum to 1",
                    "value": {
                      "type": "https://docs.aegoralabs.de/errors/invalid-weights",
                      "title": "Invalid weights",
                      "status": 422,
                      "detail": "Portfolio weights must sum to 1.0 (±0.001), got 0.900000.",
                      "instance": "tag:aegoralabs.de,2026:request:7c9e6679-7425-40de-944b-e07fc1f90ae7",
                      "code": "INVALID_WEIGHTS",
                      "errors": [
                        {
                          "code": "INVALID_WEIGHTS",
                          "detail": "Portfolio weights must sum to 1.0 (±0.001), got 0.900000.",
                          "pointer": "/holdings"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            }
          },
          "429": {
            "description": "Problem body. code: RATE_LIMIT_EXCEEDED",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            }
          },
          "500": {
            "description": "Problem body. code: INTERNAL_ERROR",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            }
          },
          "503": {
            "description": "Problem body. code: MARKET_DATA_UNAVAILABLE",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "X-Request-Id",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional. If the whole value matches [A-Za-z0-9._~-]{1,128}, it is echoed in the X-Request-Id response header, in result_id and in instance. Any other value is replaced by a generated UUID4. It never causes an error."
          }
        ],
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl https://api.aegoralabs.de/v1/analysis \\\n  -H \"Authorization: Bearer $SILK_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  --data-binary @portfolio.json \\\n  --max-time 30"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import os\n\nimport requests\n\nwith open(\"portfolio.json\", \"rb\") as file:\n    portfolio = file.read()\n\nresponse = requests.post(\n    \"https://api.aegoralabs.de/v1/analysis\",\n    headers={\n        \"Authorization\": f\"Bearer {os.environ['SILK_API_KEY']}\",\n        \"Content-Type\": \"application/json\",\n    },\n    data=portfolio,\n    timeout=30,\n)\n\nbody = response.json()\nif response.ok:\n    print(body[\"resilience_score\"], body[\"rating\"])\nelse:\n    print(response.status_code, body[\"code\"], body[\"detail\"])"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "// Node.js 18 or later\nimport { readFile } from \"node:fs/promises\";\n\nconst response = await fetch(\"https://api.aegoralabs.de/v1/analysis\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.SILK_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: await readFile(\"portfolio.json\"),\n  signal: AbortSignal.timeout(30_000),\n});\n\nconst body = await response.json();\nif (response.ok) {\n  console.log(body.resilience_score, body.rating);\n} else {\n  console.log(response.status, body.code, body.detail);\n}"
          },
          {
            "lang": "java",
            "label": "Java",
            "source": "// Java 11 or later. Run with: java Main.java\nimport java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.nio.file.Path;\nimport java.time.Duration;\n\npublic class Main {\n    public static void main(String[] args) throws Exception {\n        HttpRequest request = HttpRequest.newBuilder(URI.create(\"https://api.aegoralabs.de/v1/analysis\"))\n            .header(\"Authorization\", \"Bearer \" + System.getenv(\"SILK_API_KEY\"))\n            .header(\"Content-Type\", \"application/json\")\n            .timeout(Duration.ofSeconds(30))\n            .POST(HttpRequest.BodyPublishers.ofFile(Path.of(\"portfolio.json\")))\n            .build();\n\n        HttpResponse<String> response = HttpClient.newHttpClient()\n            .send(request, HttpResponse.BodyHandlers.ofString());\n\n        // The body is JSON: the result with \"resilience_score\" and \"rating\" on 200,\n        // otherwise a problem with \"code\" and \"detail\". Read it with your JSON library.\n        System.out.println(response.statusCode() + \" \" + response.body());\n    }\n}"
          },
          {
            "lang": "csharp",
            "label": "C#",
            "source": "// .NET 6 or later\nusing System.Net.Http.Headers;\nusing System.Text.Json;\n\nusing var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };\nclient.DefaultRequestHeaders.Authorization =\n    new AuthenticationHeaderValue(\"Bearer\", Environment.GetEnvironmentVariable(\"SILK_API_KEY\"));\n\nvar content = new ByteArrayContent(File.ReadAllBytes(\"portfolio.json\"));\ncontent.Headers.ContentType = new MediaTypeHeaderValue(\"application/json\");\n\nusing var response = await client.PostAsync(\"https://api.aegoralabs.de/v1/analysis\", content);\nusing var body = JsonDocument.Parse(await response.Content.ReadAsStringAsync());\nvar json = body.RootElement;\n\nif (response.IsSuccessStatusCode)\n{\n    Console.WriteLine($\"{json.GetProperty(\"resilience_score\")} {json.GetProperty(\"rating\")}\");\n}\nelse\n{\n    Console.WriteLine($\"{(int)response.StatusCode} {json.GetProperty(\"code\")} {json.GetProperty(\"detail\")}\");\n}"
          },
          {
            "lang": "go",
            "label": "Go",
            "source": "package main\n\nimport (\n\t\"bytes\"\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"net/http\"\n\t\"os\"\n\t\"time\"\n)\n\nfunc main() {\n\tportfolio, err := os.ReadFile(\"portfolio.json\")\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\trequest, err := http.NewRequest(http.MethodPost, \"https://api.aegoralabs.de/v1/analysis\", bytes.NewReader(portfolio))\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\trequest.Header.Set(\"Authorization\", \"Bearer \"+os.Getenv(\"SILK_API_KEY\"))\n\trequest.Header.Set(\"Content-Type\", \"application/json\")\n\n\tclient := &http.Client{Timeout: 30 * time.Second}\n\tresponse, err := client.Do(request)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer response.Body.Close()\n\n\tvar body map[string]any\n\tif err := json.NewDecoder(response.Body).Decode(&body); err != nil {\n\t\tpanic(err)\n\t}\n\tif response.StatusCode == http.StatusOK {\n\t\tfmt.Println(body[\"resilience_score\"], body[\"rating\"])\n\t} else {\n\t\tfmt.Println(response.StatusCode, body[\"code\"], body[\"detail\"])\n\t}\n}"
          },
          {
            "lang": "powershell",
            "label": "PowerShell",
            "source": "# Windows PowerShell 5.1 or PowerShell 7\n$headers = @{ Authorization = \"Bearer $env:SILK_API_KEY\" }\n\ntry {\n    $result = Invoke-RestMethod -Method Post -Uri \"https://api.aegoralabs.de/v1/analysis\" `\n        -Headers $headers -ContentType \"application/json\" -InFile \"portfolio.json\" -TimeoutSec 30\n    \"$($result.resilience_score) $($result.rating)\"\n}\ncatch {\n    $problem = $_.ErrorDetails.Message | ConvertFrom-Json\n    \"$($_.Exception.Response.StatusCode.value__) $($problem.code) $($problem.detail)\"\n}"
          }
        ]
      }
    },
    "/health": {
      "get": {
        "summary": "Check the service",
        "description": "Returns 200 while the service is running. Needs no API key and calls no other service.",
        "operationId": "health",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "type": "object",
                  "title": "Response Health"
                },
                "examples": {
                  "running": {
                    "summary": "The service is running",
                    "value": {
                      "status": "ok"
                    }
                  }
                }
              }
            },
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "X-Request-Id",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional. If the whole value matches [A-Za-z0-9._~-]{1,128}, it is echoed in the X-Request-Id response header, in result_id and in instance. Any other value is replaced by a generated UUID4. It never causes an error."
          }
        ],
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl https://api.aegoralabs.de/health --max-time 10"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\"https://api.aegoralabs.de/health\", timeout=10)\nprint(response.status_code, response.json()[\"status\"])"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "// Node.js 18 or later\nconst response = await fetch(\"https://api.aegoralabs.de/health\", {\n  signal: AbortSignal.timeout(10_000),\n});\nconsole.log(response.status, (await response.json()).status);"
          },
          {
            "lang": "java",
            "label": "Java",
            "source": "// Java 11 or later. Run with: java Main.java\nimport java.net.URI;\nimport java.net.http.HttpClient;\nimport java.net.http.HttpRequest;\nimport java.net.http.HttpResponse;\nimport java.time.Duration;\n\npublic class Main {\n    public static void main(String[] args) throws Exception {\n        HttpRequest request = HttpRequest.newBuilder(URI.create(\"https://api.aegoralabs.de/health\"))\n            .timeout(Duration.ofSeconds(10))\n            .build();\n\n        HttpResponse<String> response = HttpClient.newHttpClient()\n            .send(request, HttpResponse.BodyHandlers.ofString());\n\n        System.out.println(response.statusCode() + \" \" + response.body());\n    }\n}"
          },
          {
            "lang": "csharp",
            "label": "C#",
            "source": "// .NET 6 or later\nusing var client = new HttpClient { Timeout = TimeSpan.FromSeconds(10) };\nusing var response = await client.GetAsync(\"https://api.aegoralabs.de/health\");\n\nConsole.WriteLine($\"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}\");"
          },
          {
            "lang": "go",
            "label": "Go",
            "source": "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"time\"\n)\n\nfunc main() {\n\tclient := &http.Client{Timeout: 10 * time.Second}\n\tresponse, err := client.Get(\"https://api.aegoralabs.de/health\")\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer response.Body.Close()\n\n\tbody, err := io.ReadAll(response.Body)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tfmt.Println(response.StatusCode, string(body))\n}"
          },
          {
            "lang": "powershell",
            "label": "PowerShell",
            "source": "# Windows PowerShell 5.1 or PowerShell 7\n$result = Invoke-RestMethod -Uri \"https://api.aegoralabs.de/health\" -TimeoutSec 10\n$result.status"
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "AnalysisRequest": {
        "properties": {
          "holdings": {
            "items": {
              "$ref": "#/components/schemas/Holding"
            },
            "type": "array",
            "title": "Holdings"
          },
          "currency": {
            "type": "string",
            "title": "Currency",
            "description": "ISO 4217, uppercase. Reporting currency."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "holdings",
          "currency"
        ],
        "title": "AnalysisRequest"
      },
      "AnalysisResponse": {
        "properties": {
          "schema_version": {
            "type": "string",
            "pattern": "^[0-9]+\\.[0-9]+$",
            "title": "Schema Version"
          },
          "methodology_version": {
            "type": "string",
            "minLength": 1,
            "title": "Methodology Version"
          },
          "result_id": {
            "type": "string",
            "pattern": "^[A-Za-z0-9._~-]{1,128}$",
            "title": "Result Id"
          },
          "computed_at": {
            "type": "string",
            "format": "date-time",
            "title": "Computed At"
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "title": "Currency"
          },
          "history_window": {
            "$ref": "#/components/schemas/HistoryWindow"
          },
          "resilience_score": {
            "type": "integer",
            "maximum": 100.0,
            "minimum": 0.0,
            "title": "Resilience Score",
            "description": "Higher is better."
          },
          "rating": {
            "$ref": "#/components/schemas/Rating"
          },
          "subscores": {
            "additionalProperties": {
              "$ref": "#/components/schemas/Subscore"
            },
            "propertyNames": {
              "$ref": "#/components/schemas/SubscoreKey"
            },
            "type": "object",
            "required": [
              "concentration",
              "correlation_fragility",
              "drawdown_resistance",
              "scenario_survival",
              "volatility"
            ],
            "title": "Subscores"
          },
          "scenario_losses": {
            "additionalProperties": {
              "type": "number",
              "minimum": -1.0
            },
            "propertyNames": {
              "$ref": "#/components/schemas/ScenarioKey"
            },
            "type": "object",
            "required": [
              "covid_2020",
              "rate_shock_2022"
            ],
            "title": "Scenario Losses"
          },
          "metrics": {
            "$ref": "#/components/schemas/Metrics"
          },
          "coverage": {
            "$ref": "#/components/schemas/Coverage"
          },
          "resolved_holdings": {
            "items": {
              "$ref": "#/components/schemas/ResolvedHolding"
            },
            "type": "array",
            "maxItems": 100,
            "minItems": 1,
            "title": "Resolved Holdings"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "schema_version",
          "methodology_version",
          "result_id",
          "computed_at",
          "currency",
          "history_window",
          "resilience_score",
          "rating",
          "subscores",
          "scenario_losses",
          "metrics",
          "coverage",
          "resolved_holdings"
        ],
        "title": "AnalysisResponse",
        "description": "POST /v1/analysis. Results are not stored and cannot be retrieved."
      },
      "ConcentrationMetrics": {
        "properties": {
          "largest_exposure_label": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1
              },
              {
                "type": "null"
              }
            ],
            "title": "Largest Exposure Label"
          },
          "largest_exposure_weight": {
            "type": "number",
            "maximum": 1.0,
            "minimum": 0.0,
            "title": "Largest Exposure Weight"
          },
          "top_three_weight": {
            "type": "number",
            "maximum": 1.0,
            "minimum": 0.0,
            "title": "Top Three Weight"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "largest_exposure_label",
          "largest_exposure_weight",
          "top_three_weight"
        ],
        "title": "ConcentrationMetrics"
      },
      "Coverage": {
        "properties": {
          "scored_weight": {
            "type": "number",
            "maximum": 1.0,
            "minimum": 0.0,
            "title": "Scored Weight"
          },
          "excluded_weight": {
            "type": "number",
            "maximum": 1.0,
            "minimum": 0.0,
            "title": "Excluded Weight"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "scored_weight",
          "excluded_weight"
        ],
        "title": "Coverage"
      },
      "DrawdownMetrics": {
        "properties": {
          "max_drawdown": {
            "type": "number",
            "maximum": 0.0,
            "minimum": -1.0,
            "title": "Max Drawdown"
          },
          "max_drawdown_recovery_days": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 0.0
              },
              {
                "type": "null"
              }
            ],
            "title": "Max Drawdown Recovery Days"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "max_drawdown",
          "max_drawdown_recovery_days"
        ],
        "title": "DrawdownMetrics"
      },
      "ErrorCode": {
        "type": "string",
        "enum": [
          "NOT_FOUND",
          "METHOD_NOT_ALLOWED",
          "INVALID_API_KEY",
          "TIER_NOT_ENTITLED",
          "UNSUPPORTED_MEDIA_TYPE",
          "INVALID_REQUEST",
          "EMPTY_PORTFOLIO",
          "TOO_MANY_HOLDINGS",
          "INVALID_WEIGHTS",
          "UNSUPPORTED_IDENTIFIER_TYPE",
          "UNSUPPORTED_CURRENCY",
          "INSUFFICIENT_COVERAGE",
          "RATE_LIMIT_EXCEEDED",
          "MARKET_DATA_UNAVAILABLE",
          "INTERNAL_ERROR",
          "SCHEMA_VIOLATION"
        ],
        "title": "ErrorCode",
        "description": "The stable `code` extension member of every RFC 9457 body."
      },
      "ExclusionReason": {
        "type": "string",
        "enum": [
          "unresolved_symbol",
          "unsupported_asset_type",
          "insufficient_history",
          "holdings_unavailable"
        ],
        "title": "ExclusionReason",
        "description": "Why a holding was not scored. A scored holding has null, not a member.\n\nListed in the order the engine checks them; the first check that fails decides."
      },
      "HistoryWindow": {
        "properties": {
          "start_date": {
            "type": "string",
            "format": "date",
            "title": "Start Date"
          },
          "end_date": {
            "type": "string",
            "format": "date",
            "title": "End Date"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "start_date",
          "end_date"
        ],
        "title": "HistoryWindow"
      },
      "Holding": {
        "properties": {
          "identifier": {
            "type": "string",
            "minLength": 1,
            "title": "Identifier"
          },
          "identifier_type": {
            "$ref": "#/components/schemas/IdentifierType"
          },
          "weight": {
            "type": "number",
            "title": "Weight",
            "description": "Decimal fraction. 0.40 = 40%."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "identifier",
          "identifier_type",
          "weight"
        ],
        "title": "Holding"
      },
      "IdentifierType": {
        "type": "string",
        "enum": [
          "symbol",
          "isin"
        ],
        "title": "IdentifierType",
        "description": "How holdings[].identifier is read. ISIN is defined but not enabled yet."
      },
      "Metrics": {
        "properties": {
          "concentration": {
            "$ref": "#/components/schemas/ConcentrationMetrics"
          },
          "volatility": {
            "$ref": "#/components/schemas/VolatilityMetrics"
          },
          "drawdown": {
            "$ref": "#/components/schemas/DrawdownMetrics"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "concentration",
          "volatility",
          "drawdown"
        ],
        "title": "Metrics"
      },
      "Problem": {
        "properties": {
          "type": {
            "type": "string",
            "title": "Type",
            "description": "Documentation URI of this error. Stable within /v1/."
          },
          "title": {
            "type": "string",
            "title": "Title"
          },
          "status": {
            "type": "integer",
            "maximum": 599.0,
            "minimum": 400.0,
            "title": "Status"
          },
          "detail": {
            "type": "string",
            "title": "Detail"
          },
          "instance": {
            "type": "string",
            "title": "Instance",
            "description": "tag:aegoralabs.de,2026:request:<request-id> (RFC 4151)."
          },
          "code": {
            "$ref": "#/components/schemas/ErrorCode"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "instance",
          "code"
        ],
        "title": "Problem",
        "description": "Every error body. Callers branch on `code`, never on the prose."
      },
      "ProblemEntry": {
        "properties": {
          "code": {
            "$ref": "#/components/schemas/ErrorCode"
          },
          "detail": {
            "type": "string",
            "title": "Detail"
          },
          "pointer": {
            "type": "string",
            "title": "Pointer",
            "description": "RFC 6901 JSON Pointer into the request body. The whole body is \"\"."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "code",
          "detail",
          "pointer"
        ],
        "title": "ProblemEntry",
        "description": "One problem inside a validation response."
      },
      "Rating": {
        "type": "string",
        "enum": [
          "weak",
          "average",
          "good"
        ],
        "title": "Rating",
        "description": "Band for any 0–100 score: <40 weak, <70 average, >=70 good."
      },
      "ResolvedHolding": {
        "properties": {
          "identifier": {
            "type": "string",
            "minLength": 1,
            "title": "Identifier"
          },
          "identifier_type": {
            "$ref": "#/components/schemas/IdentifierType"
          },
          "label": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1
              },
              {
                "type": "null"
              }
            ],
            "title": "Label"
          },
          "exclusion_reason": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ExclusionReason"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "identifier",
          "identifier_type",
          "label",
          "exclusion_reason"
        ],
        "title": "ResolvedHolding"
      },
      "ScenarioKey": {
        "type": "string",
        "enum": [
          "covid_2020",
          "rate_shock_2022"
        ],
        "title": "ScenarioKey",
        "description": "Keys of `scenario_losses`, one per historical market window.\n\nAdding one requires a schema_version bump. The engine defines each window's dates;\nthe documentation publishes them."
      },
      "Subscore": {
        "properties": {
          "score": {
            "type": "integer",
            "maximum": 100.0,
            "minimum": 0.0,
            "title": "Score"
          },
          "rating": {
            "$ref": "#/components/schemas/Rating"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "score",
          "rating"
        ],
        "title": "Subscore"
      },
      "SubscoreKey": {
        "type": "string",
        "enum": [
          "scenario_survival",
          "drawdown_resistance",
          "concentration",
          "correlation_fragility",
          "volatility"
        ],
        "title": "SubscoreKey",
        "description": "Keys of the `subscores` object."
      },
      "ValidationProblem": {
        "properties": {
          "type": {
            "type": "string",
            "title": "Type",
            "description": "Documentation URI of this error. Stable within /v1/."
          },
          "title": {
            "type": "string",
            "title": "Title"
          },
          "status": {
            "type": "integer",
            "maximum": 599.0,
            "minimum": 400.0,
            "title": "Status"
          },
          "detail": {
            "type": "string",
            "title": "Detail"
          },
          "instance": {
            "type": "string",
            "title": "Instance",
            "description": "tag:aegoralabs.de,2026:request:<request-id> (RFC 4151)."
          },
          "code": {
            "$ref": "#/components/schemas/ErrorCode"
          },
          "errors": {
            "items": {
              "$ref": "#/components/schemas/ProblemEntry"
            },
            "type": "array",
            "minItems": 1,
            "title": "Errors"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "instance",
          "code",
          "errors"
        ],
        "title": "ValidationProblem",
        "description": "A 422 validation body: everything in Problem, plus every problem found."
      },
      "VolatilityMetrics": {
        "properties": {
          "annualized_volatility": {
            "type": "number",
            "minimum": 0.0,
            "title": "Annualized Volatility"
          },
          "sharpe_ratio": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Sharpe Ratio"
          },
          "sortino_ratio": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Sortino Ratio"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "annualized_volatility",
          "sharpe_ratio",
          "sortino_ratio"
        ],
        "title": "VolatilityMetrics"
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key issued by Aegora Labs. Send it as: Authorization: Bearer <api_key>."
      }
    },
    "headers": {
      "X-Request-Id": {
        "description": "The request's identifier: the caller's own X-Request-Id if it matched the allowed format, otherwise a generated UUID4. The same value as result_id in a success body and as the identifier inside instance in an error body.",
        "schema": {
          "type": "string"
        }
      },
      "RateLimit-Limit": {
        "description": "Requests allowed per window for this key.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "RateLimit-Remaining": {
        "description": "Requests left in the current window. Equals RateLimit-Limit while nothing is counted.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "RateLimit-Reset": {
        "description": "Seconds until the current window ends. Windows start on every full UTC hour.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 3600
        }
      },
      "WWW-Authenticate": {
        "description": "Always Bearer: send the key as Authorization: Bearer <api_key>.",
        "schema": {
          "type": "string",
          "enum": [
            "Bearer"
          ]
        }
      },
      "Retry-After": {
        "description": "Seconds to wait before sending the request again.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      }
    }
  }
}
