Get started
Quickstart
Send a first portfolio and read the answer.
-
Get an API key.
Keys are issued by us; contact us for one. Keep the key on your servers: never put it into a browser, a mobile app or a URL. The examples below read it from the environment variable
SILK_API_KEY. -
Describe the portfolio.
Save this as
portfolio.json:portfolio.json {"holdings": [{"identifier": "AAPL.XNAS","identifier_type": "symbol","weight": 0.40},{"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"}Field What it holds identifierThe instrument as TICKER.MIC: the ticker, a dot, and the venue’s Market Identifier Code.AAPL.XNASis Apple on Nasdaq; the same ETF isIWDA.XAMSin Amsterdam andEUNL.XETRon Xetra. Crypto uses.CRYPTO(ETH.CRYPTO), precious-metal spot.COMMODITY(XAU.COMMODITYfor gold).identifier_typesymbol.weightThe holding’s share of the portfolio as a fraction: 0.40is 40 %. Each weight is above 0 and at most 1; together they sum to 1 (±0.001).currencyThe reporting currency. EURtoday.A request holds 1 to 100 holdings. Weights only: no amounts, no account or customer data.
-
Send it.
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 osimport requestswith 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 mainimport ("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]anyif 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)"} -
Read the answer.
The response, shortened here to the fields you will use first:
200 OK {"methodology_version": "0.3","result_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7","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 },"coverage": { "scored_weight": 0.92, "excluded_weight": 0.08 },"resolved_holdings": [{ "identifier": "AAPL.XNAS", "identifier_type": "symbol", "label": "Apple Inc.", "exclusion_reason": null },{ "identifier": "NEWCO.XNAS", "identifier_type": "symbol", "label": "NewCo Holdings Inc.", "exclusion_reason": "insufficient_history" }]}Field How to read it resilience_score0 to 100, higher is better. ratingThe score in words: weakbelow 40,averagebelow 70,goodfrom 70. Every subscore has its own.subscoresThe five parts the score is built from. scenario_lossesThe portfolio’s return in two historical crash windows, as a fraction: -0.24is −24 %.coverageHow much of the submitted weight was scored and how much was left out. resolved_holdingsEvery holding you sent, in your order. exclusion_reasonisnullwhen the holding was scored, otherwise it says why it was left out.result_idNames this request. Quote it if you contact us; the result itself cannot be fetched again. The full response, including the metrics behind each subscore, is in the API reference.
Holdings that cannot be scored
Section titled “Holdings that cannot be scored”A holding that cannot be scored does not fail the request. It is left out, and the remaining weights are scaled up to sum to 1 before scoring: a 60/40 portfolio with the 40 left out is scored as 100 % of the first holding. coverage shows how much was left out, and exclusion_reason says why:
exclusion_reason |
Meaning |
|---|---|
null |
The holding was scored. |
unresolved_symbol |
Not a valid TICKER.MIC, a venue that is not supported, or an instrument the market data does not know. |
unsupported_asset_type |
A kind of instrument that is not scored, such as a derivative. |
insufficient_history |
Not enough price history: it has to reach back to 19 February 2020, the start of the covid_2020 window. |
holdings_unavailable |
A fund whose holdings are not available. The fund is left out as a whole. |
If so much is left out that the result would not mean anything, the request fails with INSUFFICIENT_COVERAGE instead of returning a misleading score.
When something goes wrong
Section titled “When something goes wrong”Every error has an HTTP status and a body with a stable code; branch on code. A 4xx status means the request has to change, a 5xx status means the problem is on our side. The error pages say for each code what happened and what to do.