Schemas

The shapes the server sends and accepts. Each type links to its own entry.

ActiveRiskPayload

How tracking error against a benchmark divides among active positions.

Contributions sum to tracking_error exactly, the same identity the total decomposition satisfies, on active weights rather than holdings.

Field	Type	Required	Description
benchmark	string	yes	Index the comparison is against.
contributions_not_held	map of string to number	no	Contributions from benchmark constituents the index does not hold. They have no row in the weights table but are often the largest active positions there are, so omitting them would hide the biggest sources of tracking error.
covered_weight	number	yes	Share of gross active weight the model covers. Gross because active weights sum to roughly zero, so a plain sum would say nothing about coverage.
tracking_error	number	yes	Annualised volatility of the active position.
uncovered	array of string	no	Names with no estimate, from either side.
window_end	string or null	no	Last date of the run's own level series, YYYY-MM-DD, on the same terms as window_start, which is the other end: a bound given to the price fetch, unchanged by what the store actually held.
window_start	string or null	no	First date of the run's own level series, YYYY-MM-DD: the span the price fetch behind this estimate was given, not the dates prices came back on. It does not narrow: when the store covers less, the covariance is estimated from fewer observations and this still reports the run's span, so it is a bound rather than a measurement. Null when the run carries no level series. window_end is the other end.

ActiveStepPayload

What an active strategy did at one rebalance.

Field	Type	Required	Description
active_share	number	yes	Half the summed absolute differences from the benchmark.
date	string	yes	YYYY-MM-DD.
exposures	map of string to number	no	What the construction reports, such as a factor tilt's active exposure to each factor. Empty for most.
risk_contributions	map of string to number	no	Each holding's share of the portfolio's variance, adding up to one over the names the construction placed.
tracking_error	number	yes	Ex-ante, annualised.
weights	map of string to number	yes	The weights traded to.

AllNode

Every operand must pass: expressions.core.All.

Field	Type	Required	Description
node	"all"	yes	Discriminator. Always 'all'.
operands	array of ExpressionNode	yes	The expressions that must all pass.

AnalysisCatalogue

Response of GET /analysis/options: everything an analysis can be asked for, so a client hard-codes none of it.

Field	Type	Required	Description
dropped	array of string	yes	Statistic ids no longer given.
names	map of string to map of string to string	yes	Labels for figure names that are not statistic ids, by dimension: books, methods, confidence levels, horizons, comparators, fields.
renamed	map of string to string	yes	Statistic ids renamed in this release, old to new.
reports	array of ReportSpec	yes	Every report, in order.
settings	array of object	yes	Each section of settings in order, each with its parameters in the shape GET /backtest/options describes a backtest's.
statistics	array of StatisticSpec	yes	Every statistic, in order.
tables	array of TableSpec	yes	The large tables a run gives.
unavailable	array of UnavailableSpec	yes	Every reason a statistic can be unavailable.

AnalysisRequestSpec

What a run's analysis should give: the reports wanted, each at a level, with statistics added or taken out, their time views, and every choice the analysis makes. GET /analysis/options lists the reports, statistics and settings.

Field	Type	Required	Description
add	map of string to array of string	no	By report, optional statistics to show, by id.
options	map of string to object	no	Every choice the analysis makes, by section and setting, as GET /analysis/options describes them; a setting left out takes its default.
remove	map of string to array of string	no	By report, included statistics not to show, by id.
reports	map of string to string	no	Each report wanted, by id, with its level: 'core' or 'extended'.
statistics	array of string	no	Statistics wanted outside any report, by id.
time_views	map of string to map of string to string	no	By report, statistic ids with the time view to show them in: 'point', 'rolling' or 'both'.

AnalyticsBlock

A run's analysis: each statistic once, and each report as a list of statistic ids.

Field	Type	Required	Description
active_against	string or null	yes	The comparator relative and active figures are measured against.
groupings	array of string	no	The reference fields the run kept for its names, which options.attribution.grouping can name.
reports	map of string to ReportSelection	yes	Each report asked for, by id.
request	object	yes	The request, every default filled in.
statistics	map of string to StatisticValue	yes	Each statistic worked out, by id. Labels, units and decimals are in GET /analysis/options.
tables	map of string to TableRef	no	The run's large tables, by name, read on their own.
timings	map of string to number	yes	Seconds each part took: 'tables', then 'performance', 'portfolio', 'risk' and 'attribution' as asked for.
unavailable	map of string to UnavailableReason	yes	Each statistic asked for that the run cannot give, by id.

AnalyticsJobStatus

An analytics:{strategy_id} job. result is the latest run's analysis, whole: what was kept with it and what was worked out now.

Field	Type	Required	Description
error	ErrorDetail or null	no	Failure reason, when status is failed; null otherwise. The same {code, message, detail} a non-2xx response carries, and the same schema, so a failed job branches on error.code exactly as an HTTP error does. A job recorded by an older engine carries UNCLASSIFIED_FAILURE: its message was recorded, its code was not, and the migration does not guess one.
job_id	string	yes	The job's id: poll GET /jobs/{job_id}, or watch it on the event socket.
kind	string	yes	What the job is, e.g. 'backtest'.
message	string	no	Latest progress message. Default: "".
progress	number	yes	Fraction complete, 0.0 to 1.0.
result	AnalyticsBlock or null	no	Present only once the job has succeeded; null otherwise.
status	string	yes	pending, running, succeeded, failed or cancelled. The last three are terminal.

AnalyticsRerun

Body of POST /strategies/{strategy_id}/analytics: the analysis to give of the strategy's latest run, and a name to keep it under.

Field	Type	Required	Description
analysis	AnalysisRequestSpec	no	What to give: reports, statistics and every choice they make.
save	string or null	no	A name to keep this analysis under, read back from /strategies/{strategy_id}/analyses/{name}; null keeps none apart from the run's own.

AnalyticsView

Response of GET /strategies/{strategy_id}/analytics.

Field	Type	Required	Description
analytics	AnalyticsBlock or null	yes	The run's analysis; null when not computed.
reason	string or null	no	Why it was not computed.
status	string	yes	'computed', or 'not_computed' for a run made without an analysis, or before 0.10.0, which the analytics rerun gives.
warnings	array of string	no	What the stored run says as it opens: that the data store its market inputs came from was deleted, say.

AnyNode

At least one operand must pass: expressions.core.Any_.

Field	Type	Required	Description
node	"any"	yes	Discriminator. Always 'any'.
operands	array of ExpressionNode	yes	The expressions, any of which may pass.

AssetView

Response of GET /strategies/{strategy_id}/assets/{identifier}.

Field	Type	Required	Description
beta	number	yes
correlation	number	yes
currency	string or null	no	The currency total_return, excess_return, tracking_error, correlation and beta are measured in: the index's.
excess_return	number	yes	total_return less index_return, both in the index's currency.
identifier	string	yes
index_id	string	yes	The index the strategy holds.
index_return	number	yes
observations	integer	yes
price	SeriesPayload	yes	The name's close, in its own currency.
price_currency	string or null	no	The currency price is in: the name's own, from its latest reference record. Null when no currency is on record for it, in which case its prices are taken to be in the index's currency.
raw_weight_history	map of string to number	no	The same dates -> the weight before capping, so the drilldown can show what the cap did to this name over time. Carried alongside weight_history, which stays the applied series.
rebalances_held	integer	yes
strategy_id	string	yes	The strategy whose latest run this reads.
total_return	number	yes	The name's return over the run, in the index's currency.
tracking_error	number	yes
weight_history	map of string to number	yes	Rebalance date -> this name's applied weight. Only the rebalances it was actually in.

AttributionView

Response of GET /strategies/{strategy_id}/attribution.

Contributions are Carino-linked, so they sum to the compounded total return rather than approximately to it. residual is reported regardless and should sit at machine epsilon; anything larger means an assumption broke upstream, which is worth surfacing rather than rounding away.

Field	Type	Required	Description
cap_drag	number or null	no	Capped return minus uncapped. Null on an uncapped index: reporting 0.0 would claim capping happened and made no difference.
contributions	array of ContributionPayload	yes
cost_drag	number or null	no	Direct effect of transaction costs. Null at zero cost.
end	string	yes	Last date a contribution was computed for, in the same full ISO-8601 form as start. Resolved: the latest date the run covers at or before the requested end, which requested_end echoes. start is the other end.
index_id	string	yes	The index the strategy holds.
periods	integer	yes
reconciles	boolean	yes
requested_end	string or null	no	The window's last date as asked for, YYYY-MM-DD, on the same terms as requested_start, which is the other end: the end query echoed unchanged, or the run's own last date when none was given. end is the resolved counterpart.
requested_start	string or null	no	The window's first date as asked for, YYYY-MM-DD: the start query echoed back unchanged, or the run's own first date when the query was omitted, which is what the window then defaulted to. It does not resolve (no data moves it), so it is the field to label a range with. start is the resolved counterpart and is a trading day later. Null only when the query was omitted and the run carries no level series to default from. requested_end is the other end.
residual	number	yes
start	string	yes	First date a contribution was computed for, as a full ISO-8601 timestamp. Resolved, and one trading day later than the window's own first date: a period's return is earned by the weight held at its start, so the first date in the window has no complete period behind it and is dropped. requested_start carries the window that was asked for, in YYYY-MM-DD; this is not that date. end is the other end.
strategy_id	string	yes	The strategy whose latest run this reads.
total_return	number	yes

BacktestJobStatus

A backtest:{strategy_id} job. result is the run payload.

Field	Type	Required	Description
error	ErrorDetail or null	no	Failure reason, when status is failed; null otherwise. The same {code, message, detail} a non-2xx response carries, and the same schema, so a failed job branches on error.code exactly as an HTTP error does. A job recorded by an older engine carries UNCLASSIFIED_FAILURE: its message was recorded, its code was not, and the migration does not guess one.
job_id	string	yes	The job's id: poll GET /jobs/{job_id}, or watch it on the event socket.
kind	string	yes	What the job is, e.g. 'backtest'.
message	string	no	Latest progress message. Default: "".
progress	number	yes	Fraction complete, 0.0 to 1.0.
result	BacktestRunResult or null	no	Present only once the job has succeeded; null otherwise.
status	string	yes	pending, running, succeeded, failed or cancelled. The last three are terminal.

BacktestMetrics

Headline metrics from a backtest run.

Tracking figures are null when the run had no target index to compare to.

Field	Type	Required	Description
annualised_return	number	yes	Fraction, not percent: 0.0523 means 5.23%.
average_active_share	number or null	no	For an active strategy, the mean active share at its rebalances.
average_ex_ante_tracking_error	number or null	no	For an active strategy, the mean ex-ante tracking error at its rebalances.
average_premium	number or null	no	For an ETF, the mean premium to NAV.
average_spread	number or null	no	For an ETF, the mean bid-ask spread.
days_at_premium	number or null	no	For an ETF, the share of days its price was above NAV.
hit_rate_monthly	number or null	no	The share of calendar months with a positive return.
information_ratio	number or null	no	For an active strategy, annualised active return over tracking error against its benchmark.
market_return	number or null	no	For an ETF, an exchange investor's return: bought at the ask on the first day, sold at the bid on the last.
max_drawdown	number	yes	Fraction, not percent: 0.0523 means 5.23%.
money_weighted_return	number or null	no	The investors' annual internal rate of return, when money flowed. Null otherwise.
sharpe_ratio	number	yes
total_return	number	yes	Fraction, not percent: 0.0523 means 5.23%.
tracking_difference	number or null	no
tracking_error	number or null	no
volatility	number	yes	Fraction, not percent: 0.0523 means 5.23%.

BacktestOptions

Response of GET /backtest/options.

Everything a backtest form needs, from the engine itself: each family's types with their fields (in the shape /indices/rule-types uses), the vehicle presets with their resolved settings, the settings' descriptors, the modelling assumptions with their defaults, and the closed choices.

Field	Type	Required	Description
active_constraints	array of TypeSpec	yes	For strategy.constraints.
caps	array of TypeSpec	yes	For implementation.caps.
choices	map of string to array of string	yes	Closed sets: 'dividends', 'strategy', 'rebalancing', 'redistribution', 'invest_flows' and 'fx_policy'.
constructions	array of TypeSpec	yes	For strategy.construction.
flows	array of TypeSpec	yes	For flows.
implementation_settings	array of ParameterSpec	yes	The implementation's plain settings: minimum_position, impact and execution fields, redistribution, cash_buffer and invest_flows.
limits	array of TypeSpec	yes	For a vehicle's limits.
market_settings	array of ParameterSpec	yes	What an ETF's market setting accepts.
modelling_assumptions	array of ParameterSpec	yes	Each modelling assumption, with the engine's default as its default.
presets	array of VehiclePreset	yes	Every preset, generic first: the vehicle used when preset is null.
pricing	array of TypeSpec	yes	For a vehicle's pricing.
replication_constraints	array of TypeSpec	yes	For OptimisedReplication.constraints: the optimiser's constraints, the same catalogue GET /optimise/constraint-types serves.
replications	array of TypeSpec	yes	For strategy.replication.
run_settings	array of ParameterSpec	yes	The run's own settings: start, end, initial_capital, transaction_cost_bps, currency, dividends and benchmark.
screens	array of TypeSpec	yes	For implementation.screens.
share_class_settings	array of ParameterSpec	yes	What each of share_classes takes.
signals	array of TypeSpec	yes	For strategy.signal.
vehicle_settings	array of ParameterSpec	yes	What vehicle.settings accepts; applies_to marks the exchange-traded ones.

BacktestRecordCollection

Response of GET /strategies/runs.

An envelope rather than a bare array, so the listing can say how many stored records it left out.

Field	Type	Required	Description
backtests	array of BacktestRecordRow	yes
skipped	integer	no	Stored documents the server could not read, and so left out of this listing. Non-zero means the collection is incomplete: the fault is logged server-side, and each skipped document answers 404 on its own route. Default: 0.
skipped_causes	SkippedCauses	no	The same documents as skipped, by cause, so the listing can say what to do about them. Its three counts sum to skipped.

BacktestRecordRow

One stored backtest record, as a listing knows it.

The row is deliberately thin: the strategy to fetch the record by, what it holds, and when it was captured. Everything else comes from /strategies/{strategy_id}/record.

Field	Type	Required	Description
currency	string or null	no	The book's currency.
index_id	string	yes	The index it held when it ran.
run_at	string or null	no	ISO-8601 UTC capture time; null on records written before they were stamped.
strategy	string or null	no	The strategy's type: 'index', 'index_tracking' or 'active'.
strategy_id	string	yes	The strategy the run was of.
strategy_name	string	yes	Its name when it ran.
vehicle	string or null	no	The vehicle's name; null for a plain backtest.
vehicle_preset	string or null	no	The preset's key, stable across renames; null for a plain backtest or a generic vehicle.

BacktestResultSummary

Serialised view of a BacktestResult, in the shape of its books.

The nested shape mirrors the library object, one home per fact. Books the run did not have (no benchmark given, no index calculated) are null rather than empty, so a client can tell "not measured" from "measured and empty". index is a container of two books, {target, optimised}, matching the library's IndexBooks.

Field	Type	Required	Description
benchmark	BookPayload or null	no
currency	string or null	no	The book's currency.
index	IndexBooksPayload	no
metrics	BacktestMetrics	yes
portfolio	PortfolioBookPayload	yes
price_gaps	array of PriceGapPayload	no	Days a holding or a target name had no bar on a session its index's calendar says was open, and was therefore marked at a carried-forward price. Empty on a run with complete data: a market holiday is not a gap, since nothing is missing on a day nothing traded. A non-empty list is the signal that some marks are stale quotes rather than that day's market, which is otherwise invisible in the NAV.
rebalance_pricing	array of RebalancePricingPayload	no	What each rebalance priced from, in date order. date and priced_from differ only where the schedule landed on a day the market was shut, so the run states which session its trades were struck at rather than leaving it inferable from the weight snapshots.
run_at	string or null	no	When this record was captured, ISO-8601 UTC with an offset: wall-clock at the moment the finished run was serialised, within a second of the backtest completing. Not a market date, and not the period the backtest covered: that span is the index of portfolio.nav. BacktestRecordRow.run_at on GET /strategies/runs is the same stamp. Null only on records written by an older engine that did not stamp them.
settings	object or null	no	What ran, fully resolved, as the run payload's settings. Null on a record from before it was kept.
unfilled	array of UnfilledOrderPayload	no

BacktestRunResult

Result payload of a completed backtest job.

Every series here derives from the same NAV, rebased to 100: returns is the level's percentage change, drawdown is the level against its running peak, and annual_returns compound back to the total. A client that recomputes any of them lands on these numbers exactly.

