Skip to content

API reference

Score a portfolio

POSTapi.aegoralabs.de/v1/analysis
curl https://api.aegoralabs.de/v1/analysis \
-H "Authorization: Bearer $SILK_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @portfolio.json \
--max-time 30

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.

X-Request-Id
string

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.

Media typeapplication/json
{
"holdings": [ … ],
{
"identifier": string,// not empty
// How holdings[].identifier is read. ISIN is defined but not enabled yet.
"identifier_type": "symbol" | "isin",
// Decimal fraction. 0.40 = 40%.
"weight": number
}
],
// ISO 4217, uppercase. Reporting currency.
"currency": string
}

200 Successful response

Media typeapplication/json
// POST /v1/analysis. Results are not stored and cannot be retrieved.
{
"schema_version": string,// /^[0-9]+\.[0-9]+$/
"methodology_version": string,// not empty
"result_id": string,// /^[A-Za-z0-9._~-]{1,128}$/
"computed_at": string,// date-time
"currency": string,// /^[A-Z]{3}$/
"history_window": { … },
"start_date": string,// date
"end_date": string// date
},
// Higher is better.
"resilience_score": integer,// 0–100
// Band for any 0–100 score: <40 weak, <70 average, >=70 good.
"rating": "weak" | "average" | "good",
"subscores": { … },
// one entry per key: scenario_survival, drawdown_resistance, concentration, correlation_fragility, volatility
"<key>": {
"score": integer,// 0–100
// Band for any 0–100 score: <40 weak, <70 average, >=70 good.
"rating": "weak" | "average" | "good"
}
},
"scenario_losses": { … },
// one entry per key: covid_2020, rate_shock_2022
"<key>": number// ≥ −1
},
"metrics": { … },
"concentration": { … },
"largest_exposure_label": string | null,// not empty
"largest_exposure_weight": number,// 0–1
"top_three_weight": number// 0–1
},
"volatility": { … },
"annualized_volatility": number,// ≥ 0
"sharpe_ratio": number | null,
"sortino_ratio": number | null
},
"drawdown": { … }
"max_drawdown": number,// −1 to 0
"max_drawdown_recovery_days": integer | null// ≥ 0
}
},
"coverage": { … },
"scored_weight": number,// 0–1
"excluded_weight": number// 0–1
},
"resolved_holdings": [ … ]// 1–100 items
{
"identifier": string,// not empty
// How holdings[].identifier is read. ISIN is defined but not enabled yet.
"identifier_type": "symbol" | "isin",
"label": string | null,// not empty
// Why a holding was not scored. A scored holding has null, not a member.
// Listed in the order the engine checks them; the first check that fails decides.
"exclusion_reason": "unresolved_symbol" | "unsupported_asset_type" | "insufficient_history" | "holdings_unavailable" | null
}
]
}
X-Request-Id
string

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.

RateLimit-Limit
integer

Requests allowed per window for this key.

RateLimit-Remaining
integer

Requests left in the current window. Equals RateLimit-Limit while nothing is counted.

RateLimit-Reset
integer
>= 1 <= 3600

Seconds until the current window ends. Windows start on every full UTC hour.

400 Invalid request

INVALID_REQUEST

Media typeapplication/problem+json
// Every error body. Callers branch on code, never on the prose.
{
// Documentation URI of this error. Stable within /v1/.
"type": string,
"title": string,
"status": integer,// 400–599
"detail": string,
// tag:aegoralabs.de,2026:request:<request-id> (RFC 4151).
"instance": string,
// The stable code extension member of every RFC 9457 body.
"code": string// one of 16 values
"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"
}
X-Request-Id
string

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.

RateLimit-Limit
integer

Requests allowed per window for this key.

RateLimit-Remaining
integer

Requests left in the current window. Equals RateLimit-Limit while nothing is counted.

RateLimit-Reset
integer
>= 1 <= 3600

Seconds until the current window ends. Windows start on every full UTC hour.

401 Invalid API key

INVALID_API_KEY

Media typeapplication/problem+json
// Every error body. Callers branch on code, never on the prose.
{
// Documentation URI of this error. Stable within /v1/.
"type": string,
"title": string,
"status": integer,// 400–599
"detail": string,
// tag:aegoralabs.de,2026:request:<request-id> (RFC 4151).
"instance": string,
// The stable code extension member of every RFC 9457 body.
"code": string// one of 16 values
"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"
}
X-Request-Id
string

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.

RateLimit-Limit
integer

Requests allowed per window for this key.

RateLimit-Remaining
integer

Requests left in the current window. Equals RateLimit-Limit while nothing is counted.

RateLimit-Reset
integer
>= 1 <= 3600

Seconds until the current window ends. Windows start on every full UTC hour.

WWW-Authenticate
string
Allowed values: Bearer

Always Bearer: send the key as Authorization: Bearer <api_key>.

403 Tier not entitled

TIER_NOT_ENTITLED

Media typeapplication/problem+json
// Every error body. Callers branch on code, never on the prose.
{
// Documentation URI of this error. Stable within /v1/.
"type": string,
"title": string,
"status": integer,// 400–599
"detail": string,
// tag:aegoralabs.de,2026:request:<request-id> (RFC 4151).
"instance": string,
// The stable code extension member of every RFC 9457 body.
"code": string// one of 16 values
"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"
}
X-Request-Id
string

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.

