# TanitFolio MCP — tool reference

> Generated by `backend/scripts/export_mcp_tools.py` from the API's routes — do not edit by hand.
> Server `tanitfolio` 0.1.0, Streamable HTTP on `/mcp`, 112 tools.
> Each tool calls the route shown, with the caller's own identity (a personal API key).
> The JSON Schema of every tool, as the server lists it, is served by `GET /api/mcp/tools`.

## Reading this file

- **role** — who sees and may call the tool: `public`, `user`, `admin`, `super admin`. The server lists only the tools of the caller's role; the API refuses the others with 403.
- **read-only** — a `GET`: nothing changes. **destructive** — a `DELETE`: the API deletes for good (an archived portfolio stays readable; a journal entry does not).
- **Argument location** — `path` and `query` are URL parts, `body` is a field of the JSON body. One flat object on the wire of MCP, whatever the location.
- **Types** — JSON Schema rendered: `integer or null` is an optional field; `enum: a \| b` lists the accepted values; `object {…}` names the fields of a nested object (the full schema is in `GET /api/mcp/tools`).
- **Results** — the JSON the route returns, as text and as `structuredContent`; a 4xx/5xx becomes an error result carrying `HTTP <status>: <detail>`.

Routes that are **not** tools: `create_api_key`, `decide_oauth_request`, `download_portfolio_import_template`, `export_analysis`, `forgot_password`, `get_oauth_request`, `list_api_keys`, `list_mcp_tools`, `list_oauth_connections`, `login`, `merge_guest`, `parse_portfolio`, `register`, `resend_verification`, `reset_password`, `revoke_api_key`, `revoke_oauth_connection`, `session_ping`, `start_guest_session`, `update_me`, `verify_email` (credentials, key management, the catalog itself, a multipart upload and two binary downloads).

## Domains

