Appearance
Scenarios
Scenarios are sandboxed copies of your live workforce data. There are no REST endpoints for creating or managing scenarios. You manage them in the app, or through the MCP server. What the REST API does support, on every mounted endpoint, is querying and mutating inside a scenario with the scenarioId query parameter.
New to Flowstate?
Read Live data vs scenarios first. Scenarios are the foundation of every "what-if" workflow in Flowstate.
Querying with a scenario context
Every entity endpoint in the API accepts a scenarioId query parameter. Pass a scenario's ID and the endpoint returns the merged view: live data with that scenario's overlays applied.
bash
curl -X GET "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/employees?scenarioId=cls_abc123" \
-H "Authorization: Bearer private_..."Omit scenarioId to read live data.
Writes work the same way. To mutate inside a scenario, call the corresponding write endpoint with scenarioId set. For example, POST /employees?scenarioId=... creates the employee inside the scenario rather than as live data. Changes made inside a scenario do not touch live data until the scenario is reviewed and merged in the app.
You can find a scenario's ID in the app, or by calling the MCP list_scenarios tool.
Managing scenarios
| Task | Where |
|---|---|
| Create a scenario | The app, or the MCP create_scenario tool |
| List scenarios | The app, or the MCP list_scenarios tool |
| Edit scenario contents | REST write endpoints with ?scenarioId=, MCP write tools, or the app |
| Submit, approve, reject, merge | The app (Inbox and change review) |
The MCP server's write tools all operate on scenarios: you call create_scenario first, then pass the returned ID as planId on subsequent writes. Approval and merge are deliberately a human gate in the app. See MCP server for the full tool catalogue.
Where to go next
- Live data vs scenarios: the data model behind scenario overlays.
- Scenarios workflow: the conceptual lifecycle.
- Comparing scenarios: diffing two plans.
- MCP server: create and populate scenarios from an LLM client.