Field	Type	Required	Description
active	array of ActiveStepPayload	no	For an active strategy, what it did at each rebalance. Empty otherwise.
analytics	AnalyticsBlock or null	no	The run's analysis, when one was asked for: each statistic once, each report as a list of statistic ids, and the run's large tables to read on their own.
annual_returns	map of string to number	yes	Calendar year -> return. Compounds to total_return.
benchmark	RelativeMetricsPayload or null	no	Comparison against the requested external benchmark, if one was given. Null otherwise; metrics.tracking_error still reports replication accuracy against the tracked index either way.
comparisons	ComparisonsPayload	no	The run against its index and its benchmark, each with the comparator's own figures over the run's window.
counterparty_exposure	SeriesPayload or null	no	What a synthetic fund would lose if its swap counterparty failed, as a fraction of NAV each day. Null for any other fund.
currency	string or null	no	The book's currency, which total_costs and initial_capital are in: the index's. Null on a run saved before this was recorded, whose book was in USD.
dividends_receivable	SeriesPayload or null	no	The dividends the fund is owed at the end of each day, in the book's currency: gone ex, not yet paid, net of withholding tax. The NAV includes them. Null for a run that is never owed one.
drawdown	SeriesPayload	yes	Level against its running peak; 0 at a new high.
fees_paid	number	no	The vehicle's management fee paid, in the book's currency. Default: 0.0.
flows	array of FlowPayload	no	Each flow as dealt. Empty without flows.
futures_exposure	SeriesPayload or null	no	The same as a fraction of NAV. Null for any other fund.
futures_notional	SeriesPayload or null	no	The exposure a fund's index futures carried each day, in the book's currency, 0 before they open: a futures-based fund's, or one equitising its cash buffer. Null for any other fund.
futures_rolls	array of FuturesRollPayload	no	Each roll of the futures to the next contract.
hedge_value	SeriesPayload or null	no	The hedged classes' forwards together, in the book's currency; null without a hedged class.
index_level	SeriesPayload	yes	The tracked index, rebased to 100 on the same axis. Not the external benchmark, which is benchmark.
initial_capital	number	no	Capital the simulation started with. Default: 0.0.
level	SeriesPayload	yes	Portfolio value, rebased to 100.
market	MarketPayload or null	no	An ETF's exchange quotes. Null otherwise.
metrics	BacktestMetrics	yes
nav_per_unit	SeriesPayload or null	no	NAV per unit on level's dates. With flows level is this series rebased, so a flow is not drawn as a gain.
price_gaps	array of PriceGapPayload	no	Days a holding or a target name had no bar on a session its index's calendar says was open, and was therefore marked at a carried-forward price. Empty on a run with complete data: a market holiday is not a gap, since nothing is missing on a day nothing traded. A non-empty list is the signal that some marks are stale quotes rather than that day's market, which is otherwise invisible in the NAV.
rebalance_pricing	array of RebalancePricingPayload	no	What each rebalance priced from, in date order. date and priced_from differ only where the schedule landed on a day the market was shut, so the run states which session its trades were struck at rather than leaving it inferable from the weight snapshots.
rebalance_steps	array of RebalanceStepPayload	no	What the implementation's stages did at each rebalance.
rebalances	array of RebalanceSnapshot	no	Composition at each rebalance. Everything the view endpoints say about weights, attribution and individual names is derived from these, so a run is readable without recalculating the index. Daily weights are deliberately absent: they are reconstructed from these and the prices, and storing one per name per day would multiply the payload by the number of trading days to save an inexpensive calculation.
replication	array of ReplicationPayload	no	For index tracking, what the replication did at each rebalance. Empty otherwise.
returns	SeriesPayload	yes	Period returns of level.
settings	object or null	no	What ran, fully resolved: the strategy and index, the dates it ran over, capital, trading cost and benchmark, the strategy's settings and implementation, flows, vehicle (preset and every setting), share classes, modelling assumptions, currency and dividend policy. Null on a run saved before it was recorded.
share_classes	array of ShareClassPayload	no	Each share class's record, in the request's order. Empty without share classes.
swap_resets	array of SwapResetPayload	no	Each reset of a synthetic fund's swap.
swap_value	SeriesPayload or null	no	A synthetic fund's swap's value each day, in the book's currency: owed to the fund when positive. The NAV includes it. Null for any other fund.
total_costs	number	no	Transaction costs paid across the run, for the cost drag. Default: 0.0.
unfilled	array of UnfilledOrderPayload	no	Orders not filled in full.
units	SeriesPayload or null	no	Units outstanding on level's dates.

BacktestValidation

Response of POST /strategies/{strategy_id}/backtest/validate.

Field	Type	Required	Description
findings	array of Finding	no	Every problem, each at its field's dotted path, such as 'vehicle.settings.pricing.params.threshold'.
settings	object or null	no	What would run, fully resolved, in the shape a run's settings takes. Null when the request is not valid.
valid	boolean	yes	False when any finding is an error.

BatchReferenceResponse

Response of GET /data/reference.

Entries are in the order the request named them, one per identifier, so a table can render straight down the list without re-sorting against what it asked for.

Field	Type	Required	Description
as_of	string or null	no	Point-in-time date applied, if one was requested.
entries	array of ReferenceEntry	yes

BenchmarkRef

What to compare a backtest against.

Distinct from the index being tracked. The tracked index measures replication accuracy; a benchmark measures relative performance against something the portfolio was never trying to replicate.

Field	Type	Required	Description
id	string	yes	Index id, or market-data identifier.
kind	one of "index", "identifier"	yes	'index' for a stored index definition, 'identifier' for a market-data series.
price_column	string	no	Market-data column to read. Ignored when kind is 'index'. Default: "CLOSE".

BookPayload

One comparator's record on the wire.

Two different facts about weights, not two copies of one: weights is the daily panel (what the book actually HELD each day, drift included) and rebalances is what each rebalance DECIDED. They agree only on a rebalance date; everywhere else prices have moved the held weights away from the decided ones. A client wanting decided weights reads rebalances rather than resampling the panel, which cannot answer what capping cost whatever it is resampled onto.

Field	Type	Required	Description
calendar_coverage	CalendarCoveragePayload or null	no	Set only when the index's calendar could not cover the whole requested range, in which case levels spans covered_start to covered_end rather than the dates asked for. Null on an ordinary run, and on a comparator supplied as a bare level series, which has no calendar of its own. A range the calendar could cover none of refuses instead, so it never arrives here.
levels	SeriesPayload	yes
rebalances	array of RebalanceSnapshot	no	What each rebalance decided (applied weights, their uncapped counterparts and the announcement date), in date order; most recent MAX_REBALANCES at most. The same rows the run payload publishes, kept here because the record is what survives the job result. Empty for a comparator supplied as a bare level series, which decided nothing.
rebalances_total	integer	no	Rebalances the index actually had; larger than the rows served when the list was truncated. Default: 0.
reference_windows	map of string to array of ReferenceWindow or null	no	By identifier, the reference columns asked for with reference_fields over the weights panel's span, as windows with the dates they held, so any day of the panel reads the classification of its time. Null when none were asked for.
weights	TableFrame	yes	Daily weights, dates by identifier; most recent MAX_WEIGHT_DATES dates at most. Empty for a comparator supplied as a bare level series.
weights_dates_total	integer	yes	Dates the book's daily weights panel actually covers: a count, not a date. Larger than the rows in weights whenever the panel was truncated to its most recent MAX_WEIGHT_DATES, and 0 for a comparator supplied as a bare level series. rebalances_total says the same thing for rebalances.

CalendarCoveragePayload

The window asked for beside the one the calendar could offer.

Present only when the calendar narrowed the run, so its presence is the signal. A window the calendar covers nothing of never reaches a result at all: that refuses, because an empty index is a failure wearing a success.

Field	Type	Required	Description
calendar	string	yes	MIC of the calendar that narrowed the range.
covered_end	string	yes	Last date the calendar could speak for, ISO 8601.
covered_start	string	yes	First date the calendar could speak for, ISO 8601. The index has no level before this.
requested_end	string	yes	Last date the run asked for, ISO 8601.
requested_start	string	yes	First date the run asked for, ISO 8601. Not the date it produced; see covered_start.
trimmed_end	boolean	yes	Whether the calendar's published sessions stop before requested_end. A different remedy from trimmed_start: the sessions do not exist yet rather than not at all.
trimmed_start	boolean	yes	Whether the calendar's history does not reach back to requested_start. Published so a client never compares dates to find out; the remedy is a different calendar or a later base date.

CalendarList

Response of GET /indices/calendars.

IndexDocument.calendar is required, so this publishes the calendars the engine accepts, the way /indices/rule-types and /optimise/constraint-types publish theirs. It is read from exchange_calendars at request time, never a hand-kept copy, so the wire set cannot drift from the set the calculation schedules on.

Field	Type	Required	Description
calendars	array of CalendarOption	yes	Every exchange MIC this server can schedule against, sorted by code, each with what a picker needs to render it. Around a hundred entries; served whole rather than paged, because a picker wants all of them and the payload is a few kilobytes.
default	string	yes	The calendar code to preselect. The same value stored documents without a calendar were migrated to, so it is a reasonable default for a new index rather than an arbitrary one. It is a suggestion for the form, not a server-side fallback: IndexDocument.calendar has no default and omitting it is a 422.

CalendarOption

One selectable trading calendar, as GET /indices/calendars serves it.

Every field is derived from exchange_calendars at request time except name, which is curated and falls back to the code. Nothing here is a hand-kept table of the calendar set itself, so the options a client offers cannot drift from the calendars the schedule accepts.

Field	Type	Required	Description
code	string	yes	The exchange MIC, e.g. 'XNYS'. This is the value to send as IndexDocument.calendar; everything else on this row is for display.
name	string	yes	Display name, e.g. 'New York Stock Exchange'. Curated for the major venues only and falls back to code for the rest. exchange_calendars carries no friendly names, so a partial list that degrades to the MIC is the honest option. A row where name equals code is an uncurated calendar, not a broken one.
region	string	yes	Derived, not curated: the first segment of the calendar's own IANA timezone, so 'Europe/Oslo' gives 'Europe'. A noun as the tz database spells it; group headings are the client's wording, since 'Atlantic' and 'Pacific' have no distinct adjective and a mapping to one would be the hand-kept table this field exists to avoid. Two calendars sit on bare UTC and so report 'UTC', which is not a region; that is deliberate rather than a gap, and whether it becomes an 'Other' heading is the client's call.
tz	string	yes	The calendar's full IANA timezone, e.g. 'America/New_York'. Carried because region throws away the rest of it, and a client showing session times needs the whole zone.

CarryDecomposition

Carry split into the pieces a person can reason about.

Each part is the price effect of one rate acting alone. They do not sum to the total exactly, because carry compounds rather than adds; the residual is reported rather than spread across the parts, which would make each of them slightly wrong in order to hide that the split is approximate.

Field	Type	Required	Description
borrow	number	yes
dividend	number	yes	Negative: dividends reduce the forward.
financing	number	yes
residual	number	yes	Total minus the three parts: the compounding the decomposition cannot attribute.
total	number	yes	Fair value minus spot.

CashBandSpec

The shares of the book the cash may move between before it is brought back to the cash buffer.

Field	Type	Required	Description
lower	number	yes	The lowest share of the book in cash, a fraction.
upper	number	yes	The highest share of the book in cash, a fraction.

ChangelogEntryView

One release of the engine.

Field	Type	Required	Description
date	string or null	yes	Release date, YYYY-MM-DD. Null for Unreleased.
sections	array of ChangelogSectionView	yes	What changed, grouped by kind of change. Empty for an Unreleased entry with nothing in it yet.
summary	string or null	no	The release's one-paragraph summary, as markdown: the prose between its heading and its first section. Null when it has none.
version	string	yes	e.g. '0.1.0', or 'Unreleased'.

ChangelogResponse

Response of GET /changelog.

Field	Type	Required	Description
entries	array of ChangelogEntryView	yes	Newest first, leaving out any with no changes listed. With since, only the releases after that version.
version	string	yes	The running engine's version, the same value /health reports.

ChangelogSectionView

One heading under a release and its items.

Field	Type	Required	Description
heading	string	yes	Added, Changed, Fixed, Removed, Deprecated or Security.
items	array of string	yes	One change each, as markdown.

CodedColumn

A column of text sent once per distinct value.

Field	Type	Required	Description
codes	array of integer	yes	A row's value, as its position in values.
values	array of any	yes	Each distinct value.

ColumnarTable

A large table by column: each column a list of values, or, for repeated text, its distinct values and a code a row.

Field	Type	Required	Description
columns	map of string to CodedColumn or array of any	yes	Each column by name, in order: a list of values a row, or a coded column.
constant	object	no	Columns the same on every row, each sent once.
decimals	map of string to integer	no	The decimals each number column is rounded to.
length	integer	yes	How many rows it has.

ComparatorFigures

A comparator's own figures over a run's window, defined as a run's are.

Field	Type	Required	Description
annualised_return	number	yes	The total return a year.
hit_rate_monthly	number or null	no	The share of calendar months with a positive return.
max_drawdown	number	yes	Its largest fall from a peak.
sharpe_ratio	number	yes	The annualised return in excess of the risk-free rate, over the volatility.
total_return	number	yes	Over the window, from its first day's level.
volatility	number	yes	Of its daily returns, annualised.

CompareEntry

One strategy's latest run within a comparison, on the shared window.

Field	Type	Required	Description
level	SeriesPayload	yes	Rebased to 100 on the first shared date, so lines start together and the comparison is of shape, not scale.
strategy_id	string	yes	The strategy.
total_return	number	yes

CompareView

Response of GET /strategies/compare.

Field	Type	Required	Description
end	string	yes	Last date every index covers, YYYY-MM-DD. Resolved by the same intersection as start, which is the other end: one index whose run stops early pulls this back for all of them.
entries	array of CompareEntry	yes
observations	integer	yes	Dates every index covers. Fewer than any one of them carries alone whenever their spans differ.
start	string	yes	First date every run in strategy_ids covers, YYYY-MM-DD: the intersection of their level series, not the earliest start among them. Resolved: one index whose history begins later moves this forward for all of them, which is why each entry's level is rebased from here. Nothing was requested (GET /strategies/compare takes only ids), so there is no window to echo. end is the other end of the same shared span.
strategy_ids	array of string	yes	The strategies compared, as asked.

ComparisonNode

A field, an operator and a value: expressions.core.Comparison.

Field	Type	Required	Description
comparison	one of "gt", "ge", "lt", "le", "eq", "ne", "in", "between"	yes	How the field is compared to the value, spelled as the stored document spells it: gt, ge, lt, le, eq, ne, in, between.
field	FieldNode	yes	The datapoint being compared.
node	"comparison"	yes	Discriminator. Always 'comparison'.
value	any	yes

ComparisonPayload

A run against one comparator: the comparator's own figures and the run's relative to it, over the days both have.

Field	Type	Required	Description
end	string	yes	Its last day, YYYY-MM-DD.
id	string	yes	The index id, or the market-data identifier.
kind	string	yes	'index' or 'identifier'.
level	SeriesPayload	yes	The comparator rebased to 100 on the window's first day.
observations	integer	yes	Its days.
own	ComparatorFigures	yes	The comparator's own figures.
relative	RelativeFigures	yes	The run against it.
start	string	yes	The window's first day, YYYY-MM-DD.

ComparisonsPayload

A run against each of its comparators; null where it has none.

Field	Type	Required	Description
benchmark	ComparisonPayload or null	no	The request's external benchmark.
index	ComparisonPayload or null	no	The index the run tracked, or an active strategy's benchmark index. Its relative figures agree with the run's tracking error and tracking difference.

ConcentrationPayload

How concentrated a weight vector is.

Field	Type	Required	Description
constituents	integer	yes
effective_assets	number	yes	1/HHI: how many equally weighted names would be as concentrated. Lower than the raw count whenever weights are uneven.
herfindahl	number	yes	Sum of squared weights.
largest	number	yes	Largest single weight.
top_weights	map of string to number	yes	Combined weight of the largest N, keyed by N.

ConstituentRow

One constituent's row in the weights table.

Everything a row needs is here, so the table renders from one response rather than joining three. The two weights are the point: raw_weight is what the weighting scheme produced, weight is what survived the cap, and the difference is what capping moved.

Field	Type	Required	Description
active_risk_contribution	number or null	no	This name's share of tracking error. Can be negative: an underweight that hedges an overweight genuinely reduces tracking error, and hiding that behind an absolute value would misreport what the index is doing.
active_weight	number or null	no	Weight minus the benchmark's, when a benchmark was given. Negative is an underweight.
capped	boolean	no	Whether this name was held at the cap on this rebalance. Default: false.
delta_since_rebalance	number or null	no	Held weight minus target weight, for this name, as of as_of. Null when as_of is the rebalance date itself: the weights were just set, so nothing has drifted and a zero would claim a measurement rather than its absence.
identifier	string	yes
raw_weight	number	yes	Weight before capping. Equal to weight on an uncapped index, and the only way to see what the cap cost.
reference	object or null	no	The reference columns asked for with reference_fields, keyed in lower case, as they stood on this row's date. Null when the name had no reference row then.
risk_contribution	number or null	no	This name's share of the index's annualised volatility, in the same units. Populated only when risk=true was requested; null also when the risk model has no estimate for this constituent, which risk.uncovered lists.
shares_outstanding	number or null	no	The company's shares outstanding on this date, from market data. Deliberately NOT the number of shares the index holds: that is a different figure needing a divisor and a notional, and naming this one shares would let the two be confused silently.
weight	number	yes	Applied weight, after any cap.

ConstraintRow

One constraint, in the shape a client's editor holds it.

Maps 1:1 to a class in beacon.optimise.constraints: the row a user edits, the JSON that is stored and the object the solver receives are the same thing in three representations, so a rule cannot change meaning in translation.

Field	Type	Required	Description
id	string	no	Stable row id. Carried back on any binding constraint so a client can highlight the row that bound. Default: "".
params	object	no	Constructor arguments for that class, by name.
type	string	yes	Constraint class, e.g. 'PositionBounds'.

ConstraintRows

Optimiser constraints, one row each. The parameter's options names the family whose types the rows take.

Type: array of ConstraintRow

ConstraintSet

A named list of constraints.

Field	Type	Required	Description
constraints	array of ConstraintRow	no
id	string	yes	Stable identifier, used in the URL.
name	string	yes	Display name.

ConstraintSetCollection

Response of GET /optimise/constraint-sets.

Field	Type	Required	Description
constraint_sets	array of ConstraintSet	yes
skipped	integer	no	Stored documents the server could not read, and so left out of this listing. Non-zero means the collection is incomplete: the fault is logged server-side, and each skipped document answers 404 on its own route. Default: 0.
skipped_causes	SkippedCauses	no	The same documents as skipped, by cause, so the listing can say what to do about them. Its three counts sum to skipped.

ConstraintTypes

Response of GET /optimise/constraint-types.

Served so a client builds its editor from the same source the solver reads, rather than from a copy that drifts.

Field	Type	Required	Description
specs	array of TypeSpec	no	The same constraint types in the richer shape /indices/rule-types uses, so one client component can render both editors.
types	map of string to array of string	yes	Constraint type -> the parameters it accepts. The compact shape, kept for existing clients; specs carries the same set with everything needed to render it.

ContributionPayload

One constituent's share of the index return.

Field	Type	Required	Description
asset_id	string	yes
average_weight	number	yes
contribution	number	yes
reference	object or null	no	The reference columns asked for with reference_fields, keyed in lower case, as they stood on this row's date. Null when the name had no reference row then.
total_return	number	yes

CorporateAction

One corporate action.

kind is the authoritative answer to what value means, and the reason a client needs no list of type strings. Reading type and inferring cash or ratio from a hardcoded list works until a type the client has never seen arrives, at which point it renders as whichever the list defaults to: confidently, and wrongly.

