Scenarios
A scenario is a copy of the plan where changes are modelled before they’re merged into live data. Background: Live data and scenarios.
REST reads and writes live data. The one exception is functional groups. To create, read or change a scenario from code, use the MCP server.
| Task | REST API | MCP server |
|---|---|---|
| Create or list scenarios | — | Yes |
| Read or change people, teams, projects and allocations in a scenario | — | Yes |
| Read or change functional groups in a scenario | ?scenarioId= | Yes |
| Submit, approve or merge | — | — (in the app) |
scenarioId on other endpoints
Don’t send scenarioId to anything except /functional-groups. On employees, contractors, vacancies, teams and projects it is checked but not applied:
| Request | Result |
|---|---|
scenarioId isn’t one of your organisation’s scenarios | 404 NOT_FOUND |
GET with a valid scenarioId | Live data |
POST, PATCH, DELETE, or POST /vacancies/{id}/fill, with a valid scenarioId | 501 NOT_IMPLEMENTED; nothing written |
{
"error": {
"code": "NOT_IMPLEMENTED",
"message": "Scenario mode is not yet supported for create operations"
}
}Functional groups
Every /functional-groups read and write takes ?scenarioId= and acts on that scenario. Omit it, or pass main, for live data.
The key needs its usual functional group permissions, and the key’s creator must be able to use the scenario:
| Requirement | Otherwise | |
|---|---|---|
| Read | The creator’s role has Use Scenario Plans, and the scenario is open or was created by or assigned to the creator. | 403 FORBIDDEN |
| Write | Also Edit Scenario Plans. The scenario is in Draft, and any budget proposal it belongs to is still open for editing. | 403 PLAN_NOT_EDITABLE |
| Any | The scenario belongs to the key’s organisation. | 403 FORBIDDEN |