DIONYSUS · Create

DIONYSUS base URL: https://dionysus-api.trinitytrade.io

A public GET to / returns JSON with name, version, and status.

This page documents GET /health and POST /api/v1/portfolios/optimize on the DIONYSUS host (public demo body without credentials, or authenticated requests with a bearer token). Request and response objects match the DIONYSUS PortfolioRequest and PortfolioResponse models — see PortfolioRequest and PortfolioResponse below for full field tables.

Production access. Authenticated routes require valid credentials per environment. For tokens, quotas, and SLAs, contact [email protected].

Endpoints

GET

Health

/health

Returns a small JSON status payload so you can confirm the API is reachable.

Auth: None — /health is public on the DIONYSUS production host.

Responses

Status Description
200 JSON with status
503 Unavailable

Example

export DIONYSUS_API="${DIONYSUS_API:-https://dionysus-api.trinitytrade.io}"
curl -sS "$DIONYSUS_API/health"
POST

Create on DIONYSUS

/api/v1/portfolios/optimize

Primary optimizer HTTP contract on the DIONYSUS service. Without credentials, the API accepts only the fixed demo JSON below (demo mode; result is not persisted; response includes at most two allocation rows, with capital totals matching those rows). With a valid Bearer token, send a full PortfolioRequest as documented for your deployment.

Auth: Optional for the fixed demo body in the example (no Authorization header). Add Bearer for authenticated optimization and persistence, per your DIONYSUS environment.

Responses

Status Description
200 PortfolioResponse
400 Invalid body, constraints, or demo-mode body mismatch
401 Unauthorized (authenticated routes)
503 Service unavailable

Example

export DIONYSUS_API="${DIONYSUS_API:-https://dionysus-api.trinitytrade.io}"
curl -sS -X POST "$DIONYSUS_API/api/v1/portfolios/optimize" \
  -H "Content-Type: application/json" \
  -d '{  "name": "Example allocation",  "total_capital": 100000,  "risk_settings": {    "max_risk_per_trade": 0.2,    "max_portfolio_risk": 0.2,    "max_position_size": 0.2,    "max_positions": 10,    "allocation_strategy": "KELLY_CRITERION"  }}'
Sample JSON response 
{
  "portfolio_id": "6f6c317f-4836-4975-b359-9854d05150c9",
  "name": "Example allocation",
  "description": null,
  "total_capital": 100000.0,
  "allocated_capital": 2206.42,
  "remaining_capital": 97793.58,
  "position_count": 2,
  "allocations": [
    {
      "symbol": "TER",
      "shares": 7,
      "position_type": "LONG",
      "entry_price": 358.29,
      "position_value": 1003.21,
      "risk_amount": 116.98,
      "percent_of_account": 0.010032,
      "stop_loss": 316.51,
      "target_price": 441.85,
      "risk_reward_ratio": 2.0,
      "confidence": 1.0,
      "stage": "STAGE 2",
      "entry_date": "2026-04-09T12:30:25.999176",
      "signal": "BUY",
      "stage_strength": "VERY_STRONG",
      "signal_confidence": null,
      "signal_reason": null,
      "bb_width": null,
      "atr": null,
      "atr_percent": null,
      "volatility_trend": null,
      "is_high_volatility": null,
      "volatility_stop_loss_levels": null,
      "historical_volatility": 4.72,
      "support_levels": [{ "price": 263.02, "strength": null }],
      "resistance_levels": [{ "price": 344.92, "strength": null }]
    },
    {
      "symbol": "XYZ",
      "shares": 12,
      "position_type": "LONG",
      "entry_price": 250.75,
      "position_value": 1203.21,
      "risk_amount": 96.0,
      "percent_of_account": 0.012032,
      "stop_loss": 230.0,
      "target_price": 290.0,
      "risk_reward_ratio": 2.0,
      "confidence": 0.92,
      "stage": "STAGE 2",
      "entry_date": "2026-04-09T12:30:26.001000",
      "signal": "BUY",
      "stage_strength": "STRONG",
      "signal_confidence": null,
      "signal_reason": null,
      "bb_width": null,
      "atr": null,
      "atr_percent": null,
      "volatility_trend": null,
      "is_high_volatility": null,
      "volatility_stop_loss_levels": null,
      "historical_volatility": null,
      "support_levels": null,
      "resistance_levels": null
    }
  ],
  "created_at": "2026-04-09T12:30:26.056787",
  "currency": "USD",
  "risk_settings": {
    "max_risk_per_trade": 0.2,
    "max_portfolio_risk": 0.2,
    "max_position_size": 0.2,
    "max_positions": 10,
    "allocation_strategy": "KELLY_CRITERION",
    "softmax_temperature": 1.0,
    "reward_multiplier": 2.0,
    "stage_weights": null,
    "half_kelly": true
  },
  "trace_id": "bbe9cbb2-595b-4ef5-af1e-bc31b3409da6",
  "optimizer_diagnostics": {
    "schema_version": "1",
    "max_position_size_effective": 0.2,
    "max_position_size_from_risk_settings": 0.2,
    "constraint_pack_default_sector_cap": null,
    "vol_target_annual": null,
    "max_portfolio_turnover_annual": null,
    "softmax_temperature_base": 1.0,
    "softmax_temperature_effective": 1.0,
    "binding_notes": ["constraint_pack absent for this run: allocation uses risk_settings only (no sector_caps.DEFAULT merge)."]
  }
}

