Route Behavior
Scenarios
Frontend development often needs the same endpoint to answer differently on demand -- an empty list to check the empty state, a 500 to check the error banner, a slow response to check the loading spinner -- without editing the mock every time. A scenario is a name you switch a mock to, and a route only answers while its own scenario condition matches.
How it works
There is no separate "scenario" system -- a scenario is a value like any other a route can match on, using the same conditional matching every other route condition uses. Give a route a match condition with source scenario, operator equals, and the scenario's name as the value, and that route only answers while that scenario is the active one. A route with no scenario condition is unaffected and keeps answering regardless.
That means the usual pattern is several routes at the same method and path, each gated on a different scenario, plus one route with no conditions as the fallback:
{
"routes": [
{ "method": "GET", "path": "/orders", "status_code": 500,
"match_conditions": [{ "source": "scenario", "operator": "equals", "value": "error" }] },
{ "method": "GET", "path": "/orders", "status_code": 200, "response_body": { "orders": [] },
"match_conditions": [{ "source": "scenario", "operator": "equals", "value": "empty" }] },
{ "method": "GET", "path": "/orders", "status_code": 200, "response_body": { "orders": [{ "id": 1 }] } }
]
}With no scenario active, the third route answers. Switch to "error" and the first one does instead -- nothing else about the mock changes.
Switching scenarios
Each mock has its own scenarios list -- names you've added, shown in the Scenario switcher next to the mock's Base URL -- and an active_scenario, which is the one currently selected there. Switching it there is what changes what an ordinary request from your frontend gets, with no header or query param needed, which is what makes it usable while developing against the mock in a real browser.
The scenarios list is a convenience for the switcher and for autocomplete on a route's condition value. A route's condition can reference any name, whether or not it's been added to the list.
Overriding it for one call
Sometimes you don't want to touch the mock's active scenario -- an automated test, for instance, shouldn't flip a setting every other concurrent test run might also be relying on. Send an X-Mock-Scenario header and it's used for that one request instead of the mock's own active_scenario, which is left untouched:
curl https://mockbase.org/mock/<mock_id>/orders -H "X-Mock-Scenario: empty"The Try It panel has its own "Scenario for this call" selector that does exactly this -- pick a scenario there to test it without changing what a plain request from your app gets.
Whichever scenario actually applied -- the header, or the mock's own default -- comes back on the response as the same X-Mock-Scenario header, so it's visible in the Request Inspector and in browser devtools.
Managing the list
Add or remove scenarios from the same switcher panel (click "Manage"). There's no rename -- add the new name, update any route conditions that used the old one, then remove it. Removing the scenario that's currently active puts the mock back to no active scenario, in the same save -- it's never left pointing at a name that no longer exists.
Mock as code
scenarios and active_scenario are ordinary fields on a mock's configuration, so they push and pull through the CLI and MCP server like everything else -- active_scenario is what a CI job would set before running a suite against a particular state, if it doesn't use the header override instead.