Field	Type	Required	Description
ex_date	string	yes	Ex-date, ISO 8601.
kind	one of "cash", "ratio", "structural"	yes	What value means. 'cash' is an amount per share and adds up; 'ratio' is a share-count multiplier and compounds; 'structural' (rights issue, spin-off, merger) carries no directly aggregable value and should not be rendered as a quantity in either column.
pay_date	string (date) or null	no	Payment date, ISO 8601, where the source knows it. Null means unknown: omit the field in the UI rather than dashing it, since a dash reads as 'there is none'.
status	one of "announced", "paid", "cancelled" or null	no	Lifecycle state, where the source knows it. Null means unknown, not 'not yet announced'.
type	string	yes	Action type, e.g. DIVIDEND or SPLIT. A closed set the engine validates on load, but branch on kind rather than on this: new types are added, and a client that matches type strings breaks silently when one is.
value	number	yes	Cash amount per share for cash actions; a share-count multiplier for ratio actions. What it means depends on kind, so the two are never summed together.

CorporateActionsResponse

Response of GET /data/corporate-actions/{identifier}.

Carries the raw history and the two aggregates that need the whole series to compute, so a client asking "what did this pay" does not have to reimplement the trailing window and get its boundary subtly wrong.

Field	Type	Required	Description
actions	array of CorporateAction	no
cumulative_split_ratio	number	no	Compounded share-count multiplier across the returned window. 1.0 when there were no splits. Default: 1.0.
identifier	string	yes
trailing_dividend	number	no	Ordinary dividends per share over the twelve calendar months ending at the as-of date. Default: 0.0.
trailing_dividend_yield	number or null	no	Trailing dividend over the close on the as-of date. Null when no price is available, since a missing price is a reason to say nothing rather than to guess.

CountryRates

A rate for each two-letter country code, such as {"US": 0.15}, as a fraction.

Type: map of string to number

CoverageResponse

Response of GET /data/coverage.

Field	Type	Required	Description
cache_size_bytes	integer or null	no	Total bytes on disk for the whole store. Null when no store backs this process.
datasets	array of DatasetCoverage	yes
identifiers_union	integer	no	Distinct identifiers across every dataset. Not the sum of the per-dataset counts: a name present in both market and reference data would otherwise be counted twice, and 'assets covered' would exceed the universe. Default: 0.

DatasetCoverage

What the loaded data actually spans, for one dataset.

Field	Type	Required	Description
cache_age	number or null	no	Seconds since this dataset was last loaded or refreshed. Null when the dataset is not loaded at all, which is a different statement from 'loaded and never refreshed'.
cache_size_bytes	integer or null	no	Bytes the backing store occupies on disk. Null when the data did not come from a store, in which case it has no size to report rather than a size of zero.
configured	boolean	yes	Whether this dataset is loaded.
dataset	string	yes	'market' or 'reference'.
end	string or null	no	Latest date held, ISO 8601.
field_count	integer	no	Data columns this dataset holds, excluding the identifier and date keys. Default: 0.
frequency	string	no	How often this dataset is expected to change: 'daily', 'static' or 'event'. The engine's definition of what stale means, so a client renders staleness from this rather than from thresholds of its own. Default: "static".
identifiers	integer	yes	Distinct identifiers present.
last_refreshed	string or null	no	When this dataset was last loaded or refreshed, ISO 8601. Carried alongside the age because an age is only meaningful at the instant it was read, and a client holding a response for a minute needs the timestamp.
source	string or null	no	Where the data was loaded from, e.g. 'synthetic', 'yfinance', 'local'. Null when a fetcher was assembled in-process and nothing recorded a provenance.
stale_after_seconds	number or null	no	Age beyond which this dataset should read as stale. Published so the mapping from frequency to a duration lives in one place; null means the question does not apply, as for static data.
start	string or null	no	Earliest date held, ISO 8601.

DataSourceStatus

Whether data is loaded, how much, and from where.

Field	Type	Required	Description
configured	boolean	yes	True when data is loaded.
data_version	string	no	An opaque token that changes whenever the data being served changes: at startup, on every store load (the same store loaded again included), and when a refresh of the served store (POST /data/stores/{id}/refresh) finishes. Compare it for equality only: if it differs from the value a client cached against, the client's copy is stale. Never reused, even across engine restarts. The data.loaded and data.freshness events carry the new value. Default: "".
identifiers	integer	yes	Distinct identifiers in market data.
loading	boolean	no	True while a data store is being loaded. The data served until it finishes is the previous store's. Default: false.
store_id	string or null	no	The registered data store being served. Null when nothing is loaded, or when the data came from --data or BEACON_DATA_PATH rather than a registered store.
store_name	string or null	no	A name for what is being served: the store's name, or where unregistered data came from. Null when nothing is loaded.

DataStore

One registered data store.

Field	Type	Required	Description
active	boolean	yes	Whether this is the store the engine is serving.
connection	PostgresConnection or null	no	For a Postgres store, its connection details.
created_at	string	yes	When it was registered, ISO 8601 UTC.
id	string	yes	Stable id, from the name it was created with.
kind	one of "folder", "postgres"	yes	What the store is physically.
last_loaded_at	string or null	no	When the engine last loaded it, ISO 8601 UTC. Null if never.
managed	boolean	no	True for a store the engine created, such as generated synthetic data, in its own folder. Deleting a managed store deletes its files; deleting any other store only forgets it and leaves the folder alone. Default: false.
name	string	yes	Display name.
path	string	yes	Where the store is: a folder, or a database described without its password.
problem	StoreProblem or null	no	Why the store is not readable, when that is known: a store saved before py-beacon 0.7.0 has the code 'STORE_FORMAT_OUTDATED'. Null otherwise, including for a folder that was moved or deleted.
readable	boolean	yes	Whether the store can be read now. A folder that has been moved or deleted stays registered but is not readable, and nor is one saved in a format this version no longer reads (see problem).
refresh	one of "extend", "reread", "download" or null	no	What POST /data/stores/{id}/refresh would do: 'extend' synthetic data to today, 'reread' a folder or database, or 'download' from Yahoo Finance. Null when there is nothing to refresh: imported files (import again instead), synthetic data generated before py-beacon 0.2.0, or a store that cannot be read.
refresh_from	one of "source", "yfinance"	no	Where a refresh takes new data from. 'source' (the default) uses the store's own source: synthetic data is extended to today, a folder or database is read again. 'yfinance' downloads new prices for the store's instruments from Yahoo Finance and saves them into its folder; it needs the data extra, and only a folder store that is not synthetic data can choose it. Default: "source".
size_bytes	integer or null	no	Size of the store's files. Null when it cannot be read.
source	string or null	no	Where the rows came from, as the store records it: 'synthetic' for generated data, 'imported' for data loaded from files, 'yfinance' for downloaded prices, 'local' for a folder written another way. Null when the store cannot be read.

DataStoreCollection

Response of GET /data/stores.

Field	Type	Required	Description
active	string or null	no	The id of the store being served, or null when none is, or when the data came from --data or BEACON_DATA_PATH rather than a registered store.
skipped	integer	no	Stored documents the server could not read, and so left out of this listing. Non-zero means the collection is incomplete: the fault is logged server-side, and each skipped document answers 404 on its own route. Default: 0.
skipped_causes	SkippedCauses	no	The same documents as skipped, by cause, so the listing can say what to do about them. Its three counts sum to skipped.
stores	array of DataStore	yes	Every readable registered store, in name order.

DataStoreCreate

Body of POST /data/stores: register an existing store.

Field	Type	Required	Description
connection	PostgresConnection or null	no	For a Postgres database: where to connect.
kind	one of "folder", "postgres"	no	'folder' for a py-beacon data folder, 'postgres' for a database. Default: "folder".
name	string	yes	Display name, e.g. 'My data'. Also the basis of the store's id.
path	string or null	no	For a folder: its absolute path on the machine the engine runs on.
refresh_from	one of "source", "yfinance"	no	Where a refresh takes new data from. 'source' (the default) uses the store's own source: synthetic data is extended to today, a folder or database is read again. 'yfinance' downloads new prices for the store's instruments from Yahoo Finance and saves them into its folder; it needs the data extra, and only a folder store that is not synthetic data can choose it. Default: "source".

DataStoreUpdate

Body of PATCH /data/stores/{store_id}. Omitted fields are unchanged.

Field	Type	Required	Description
name	string or null	no	The new display name. The id does not change.
refresh_from	one of "source", "yfinance" or null	no	Where a refresh takes new data from. 'source' (the default) uses the store's own source: synthetic data is extended to today, a folder or database is read again. 'yfinance' downloads new prices for the store's instruments from Yahoo Finance and saves them into its folder; it needs the data extra, and only a folder store that is not synthetic data can choose it.

DatedAmounts

An amount for each date (YYYY-MM-DD), in the book's currency, positive in and negative out.

Type: map of string to number

DeletedIndex

One index a delete removed, and what went with it.

Field	Type	Required	Description
derived_from	string or null	no	The index this one was derived from, when it went as an optimised child. Null for the index the request named.
index_id	string	yes	The index that was removed.

DerivationPayload

How an optimised index is derived from the index it was built on.

The whole of an optimised index's methodology: the source it reallocates, what the solve minimises, and what the answer must satisfy. No weights (neither the parent's nor the solved ones), because definitions are rules and weights are calculated.

Field	Type	Required	Description
constraints	array of ConstraintRow	no	What the solved weights must satisfy: exactly the rows /optimise/constraint-sets stores, so one editor serves both. Empty leaves the solver's own full-investment default.
objective	string	no	What the solve minimises. Accepted values: min_tracking_error. A plain string rather than an enum so a risk-model objective can be added without a wire break; an unknown value is refused with a finding naming the accepted set. Default: "min_tracking_error".
source_index_id	string	yes	Id of the index this one optimises. Immutable after creation: re-pointing a derivation is a new index, not an edit, so an update that changes it is refused.

DriftPayload

How far weights moved between two rebalances.

Field	Type	Required	Description
maximum	number	yes	Largest single move.
since	string	yes	The rebalance drifted from.
total_absolute	number	yes	Sum of absolute weight changes.
turnover	number	yes	Half the total: the one-way trading needed to return to target, since every overweight funds an underweight.
worst	string	yes	Constituent that moved most.

ErrorDetail

The body of an error envelope.

Field	Type	Required	Description
code	string	yes	Stable machine-readable code; safe to branch on.
detail	object or null	no	Structured context, e.g. the offending field or rule. An UNEXPECTED_CALCULATION_FAILURE additionally carries 'original_type': the class name of the exception that failed, so a crash can be told apart from a refusal without reading a server log.
message	string	yes	Human-readable summary.

ErrorEnvelope

Every non-2xx response uses this shape.

Field	Type	Required	Description
error	ErrorDetail	yes

ExposuresView

Response of GET /optimise/runs/{run_id}/exposures.

Factors are the ones derivable from price and share count (size, momentum, volatility), plus a market intercept. Value and quality are absent rather than approximated: a momentum factor built from prices is the real thing, a value factor faked without book values would not be.

Field	Type	Required	Description
active_exposures	array of FactorExposure	yes
factors	array of string	yes
index_exposures	array of FactorExposure	yes
optimal_exposures	array of FactorExposure	yes
r_squared	number	yes	Read against a floor of roughly k/n rather than against zero: fitting k factors to an n-asset cross-section explains about that much by construction.
risk	RiskDecomposition	yes
run_id	string	yes

ExpressionNode

One node of a serialised expression, discriminated on node.

The grammar a screen is written in: a field, a comparison over one, or a boolean composition of either. Recursive (all, any and not carry nodes of this same union), so an arbitrarily nested screen is one type.

A RootModel rather than a bare union so the union is a named schema in this document: a recursive $ref needs a name to point at, and so does ParameterSpec.ref.

Type: FieldNode or ComparisonNode or AllNode or AnyNode or NotNode

FactorExposure

One factor loading.

Field	Type	Required	Description
exposure	number	yes
factor	string	yes

FactorSignals

Each factor by a name of your choosing, as a signal whose scores are the names' exposures to it. The parameter's options names the family the signals' types come from.

Type: map of string to TypedSpec

FactorTargets

A target active exposure, in scores, for each factor named in the construction's factors. A factor with no target is aimed at zero.

Type: map of string to number

FeatureBatchEntry

One instrument in a batch feature response.

Field	Type	Required	Description
features	array of FeatureValue	yes
identifier	string	yes

FeatureBatchResponse

Response of GET /data/features.

Field	Type	Required	Description
as_of	string	yes	The cutoff the features were read at, YYYY-MM-DD: the date query echoed back unchanged, or the last date the loaded market data carries when none was given. Never resolved back (a request for a weekend stays a weekend), because each feature independently takes the latest row published on or before it. What was actually read is each entries[].features[].date, the announcement date of the row that answered, which is usually earlier than this and differs from feature to feature. FeatureResponse.as_of is the same field on the single-instrument endpoint.
entries	array of FeatureBatchEntry	yes

FeatureCatalogue

Response of GET /data/features/catalogue.

What a client populates its controls from. Derived from the loaded data rather than a fixed vocabulary, so a dataset somebody loads tomorrow becomes a filter without a code change.

Field	Type	Required	Description
fields	array of string	yes	Every field across every dataset. Names collide where two datasets carry the same one, which is why the per-type lists above exist.
types	array of FeatureTypeCoverage	yes

FeatureImport

Body of POST /data/features.

Field	Type	Required	Description
rows	array of FeatureRow	yes	Field-value rows. Merged into whatever is already loaded; a row matching an existing identifier, date, type and field replaces it.

FeatureImportResult

What an import did.

Field	Type	Required	Description
accepted	integer	yes
data_version	string or null	no	The engine's data_version after the import. It changes on every import, and a data.freshness event for the features dataset carries the same value.
identifiers	integer	yes
saved	boolean	no	Whether the rows were written into the served data store, so they survive a restart and a reload. True for a folder store. False for a Postgres store, which is read-only, and for data not registered as a store: there the rows are served until the engine stops or other data is loaded. Default: false.
types	array of string	yes	Datasets the import touched.

FeatureResponse

Response of GET /data/features/{identifier}.

Field	Type	Required	Description
as_of	string	yes	The cutoff the features were read at, YYYY-MM-DD: the date query echoed back unchanged, or the last date the loaded market data carries when none was given. Never resolved back (a request for a weekend stays a weekend), because each feature independently takes the latest row published on or before it. What was actually read is each features[].date, the announcement date of the row that answered, which is usually earlier than this and differs from feature to feature. FeatureBatchResponse.as_of is the same field on the batch endpoint.
features	array of FeatureValue	yes
identifier	string	yes

FeatureRow

One row of an import.

Field	Type	Required	Description
date	string (date)	yes	Calendar date, YYYY-MM-DD.
detail	string or null	no
field	string	yes
identifier	string	yes
type	string	yes
value	number	yes

FeatureTypeCoverage

One feature dataset, and how much of it is present.

Field	Type	Required	Description
fields	array of string	yes
identifiers	integer	yes	Instruments this dataset covers.
rows	integer	yes
type	string	yes

FeatureValue

One field and what it was worth.

Field	Type	Required	Description
date	string or null	no	When the value became knowable: the announcement date, not the period it describes.
detail	string or null	no	Free-form context the dataset carried.
field	string	yes
type	string or null	no	Which dataset it came from.
value	number or null	yes	Null when nothing was knowable on the date: no coverage, nothing published yet, or nothing recent enough.

FieldCatalogue

Response of GET /data/fields.

Every datapoint an expression can name, from one place, so a client builds one field picker rather than one per dataset. Derived from the loaded store, so a column or dataset nobody declared still appears.

Field	Type	Required	Description
fields	array of FieldDescriptor	yes
namespaces	array of string	yes

FieldDescriptor

One datapoint a client can offer as a filter.

Field	Type	Required	Description
dataset	string or null	no	Feature TYPE, for feature fields only.
derived	boolean	no	Computed per request rather than stored. Screenable either way; a client should not have to care. Default: false.
label	string	no	What a column chooser shows for it. Default: "".
name	string	yes
namespace	string	yes	market, reference, actions or features.
path	string	yes	How it is written, e.g. 'reference.sector' or 'features.fundamentals.revenue'.

FieldNode

A named datapoint: expressions.core.Field.

namespace is the surface the value comes from and dataset narrows a feature to one vendor's TYPE, so two sources can both ship a revenue without collision.

Field	Type	Required	Description
dataset	string or null	no	Narrows a feature to one dataset. Null on a reference or market field, which have no dataset to narrow.
name	string	yes	The datapoint's name.
namespace	string	yes	The surface the datapoint comes from: 'reference', 'market' or 'features'. GET /data/fields lists what each one holds.
node	"field"	yes	Discriminator. Always 'field'.

Finding

One validation result, addressable to the rule that caused it.

Field	Type	Required	Description
code	string	yes	Stable machine-readable code.
message	string	yes	Human-readable explanation.
path	string	yes	Dotted path to the offending field.
rule_id	string or null	no	Id of the rule responsible, when there is one.
severity	string	yes	'error' blocks saving; 'warning' does not.

FlowPayload

One day's flow, as the run dealt it.

Field	Type	Required	Description
adjustment	number	yes	What the dealing investors paid into the fund through the price or a levy, in the book's currency.
amount	number	yes	Paid in (positive) or out (negative), in the book's currency.
creation_units	number or null	no	For an ETF, the creation units; null otherwise.
date	string	yes	YYYY-MM-DD.
dealing_price	number	yes	The price per unit dealt at, after the vehicle's pricing.
nav_per_unit	number	yes	The day's NAV per unit, before it.
units	number	yes	Units created (positive) or cancelled.

FrontierPoint

One portfolio on the efficient frontier.

Field	Type	Required	Description
binding	array of string	no
expected_return	number or null	no
heuristic	boolean	no	Default: false.
sharpe_ratio	number or null	no
volatility	number	yes
weights	map of string to number	yes

FrontierView

Response of GET /optimise/runs/{run_id}/frontier.