PortfolioRequest

JSON request body for POST /api/v1/portfolios/optimize. The public demo sends a minimal subset (name, total_capital, risk_settings). Authenticated clients may include optional v1 objects (investor profile, constraint pack, prior book weights) per deployment. total_capital must be at least 1000.

Show full field reference (tables)

Top-level fields

Field Type Description
name string Required. Portfolio display name.
description string or null Optional description.
total_capital number Required. Capital available for allocation; minimum 1000 (validated server-side).
currency string Currency code; default USD.
risk_quiz_answers object or null Optional raw risk quiz keys (e.g. goal, horizon, drawdown, volatility, concentration, preference).
suggested_preset object or null Optional preset key and description from the risk wizard.
risk_settings RiskSettings Risk and allocation parameters. Server applies defaults when omitted (see table below).
investor_profile InvestorProfileV1 or null Optional structured questionnaire snapshot (v1); embedded on the portfolio document.
constraint_pack ConstraintPackV1 or null Optional machine-readable constraints (turnover, vol target, sector caps); stored for optimizer rollout.
prior_book_weights object or null Optional map of symbol → fraction of total_capital for rebalance-only blending with turnover caps when constraint_pack supplies annual turnover.
policy_explanation PolicyExplanationV1 or null Optional client hint; optimize overwrites with a server-built audit object when present.

RiskSettings

Nested under risk_settings. allocation_strategy is one of: EQUAL_WEIGHT, STAGE_WEIGHTED, CONFIDENCE_WEIGHTED, KELLY_CRITERION, HYBRID_WEIGHTED.

Field Type Description
max_risk_per_trade number Max risk per trade as fraction 0–1 (default 0.01).
max_portfolio_risk number Max portfolio-wide risk as fraction 0–1 (default 0.05).
max_position_size number Max weight for any single name as fraction 0–1 (default 0.2).
max_positions integer Maximum number of positions (default 30).
allocation_strategy string (enum) How weights are computed (see list above). Demo uses KELLY_CRITERION.
softmax_temperature number or null Temperature for softmax-style strategies; higher → more uniform weights.
reward_multiplier number or null Kelly-related reward scale; used with KELLY_CRITERION.
stage_weights object or null Custom stage weights (e.g. STAGE 2 → factor) for stage/hybrid strategies.
half_kelly boolean or null Use half-Kelly for more conservative sizing when using Kelly strategy.

InvestorProfileV1 (optional)

Field Type Description
schema_version string Profile schema version (e.g. 1).
recorded_at string or null ISO8601 when the profile was captured.
risk_quiz_answers object Quiz key → answer strings from Iris.
suggested_preset object or null Optional preset metadata from the wizard.

ConstraintPackV1 (optional)

