FlowMock

Sessions

Read, set, and tear down per-session mock state — idempotent by design.

On this page

Sessions are the heart of the Public API. Set up a test state before your app runs, read it back, clean up when done.

Query parameters

Most session endpoints need:

ParamRequiredNotes
projectOrg-wide keys: yesProject slug
environmentMulti-endpoint: yesProxy endpoint slug

PUT also accepts project and environment in the JSON body.

GET /sessions/:sessionKey

Read current session state.

bash
curl "$BASE/sessions/ci-42?project=checkout&environment=staging" \
  -H "Authorization: Bearer $KEY"

Response (200):

json
{
  "project": "checkout",
  "environment": "staging",
  "sessionKey": "ci-42",
  "label": "CI run 4821",
  "scenario": "scn_paymentDeclined",
  "overrides": ["ovr_extraMock"],
  "globalDelayMs": 0,
  "globalDelayMaxMs": 0,
  "lastSeenAt": "2026-06-23T12:00:00.000Z"
}

404 not_found if the session doesn't exist yet. Use PUT to create it.

PUT /sessions/:sessionKey

Declarative, idempotent set-state. Creates the session if missing. Takes effect on the proxy immediately.

bash
curl -X PUT "$BASE/sessions/ci-42" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "checkout",
    "environment": "staging",
    "scenario": "scn_paymentDeclined",
    "overrides": ["ovr_extraMock"],
    "globalDelayMs": 0,
    "globalDelayMaxMs": 0,
    "label": "CI run 4821"
  }'

Body fields

FieldTypeNotes
projectstring?Max 64 chars
environmentstring?Max 64 chars
scenariostring | null?Scenario id, or null to clear
overridesstring[]?Exact desired set of published, non-scenario mocks
globalDelayMsint 0–120000 | null?Fixed delay for all responses
globalDelayMaxMsint 0–120000 | null?Random delay up to this max
labelstring | null?Human note, max 200 chars

Omitted fields are left unchanged. When overrides is provided, activations not in the list are removed — including ones set manually in the dashboard.

Returns the same shape as GET.

DELETE /sessions/:sessionKey

bash
curl -X DELETE "$BASE/sessions/ci-42?project=checkout&environment=staging&mode=delete" \
  -H "Authorization: Bearer $KEY"
ModeBehavior
reset (default)Clear state, keep the session
deleteRemove the session entirely

Response:

json
{ "ok": true, "mode": "delete" }

Invalid mode → 422 invalid_mode.

Product context

Your app must send x-flowmock-session: ci-42 on proxied requests. See QA sessions for the full picture.