API reference
Score a portfolio
curl https://api.aegoralabs.de/v1/analysis \ -H "Authorization: Bearer $SILK_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @portfolio.json \ --max-time 30import os
import requests
with open("portfolio.json", "rb") as file: portfolio = file.read()
response = requests.post( "https://api.aegoralabs.de/v1/analysis", headers={ "Authorization": f"Bearer {os.environ['SILK_API_KEY']}", "Content-Type": "application/json", }, data=portfolio, timeout=30,)
body = response.json()if response.ok: print(body["resilience_score"], body["rating"])else: print(response.status_code, body["code"], body["detail"])// Node.js 18 or laterimport { readFile } from "node:fs/promises";
const response = await fetch("https://api.aegoralabs.de/v1/analysis", { method: "POST", headers: { Authorization: `Bearer ${process.env.SILK_API_KEY}`, "Content-Type": "application/json", }, body: await readFile("portfolio.json"), signal: AbortSignal.timeout(30_000),});
const body = await response.json();if (response.ok) { console.log(body.resilience_score, body.rating);} else { console.log(response.status, body.code, body.detail);}// Java 11 or later. Run with: java Main.javaimport java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.nio.file.Path;import java.time.Duration;
public class Main { public static void main(String[] args) throws Exception { HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aegoralabs.de/v1/analysis")) .header("Authorization", "Bearer " + System.getenv("SILK_API_KEY")) .header("Content-Type", "application/json") .timeout(Duration.ofSeconds(30)) .POST(HttpRequest.BodyPublishers.ofFile(Path.of("portfolio.json"))) .build();
HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString());
// The body is JSON: the result with "resilience_score" and "rating" on 200, // otherwise a problem with "code" and "detail". Read it with your JSON library. System.out.println(response.statusCode() + " " + response.body()); }}// .NET 6 or laterusing System.Net.Http.Headers;using System.Text.Json;
using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("SILK_API_KEY"));
var content = new ByteArrayContent(File.ReadAllBytes("portfolio.json"));content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
using var response = await client.PostAsync("https://api.aegoralabs.de/v1/analysis", content);using var body = JsonDocument.Parse(await response.Content.ReadAsStringAsync());var json = body.RootElement;
if (response.IsSuccessStatusCode){ Console.WriteLine($"{json.GetProperty("resilience_score")} {json.GetProperty("rating")}");}else{ Console.WriteLine($"{(int)response.StatusCode} {json.GetProperty("code")} {json.GetProperty("detail")}");}package main
import ( "bytes" "encoding/json" "fmt" "net/http" "os" "time")
func main() { portfolio, err := os.ReadFile("portfolio.json") if err != nil { panic(err) }
request, err := http.NewRequest(http.MethodPost, "https://api.aegoralabs.de/v1/analysis", bytes.NewReader(portfolio)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("SILK_API_KEY")) request.Header.Set("Content-Type", "application/json")
client := &http.Client{Timeout: 30 * time.Second} response, err := client.Do(request) if err != nil { panic(err) } defer response.Body.Close()
var body map[string]any if err := json.NewDecoder(response.Body).Decode(&body); err != nil { panic(err) } if response.StatusCode == http.StatusOK { fmt.Println(body["resilience_score"], body["rating"]) } else { fmt.Println(response.StatusCode, body["code"], body["detail"]) }}# Windows PowerShell 5.1 or PowerShell 7$headers = @{ Authorization = "Bearer $env:SILK_API_KEY" }
try { $result = Invoke-RestMethod -Method Post -Uri "https://api.aegoralabs.de/v1/analysis" ` -Headers $headers -ContentType "application/json" -InFile "portfolio.json" -TimeoutSec 30 "$($result.resilience_score) $($result.rating)"}catch { $problem = $_.ErrorDetails.Message | ConvertFrom-Json "$($_.Exception.Response.StatusCode.value__) $($problem.code) $($problem.detail)"}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.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”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.
Request Bodyrequired
Section titled “Request Bodyrequired”"holdings": [ … ],
{ "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"}{ "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"}Responses
Section titled “Responses”200 Successful response
"history_window": { … },
"subscores": { … },
"scenario_losses": { … },
"metrics": { … },
"concentration": { … },
"volatility": { … },
"drawdown": { … }
"coverage": { … },
"resolved_holdings": [ … ]// 1–100 items
{ "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" } ]}{ "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 }, "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
Section titled “Headers”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.
Requests allowed per window for this key.
Requests left in the current window. Equals RateLimit-Limit while nothing is counted.
Seconds until the current window ends. Windows start on every full UTC hour.
400 Invalid request
"code": string// one of 16 values
{ "code": "NOT_FOUND"}Headers
Section titled “Headers”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.
Requests allowed per window for this key.
Requests left in the current window. Equals RateLimit-Limit while nothing is counted.
Seconds until the current window ends. Windows start on every full UTC hour.
401 Invalid API key
"code": string// one of 16 values
{ "code": "NOT_FOUND"}Headers
Section titled “Headers”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.
Requests allowed per window for this key.
Requests left in the current window. Equals RateLimit-Limit while nothing is counted.
Seconds until the current window ends. Windows start on every full UTC hour.
Always Bearer: send the key as Authorization: Bearer <api_key>.
403 Tier not entitled
"code": string// one of 16 values
{ "code": "NOT_FOUND"}Headers
Section titled “Headers”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.
Requests allowed per window for this key.
Requests left in the current window. Equals RateLimit-Limit while nothing is counted.
Seconds until the current window ends. Windows start on every full UTC hour.
415 Unsupported media type
"code": string// one of 16 values
{ "code": "NOT_FOUND"}Headers
Section titled “Headers”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.
Requests allowed per window for this key.
Requests left in the current window. Equals RateLimit-Limit while nothing is counted.
Seconds until the current window ends. Windows start on every full UTC hour.
422 Unprocessable content
7 codes
EMPTY_PORTFOLIOINSUFFICIENT_COVERAGEINVALID_WEIGHTSSCHEMA_VIOLATIONTOO_MANY_HOLDINGSUNSUPPORTED_CURRENCYUNSUPPORTED_IDENTIFIER_TYPE
One of 2:
ValidationProblem
"code": string,// one of 16 values
"errors": [ … ]// at least 1 item
"code": string,// one of 16 values
Problem
"code": string// one of 16 values
{ "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
Section titled “Headers”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.
Requests allowed per window for this key.
Requests left in the current window. Equals RateLimit-Limit while nothing is counted.
Seconds until the current window ends. Windows start on every full UTC hour.
429 Rate limit exceeded
"code": string// one of 16 values
{ "code": "NOT_FOUND"}Headers
Section titled “Headers”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.
Requests allowed per window for this key.
Requests left in the current window. Equals RateLimit-Limit while nothing is counted.
Seconds until the current window ends. Windows start on every full UTC hour.
Seconds to wait before sending the request again.
500 Internal error
"code": string// one of 16 values
{ "code": "NOT_FOUND"}Headers
Section titled “Headers”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.
Requests allowed per window for this key.
Requests left in the current window. Equals RateLimit-Limit while nothing is counted.
Seconds until the current window ends. Windows start on every full UTC hour.
503 Market data unavailable
"code": string// one of 16 values
{ "code": "NOT_FOUND"}Headers
Section titled “Headers”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.
Requests allowed per window for this key.
Requests left in the current window. Equals RateLimit-Limit while nothing is counted.
Seconds until the current window ends. Windows start on every full UTC hour.