RateLimit-Limit
integer

Requests allowed per window for this key.

RateLimit-Remaining
integer

Requests left in the current window. Equals RateLimit-Limit while nothing is counted.

RateLimit-Reset
integer
>= 1 <= 3600

Seconds until the current window ends. Windows start on every full UTC hour.

415 Unsupported media type

UNSUPPORTED_MEDIA_TYPE

Media typeapplication/problem+json
// Every error body. Callers branch on code, never on the prose.
{
// Documentation URI of this error. Stable within /v1/.
"type": string,
"title": string,
"status": integer,// 400–599
"detail": string,
// tag:aegoralabs.de,2026:request:<request-id> (RFC 4151).
"instance": string,
// The stable code extension member of every RFC 9457 body.
"code": string// one of 16 values
"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"
}
X-Request-Id
string

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.

RateLimit-Limit
integer

Requests allowed per window for this key.

RateLimit-Remaining
integer

Requests left in the current window. Equals RateLimit-Limit while nothing is counted.

RateLimit-Reset
integer
>= 1 <= 3600

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

Media typeapplication/problem+json

One of 2:

ValidationProblem

// A 422 validation body: everything in Problem, plus every problem found.
{
// Documentation URI of this error. Stable within /v1/.
"type": string,
"title": string,
"status": integer,// 400–599
"detail": string,
// tag:aegoralabs.de,2026:request:<request-id> (RFC 4151).
"instance": string,
// The stable code extension member of every RFC 9457 body.
"code": string,// one of 16 values
"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"
"errors": [ … ]// at least 1 item
{
// The stable code extension member of every RFC 9457 body.
"code": string,// one of 16 values
"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"
"detail": string,
// RFC 6901 JSON Pointer into the request body. The whole body is "".
"pointer": string
}
]
}

Problem

// Every error body. Callers branch on code, never on the prose.
{
// Documentation URI of this error. Stable within /v1/.
"type": string,
"title": string,
"status": integer,// 400–599
"detail": string,
// tag:aegoralabs.de,2026:request:<request-id> (RFC 4151).
"instance": string,
// The stable code extension member of every RFC 9457 body.
"code": string// one of 16 values
"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"
}
X-Request-Id
string

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.

RateLimit-Limit
integer

Requests allowed per window for this key.

RateLimit-Remaining
integer

Requests left in the current window. Equals RateLimit-Limit while nothing is counted.

RateLimit-Reset
integer
>= 1 <= 3600

Seconds until the current window ends. Windows start on every full UTC hour.

429 Rate limit exceeded

RATE_LIMIT_EXCEEDED

Media typeapplication/problem+json
// Every error body. Callers branch on code, never on the prose.
{
// Documentation URI of this error. Stable within /v1/.
"type": string,
"title": string,
"status": integer,// 400–599
"detail": string,
// tag:aegoralabs.de,2026:request:<request-id> (RFC 4151).
"instance": string,
// The stable code extension member of every RFC 9457 body.
"code": string// one of 16 values
"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"
}
X-Request-Id
string

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.

RateLimit-Limit
integer

Requests allowed per window for this key.

RateLimit-Remaining
integer

Requests left in the current window. Equals RateLimit-Limit while nothing is counted.

RateLimit-Reset
integer
>= 1 <= 3600

Seconds until the current window ends. Windows start on every full UTC hour.

Retry-After
integer

Seconds to wait before sending the request again.

500 Internal error

INTERNAL_ERROR

Media typeapplication/problem+json
// Every error body. Callers branch on code, never on the prose.
{
// Documentation URI of this error. Stable within /v1/.
"type": string,
"title": string,
"status": integer,// 400–599
"detail": string,
// tag:aegoralabs.de,2026:request:<request-id> (RFC 4151).
"instance": string,
// The stable code extension member of every RFC 9457 body.
"code": string// one of 16 values
"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"
}
X-Request-Id
string

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.

RateLimit-Limit
integer

Requests allowed per window for this key.

RateLimit-Remaining
integer

Requests left in the current window. Equals RateLimit-Limit while nothing is counted.

RateLimit-Reset
integer
>= 1 <= 3600

Seconds until the current window ends. Windows start on every full UTC hour.

503 Market data unavailable

MARKET_DATA_UNAVAILABLE

Media typeapplication/problem+json
// Every error body. Callers branch on code, never on the prose.
{
// Documentation URI of this error. Stable within /v1/.
"type": string,
"title": string,
"status": integer,// 400–599
"detail": string,
// tag:aegoralabs.de,2026:request:<request-id> (RFC 4151).
"instance": string,
// The stable code extension member of every RFC 9457 body.
"code": string// one of 16 values
"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"
}
X-Request-Id
string

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.

RateLimit-Limit
integer

Requests allowed per window for this key.

RateLimit-Remaining
integer

Requests left in the current window. Equals RateLimit-Limit while nothing is counted.

RateLimit-Reset
integer
>= 1 <= 3600

Seconds until the current window ends. Windows start on every full UTC hour.