{"openapi":"3.1.0","info":{"title":"POST /api/v1/scenarios","version":"1.0.0","description":"Fork the company and simulate a decision"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/scenarios":{"post":{"tags":["scenarios"],"summary":"Fork the company and simulate a decision","description":"Queues a scenario: the business is copied into a sandbox, the typed changes (`price_change_pct`, `vendor_cost_change_pct`, `headcount_add`, `take_credit_line`, `cut_spend`, `delay_po`, `one_time_item`) are applied to the copy's cash forecast, and the baseline and scenario are stored with their diff. Poll `GET /scenarios/{id}` until `status` is `ready`. The copy is deleted afterwards unless `keep_clone` is true. At most two forks may be queued or running per business (`409`).","operationId":"create_scenario_fork","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScenarioForkCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_ScenarioForkResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict - Resource already exists or is in an incompatible state","content":{"application/json":{"example":{"error":"conflict","message":"Resource already exists","code":"CONFLICT_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"create_scenario_fork_api_v1_scenarios_post"}}},"components":{"schemas":{"CutSpend":{"properties":{"type":{"type":"string","const":"cut_spend","title":"Type"},"ledger_id":{"type":"string","minLength":1,"title":"Ledger Id"},"pct":{"type":"number","maximum":100.0,"exclusiveMinimum":0.0,"title":"Pct","description":"Percent of the line cut."},"start_week":{"type":"integer","maximum":26.0,"minimum":1.0,"title":"Start Week","default":1}},"additionalProperties":false,"type":"object","required":["type","ledger_id","pct"],"title":"CutSpend","description":"Cut a budget line: reduces that ledger's budgeted spend by the percent."},"DelayPo":{"properties":{"type":{"type":"string","const":"delay_po","title":"Type"},"po_id":{"type":"string","minLength":1,"title":"Po Id"},"weeks":{"type":"integer","maximum":26.0,"minimum":1.0,"title":"Weeks"}},"additionalProperties":false,"type":"object","required":["type","po_id","weeks"],"title":"DelayPo","description":"Pay a purchase order later: moves its payment by N weeks."},"HeadcountAdd":{"properties":{"type":{"type":"string","const":"headcount_add","title":"Type"},"role":{"type":"string","maxLength":120,"minLength":1,"title":"Role"},"monthly_cost_cents":{"type":"integer","exclusiveMinimum":0.0,"title":"Monthly Cost Cents"},"start_week":{"type":"integer","maximum":26.0,"minimum":1.0,"title":"Start Week","default":1},"count":{"type":"integer","maximum":500.0,"minimum":1.0,"title":"Count","default":1}},"additionalProperties":false,"type":"object","required":["type","role","monthly_cost_cents"],"title":"HeadcountAdd","description":"Hire: adds the loaded monthly cost to budgeted expense from the start week."},"OneTimeItem":{"properties":{"type":{"type":"string","const":"one_time_item","title":"Type"},"label":{"type":"string","maxLength":200,"minLength":1,"title":"Label"},"amount_cents":{"type":"integer","exclusiveMinimum":0.0,"title":"Amount Cents"},"week":{"type":"integer","maximum":26.0,"minimum":1.0,"title":"Week"},"direction":{"type":"string","enum":["inflow","outflow"],"title":"Direction"}},"additionalProperties":false,"type":"object","required":["type","label","amount_cents","week","direction"],"title":"OneTimeItem","description":"A single cash event in one week."},"PriceChange":{"properties":{"type":{"type":"string","const":"price_change_pct","title":"Type"},"pct":{"type":"number","maximum":1000.0,"minimum":-100.0,"title":"Pct","description":"Percent change, e.g. 5 or -10."},"start_week":{"type":"integer","maximum":26.0,"minimum":1.0,"title":"Start Week","default":1}},"additionalProperties":false,"type":"object","required":["type","pct"],"title":"PriceChange","description":"Move prices: scales budgeted revenue (or, with no budget, scheduled AR)."},"ScenarioAppliedChange":{"properties":{"change_index":{"type":"integer","title":"Change Index"},"change_type":{"type":"string","title":"Change Type"},"kind":{"type":"string","enum":["pending_change","limit_change_request","manual"],"title":"Kind"},"summary":{"type":"string","title":"Summary"},"pending_change_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pending Change Id"},"limit_change_request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Limit Change Request Id"},"tool_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Name"}},"type":"object","required":["change_index","change_type","kind","summary"],"title":"ScenarioAppliedChange"},"ScenarioCovenant":{"properties":{"instrument_id":{"type":"string","title":"Instrument Id"},"instrument_name":{"type":"string","title":"Instrument Name"},"metric_name":{"type":"string","title":"Metric Name"},"operator":{"type":"string","title":"Operator"},"threshold_value":{"type":"string","title":"Threshold Value"},"baseline_status":{"type":"string","enum":["pass","fail","not_evaluated"],"title":"Baseline Status"},"scenario_status":{"type":"string","enum":["pass","fail","not_evaluated"],"title":"Scenario Status"},"baseline_value_cents":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Baseline Value Cents"},"scenario_value_cents":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Scenario Value Cents"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note"}},"type":"object","required":["instrument_id","instrument_name","metric_name","operator","threshold_value","baseline_status","scenario_status"],"title":"ScenarioCovenant"},"ScenarioDiff":{"properties":{"ending_cash_delta_cents":{"type":"integer","title":"Ending Cash Delta Cents"},"lowest_cash_delta_cents":{"type":"integer","title":"Lowest Cash Delta Cents"},"baseline_lowest_cash_week":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Baseline Lowest Cash Week"},"scenario_lowest_cash_week":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Scenario Lowest Cash Week"},"goes_negative":{"type":"boolean","title":"Goes Negative","description":"Scenario dips below zero where the baseline did not."},"week_deltas":{"items":{"$ref":"#/components/schemas/ScenarioWeekDelta"},"type":"array","title":"Week Deltas"},"pnl_delta":{"$ref":"#/components/schemas/ScenarioPnlDelta"},"covenant_flags":{"items":{"type":"string"},"type":"array","title":"Covenant Flags","description":"Covenants whose status changed, e.g. 'Minimum cash: pass -> fail'."},"trust_grade_changed":{"type":"boolean","title":"Trust Grade Changed","default":false},"overrides":{"items":{"$ref":"#/components/schemas/ScenarioOverrideCell"},"type":"array","title":"Overrides","description":"The forecast cells the changes moved, as literal values."},"one_time_items":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"One Time Items"},"notes":{"items":{"type":"string"},"type":"array","title":"Notes","description":"How each change was applied and anything it could not do."},"headline":{"type":"string","title":"Headline"}},"type":"object","required":["ending_cash_delta_cents","lowest_cash_delta_cents","goes_negative","pnl_delta","headline"],"title":"ScenarioDiff"},"ScenarioForkCreate":{"properties":{"title":{"type":"string","maxLength":200,"minLength":1,"title":"Title"},"decision":{"items":{"oneOf":[{"$ref":"#/components/schemas/PriceChange"},{"$ref":"#/components/schemas/VendorCostChange"},{"$ref":"#/components/schemas/HeadcountAdd"},{"$ref":"#/components/schemas/TakeCreditLine"},{"$ref":"#/components/schemas/CutSpend"},{"$ref":"#/components/schemas/DelayPo"},{"$ref":"#/components/schemas/OneTimeItem"}],"discriminator":{"propertyName":"type","mapping":{"cut_spend":"#/components/schemas/CutSpend","delay_po":"#/components/schemas/DelayPo","headcount_add":"#/components/schemas/HeadcountAdd","one_time_item":"#/components/schemas/OneTimeItem","price_change_pct":"#/components/schemas/PriceChange","take_credit_line":"#/components/schemas/TakeCreditLine","vendor_cost_change_pct":"#/components/schemas/VendorCostChange"}}},"type":"array","maxItems":25,"minItems":1,"title":"Decision"},"horizon_weeks":{"type":"integer","maximum":26.0,"minimum":4.0,"title":"Horizon Weeks","default":13},"keep_clone":{"type":"boolean","title":"Keep Clone","description":"Keep the sandbox copy after the simulation so it can be opened; by default it is deleted when the results are stored.","default":false}},"additionalProperties":false,"type":"object","required":["title","decision"],"title":"ScenarioForkCreate"},"ScenarioForkResponse":{"properties":{"id":{"type":"string","title":"Id"},"business_id":{"type":"string","title":"Business Id"},"clone_business_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Clone Business Id"},"title":{"type":"string","title":"Title"},"decision":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Decision"},"horizon_weeks":{"type":"integer","title":"Horizon Weeks"},"status":{"type":"string","title":"Status"},"keep_clone":{"type":"boolean","title":"Keep Clone"},"baseline_summary":{"anyOf":[{"$ref":"#/components/schemas/ScenarioSummary"},{"type":"null"}]},"result_summary":{"anyOf":[{"$ref":"#/components/schemas/ScenarioSummary"},{"type":"null"}]},"diff":{"anyOf":[{"$ref":"#/components/schemas/ScenarioDiff"},{"type":"null"}]},"applied_changes":{"anyOf":[{"items":{"$ref":"#/components/schemas/ScenarioAppliedChange"},"type":"array"},{"type":"null"}],"title":"Applied Changes"},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"finished_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Finished At"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["id","business_id","title","decision","horizon_weeks","status","keep_clone","created_at"],"title":"ScenarioForkResponse"},"ScenarioOverrideCell":{"properties":{"week_number":{"type":"integer","title":"Week Number"},"column":{"type":"string","title":"Column"},"amount_cents":{"type":"integer","title":"Amount Cents"},"baseline_amount_cents":{"type":"integer","title":"Baseline Amount Cents"}},"type":"object","required":["week_number","column","amount_cents","baseline_amount_cents"],"title":"ScenarioOverrideCell"},"ScenarioPnl":{"properties":{"revenue_cents":{"type":"integer","title":"Revenue Cents"},"revenue_basis":{"type":"string","enum":["budget","scheduled_ar","none"],"title":"Revenue Basis"},"cogs_cents":{"type":"integer","title":"Cogs Cents"},"gross_margin_cents":{"type":"integer","title":"Gross Margin Cents"},"gross_margin_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Gross Margin Pct"},"opex_cents":{"type":"integer","title":"Opex Cents"},"financing_cost_cents":{"type":"integer","title":"Financing Cost Cents","default":0},"net_cents":{"type":"integer","title":"Net Cents"},"debt_service_cents":{"type":"integer","title":"Debt Service Cents","default":0}},"type":"object","required":["revenue_cents","revenue_basis","cogs_cents","gross_margin_cents","opex_cents","net_cents"],"title":"ScenarioPnl","description":"A cash-basis proxy for the horizon's P&L, from the forecast's own rows."},"ScenarioPnlDelta":{"properties":{"revenue_cents":{"type":"integer","title":"Revenue Cents"},"cogs_cents":{"type":"integer","title":"Cogs Cents"},"gross_margin_cents":{"type":"integer","title":"Gross Margin Cents"},"opex_cents":{"type":"integer","title":"Opex Cents"},"financing_cost_cents":{"type":"integer","title":"Financing Cost Cents"},"net_cents":{"type":"integer","title":"Net Cents"}},"type":"object","required":["revenue_cents","cogs_cents","gross_margin_cents","opex_cents","financing_cost_cents","net_cents"],"title":"ScenarioPnlDelta"},"ScenarioSummary":{"properties":{"starting_cash_cents":{"type":"integer","title":"Starting Cash Cents"},"ending_cash_cents":{"type":"integer","title":"Ending Cash Cents"},"lowest_cash_cents":{"type":"integer","title":"Lowest Cash Cents"},"lowest_cash_week":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Lowest Cash Week"},"lowest_cash_week_start":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Lowest Cash Week Start"},"weeks":{"items":{"$ref":"#/components/schemas/ScenarioWeekPoint"},"type":"array","title":"Weeks"},"pnl":{"$ref":"#/components/schemas/ScenarioPnl"},"covenants":{"items":{"$ref":"#/components/schemas/ScenarioCovenant"},"type":"array","title":"Covenants"},"trust":{"anyOf":[{"$ref":"#/components/schemas/ScenarioTrust"},{"type":"null"}]},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"}},"type":"object","required":["starting_cash_cents","ending_cash_cents","lowest_cash_cents","pnl"],"title":"ScenarioSummary","description":"Baseline or scenario: the cash curve, its low point and the P&L proxy."},"ScenarioTrust":{"properties":{"grade":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Grade"},"provisional":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Provisional"},"changed":{"type":"boolean","title":"Changed","default":false},"note":{"type":"string","title":"Note"}},"type":"object","required":["note"],"title":"ScenarioTrust"},"ScenarioWeekDelta":{"properties":{"week":{"type":"integer","title":"Week"},"start_date":{"type":"string","format":"date","title":"Start Date"},"baseline_ending_cash_cents":{"type":"integer","title":"Baseline Ending Cash Cents"},"scenario_ending_cash_cents":{"type":"integer","title":"Scenario Ending Cash Cents"},"delta_cents":{"type":"integer","title":"Delta Cents"}},"type":"object","required":["week","start_date","baseline_ending_cash_cents","scenario_ending_cash_cents","delta_cents"],"title":"ScenarioWeekDelta"},"ScenarioWeekPoint":{"properties":{"week":{"type":"integer","title":"Week"},"start_date":{"type":"string","format":"date","title":"Start Date"},"ending_cash_cents":{"type":"integer","title":"Ending Cash Cents"}},"type":"object","required":["week","start_date","ending_cash_cents"],"title":"ScenarioWeekPoint"},"SuccessEnvelope_ScenarioForkResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/ScenarioForkResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[ScenarioForkResponse]"},"TakeCreditLine":{"properties":{"type":{"type":"string","const":"take_credit_line","title":"Type"},"amount_cents":{"type":"integer","exclusiveMinimum":0.0,"title":"Amount Cents"},"term_days":{"type":"integer","maximum":3650.0,"minimum":1.0,"title":"Term Days"},"rate_bps":{"type":"integer","maximum":100000.0,"minimum":0.0,"title":"Rate Bps","description":"Annual rate, basis points."},"fee_bps":{"type":"integer","maximum":10000.0,"minimum":0.0,"title":"Fee Bps","description":"Draw fee, bps.","default":0}},"additionalProperties":false,"type":"object","required":["type","amount_cents","term_days","rate_bps"],"title":"TakeCreditLine","description":"Borrow: the amount less the fee lands in week 1; principal plus simple\ninterest is repaid at the end of the term."},"VendorCostChange":{"properties":{"type":{"type":"string","const":"vendor_cost_change_pct","title":"Type"},"pct":{"type":"number","maximum":1000.0,"minimum":-100.0,"title":"Pct"},"start_week":{"type":"integer","maximum":26.0,"minimum":1.0,"title":"Start Week","default":1}},"additionalProperties":false,"type":"object","required":["type","pct"],"title":"VendorCostChange","description":"Move what vendors charge: scales AP bills and open purchase orders."},"ErrorResponse":{"title":"ErrorResponse","type":"object","description":"Envelope returned by every non-2xx response. Branch on `code` (stable) rather than `message` (human-readable, may change).","required":["error","message","code"],"properties":{"error":{"type":"string","description":"Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`."},"message":{"type":"string","description":"Human-readable explanation, safe to show to end users."},"code":{"type":"string","description":"Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`)."},"request_id":{"type":"string","description":"Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied."},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"Field-level validation messages keyed by field name. Present on 400/422 validation failures only."}}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}