{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Alvo Decision Support API","version":"1.0.0","summary":"Decision-support API for Ukraine DAM analytics, BESS planning, risk control, AI briefs, and audit events.","description":"Alvo exposes server-validated endpoints for day-ahead market analysis and controlled trader workflows. V1 prepares plans, explanations, risk reports, and audit events; it does not submit market orders automatically."},"servers":[{"url":"https://dev.alvo.energy","description":"Configured Alvo deployment"}],"tags":[{"name":"Market data","description":"OREE public price ingestion and normalization."},{"name":"Strategy","description":"DAM spread plans and trader-controlled decision support."},{"name":"BESS","description":"Battery storage arbitrage planning over hourly prices."},{"name":"Risk","description":"Guardrails, blockers, and human approval status."},{"name":"AI","description":"Deterministic AI brief generation for trader workflows."},{"name":"Audit","description":"Action events for audit-ready workflows."},{"name":"Billing","description":"Subscription catalog, usage boundaries, and checkout readiness."},{"name":"Notifications","description":"PWA notification subscription contracts and signal channels."},{"name":"Operations","description":"Health and operational readiness signals."}],"security":[{"AlvoApiKey":[]},{"BearerAuth":[]}],"paths":{"/api/health":{"get":{"tags":["Operations"],"summary":"Read platform operational readiness","description":"Returns non-secret health, security mode, rate limit, engine, market data, AI brief, and audit readiness checks for monitoring.","operationId":"getOperationalReadiness","security":[],"responses":{"200":{"description":"Platform is operational","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationalReadiness"}}}},"503":{"description":"Platform is degraded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationalReadiness"}}}}}}},"/api/billing/plans":{"get":{"tags":["Billing"],"summary":"Read the Alvo subscription catalog","description":"Returns public subscription packages, usage limits, add-ons, and billing policy. Checkout remains planned; production billing should bind this catalog to the selected payment provider.","operationId":"getSubscriptionCatalog","security":[],"parameters":[{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["uk","en"],"default":"uk"}}],"responses":{"200":{"description":"Subscription catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionCatalog"}}}}}}},"/api/oree/prices":{"get":{"tags":["Market data"],"summary":"Fetch monthly OREE prices","description":"Reads public Market Operator data for DAM or IDM and returns a date-keyed book of normalized hourly prices.","operationId":"getOreePrices","parameters":[{"name":"month","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{2}\\.\\d{4}$","example":"05.2026"}},{"name":"market","in":"query","required":false,"schema":{"type":"string","enum":["DAM","IDM"],"default":"DAM"}}],"responses":{"200":{"description":"OREE price book","content":{"application/json":{"schema":{"type":"object","required":["source","month","market","data"],"properties":{"source":{"type":"string","example":"oree.com.ua"},"month":{"type":"string","example":"05.2026"},"market":{"type":"string","enum":["DAM","IDM"],"example":"DAM"},"data":{"$ref":"#/components/schemas/PriceBook"}},"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamError"}}}},"/api/oree/indexes":{"get":{"tags":["Market data"],"summary":"Fetch monthly OREE DAM indexes","description":"Reads public Market Operator DAM index data and returns base, peak, off-peak, min, max, and weighted-average prices by date.","operationId":"getOreeIndexes","parameters":[{"name":"month","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{2}\\.\\d{4}$","example":"05.2026"}},{"name":"zone","in":"query","required":false,"schema":{"type":"string","enum":["IPS","BEI"],"default":"IPS"}}],"responses":{"200":{"description":"OREE DAM index book","content":{"application/json":{"schema":{"type":"object","required":["source","month","market","zone","data"],"properties":{"source":{"type":"string","example":"oree.com.ua"},"month":{"type":"string","example":"05.2026"},"market":{"type":"string","enum":["DAM"],"example":"DAM"},"zone":{"type":"string","enum":["IPS","BEI"],"example":"IPS"},"data":{"$ref":"#/components/schemas/OreeIndexBook"}},"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamError"}}}},"/api/oree/trading-results":{"get":{"tags":["Market data"],"summary":"Fetch OREE daily trading results","description":"Reads public Market Operator daily trading result summaries and hourly matched volumes for DAM or IDM.","operationId":"getOreeTradingResults","parameters":[{"name":"tradeDate","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{2}\\.\\d{2}\\.\\d{4}$","example":"13.05.2026"}},{"name":"market","in":"query","required":false,"schema":{"type":"string","enum":["DAM","IDM"],"default":"DAM"}}],"responses":{"200":{"description":"OREE trading results","content":{"application/json":{"schema":{"type":"object","required":["source","tradeDate","market","data"],"properties":{"source":{"type":"string","example":"oree.com.ua"},"tradeDate":{"type":"string","example":"13.05.2026"},"market":{"type":"string","enum":["DAM","IDM"],"example":"DAM"},"data":{"$ref":"#/components/schemas/OreeTradingResultsDay"}},"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamError"}}}},"/api/ueex/electricity-indexes":{"get":{"tags":["Market data"],"summary":"Fetch UEEX electricity indexes","description":"Reads public Ukrainian Energy Exchange electricity indexes for bilateral contracts market BASE load in IPS Ukraine.","operationId":"getUeexElectricityIndexes","parameters":[{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["uk","en"],"default":"uk"}}],"responses":{"200":{"description":"UEEX electricity indexes","content":{"application/json":{"schema":{"type":"object","required":["source","market","zone","lang","data"],"properties":{"source":{"type":"string","example":"ueex.com.ua"},"market":{"type":"string","enum":["BCM"],"example":"BCM"},"zone":{"type":"string","enum":["IPS"],"example":"IPS"},"lang":{"type":"string","enum":["uk","en"],"example":"uk"},"data":{"type":"array","items":{"$ref":"#/components/schemas/UeexElectricityIndex"},"example":[{"period":"April 2026","periodType":"monthly","deliveryKey":"2026-04","valueUahMwh":6006.7},{"period":"May 2026 (DEC 3*)","periodType":"decadal","deliveryKey":"2026-05-D3","valueUahMwh":5309.2}]}},"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamError"}}}},"/api/forecast":{"get":{"tags":["Market data"],"summary":"Fetch the probabilistic price forecast","description":"Returns the served price forecast for the month: a date-keyed book of hourly p10/p50/p90 bands, the chosen model, and its walk-forward skill (rMAE vs the seasonal-naive benchmark). `forecast` is null when the platform has no usable forecast.","operationId":"getMarketForecast","parameters":[{"name":"month","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{2}\\.\\d{4}$","example":"05.2026"}},{"name":"market","in":"query","required":false,"schema":{"type":"string","enum":["DAM","IDM"],"default":"DAM"}}],"responses":{"200":{"description":"Market forecast","content":{"application/json":{"schema":{"type":"object","required":["month","market","forecast"],"properties":{"month":{"type":"string","example":"05.2026"},"market":{"type":"string","enum":["DAM","IDM"],"example":"DAM"},"forecast":{"oneOf":[{"$ref":"#/components/schemas/Forecast"},{"type":"null"}]}},"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/strategy/plan":{"post":{"tags":["Strategy"],"summary":"Build a DAM spread plan","operationId":"createStrategyPlan","requestBody":{"required":true,"description":"Strategy plan input","content":{"application/json":{"schema":{"type":"object","required":["tradeDate","prices","settings"],"properties":{"tradeDate":{"type":"string","example":"13.05.2026"},"prices":{"$ref":"#/components/schemas/PriceDay"},"settings":{"$ref":"#/components/schemas/TradingSettings"}},"additionalProperties":false},"example":{"tradeDate":"13.05.2026","prices":[{"hour":0,"priceUahMwh":5575},{"hour":1,"priceUahMwh":5100},{"hour":2,"priceUahMwh":100},{"hour":3,"priceUahMwh":70},{"hour":4,"priceUahMwh":100},{"hour":5,"priceUahMwh":4800},{"hour":6,"priceUahMwh":5880},{"hour":7,"priceUahMwh":5267},{"hour":8,"priceUahMwh":3878},{"hour":9,"priceUahMwh":3050},{"hour":10,"priceUahMwh":49},{"hour":11,"priceUahMwh":10},{"hour":12,"priceUahMwh":11},{"hour":13,"priceUahMwh":11},{"hour":14,"priceUahMwh":10},{"hour":15,"priceUahMwh":12},{"hour":16,"priceUahMwh":110},{"hour":17,"priceUahMwh":1900},{"hour":18,"priceUahMwh":6200},{"hour":19,"priceUahMwh":7400},{"hour":20,"priceUahMwh":6900},{"hour":21,"priceUahMwh":6100},{"hour":22,"priceUahMwh":5400},{"hour":23,"priceUahMwh":4800}],"settings":{"volumeMwh":5,"minSpreadUah":250,"maxTradesPerDay":4,"feeUahPerMwh":12}}}}},"responses":{"200":{"description":"Generated strategy plan","content":{"application/json":{"schema":{"type":"object","required":["tradeDate","generatedAt","plan"],"properties":{"tradeDate":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"plan":{"$ref":"#/components/schemas/TradingPlan"}},"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/strategy/profiles":{"get":{"tags":["Strategy"],"summary":"List saved strategy profiles","description":"Returns the signed-in tenant/user's saved strategy settings, including the hidden active profile used for cross-device workspace sync.","operationId":"listStrategyProfiles","responses":{"200":{"description":"Saved strategy profiles","content":{"application/json":{"schema":{"type":"object","required":["profiles"],"properties":{"profiles":{"type":"array","items":{"$ref":"#/components/schemas/StrategyProfile"},"example":[{"id":"f1c1d77a-7d71-46ef-b64d-3a3cbce8b22b","tenantId":"org_acme","actorId":"trader@example.com","profileKey":"balanced","name":"Balanced","settings":{"volumeMwh":5,"minSpreadUah":250,"maxTradesPerDay":4,"feeUahPerMwh":12},"fingerprint":"v5-s250-t4-f12","createdAt":"2026-05-25T08:00:00.000Z","updatedAt":"2026-05-25T08:00:00.000Z"}]}},"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Strategy"],"summary":"Save or update a strategy profile","operationId":"upsertStrategyProfile","requestBody":{"required":true,"description":"Strategy profile input","content":{"application/json":{"schema":{"type":"object","required":["name","settings"],"properties":{"profileKey":{"type":"string","maxLength":120,"example":"balanced"},"name":{"type":"string","minLength":1,"maxLength":80,"example":"Balanced"},"settings":{"$ref":"#/components/schemas/TradingSettings"}},"additionalProperties":false},"example":{"profileKey":"balanced","name":"Balanced","settings":{"volumeMwh":5,"minSpreadUah":250,"maxTradesPerDay":4,"feeUahPerMwh":12}}}}},"responses":{"200":{"description":"Saved strategy profile","content":{"application/json":{"schema":{"type":"object","required":["profile"],"properties":{"profile":{"$ref":"#/components/schemas/StrategyProfile"}},"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"tags":["Strategy"],"summary":"Delete a saved strategy profile","operationId":"deleteStrategyProfile","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted strategy profile","content":{"application/json":{"schema":{"type":"object","required":["deleted"],"properties":{"deleted":{"type":"boolean"}},"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/bess/plan":{"post":{"tags":["BESS"],"summary":"Build a BESS arbitrage plan","operationId":"createBessPlan","requestBody":{"required":true,"description":"BESS plan input","content":{"application/json":{"schema":{"type":"object","required":["tradeDate","prices","settings"],"properties":{"tradeDate":{"type":"string","example":"13.05.2026"},"prices":{"$ref":"#/components/schemas/PriceDay"},"settings":{"$ref":"#/components/schemas/BessSettings"}},"additionalProperties":false},"example":{"tradeDate":"13.05.2026","prices":[{"hour":0,"priceUahMwh":5575},{"hour":1,"priceUahMwh":5100},{"hour":2,"priceUahMwh":100},{"hour":3,"priceUahMwh":70},{"hour":4,"priceUahMwh":100},{"hour":5,"priceUahMwh":4800},{"hour":6,"priceUahMwh":5880},{"hour":7,"priceUahMwh":5267},{"hour":8,"priceUahMwh":3878},{"hour":9,"priceUahMwh":3050},{"hour":10,"priceUahMwh":49},{"hour":11,"priceUahMwh":10},{"hour":12,"priceUahMwh":11},{"hour":13,"priceUahMwh":11},{"hour":14,"priceUahMwh":10},{"hour":15,"priceUahMwh":12},{"hour":16,"priceUahMwh":110},{"hour":17,"priceUahMwh":1900},{"hour":18,"priceUahMwh":6200},{"hour":19,"priceUahMwh":7400},{"hour":20,"priceUahMwh":6900},{"hour":21,"priceUahMwh":6100},{"hour":22,"priceUahMwh":5400},{"hour":23,"priceUahMwh":4800}],"settings":{"capacityMwh":10,"powerMw":5,"roundTripEfficiency":0.9,"maxCyclesPerDay":2,"degradationCostUahMwh":80}}}}},"responses":{"200":{"description":"Generated BESS plan","content":{"application/json":{"schema":{"type":"object","required":["tradeDate","generatedAt","plan"],"properties":{"tradeDate":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"plan":{"$ref":"#/components/schemas/BessPlan"}},"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/backtest/summary":{"post":{"tags":["Strategy","BESS"],"summary":"Run a multi-day strategy and BESS backtest","operationId":"createBacktestSummary","requestBody":{"required":true,"description":"Backtest input","content":{"application/json":{"schema":{"type":"object","required":["priceBook","strategySettings","bessSettings"],"properties":{"priceBook":{"$ref":"#/components/schemas/PriceBook"},"strategySettings":{"$ref":"#/components/schemas/TradingSettings"},"bessSettings":{"$ref":"#/components/schemas/BessSettings"}},"additionalProperties":false},"example":{"priceBook":{"13.05.2026":[{"hour":0,"priceUahMwh":5575},{"hour":1,"priceUahMwh":5100},{"hour":2,"priceUahMwh":100},{"hour":3,"priceUahMwh":70},{"hour":4,"priceUahMwh":100},{"hour":5,"priceUahMwh":4800},{"hour":6,"priceUahMwh":5880},{"hour":7,"priceUahMwh":5267},{"hour":8,"priceUahMwh":3878},{"hour":9,"priceUahMwh":3050},{"hour":10,"priceUahMwh":49},{"hour":11,"priceUahMwh":10},{"hour":12,"priceUahMwh":11},{"hour":13,"priceUahMwh":11},{"hour":14,"priceUahMwh":10},{"hour":15,"priceUahMwh":12},{"hour":16,"priceUahMwh":110},{"hour":17,"priceUahMwh":1900},{"hour":18,"priceUahMwh":6200},{"hour":19,"priceUahMwh":7400},{"hour":20,"priceUahMwh":6900},{"hour":21,"priceUahMwh":6100},{"hour":22,"priceUahMwh":5400},{"hour":23,"priceUahMwh":4800}]},"strategySettings":{"volumeMwh":5,"minSpreadUah":250,"maxTradesPerDay":4,"feeUahPerMwh":12},"bessSettings":{"capacityMwh":10,"powerMw":5,"roundTripEfficiency":0.9,"maxCyclesPerDay":2,"degradationCostUahMwh":80}}}}},"responses":{"200":{"description":"Backtest summary","content":{"application/json":{"schema":{"type":"object","required":["generatedAt","summary"],"properties":{"generatedAt":{"type":"string","format":"date-time"},"summary":{"$ref":"#/components/schemas/BacktestSummary"}},"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/risk/report":{"post":{"tags":["Risk"],"summary":"Create a risk guardrail report","description":"Runs strategy and BESS engines, then returns data quality, exposure, anomaly, BESS cycle, and human approval checks.","operationId":"createRiskReport","requestBody":{"required":true,"description":"Risk report input","content":{"application/json":{"schema":{"type":"object","required":["tradeDate","prices","strategySettings","bessSettings"],"properties":{"tradeDate":{"type":"string","example":"13.05.2026"},"prices":{"$ref":"#/components/schemas/PriceDay"},"strategySettings":{"$ref":"#/components/schemas/TradingSettings"},"bessSettings":{"$ref":"#/components/schemas/BessSettings"},"sourceLabel":{"type":"string","default":"unknown","example":"oree.com.ua"},"isFallbackData":{"type":"boolean","default":false}},"additionalProperties":false},"example":{"tradeDate":"13.05.2026","prices":[{"hour":0,"priceUahMwh":5575},{"hour":1,"priceUahMwh":5100},{"hour":2,"priceUahMwh":100},{"hour":3,"priceUahMwh":70},{"hour":4,"priceUahMwh":100},{"hour":5,"priceUahMwh":4800},{"hour":6,"priceUahMwh":5880},{"hour":7,"priceUahMwh":5267},{"hour":8,"priceUahMwh":3878},{"hour":9,"priceUahMwh":3050},{"hour":10,"priceUahMwh":49},{"hour":11,"priceUahMwh":10},{"hour":12,"priceUahMwh":11},{"hour":13,"priceUahMwh":11},{"hour":14,"priceUahMwh":10},{"hour":15,"priceUahMwh":12},{"hour":16,"priceUahMwh":110},{"hour":17,"priceUahMwh":1900},{"hour":18,"priceUahMwh":6200},{"hour":19,"priceUahMwh":7400},{"hour":20,"priceUahMwh":6900},{"hour":21,"priceUahMwh":6100},{"hour":22,"priceUahMwh":5400},{"hour":23,"priceUahMwh":4800}],"strategySettings":{"volumeMwh":5,"minSpreadUah":250,"maxTradesPerDay":4,"feeUahPerMwh":12},"bessSettings":{"capacityMwh":10,"powerMw":5,"roundTripEfficiency":0.9,"maxCyclesPerDay":2,"degradationCostUahMwh":80},"sourceLabel":"oree.com.ua","isFallbackData":false}}}},"responses":{"200":{"description":"Risk guardrail report","content":{"application/json":{"schema":{"type":"object","required":["tradeDate","generatedAt","report"],"properties":{"tradeDate":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"report":{"$ref":"#/components/schemas/RiskGuardrailReport"}},"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/ai/trading-brief":{"post":{"tags":["AI"],"summary":"Generate a deterministic trading brief","operationId":"createTradingBrief","requestBody":{"required":true,"description":"Trading brief input","content":{"application/json":{"schema":{"type":"object","required":["tradeDate","prices","settings"],"properties":{"tradeDate":{"type":"string","example":"13.05.2026"},"prices":{"$ref":"#/components/schemas/PriceDay"},"settings":{"$ref":"#/components/schemas/TradingSettings"},"locale":{"type":"string","enum":["uk","en"],"default":"uk"},"context":{"type":"object","description":"Optional pre-summarized market context forwarded by the workspace; the brief remains deterministic and validates every field.","properties":{"market":{"type":"string","enum":["DAM","IDM"]},"regulatory":{"type":"object","properties":{"priceCap":{"type":"object","nullable":true,"properties":{"source":{"type":"string","enum":["NEURC"]},"decision":{"type":"string","example":"Resolution No. 621"},"validFrom":{"type":"string","example":"2026-05-01"},"sourceUrl":{"type":"string","format":"uri"},"market":{"type":"string","enum":["DAM","IDM","BM"]},"minUahMwh":{"type":"number"},"maxUahMwh":{"type":"number"},"unit":{"type":"string","enum":["UAH/MWh"]},"minObservedUahMwh":{"type":"number"},"maxObservedUahMwh":{"type":"number"},"distanceToMinUahMwh":{"type":"number"},"distanceToMaxUahMwh":{"type":"number"},"minCapHitHours":{"type":"array","items":{"type":"integer","minimum":0,"maximum":23}},"maxCapHitHours":{"type":"array","items":{"type":"integer","minimum":0,"maximum":23}},"capHitToleranceUahMwh":{"type":"number"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":true}},"additionalProperties":false},"example":{"tradeDate":"13.05.2026","prices":[{"hour":0,"priceUahMwh":5575},{"hour":1,"priceUahMwh":5100},{"hour":2,"priceUahMwh":100},{"hour":3,"priceUahMwh":70},{"hour":4,"priceUahMwh":100},{"hour":5,"priceUahMwh":4800},{"hour":6,"priceUahMwh":5880},{"hour":7,"priceUahMwh":5267},{"hour":8,"priceUahMwh":3878},{"hour":9,"priceUahMwh":3050},{"hour":10,"priceUahMwh":49},{"hour":11,"priceUahMwh":10},{"hour":12,"priceUahMwh":11},{"hour":13,"priceUahMwh":11},{"hour":14,"priceUahMwh":10},{"hour":15,"priceUahMwh":12},{"hour":16,"priceUahMwh":110},{"hour":17,"priceUahMwh":1900},{"hour":18,"priceUahMwh":6200},{"hour":19,"priceUahMwh":7400},{"hour":20,"priceUahMwh":6900},{"hour":21,"priceUahMwh":6100},{"hour":22,"priceUahMwh":5400},{"hour":23,"priceUahMwh":4800}],"settings":{"volumeMwh":5,"minSpreadUah":250,"maxTradesPerDay":4,"feeUahPerMwh":12},"locale":"uk"}}}},"responses":{"200":{"description":"Trading brief","content":{"application/json":{"schema":{"type":"object","required":["mode","generatedAt","brief","usage","auditEvent"],"properties":{"mode":{"type":"string","enum":["deterministic"]},"generatedAt":{"type":"string","format":"date-time"},"brief":{"$ref":"#/components/schemas/TradingBrief"},"usage":{"$ref":"#/components/schemas/AiUsageTelemetry"},"auditEvent":{"$ref":"#/components/schemas/AuditEvent"}},"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/audit/events":{"post":{"tags":["Audit"],"summary":"Create an audit event","operationId":"createAuditEvent","requestBody":{"required":true,"description":"Audit event input","content":{"application/json":{"schema":{"type":"object","required":["type","actor","tradeDate","source"],"properties":{"type":{"type":"string","enum":["prices_loaded","csv_imported","ai_brief_generated","plan_exported"]},"actor":{"type":"string","default":"local-user"},"tradeDate":{"type":"string","example":"13.05.2026"},"source":{"type":"string","example":"workspace"},"metadata":{"oneOf":[{"$ref":"#/components/schemas/DecisionPackageMetadata"},{"$ref":"#/components/schemas/AuditEventMetadata"}],"default":{},"description":"Use DecisionPackageMetadata for plan_exported events. Other audit events may use flat string/number/boolean metadata."}},"additionalProperties":false},"example":{"type":"plan_exported","actor":"local-user","tradeDate":"13.05.2026","source":"workspace","metadata":{"decision_package_id":"alvo-rdn-13-05-2026-0ab12cd","human_approval_required":true,"no_auto_submit":true,"generated_at":"2026-05-20T07:00:00.000Z","source":"oree.com.ua","data_confidence_score":95,"risk_score":84,"risk_status":"needsReview"}}}}},"responses":{"201":{"description":"Created audit event","content":{"application/json":{"schema":{"type":"object","required":["event"],"properties":{"event":{"$ref":"#/components/schemas/AuditEvent"}},"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/notifications/subscriptions":{"post":{"tags":["Notifications"],"summary":"Accept a PWA notification subscription contract","description":"Validates web push subscription details and selected signal channels. The endpoint is a contract boundary for future tenant-scoped persistence and provider delivery.","operationId":"createNotificationSubscription","requestBody":{"required":true,"description":"Notification subscription input","content":{"application/json":{"schema":{"type":"object","required":["subscription"],"properties":{"actor":{"type":"string","default":"local-user","example":"trader@example.com"},"channels":{"type":"array","minItems":1,"maxItems":4,"items":{"$ref":"#/components/schemas/NotificationChannel"},"default":["priceUpdate","riskAlert","exportReady"]},"locale":{"type":"string","enum":["uk","en"],"default":"uk"},"preferences":{"$ref":"#/components/schemas/NotificationPreferences"},"source":{"type":"string","enum":["workspace","api","pwa"],"default":"workspace"},"subscription":{"$ref":"#/components/schemas/WebPushSubscription"},"workspaceId":{"type":"string","default":"demo","example":"pilot-desk"}},"additionalProperties":false},"example":{"actor":"trader@example.com","locale":"uk","preferences":{"priceUpdate":true,"riskAlert":true,"bessWindow":false,"exportReady":true},"source":"workspace","subscription":{"endpoint":"https://push.example.com/send/alvo-demo-subscription","expirationTime":null,"keys":{"auth":"auth-secret-demo-value","p256dh":"p256dh-public-key-demo-value"}},"workspaceId":"pilot-desk"}}}},"responses":{"202":{"description":"Accepted notification subscription contract","content":{"application/json":{"schema":{"type":"object","required":["registration","nextStep"],"properties":{"registration":{"$ref":"#/components/schemas/NotificationSubscriptionRegistration"},"nextStep":{"type":"string"}},"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"AlvoApiKey":{"type":"apiKey","in":"header","name":"x-alvo-api-key","description":"Required when ALVO_REQUIRE_API_KEY=true. Demo deployments may expose read-only decision-support endpoints without a key."},"BearerAuth":{"type":"http","scheme":"bearer","description":"Alternative bearer token form for the same API key."}},"responses":{"ValidationError":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"API key required or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UpstreamError":{"description":"Upstream market data error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"PricePoint":{"type":"object","required":["hour","priceUahMwh"],"properties":{"hour":{"type":"integer","minimum":0,"maximum":23,"example":14},"priceUahMwh":{"type":"number","minimum":0,"example":4478}},"additionalProperties":false},"PriceDay":{"type":"array","minItems":24,"maxItems":24,"items":{"$ref":"#/components/schemas/PricePoint"}},"PriceBook":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/PriceDay"},"example":{"13.05.2026":[{"hour":0,"priceUahMwh":5575},{"hour":1,"priceUahMwh":5100},{"hour":2,"priceUahMwh":100},{"hour":3,"priceUahMwh":70},{"hour":4,"priceUahMwh":100},{"hour":5,"priceUahMwh":4800},{"hour":6,"priceUahMwh":5880},{"hour":7,"priceUahMwh":5267},{"hour":8,"priceUahMwh":3878},{"hour":9,"priceUahMwh":3050},{"hour":10,"priceUahMwh":49},{"hour":11,"priceUahMwh":10},{"hour":12,"priceUahMwh":11},{"hour":13,"priceUahMwh":11},{"hour":14,"priceUahMwh":10},{"hour":15,"priceUahMwh":12},{"hour":16,"priceUahMwh":110},{"hour":17,"priceUahMwh":1900},{"hour":18,"priceUahMwh":6200},{"hour":19,"priceUahMwh":7400},{"hour":20,"priceUahMwh":6900},{"hour":21,"priceUahMwh":6100},{"hour":22,"priceUahMwh":5400},{"hour":23,"priceUahMwh":4800}]}},"ForecastPoint":{"type":"object","required":["hour","p10","p50","p90"],"properties":{"hour":{"type":"integer","minimum":0,"maximum":23,"example":18},"p10":{"type":"number","minimum":0,"example":5200},"p50":{"type":"number","minimum":0,"example":6100},"p90":{"type":"number","minimum":0,"example":7300}},"additionalProperties":false},"ForecastDay":{"type":"array","minItems":24,"maxItems":24,"items":{"$ref":"#/components/schemas/ForecastPoint"}},"ForecastBook":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ForecastDay"}},"ForecastMetrics":{"type":"object","required":["rmaeVsNaive","mae","rmse","sampleDays"],"properties":{"rmaeVsNaive":{"type":"number","minimum":0,"example":0.92},"mae":{"type":"number","minimum":0,"example":430},"rmse":{"type":"number","minimum":0,"example":560},"sampleDays":{"type":"integer","minimum":0,"example":26},"coverage":{"type":"number","minimum":0,"maximum":1,"example":0.81}},"additionalProperties":false},"ForecastFreshness":{"type":"object","required":["status","source","generatedAt"],"properties":{"status":{"type":"string","enum":["fresh","stale","missing","fallback"],"example":"fresh"},"source":{"type":"string","example":"forecast:ridge-ar"},"generatedAt":{"type":"string","format":"date-time"},"observedAt":{"type":"string","format":"date-time"}},"additionalProperties":false},"Forecast":{"type":"object","required":["source","model","baseline","metrics","freshness","data"],"properties":{"source":{"type":"string","example":"forecast:ridge-ar"},"model":{"type":"string","example":"ridge-ar"},"baseline":{"type":"string","example":"seasonal-naive"},"metrics":{"$ref":"#/components/schemas/ForecastMetrics"},"freshness":{"$ref":"#/components/schemas/ForecastFreshness"},"data":{"$ref":"#/components/schemas/ForecastBook"}},"additionalProperties":false},"OreeIndexPoint":{"type":"object","required":["tradeDate","baseIndexUahMwh","peakIndexUahMwh","offPeakIndexUahMwh","minPriceUahMwh","maxPriceUahMwh","weightedAverageUahMwh"],"properties":{"tradeDate":{"type":"string","example":"13.05.2026"},"baseIndexUahMwh":{"type":"number","example":6856},"peakIndexUahMwh":{"type":"number","example":7400},"offPeakIndexUahMwh":{"type":"number","example":6312},"minPriceUahMwh":{"type":"number","example":10},"maxPriceUahMwh":{"type":"number","example":9000},"weightedAverageUahMwh":{"type":"number","example":6904}},"additionalProperties":false},"OreeIndexBook":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/OreeIndexPoint"},"example":{"13.05.2026":{"tradeDate":"13.05.2026","baseIndexUahMwh":6856,"peakIndexUahMwh":7400,"offPeakIndexUahMwh":6312,"minPriceUahMwh":10,"maxPriceUahMwh":9000,"weightedAverageUahMwh":6904}}},"OreeTradingResultPoint":{"type":"object","required":["hour","priceUahMwh","sellVolumeMwh","buyVolumeMwh","declaredSellVolumeMwh","declaredBuyVolumeMwh"],"properties":{"hour":{"type":"integer","minimum":0,"maximum":23,"example":21},"priceUahMwh":{"type":"number","example":9277},"sellVolumeMwh":{"type":"number","example":4100.4},"buyVolumeMwh":{"type":"number","example":4100.4},"declaredSellVolumeMwh":{"type":"number","example":5200.1},"declaredBuyVolumeMwh":{"type":"number","example":4300.8}},"additionalProperties":false},"OreeTradingResultsDay":{"type":"object","required":["tradeDate","market","resultId","totalSellVolumeMwh","totalBuyVolumeMwh","declaredSellVolumeMwh","declaredBuyVolumeMwh","weightedAveragePriceUahMwh","hours"],"properties":{"tradeDate":{"type":"string","example":"13.05.2026"},"market":{"type":"string","enum":["DAM","IDM"],"example":"DAM"},"resultId":{"type":"string","example":"13.05.2026/DAM/2"},"totalSellVolumeMwh":{"type":"number","example":79342.1},"totalBuyVolumeMwh":{"type":"number","example":79342.1},"declaredSellVolumeMwh":{"type":"number","example":116774.7},"declaredBuyVolumeMwh":{"type":"number","example":82121.5},"weightedAveragePriceUahMwh":{"type":"number","example":7653.97},"hours":{"type":"array","minItems":1,"maxItems":24,"items":{"$ref":"#/components/schemas/OreeTradingResultPoint"}}},"additionalProperties":false,"example":{"tradeDate":"13.05.2026","market":"DAM","resultId":"13.05.2026/DAM/2","totalSellVolumeMwh":79342.1,"totalBuyVolumeMwh":79342.1,"declaredSellVolumeMwh":116774.7,"declaredBuyVolumeMwh":82121.5,"weightedAveragePriceUahMwh":7653.97,"hours":[{"hour":21,"priceUahMwh":9277,"sellVolumeMwh":4100.4,"buyVolumeMwh":4100.4,"declaredSellVolumeMwh":5200.1,"declaredBuyVolumeMwh":4300.8}]}},"UeexElectricityIndex":{"type":"object","required":["period","periodType","deliveryKey","valueUahMwh"],"properties":{"period":{"type":"string","example":"April 2026"},"periodType":{"type":"string","enum":["monthly","quarterly","halfYear","decadal"],"example":"monthly"},"deliveryKey":{"type":"string","example":"2026-04"},"valueUahMwh":{"type":"number","example":6006.7}},"additionalProperties":false},"DataProvider":{"type":"object","required":["id","name","category","status","sourceUrl","requiresToken","summary","detail","nextStep"],"properties":{"id":{"type":"string","enum":["oree","ueex","entsoe","ukrenergo","weather","fuelCarbon","energyMap","neurc","amcu"],"example":"oree"},"name":{"type":"string","example":"Market Operator"},"category":{"type":"string","enum":["market","benchmark","system","regulatory","weather","macro"],"example":"market"},"status":{"type":"string","enum":["connected","tokenRequired","planned","review"],"example":"connected"},"sourceUrl":{"type":"string","format":"uri","example":"https://www.oree.com.ua/index.php/pricectr"},"apiPath":{"type":"string","example":"/api/oree/prices, /api/oree/indexes, /api/oree/trading-results"},"requiresToken":{"type":"boolean","example":false},"summary":{"type":"string"},"detail":{"type":"string"},"nextStep":{"type":"string"}},"additionalProperties":false},"DataProviderHealth":{"type":"object","required":["providerId","status","cadence","maxAgeHours","latestDataAt","checkedAt","ageHours","detail"],"properties":{"providerId":{"type":"string","enum":["oree","ueex","entsoe","ukrenergo","weather","fuelCarbon","energyMap","neurc","amcu"],"example":"oree"},"status":{"type":"string","enum":["fresh","stale","pending","blocked"],"example":"fresh"},"cadence":{"type":"string","example":"daily market publication"},"maxAgeHours":{"type":"number","example":36},"latestDataAt":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}],"example":"2026-05-18T06:00:00.000Z"},"checkedAt":{"type":"string","format":"date-time","example":"2026-05-18T06:10:00.000Z"},"ageHours":{"oneOf":[{"type":"number"},{"type":"null"}],"example":6},"detail":{"type":"string"}},"additionalProperties":false},"TradingSettings":{"type":"object","required":["volumeMwh","minSpreadUah","maxTradesPerDay"],"properties":{"volumeMwh":{"type":"number","exclusiveMinimum":0,"example":5},"minSpreadUah":{"type":"number","minimum":0,"example":250},"maxTradesPerDay":{"type":"integer","minimum":1,"maximum":24,"example":4},"feeUahPerMwh":{"type":"number","minimum":0,"default":0,"example":12}},"additionalProperties":false},"StrategyProfile":{"type":"object","required":["id","tenantId","actorId","profileKey","name","settings","fingerprint","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string"},"actorId":{"type":"string"},"profileKey":{"type":"string"},"name":{"type":"string"},"settings":{"$ref":"#/components/schemas/TradingSettings"},"fingerprint":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false,"example":{"id":"f1c1d77a-7d71-46ef-b64d-3a3cbce8b22b","tenantId":"org_acme","actorId":"trader@example.com","profileKey":"balanced","name":"Balanced","settings":{"volumeMwh":5,"minSpreadUah":250,"maxTradesPerDay":4,"feeUahPerMwh":12},"fingerprint":"v5-s250-t4-f12","createdAt":"2026-05-25T08:00:00.000Z","updatedAt":"2026-05-25T08:00:00.000Z"}},"BessSettings":{"type":"object","required":["capacityMwh","powerMw","roundTripEfficiency","maxCyclesPerDay"],"properties":{"capacityMwh":{"type":"number","exclusiveMinimum":0,"example":10},"powerMw":{"type":"number","exclusiveMinimum":0,"example":5},"roundTripEfficiency":{"type":"number","exclusiveMinimum":0,"maximum":1,"example":0.9},"maxCyclesPerDay":{"type":"integer","minimum":1,"maximum":12,"example":2},"degradationCostUahMwh":{"type":"number","minimum":0,"default":0,"example":80}},"additionalProperties":false},"RecommendedTrade":{"type":"object","required":["buyHour","sellHour","buyPriceUahMwh","sellPriceUahMwh","netSpreadUah","volumeMwh","pnlUah"],"properties":{"buyHour":{"type":"integer","minimum":0,"maximum":23},"sellHour":{"type":"integer","minimum":0,"maximum":23},"buyPriceUahMwh":{"type":"number"},"sellPriceUahMwh":{"type":"number"},"netSpreadUah":{"type":"number"},"volumeMwh":{"type":"number"},"pnlUah":{"type":"number"}},"additionalProperties":false},"TradingPlan":{"type":"object","required":["trades","totalVolumeMwh","netPnlUah","averageSpreadUah"],"properties":{"trades":{"type":"array","items":{"$ref":"#/components/schemas/RecommendedTrade"}},"totalVolumeMwh":{"type":"number"},"netPnlUah":{"type":"number"},"averageSpreadUah":{"type":"number"}},"additionalProperties":false},"BessCycle":{"type":"object","required":["chargeHour","dischargeHour","chargeMwh","dischargeMwh","chargePriceUahMwh","dischargePriceUahMwh","grossSpreadUahMwh","profitUah"],"properties":{"chargeHour":{"type":"integer","minimum":0,"maximum":23},"dischargeHour":{"type":"integer","minimum":0,"maximum":23},"chargeMwh":{"type":"number"},"dischargeMwh":{"type":"number"},"chargePriceUahMwh":{"type":"number"},"dischargePriceUahMwh":{"type":"number"},"grossSpreadUahMwh":{"type":"number"},"profitUah":{"type":"number"}},"additionalProperties":false},"BessPlan":{"type":"object","required":["cycles","netProfitUah","chargedMwh","dischargedMwh","equivalentCycles"],"properties":{"cycles":{"type":"array","items":{"$ref":"#/components/schemas/BessCycle"}},"netProfitUah":{"type":"number"},"chargedMwh":{"type":"number"},"dischargedMwh":{"type":"number"},"equivalentCycles":{"type":"number"}},"additionalProperties":false},"BacktestDay":{"type":"object","required":["tradeDate","strategyPnlUah","bessPnlUah","combinedPnlUah","trades","bessCycles","averageSpreadUah","equivalentBessCycles"],"properties":{"tradeDate":{"type":"string"},"strategyPnlUah":{"type":"number"},"bessPnlUah":{"type":"number"},"combinedPnlUah":{"type":"number"},"trades":{"type":"integer"},"bessCycles":{"type":"integer"},"averageSpreadUah":{"type":"number"},"equivalentBessCycles":{"type":"number"}},"additionalProperties":false},"BacktestSummary":{"type":"object","required":["totalDays","profitableDays","hitRate","strategyNetPnlUah","bessNetProfitUah","combinedNetPnlUah","averageDailyPnlUah","totalTrades","totalBessCycles","bestDay","worstDay","daily"],"properties":{"totalDays":{"type":"integer"},"profitableDays":{"type":"integer"},"hitRate":{"type":"number"},"strategyNetPnlUah":{"type":"number"},"bessNetProfitUah":{"type":"number"},"combinedNetPnlUah":{"type":"number"},"averageDailyPnlUah":{"type":"number"},"totalTrades":{"type":"integer"},"totalBessCycles":{"type":"integer"},"bestDay":{"oneOf":[{"$ref":"#/components/schemas/BacktestDay"},{"type":"null"}]},"worstDay":{"oneOf":[{"$ref":"#/components/schemas/BacktestDay"},{"type":"null"}]},"daily":{"type":"array","items":{"$ref":"#/components/schemas/BacktestDay"}}},"additionalProperties":false},"RiskGuardrailReport":{"type":"object","required":["overallStatus","score","checks","reviewCount","blockCount"],"properties":{"overallStatus":{"type":"string","enum":["ready","needsReview","blocked"]},"score":{"type":"number","minimum":0,"maximum":100},"checks":{"type":"array","items":{"type":"object","required":["id","status","value","unit"],"properties":{"id":{"type":"string","enum":["dataSource","dataCoverage","priceAnomaly","tradeConcentration","cashExposure","bessCycles","humanApproval"]},"status":{"type":"string","enum":["pass","review","block"]},"value":{"oneOf":[{"type":"number"},{"type":"string"}]},"unit":{"type":"string","enum":["source","coverage","count","uah","mwh","cycles","approval"]}},"additionalProperties":false}},"reviewCount":{"type":"integer"},"blockCount":{"type":"integer"}},"additionalProperties":false},"TradingBrief":{"type":"object","description":"Localized brief object generated by the deterministic AI assistant.","required":["summary","actionGate","auditTrail","decisionQuality","dataCoverage","decisionSensitivity","decisionDrivers","marketContext","traderChecklist","anomalies","automationActions","disclaimer"],"properties":{"summary":{"type":"string"},"actionGate":{"type":"object","required":["status","label","reasons","nextActions"],"properties":{"status":{"type":"string","enum":["ready","review","hold"]},"label":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}},"nextActions":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"auditTrail":{"type":"object","required":["rationaleId","facts","controls","limitations"],"properties":{"rationaleId":{"type":"string"},"facts":{"type":"array","items":{"type":"object","required":["key","label","value"],"properties":{"key":{"type":"string"},"label":{"type":"string"},"value":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"unit":{"type":"string"}},"additionalProperties":false}},"controls":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"decisionQuality":{"type":"object","required":["level","score","label","reasons"],"properties":{"level":{"type":"string","enum":["high","medium","low"]},"score":{"type":"integer","minimum":0,"maximum":100},"label":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"dataCoverage":{"type":"object","required":["score","label","available","missing"],"properties":{"score":{"type":"integer","minimum":0,"maximum":100},"label":{"type":"string"},"available":{"type":"array","items":{"type":"string"}},"missing":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"decisionSensitivity":{"type":"object","required":["score","label","checks"],"properties":{"score":{"type":"integer","minimum":0,"maximum":100},"label":{"type":"string"},"checks":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"decisionDrivers":{"type":"array","items":{"type":"string"}},"marketContext":{"type":"array","items":{"type":"string"}},"traderChecklist":{"type":"array","items":{"type":"string"}},"anomalies":{"type":"array","items":{"type":"string"}},"automationActions":{"type":"array","items":{"type":"string"}},"disclaimer":{"type":"string"}},"additionalProperties":false},"AiUsageTelemetry":{"type":"object","required":["budgetImpact","cacheEligible","dataSentToExternalModel","estimatedCostUsd","externalTokenUsage","mode","model","provider"],"properties":{"mode":{"type":"string","enum":["deterministic"]},"provider":{"type":"string","enum":["none"]},"model":{"type":"string","enum":["alvo-rules-v1"]},"dataSentToExternalModel":{"type":"boolean","enum":[false]},"externalTokenUsage":{"type":"object","required":["input","output","total"],"properties":{"input":{"type":"integer","enum":[0]},"output":{"type":"integer","enum":[0]},"total":{"type":"integer","enum":[0]}},"additionalProperties":false},"estimatedCostUsd":{"type":"number","enum":[0]},"budgetImpact":{"type":"string","enum":["none"]},"cacheEligible":{"type":"boolean","enum":[true]}},"additionalProperties":false},"AuditEventMetadata":{"type":"object","additionalProperties":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"example":{"locale":"uk","source":"oree.com.ua"}},"DecisionPackageMetadata":{"type":"object","description":"Flat metadata attached to CSV exports and plan_exported audit events. It identifies the generated decision package and keeps the V1 no-auto-submit control explicit.","required":["decision_package_id","human_approval_required","no_auto_submit"],"properties":{"decision_package_id":{"type":"string","pattern":"^alvo-(rdn|bess)-","example":"alvo-rdn-13-05-2026-0ab12cd"},"human_approval_required":{"type":"boolean","enum":[true]},"no_auto_submit":{"type":"boolean","enum":[true]},"generated_at":{"type":"string","format":"date-time","example":"2026-05-20T07:00:00.000Z"},"source":{"type":"string","example":"oree.com.ua"},"data_confidence_score":{"type":"integer","minimum":0,"maximum":100,"example":95},"risk_score":{"type":"integer","minimum":0,"maximum":100,"example":84},"risk_status":{"type":"string","enum":["ready","needsReview","blocked"],"example":"needsReview"},"strategy_net_pnl_uah":{"type":"number"},"bess_net_profit_uah":{"type":"number"},"bess_equivalent_cycles":{"type":"number"}},"additionalProperties":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"example":{"decision_package_id":"alvo-rdn-13-05-2026-0ab12cd","human_approval_required":true,"no_auto_submit":true,"generated_at":"2026-05-20T07:00:00.000Z","source":"oree.com.ua","data_confidence_score":95,"risk_score":84,"risk_status":"needsReview"}},"AuditEvent":{"type":"object","required":["id","createdAt","type","actor","tradeDate","source","metadata"],"properties":{"id":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"type":{"type":"string"},"actor":{"type":"string"},"tradeDate":{"type":"string"},"source":{"type":"string"},"metadata":{"oneOf":[{"$ref":"#/components/schemas/DecisionPackageMetadata"},{"$ref":"#/components/schemas/AuditEventMetadata"}]}},"additionalProperties":false},"NotificationChannel":{"type":"string","enum":["priceUpdate","riskAlert","bessWindow","exportReady"]},"NotificationPreferences":{"type":"object","required":["priceUpdate","riskAlert","bessWindow","exportReady"],"properties":{"priceUpdate":{"type":"boolean","default":true},"riskAlert":{"type":"boolean","default":true},"bessWindow":{"type":"boolean","default":false},"exportReady":{"type":"boolean","default":true}},"additionalProperties":false},"WebPushSubscription":{"type":"object","required":["endpoint","keys"],"properties":{"endpoint":{"type":"string","format":"uri","example":"https://push.example.com/send/alvo-demo-subscription"},"expirationTime":{"oneOf":[{"type":"number"},{"type":"null"}],"default":null},"keys":{"type":"object","required":["p256dh","auth"],"properties":{"p256dh":{"type":"string","example":"p256dh-public-key-demo-value"},"auth":{"type":"string","example":"auth-secret-demo-value"}},"additionalProperties":false}},"additionalProperties":false},"SubscriptionPlan":{"type":"object","required":["apiAccess","description","features","id","includedAiBriefsMonthly","includedUsers","limits","monthlyPriceFromUah","name","supportLevel"],"properties":{"id":{"type":"string","enum":["starter","tradingDesk","bessOptimizer","platformApi"]},"name":{"type":"string","example":"Trading Desk"},"description":{"type":"string"},"monthlyPriceFromUah":{"type":"integer","minimum":0,"example":45000},"includedUsers":{"oneOf":[{"type":"integer","minimum":1},{"type":"string","enum":["custom"]}],"example":15},"includedAiBriefsMonthly":{"oneOf":[{"type":"integer","minimum":0},{"type":"string","enum":["custom"]}],"example":1500},"apiAccess":{"type":"string","enum":["none","read","bess","custom"],"example":"read"},"supportLevel":{"type":"string","enum":["standard","priority","dedicated"],"example":"priority"},"features":{"type":"array","minItems":1,"items":{"type":"string"}},"limits":{"type":"object","required":["auditTrail","bessPlanning","csvExport","sso","tenantIsolation","webPushSignals"],"properties":{"auditTrail":{"type":"boolean"},"bessPlanning":{"type":"boolean"},"csvExport":{"type":"boolean"},"sso":{"type":"boolean"},"tenantIsolation":{"type":"boolean"},"webPushSignals":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false},"SubscriptionAddOn":{"type":"object","required":["description","id","name","pricingModel"],"properties":{"id":{"type":"string","enum":["aiPack","extraSeats","integrationSupport"]},"name":{"type":"string","example":"AI pack"},"description":{"type":"string"},"pricingModel":{"type":"string","enum":["usage","seat","project"]}},"additionalProperties":false},"SubscriptionCatalog":{"type":"object","required":["addOns","billingMode","billingProvider","cadence","checkoutStatus","currency","locale","plans","policy"],"properties":{"addOns":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionAddOn"},"example":[{"id":"aiPack","name":"AI pack","description":"+1,000 AI briefs or a stronger model for complex risk/anomaly cases.","pricingModel":"usage"},{"id":"extraSeats","name":"Extra seats","description":"Additional trader, risk, analyst, or API-client users with roles.","pricingModel":"seat"},{"id":"integrationSupport","name":"Integration support","description":"Approved data connectors, private CSV/API sources, legal and security review.","pricingModel":"project"}]},"billingMode":{"type":"string","enum":["subscription"]},"billingProvider":{"type":"string","enum":["manualContract"]},"cadence":{"type":"string","enum":["monthly"]},"checkoutStatus":{"type":"string","enum":["planned"]},"currency":{"type":"string","enum":["UAH"]},"locale":{"type":"string","enum":["uk","en"]},"plans":{"type":"array","minItems":4,"items":{"$ref":"#/components/schemas/SubscriptionPlan"},"example":[{"id":"starter","monthlyPriceFromUah":15000,"monthlyPriceFromEur":330,"includedUsers":5,"includedAiBriefsMonthly":300,"apiAccess":"none","supportLevel":"standard","limits":{"auditTrail":true,"bessPlanning":false,"csvExport":true,"sso":false,"tenantIsolation":false,"webPushSignals":true},"name":"Starter","description":"First DAM workspace for a small trading team.","features":["DAM Assistant, OREE + UEEX data","Spread plan, risk guardrails, and CSV export","AI transparency: mode, tokens, cost, and external model"]},{"id":"tradingDesk","monthlyPriceFromUah":45000,"monthlyPriceFromEur":1000,"includedUsers":15,"includedAiBriefsMonthly":1500,"apiAccess":"read","supportLevel":"priority","limits":{"auditTrail":true,"bessPlanning":false,"csvExport":true,"sso":false,"tenantIsolation":true,"webPushSignals":true},"name":"Trading Desk","description":"Team workflow with roles, decision history, and read API access.","features":["Everything in Starter plus team workspace","RBAC-ready roles, approvals, and tenant audit trail","API for plans, risk, backtesting, and export"]},{"id":"bessOptimizer","monthlyPriceFromUah":90000,"monthlyPriceFromEur":2000,"includedUsers":25,"includedAiBriefsMonthly":3000,"apiAccess":"bess","supportLevel":"priority","limits":{"auditTrail":true,"bessPlanning":true,"csvExport":true,"sso":false,"tenantIsolation":true,"webPushSignals":true},"name":"BESS Optimizer","description":"Storage planning over DAM: charge, discharge, cycles, and degradation.","features":["BESS planning, SoC, cycles, and degradation","DAM vs BESS scenario comparison","Push signals for BESS windows and risk events"]},{"id":"platformApi","monthlyPriceFromUah":150000,"monthlyPriceFromEur":3300,"includedUsers":"custom","includedAiBriefsMonthly":"custom","apiAccess":"custom","supportLevel":"dedicated","limits":{"auditTrail":true,"bessPlanning":true,"csvExport":true,"sso":true,"tenantIsolation":true,"webPushSignals":true},"name":"Platform API","description":"Internal API layer or white-label analytics with custom limits.","features":["SSO/OIDC, tenant isolation, and production audit","Dedicated API limits, integration keys, and webhooks","Approved data connectors, support, and security review"]}]},"policy":{"type":"object","required":["aiUsageMetered","humanApprovalRequired","noGuaranteedProfitClaims","overagesRequireApproval"],"properties":{"aiUsageMetered":{"type":"boolean","enum":[true]},"humanApprovalRequired":{"type":"boolean","enum":[true]},"noGuaranteedProfitClaims":{"type":"boolean","enum":[true]},"overagesRequireApproval":{"type":"boolean","enum":[true]}},"additionalProperties":false}},"additionalProperties":false},"NotificationSubscriptionRegistration":{"type":"object","required":["actor","channels","createdAt","delivery","locale","mode","policy","source","status","subscriptionId","workspaceId"],"properties":{"actor":{"type":"string"},"channels":{"type":"array","items":{"$ref":"#/components/schemas/NotificationChannel"}},"createdAt":{"type":"string","format":"date-time"},"delivery":{"type":"string","enum":["webPush"]},"locale":{"type":"string","enum":["uk","en"]},"mode":{"type":"string","enum":["contract"]},"policy":{"type":"object","required":["humanApprovalRequired","noTradingAction"],"properties":{"humanApprovalRequired":{"type":"boolean","enum":[true]},"noTradingAction":{"type":"boolean","enum":[true]}},"additionalProperties":false},"source":{"type":"string","enum":["workspace","api","pwa"]},"status":{"type":"string","enum":["accepted"]},"subscriptionId":{"type":"string","example":"sub_2k9h31"},"workspaceId":{"type":"string"}},"additionalProperties":false},"OperationalReadiness":{"type":"object","required":["status","generatedAt","app","security","securityPosture","notifications","platformData","production","summary","dataProviders","dataProviderHealth","trustIntegrations","checks"],"properties":{"status":{"type":"string","enum":["ok","degraded"]},"generatedAt":{"type":"string","format":"date-time"},"app":{"type":"object","required":["name","version","apiVersion","mode"],"properties":{"name":{"type":"string","enum":["Alvo"]},"version":{"type":"string","example":"0.1.0"},"apiVersion":{"type":"string","enum":["v1"]},"mode":{"type":"string","enum":["decision-support"]}},"additionalProperties":false},"security":{"type":"object","required":["apiKeyRequired","apiKeyConfigured","rateLimitPerMinute","rateLimitWindowMs","authRequired","authProvider","authProviderConfigured"],"properties":{"apiKeyRequired":{"type":"boolean"},"apiKeyConfigured":{"type":"boolean"},"rateLimitPerMinute":{"type":"integer"},"rateLimitWindowMs":{"type":"integer"},"authRequired":{"type":"boolean"},"authProvider":{"type":"string","enum":["none","clerk","auth0","workos","cognito","customOidc"]},"authProviderConfigured":{"type":"boolean"}},"additionalProperties":false},"securityPosture":{"type":"object","required":["generatedFrom","auth","accessControl","controls"],"properties":{"generatedFrom":{"type":"string","enum":["server-env"]},"auth":{"type":"object","required":["provider","required","configured","issuerConfigured","audienceConfigured","recommendation","mode"],"properties":{"provider":{"type":"string","enum":["none","clerk","auth0","workos","cognito","customOidc"]},"required":{"type":"boolean"},"configured":{"type":"boolean"},"issuerConfigured":{"type":"boolean"},"audienceConfigured":{"type":"boolean"},"recommendation":{"type":"string","enum":["workos","clerk","auth0","cognito"]},"mode":{"type":"string","enum":["public-demo","api-key","external-auth"]}},"additionalProperties":false},"accessControl":{"type":"object","required":["mode","enforced","roles","permissions","permissionCount","highRiskPermissions","decisionSubmitRequiresApproval","nextStep"],"properties":{"mode":{"type":"string","enum":["planned","enforced"]},"enforced":{"type":"boolean"},"roles":{"type":"array","items":{"type":"object","required":["id","label","description","permissions"],"properties":{"id":{"type":"string","enum":["owner","trader","analyst","risk","apiClient","auditor"]},"label":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}},"permissions":{"type":"array","items":{"type":"object","required":["id","category","label","description","highRisk"],"properties":{"id":{"type":"string"},"category":{"type":"string","enum":["workspace","data","decision","risk","automation","admin"]},"label":{"type":"string"},"description":{"type":"string"},"highRisk":{"type":"boolean"}},"additionalProperties":false}},"permissionCount":{"type":"integer"},"highRiskPermissions":{"type":"array","items":{"type":"string"}},"decisionSubmitRequiresApproval":{"type":"boolean"},"nextStep":{"type":"string"}},"additionalProperties":false},"controls":{"type":"array","items":{"type":"object","required":["id","status","framework","target","evidence","nextStep"],"properties":{"id":{"type":"string","enum":["owaspAsvs","soc2","hipaa","authProvider","rbac"]},"status":{"type":"string","enum":["active","review","planned","notApplicable"]},"framework":{"type":"string"},"target":{"type":"string"},"evidence":{"type":"array","items":{"type":"string"}},"nextStep":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false},"notifications":{"type":"object","required":["mode","deliveryProvider","webPushPublicKeyConfigured","webPushPrivateKeyConfigured","subscriptionStoreConfigured"],"properties":{"mode":{"type":"string","enum":["contractOnly","deliveryReady"]},"deliveryProvider":{"type":"string","enum":["none","webPush","sns","pinpoint","firebase","onesignal","custom"]},"webPushPublicKeyConfigured":{"type":"boolean"},"webPushPrivateKeyConfigured":{"type":"boolean"},"subscriptionStoreConfigured":{"type":"boolean"}},"additionalProperties":false},"platformData":{"type":"object","required":["mode","databaseConfigured","redisConfigured","dbReadsEnabled","dbIngestionEnabled","liveOreeFallbackEnabled"],"properties":{"mode":{"type":"string","enum":["gracefulFallback","platformOnly"]},"databaseConfigured":{"type":"boolean"},"redisConfigured":{"type":"boolean"},"dbReadsEnabled":{"type":"boolean"},"dbIngestionEnabled":{"type":"boolean"},"liveOreeFallbackEnabled":{"type":"boolean"}},"additionalProperties":false},"production":{"type":"object","required":["ready","summary","gates"],"properties":{"ready":{"type":"boolean"},"summary":{"type":"object","required":["ready","review","blocked"],"properties":{"ready":{"type":"integer"},"review":{"type":"integer"},"blocked":{"type":"integer"}},"additionalProperties":false},"gates":{"type":"array","items":{"type":"object","required":["id","status","owner","label","detail"],"properties":{"id":{"type":"string","enum":["apiProtection","auth","rbac","marketData","auditStorage","notifications","trustLayer"]},"status":{"type":"string","enum":["ready","review","blocked"]},"owner":{"type":"string","enum":["security","platform","data","product","legal"]},"label":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false},"summary":{"type":"object","required":["pass","review","block"],"properties":{"pass":{"type":"integer"},"review":{"type":"integer"},"block":{"type":"integer"}},"additionalProperties":false},"checks":{"type":"array","items":{"type":"object","required":["id","status","label","detail"],"properties":{"id":{"type":"string","enum":["web","api","security","rateLimit","marketData","decisionEngine","bessEngine","aiBrief","audit","notifications"]},"status":{"type":"string","enum":["pass","review","block"]},"label":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":false}},"dataProviders":{"type":"array","items":{"$ref":"#/components/schemas/DataProvider"}},"dataProviderHealth":{"type":"array","items":{"$ref":"#/components/schemas/DataProviderHealth"}},"trustIntegrations":{"type":"array","items":{"$ref":"#/components/schemas/TrustIntegration"}}},"additionalProperties":false},"TrustIntegration":{"type":"object","required":["id","name","category","status","sourceUrl","requiresContract","summary","productUse","nextStep"],"properties":{"id":{"type":"string","enum":["diiaSignature","diiaSharing","diiaValidation","qualifiedSignature"]},"name":{"type":"string"},"category":{"type":"string","enum":["identity","signature","documents","antiFraud"]},"status":{"type":"string","enum":["planned","legalReview","ready"]},"sourceUrl":{"type":"string","format":"uri"},"requiresContract":{"type":"boolean"},"summary":{"type":"string"},"productUse":{"type":"string"},"nextStep":{"type":"string"}},"additionalProperties":false},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string"},"retryAfterSeconds":{"type":"number"},"issues":{"type":"object","additionalProperties":true}},"additionalProperties":true}}}}