--- title: "seed a load scenario from an OpenAPI specification" method: PUT path: "/mockserver/loadScenario/generateFromOpenAPI" tags: ["loadgen"] --- # seed a load scenario from an OpenAPI specification `PUT /mockserver/loadScenario/generateFromOpenAPI` ## Request - Base URL: `http://localhost:1080` - URL: `http://localhost:1080/mockserver/loadScenario/generateFromOpenAPI` - Auth: none declared Generates an editable load scenario from an OpenAPI spec and loads (registers) it into the registry under "name" in the LOADED state — exactly like PUT /mockserver/loadScenario, it generates no traffic and is allowed even when loadGenerationEnabled is false. One step is produced per OpenAPI operation (in a stable path-then-method order), each with the operation's method and server-prefixed path, a representative request-body example, and a Content-Type header. The spec is accepted identically to PUT /mockserver/openapi/expectation — an inline JSON/YAML payload, a URL, or a file/classpath reference. Target precedence for where each request is sent (carried as the request's Host header and secure flag): an explicit "target" wins, else the spec's servers[0] URL, else the request is left path-only for the operator to edit. When no "profile" is supplied a conservative default is applied (one short constant-VU stage) so the scenario is immediately runnable yet safe — the operator edits it before scaling up. The generated scenario is returned so a client/UI can show and edit it before triggering a run. ## Request body - object - `name` string, required: the generated scenario name (the unique registry key) - `specUrlOrPayload` string, required: the OpenAPI spec as an inline JSON/YAML payload, a URL, or a file/classpath reference - `target` object: explicit network target for every generated step (overrides the spec's servers[0]) - `host` string - `port` integer - `scheme` 'http' | 'https' - `profile` LoadProfile: describes the load over time, as EITHER an ordered list of 'stages' OR a single named 'shape' (which expands into stages). Set one, not both; if both are set the explicit stages win. - `stages` LoadStage[]: ordered stages run one after another (max 20). Each holds or ramps virtual users (VU, closed model) or an arrival rate (RATE, open model), or pauses (PAUSE). - `type` 'VU' | 'RATE' | 'PAUSE', required: VU = closed model (hold/ramp concurrent virtual users); RATE = open model (hold/ramp an arrival rate in iterations/second); PAUSE = drive no load. - `durationMillis` integer, required: how long this stage runs in milliseconds (> 0); the sum across all stages is the total run length (max 3600000 = 1h) - `curve` 'LINEAR' | 'EXPONENTIAL' | 'QUADRATIC': interpolation curve used to ramp a value across a stage: LINEAR (constant slope), QUADRATIC (ease-in), EXPONENTIAL (steeper ease-in). Only meaningful for ramp stages; ignored for holds and pauses. - `vus` integer: VU hold: the number of virtual users to hold for the stage (max 50) - `startVus` integer: VU ramp: virtual users at the start of the ramp - `endVus` integer: VU ramp: virtual users at the end of the ramp (max 50) - `rate` number: RATE hold: arrival rate to hold, in iterations per second (max 5000) - `startRate` number: RATE ramp: arrival rate at the start of the ramp, in iterations per second - `endRate` number: RATE ramp: arrival rate at the end of the ramp, in iterations per second (max 5000) - `maxVus` integer: RATE stage only: optional cap on the auto-scaling virtual-user pool that runs the started iterations (defaults to the global virtual-user cap) - `shape` LoadShape: a declarative named load shape that expands into ordinary stages; only the parameters its 'type' needs are read, the rest are ignored. Use a shape OR an explicit 'stages' list, not both. - `type` 'SPIKE' | 'STAIRS' | 'RAMP_HOLD', required: named load shape: SPIKE (ramp up, hold the peak, ramp back down, optional recovery hold); STAIRS (a flight of pure-hold steps, each one 'step' higher); RAMP_HOLD (ramp 0 to target then hold). - `metric` 'VU' | 'RATE': what the shape drives: VU = concurrent virtual users (closed model); RATE = arrival rate in iterations/second (open model). A shape expands into ordinary LoadStage stages of this type. - `curve` 'LINEAR' | 'EXPONENTIAL' | 'QUADRATIC': interpolation curve used to ramp a value across a stage: LINEAR (constant slope), QUADRATIC (ease-in), EXPONENTIAL (steeper ease-in). Only meaningful for ramp stages; ignored for holds and pauses. - `baseline` number: SPIKE: the level held before and after the spike - `peak` number: SPIKE: the level held at the top of the spike - `rampUpMillis` integer: SPIKE: duration of the baseline to peak ramp - `holdMillis` integer: SPIKE: duration to hold at the peak; RAMP_HOLD: duration to hold at the target - `rampDownMillis` integer: SPIKE: duration of the peak to baseline ramp - `recoveryHoldMillis` integer: SPIKE (optional): duration to hold at baseline after the down ramp - `start` number: STAIRS: the level of the first step - `step` number: STAIRS: how much each step rises above the previous one - `steps` integer: STAIRS: the number of steps - `stepDurationMillis` integer: STAIRS: how long each step holds at its level - `target` number: RAMP_HOLD: the level ramped up to (from 0) and then held - `rampMillis` integer: RAMP_HOLD: duration of the 0 to target ramp ## Response `200` load scenario generated and loaded (registered) - object - `status` 'loaded' - `name` string - `state` 'LOADED' | 'PENDING' | 'RUNNING' | 'COMPLETED' | 'STOPPED' - `scenario` LoadScenario: an API-driven load scenario: ordered templated steps driven at a target concurrency. The name is the unique registry key — PUT loads (registers) it; PUT /loadScenario/start triggers it to run. - `name` string, required: scenario name — the unique registry key. Loading the same name replaces the prior definition. - `templateType` 'VELOCITY' | 'MUSTACHE': template engine used to render the per-iteration request path and body; only VELOCITY and MUSTACHE are supported for load steps (JAVASCRIPT is rejected) - `maxRequests` integer: optional hard cap on the total number of requests dispatched - `startDelayMillis` integer: delay in milliseconds, applied after this scenario is triggered to start, before its iterations begin. A positive value means the scenario is PENDING until the delay elapses, then RUNNING; 0 (default) starts immediately on trigger. Lets several triggered scenarios begin at staggered offsets. - `labels` object: optional scenario-level custom annotation labels; exported as OpenTelemetry attributes on every load measurement and (for keys named in the loadGenerationMetricLabels allowlist) as extra Prometheus labels - `thresholds` LoadThreshold[]: optional in-run pass/fail thresholds; the run carries a PASS verdict iff all hold, FAIL otherwise. Empty/omitted means no verdict is computed. - `metric` 'LATENCY_P50' | 'LATENCY_P95' | 'LATENCY_P99' | 'LATENCY_P999' | 'ERROR_RATE' | 'THROUGHPUT_RPS' | 'CHECK_FAILURE_RATE', required: the per-run metric to evaluate: latency percentiles in milliseconds, ERROR_RATE as a 0.0-1.0 fraction, THROUGHPUT_RPS as requests/second over the run's elapsed time, CHECK_FAILURE_RATE as failed per-step checks as a 0.0-1.0 fraction of all evaluated checks (0 when no checks ran) - `comparator` 'LESS_THAN' | 'LESS_THAN_OR_EQUAL' | 'GREATER_THAN' | 'GREATER_THAN_OR_EQUAL', required: how the observed per-run value is compared to the threshold - `threshold` number, required: the threshold value (milliseconds for latency metrics, a 0.0-1.0 fraction for ERROR_RATE or CHECK_FAILURE_RATE, requests/second for THROUGHPUT_RPS) - `abortOnFail` boolean: when true, a FAIL verdict aborts the run early (terminal STOPPED state, abortedByThreshold set); default false (the run always finishes its stages and carries a final verdict) - `abortGraceMillis` integer: suppress abortOnFail for the first N milliseconds of the run so noisy startup samples cannot trigger a premature abort (thresholds are still evaluated and a verdict still reported during the grace window — only the abort action is deferred) - `pacing` LoadPacing: adaptive iteration pacing (think-time) for a load scenario: a target per-virtual-user iteration cycle time. After a closed-model VU finishes one pass through the steps, the orchestrator waits whatever remains of the target cycle before launching that VU's next iteration; on overrun the next iteration starts immediately (no wait). Applies only to the closed-model VU loop — open-model RATE iterations ignore it, their arrival rate already governing spacing — and composes with per-step thinkTime. In-flight latency measurement is unchanged; pacing only affects when the next iteration launches. - `mode` 'NONE' | 'CONSTANT_PACING' | 'CONSTANT_THROUGHPUT', required: how the target iteration cycle is derived from value: NONE = no pacing (immediate reschedule); CONSTANT_PACING = value is the target cycle in milliseconds; CONSTANT_THROUGHPUT = value is the target iterations/second per VU (cycle = 1000 / value ms) - `value` number, required: for CONSTANT_PACING the target cycle in milliseconds; for CONSTANT_THROUGHPUT the target iterations/second per VU. Must be > 0 when mode is not NONE; ignored when mode is NONE. - `feeder` LoadFeeder: parameterized test data (a data feeder) for a load scenario: an inline dataset from which one row is selected per iteration and exposed to that iteration's templated request path, body and headers as $iteration.data. (Velocity) / {{iteration.data.}} (Mustache). The dataset is always inline (no external URL or file source). Supply EITHER rows (inline list of objects, the primary form) OR data + format (raw CSV/JSON parsed server-side); when both are given rows wins. - `rows` object[]: inline dataset: a list of column-name to value maps, one per row (the primary mechanism; round-trips with no parsing). Must be non-empty when used. - `data` string: optional raw inline dataset parsed server-side into rows per format. CSV: first line is the header row (RFC 4180-ish — embedded commas, doubled quotes and newlines are handled). JSON: an array of flat objects. The raw text is preserved verbatim on round-trip (the derived rows are not re-serialized). Ignored when rows is set. - `format` 'CSV' | 'JSON': the format of data (required when data is set) - `strategy` 'CIRCULAR' | 'RANDOM' | 'SEQUENTIAL': how a row is chosen each iteration: CIRCULAR (default) cycles rows[globalIteration % size] and never exhausts; RANDOM picks a uniformly random row each iteration; SEQUENTIAL uses rows[globalIteration] once each in order and COMPLETES the run once the dataset is exhausted (data-driven replay-once). - `profile` LoadProfile, required: describes the load over time, as EITHER an ordered list of 'stages' OR a single named 'shape' (which expands into stages). Set one, not both; if both are set the explicit stages win. - `stages` LoadStage[]: ordered stages run one after another (max 20). Each holds or ramps virtual users (VU, closed model) or an arrival rate (RATE, open model), or pauses (PAUSE). - `type` 'VU' | 'RATE' | 'PAUSE', required: VU = closed model (hold/ramp concurrent virtual users); RATE = open model (hold/ramp an arrival rate in iterations/second); PAUSE = drive no load. - `durationMillis` integer, required: how long this stage runs in milliseconds (> 0); the sum across all stages is the total run length (max 3600000 = 1h) - `curve` 'LINEAR' | 'EXPONENTIAL' | 'QUADRATIC': interpolation curve used to ramp a value across a stage: LINEAR (constant slope), QUADRATIC (ease-in), EXPONENTIAL (steeper ease-in). Only meaningful for ramp stages; ignored for holds and pauses. - `vus` integer: VU hold: the number of virtual users to hold for the stage (max 50) - `startVus` integer: VU ramp: virtual users at the start of the ramp - `endVus` integer: VU ramp: virtual users at the end of the ramp (max 50) - `rate` number: RATE hold: arrival rate to hold, in iterations per second (max 5000) - `startRate` number: RATE ramp: arrival rate at the start of the ramp, in iterations per second - `endRate` number: RATE ramp: arrival rate at the end of the ramp, in iterations per second (max 5000) - `maxVus` integer: RATE stage only: optional cap on the auto-scaling virtual-user pool that runs the started iterations (defaults to the global virtual-user cap) - `shape` LoadShape: a declarative named load shape that expands into ordinary stages; only the parameters its 'type' needs are read, the rest are ignored. Use a shape OR an explicit 'stages' list, not both. - `type` 'SPIKE' | 'STAIRS' | 'RAMP_HOLD', required: named load shape: SPIKE (ramp up, hold the peak, ramp back down, optional recovery hold); STAIRS (a flight of pure-hold steps, each one 'step' higher); RAMP_HOLD (ramp 0 to target then hold). - `metric` 'VU' | 'RATE': what the shape drives: VU = concurrent virtual users (closed model); RATE = arrival rate in iterations/second (open model). A shape expands into ordinary LoadStage stages of this type. - `curve` 'LINEAR' | 'EXPONENTIAL' | 'QUADRATIC': interpolation curve used to ramp a value across a stage: LINEAR (constant slope), QUADRATIC (ease-in), EXPONENTIAL (steeper ease-in). Only meaningful for ramp stages; ignored for holds and pauses. - `baseline` number: SPIKE: the level held before and after the spike - `peak` number: SPIKE: the level held at the top of the spike - `rampUpMillis` integer: SPIKE: duration of the baseline to peak ramp - `holdMillis` integer: SPIKE: duration to hold at the peak; RAMP_HOLD: duration to hold at the target - `rampDownMillis` integer: SPIKE: duration of the peak to baseline ramp - `recoveryHoldMillis` integer: SPIKE (optional): duration to hold at baseline after the down ramp - `start` number: STAIRS: the level of the first step - `step` number: STAIRS: how much each step rises above the previous one - `steps` integer: STAIRS: the number of steps - `stepDurationMillis` integer: STAIRS: how long each step holds at its level - `target` number: RAMP_HOLD: the level ramped up to (from 0) and then held - `rampMillis` integer: RAMP_HOLD: duration of the 0 to target ramp - `stepSelection` 'SEQUENTIAL' | 'WEIGHTED': how each iteration selects which steps to run: SEQUENTIAL (default) runs ALL steps in declared order (a multi-step user journey); WEIGHTED runs exactly ONE step per iteration chosen at random proportional to each step's weight (mixed-workload modelling, e.g. 70% browse / 20% search / 10% checkout). Cross-step captures are meaningful only under SEQUENTIAL (a WEIGHTED iteration runs a single step); feeder data and pacing apply to both. - `steps` LoadStep[], required: ordered list of request steps. Under SEQUENTIAL stepSelection (default) all steps are fired in sequence each iteration; under WEIGHTED one step is chosen per iteration by weight (max 50) - `request` HttpRequest, required: request properties matcher - `secure` boolean - `keepAlive` boolean - `method` union: string value that can be support nottable, optional or a json schema - string - object - `not` boolean - `optional` boolean - `value` string - `schema` Schema (unresolved $ref) - `parameterStyle` 'SIMPLE' | 'SIMPLE_EXPLODED' | 'LABEL' | 'LABEL_EXPLODED' | 'MATRIX' | 'MATRIX_EXPLODED' | 'FORM_EXPLODED' | 'FORM' | 'SPACE_DELIMITED_EXPLODED' | 'SPACE_DELIMITED' | 'PIPE_DELIMITED_EXPLODED' | 'PIPE_DELIMITED' | 'DEEP_OBJECT' - `path` union: string value that can be support nottable, optional or a json schema - string - object - `not` boolean - `optional` boolean - `value` string - `schema` Schema (unresolved $ref) - `parameterStyle` 'SIMPLE' | 'SIMPLE_EXPLODED' | 'LABEL' | 'LABEL_EXPLODED' | 'MATRIX' | 'MATRIX_EXPLODED' | 'FORM_EXPLODED' | 'FORM' | 'SPACE_DELIMITED_EXPLODED' | 'SPACE_DELIMITED' | 'PIPE_DELIMITED_EXPLODED' | 'PIPE_DELIMITED' | 'DEEP_OBJECT' - `pathParameters` union - object[] - `name` string - `values` string[] - object - `keyMatchStyle` 'MATCHING_KEY' | 'SUB_SET' - `queryStringParameters` union - object[] - `name` string - `values` string[] - object - `keyMatchStyle` 'MATCHING_KEY' | 'SUB_SET' - `body` union: request body matcher - object: binary body matcher - `not` boolean - `type` 'BINARY' - `base64Bytes` string - `contentType` string - object: json body matcher - `not` boolean - `type` 'JSON' - `json` string - `contentType` string - `matchType` 'STRICT' | 'ONLY_MATCHING_FIELDS' - `matchNumbersAsStrings` boolean - object: json matching fields body matcher - object: json schema body matcher - `not` boolean - `type` 'JSON_SCHEMA' - `jsonSchema` Schema (unresolved $ref) - object: JSON path body matcher - `not` boolean - `type` 'JSON_PATH' - `jsonPath` string - object: parameter body matcher - `not` boolean - `type` 'PARAMETERS' - `parameters` union - … - object: regex body matcher - `not` boolean - `type` 'REGEX' - `regex` string - object: string body matcher - `not` boolean - `type` 'STRING' - `string` string - `contentType` string - `subString` boolean - string: substring body matcher - object: xml body matcher - `not` boolean - `type` 'XML' - `xml` string - `contentType` string - object: xml schema body matcher - `not` boolean - `type` 'XML_SCHEMA' - `xmlSchema` string - object: xpath body matcher - `not` boolean - `type` 'XPATH' - `xpath` string - object: all-of body matcher — matches only when every one of its component body matchers matches the same request body - `not` boolean - `optional` boolean - `type` 'ALL_OF' - `bodyAllOf` Body[], required - object: binary body matcher - `not` boolean - `optional` boolean - `type` 'BINARY' - `base64Bytes` string - `contentType` string - object: json body matcher - `not` boolean - `optional` boolean - `type` 'JSON' - `json` string - `contentType` string - `matchType` 'STRICT' | 'ONLY_MATCHING_FIELDS' - `matchNumbersAsStrings` boolean - object: json schema body matcher - `not` boolean - `optional` boolean - `type` 'JSON_SCHEMA' - `jsonSchema` Schema (unresolved $ref) - object: JSON path body matcher - `not` boolean - `optional` boolean - `type` 'JSON_PATH' - `jsonPath` string - object: parameter body matcher - `not` boolean - `optional` boolean - `type` 'PARAMETERS' - `parameters` union - … - object: multipart form-data body matcher - `not` boolean - `optional` boolean - `type` 'MULTIPART' - `fields` union - … - `filenames` union - … - `partContentTypes` union - … - object: regex body matcher - `not` boolean - `optional` boolean - `type` 'REGEX' - `regex` string - object: string body matcher - `not` boolean - `optional` boolean - `type` 'STRING' - `string` string - `contentType` string - `subString` boolean - object: xml body matcher - `not` boolean - `optional` boolean - `type` 'XML' - `xml` string - `contentType` string - object: xml schema body matcher - `not` boolean - `optional` boolean - `type` 'XML_SCHEMA' - `xmlSchema` string - object: xpath body matcher - `not` boolean - `optional` boolean - `type` 'XPATH' - `xpath` string - object: JSON-RPC body matcher - `not` boolean - `optional` boolean - `type` 'JSON_RPC' - `method` string - `paramsSchema` string - object: GraphQL body matcher - `not` boolean - `optional` boolean - `type` 'GRAPHQL', required - `query` string, required - `operationName` string - `variablesSchema` string - `headers` union - object[] - `name` string - `values` string[] - object - `keyMatchStyle` 'MATCHING_KEY' | 'SUB_SET' - `cookies` union - object[] - `name` string - `value` string - object - `socketAddress` SocketAddress: remote address to send request to, only used for request overrides - `host` string - `port` integer - `scheme` 'HTTP' | 'HTTPS' - `protocol` 'HTTP_1_1' | 'HTTP_2' | 'HTTP_3': protocol matcher - `jwt` Jwt: JSON Web Token (JWT) request matcher — decodes the token carried in a request header (no signature verification) and matches its claims - `header` string: name of the request header carrying the JWT (default 'authorization') - `scheme` string: authentication scheme prefix stripped from the header value before decoding (default 'Bearer') - `claims` object: claim-value criteria; each value may be an exact string, regex or '!'-negated form - `issuer` union: string value that can be support nottable, optional or a json schema - string - object - … - `audience` union: string value that can be support nottable, optional or a json schema - string - object - … - `algorithm` union: string value that can be support nottable, optional or a json schema - string - object - … - `not` boolean - `respondBeforeBody` boolean: If true, MockServer responds to a matching request before consuming its body and may close the connection. Required: the matcher must not specify a body matcher, and the action must be RESPONSE or ERROR. - `thinkTime` object: optional inter-step pause (a Delay) - `timeUnit` string - `value` integer - `name` string: optional human label for this step; used as the 'step' metric label (otherwise the step index is used) and may be used as the low-cardinality 'route' metric label in place of the templatised request path - `labels` object: optional step-level custom annotation labels, merged over the scenario labels (step keys win); exported as OpenTelemetry attributes on every load measurement and as allowlisted Prometheus labels - `captures` LoadCapture[]: optional cross-step capture rules applied to this step's response. Each binds an extracted value to a variable name visible to SUBSEQUENT steps in the same iteration via $iteration.captured. (Velocity) / {{iteration.captured.}} (Mustache), in path, body and header templates. Scope is per-iteration (one virtual user's single pass through the steps). - `name` string, required: the variable name later steps reference (e.g. 'token' for $iteration.captured.token) - `source` 'BODY_JSONPATH' | 'HEADER' | 'BODY_REGEX', required: where to extract from: a JSONPath over the response body, a response header value, or a regex over the response body string - `expression` string, required: the JSONPath (BODY_JSONPATH), header name (HEADER), or regex (BODY_REGEX, capture group 1) driving the extraction - `defaultValue` string: optional fallback value bound to the variable when extraction yields nothing; when omitted the variable is left unset on no match - `checks` LoadCheck[]: optional per-step response assertions (k6 'check' parity). Each check extracts a value from this step's response and compares it against an expected value; pass/fail outcomes feed the mock_server_load_checks metric, the end-of-run report and the CHECK_FAILURE_RATE threshold. Observational — a failing check never fails an individual request or stops dispatch. Omitted (the default) leaves behaviour unchanged. - `source` 'STATUS' | 'HEADER' | 'BODY_JSONPATH', required: where to read the observed value from: the response status code, a response header (headerName), or a JSONPath over the response body (jsonPath) - `headerName` string: the response header name to read (required when source is HEADER) - `jsonPath` string: the JSONPath to evaluate over the response body (required when source is BODY_JSONPATH) - `comparator` 'EQUALS' | 'NOT_EQUALS' | 'CONTAINS' | 'MATCHES' | 'GT' | 'LT' | 'GTE' | 'LTE', required: how the observed value is compared to value: string comparators (EQUALS/NOT_EQUALS/CONTAINS/MATCHES — MATCHES is a full-match regex) operate on the raw string; numeric comparators (GT/LT/GTE/LTE) parse both sides as numbers and fail the check when either side is not a number - `value` string: the expected value / comparand the observed value is compared against - `weight` number: relative selection weight, used only when the scenario's stepSelection is WEIGHTED: each iteration runs exactly ONE step chosen at random with probability proportional to its weight (e.g. weights 7 / 2 / 1 model a 70% / 20% / 10% mixed workload). Omitted means 1.0 in WEIGHTED mode; must be > 0 when WEIGHTED. Ignored under the default SEQUENTIAL mode (all steps run in order). ## Other responses - `400`: missing name/spec, an unparseable spec, a spec with no operations, or a generated scenario that fails validation --- [API](https://skmtc.dev/mock-server/apis/mockserver-api.md) · [All operations](https://skmtc.dev/mock-server/apis/mockserver-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mock-server/apis/mockserver-api/revisions/9239b693996e?raw)