Field	Type	Required	Description
expected_returns	map of string to number	yes	Annualised historical mean returns, per name. A poor forecast, and the honest one: it is the only return estimate derivable from the data the server holds. A caller with a real view should supply it.
minimum_variance	FrontierPoint	yes
monotonic	boolean	yes	Whether risk rises with return across the grid. Always true for a correct solve, so a false here means a point did not reach optimality.
points	array of FrontierPoint	yes
reference	map of string to object or null or null	no	By identifier, the reference columns asked for with reference_fields, keyed in lower case, as they stood on this date; null for a name with no reference row then. Null when the response carries none.
risk_free_rate	number	yes
run_id	string	yes
tangency	FrontierPoint	yes

FuturesPriceRequest

Body of POST /derivatives/futures/price.

Stateless: every input the calculation needs is here, and nothing is read from or written to storage.

Field	Type	Required	Description
borrow_cost	number	no	Continuous borrow or financing spread. Default: 0.0.
contract_multiplier	number	no	Index points per contract. Default: 1.0.
contracts	number	no	Number of contracts. Default: 1.0.
curve	map of string to number or null	no	Zero-rate pillars as {tenor_in_years: rate}. A flat curve and a scalar rate give identical answers, so supplying one changes nothing unless the curve has shape.
dividend_yield	number	no	Continuous dividend yield. Default: 0.0.
dividends	array of array of any or null	no	Discrete cash dividends as (years_to_ex, amount). When present these are used instead of the continuous yield: the two are different models of the same thing and applying both would double-count.
expiry	string (date) or null	no	YYYY-MM-DD.
grid_rates	array of number or null	no	Columns of the sensitivity grid.
grid_tenors	array of number or null	no	Rows of the sensitivity grid, in years.
market_price	number or null	no	Quoted price, for the basis and implied repo. Both are null without one rather than computed against the theoretical value, which would make them identically zero.
risk_free_rate	number	no	Continuously compounded financing rate. Ignored when curve is supplied. Default: 0.0.
spot	number	yes	Spot price of the underlying.
time_to_expiry	number or null	no	Years to expiry. Dates win when both are given, being the less ambiguous statement.
valuation_date	string (date) or null	no	YYYY-MM-DD.

FuturesPriceResponse

Response of POST /derivatives/futures/price.

Field	Type	Required	Description
basis	number or null	no	Market minus theoretical, when quoted.
carry	CarryDecomposition	yes
contract_value	number	yes	Fair value times multiplier times contracts.
fair_value	number	yes
financing_rate	number	yes	Rate used, read off the curve.
implied_repo	number or null	no	Financing rate the quoted price implies, when quoted.
market_price	number or null	no
sensitivity	TableFrame	yes	Fair value across a tenor x rate grid, centred on this contract.
time_to_expiry	number	yes	Years the contract was priced over, ACT/365: what the calculation used, which is not always what the request sent. Computed from valuation_date to expiry when both were given, dates being the less ambiguous statement; the request's own time_to_expiry is echoed back only when the dates were omitted. Nothing is resolved against market data; this endpoint reads none.

FuturesRollPayload

One roll of a fund's index futures to the next contract.

Field	Type	Required	Description
contracts	number	yes	Contracts held of it, so the contracts times the price times the multiplier is the notional. Whole unless the run holds fractional contracts.
cost	number	yes	What the roll cost, paid from cash.
date	string	yes	YYYY-MM-DD.
dividend_yield	number	yes	The dividend yield it was priced with.
expiry	string	yes	The new contract's expiry, YYYY-MM-DD.
multiplier	number	no	The value of one index point per contract, in the book's currency. Default: 1.0.
notional	number	yes	The exposure carried into it, in the book's currency.
price	number	yes	The new contract's price, at fair value.

GenerateJobStatus

A generate:{store_id} job. result describes the new store.

Field	Type	Required	Description
error	ErrorDetail or null	no	Failure reason, when status is failed; null otherwise. The same {code, message, detail} a non-2xx response carries, and the same schema, so a failed job branches on error.code exactly as an HTTP error does. A job recorded by an older engine carries UNCLASSIFIED_FAILURE: its message was recorded, its code was not, and the migration does not guess one.
job_id	string	yes	The job's id: poll GET /jobs/{job_id}, or watch it on the event socket.
kind	string	yes	What the job is, e.g. 'backtest'.
message	string	no	Latest progress message. Default: "".
progress	number	yes	Fraction complete, 0.0 to 1.0.
result	GenerateResult or null	no	Present only once the job has succeeded; null otherwise.
status	string	yes	pending, running, succeeded, failed or cancelled. The last three are terminal.

GenerateResult

Result payload of a completed generate:{store_id} job.

Field	Type	Required	Description
activated	boolean	yes	Whether the engine is now serving it.
name	string	yes	Its display name.
path	string	yes	The folder the engine wrote it to.
store_id	string	yes	The new store's id.

GenerateSyntheticRequest

Body of POST /data/synthetic: generate a synthetic data store.

Every field is optional. Anything left out takes the same default as python -m beacon.synthetic, because the engine runs that command: the same settings always give the same data, whichever way it was made.

Field	Type	Required	Description
activate	boolean	no	Serve the new store as soon as it is written. Default: true.
assets	integer or null	no	How many names. Default 6,000, or 10,000 with extended_universe.
calendar	string or null	no	Exchange code whose trading days the data has prices on. Default XNYS.
end	string (date) or null	no	Last date. Default today.
equity_premium	number or null	no	Annualised excess return on a beta-one name, as a decimal.
extended_universe	boolean	no	10,000 names instead of 6,000. Ignored when assets is given. Default: false.
features	boolean	no	Include fundamental ratios and alternative data. Default: true.
long_history	boolean	no	Reach back to cover every crisis the generator models. Ignored when start is given. Default: false.
name	string	no	Display name for the new store. Default: "Synthetic data".
risk_free_rate	number or null	no	Annualised, as a decimal.
seed	integer or null	no	Everything random is drawn from this, so the same seed and settings always give the same data.
start	string (date) or null	no	First date. Default ten years before end, or the start of the crises the generator models with long_history.

GroupingFields

Reference fields to group names by, such as ["region", "sector"]: each name is centred within the group its values put it in.

Type: array of string

HealthResponse

Response of GET /health.

Field	Type	Required	Description
cache_age	number or null	no	Seconds since the market data being served was loaded. Loading a store and refreshing the served one both reset it. Null only when no data source is configured, since there is then nothing whose age could be reported.
data_source	DataSourceStatus	yes
free_float_backfill_days	integer or null	no	How many days a free float carries forward over days with no reported value. Beyond it a float-adjusted index refuses rather than weight the name by its full market cap. 0 uses only a value dated that day; the default is 90. A modelling choice: it decides which float a name is weighted by. Null when no data source is configured.
fx_policy	string or null	no	How this installation reads an exchange rate on a day the pair printed none: CARRY_FORWARD uses the last rate in force, EXACT_DAY refuses unless the rate is dated that day. A modelling assumption rather than a preference: the same holding converts to different money under the two, and every conversion in the library obeys whichever is set. Null when no data source is configured, since nothing is being converted.
max_price_staleness_days	integer or null	no	How long a name may go without trading before this installation drops it from an index and from a backtest's targets. Null means keep everything regardless, which is the default. A modelling choice, not a preference: it changes index membership, so two runs either side of a change are different indices. Also null when no data source is configured.
status	string	yes	'ok' when the process is serving.
version	string	yes	Installed py-beacon version.

HedgePayload

One trade of a hedged class's forward.

Field	Type	Required	Description
date	string	yes	YYYY-MM-DD.
kind	string	yes	What it did: 'open', 'roll' (a new month) or 'band' (the hedge ratio left its band).
notional	number	yes	The new forward's notional, in the book's currency.
rate	number	yes	Its contracted rate, class currency per unit of the book's.
reason	string	yes	Why it was made: 'fx hedge'.
settled	number	yes	What the old forward settled for, in the class's currency; 0 when one was opened.

HoldingRow

One name's way through the workflow at the rebalance in force.

Field	Type	Required	Description
benchmark_weight	number or null	no	Its weight in the backtest's benchmark index; null without one, or for a name it does not hold.
current_weight	number or null	no	Its weight in the book as of as_of.
excluded_at	string or null	no	The key of the stage it left at; null for a name still in the book.
identifier	string	yes	The name.
implementation	map of string to number or null	no	By implementation stage key, the weight it carried after that stage; null after the stage that removed it.
index_weight	number or null	no	Its index weight after the index's cap.
index_weight_uncapped	number or null	no	Its index weight before the index's cap.
portfolio_weight	number or null	no	The weight the rebalance traded to.
reference	object or null	no	The reference columns asked for with reference_fields, as of as_of, keyed in lower case; null when the name had no reference row then.
shares_held	number or null	no	The units of it the book held as of as_of.
strategy_weight	number or null	no	What the strategy chose before the implementation: the index weight for a strategy that holds its index, the replication's or the construction's otherwise.
universe_weight	number or null	no	Its share of the universe's total market cap at the rebalance. A universe has no weighting of its own, so this is its free-float market cap over the universe's total where the index weights by free-float market cap, its full market cap otherwise. Null when it has no cap that day.
weight_drift	number or null	no	Its held weight less its portfolio weight as of as_of; null on the rebalance date itself.

HoldingStage

One step of the workflow, in order.

Field	Type	Required	Description
description	string	no	One plain sentence of what the stage does with its settings, to show as written. Default: "".
key	string	yes	What a row's excluded_at and implementation name it by: a rule's id, a screen's type, or the kind for the single steps.
kind	string	yes	One of universe, index_rule, index_cap, strategy, implementation_screen, cash_buffer, implementation_cap.
label	string	yes	What a column header reads, such as 'Minimum price'.
params	array of StageParam	no	Its settings, labelled and formatted.
remaining	integer	yes	How many names are left after it.
type	string	no	The stage's class, or its kind for a step that has none. Default: "".

HoldingsView

Response of GET /strategies/{strategy_id}/holdings.

Field	Type	Required	Description
as_of	string	yes	The date asked about, YYYY-MM-DD.
cash_weight	number or null	no	The share of the book the rebalance left in cash.
index_id	string	yes	The index it holds.
rebalance_date	string	yes	The rebalance in force on as_of.
rebalance_dates	array of string	yes	Every rebalance of the run, in order.
rows	array of HoldingRow	yes	One per name in the universe at the rebalance, those that left included, then any name held that the universe did not name.
stages	array of HoldingStage	yes	The workflow's steps, in order.
strategy_id	string	yes	The strategy whose latest run this reads.

IdentifierList

Instrument identifiers, such as those GET /data/identifiers finds.

Type: array of string

IdentifierMatch

One identifier a search or enumeration returned.

Field	Type	Required	Description
currency	string or null	no	Denomination, when reference data has one.
datasets	array of string	no	Which datasets actually cover this identifier: 'market', 'reference', 'corporate_actions'. This is what lets a client offer a reference-only name in a reference view and mark it unavailable for prices, rather than suggesting something the engine cannot then serve.
exchange	string or null	no	Listing venue, when reference data has one.
identifier	string	yes	The symbol itself.
name	string or null	no	Display name, or null when reference data carries none. A row without a name is still a useful suggestion, so it is returned rather than dropped.

IdentifierSearchResponse

Response of GET /data/identifiers.

Search when q is given, enumeration when it is not.

Ranking is decided server-side and is part of the contract: exact identifier, identifier prefix, name prefix, identifier substring, name substring, alphabetical within each. Once limit is applied a client cannot re-rank what it was not sent.

Field	Type	Required	Description
identifiers	array of IdentifierMatch	no
total	integer	no	Matches before limit, so a client can say 'showing 20 of 340'. Default: 0.
truncated	boolean	no	Whether the limit hid anything. Derivable from total, but explicit beats arithmetic at a call site. Default: false.
version	string	no	Fingerprint of the data this was built from, also served as the ETag. Changes only when the served data changes (a store load or refresh, or a feature import), so a client can cache an enumeration and revalidate cheaply. Default: "".

IdentifierValues

A number for each identifier. The parameter's help says what the numbers are, and whether they are scaled to add up to one.

Type: map of string to number

ImplementationSpec

How the strategy is carried out at the fund's size.