- [portfolios](#portfolios) — 36 tools
- [analyses](#analyses) — 9 tools
- [backtests](#backtests) — 4 tools
- [backtest-batches](#backtest-batches) — 4 tools
- [dashboard](#dashboard) — 3 tools
- [portfolio-comparison](#portfolio-comparison) — 1 tools
- [portfolio-strategies](#portfolio-strategies) — 1 tools
- [assets](#assets) — 13 tools
- [market-data](#market-data) — 4 tools
- [fx](#fx) — 1 tools
- [valuation](#valuation) — 1 tools
- [fundamentals](#fundamentals) — 1 tools
- [analyst-consensus](#analyst-consensus) — 1 tools
- [parameters](#parameters) — 3 tools
- [auth](#auth) — 1 tools
- [admin](#admin) — 6 tools
- [data-links](#data-links) — 19 tools
- [meta](#meta) — 2 tools
- [indicators](#indicators) — 2 tools

## portfolios

### `create_sample_portfolio` — Create a sample portfolio: 20 S&P 500 stocks opened a year ago, whole shares (BE-217)

`POST /api/portfolios/sample` · role: **user**

Create a sample portfolio: 20 S&P 500 stocks opened a year ago, whole shares (BE-217).

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `variant` (body) | enum: market_cap \\| equal_weight | yes |  |  |

### `get_favorites` — The user's favorites watchlist, or null before the first star

`GET /api/portfolios/favorites` · role: **user** · read-only

The user's favorites watchlist, or null before the first star.
The user's favorites: one special watchlist (is_favorites), or null before the first star. Use its id like any watchlist id (analysis scope, backtests, history).

No arguments.

### `add_favorite` — Star a ticker: add it to the favorites watchlist, created at the first star

`POST /api/portfolios/favorites/items` · role: **user**

Star a ticker: add it to the favorites watchlist, created at the first star.
The star: adds a ticker to the favorites without choosing a list — the list is created at the first star. Already a favorite answers 200, not an error.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `ticker` (body) | string | yes |  |  |
| `platform` (body) | string or null | no |  |  |

### `remove_favorite` — Unstar a ticker: remove it from the favorites watchlist

`DELETE /api/portfolios/favorites/items/{ticker}` · role: **user** · destructive

Unstar a ticker: remove it from the favorites watchlist.
Removes a ticker from the favorites (204 even when absent); the list stays and its history keeps the dates.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `ticker` (path) | string | yes |  |  |

### `create_portfolio_from_json` — Register a portfolio from JSON (manual input)

`POST /api/portfolios/from-json` · role: **user**

Register a portfolio from JSON (manual input).
Accepts a list of assets in JSON format (no Excel required). Returns the same structure as POST /portfolios/parse. Quantity, Price and Amount are all optional — assets with zero Amount are treated as watchlist entries.
Parses a list of assets into a temporary analysis input (30 min) and returns a string portfolio_id for create_analysis's legacy portfolio_id field. Nothing is saved: to keep a portfolio, use create_or_replace_portfolio.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `assets` (body) | array of object {ticker, type, asset_name, platform, quantity, price, amount, manual_target_price} | yes |  |  |

### `preview_portfolio` — Preview portfolio composition with asset enrichment (no persistence)

`POST /api/portfolios/preview` · role: **user**

Preview portfolio composition with asset enrichment (no persistence).
Enriches a list of assets (names, prices, weights) without saving anything: use it to check tickers before create_or_replace_portfolio.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `kind` (body) | enum: portfolio \\| watchlist | yes |  |  |
| `name` (body) | string | yes |  |  |
| `assets` (body) | array of object {ticker, quantity, amount} | yes |  |  |

### `create_or_replace_portfolio` — Create or replace a portfolio or watchlist

`POST /api/portfolios` · role: **user**

Create or replace a portfolio or watchlist.
Creates a portfolio or a watchlist (kind) with its assets; with an id, replaces that one. A portfolio needs at least one asset (400 otherwise); a watchlist may start empty. Positions are opened in the journal at creation. To add a trade later, prefer create_transaction.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `id` (body) | integer or null | no |  |  |
| `kind` (body) | enum: portfolio \\| watchlist | yes |  |  |
| `name` (body) | string | yes |  |  |
| `status` (body) | enum: draft \\| validated \\| simulated | no | draft |  |
| `assets` (body) | array of object {ticker, asset_type, asset_name, platform, quantity, price, amount, manual_target_price, acquisition_price, acquisition_date} | no |  |  |

### `list_portfolios` — List the authenticated user's portfolios and watchlists

`GET /api/portfolios` · role: **user** · read-only

List the authenticated user's portfolios and watchlists.
Every portfolio and watchlist of the user with its id, kind (portfolio | watchlist), status (draft | validated | simulated), name and totals. Use the id with the other portfolio tools.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `kind` (query) | enum: portfolio \\| watchlist or null | no |  | Filter by kind |

### `get_portfolio_detail` — Get a single portfolio or watchlist with all assets

`GET /api/portfolios/{portfolio_id}` · role: **user** · read-only

Get a single portfolio or watchlist with all assets.
The portfolio with its assets as held today (quantities, prices, cost basis, PnL). For prices, sparklines and indicators per position call get_portfolio_composition.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |

### `patch_portfolio` — Update name and/or status of a portfolio or watchlist

`PATCH /api/portfolios/{portfolio_id}` · role: **user**

Update name and/or status of a portfolio or watchlist.
Renames a portfolio or changes its status (draft | validated | simulated).

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |
| `name` (body) | string or null | no |  |  |
| `status` (body) | enum: draft \\| validated \\| simulated or null | no |  |  |
| `tax_residence` (body) | enum: FR \\| DE \\| US \\|  or null | no |  |  |
| `display_currency` (body) | string or null | no |  |  |
| `opening_date` (body) | string (date) or null | no |  |  |

### `delete_portfolio` — Archive a portfolio or watchlist (soft delete)

`DELETE /api/portfolios/{portfolio_id}` · role: **user** · destructive

Archive a portfolio or watchlist (soft delete).
Archives the portfolio (soft delete): it leaves the lists but its data stays.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |

### `patch_portfolio_status` — Change the status of a portfolio or watchlist (legacy endpoint)

`PATCH /api/portfolios/{portfolio_id}/status` · role: **user**

Change the status of a portfolio or watchlist (legacy endpoint).

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |
| `status` (body) | enum: draft \\| validated \\| simulated | yes |  |  |

### `get_portfolio_composition` — Get enriched composition: latest prices, PnL, sparklines (BE-25)

`GET /api/portfolios/{portfolio_id}/composition` · role: **user** · read-only

Get enriched composition: latest prices, PnL, sparklines (BE-25).
Latest prices, weights, PnL, sparklines, momentum and fundamentals per position, plus the cash line (USD=X). Window: 1W | 1M | 3M | 1Y | YTD.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |
| `window` (query) | enum: 1W \\| 1M \\| 3M \\| 1Y \\| YTD | no | 1M | Sparkline time window |
| `currency` (query) | string or null | no |  | BE-101: display currency of the *_display fields (default: the portfolio's) |

### `get_portfolio_sparklines` — Refresh portfolio sparklines for a given time window (BE-25)

`GET /api/portfolios/{portfolio_id}/composition/sparklines` · role: **user** · read-only

Refresh portfolio sparklines for a given time window (BE-25).

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |
| `window` (query) | enum: 1W \\| 1M \\| 3M \\| 1Y \\| YTD | no | 1M | Sparkline time window |

### `get_portfolio_performance` — Backcast performance of the current allocation vs a benchmark (BE-40)

`GET /api/portfolios/{portfolio_id}/performance` · role: **user** · read-only

Backcast performance of the current allocation vs a benchmark (BE-40).
Time-weighted performance of the actual holdings versus a benchmark (^GSPC by default), from the journal; a curve of dated values in USD.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |
| `window` (query) | enum: 1M \\| 3M \\| YTD \\| MTD \\| 1Y \\| 2Y | no | 1Y | Backcast time window |
| `benchmark` (query) | string or null | no | ^GSPC | Benchmark ticker, omit for none |
| `currency` (query) | string or null | no |  | BE-101: currency the curves are measured in (default: the portfolio's) |
| `allow_projection` (query) | boolean | no | False | BE-74 §mod: when the journal has fewer than two priced days, chart the current composition over the window instead of no curve (a labelled what-if, e.g. the welcome summary). Off: a portfolio's curve never shows a past it did not live. |

### `get_portfolio_pnl` — PnL since inception (USD) and annualised XIRR of this portfolio (BE-143)

`GET /api/portfolios/{portfolio_id}/pnl` · role: **user** · read-only

PnL since inception (USD) and annualised XIRR of this portfolio (BE-143).
PnL since inception in USD, split by price, FX and dividends, and the annualised XIRR.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |

### `refresh_portfolio_scorecard` — Recompute the 'current' scorecard row — no optimizer solve (BE-76)

`POST /api/portfolios/{portfolio_id}/scorecard/refresh` · role: **user**

Recompute the 'current' scorecard row — no optimizer solve (BE-76).
Recomputes the 'current' scorecard row with the latest prices, without running any optimiser.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |

### `clone_portfolio` — Clone a portfolio (full journal) or a watchlist (current members)

`POST /api/portfolios/{portfolio_id}/clone` · role: **user**

Clone a portfolio (full journal) or a watchlist (current members).
Copies a portfolio with its whole journal, or a watchlist with its current members.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |
| `body` (body) | object {name, status} or null | no |  | The JSON request body |

### `create_transaction` — Record a buy, a sell, a deposit or a withdrawal on a portfolio

`POST /api/portfolios/{portfolio_id}/transactions` · role: **user**

Record a buy, a sell, a deposit or a withdrawal on a portfolio.
side: buy | sell | deposit | withdraw. A buy or sell needs ticker, quantity and price (native currency of the ticker); transaction_date defaults to today; fx_rate, payment_currency and payment_amount are optional. A deposit or withdraw needs amount (USD unless payment_currency is given). The position and the cash are replayed at once.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |
| `ticker` (body) | string or null | no |  |  |
| `side` (body) | enum: buy \\| sell \\| deposit \\| withdraw | yes |  |  |
| `transaction_date` (body) | string (date) or null | no |  |  |
| `quantity` (body) | number or null | no |  |  |
| `amount` (body) | number or null | no |  |  |
| `price` (body) | number or null | no |  |  |
| `fx_rate` (body) | number or null | no |  |  |
| `note` (body) | string or null | no |  |  |
| `payment_currency` (body) | string or null | no |  |  |
| `payment_amount` (body) | number or null | no |  |  |
| `payment_price` (body) | number or null | no |  |  |
| `payment_fx_rate` (body) | number or null | no |  |  |
| `commission_usd` (body) | number or null | no |  |  |

### `list_transactions` — List the transaction journal of a portfolio

`GET /api/portfolios/{portfolio_id}/transactions` · role: **user** · read-only

List the transaction journal of a portfolio.
The journal: every buy, sell, deposit, withdraw, dividend, open and adjust entry, oldest first.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |
| `ticker` (query) | string or null | no |  | Filter by ticker |

### `update_transaction` — Correct a transaction and replay the position

`PATCH /api/portfolios/{portfolio_id}/transactions/{tx_id}` · role: **user**

Correct a transaction and replay the position.
Corrects one journal entry (same fields as create_transaction) and replays the position.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |
| `tx_id` (path) | integer | yes |  |  |
| `transaction_date` (body) | string (date) or null | no |  |  |
| `quantity` (body) | number or null | no |  |  |
| `amount` (body) | number or null | no |  |  |
| `price` (body) | number or null | no |  |  |
| `fx_rate` (body) | number or null | no |  |  |
| `note` (body) | string or null | no |  |  |
| `payment_currency` (body) | string or null | no |  |  |
| `payment_amount` (body) | number or null | no |  |  |
| `payment_price` (body) | number or null | no |  |  |
| `payment_fx_rate` (body) | number or null | no |  |  |
| `commission_usd` (body) | number or null | no |  |  |

### `delete_transaction` — Delete a transaction and replay the position

`DELETE /api/portfolios/{portfolio_id}/transactions/{tx_id}` · role: **user** · destructive

Delete a transaction and replay the position.
Removes one journal entry and replays the position. Irreversible.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |
| `tx_id` (path) | integer | yes |  |  |

### `get_watchlist_history` — List the membership history (added/removed dates) of a watchlist

`GET /api/portfolios/{portfolio_id}/watchlist-history` · role: **user** · read-only

List the membership history (added/removed dates) of a watchlist.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |
| `ticker` (query) | string or null | no |  | Filter by ticker |

### `add_watchlist_item` — Add one ticker to a watchlist

`POST /api/portfolios/{portfolio_id}/watchlist-items` · role: **user**

Add one ticker to a watchlist.
Adds a ticker to a watchlist (added_date optional, defaults to today).

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |
| `ticker` (body) | string | yes |  |  |
| `platform` (body) | string or null | no |  |  |
| `manual_target_price` (body) | number or null | no |  |  |

### `delete_watchlist_item` — Remove one ticker from a watchlist

`DELETE /api/portfolios/{portfolio_id}/watchlist-items/{ticker}` · role: **user** · destructive

Remove one ticker from a watchlist.
Removes a ticker from a watchlist; the membership history keeps the dates.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |
| `ticker` (path) | string | yes |  |  |

### `update_watchlist_item` — Change the date a ticker was added to a watchlist (BE-95)

`PATCH /api/portfolios/{portfolio_id}/watchlist-items/{ticker}` · role: **user**

Change the date a ticker was added to a watchlist (BE-95).
Backdate the current membership period — the only way a watchlist can say it
was following an asset before the app recorded it, which a point-in-time
backtest (BE-95) reads as "known since". A date before the watchlist's own
creation is the normal case, not an error.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |
| `ticker` (path) | string | yes |  |  |
| `added_date` (body) | string (date) | yes |  |  |

### `update_asset_discovery_date` — Set or reset the discovery date of a portfolio asset

`PATCH /api/portfolios/{portfolio_id}/assets/{ticker}` · role: **user**

Set or reset the discovery date of a portfolio asset.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |
| `ticker` (path) | string | yes |  |  |
| `discovery_date` (body) | string (date) or null | yes |  |  |

### `set_asset_analysis_exclusion` — Exclude a position from the analyses, or bring it back

`PATCH /api/portfolios/{portfolio_id}/assets/{ticker}/analysis-exclusion` · role: **user**

Exclude a position from the analyses, or bring it back.
BE-255: an excluded position gets a target of 0 in every analysis, backtest and strategy that reads this portfolio (the analysis proposes to sell it, its value is reallocated); the current portfolio keeps it. The flag stays until it is removed. Portfolios only: on a watchlist, remove the asset instead.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |
| `ticker` (path) | string | yes |  |  |
| `is_excluded` (body) | boolean | yes |  |  |

### `add_observation` — Track an asset in a portfolio without holding it

`POST /api/portfolios/{portfolio_id}/observations` · role: **user**

Track an asset in a portfolio without holding it.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |
| `ticker` (body) | string | yes |  |  |
| `discovery_date` (body) | string (date) or null | no |  |  |
| `platform` (body) | string or null | no |  |  |
| `manual_target_price` (body) | number or null | no |  |  |

### `delete_observation` — Stop observing an asset

`DELETE /api/portfolios/{portfolio_id}/observations/{ticker}` · role: **user** · destructive

Stop observing an asset.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |
| `ticker` (path) | string | yes |  |  |

### `get_strategy_runs` — The decisions of the portfolio's strategy, newest first (BE-198)

`GET /api/portfolios/{portfolio_id}/strategy/runs` · role: **user** · read-only

The decisions of the portfolio's strategy, newest first (BE-198).
The decisions log of a portfolio's automatic strategy (BE-198).

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |
| `limit` (query) | integer | no | 50 |  |

### `get_strategy_settings` — The settings the strategy's next decision will use, and which of them can be edited (BE-208)

`GET /api/portfolios/{portfolio_id}/strategy/parameters` · role: **user** · read-only

The settings the strategy's next decision will use, and which of them can be edited (BE-208).

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |

### `update_strategy` — Edit the strategy's settings: forward-only, the decisions already written never change (BE-208)

`PATCH /api/portfolios/{portfolio_id}/strategy` · role: **user**

Edit the strategy's settings: forward-only, the decisions already written never change (BE-208).

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |
| `method` (body) | string or null | no |  |  |
| `rebalance_frequency` (body) | enum: weekly \\| monthly \\| quarterly \\| yearly or null | no |  |  |
| `transaction_cost_rate` (body) | number or null | no |  |  |
| `fee_per_buy_usd` (body) | number or null | no |  |  |
| `fee_per_sell_usd` (body) | number or null | no |  |  |
| `parameters` (body) | object or null | no |  |  |

### `suspend_strategy` — Pause the strategy: nothing is traded until it is resumed (BE-198)

`POST /api/portfolios/{portfolio_id}/strategy/suspend` · role: **user**

Pause the strategy: nothing is traded until it is resumed (BE-198).
Pauses a portfolio's automatic strategy; resume_strategy restarts it, disable_strategy ends it.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |

### `resume_strategy` — Resume the strategy from the next decision; the missed ones are not replayed (BE-198 A4)

`POST /api/portfolios/{portfolio_id}/strategy/resume` · role: **user**

Resume the strategy from the next decision; the missed ones are not replayed (BE-198 A4).

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |

### `disable_strategy` — Stop the strategy for good: the portfolio becomes manual, its trades stay (BE-198)

`POST /api/portfolios/{portfolio_id}/strategy/disable` · role: **user**

Stop the strategy for good: the portfolio becomes manual, its trades stay (BE-198).

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (path) | integer | yes |  |  |

## analyses

### `create_analysis` — Start a full optimisation in the background (BE-202)

`POST /api/analyses` · role: **user**

Start a full optimisation in the background (BE-202).
Launches an optimisation in the background and answers 202 with analysis_id. Select the universe with portfolio_ids_persistent and/or watchlist_ids_persistent (ids from list_portfolios), or scope = all_assets with optional scope_filters. parameters: get the defaults from get_parameter_defaults and override what the user asks (methods, constraints, return estimation, quantity_mode). Then poll fetch_analysis_status every few seconds until status is completed or failed, and read the results with fetch_analysis. The 202 answer's warnings list settings that cannot act (parameter_ignored: e.g. the momentum filter with composite_score, or a setting no chosen method reads) and a noisy EWMA half-life (short_halflife_noise): tell the user about each of them.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id_persistent` (body) | integer or null | no |  |  |
| `watchlist_id_persistent` (body) | integer or null | no |  |  |
| `portfolio_ids_persistent` (body) | array of integer | no |  |  |
| `watchlist_ids_persistent` (body) | array of integer | no |  |  |
| `scope` (body) | enum: portfolio_only \\| watchlist_only \\| both \\| all_assets or null | no |  |  |
| `scope_filters` (body) | object {asset_types, markets} or null | no |  |  |
| `portfolio_id` (body) | string or null | no |  |  |
| `parameters` (body) | object {risk_aversion_lambda, risk_free_rate, risk_measure, mar_sortino, max_weight_per_asset, optimization_methods, max_weight_equity, min_weight_equity, max_weight_crypto, max_weight_currency, bl_market_weights_mode, bl_tau, momentum_filter_enabled, target_decay_enabled, return_estimation, aggregated_target_statistic, synthetic_target_horizon, synthetic_target_fallback, synthetic_target_ma_window, blend_alpha, ewma_halflife_years, quantity_mode, quantity_capital_usd, max_expected_return, composite_k, composite_preset, composite_family_weights, composite_trend_filter, composite_min_dollar_volume_usd, composite_max_amihud, profile, relax_infeasible_asset_cap} | yes |  | Subset of optimizer parameters validated for the REST API. |
| `bl_views` (body) | array of object {view_id, view_type, asset_1, asset_2, expected_return, confidence} | no |  |  |
| `sparkline_window` (body) | enum: 1W \\| 1M \\| 3M \\| 1Y \\| YTD | no | 1M |  |

### `list_analyses` — Paginated analyses for the authenticated user

`GET /api/analyses` · role: **user** · read-only

Paginated analyses for the authenticated user.
The user's analyses, newest first, with status, best method and best Sharpe. Filter by linked portfolio or watchlist.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `limit` (query) | integer | no | 20 |  |
| `offset` (query) | integer | no | 0 |  |
| `sort` (query) | enum: created_at_desc \\| created_at_asc \\| sharpe_desc \\| sharpe_asc | no | created_at_desc | Sorting mode for analyses |
| `linked_portfolio_id` (query) | integer or null | no |  | Filter analyses linked to this persistent portfolio id |
| `linked_watchlist_id` (query) | integer or null | no |  | Filter analyses linked to this persistent watchlist id |

### `get_all_assets_facets` — Asset classes and markets of the referential, with counts (BE-180)

`GET /api/analyses/all-assets-facets` · role: **user** · read-only

Asset classes and markets of the referential, with counts (BE-180).
The asset classes and markets available as scope_filters for an all_assets analysis.

No arguments.

### `fetch_analysis_status` — Status of a background optimisation (BE-202)

`GET /api/analyses/{analysis_id}/status` · role: **user** · read-only

Status of a background optimisation (BE-202).
pending | running | completed | failed, with elapsed_seconds and the error when failed.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `analysis_id` (path) | integer | yes |  |  |

### `fetch_analysis` — Fetch Analysis

`GET /api/analyses/{analysis_id}` · role: **user** · read-only

Fetch Analysis.
The full results of a completed analysis: per method, the weights, the metrics (return, volatility, Sharpe) and the scorecard; best_method names the winner. A 409 analysis_not_completed means it is still running. The payload is large: summarise it.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `analysis_id` (path) | integer | yes |  |  |

### `delete_analysis` — Delete Analysis

`DELETE /api/analyses/{analysis_id}` · role: **user** · destructive

Delete Analysis.
Deletes an analysis and its links. Irreversible.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `analysis_id` (path) | integer | yes |  |  |

### `fetch_analysis_sparklines` — Sparkline price series for an analysis portfolio

`GET /api/analyses/{analysis_id}/sparklines` · role: **user** · read-only

Sparkline price series for an analysis portfolio.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `analysis_id` (path) | integer | yes |  |  |
| `window` (query) | enum: 1W \\| 1M \\| 3M \\| 1Y \\| YTD | no | 1M | Sparkline time window |

### `clone_analysis_method_to_portfolio` — Hold one optimiser's allocation in a new simulated portfolio (BE-190)

`POST /api/analyses/{analysis_id}/clone-portfolio` · role: **user**

Hold one optimiser's allocation in a new simulated portfolio (BE-190).
Creates a simulated portfolio holding one method's allocation; optionally runs it automatically on a schedule (strategy).

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `analysis_id` (path) | integer | yes |  |  |
| `method` (body) | string | yes |  |  |
| `name` (body) | string | yes |  |  |
| `capital_usd` (body) | number | yes |  |  |
| `strategy` (body) | object {rebalance_frequency, transaction_cost_rate, fee_per_buy_usd, fee_per_sell_usd} or null | no |  |  |

### `apply_analysis` — Apply optimized weights to create or overwrite a portfolio (post-analysis rebalancing)

`POST /api/analyses/{analysis_id}/apply` · role: **user**

Apply optimized weights to create or overwrite a portfolio (post-analysis rebalancing).
Writes one method's weights into a portfolio: target_portfolio_id overwrites an existing one, new_portfolio_name creates a new one. overrides adjusts quantities per ticker.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `analysis_id` (path) | integer | yes |  |  |
| `method` (body) | string | yes |  | Optimization method whose weights to apply |
| `overrides` (body) | array of object {ticker, quantity, amount} | no |  | Sparse per-ticker quantity/amount edits; replaces method defaults |
| `target_portfolio_id` (body) | integer or null | no |  |  |
| `new_portfolio_name` (body) | string or null | no |  |  |

## backtests

### `create_backtest` — Create Backtest

`POST /api/backtests` · role: **user**

Create Backtest.
Replays an analysis's optimisation over start_date..end_date with the chosen method and rebalance_frequency (daily | weekly | monthly | quarterly | yearly). Answers 202 with backtest_id; poll get_backtest until status is completed, then read its summary, curves and decisions. Its warnings (in the 202 answer and the result) include parameter_ignored and short_halflife_noise: relay them to the user.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `analysis_id` (body) | integer | yes |  |  |
| `start_date` (body) | string (date) | yes |  |  |
| `end_date` (body) | string (date) | yes |  |  |
| `method` (body) | enum: max_sharpe \\| max_sortino \\| max_utility \\| min_variance \\| hrp_pragmatic \\| hrp_strict | no | max_sharpe |  |
| `rebalance_frequency` (body) | enum: weekly \\| monthly \\| quarterly \\| yearly | no | weekly |  |
| `transaction_cost_rate` (body) | number | no | 0.001 |  |
| `fee_per_buy_usd` (body) | number | no | 0.0 |  |
| `fee_per_sell_usd` (body) | number | no | 0.0 |  |
| `fee_capital_usd` (body) | number | no | 100000.0 |  |
| `benchmark` (body) | string or null | no | ^GSPC |  |
| `universe_mode` (body) | enum: current \\| point_in_time | no | current |  |

### `list_backtests` — List Backtests

`GET /api/backtests` · role: **user** · read-only

List Backtests.
The user's backtests with their status and summary; rows that belong to a batch are hidden.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `portfolio_id` (query) | integer or null | no |  |  |
| `analysis_id` (query) | integer or null | no |  |  |

### `get_backtest` — Get Backtest

`GET /api/backtests/{backtest_id}` · role: **user** · read-only

Get Backtest.
Status, summary statistics (return, volatility, Sharpe, max drawdown), value curves and per-decision allocations of a backtest.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `backtest_id` (path) | integer | yes |  |  |

### `clone_backtest_to_portfolio` — Hold a run's last allocation in a new simulated portfolio (BE-178)

`POST /api/backtests/{backtest_id}/clone-portfolio` · role: **user**

Hold a run's last allocation in a new simulated portfolio (BE-178).
Creates a simulated portfolio from the last allocation of a completed backtest.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `backtest_id` (path) | integer | yes |  |  |
| `name` (body) | string | yes |  |  |
| `capital_usd` (body) | number | yes |  |  |
| `strategy` (body) | object {rebalance_frequency, transaction_cost_rate, fee_per_buy_usd, fee_per_sell_usd} or null | no |  |  |

## backtest-batches

### `create_backtest_batch` — Create Backtest Batch

`POST /api/backtest-batches` · role: **user**

Create Backtest Batch.
One backtest per combination of the grid (optimisers × return sources × decays × momentum × risk measures) over the same window. Answers 202 with batch_id and deduplicated_count, the ticked combinations not run because they could not differ from another (e.g. momentum on/off with composite_score); poll get_backtest_batch. Relay each run's parameter_ignored and short_halflife_noise warnings to the user.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `analysis_id` (body) | integer | yes |  |  |
| `start_date` (body) | string (date) | yes |  |  |
| `end_date` (body) | string (date) | yes |  |  |
| `rebalance_frequency` (body) | enum: weekly \\| monthly \\| quarterly \\| yearly | no | weekly |  |
| `transaction_cost_rate` (body) | number | no | 0.001 |  |
| `fee_per_buy_usd` (body) | number | no | 0.0 |  |
| `fee_per_sell_usd` (body) | number | no | 0.0 |  |
| `fee_capital_usd` (body) | number | no | 100000.0 |  |
| `benchmark` (body) | string or null | no | ^GSPC |  |
| `universe_mode` (body) | enum: current \\| point_in_time | no | current |  |
| `grid` (body) | object {methods, return_estimations, target_decay, momentum_filter, risk_measures, consensus_statistics, composite_k, composite_presets, composite_trend_filter, composite_min_dollar_volume_usd, composite_max_amihud} | yes |  | Values ticked for each dimension. Combinations that cannot differ are collapsed by ``expand_grid`` (see the service), never run twice. |

### `list_backtest_batches` — List Backtest Batches

`GET /api/backtest-batches` · role: **user** · read-only

List Backtest Batches.
The user's batches, newest first.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `analysis_id` (query) | integer or null | no |  |  |

### `extend_backtest_batch` — Extend Backtest Batch

`POST /api/backtest-batches/{batch_id}/runs` · role: **user**

Extend Backtest Batch.
Adds the ticked combinations a finished batch does not hold yet, and runs them.
Adds combinations to a finished batch.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `batch_id` (path) | integer | yes |  |  |
| `grid` (body) | object {methods, return_estimations, target_decay, momentum_filter, risk_measures, consensus_statistics, composite_k, composite_presets, composite_trend_filter, composite_min_dollar_volume_usd, composite_max_amihud} | yes |  | Values ticked for each dimension. Combinations that cannot differ are collapsed by ``expand_grid`` (see the service), never run twice. |

### `get_backtest_batch` — Get Backtest Batch

`GET /api/backtest-batches/{batch_id}` · role: **user** · read-only

Get Backtest Batch.
The batch's runs with their summaries and the reference curves (1/N, S&P 500, static t0, actual portfolio, market cap).

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `batch_id` (path) | integer | yes |  |  |
| `include_series` (query) | boolean | no | True |  |

## dashboard

### `get_dashboard_performance` — Performance of every validated portfolio, their combined value, and a benchmark (BE-80)

`GET /api/dashboard/performance` · role: **user** · read-only

Performance of every validated portfolio, their combined value, and a benchmark (BE-80).
Every validated portfolio's curve, the value-weighted aggregate and the S&P 500, as on the dashboard.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `window` (query) | enum: 1M \\| 3M \\| YTD \\| MTD \\| 1Y \\| 2Y | no | YTD | Backcast time window |
| `benchmark` (query) | string or null | no | ^GSPC | Benchmark ticker, omit for none |

### `get_dashboard_totals` — Cross-portfolio totals (validated portfolios only), cached prices only (BE-138)

`GET /api/dashboard/totals` · role: **user** · read-only

Cross-portfolio totals (validated portfolios only), cached prices only (BE-138).
Total value, cash and invested amount across the validated portfolios, in USD.

No arguments.

### `get_dashboard_pnl` — PnL since inception and annualised XIRR across every validated portfolio (BE-141)

`GET /api/dashboard/pnl` · role: **user** · read-only

PnL since inception and annualised XIRR across every validated portfolio (BE-141).
PnL since inception and YTD across the validated portfolios.

No arguments.

## portfolio-comparison

### `get_portfolio_comparison` — Two to four portfolios over their common period, in one currency (BE-192)

`GET /api/portfolio-comparison` · role: **user** · read-only

Two to four portfolios over their common period, in one currency (BE-192).
Two to four portfolios (ids) compared over their common period: curves and statistics.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `ids` (query) | string | yes |  | Portfolio ids, comma-separated; the first is the reference |
| `window` (query) | enum: 1M \\| 3M \\| YTD \\| MTD \\| 1Y \\| 2Y | no | 1Y |  |
| `benchmark` (query) | string or null | no | ^GSPC | Benchmark ticker, empty for none |
| `currency` (query) | string or null | no |  |  |

## portfolio-strategies

### `run_due_strategies` — Run every active strategy that has a decision due (admins; the scheduled job does the same)

`POST /api/portfolio-strategies/run-due` · role: **admin**

Run every active strategy that has a decision due (admins; the scheduled job does the same).

No arguments.

## assets

### `get_assets_overview` — Every referential asset with price, sparkline, momentum and fundamentals (BE-176)

`GET /api/assets/overview` · role: **user** · read-only

Every referential asset with price, sparkline, momentum and fundamentals (BE-176).
The referential is shared and its data public: only ``memberships`` is the user's.
The whole asset referential with price, sparkline, momentum, short-term signals, fundamentals and which portfolios hold each ticker. `fields` picks the short-term codes (V1 by default). Large: filter on the client side.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `window` (query) | enum: 1W \\| 1M \\| 3M \\| 1Y \\| YTD | no | 1M | Sparkline time window |
| `fields` (query) | array of string or null | no |  | BE-221 — short-term indicator codes to return in each row's `short_term` (repeat the parameter, or comma-separate); the V1 indicators when absent. Codes: GET /api/indicators/catalog, family `short_term`. |

### `get_assets_overview_sparklines` — Referential sparklines for a given window (BE-176)

`GET /api/assets/overview/sparklines` · role: **user** · read-only

Referential sparklines for a given window (BE-176).

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `window` (query) | enum: 1W \\| 1M \\| 3M \\| 1Y \\| YTD | no | 1M | Sparkline time window |

### `search_assets` — Search the referential by ticker or name, short answers (BE-210)

`GET /api/assets/search` · role: **user** · read-only

Search the referential by ticker or name, short answers (BE-210).
The referential is shared and public (BE-176): no ``user_id`` filter.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `q` (query) | string | yes |  | What the user typed |
| `limit` (query) | integer | no | 8 |  |
| `types` (query) | array of string or null | no |  | Restrict to these stored asset types |

### `get_asset_markets` — The markets and asset classes an asset can be added on (BE-210)

`GET /api/assets/markets` · role: **user** · read-only

The markets and asset classes an asset can be added on (BE-210).

No arguments.

### `lookup_asset` — Add an asset to the referential from its ticker and market (BE-210)

`POST /api/assets/lookup` · role: **user**

Add an asset to the referential from its ticker and market (BE-210).

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `ticker` (body) | string | yes |  |  |
| `market` (body) | string or null | no |  |  |
| `asset_class` (body) | string | no | Equity |  |
| `quote` (body) | string or null | no |  |  |

### `get_asset_profile` — Profile of one ticker: identity, last price, depth, holdings, sections (BE-186)

`GET /api/assets/{ticker}` · role: **user** · read-only

Profile of one ticker: identity, last price, depth, holdings, sections (BE-186).
The referential is shared and its data public: only ``memberships`` is the user's.
Name, sector, market, currency and memberships of one ticker.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `ticker` (path) | string | yes |  |  |

### `get_asset_prices` — Quoted price and total return of every stored bar, in columns (BE-186)

`GET /api/assets/{ticker}/prices` · role: **user** · read-only

Quoted price and total return of every stored bar, in columns (BE-186).
Daily closes of one ticker over a window.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `ticker` (path) | string | yes |  |  |
| `start` (query) | string (date) or null | no |  | First date, inclusive (ISO) |
| `end` (query) | string (date) or null | no |  | Last date, inclusive (ISO) |

### `get_asset_momentum` — Momentum and trend indicators of every bar, each with its status (BE-186)

`GET /api/assets/{ticker}/momentum` · role: **user** · read-only

Momentum and trend indicators of every bar, each with its status (BE-186).
Trend & momentum family (1–12 months) of one ticker: 12-1 momentum, residual momentum, trend slopes, trend divergence and breaking-trend flag, volatility, beta.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `ticker` (path) | string | yes |  |  |
| `start` (query) | string (date) or null | no |  | First date, inclusive (ISO) |
| `end` (query) | string (date) or null | no |  | Last date, inclusive (ISO) |

### `get_asset_short_term` — Short-term technical indicators of every bar, each with its status (BE-221)

`GET /api/assets/{ticker}/short-term` · role: **user** · read-only

Short-term technical indicators of every bar, each with its status (BE-221).
Short-term signals family (2 to 20 trading days), in columns: one value and one
``*_status`` per indicator code of ``GET /api/indicators/catalog``. Without ``start``,
the last 252 bars up to ``end``.
Short-term signals family (2–20 trading days) of one ticker: returns, MACD, ADX, RSI, stochastic, Bollinger, ATR, volatility regime, volume and liquidity, each with its status. Default window: the last 252 bars.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `ticker` (path) | string | yes |  |  |
| `start` (query) | string (date) or null | no |  | First date, inclusive (ISO) |
| `end` (query) | string (date) or null | no |  | Last date, inclusive (ISO) |

### `get_asset_financials` — Amounts of each period as first published, dated by availability (BE-186)

`GET /api/assets/{ticker}/financials` · role: **user** · read-only

Amounts of each period as first published, dated by availability (BE-186).
Point-in-time financial statements and fundamental indicators of one ticker (as published, dated by publication).

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `ticker` (path) | string | yes |  |  |
| `start` (query) | string (date) or null | no |  | First date, inclusive (ISO) |
| `end` (query) | string (date) or null | no |  | Last date, inclusive (ISO) |

### `get_asset_insiders` — Daily insider indicators and the latest Form 4 lines, bounded on filing date (BE-186)

`GET /api/assets/{ticker}/insiders` · role: **user** · read-only

Daily insider indicators and the latest Form 4 lines, bounded on filing date (BE-186).
Form 4 insider transactions of one ticker, dated by filing date.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `ticker` (path) | string | yes |  |  |
| `start` (query) | string (date) or null | no |  | First date, inclusive (ISO) |
| `end` (query) | string (date) or null | no |  | Last date, inclusive (ISO) |
| `limit` (query) | integer | no | 50 | Number of rows, newest first |
| `include_holdings` (query) | boolean | no | False | Also list the holding lines (a position, no trade) |

### `get_asset_analysts` — Consensus target history and the latest analyst actions (BE-186)

`GET /api/assets/{ticker}/analysts` · role: **user** · read-only

Consensus target history and the latest analyst actions (BE-186).
Analyst actions (ratings, targets) and the rebuilt consensus of one ticker.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `ticker` (path) | string | yes |  |  |
| `start` (query) | string (date) or null | no |  | First date, inclusive (ISO) |
| `end` (query) | string (date) or null | no |  | Last date, inclusive (ISO) |
| `limit` (query) | integer | no | 50 | Number of rows, newest first |

### `get_asset_corporate_actions` — Dividends and splits of the ticker, newest first (BE-186)

`GET /api/assets/{ticker}/corporate-actions` · role: **user** · read-only

Dividends and splits of the ticker, newest first (BE-186).
Splits and dividends of one ticker.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `ticker` (path) | string | yes |  |  |

## market-data

### `list_market_data_jobs` — List Market Data Jobs

`GET /api/market-data/jobs` · role: **user** · read-only

List Market Data Jobs.

No arguments.

### `create_market_data_job` — Create Market Data Job

`POST /api/market-data/jobs` · role: **user**

Create Market Data Job.
Fetches price history (and optionally fundamentals, insiders, analyst targets, splits/dividends) for tickers; answers with job_id, poll get_market_data_job.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `start_date` (body) | string (date) | yes |  |  |
| `end_date` (body) | string (date) | yes |  |  |
| `job_type` (body) | enum: market_data \\| analyst_targets \\| analyst_actions \\| synthetic_targets \\| corporate_actions \\| insider_transactions \\| financial_statements \\| valuation_reconstruction | no | market_data |  |
| `job_types` (body) | array of enum: market_data \\| analyst_targets \\| analyst_actions \\| synthetic_targets \\| corporate_actions \\| insider_transactions \\| financial_statements \\| valuation_reconstruction or null | no |  |  |
| `tickers` (body) | array of string or null | no |  |  |

### `get_market_data_job` — Get Market Data Job

`GET /api/market-data/jobs/{job_id}` · role: **user** · read-only

Get Market Data Job.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `job_id` (path) | integer | yes |  |  |

### `search_market_data_tickers` — Search Market Data Tickers

`GET /api/market-data/tickers` · role: **user** · read-only

Search Market Data Tickers.
BE-188 §6 — the referential is shared (BE-176): any signed-in user may search it.
Finds tickers by symbol or name — use it before adding an unknown asset.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `q` (query) | string | yes |  |  |
| `limit` (query) | integer | no | 20 |  |

## fx

### `get_fx_rates` — Get Fx Rates

`GET /api/fx/rates` · role: **user** · read-only

Get Fx Rates.
USD rates of one or several currencies, latest or as of a date.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `currencies` (query) | string | yes |  | Comma-separated ISO codes, e.g. EUR,GBP |
| `as_of` (query) | string (date) or null | no |  | Bounded read when given |
| `convention` (query) | enum: close \\| trade | no | close | BE-101: 'trade' = the rate a buy/sell/deposit on that date is recorded with |

## valuation

### `get_valuation_screening` — Get Valuation Screening

`GET /api/valuation/screening` · role: **user** · read-only

Get Valuation Screening.
Score the referential's equities against their sector peers.
The response always carries ``not_scored`` and ``disclaimer``: an asset that
could not be scored is listed with its reason rather than quietly dropped, and
the caveat text is produced here so the frontend never has to restate it.
No ``user_id`` filtering: valuation data is public and the referential is shared.
Sector-relative valuation screening of the referential (live reader).

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `tickers` (query) | string or null | no |  | Comma-separated; defaults to every Equity in the referential |
| `limit` (query) | integer or null | no |  |  |
| `min_sector_size` (query) | integer | no | 5 |  |

## fundamentals

### `get_fundamentals_history` — The latest fundamental states of a ticker, newest first (BE-157)

`GET /api/fundamentals/{ticker}/history` · role: **user** · read-only

The latest fundamental states of a ticker, newest first (BE-157).
Each state with its valuation at the report-day close (``valuation_current`` is
null). Fundamentals are public data: no ``user_id`` filtering. An unknown ticker, or one
without any state, returns an empty list.
Dated history of the fundamental indicators of one ticker (newest first, limit 1–120).

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `ticker` (path) | string | yes |  |  |
| `limit` (query) | integer | no | 8 | Number of states |
| `eps_quarters` (query) | boolean | no | True | Read each state's eight quarterly EPS (off: the field is null) |

## analyst-consensus

### `get_analyst_consensus` — Rebuilt analyst consensus per ticker — mean and median side by side (BE-145)

`GET /api/analyst-consensus` · role: **user** · read-only

Rebuilt analyst consensus per ticker — mean and median side by side (BE-145).
The consensus rebuilt from each firm's last target (BE-113). Without `as_of`: the latest strict point, what a live analysis reads. With `as_of`: the last extended point at or before that date, what a backtest reads on that day. A ticker with no point is absent from `items`.
Analyst consensus (target, rating) of tickers as of a day.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `tickers` (query) | string | yes |  | Comma-separated tickers, e.g. AAPL,MSFT (max 50) |
| `as_of` (query) | string (date) or null | no |  | Historical read when given |

## parameters

### `get_parameter_defaults` — Default analysis parameters

`GET /api/parameters/defaults` · role: **user** · read-only

Default analysis parameters.
Returns metadata (labels, bounds, widgets) for the parameters exposed to the UI, including defaults.
The default optimisation parameters with their bounds and options — the base to build create_analysis's parameters. applies_to says when a parameter can act: estimators (the return_estimation modes, null = all), methods (at least one chosen method listed, null = all), requires (a condition on another parameter), any_of (alternatives); null = always. Do not set a parameter that cannot act with the user's choices.

No arguments.

### `list_parameter_profiles` — Investment profiles

`GET /api/parameters/profiles` · role: **user** · read-only

Investment profiles.
The three questions of an investment profile (horizon, risk, spread) with their answers, and the named cards that answer them in one click.
The three questions of an investment profile — horizon (short | medium | long), risk (low | medium | high), spread (diversified | balanced | concentrated) — and six named cards that answer them. Use it to help a user who does not know which parameters to set.

No arguments.

### `compose_parameter_profile` — Compose an investment profile

`GET /api/parameters/profiles/compose` · role: **user** · read-only

Compose an investment profile.
The full analysis parameters of three answers, without any setting that has no effect: a main and a comparison method, a suggested rebalancing frequency, a label and a plain-English summary.
The parameters of three answers: pass them as create_analysis's parameters, with profile = {horizon, risk, spread, shortcut, primary_method, customised: false} and the user's quantity_mode. Also gives the main method to read first, the comparison method, the rebalancing frequency to suggest for a backtest and a summary to show the user.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `horizon` (query) | enum: short \\| medium \\| long | yes |  |  |
| `risk` (query) | enum: low \\| medium \\| high | yes |  |  |
| `spread` (query) | enum: diversified \\| balanced \\| concentrated | yes |  |  |

## auth

### `get_current_user` — Me

`GET /api/auth/me` · role: **user** · read-only

Me.
Start here: the user behind the key, with the email and the admin flags.

No arguments.

## admin

### `list_admin_users` — The admins and super admins (BE-163)

`GET /api/admin/users` · role: **super admin** · read-only

The admins and super admins (BE-163).

No arguments.

### `add_admin_user` — Promote an account, or create it without a password (BE-163)

`POST /api/admin/users` · role: **super admin**

Promote an account, or create it without a password (BE-163).
Never demotes: an account that already has this role or a higher one is returned
unchanged. No email is sent; the person sets a password through "forgot password".

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `email` (body) | string (email) | yes |  |  |
| `role` (body) | enum: admin \\| super_admin | yes |  |  |

### `set_admin_user_role` — Set the role of an account (BE-163)

`PATCH /api/admin/users/{user_id}` · role: **super admin**

Set the role of an account (BE-163).

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `user_id` (path) | integer | yes |  |  |
| `role` (body) | enum: user \\| admin \\| super_admin | yes |  |  |

### `list_accounts` — Every account, with its number of portfolios and watchlists (BE-213)

`GET /api/admin/accounts` · role: **super admin** · read-only

Every account, with its number of portfolios and watchlists (BE-213).

No arguments.

### `list_account_portfolios` — An account's portfolios and watchlists (BE-213)

`GET /api/admin/accounts/{user_id}/portfolios` · role: **super admin** · read-only

An account's portfolios and watchlists (BE-213).

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `user_id` (path) | integer | yes |  |  |

### `copy_portfolios` — Copy portfolios and watchlists into another account (BE-213)

`POST /api/admin/portfolios/copy` · role: **super admin**

Copy portfolios and watchlists into another account (BE-213).

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `target_user_id` (body) | integer | yes |  |  |
| `portfolio_ids` (body) | array of integer | yes |  |  |
| `portfolio_status` (body) | enum: validated \\| simulated \\| draft | no | simulated |  |
| `include_journal` (body) | boolean | no | False |  |
| `include_strategies` (body) | boolean | no | False |  |

## data-links

### `list_data_quality_alerts` — List Alerts

`GET /api/data-links/alerts` · role: **admin** · read-only

List Alerts.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `status` (query) | enum: open \\| resolved \\| dismissed or null | no |  |  |
| `code` (query) | string or null | no |  |  |
| `ticker` (query) | string or null | no |  |  |
| `limit` (query) | integer | no | 50 |  |
| `offset` (query) | integer | no | 0 |  |

### `detect_data_quality_alerts` — Detect Alerts

`POST /api/data-links/alerts/detect` · role: **admin**

Detect Alerts.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `body` (body) | object {ticker} or null | no |  | The JSON request body |

### `resolve_data_quality_alert` — Resolve Alert

`POST /api/data-links/alerts/{alert_id}/resolve` · role: **admin**

Resolve Alert.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `alert_id` (path) | integer | yes |  |  |
| `body` (body) | object {note} or null | no |  | The JSON request body |

### `dismiss_data_quality_alert` — Dismiss Alert

`POST /api/data-links/alerts/{alert_id}/dismiss` · role: **admin**

Dismiss Alert.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `alert_id` (path) | integer | yes |  |  |
| `note` (body) | string | yes |  |  |

### `get_data_links_summary` — Summary

`GET /api/data-links/summary` · role: **admin** · read-only

Summary.

No arguments.

### `list_share_class_listings` — List Listings

`GET /api/data-links/share-class-listings` · role: **admin** · read-only

List Listings.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `cik` (query) | string or null | no |  |  |
| `ticker` (query) | string or null | no |  |  |

### `create_share_class_listing` — Create Listing

`POST /api/data-links/share-class-listings` · role: **admin**

Create Listing.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `cik` (body) | string | yes |  |  |
| `ticker` (body) | string | yes |  |  |
| `share_class_member` (body) | string | yes |  |  |
| `is_confirmed` (body) | boolean or null | no |  |  |
| `note` (body) | string or null | no |  |  |

### `update_share_class_listing` — Update Listing

`PATCH /api/data-links/share-class-listings/{listing_id}` · role: **admin**

Update Listing.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `listing_id` (path) | integer | yes |  |  |
| `cik` (body) | string or null | no |  |  |
| `ticker` (body) | string or null | no |  |  |
| `share_class_member` (body) | string or null | no |  |  |
| `is_confirmed` (body) | boolean or null | no |  |  |
| `note` (body) | string or null | no |  |  |

### `list_share_class_conversions` — List Conversions

`GET /api/data-links/share-class-conversions` · role: **admin** · read-only

List Conversions.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `cik` (query) | string or null | no |  |  |

### `create_share_class_conversion` — Create Conversion

`POST /api/data-links/share-class-conversions` · role: **admin**

Create Conversion.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `cik` (body) | string | yes |  |  |
| `share_class_member` (body) | string | yes |  |  |
| `conversion_rate` (body) | number | yes |  |  |
| `valid_from_date` (body) | string (date) or null | no |  |  |
| `valid_until_date` (body) | string (date) or null | no |  |  |
| `document_url` (body) | string | yes |  |  |
| `document_date` (body) | string (date) | yes |  |  |

### `preview_share_class_conversion` — Preview Conversion

`GET /api/data-links/share-class-conversions/preview` · role: **admin** · read-only

Preview Conversion.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `cik` (query) | string | yes |  |  |
| `share_class_member` (query) | string | yes |  |  |
| `conversion_rate` (query) | number | yes |  |  |

### `update_share_class_conversion` — Update Conversion

`PATCH /api/data-links/share-class-conversions/{conversion_id}` · role: **admin**

Update Conversion.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `conversion_id` (path) | integer | yes |  |  |
| `cik` (body) | string or null | no |  |  |
| `share_class_member` (body) | string or null | no |  |  |
| `conversion_rate` (body) | number or null | no |  |  |
| `valid_from_date` (body) | string (date) or null | no |  |  |
| `valid_until_date` (body) | string (date) or null | no |  |  |
| `document_url` (body) | string | yes |  |  |
| `document_date` (body) | string (date) | yes |  |  |

### `list_debt_line_exceptions` — List Exceptions

`GET /api/data-links/debt-exceptions` · role: **admin** · read-only

List Exceptions.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `ticker` (query) | string or null | no |  |  |
| `status` (query) | enum: active \\| disabled or null | no |  |  |

### `create_debt_line_exception` — Create Exception

`POST /api/data-links/debt-exceptions` · role: **admin**

Create Exception.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `ticker` (body) | string | yes |  |  |
| `cik` (body) | string or null | no |  |  |
| `rule_code` (body) | string | yes |  |  |
| `valid_from_date` (body) | string (date) or null | no |  |  |
| `valid_until_date` (body) | string (date) or null | no |  |  |
| `document_url` (body) | string | yes |  |  |
| `note` (body) | string or null | no |  |  |
| `exception_status` (body) | enum: active \\| disabled | no | active |  |

### `preview_debt_line_exception` — Preview Exception

`GET /api/data-links/debt-exceptions/preview` · role: **admin** · read-only

Preview Exception.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `ticker` (query) | string | yes |  |  |
| `rule_code` (query) | string | yes |  |  |

### `update_debt_line_exception` — Update Exception

`PATCH /api/data-links/debt-exceptions/{exception_id}` · role: **admin**

Update Exception.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `exception_id` (path) | integer | yes |  |  |
| `ticker` (body) | string or null | no |  |  |
| `cik` (body) | string or null | no |  |  |
| `rule_code` (body) | string or null | no |  |  |
| `valid_from_date` (body) | string (date) or null | no |  |  |
| `valid_until_date` (body) | string (date) or null | no |  |  |
| `document_url` (body) | string or null | no |  |  |
| `note` (body) | string or null | no |  |  |
| `exception_status` (body) | enum: active \\| disabled or null | no |  |  |

### `create_reprocess_job` — Create Reprocess Job

`POST /api/data-links/reprocess/{ticker}` · role: **admin**

Create Reprocess Job.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `ticker` (path) | string | yes |  |  |

### `list_reprocess_jobs` — List Reprocess Jobs

`GET /api/data-links/reprocess` · role: **admin** · read-only

List Reprocess Jobs.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `ticker` (query) | string or null | no |  |  |

### `get_reprocess_job` — Get Reprocess Job

`GET /api/data-links/reprocess/{job_id}` · role: **admin** · read-only

Get Reprocess Job.

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `job_id` (path) | integer | yes |  |  |

## meta

### `get_health` — Health

`GET /health` · role: **public** · read-only

Health.
Liveness of the API and of its database.

No arguments.

### `get_api_version` — Version

`GET /api/version` · role: **public** · read-only

Version.
Version of the API.

No arguments.

## indicators

### `get_indicator_catalog` — Catalogue of the technical indicators: two families, sub-groups, labels, readings (BE-221)

`GET /api/indicators/catalog` · role: **public** · read-only

Catalogue of the technical indicators: two families, sub-groups, labels, readings (BE-221).
Trend & momentum (1 to 12 months, ``/assets/{ticker}/momentum``) and Short-term
signals (2 to 20 trading days, ``/assets/{ticker}/short-term``): each indicator's code,
family, sub-group, label, formula, reading, unit and reference lines. Public: the same
for every user.
Labels, formulas, readings and sub-groups of every technical indicator, both families (Trend & momentum, Short-term signals): read it to name and interpret the codes of get_asset_momentum and get_asset_short_term.

No arguments.

### `recompute_short_term_indicators` — Recompute the short-term indicators of one ticker or of the whole referential (BE-221, admin)

`POST /api/indicators/short-term/recompute` · role: **admin**

Recompute the short-term indicators of one ticker or of the whole referential (BE-221, admin).
One ticker is recomputed in the request; the whole referential in the background
(one commit per ticker, a few minutes).
Admin: recompute the short-term indicators of one ticker (in the request) or of the whole referential (in the background).

| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
| `ticker` (body) | string or null | no |  |  |