Field Type Description
schema_version string Constraint pack version (e.g. 1).
max_portfolio_turnover_annual number or null One-way annual turnover cap (fraction). Diagnostic on first optimize unless prior weights are set.
vol_target_annual number or null Target annualized volatility as fraction (e.g. 0.12).
sector_caps object or null Max weight per sector label; DEFAULT may merge with max position size.
covariance_model string or null Reserved placeholder for covariance / risk-model integration.

PolicyExplanationV1 (optional)

Field Type Description
schema_version string Explanation schema version.
mapper_version string Policy compiler version label.
preset_key string or null Risk preset key when applicable.
bullets string[] Short audit lines aligned with constraint fields.

PortfolioResponse

JSON returned on 200 from /api/v1/portfolios/optimize. Includes capital totals, per-position allocations[] (optimizer output with Athena-style enrichment where available), echoed risk_settings, a trace_id for log correlation, and optional optimizer_diagnostics. In unauthenticated demo mode, allocations contains at most two rows and position_count / capital fields reflect that subset only; authenticated responses include the full book.

Show full field reference (tables)

Top-level fields

Field Type Description
portfolio_id string Unique id for this optimized portfolio result.
name string Portfolio name (echoed from request).
description string or null Optional description.
total_capital number Total capital from the request.
allocated_capital number Sum allocated across positions.
remaining_capital number Unallocated cash (total − allocated).
position_count integer Length of allocations.
allocations PortfolioAllocation[] One object per line; see nested table.
created_at string (datetime) ISO8601 timestamp when the result was built.
currency string Currency code (e.g. USD).
risk_settings RiskSettings Effective risk settings used for this run (same shape as request).
trace_id string Correlation id for support and logs.
optimizer_diagnostics OptimizerDiagnosticsV1 or null How constraints and temperature affected sizing; see nested table.

PortfolioAllocation (each element)

Live responses include many optional Athena analysis fields; keys may be null when data is unavailable. signal may be a string (legacy) or a structured object in some paths.

Field Type Description
symbol string Ticker.
shares integer Whole-share count for the book.
position_type string e.g. LONG / SHORT.
entry_price number Suggested entry reference price.
position_value number Dollar value of the position.
risk_amount number Capital at risk for the position.
percent_of_account number Fraction of account in this name (0–1 scale in API responses).
stop_loss number Stop price level.
target_price number or null Price target when set.
risk_reward_ratio number Risk/reward ratio used in planning.
confidence number or null Signal or sizing confidence.
stage string or null Market stage label (e.g. STAGE 2, Stage 2).
entry_date string (datetime) or null Entry timestamp for the allocation row.
signal string, object, or null Trading signal (often BUY/SELL/HOLD).
stage_strength string or null e.g. VERY_STRONG, MODERATE.
signal_confidence number or null Athena signal confidence when present.
signal_reason string or null Human-readable reason from analysis.
bb_width number or null Bollinger bandwidth.
atr number or null Average True Range.
atr_percent number or null ATR as percent of price.
volatility_trend string or null Vol trend label from analysis.
is_high_volatility boolean or null High-vol flag.
volatility_stop_loss_levels object or null Map of vol-derived stop levels.
historical_volatility number or null Historical vol estimate.
support_levels array or null Array of objects with price and optional strength support levels.
resistance_levels array or null Array of objects with price and optional strength resistance levels.

OptimizerDiagnosticsV1

Field Type Description
schema_version string Diagnostics schema version.
max_position_size_effective number Per-name cap after merging sector DEFAULT and risk settings.
max_position_size_from_risk_settings number Original risk_settings.max_position_size.
constraint_pack_default_sector_cap number or null sector_caps.DEFAULT when a constraint pack was supplied.
vol_target_annual number or null Echoed vol target from constraint pack.
max_portfolio_turnover_annual number or null Echoed turnover cap from constraint pack.
softmax_temperature_base number or null Temperature before vol/constraint merge heuristics.
softmax_temperature_effective number or null Temperature after merge.
binding_notes string[] Short lines describing binding constraints and deferred fields.

DIONYSUS production base: https://dionysus-api.trinitytrade.io (override with PUBLIC_DIONYSUS_API_BASE for local docs).