Field	Type	Required	Description
caps	array of TypedSpec	no	How much of each may be held.
cash_band	CashBandSpec or null	no	Checked every day between rebalances: cash above upper is invested down to cash_buffer, and cash below lower raised back up to it by selling pro rata. lower <= cash_buffer <= upper. Null leaves the cash to the next rebalance.
cash_buffer	number	no	The share of the book kept in cash, a fraction. Default: 0.0.
equitise	object or null	no	Index futures held on the uninvested cash, so the buffer earns the index's return: roll_days, roll_cost_bps, dividend_yield (null to estimate it), multiplier (the value of an index point per contract, 50 by default), whole_contracts (true by default), band (how far the exposure may drift from the cash before the futures are resized, as a share of the net assets; 0.0025 by default), cost_per_contract (each contract traded, in the book's currency), trading_cost_bps (on the notional of each trade between rolls), underlying (a market series the futures are on, when not the fund's index), prices (a series of the held contract's prices) and the assumed mispricing when there are none: mispricing_bps (its standard deviation, 0 by default), mispricing_half_life (sessions, 10 by default) and mispricing_seed. Null leaves the cash as cash.
execution	map of string to number or null or null	no	Execution limits: participation (a fraction of the day's volume), days and lookback_days. Null to trade every order on the rebalance day.
impact	map of string to number or null	no	Market impact: coefficient and lookback_days. Null for none.
invest_flows	string	no	What money arriving between rebalances buys: 'target' (the last rebalance's weights) or 'holdings'. Default: "target".
minimum_position	map of string to number or null or null	no	Positions too small to keep: value (money, in the book's currency) and weight (a fraction).
redistribution	string	no	Where removed or capped weight goes: 'pro_rata' or 'cash'. Default: "pro_rata".
screens	array of TypedSpec	no	Which names may be held.

ImportRequest

Body of POST /data/import: load CSV files or an Excel workbook.

Field	Type	Required	Description
activate	boolean	no	Load the new store as soon as it is saved. Default: true.
name	string	no	Display name for the new store. Default: "Imported data".
paths	array of string	yes	Absolute paths on the machine the engine runs on: CSV files named after their sheet (market.csv, reference.csv, ...), or one Excel workbook with those sheets. GET /data/import/template has the layout.

ImportResult

Response of POST /data/import.

Field	Type	Required	Description
load_job	LoadJobStatus or null	no	The job loading it, when activate was set and no other load was running. Null otherwise: the store is saved and can be activated later.
store	DataStore	yes	The new store, saved and registered.

IndexBooksPayload

The run's calculated indices on the wire.

Mirrors the library's IndexBooks: target is the index being aimed at, pre-optimisation; optimised is the solved index's own calculation, null until an optimised run fills it.

Field	Type	Required	Description
optimised	BookPayload or null	no
target	BookPayload or null	no

IndexCollection

Response of GET /indices.

Field	Type	Required	Description
indices	array of IndexDocument	yes
skipped	integer	no	Stored documents the server could not read, and so left out of this listing. Non-zero means the collection is incomplete: the fault is logged server-side, and each skipped document answers 404 on its own route. Default: 0.
skipped_causes	SkippedCauses	no	The same documents as skipped, by cause, so the listing can say what to do about them. Its three counts sum to skipped.

IndexDeletion

Response of DELETE /indices/{index_id}.

Everything the delete removed, so a client reports the outcome from the response rather than from its own prediction of the blast radius. The named index comes first, then each optimised child in the order the cascade reached it.

Field	Type	Required	Description
deleted	array of DeletedIndex	yes
index_id	string	yes	The index the request named.

IndexDocument

A stored index definition, in one of its two faces.

A document carries either a rule pipeline (pipeline and universe) or a derivation, never both and never neither. derivation is the discriminator: present, the index is optimiser-derived and its methodology is the derivation; absent, it is a rule pipeline over a universe.

Field	Type	Required	Description
base_date	string	yes	Base date, YYYY-MM-DD.
base_value	number	yes	Index level on the base date.
calendar	string	yes	Exchange MIC backing trading-day arithmetic, e.g. 'XNYS'. Required: every index schedules against a real exchange calendar, so rebalances never land on days no exchange has a session for. Stored documents without one are read as 'XNYS' (schema version 2 migrates them). GET /indices/calendars publishes every value this server accepts, read from the calendar package itself, so a client renders a closed list instead of guessing a MIC.
currency	string	yes	Index currency.
derivation	DerivationPayload or null	no	Present on an optimiser-derived index, null on a rule-driven one. Its presence is the discriminator a client branches on.
description	string or null	no
effective_lag_sessions	integer	no	Sessions between a rebalance being announced and its weights taking effect, counted on the index's calendar. 0, the default, means the weights take effect on the announcement date. Default: 0.
id	string	yes	Stable identifier, used in the URL.
name	string	yes	Display name.
pipeline	PipelineSpec or null	no	The rule pipeline. Present on a rule-driven index, null on an optimiser-derived one.
publication_time	string or null	no	When the level is published, e.g. '18:00 America/New_York'. Display metadata: it says when a figure is released and changes no figure, so nothing in the calculation reads it.
rebalance_day_rule	string	no	Which day of a scheduled month the rebalance falls on: FIRST_BUSINESS_DAY, LAST_BUSINESS_DAY or THIRD_FRIDAY. A date landing on a holiday rolls back to the previous session. Default: "FIRST_BUSINESS_DAY".
rebalancing_frequency	string	yes	MONTHLY, QUARTERLY, SEMI-ANNUAL or ANNUAL. The cadence; rebalance_day_rule decides which day of the month.
return_type	one of "PRICE", "TOTAL_RETURN", "NET_TOTAL_RETURN"	no	How returns accumulate. PRICE ignores distributions; TOTAL_RETURN reinvests them across the index by shrinking the divisor; NET_TOTAL_RETURN does the same after withholding tax. PRICE is the default. Default: "PRICE".
universe	UniverseRef or null	no	The investable set. Present on a rule-driven index, null on an optimiser-derived one, which reallocates exactly the names its source published.
withholding_tax_rate	number	no	Fraction of each distribution withheld, for a net index. A flat index-level rate rather than a per-country table: a table is only as good as the country field behind it, and an unpopulated one produces a number that looks precise and is not. Ignored unless return_type is NET_TOTAL_RETURN. Default: 0.0.

IndexLevelView

Response of GET /indices/{index_id}/level.

Field	Type	Required	Description
currency	string	yes	The currency its level is in.
end	string	yes	Last date calculated, YYYY-MM-DD.
index_id	string	yes	The index calculated.
level	SeriesPayload	yes	The index level as calculated, from its base value.
metrics	BacktestMetrics	yes	The level's total and annualised return, volatility, Sharpe ratio and maximum drawdown, defined as a backtest's are; the tracking and fund figures are null.
name	string	yes	Its display name.
rebalances	array of RebalanceSnapshot	yes	The weights at each rebalance in the window, in date order.
start	string	yes	First date calculated, YYYY-MM-DD.

JobCollection

Response of GET /jobs.

Untyped results on purpose: a listing spans every kind at once, so the per-kind arms buy a client nothing it can use without reading kind anyway. GET /jobs/{job_id} is where the typed result lives.

Field	Type	Required	Description
jobs	array of JobStatus	yes
skipped	integer	no	Stored documents the server could not read, and so left out of this listing. Non-zero means the collection is incomplete: the fault is logged server-side, and each skipped document answers 404 on its own route. Default: 0.
skipped_causes	SkippedCauses	no	The same documents as skipped, by cause, so the listing can say what to do about them. Its three counts sum to skipped.

JobStatus

State of one background job, with an untyped result.

Used for a listing, which mixes kinds, and as the fallback arm of AnyJobStatus for a kind nothing models yet.

Field	Type	Required	Description
error	ErrorDetail or null	no	Failure reason, when status is failed; null otherwise. The same {code, message, detail} a non-2xx response carries, and the same schema, so a failed job branches on error.code exactly as an HTTP error does. A job recorded by an older engine carries UNCLASSIFIED_FAILURE: its message was recorded, its code was not, and the migration does not guess one.
job_id	string	yes	The job's id: poll GET /jobs/{job_id}, or watch it on the event socket.
kind	string	yes	What the job is, e.g. 'backtest'.
message	string	no	Latest progress message. Default: "".
progress	number	yes	Fraction complete, 0.0 to 1.0.
result	any	no	Present only once the job has succeeded; null otherwise.
status	string	yes	pending, running, succeeded, failed or cancelled. The last three are terminal.

LoadJobStatus

A load:{store_id} job. result describes the store now served.

Field	Type	Required	Description
error	ErrorDetail or null	no	Failure reason, when status is failed; null otherwise. The same {code, message, detail} a non-2xx response carries, and the same schema, so a failed job branches on error.code exactly as an HTTP error does. A job recorded by an older engine carries UNCLASSIFIED_FAILURE: its message was recorded, its code was not, and the migration does not guess one.
job_id	string	yes	The job's id: poll GET /jobs/{job_id}, or watch it on the event socket.
kind	string	yes	What the job is, e.g. 'backtest'.
message	string	no	Latest progress message. Default: "".
progress	number	yes	Fraction complete, 0.0 to 1.0.
result	LoadResult or null	no	Present only once the job has succeeded; null otherwise.
status	string	yes	pending, running, succeeded, failed or cancelled. The last three are terminal.

LoadResult

Result payload of a completed load:{store_id} job.

Field	Type	Required	Description
end	string or null	no	Latest date held, ISO 8601.
identifiers	integer	yes	Distinct identifiers in its market data.
name	string	yes	Its display name.
start	string or null	no	Earliest date held, ISO 8601.
store_id	string	yes	The store now being served.

MarketPayload

An ETF's quotes on the exchange, on level's dates.

Field	Type	Required	Description
ask	SeriesPayload	yes
bid	SeriesPayload	yes
market_price	SeriesPayload	yes
premium	SeriesPayload	yes	Over NAV, a fraction; negative for a discount.
spread	SeriesPayload	yes	Full bid-ask, a fraction of the price.

ModellingAssumptionsSpec

What the run takes as given about markets and data. Every field is optional; an unset one takes the engine's default, which /backtest/options lists.

Field	Type	Required	Description
cash_rate	number or null	no	The annual rate cash earns, a fraction, ACT/365.
free_float_backfill_days	integer or null	no	Calendar days a reported free float carries over blanks.
fx_policy	string or null	no	The FX rate on a day a pair printed none: CARRY_FORWARD or EXACT_DAY.
max_price_staleness_days	integer or null	no	Calendar days a name may go without trading before it is dropped as stale; 0 is no limit.
periods_per_year	integer or null	no	How many periods make a year.
risk_free_rate	number or null	no	The annual rate the Sharpe ratio is measured against.
volume_backfill_days	integer or null	no	Calendar days a reported volume stands in for a blank one under an execution limit.
withholding_tax_rate	number or null	no	The share of each dividend withheld, a fraction.

NotNode

The negation of an expression: expressions.core.Not.

Field	Type	Required	Description
node	"not"	yes	Discriminator. Always 'not'.
operand	ExpressionNode	yes

OptimisationJobStatus

An optimise:{run_id} job. result is the solved portfolio.

Field	Type	Required	Description
error	ErrorDetail or null	no	Failure reason, when status is failed; null otherwise. The same {code, message, detail} a non-2xx response carries, and the same schema, so a failed job branches on error.code exactly as an HTTP error does. A job recorded by an older engine carries UNCLASSIFIED_FAILURE: its message was recorded, its code was not, and the migration does not guess one.
job_id	string	yes	The job's id: poll GET /jobs/{job_id}, or watch it on the event socket.
kind	string	yes	What the job is, e.g. 'backtest'.
message	string	no	Latest progress message. Default: "".
progress	number	yes	Fraction complete, 0.0 to 1.0.
result	OptimisationRunResult or null	no	Present only once the job has succeeded; null otherwise.
status	string	yes	pending, running, succeeded, failed or cancelled. The last three are terminal.

OptimisationRunRequest

Body of POST /optimise/runs: the weights a target held on a date, solved for under a constraint set.

The target is an index or a stored strategy, exactly one of the two. An index's weights are calculated, so no backtest is needed; a strategy's are what its latest run chose at that rebalance, so an active strategy's answers how close a portfolio can get to it under the constraints.

Field	Type	Required	Description
as_of	string or null	no	Which rebalance to target, YYYY-MM-DD. Defaults to the latest.
constraint_set_id	string	yes	Constraint set to solve under.
end	string or null	no	End of that window.
index_id	string or null	no	An index whose weights are the target.
risk_free_rate	number	no	Used for the frontier's tangency point. Default: 0.0.
start	string or null	no	Start of the window the risk model is estimated over.
strategy_id	string or null	no	A stored strategy whose own weights, from its latest run, are the target.

OptimisationRunResult

Result payload of a completed optimisation job.

Field	Type	Required	Description
active_sum	number	yes	Sum of the active weights. Zero under full investment: rearranging weight cannot create any.
binding	array of map of string to string or null	no	Constraints the answer sits on, each traced back to the row that produced it where one can be identified. These are the rules that actually cost something.
constraint_set_id	string	yes
converged	boolean	yes
currency	string or null	no	The index's currency, which every name's prices were converted into before the risk model was estimated. Null on a run saved before this was recorded, whose prices were in each name's own currency.
end	string	yes	Last date the constituent price frame carries, YYYY-MM-DD, resolved on the same terms as start, which is the other end: earlier than the requested end whenever the store stops short of it.
heuristic	boolean	yes	True when a non-convex constraint forced a restricted re-solve, so the answer is feasible but not proven optimal.
holdings	integer	yes
index_id	string	yes	The index targeted, or the index the targeted strategy holds.
iterations	integer	yes
objective	number	yes
run_id	string	yes
solver_message	string	yes
start	string	yes	First date the constituent price frame actually carries, YYYY-MM-DD: the window the risk model behind this solve was estimated over. Resolved rather than echoed: the request's start is a bound on the fetch, and this is later than it whenever the store does not reach back that far. end is the other end.
strategy_id	string or null	no	The strategy targeted; null for an index target.
target_date	string or null	no	The rebalance whose weights were the target, YYYY-MM-DD; for a strategy, from its latest run when the solve was asked for.
tracking_error	number	yes
turnover	number	yes	One-way, against the index weights.
weights	array of WeightRow	yes	Every name, largest active position first.

OptimiseRequest

Body of POST /indices/{index_id}/optimise.

Everything the derived index needs that the parent cannot supply. The source is deliberately absent: provenance is server-truth, taken from the URL, so a client cannot assert a parentage the server did not create.

Field	Type	Required	Description
constraints	array of ConstraintRow	no	What the solved weights must satisfy. Validated through the same catalogue /optimise/constraint-sets uses, so a bad row is refused here naming the row.
description	string or null	no	Optional description for the derived index. Null inherits nothing: the parent's description describes the parent.
id	string	yes	Id for the new optimised index.
name	string	yes	Display name for the new optimised index.
objective	string	no	What the solve minimises. Accepted values: min_tracking_error. Default: "min_tracking_error".

OverviewView

Response of GET /strategies/{strategy_id}/overview.

Field	Type	Required	Description
concentration	ConcentrationPayload	yes
end	string	yes	Last date the stored run's level series covers, YYYY-MM-DD, in the same form as start. Resolved from the data: earlier than the end the backtest requested whenever the price store stops short of it. start is the other end.
index_id	string	yes	The index the strategy holds.
last_rebalance	string	yes
level	SeriesPayload	yes
metrics	BacktestMetrics	yes
name	string	yes
observations	integer	yes
rebalances	integer	yes
start	string	yes	First date the stored run's level series covers, YYYY-MM-DD, the same form CompareView.start uses. Resolved from the data rather than requested: it is later than the index's base_date whenever the price store does not reach back that far, so labelling it as the base date shows a different figure from the one the definition carries. end is the other end of the same series; the window the backtest was asked for is not published here.
strategy_id	string	yes	The strategy whose latest run this reads.

ParameterSpec

One parameter of a configurable type, described well enough to render.

Names, types, defaults and whether a parameter is required are read from the constructor, so they cannot drift from what the code accepts. Labels, ordering and choices are declared on the class, because a signature cannot carry them.

Field	Type	Required	Description
applies_to	array of string or null	no	For a vehicle setting, the archetypes it belongs to, such as 'exchange_traded'. Null means every vehicle, and every type outside the vehicle settings.
choices	array of string or null	no	The accepted values, when this is a closed set. Null means any value of type is allowed.
column	string or null	no	For a list of reference values, the reference column they are values of, such as 'SECTOR'; GET /data/reference-values lists what it holds. Null otherwise.
default	any	no	Value used when omitted. Null both for 'no default' and for a default of None; required distinguishes them.
help	string or null	no	One line of guidance for the field.
label	string	yes	Human-readable field name.
maximum	number or null	no	The largest value accepted, when bounded.
minimum	number or null	no	The smallest value accepted, when bounded.
name	string	yes	Parameter name, as it must appear in params.
options	string or null	no	For a parameter whose entries are themselves configurable types, the family in GET /backtest/options their types come from, such as 'signals'. Null otherwise.
order	integer	yes	Position in the form, ascending.
ref	string or null	no	Component schema this parameter's value must conform to, e.g. 'ExpressionNode'; resolve it under components.schemas in this document. Null for a scalar parameter. type stays the coarse render hint, so a client that ignores this still renders a JSON editor.
required	boolean	yes	Whether the constructor rejects the call without it.
type	string	yes	Display type: number, integer, boolean, string or json. What control to render, not the Python annotation.
unit	string or null	no	What the value is measured in: 'fraction' (show 0.02 as 2%), 'bps', 'days', 'money' (in the book's currency), 'count' or 'ratio'. Null for a value with no unit.

PeriodComparison

A comparator over one period: its own figures and the run's against it.

Field	Type	Required	Description
own	ComparatorFigures	yes	The comparator's own figures.
relative	RelativeFigures	yes	The run against it.

PeriodFigures

A run's figures over one calendar period.

Field	Type	Required	Description
max_drawdown	number	yes	Its largest fall from a peak within the period.
positive_days	number	yes	The share of its days with a positive return.
sharpe_ratio	number	yes	Its annualised return in excess of the risk-free rate, over the volatility.
total_return	number	yes	From the previous period's close.
volatility	number	yes	Of its daily returns, annualised.

PeriodRow

One calendar period of a run.

Field	Type	Required	Description
benchmark	PeriodComparison or null	no	Against its benchmark; null when the run has none.
end	string	yes	Its last day in the run, YYYY-MM-DD.
index	PeriodComparison or null	no	Against its index; null when the run has none.
period	string	yes	'2025', '2025 Q3' or '2025-07'.
start	string	yes	Its first day in the run, YYYY-MM-DD.
strategy	PeriodFigures	yes	The run's figures.

PeriodsView

Response of GET /strategies/{strategy_id}/periods.

Field	Type	Required	Description
frequency	string	yes	'annual', 'quarterly' or 'monthly'.
index_id	string	yes	The index the strategy holds.
periods	array of PeriodRow	yes	Each calendar period in order, the first from the run's start and each later one from the previous period's close, so they compound to the whole run.
strategy_id	string	yes	The strategy whose latest run this reads.

PipelineSpec

The grouped rule pipeline: Selection, Weighting, Treatment.

Field	Type	Required	Description
selection	array of RuleSpec	no
treatment	TreatmentSpec	no
weighting	WeightingSpec	yes

PortfolioBookPayload

The portfolio's books on the wire.

No rebalances here, unlike the index books: a portfolio makes no rebalance decision of its own (it trades toward one), so decided weights would be a field with nothing honest to put in it.

Field	Type	Required	Description
cash	SeriesPayload	yes
initial_capital	number	yes
nav	SeriesPayload	yes	The full NAV book, day-zero row included: it opens with initial capital on the eve of the first trading day. Metrics derive from the series without that row, and a client deriving its own period figures should do the same. A period holding only the day-zero row measures that row against itself and reads as a flat period rather than one that never traded.
portfolio_id	string	yes
positions	TableFrame	yes	The positions panel, long-form; most recent MAX_POSITION_ROWS rows at most.
positions_total	integer	yes	Rows in the whole positions panel.
reference_windows	map of string to array of ReferenceWindow or null	no	By identifier, the reference columns asked for with reference_fields over the weights panel's span, as windows with the dates they held, so any day of the panel reads the classification of its time. Null when none were asked for.
transactions	TableFrame	yes
weights	TableFrame	yes	Stored daily weights, dates by asset; most recent MAX_WEIGHT_DATES dates at most.
weights_dates_total	integer	yes	Dates the weights panel actually covers; larger than the rows served when the panel was truncated.

PostgresConnection

Where a Postgres store's tables or views are. Read-only.

Field	Type	Required	Description
database	string	yes	The database name.
host	string	yes	The database server.
password_env	string or null	no	The environment variable holding the password, read each time the engine connects. The password itself is never sent to the engine or saved. Null when the server needs none.
port	integer	no	The server's port. Default: 5432.
schema	string	no	The schema holding tables or views named market, reference, and optionally fx, corporate_actions and features, with the import template's columns. Default: "public".
user	string	yes	The user to connect as. Read access is all it needs.

PreviewAsset

Per-asset outcome of the derivation.

Two disjoint groups of fields, matching the two faces of a preview. The rule-provenance fields (excluded_by, excluded_at, uncapped_weight, capped) describe a walk down a pipeline and are null on a derived preview, which has no rules to attribute anything to. The derived fields (source_weight, solved_weight, weight_delta) describe a reallocation and are null on a rule-driven one. Neither group was overloaded to carry the other's meaning: a client reading excluded_by on a derived index would be reading an answer to a question nobody asked.

Field	Type	Required	Description
capped	boolean	no	Whether this name sits at the cap. Default: false.
excluded_at	integer or null	no	Waterfall position where it dropped out.
excluded_by	string or null	no	Id of the first rule that excluded it. Null when included, and always null on a derived preview.
free_float_market_cap	number or null	no	market_cap x free float, in market_cap_currency. Null when the free float is unknown or market_cap is null.
free_float_market_cap_local	number or null	no	market_cap_local x free float, in local_currency. Null when the free float is unknown.
identifier	string	yes
included	boolean	yes	Whether it reached the final index.
local_currency	string or null	no	ISO code the _local caps are in: the instrument's own quote currency. Null when the name has no price.
market_cap	number or null	no	Price x shares outstanding at resolved_date, converted into market_cap_currency, the index currency. Null when the name has no price or share count, or no rate converts it. Computed as /data/reference computes it.
market_cap_currency	string or null	no	ISO code the converted caps are in: the index currency.
market_cap_local	number or null	no	Price x shares outstanding, unconverted, in local_currency.
price_is_stale	boolean or null	no	Whether priced_from is more than 30 days before resolved_date. Null when the name has no price at all.
priced_from	string or null	no	The date of the close and share count behind the caps, YYYY-MM-DD: the last print on or before resolved_date. Null when the name has no price at all.
reference	object or null	no	The reference columns asked for with reference_fields, keyed in lower case, as they stood on this row's date. Null when the name had no reference row then.
solved_weight	number or null	no	Derived preview only: what the optimiser allocated it, the 'after'. Equal to weight, and carried separately so the before/after/delta triple reads as one row without a client having to know which face it is on.
source_weight	number or null	no	Derived preview only: what the parent index published for this name at the rebalance being previewed: the 'before'.
uncapped_weight	number or null	no	Weight before capping, when the cap bound this name.
universe_weight	number or null	no	Its share of the universe's total market cap on the preview date. A universe has no weighting of its own, so this is its free-float market cap over the universe's total where the index weights by free-float market cap, its full market cap otherwise. Null when it has no cap that day.
weight	number or null	no	Final weight as a fraction: the capped pipeline weight on a rule-driven preview, the solved weight on a derived one. Null when the name is not held.
weight_delta	number or null	no	Derived preview only: solved_weight minus source_weight. What the constraints did to this name.

PreviewConstraint

One constraint at the solved point: whether it bound, and its room.

Every constraint appears, not only the binding ones. A binding constraint's slack is zero by definition, so a report of only those is a list of zeros; what a reader actually wants beside "this cap bound" is "and the turnover budget had four points of room left".

Field	Type	Required	Description
binding	boolean	yes	Whether the solution sits on this constraint's boundary.
kind	string	yes	'eq' for an equality, 'ineq' for an inequality. An equality is always binding.
label	string	yes	The constraint's own description of itself, e.g. 'maximum weight 60.0000% on AAA'.
slack	number	yes	Signed room at the solution: zero sits exactly on the boundary, positive has room, negative would be a violation and is never returned. Measured in unit, not in a common currency: there is no shadow price here and slacks of different constraints are not comparable.
unit	string	yes	What slack is measured in, declared by the constraint class and also published by /optimise/constraint-types. 'fraction' means a proportion (of the portfolio for a weight or turnover limit, of return for a return target) and formats as a percentage; 'count' is a whole number of names.

PreviewDocumentRequest

Body of POST /indices/preview, which previews a document as supplied.

The route for a draft. The by-id route reads what is stored, so while an editor holds unsaved changes its figures describe the old definition, with nothing on screen to say they are stale. This one previews exactly what was sent, so editing a rule updates the resolved figures without saving.

Field	Type	Required	Description
as_of	string or null	no	Date to evaluate the pipeline at, YYYY-MM-DD. Defaults to the document's base date.
document	IndexDocument	yes	The definition to derive, saved or not.

PreviewRequest

Body of POST /indices/{id}/preview, which previews the saved index.

Field	Type	Required	Description
as_of	string or null	no	Date to evaluate the pipeline at, YYYY-MM-DD. Defaults to the index's base date.

PreviewResponse

Response of POST /indices/{id}/preview, in one of its two faces.

Exactly one of steps and solve is present, mirroring pipeline and derivation on the document the preview was built from: a rule-driven index answers with the waterfall, a derived one with the solve. solve is the discriminator, and it is the same discriminator the client already branches on one level up.

Everything outside the pair is common to both: the resolved weights, their total, and one row per name.

Field	Type	Required	Description
as_of	string	yes	The date the preview was asked for, YYYY-MM-DD, echoed back unchanged. What the data was actually read from is resolved_date, which is earlier whenever as_of fell on a day the market was shut.
assets	array of PreviewAsset	yes
cap	number or null	no	Cap applied, as a fraction, if any. Always null on a derived preview, whose limits are constraints.
cap_redistributed	number	no	Weight moved off capped names onto the rest. Default: 0.0.
index_id	string	yes
resolved_date	string or null	no	The market session as_of resolved to, YYYY-MM-DD: the latest one the data carries on or before it. A request for a weekend or a holiday resolves back to the session before it, which is the composition the index actually held that day rather than an approximation of one. Equal to as_of on a day the data has, and null only when as_of falls outside the data's coverage altogether.
solve	PreviewSolve or null	no	The optimisation at as_of. Null on a rule-driven index.
steps	array of PreviewStep or null	no	The derivation waterfall, one rung per selection rule. Null on a derived index, which narrows nothing.
total_weight	number	yes	Sum of the final weights; 1.0 for a non-empty index.
weights	map of string to number	yes	Final weights as fractions, keyed by identifier.

PreviewSolve

What the optimiser did at one rebalance: the derived face of a preview.

A derivation has no waterfall: the solve moves every weight at once rather than eliminating names in steps, so there are no rungs to show. This is the honest analogue: which parent snapshot was solved, under what, and which rules cost something.

Field	Type	Required	Description
binding	array of string	no	Labels of the constraints the solution sits on: the headline answer to 'what did my constraints do?'. Each also appears in constraints with its slack.
constraints	array of PreviewConstraint	no	Every constraint at the solution, binding or not.
objective	string	yes	What the solve minimised.
rebalance_date	string	yes	The parent snapshot this reports, YYYY-MM-DD: the latest one on or before as_of. A derivation solves only at its parent's rebalances, so an as_of between two of them previews the composition actually in force on that day.
source_index_id	string	yes	The parent index whose published weights were solved.

PreviewStep

One rung of the derivation waterfall.

There is one of these per selection rule, in pipeline order, plus a first entry for the universe itself so the funnel starts from a stated total.

Field	Type	Required	Description
description	string	no	One plain sentence of what the stage does with its settings, to show as written. Default: "".
excluded	array of string	no	Identifiers this step removed. Empty for the universe row.
params	array of StageParam	no	Its settings, labelled and formatted.
position	integer	yes	0 is the universe; rules follow in order.
remaining	integer	yes	Constituents surviving after this step.
rule_id	string or null	no	Rule responsible, or null for the universe row.
rule_type	string or null	no	Rule class name.
type	string	no	The stage's class, or its kind for a step that has none. Default: "".

PriceGapPayload

A day a name had no bar on a session that should have had one.

Field	Type	Required	Description
asset_id	string	yes	The name with no bar on that day.
date	string	yes	The simulated day whose bar was missing, YYYY-MM-DD. A trading day out of the backtest, not a wall-clock stamp.
priced_from	string	yes	The session the carried-forward price actually came from, YYYY-MM-DD; always earlier than date.
reference	object or null	no	The reference columns asked for with reference_fields, keyed in lower case, as they stood on this row's date. Null when the name had no reference row then.

PricesResponse

Response of GET /data/prices/{identifier}.

Field	Type	Required	Description
identifier	string	yes
interval	string	yes	Resolution actually served: 'native', 'weekly' or 'monthly'.
prices	TableFrame	yes	Date-indexed market data.

RebalancePricingPayload

The session one rebalance's trades were priced from.

Field	Type	Required	Description
date	string	yes	The rebalance date from the weight schedule, YYYY-MM-DD.
priced_from	string	yes	The session its prices were read from, YYYY-MM-DD. Equal to date for an ordinary rebalance; earlier when the schedule landed on a day the market was shut, which is the case worth reading.

RebalanceSnapshot

The index's composition at one rebalance.

Both weight sets are carried. weights is what the index applied; uncapped_weights is what the weighting scheme produced before any cap. They are equal on an uncapped index, and the difference is the only way to answer what capping cost, a question that cannot be reconstructed from the applied weights alone.

The run payload publishes these snapshots as rebalances, and the stored backtest record publishes the same rows on each index book.

Field	Type	Required	Description
announced	string or null	no	When this composition was published, if earlier than date. Null when the index has no effective-date lag and the two coincide, so its presence is itself the signal that a lag applies.
cap	number or null	no	Maximum single weight, if one applies.
capped	array of string	no	Constituents held at the cap on this date.
date	string	yes	Date these weights took effect, YYYY-MM-DD. Snapshots are keyed by the effective date because that is when the composition is in force.
redistributed	number	no	Weight moved off capped names onto the rest. Default: 0.0.
reference	map of string to object or null or null	no	By identifier, the reference columns asked for with reference_fields, keyed in lower case, as they stood on this date; null for a name with no reference row then. Null when the response carries none.
uncapped_weights	map of string to number	no	Weights before capping. Equal to weights when no cap was applied.
weights	map of string to number	yes	Applied weights, summing to 1.

RebalanceStepPayload

What the implementation's stages did at one rebalance.

Field	Type	Required	Description
capped	map of string to number	no	Name -> the weight it was capped at.
cash_weight	number	no	The share of the book the weights leave in cash. Default: 0.0.
date	string	yes	YYYY-MM-DD.
removed	map of string to string	no	Name -> the screen that removed it.

ReferenceEntry

One identifier's row in a batch reference response.

Field	Type	Required	Description
fields	object	no	Requested reference columns and derived fields. A column the dataset holds but this identifier has no value for is present and null, which is a different statement from the identifier being absent.
found	boolean	yes	Whether the reference dataset holds this identifier. False leaves fields empty rather than failing the batch, so one unknown name does not lose the other 511.
identifier	string	yes

ReferenceResponse

Response of GET /data/reference/{identifier}.

Fields are whatever columns the loaded reference data carries (the library does not impose a schema on it), so they are returned as a mapping rather than as named attributes.

Field	Type	Required	Description
fields	object	yes	Reference columns for this identifier, e.g. NAME, CURRENCY, EXCHANGE. Timestamps are ISO 8601 strings.
identifier	string	yes
universes	array of UniverseMembership	no	Universes containing this instrument, so a client can answer 'where is this used?' without reading every universe and searching it.

ReferenceValueList

Values of one reference column, matched exactly. The parameter's column names the column, and GET /data/reference-values lists what it holds.

Type: array of string

ReferenceValues

Response of GET /data/reference-values.

Field	Type	Required	Description
column	string	yes	The column, as the reference data names it.
values	array of string	yes	Every value it holds in any record, current or not, sorted. A screen matches them exactly.

ReferenceWindow

A span over which a name's reference columns held.

Field	Type	Required	Description
date_from	string	yes	Its first day, YYYY-MM-DD.
date_to	string or null	no	Its last day; null while open.
reference	object	yes	The columns that held over it.

RefreshJobStatus

A refresh:{store_id} job. result says what changed.

Field	Type	Required	Description
error	ErrorDetail or null	no	Failure reason, when status is failed; null otherwise. The same {code, message, detail} a non-2xx response carries, and the same schema, so a failed job branches on error.code exactly as an HTTP error does. A job recorded by an older engine carries UNCLASSIFIED_FAILURE: its message was recorded, its code was not, and the migration does not guess one.
job_id	string	yes	The job's id: poll GET /jobs/{job_id}, or watch it on the event socket.
kind	string	yes	What the job is, e.g. 'backtest'.
message	string	no	Latest progress message. Default: "".
progress	number	yes	Fraction complete, 0.0 to 1.0.
result	RefreshResult or null	no	Present only once the job has succeeded; null otherwise.
status	string	yes	pending, running, succeeded, failed or cancelled. The last three are terminal.

RefreshRequest

Body of POST /data/stores/{store_id}/refresh. Optional.

Field	Type	Required	Description
end	string or null	no	For synthetic data, the date to extend to, YYYY-MM-DD. Defaults to today. Ignored by other stores.

RefreshResult

Result payload of a completed refresh:{store_id} job.

Field	Type	Required	Description
action	one of "extend", "reread", "download"	yes	What the refresh did: extended synthetic data, read a folder or database again, or downloaded from Yahoo Finance.
end	string or null	no	The last date the store holds now, ISO 8601, when known.
name	string	yes	Its display name.
rows_added	integer or null	no	For a download, the market rows added. Null otherwise.
served	boolean	yes	Whether the engine now serves the refreshed data. True when the store was the one being served.
store_id	string	yes	The store refreshed.

RelativeFigures

A run against a comparator over the same window.

Field	Type	Required	Description
annualised_relative_return	number	yes	The run's annualised return less the comparator's.
beta	number or null	no	Of the run's daily returns on the comparator's.
correlation	number or null	no	Of the daily returns.
hit_rate_monthly	number or null	no	The share of calendar months the run beat the comparator.
information_ratio	number or null	no	The annualised relative return over the tracking error.
relative_return	number	yes	The run's total return less the comparator's.
tracking_error	number or null	no	Of the daily return differences, annualised.

RelativeMetricsPayload

Performance against a benchmark, over their shared window.

Field	Type	Required	Description
benchmark_return	number	yes	Fraction, not percent: 0.0523 means 5.23%.
beta	number	yes
correlation	number	yes
end	string	yes	Last shared date, in the same full ISO-8601 form as start, which is the other end. Resolved by the same intersection: earlier than the backtest's own end whenever the benchmark series stops first.
excess_return	number	yes	Portfolio minus benchmark; also the tracking difference.
level	SeriesPayload	yes	The benchmark, rebased to 100 on the shared window.
observations	integer	yes	Aligned dates used, which may be fewer than either series carried on its own.
reference	BenchmarkRef	yes
start	string	yes	First date the portfolio and the benchmark share, as a full ISO-8601 timestamp. Resolved: the two level series are intersected before anything is measured, so this is later than the backtest's own start whenever the benchmark's history begins later. observations counts the shared dates and end is the other end; the window the backtest requested is not carried here.
total_return	number	yes	Fraction, not percent: 0.0523 means 5.23%.
tracking_error	number	yes	Annualised standard deviation of return differences.

RenderJobStatus

A render:{render_id} job. result describes the rendered document.

Field	Type	Required	Description
error	ErrorDetail or null	no	Failure reason, when status is failed; null otherwise. The same {code, message, detail} a non-2xx response carries, and the same schema, so a failed job branches on error.code exactly as an HTTP error does. A job recorded by an older engine carries UNCLASSIFIED_FAILURE: its message was recorded, its code was not, and the migration does not guess one.
job_id	string	yes	The job's id: poll GET /jobs/{job_id}, or watch it on the event socket.
kind	string	yes	What the job is, e.g. 'backtest'.
message	string	no	Latest progress message. Default: "".
progress	number	yes	Fraction complete, 0.0 to 1.0.
result	RenderResult or null	no	Present only once the job has succeeded; null otherwise.
status	string	yes	pending, running, succeeded, failed or cancelled. The last three are terminal.

RenderRequest

Body of POST /reports/render.

Field	Type	Required	Description
strategy_id	string or null	no	Required for a built-in template, which is generated from that stored strategy's latest completed backtest and named after it. Ignored for a stored template, which is rendered exactly as saved.
template_id	string	yes	A stored template, or a built-in such as FACTSHEET-A4.

RenderResult

Result payload of a completed render job.

Field	Type	Required	Description
blocks	integer	yes
bytes	integer	yes	Size of the rendered document.
name	string	yes
render_id	string	yes	Fetch the PDF from GET /reports/renders/{render_id}.
rendered_at	string	yes	When the PDF was written, ISO-8601 UTC with an offset: wall-clock at render time. Not the as-of date of anything printed inside it: the figures come from the index's latest completed backtest, whose own dates this does not carry, so rendering the same template twice gives two rendered_at values over identical content.
strategy_id	string or null	no	The strategy a built-in template was generated from; null for a stored template.
template_id	string	yes

ReplicationPayload

What a replication did at one rebalance.

Field	Type	Required	Description
date	string	yes	YYYY-MM-DD.
holdings	integer	yes	How many names the weights hold.
tracking_error	number or null	no	Ex-ante, annualised; null when not estimated.
unmeasured	array of string	no	Names held at their index weight for want of history.
weights	map of string to number	yes	The weights traded to.

ReportEntrySpec

One statistic in a report level.

Field	Type	Required	Description
id	string	yes	The statistic's id.
state	string	yes	'included' (shown by default) or 'optional' (offered).
view	string	yes	Its default time view: 'point', 'rolling' or 'both'.

ReportLevelSpec

A report at one level.

Field	Type	Required	Description
sections	array of ReportSectionSpec	yes	Its sections, in reading order.

ReportSectionSpec

A level's statistics of one category, in order.

Field	Type	Required	Description
label	string	yes	The section's heading.
order	integer	yes	Its place in the level, ascending.
statistics	array of ReportEntrySpec	yes	Its statistics, in order.

ReportSelection

What a report shows, in order.

Field	Type	Required	Description
level	string	yes	The level asked for: 'core' or 'extended'.
statistics	array of StatisticRef	yes	Its statistics, in reading order.

ReportSpec

One report, at both levels.

Field	Type	Required	Description
id	string	yes	What requests name it by.
label	string	yes	Its name, as shown.
levels	map of string to ReportLevelSpec	yes	'core' and 'extended'; each lists its sections in full.
order	integer	yes	Its place among the reports, ascending.

ReportTemplateCollection

Response of GET /reports/templates.

Field	Type	Required	Description
built_in	array of string	no	Templates generated from a run rather than stored. These can be rendered but not edited: they are code, not documents.
skipped	integer	no	Stored documents the server could not read, and so left out of this listing. Non-zero means the collection is incomplete: the fault is logged server-side, and each skipped document answers 404 on its own route. Default: 0.
skipped_causes	SkippedCauses	no	The same documents as skipped, by cause, so the listing can say what to do about them. Its three counts sum to skipped.
templates	array of ReportTemplateDocument	yes

ReportTemplateDocument

A stored report template, as JSON.

Blocks are kept as free-form mappings rather than a discriminated union so the wire shape stays exactly what beacon.report.blocks reads and writes. A second definition of the same thing here is a second definition to keep in step, and the block model already validates its own rows on the way in.

Field	Type	Required	Description
blocks	array of object	no	Content, drawn top to bottom. Each carries a kind, one of: bar_chart, chart, header, stat_grid, table, text.
name	string	yes	Display name.
page	object	no	Page setup: size, orientation, margin.
template_id	string	yes	Stable identifier, used in the URL.

RiskDecomposition

Active risk split into factor and specific parts.

The two sum to the total exactly, because the covariance is defined as B F Bᵀ + D. Pair an arbitrary covariance with arbitrary loadings and there is a cross term; the identity belongs to this model and not to any pairing of a matrix with some exposures.

Field	Type	Required	Description
contributions	map of string to number	yes	Each factor's share of the factor variance. May be negative: a factor position that hedges another genuinely reduces risk.
factor_share	number	yes
factor_variance	number	yes
reconciles	boolean	yes
residual	number	yes	Total minus the two parts. Zero up to float noise, by construction.
specific_variance	number	yes
total_variance	number	yes
tracking_error	number	yes

RiskDiagnosticsPayload

How an estimate was produced, and how far it can be trusted.

Field	Type	Required	Description
assets	integer	yes
average_correlation	number	yes	Mean off-diagonal correlation. The sanity check a person can actually do: a diversified equity universe sits around 0.3-0.6, and a figure far outside that says the window or the universe is not what someone thought.
condition_number	number	yes	Largest eigenvalue over smallest. An optimiser inverts this matrix, and a large value means the inverse amplifies estimation error rather than reflecting it.
intensity	number	yes	Weight placed on the structured target. 0 means the estimate is the raw sample covariance.
observations	integer	yes	Periods used, after dropping incomplete rows.
positive_semi_definite	boolean	yes	Computed from the eigenvalues, not asserted. A matrix that fails this can produce a negative portfolio variance, and a caller about to invert it needs to know.
repaired	boolean	yes
smallest_eigenvalue	number	yes
target	string	yes

RiskModelCollection

Response of GET /risk-models.

Field	Type	Required	Description
risk_models	array of RiskModelSummary	yes

RiskModelJobStatus

A risk:{model_id} job. result is the estimated model.

Field	Type	Required	Description
error	ErrorDetail or null	no	Failure reason, when status is failed; null otherwise. The same {code, message, detail} a non-2xx response carries, and the same schema, so a failed job branches on error.code exactly as an HTTP error does. A job recorded by an older engine carries UNCLASSIFIED_FAILURE: its message was recorded, its code was not, and the migration does not guess one.
job_id	string	yes	The job's id: poll GET /jobs/{job_id}, or watch it on the event socket.
kind	string	yes	What the job is, e.g. 'backtest'.
message	string	no	Latest progress message. Default: "".
progress	number	yes	Fraction complete, 0.0 to 1.0.
result	RiskModelView or null	no	Present only once the job has succeeded; null otherwise.
status	string	yes	pending, running, succeeded, failed or cancelled. The last three are terminal.

RiskModelRequest

Body of POST /risk-models/{model_id}/estimate.

Field	Type	Required	Description
currency	string or null	no	The currency returns are measured in: every name's prices are converted into it first, so exchange-rate moves are part of the risk. Null uses the index's currency when index_id is given, otherwise USD.
end	string or null	no	End of that window.
identifiers	array of string	no	Names to estimate over. Empty takes them from index_id or strategy_id.
index_id	string or null	no	Take the names from this index's latest rebalance, calculated, instead of listing them.
intensity	number or null	no	Weight on the target, in [0, 1]. Null uses the heuristic from the panel's shape; 0 gives the raw sample covariance, which on a short history across many names is mostly noise.
repair	boolean	no	Clip negative eigenvalues if the result is not PSD. Off by default because shrinkage should make it unnecessary and clipping silently shifts the variances. Default: false.
start	string or null	no	Start of the estimation window.
strategy_id	string or null	no	Take the names from what this stored strategy held at its latest run's last rebalance instead of listing them.
target	string	no	Structured target to shrink toward: 'constant_correlation' or 'scaled_identity'. Default: "constant_correlation".

RiskModelSummary

One entry in GET /risk-models.

Field	Type	Required	Description
assets	integer	yes
average_correlation	number	yes
model_id	string	yes
observations	integer	yes
positive_semi_definite	boolean	yes

RiskModelView

Response of GET /risk-models/{model_id}.

Field	Type	Required	Description
asset_ids	array of string	yes
correlation	TableFrame	yes	Symmetric with a unit diagonal, by construction.
covariance	TableFrame	yes	Annualised.
currency	string or null	no	The currency the returns were measured in. Null on a model estimated before this was recorded, whose returns were in each name's own currency.
diagnostics	RiskDiagnosticsPayload	yes
end	string or null	no	The request's own end, echoed back unchanged on the same terms as start, which is the other bound. Null when the request omitted it.
model_id	string	yes
start	string or null	no	The request's own start, echoed back unchanged: the bound the price fetch was given, not the first date prices were found on. Null when the request omitted it, which estimates over the whole stored history. No field here reports the dates the returns actually spanned; diagnostics.observations is the only measure of what survived. end is the other bound.
volatilities	map of string to number	yes	Annualised standard deviation per asset: the square root of the covariance diagonal.

RiskPayload

How the index's volatility divides among its holdings.

Contributions sum to volatility exactly rather than approximately: the decomposition is an identity, so a client can show the parts and the whole without them disagreeing.

Field	Type	Required	Description
covered_weight	number	yes	Fraction of the index the figure speaks for. Below 1.0 when the model has no estimate for some constituent; the covered names keep their real weights rather than being renormalised, which would restate the portfolio.
uncovered	array of string	no	Constituents with no estimate, usually for want of history. Listed rather than only counted, so a reader sees which names are missing.
volatility	number	yes	Annualised volatility of the covered holdings, at the weights they are actually held.
window_end	string or null	no	Last date of the run's own level series, YYYY-MM-DD, on the same terms as window_start, which is the other end: a bound given to the price fetch, unchanged by what the store actually held.
window_start	string or null	no	First date of the run's own level series, YYYY-MM-DD: the span the price fetch behind this estimate was given, not the dates prices came back on. It does not narrow: when the store covers less, the covariance is estimated from fewer observations and this still reports the run's span, so it is a bound rather than a measurement. Null when the run carries no level series. window_end is the other end, and active_risk.window_start is this same window; both come from the run, not from a query.

RollingValue

A statistic over each trailing window.

Field	Type	Required	Description
step	string	yes	How often a window ends: 'daily' or 'month_end'.
table	object	yes	Dates down, the point figure's names across: {index, columns, data}, a list of values a row.
window	integer	yes	The days each window covers.

RollResponse

Response of GET /derivatives/{index_id}/roll.

Both legs are priced theoretically off the same spot and curve, so this is the carry roll rather than a market one.

Field	Type	Required	Description
annualised_roll	number	yes	Positive in backwardation, negative in contango.
as_of	string	yes	The session both legs were priced from, YYYY-MM-DD: the latest date with a close on or before the as_of query, or the last date the store carries when none was given. Resolved rather than echoed (a request landing on a weekend or a holiday answers from the session before it), and the date asked for is not published anywhere. Both expiries are measured from this date, so it also sets annualised_roll.
back_expiry	string	yes
back_price	number	yes
front_expiry	string	yes
front_price	number	yes
index_id	string	yes
roll_cost	number	yes	Back minus front.
spot	number	yes

RuleSpec

One rule in the pipeline, addressable by its id.

Field	Type	Required	Description
id	string	yes	Client-assigned id, unique within the pipeline.
params	object	no	Constructor arguments for the rule.
type	string	yes	Rule class name, e.g. 'MarketCapRule'.

RuleTypes

Response of GET /indices/rule-types.

Everything a methodology editor needs to render a real form: which rules and schemes exist, what each takes, and how to label and order the fields. Without it RuleSpec.type is a free-text box and params a list of key/value pairs, so a misspelled parameter is only discovered on submit.

Field	Type	Required	Description
selection	array of TypeSpec	yes	Eligibility rules available for the selection stage.
weighting	array of TypeSpec	yes	Weighting schemes available for the weighting stage.

SavedAnalyses

Response of GET /strategies/{strategy_id}/analyses.

Field	Type	Required	Description
analyses	array of SavedAnalysis	yes	Every analysis kept with the latest run, newest first.

SavedAnalysis

One analysis kept by name with a strategy's latest run.

Field	Type	Required	Description
name	string	yes	What it was saved as.
options	object	yes	The choices it was made with, by section.
reports	map of string to string	yes	Its reports, by id, with their levels.
saved_at	string	yes	When, ISO 8601, UTC.

SavedAnalysisView

Response of GET /strategies/{strategy_id}/analyses/{name}.

Field	Type	Required	Description
analytics	AnalyticsBlock	yes	The analysis.
name	string	yes	What it was saved as.
options	object	yes	The choices it was made with, by section.
reports	map of string to string	yes	Its reports, by id, with their levels.
saved_at	string	yes	When, ISO 8601, UTC.

SavedConstraintSet

Response of a successful save: the set plus any warnings.

Field	Type	Required	Description
constraint_set	ConstraintSet	yes
findings	array of Finding	no	Non-blocking warnings. Errors would have prevented the save.

SavedIndex

Response of a successful save: the document plus any warnings.

Field	Type	Required	Description
findings	array of Finding	no	Non-blocking warnings. Errors would have prevented the save.
index	IndexDocument	yes

SavedStrategy

Response of a strategy save: the document as stored, and any warnings.

Field	Type	Required	Description
findings	array of Finding	yes	Warnings the save carried; a save with errors is refused instead.
strategy	StrategyDocument	yes	The strategy as stored.

ScheduleView

Response of GET /indices/{index_id}/schedule.

Derived, not stored: the next rebalance is a function of the schedule, the calendar and today, and storing it would leave a date that silently expires.

Field	Type	Required	Description
as_of	string	yes	Date the answer was computed from.
calendar	string	yes	Exchange MIC the dates were computed on. Always present, since every index has a calendar.
days_until	integer or null	no	Calendar days from as_of to next_rebalance. Calendar days rather than sessions, because it is displayed as 'in 57 days' and a reader counts those on a wall calendar.
index_id	string	yes
next_rebalance	string or null	no	Next rebalance date, ISO 8601. Null when none falls within the lookahead, which happens only for a schedule this server cannot project, not for a normal index.
rebalance_day_rule	string	yes
rebalancing_frequency	string	yes
recent	array of string	no	Rebalances already passed, most recent last. Trimmed to the limit most recent; recent_total says how many there were.
recent_total	integer	no	Rebalances between the base date and as_of: the length recent would have had before the limit trim, so equal to it when nothing was trimmed. A client reads these two together to tell 'these are all of them' from 'the last four of many'. Default: 0.
upcoming	array of string	no	Scheduled rebalances after as_of, soonest first. Trimmed to the limit soonest; upcoming_total says how many were found.
upcoming_total	integer	no	Rebalances the lookahead projection found after as_of: the length upcoming would have had before the limit trim, not the number that will ever occur. The projection runs a fixed few periods ahead and limit does not extend it, so this is a bound on what was computed, not on the schedule, which has no end. Default: 0.

SeriesPayload

A pandas Series on the wire.

Field	Type	Required	Description
data	array of any	yes	Values, aligned to index. NaN becomes null.
index	array of any	yes	Row labels; timestamps are ISO 8601 strings.
name	string or null	no	Series name, if it has one.

ShareClassMetrics

A class's figures against the index in its currency: converted for an unhedged class, hedged the same way for a hedged one.

Field	Type	Required	Description
total_return	number	yes	Per unit, with what it paid out added back.
tracking_difference	number or null	no	Its total return less its benchmark's.
tracking_error	number or null	no	Of its daily returns against its benchmark's, annualised.

ShareClassPayload

One share class's record of a run. Its money is in its own currency, and its series share level's dates.

Field	Type	Required	Description
book_net_assets	SeriesPayload	yes	The same in the book's currency, which add up to the fund's across the classes.
currency	string	yes	The currency its figures are in.
distribution	string	yes	'accumulating' or 'distributing'.
distributions	SeriesPayload	yes	What it paid out each day.
distributions_paid	number	yes	What it paid out over the run.
fees	SeriesPayload	yes	The fee it accrued each day.
fees_paid	number	yes	Its fees over the run.
flows	array of FlowPayload	yes	Its own flows as dealt.
hedge_value	SeriesPayload or null	no	Its forward's value each day, in its currency; null for an unhedged class.
hedged	boolean	yes	Whether it hedged into that currency.
hedges	array of HedgePayload	no	Each trade of its hedge.
management_fee_bps	number	yes	Its fee, in basis points a year.
metrics	ShareClassMetrics	yes
name	string	yes	The class's name.
nav_per_unit	SeriesPayload	yes	Its NAV per unit.
net_assets	SeriesPayload	yes	Its net assets at each day's end.
units	SeriesPayload	yes	Its units outstanding.

ShareClassSpec

One share class of a backtest's fund: its own currency, fee and distribution policy, sharing the book with the other classes.

Field	Type	Required	Description
currency	string or null	no	The class's currency. Null is the book's.
distribution	string	no	'accumulating' keeps its income in the fund; 'distributing' pays it out. Default: "accumulating".
hedge_band	number or null	no	How far the hedge ratio may drift between monthly rolls before the forward is resized, as a fraction. Null resizes only at rolls. Default: 0.03.
hedge_cost_bps	number	no	What trading its forwards costs, in basis points of the notional each trade deals: all of it at a roll, the change at a resize. Default: 0.0.
hedge_ratio	number	no	The share of its net assets it hedges, as a fraction: 1 for all. Default: 1.0.
hedged	boolean	no	Whether it hedges its share of the assets into its currency with a monthly forward. Needs a currency other than the book's. Default: false.
management_fee_bps	number or null	no	The class's annual management fee in basis points. Null is the vehicle's.
name	string	yes	What the class is called, such as 'EUR H'.

SignalWeights

A weight for each of the factor's signals, in their order: zero or more, not all zero. Leave out for equal weights.

Type: array of number

SkippedCauses

Why a listing left documents out, one count per cause.

Each cause has its own remedy, so each has its own count and a description that names it.

Field	Type	Required	Description
from_newer_build	integer	no	Documents written by a newer py-beacon than the one serving this listing. Nothing is wrong with them: upgrading the engine will read them. The state two installs reach when the engine and the app are updated on different machines. Default: 0.
unparseable	integer	no	Documents that are damaged: not valid JSON, or carrying a schema version nothing can migrate. The file itself is the problem -- restore it from a backup or remove it. Default: 0.
unrecognised	integer	no	Documents that are valid JSON but that this engine's model does not accept -- the document and the engine disagree about its shape, usually a version gap the schema migrations do not cover. The server log names the field. Default: 0.

StageParam

One setting of a stage, as a reader sees it.

Field	Type	Required	Description
label	string	yes	The setting's label, as its editor shows it.
value	string	yes	Its value, formatted with its unit.

StatisticRef

One statistic a report shows, and how.

Field	Type	Required	Description
id	string	yes	The statistic's id, a key of the block's statistics or unavailable.
view	string	yes	The time view it is shown in: 'point', 'rolling' or 'both'.

StatisticSpec

One statistic, as the catalogue lists it.

Field	Type	Required	Description
category	string	yes	What it is a figure of; reports are sectioned by it.
columns	array of object	yes	For a table, its columns in order: name, label and unit.
decimals	integer or null	yes	How many decimals it is shown to.
description	string	yes	One line saying what it measures.
figure_names	array of string	yes	What its figure names are made of, part by part, each a key of the catalogue's names.
id	string	yes	What requests and stored choices name it by.
kind	string	yes	'figures', 'series' or 'table'.
label	string	yes	Its name, as shown.
part	string	yes	The analysis that works it out: 'performance', 'portfolio', 'risk' or 'attribution'.
rolling	string or null	yes	What rolling it costs ('light', 'moderate' or 'heavy'); null when it does not roll.
settings	array of string	yes	The settings it reads, as 'section.setting'.
signed	array of string	yes	Which of its figures are returns or differences, whose sign says better or worse, by the last part of a figure's, a column's or a summary figure's name; '*' for every number; empty for none.
step	string or null	yes	How often its windows end unless asked otherwise.
unit	string or null	yes	What its figures are measured in; null for none.

StatisticValue

One statistic's value.

Field	Type	Required	Description
kind	string	yes	'figures' (point maps names to numbers, names of several parts joined with '/'), 'series' (point is {index, name, data}) or 'table' (point is {index, columns, data}, a list of values a row).
point	any	yes	Its value over the analysis window, in its kind's shape.
rolling	RollingValue or null	no	Its value over each trailing window, when its time view asks for it.
summary	object or null	no	For a table, the figures that sum it up (its totals, its residual), by name.

StoredStrategy

A stored strategy as listed and read, with any problem it has.

Field	Type	Required	Description
description	string or null	no	Optional description.
id	string	yes	The strategy's id.
implementation	ImplementationSpec or null	no	How the strategy trades: screens, caps, minimum positions, market impact, execution limits, the cash buffer and equitising it. Null trades without them.
index_id	string	yes	The stored index the strategy holds: the one tracked, or the benchmark an active strategy is measured against.
name	string	yes	Display name.
problem	StrategyProblem or null	no	Why it cannot be run as it stands, such as an index that has gone; null when it can.
strategy	StrategySpec	no	What the backtest holds: the index in full (the default), the index through a replication, or an active strategy.

StoreForgotten

Response of DELETE /data/stores/{store_id}: what became of the stored runs that read the store's data.

Field	Type	Required	Description
deleted	array of string	yes	The strategies whose stored runs were deleted with the store (cascade=true).
kept	array of string	yes	The strategies whose stored runs read the store's data. Their market inputs are kept, and each run says, when opened, that its store was deleted.
warning	string or null	no	Said when runs still read the store's data.

StoreProblem

Why a store cannot be read, when the engine can tell without loading it.

Field	Type	Required	Description
code	string	yes	Stable machine-readable code: 'STORE_FORMAT_OUTDATED' for a store saved in a format this version no longer reads, which regenerating or re-importing fixes.
message	string	yes	What is wrong and what to do, in a sentence.

StrategyBacktestRequest

Body of POST /strategies/{strategy_id}/backtest: everything a backtest needs that the stored strategy does not hold.

Every field past the first five is optional, and a request without them runs exactly as one with only the dates, capital and cost does. The strategy and its implementation come from the stored strategy, so a body carrying either is refused.

Field	Type	Required	Description
analysis	AnalysisRequestSpec or null	no	What the run's analysis should give: reports, statistics and every choice they make. Null for none; the run's analytics can be worked out later.
benchmark	BenchmarkRef or null	no	Optional external benchmark. The tracked index is always reported separately; this adds a second comparison.
currency	string or null	no	The book's currency. Null keeps it in the index's.
dividends	string	no	What happens to cash distributions: 'reinvest', 'cash' or 'distribute'. Default: "reinvest".
end	string or null	no	End date, YYYY-MM-DD.
flows	array of TypedSpec or map of string to array of TypedSpec	no	Money arriving and leaving, added together. Amounts are in the book's currency. With share classes, by class name, each in its class's currency.
initial_capital	number or map of string to number	no	The capital the fund starts with, in the book's currency. With share classes, by class name, each in its class's currency. Default: 1000000.0.
modelling_assumptions	ModellingAssumptionsSpec or null	no	What the run takes as given; each unset field takes the engine's default.
reinvest_into	string	no	Where reinvested dividends go: 'payer', the name that paid each one, or 'holdings', the current holdings in proportion to value. Default: "payer".
share_classes	array of ShareClassSpec	no	The fund's share classes, sharing one book. Empty runs one class with the request's capital and flows, as without classes.
start	string or null	no	Start date, YYYY-MM-DD. Defaults to the index base date.
transaction_cost_bps	number	no	Cost per trade in basis points of notional. Default: 0.0.
vehicle	VehicleSpec or null	no	Null for a plain backtest, with no fee.

StrategyCollection

Response of GET /strategies.

Field	Type	Required	Description
skipped	integer	no	Stored documents the server could not read, and so left out of this listing. Non-zero means the collection is incomplete: the fault is logged server-side, and each skipped document answers 404 on its own route. Default: 0.
skipped_causes	SkippedCauses	no	The same documents as skipped, by cause, so the listing can say what to do about them. Its three counts sum to skipped.
strategies	array of StoredStrategy	yes	Every strategy the server could read, each with any problem it has.

StrategyDeletion

Response of DELETE /strategies/{strategy_id}.

Field	Type	Required	Description
backtest_record_deleted	boolean	yes	Whether its saved backtest record went with it.
backtest_results_deleted	integer	yes	How many job records and persisted run results of its backtests were forgotten with it.
strategy_id	string	yes	The strategy that was removed.

StrategyDocument

A stored strategy: what a backtest holds and how it trades.

Everything else a backtest needs (the period, capital, currency, dividends, costs, flows, vehicle, share classes and modelling assumptions) belongs to the backtest, not the strategy.

Field	Type	Required	Description
description	string or null	no	Optional description.
id	string	yes	The strategy's id.
implementation	ImplementationSpec or null	no	How the strategy trades: screens, caps, minimum positions, market impact, execution limits, the cash buffer and equitising it. Null trades without them.
index_id	string	yes	The stored index the strategy holds: the one tracked, or the benchmark an active strategy is measured against.
name	string	yes	Display name.
strategy	StrategySpec	no	What the backtest holds: the index in full (the default), the index through a replication, or an active strategy.

StrategyProblem

Why a stored strategy cannot be run as it stands.

Field	Type	Required	Description
code	string	yes	'INDEX_NOT_FOUND' when its index is not stored, 'INDEX_UNREADABLE' when it is stored but cannot be read.
message	string	yes	What is wrong and how to fix it.

StrategySpec

What the backtest holds.

The path's index is the strategy's index: the one tracked, or the benchmark an active strategy is measured against.

Field	Type	Required	Description
constraints	array of TypedSpec	no	For an active strategy: what its portfolio must satisfy.
construction	TypedSpec or null	no	For an active strategy: how it builds its portfolio. MaxAlpha with its default budget when null.
lookback_days	integer or null	no	For an active strategy: trading days its covariance is estimated over; a year when null.
minimum_observations	integer or null	no	For an active strategy: the fewest returns a name needs to be measured; 126 when null.
rebalancing	string	no	For an active strategy: WEEKLY, MONTHLY, QUARTERLY or ANNUALLY. Default: "MONTHLY".
replication	TypedSpec or null	no	For index tracking: how the index is held.
screen	object or null	no	For an active strategy: a condition every holding must pass, as an expression tree.
signal	TypedSpec or null	no	For an active strategy: what it believes.
type	string	no	'index' (the index in full, the default), 'index_tracking' (through a replication) or 'active'. Default: "index".
universe	array of string or null	no	For an active strategy: the names it may hold. Null means the benchmark's constituents.

SwapResetPayload

One reset of a synthetic fund's swap.

Field	Type	Required	Description
date	string	yes	YYYY-MM-DD.
notional	number	yes	The notional it was reset to, the fund's net assets, in the book's currency.
reason	string	yes	'limit' (its value owed to the fund reached the exposure limit), 'rebalance' or 'flows'.
settled	number	yes	The swap's value paid in cash, in the book's currency: received by the fund when positive, paid by it when negative; 0 when it opened.

SyncRequest

Body of POST /data/coverage/{dataset}/sync.

Deprecated with the endpoint. Its fields are accepted and ignored: a sync refreshes the whole active store from its own source, as POST /data/stores/{id}/refresh does.

Field	Type	Required	Description
end	string or null	no	Ignored. YYYY-MM-DD.
identifiers	array of string	no	Ignored. Accepted so existing clients keep working.
start	string or null	no	Ignored. YYYY-MM-DD.

TableFrame

A pandas DataFrame on the wire.

Row-oriented so column order is preserved and the payload stays compact.

Field	Type	Required	Description
columns	array of string	yes	Column names, in order.
data	array of array of any	yes	Rows, each aligned to columns. NaN becomes null.
index	array of any	yes	Row labels; timestamps are ISO 8601 strings.

TablePage

Response of GET /data/tables/{dataset}.

The stored data as it is, before any view shapes it. Paged because the default synthetic store holds 11.8M market rows, and an unbounded dump is not something a client can render or an engine should assemble.

Field	Type	Required	Description
dataset	string	yes
limit	integer	yes
offset	integer	yes
rows	object	yes	The {index, columns, data} frame shape used elsewhere.
total	integer	yes	Rows in the whole dataset, so a client can size its scrollbar without paging to the end to find out.

TableRef

A large table of the run, read on its own.

Field	Type	Required	Description
path	string	yes	Where to read it: GET this path, with Accept: application/vnd.apache.arrow.stream for Arrow.
rows	integer	yes	How many rows it has.

TableSpec

A large table of a run.

Field	Type	Required	Description
columns	array of object	yes	Its columns in order: name, label, unit, and for coded text the label of each value.
label	string	yes	Its name, as shown.
name	string	yes	What the tables path names it by.

TermStructureEntry

One expiry in a term structure.

Field	Type	Required	Description
expiry	string	yes
financing_rate	number	yes
theoretical	number	yes
time_to_expiry	number	yes	Years from the response's as_of to expiry, ACT/365. Measured from the resolved session rather than the date asked for, so a request landing on a weekend or a holiday lengthens every tenor in the strip by however many days as_of resolved back.

TermStructureResponse

Response of GET /derivatives/{index_id}/term-structure.

Field	Type	Required	Description
as_of	string	yes	The session spot was read from, YYYY-MM-DD: the latest date with a close on or before the as_of query, or the last date the store carries when none was given. Resolved rather than echoed (a request landing on a weekend or a holiday answers from the session before it), and the date asked for is not published anywhere. Every entries[].time_to_expiry is measured from this date.
entries	array of TermStructureEntry	yes
index_id	string	yes
spot	number	yes

TreatmentSpec

The treatment group of the pipeline.

Field	Type	Required	Description
corporate_actions	string	no	How corporate actions affect the index. Only ADJUST_DIVISOR is supported. Default: "ADJUST_DIVISOR".

TrsAccrual

One financing period.

Field	Type	Required	Description
accrual_fraction	number	yes	ACT/360 day-count fraction.
amount	number	yes
days	integer	yes
end	string	yes	Day this financing period ends, YYYY-MM-DD: one payment_frequency step after start, which is the other end, except in the final period, which is truncated to the trade's end_date. days counts calendar days between the two.
rate	number	yes	Reference rate for the period: the fixing for the current one, the curve's forward for later ones.
start	string	yes	First day of this financing period, YYYY-MM-DD. Derived from the request alone, never resolved against a calendar or market data: the schedule begins at last_reset_date (or start_date when no reset was given) and steps by payment_frequency. Business days are not observed, so a boundary can fall on a weekend. end is the other end.

TrsPriceRequest

Body of POST /derivatives/trs/price.

Field	Type	Required	Description
currency	string	no	Default: "USD".
curve	map of string to number or null	no	Zero-rate pillars for projecting future periods. The current period always accrues at the rate already fixed at its reset.
dividend_yield	number	no	Continuous dividend yield on the underlying, used only for the breakeven table, alongside futures_prices and time_to_expiry, because a futures price embeds expected dividends. present_value, both legs and fair_spread_bps count the dividends actually paid, through dividends, not an expected yield. Sending it without futures_prices changes nothing in the response. Default: 0.0.
dividends	number	no	What the underlying paid per unit since initial_price, in its own points. They join the total-return leg: notional x ((spot + dividends) / initial_price - 1). Leave at 0 when spot is a total return level, which already counts them. Default: 0.0.
end_date	string (date)	yes	Calendar date, YYYY-MM-DD.
futures_prices	array of number or null	no	Prices to compute breakeven spreads against.
initial_price	number	yes	Level at inception or last reset.
last_reset_date	string (date) or null	no	Defaults to the start date.
notional	number	yes
payment_frequency	string	no	Default: "QUARTERLY".
reference_rate	string	no	Name of the index. Default: "SOFR".
reference_rate_value	number	no	Its current fixing, as a decimal. Default: 0.0.
reset_type	string	no	UNFUNDED accrues reference + spread; FUNDED accrues only the spread, and therefore has no rate sensitivity at all. Default: "UNFUNDED".
spot	number	yes	Underlying level today.
spread_bps	number	no	Default: 0.0.
start_date	string (date)	yes	Calendar date, YYYY-MM-DD.
time_to_expiry	number or null	no	Needed for the breakeven table.
trade_id	string	no	Identifier for the trade. Default: "TRS".
underlying_id	string	no	Default: "INDEX".
valuation_date	string (date)	yes	Calendar date, YYYY-MM-DD.

TrsPriceResponse

Response of POST /derivatives/trs/price.

Field	Type	Required	Description
accrual_days	integer	yes
accrual_fraction	number	yes	ACT/360, from the last reset.
breakeven	array of map of string to number	no	Breakeven financing spread against each supplied futures price: what makes a swap and a future agree.
dv01	number	yes	Value change per +1bp. Negative for a receiver, who pays financing: the sign carries the information a magnitude would lose. Exactly zero on a funded swap, where only the spread accrues.
fair_spread_bps	number or null	no	Spread at which the trade would be worth nothing today. Null when no time has accrued, where no spread could balance it.
financing_leg	number	yes
present_value	number	yes	Total return leg minus accrued financing, from the receiver's side.
schedule	array of TrsAccrual	yes
total_return_leg	number	yes
trade_id	string	yes
valuation_date	string (date)	yes	Calendar date, YYYY-MM-DD.

TypedSpec

One configurable object: its type and its parameters.

The types and what each accepts are listed by GET /backtest/options.

Field	Type	Required	Description
params	object	no	Its parameters, by name.
type	string	yes	The type's name, as /backtest/options lists it.

TypedSpecs

Configurable objects, each a type and its parameters. The parameter's options names the family their types come from.

Type: array of TypedSpec

TypeSpec

One configurable type a client can offer.

Field	Type	Required	Description
label	string	yes	Human-readable name for the type.
name	string	yes	Class name, as it must appear in type.
parameters	array of ParameterSpec	no
slack_unit	string or null	no	For a constraint type, what its slack is measured in: 'fraction' or 'count'. Read off the constraint class, so the same answer reaches the constraint editor here and each row of a preview's solve.constraints. Null on a selection rule or weighting scheme, which have no slack.
summary	string	no	One line describing what it does. Default: "".

UnavailableReason

Why a statistic was not worked out for the run.

Field	Type	Required	Description
code	string	yes	A short code, such as 'no_index' or 'no_futures'; GET /analysis/options labels each.
reason	string	yes	A sentence saying why, fit to show as it is.

UnavailableSpec

One reason a statistic can be unavailable.

Field	Type	Required	Description
code	string	yes	The code a block's unavailable gives.
help	string	yes	One line saying what is missing.
label	string	yes	A short name for it.

UnfilledOrderPayload

An order the simulation could not execute in full.

Field	Type	Required	Description
asset_id	string	yes
date	string	yes	The rebalance date on which the buy fell short, YYYY-MM-DD. A simulated trading day out of the backtest, not a wall-clock stamp: re-running the same backtest produces the same date. BacktestResultSummary.run_at is the wall-clock one.
filled_quantity	number	yes
price	number or null	yes	The execution price used. Null when there was none: a name that could not be priced, or an order an execution limit left unfinished.
reason	string	no	Why: 'cash' (not enough to buy it all), 'no price' (the name could not be priced on the day) or 'execution limit' (still working when the next rebalance replaced it or the run ended). Default: "cash".
reference	object or null	no	The reference columns asked for with reference_fields, keyed in lower case, as they stood on this row's date. Null when the name had no reference row then.
requested_quantity	number	yes
shortfall_value	number or null	yes	The value that went unfilled. For a name that could not be priced, the value the rebalance aimed to hold. Null for an order an execution limit left unfinished.

Universe

A named set of instrument identifiers.

Field	Type	Required	Description
as_of	string or null	no	The date a filter was last resolved at.
description	string or null	no	Optional free text.
filter	ExpressionNode or null	no	The expression this universe was built from, when it was built by filtering. Null for a curated list.
id	string	yes	Stable identifier.
identifiers	array of string	no
mode	string	no	'frozen' means the stored identifiers are the membership; 'live' means the filter is re-evaluated on read, so the membership moves when the data does. A frozen universe records what it contained; a live one records how it was chosen. They are different objects and a caller needs to know which they have. Default: "frozen".
name	string	yes	Display name.
source	string	no	'user' for one somebody created, 'seeded' for one the generator wrote. A seeded universe cannot be edited or deleted. Default: "user".

UniverseCollection

Response of GET /universes.

Field	Type	Required	Description
skipped	integer	no	Stored documents the server could not read, and so left out of this listing. Non-zero means the collection is incomplete: the fault is logged server-side, and each skipped document answers 404 on its own route. Default: 0.
skipped_causes	SkippedCauses	no	The same documents as skipped, by cause, so the listing can say what to do about them. Its three counts sum to skipped.
universes	array of Universe	yes

UniverseCreate

Body of POST /universes.

No id: the server derives one from the name, so a client cannot create two universes whose ids differ only in punctuation and expect them to be distinct documents.

Field	Type	Required	Description
description	string or null	no
filter	ExpressionNode or null	no	A serialised expression to build the membership from, instead of naming it. Mutually exclusive with a non-empty identifiers.
identifiers	array of string	no	Members. Every one must exist in the loaded reference data. Required unless a filter is given.
mode	string	no	'live' re-evaluates the filter on every read; 'frozen' keeps the membership it resolved to. Only meaningful with a filter. Default: "frozen".
name	string	yes	Display name.

UniverseMembers

Response of GET /universes/{id}/members.

Field	Type	Required	Description
identifiers	array of string	yes
universe_id	string	yes

UniverseMembership

One universe an instrument belongs to.

Field	Type	Required	Description
id	string	yes	Universe identifier, as used in the URL.
name	string	yes	Display name.
source	string	yes	'seeded' for one the server wrote from the dataset, 'user' for one somebody made.

UniverseRef

Where an index's universe comes from.

Either a reference to a stored universe or a literal list. identifiers is always populated on read, so consumers never have to resolve it.

Field	Type	Required	Description
identifiers	array of string	no	Resolved instrument identifiers.
universe_id	string or null	no	Id of a stored universe, if referenced.

UniverseUpsert

Body of PUT /universes/{id}.

Field	Type	Required	Description
description	string or null	no
identifiers	array of string	no
name	string	yes	Display name.

ValidationReport

Response of the validation endpoint, and of a rejected save.

Field	Type	Required	Description
findings	array of Finding	yes
valid	boolean	yes	False when any finding has severity 'error'.

VehiclePreset

One vehicle preset, with every setting resolved.

Field	Type	Required	Description
archetype	string	yes	'open_ended', 'exchange_traded' or 'generic'. A setting whose applies_to names an archetype belongs only to it.
key	string	yes	What vehicle.preset takes.
name	string	yes	What the structure is called.
settings	object	yes	Every setting as the preset fills it in, in the shape vehicle.settings takes.

VehicleSpec

How the money is held: a preset, with any settings laid over it.

Settings merge over the preset's: a typed object (pricing) or a list (limits) replaces the preset's whole, a plain object (market) merges key by key, an omitted key keeps the preset's value, and null means none (refused on a setting that cannot be none). Money settings are in the book's currency.

Field	Type	Required	Description
preset	string or null	no	A preset's key from /backtest/options, or null for the generic vehicle.
settings	object	no	The settings to change, by name. Only what differs from the preset need be sent.

Watchlist

A named set of instrument identifiers.

Field	Type	Required	Description
id	string	yes	Stable identifier, used in the URL.
identifiers	array of string	no	Instrument identifiers, in user order.
name	string	yes	Display name.

WatchlistCollection

Response of GET /data/watchlists.

Field	Type	Required	Description
skipped	integer	no	Stored documents the server could not read, and so left out of this listing. Non-zero means the collection is incomplete: the fault is logged server-side, and each skipped document answers 404 on its own route. Default: 0.
skipped_causes	SkippedCauses	no	The same documents as skipped, by cause, so the listing can say what to do about them. Its three counts sum to skipped.
watchlists	array of Watchlist	yes

WatchlistUpsert

Body of PUT /data/watchlists/{id}.

The id comes from the URL, so it is not repeated here: accepting it in both places invites the two to disagree.

Field	Type	Required	Description
identifiers	array of string	no	Instrument identifiers, in user order.
name	string	yes	Display name.

WeightingSpec

The weighting group of the pipeline.

Field	Type	Required	Description
id	string	no	Id used to address findings. Default: "weighting".
max_weight	number or null	no	Cap on any single constituent's weight, as a fraction (0.1 is 10%). Applied after the scheme and iterated until nothing breaches it. Null means uncapped.
params	object	no	Constructor arguments for the scheme.
scheme	string	yes	Scheme class name, e.g. 'EqualWeighted'.

WeightRow

One name's target, optimal and active weight.

Field	Type	Required	Description
active_weight	number	yes	Optimal minus target. Sums to zero across the portfolio whenever both sides are fully invested.
asset_id	string	yes
optimal_weight	number	yes
reference	object or null	no	The reference columns asked for with reference_fields, keyed in lower case, as they stood on this row's date. Null when the name had no reference row then.
target_weight	number	yes	The target's weight.

WeightsView

Response of GET /strategies/{strategy_id}/weights.

Field	Type	Required	Description
active_risk	ActiveRiskPayload or null	no	The tracking-error decomposition, when a benchmark index was named alongside risk=true.
announced_date	string (date) or null	no	When that composition was published, if earlier than rebalance_date. Null when the index has no lag.
as_of	string	yes	Date asked about.
cap	number or null	no
cap_redistributed	number	no	Default: 0.0.
capped	array of string	no
concentration	ConcentrationPayload	yes
drift	DriftPayload or null	no	Movement since the previous rebalance. Null at the first, where there is nothing to have drifted from.
index_id	string	yes	The index the strategy holds.
rebalance_date	string	yes	Rebalance in force on that date. An index holds the weights set at its last rebalance until the next one, so this is usually earlier than as_of.
risk	RiskPayload or null	no	The volatility decomposition, when risk=true was requested. Null otherwise: estimating a covariance over every constituent is the pane's whole cost, and nobody should pay it without asking.
rows	array of ConstituentRow	no	Per-constituent detail, heaviest first. Carries the same applied weights as weights, which is kept because charts and concentration maths want a mapping while a table wants ordered rows.
strategy_id	string	yes	The strategy whose latest run this reads.
weights	map of string to number	yes