Skip to content

Vayu Engine API Reference

Base URL: http://127.0.0.1:9876 (default, configurable via --port)

All endpoints return JSON. Every response also carries Cache-Control: no-store (#1507) - see Listeners for why. Every error response has one shape - an error object carrying a machine-readable code and a human-readable message:

{
  "error": {
    "code": "bad_request",
    "message": "Missing required field: name"
  }
}

code is per-status unless the route names a more specific one: bad_request (400), unauthorized (401), forbidden (403), not_found (404), conflict (409), bad_gateway (502), unavailable (503), insufficient_storage (507), internal_error (any other 5xx). Routes with their own vocabulary pass it instead - invalid_config (POST /config), invalid_run_config (POST /runs), precondition_failed and invalid_if_match (the If-Match of a whole-record PUT or of POST /globals), and the oauth2_* family.

Any per-error detail sits inside the same object, so a client reads one place for the whole failure - item on POST /import/apply, the provider's reply on /oauth2/*:

{
  "error": {
    "code": "oauth2_provider_error",
    "message": "Token endpoint refused the request (HTTP 401): invalid_client",
    "providerStatus": 401,
    "providerError": "invalid_client"
  }
}

Most routes used to emit a flat {"error": "message"} instead, which the app's http-client could not read - every validation message surfaced as a bare HTTP 400 (issue #173). The client still accepts the flat shape so a newer app can read an older engine, but the engine no longer produces it.

Who may call the API

The engine serves no browser. No response carries a CORS header, and the request gate in server.cpp refuses, before any route runs, for every route:

  • a request whose Host is not exactly 127.0.0.1:<port>, localhost:<port> or [::1]:<port> (the port this engine bound) - 403, message naming the Host check. This is what defeats DNS rebinding, where a page reaches the listener under a name it controls and is same-origin with it;
  • any request carrying an Origin header, whatever its value (null included) - 403, message saying the engine does not serve browser origins.

A request cpp-httplib refuses to parse never reaches that gate: an HTTP/1.1 request with no Host, any request with more than one, or a Host holding a byte outside uri-host [ ":" port ] (RFC 9112 §3.2) is answered 400 with an empty body and the connection closed. An HTTP/1.0 request with no Host still reaches the gate, and is refused there with the 403 above.

An OPTIONS request that passes the Host check is answered 204 with no body and no CORS header, whatever its Origin: a preflight that grants nothing leaks nothing. Local tools (the CLI, curl, the MCP server's fetch) send no Origin and are unaffected. The Electron shell is the one browser-context client: it strips Origin from the renderer's requests and supplies the CORS response headers the renderer needs itself (app/electron/engine-origin.ts).

What a browser page can still send is a request with no Origin: a scriptless GET (<img>, <script>, <link>, a no-cors fetch, a top-level navigation) to the loopback name it dialled. That passes the gate and reaches a GET route. It is harmless because two things hold together: the response is opaque to the page (no CORS header, and the browser's CORB/ORB keeps a JSON body out of a <script>), and no GET route has a side effect. A page can therefore neither read the engine nor change it, though it can make the engine run any GET handler.

Writes to file trust need one more thing: the grant secret. Host and Origin decide who reaches the API at all; they cannot tell the Vayu app from any other local caller (a script, the CLI, the MCP server, another process). What a request body may send from disk is decided by the allowed folders and the picked files, so the four routes that change those - POST/DELETE /file-roots and POST/DELETE /file-grants - also require the header X-Vayu-Grant-Secret to carry the engine's per-start secret, and answer 403 with code grant_secret_required otherwise:

  • The app's main process generates the secret and passes it in the engine's environment as VAYU_GRANT_SECRET. The engine reads it once at start, before any thread exists, and removes it from its own environment, so nothing it later reads or starts sees it. On Linux and macOS it also overwrites the bytes the kernel passed (what /proc/<pid>/environ shows on Linux), which unsetenv alone leaves readable; on Windows the environment block is private to the process. A value shorter than 32 characters is ignored with a warning that does not print it.
  • The header is compared in constant time (both sides hashed with SHA-256, the digests compared with sodium_memcmp). A missing header, an empty one and a wrong one are the same 403. The secret is never logged (the request log records method, path, status, time and size, never a header) and no response carries it, a refusal included.
  • An engine started without a secret refuses all four writes, whatever the header says. That is every engine the app did not start: vayu-engine run by hand, or one the CLI or a CI job starts. Folders allowed and files picked before then still apply to every send, and GET /file-roots and GET /file-grants answer as usual.

The engine's own outbound client sends exactly what this gate admits, a loopback Host and no Origin, so the engine never sends a request to its own port or the MCP server's - not from a script, a redirect or a name that resolves to loopback. See Reserved local ports.

Request bodies

Every request body is judged from its headers, on the same pre-routing handler as the gate above, before any route runs and before a byte of the body is read (issue #1824):

  • A body sent with Transfer-Encoding: chunked answers 411 Refused: the engine reads a request body only when its length is declared up front - send Content-Length, not Transfer-Encoding: chunked, on every route. A chunked body's size is known only once it has been read, and cpp-httplib's read bound is fixed for the listener's life, so it could not follow a body-size setting changed while the engine runs. The app, vayu-cli and the MCP server all send Content-Length.
  • A Content-Length over 151 MiB (158334976 bytes) answers 413 Request body is N bytes, over the limit of M the engine reads for any request, on every route. The ceiling is fixed and derived from the largest values the two body-size settings accept: maxSpecDocumentBytes at its 100 MiB maximum under the import rule below, which also covers maxScenarioDataBytes at its own 100 MiB maximum. Raising either setting never meets this ceiling first.
  • POST /import, /import/parse and /import/document carry a whole document and are held to a tighter bound that follows the live maxSpecDocumentBytes, checked first because its message names the setting; see the body cap under POST /import/parse.

Both refusals are the shared error shape, with code error. Because the body is not read, the engine answers and closes the connection: a client that is still writing a large body may see the connection reset rather than the response.

Once read, every route that reads a JSON body holds it to a depth bound: one nested deeper than 128 levels answers 400 request body is nested deeper than 128 levels before the route reads a field, and text that does not parse answers 400 Invalid JSON: <parser message> (issues #2417, #2671). Both carry code bad_request unless the route has one of its own for a malformed body, which the depth refusal then shares: invalid_compose_request on POST /compose, oauth2_invalid_config on the /oauth2/* routes, mock_issuer_invalid_config on /mock-issuer, invalid_config on POST /config. POST /execute and POST /runs hold the same bound; see their sections. A route that accepts an empty body (POST /mock/start, POST /mock-issuer/start, the /inbox writes) reads it as no body at all rather than as a parse failure. The import routes are held to the same 128 levels: their documents travel as a string (content) or as flat lists linked by temp ids, so a legitimate body is far shallower. A document's own nesting is bounded separately, where the engine reads it.

The bound reads the body's own tree, so JSON carried inside a string field is not covered by it. The engine parses three such fields again and holds each to the same 128 levels itself (issue #2672): a request's postmanProtocolBehavior string (POST /requests), and a graphql or jsonrpc body's content (the graphql envelope, the jsonrpc envelope).

Removed route aliases

The execution and run/metrics routes were consolidated behind a /runs family, /execute, and /runs/:id/metrics (#83). The pre-consolidation paths served as deprecated aliases for a release cycle and are now gone; each answers 404.

Removed Use
POST /request POST /execute
POST /run POST /runs
GET /run/:id GET /runs/:id
DELETE /run/:id DELETE /runs/:id
POST /run/:id/stop POST /runs/:id/stop
GET /run/:id/report GET /runs/:id/report
GET /metrics/live/:id GET /runs/:id/live
GET /stats/:id?format=json GET /runs/:id/metrics
GET /stats/:id (SSE) GET /runs/:id/live while the run is retained, then GET /runs/:id/report

GET /runs with no query parameters no longer returns the pre-pagination bare array: it answers the {data, pagination} envelope at the default page size, the same as any other call (see GET /runs).

Resource writes: create vs update

Collections, requests and environments follow one write contract. /globals is a singleton and stays POST-only, so it is exempt from the verb split below - but not from the null-vs-absent rule, which it follows with every write treated as a create (see POST /globals).

Verb Path Meaning Wrong-target status
POST /<resource> Create only. 400 when the body carries an id
PUT /<resource>/:id Update only (merge-patch). 404 when the id does not exist

PUT is used loosely as a merge-patch rather than a whole-record replace: an omitted field keeps its stored value. We deliberately did not add a separate PATCH verb - merge-patch is what the update path has always done, and every client call site expects it. The :id in the path is the record's identity; the body carries the changed fields only.

An update is atomic against a concurrent one. The read the merge is computed from, the merge itself and the write are one acquisition of the database lock, so two clients patching one record at the same moment - the app's autosave and an MCP agent, say - each merge onto what the other committed rather than onto the row as both of them found it. The alternative is not a conflict but a silent loss: the merge carries every field the body did not name, so the loser's fields come back written with the values the winner read a moment earlier, and neither request fails. A client that computes its body from an earlier read (a read-merge-write across two round trips) closes its own window with If-Match.

Conditional updates with If-Match

The four whole-record PUTs - collections, requests, environments and examples - take an optional If-Match header (issue #2433), and so does the globals singleton's whole-blob save, POST /globals (#2988). A row's version is its updatedAt, and its entity tag is the weak W/"<updatedAt>".

  • Every 200 from those writes, and from GET /requests/:id and GET /globals, carries the row's ETag. The list reads (GET /collections, GET /environments, GET /requests/:id/examples) carry no per-row header; a client builds the tag from the row's updatedAt, which is the same value.
  • If-Match: W/"<updatedAt>" makes the write conditional: it lands only while the stored row is at that version. The check runs inside the same lock acquisition as the read and the merge, after the 404, so the row it judges is the row the write replaces.
  • A mismatch is 412 with code precondition_failed, and nothing is written. The stored updatedAt rides inside the error, so the caller can re-read, merge again and retry under the new tag:
{"error": {"code": "precondition_failed", "message": "The record changed after it was read; read it again and re-apply the change", "updatedAt": 1792359304908}}
  • If-Match: * holds for any stored row (a missing one is still 404). A comma-separated list holds when any member names the version, and repeated If-Match lines are read as one list. The comparison is weak: W/ is ignored on both sides, where RFC 9110 asks for the strong comparison, which no weak tag passes. Every tag the engine issues is weak because a row's answer carries members its updatedAt does not version (a request's derived file trust).
  • A value that is not * or entity tags (a bare 1792359304908, an empty value) is 400 invalid_if_match, before the row is looked up.
  • No If-Match is the unconditional write it always was. The app sends none: its autosave patches only the fields that changed (#1436), so its writes merge rather than collide.

An update through these routes always moves updatedAt forward, even within one millisecond, so two of them never share a tag. Other writers of these rows (a reorder, a spec sync, a run persisting script variables, an import's globals) stamp the current time. Activating an environment clears isActive on the one it replaces without restamping that row, so an environment's tag does not cover isActive.

Globals has no 404: an engine that never saved any answers the empty set at updatedAt: 0, and W/"0" is that version's tag. A first conditional save names it, and once anything is written it is stale like any other.

The engine owns every id

A create must not carry an id. The engine generates one via generate_id, giving the <prefix>_<uuidv4> form, and a body containing the field is a 400:

{"error": {"code": "bad_request", "message": "id is assigned by the engine; omit it (bulk import: POST /import/apply)"}}

Presence alone is rejected, null included - id is not a settable field with a default, so the null-vs-absent rule below does not reach it, and accepting {"id": null} would leave a caller believing the field is honoured. The field existed for the import orchestrator, which pre-assigned ids so it could wire parentId / collectionId across a whole tree before anything was persisted; import sends one POST /import/apply instead, referencing items by opaque tempId and reading the real ids back from idMap (issues #96, #97).

On PUT, the path is the identity. A body id matching it is accepted and ignored; one that disagrees - including null - is a 400 (message Body 'id' must match the id in the path ('col_1') or be omitted), because the payload otherwise names two different records and guessing between them is how a PUT to one id rewrites another. This is checked before the record is looked up, so a malformed body answers 400 whether or not the target exists.

Since no create can select an id, the pre-existing "id already exists" 409 - whose body names the update path, e.g. message Collection 'col_1' already exists; use PUT /collections/:id to update - is now reachable only on a generate_id collision, which 122 bits of entropy put out of reach. It stays as a guard: on that draw the alternative is overwriting a live record.

The null-vs-absent rule

One rule, identical for every field of all three resources:

Field absent Field explicitly null
Create (POST) use the default use the default
Update (PUT) keep the current value reset to the default

The defaults are {} for variables, the resource's own default for auth ({"mode":"none"} for a collection, {"mode":"inherit"} for a request), [] for params / headers, "" for description and the two script fields, {"mode":"none"} for a request body, true for followRedirects, 10 for maxRedirects, null for a request's timeout (the defaultTimeout setting, read at each send), and false for isActive.

order is the one default that is computed rather than constant: it means "append after the current siblings", on both resources and on both verbs - see Ordering below.

A request's httpVersion is the one field whose default is not fixed: absent or null seeds it from the live defaultHttpVersion config entry ("auto" unless changed), read fresh on every write rather than cached - see POST /requests. Unlike every other field above, an unrecognized httpVersion value is rejected with a 400 rather than silently coerced, because a typo'd protocol silently running as HTTP/1.1 is the worst available outcome.

A field that has no default cannot be reset, so null is a 400 on either verb rather than a silently discarded write. Those fields are a collection's name, an environment's name, and a request's collectionId, name, method and url. Each is also required on create.

A storage failure is not a 400

A create or update whose request was fine but whose database write failed does not answer 400 (issue #2423), because a 4xx tells the caller to change the request and the app does not retry one. It is told apart by SQLite's own result code, and the body never quotes SQLite's text (the engine log does):

Cause Status code The caller should
The disk holding the data is full (SQLITE_FULL) 507 insufficient_storage free space, then repeat the call
The database stayed locked past the busy timeout (SQLITE_BUSY, SQLITE_LOCKED) 503 with Retry-After: 1 unavailable repeat the call
Any other SQLite failure (I/O error, read-only file, corruption) 500 internal_error read the engine log

An exception that is not SQLite's (a body that is not JSON, a field that fails validation) stays a 400. Every handler of a resource write answers through send_exception in routes.hpp; SendExceptionGuard fails the build on one that goes back to a bare 400.

A stored JSON field has a write-time cap

One rule, identical for every resource (issue #1485): a request's params / headers / body / auth, a collection's variables / auth / dataSchema / openapi / specFile / dataFile, and an environment's variables are each refused with a 413 when the serialized value is over the engine's field cap (10 MiB, json::MAX_FIELD_SIZE in engine/include/vayu/core/constants.hpp) - naming the field, its size and the cap, and leaving the stored row untouched. POST /import/apply enforces it too, through the same apply_*_field helpers every other write goes through.

A row written before this cap existed can still be oversized. GET /<resource>/:id always answers with the field whole, however large it is - this did not change. Only a request's list route, GET /requests?collectionId=, behaves differently: it has always substituted the field's documented default for a column too large to serve efficiently across a whole page, and now names which fields it substituted for that row in a truncatedFields array (e.g. ["body"]), omitted when nothing was. Neither GET /collections nor GET /environments substitutes or carries this field - see GET /requests.

Ordering

Collections and requests both carry an order column that fixes their position among their siblings. The siblings of a row are every child of its parent, of both kinds (#2535): a collection's sub-collections and its requests share one order space, so a request can sit between two folders.

Reading. GET /collections and GET /requests each sort by order ascending, then createdAt ascending, then id ascending. All three keys are load-bearing: order alone is not a total order (every request created before explicit orders existed sits at 0), and rows are stored with INSERT OR REPLACE on a TEXT primary key, which hands the row a new rowid on every edit - so without an explicit tiebreak, renaming a request silently moved it among its ties.

A client that lists a parent's children merges the two lists by order, and on an order tie ranks the sub-collection before the request, ahead of createdAt and id: the sibling order is (order, kind, createdAt, id), which within one kind is the three-key rule above unchanged. The engine's copy is engine/include/vayu/db/sibling_order.hpp; the app's compareTreeOrder is pinned to it by engine/tests/fixtures/tree-order-conformance.json, read by both test suites. A recursive collection run walks the same merged list depth-first, a request where it sits and a sub-collection's whole subtree where the sub-collection sits, pinned across both consumers by engine/tests/fixtures/recursive-run-order-conformance.json; a mock server's route table and POST /specs/export list a subtree in that order too.

A workspace from before schema version 7 numbered the two kinds apart, each from 0, and showed every sub-collection above every request. The version-7 migration moves each collection's requests past its highest sub-collection order, so that display survives (docs/engine/db-schema.md, Schema versions); rows still tied at the legacy 0 keep it through the tie rule.

Writing. order defaults to "append after the current siblings" - one past the highest order any sibling of either kind holds:

Write order
Create, order absent or null appended
Create, order stated as given, if an integer from 0 to 2147483647; otherwise a 400
Update, order stated as given, if an integer from 0 to 2147483647; otherwise a 400
Update, order absent, no move unchanged
Update, order absent or null, and the row changes parent (a collection's parentId, a request's collectionId) appended in the destination
Update, order null, no move appended among its current siblings

A move that states no order therefore lands at the end of the destination rather than at whatever slot its position in the old list happened to name, after its folders and its requests alike. Ordering within a list is always the caller's to state, and a stated order may put a request between two sub-collections.

A stored order is an integer from 0 to 2147483647 (#3451), so a negative, truncated or wrapped slot cannot be written. A stated order outside that range or that is not a JSON integer ("3", 2.5, -1, 2147483648) is a 400 naming the field on every route that writes one (POST/PUT /collections, POST/PUT /requests, POST /reorder, POST /import/apply, POST /specs/sync), for example Invalid 'order': must be an integer from 0 to 2147483647 (got 2.5), and nothing is written. An append under a parent where a sibling already holds 2147483647 has no slot left, so it is a 400 naming order too (Cannot append: a sibling already holds 'order' 2147483647 ...) rather than a row that wraps to the top; state an order, or renumber the parent with POST /reorder's normalize, which frees the end again. An import document's own stated order (x-vayu-request.order, an x-vayu-collection.folders entry's order) outside the range counts as unstated, so the row takes the position an unordered one would.

Bulk import is the one exception to the append scan: POST /import/apply writes rows that cannot see each other yet, so an omitted order gives the payload's items consecutive slots per parent starting from the append point, one run across both kinds - the parent's sub-collections first, in payload order, then its requests - see POST /import/apply. POST /specs/sync numbers the folders and requests it creates the same way.

Any writer producing several sibling rows at once owes them distinct orders - the import applier is the instance of a general rule, not a special case. The createdAt leg is a millisecond stamp, so rows written inside one tick tie on it and fall through to id, which compares random UUIDs: stable across reads of the same data, but arbitrary with respect to the order the caller meant. Single-row creates need nothing extra, because the append scan already sees every stored sibling and hands out a fresh slot. The rule is on the writer rather than on a finer timestamp: a microsecond stamp would still tie under a fast enough writer, and it would make row identity depend on clock resolution across the three platforms Vayu builds on.

Repositioning several rows at once is POST /reorder, not a run of PUTs. Each PUT is one row under its own lock, so a reorder expressed as N sibling PUTs can be interrupted halfway, leaving two rows at one order and a gap where the moved one was, and a concurrent client's move lands between any two of them. The batch endpoint validates and writes the whole set under one lock scope, which closes both. What is not a difference any more is the cycle guard: since a PUT holds its own read to its own write, its guard and its write are one scope too, so two conflicting reparents sent as single PUTs are serialized and the second is refused against the first's committed graph - it is refused after that first move is already stored, which is the part only a batch avoids. The per-row PUTs remain correct for a single row - a rename, a move that appends - and still carry those caveats when used in a loop.

Paged lists

GET /collections, GET /requests, GET /trash and GET /cookies answer every row they hold by default. Three optional query parameters ask for one page of them instead, and a page cuts the route's own documented order (the three-key rule above for collections and requests, newest first for the trash, scope then jar line for cookies), so consecutive pages neither skip nor repeat a row while nothing is written between them (#2443):

  • q - case-insensitive substring of the row's name (for a cookie, its name or its domain). The fold is ASCII only: A-Z match a-z, and any other letter matches only as typed, so É does not find é. Empty matches every row. Rows the route never lists (a request or collection in the trash, a cookie cleared from its jar) never match.
  • limit - page size, an integer from 1 to 500; default 50. 0, a value over 500 or anything that is not a whole unsigned integer (5abc, -1, +5, empty) is a 400 with code invalid_limit, never a clamp.
  • offset - matching rows to skip, a non-negative integer; default 0. Anything else is a 400 with code invalid_offset. An offset past the end is an empty page, not an error.

Naming any of the three (?q= alone counts) switches the answer to the envelope GET /runs uses:

{
  "data": [ ... ],
  "pagination": { "total": 812, "limit": 50, "offset": 0, "returned": 50, "hasMore": true }
}

data holds the rows the route's own answer would have carried, cut to the page; total counts the rows matching q before the page was cut, read from the same fetch as the page; hasMore is offset + returned < total. Naming none of them answers exactly what the route answered before paging existed, byte for byte: a bare array for GET /collections and GET /requests, {items, total} for GET /trash, {scopes} for GET /cookies. Filtering and slicing run in memory over the route's ordinary fetch, so a page saves the transfer and the client's parse, not the engine's read.

Accepted field shapes

A field that is present and not null must have the shape below, on both verbs. Anything else is a 400 naming the field, e.g. message Invalid 'auth': must be a JSON object.

Field Shape
variables (collection / environment / globals) object
auth (collection / request) object
body (request) object - see The request body union
params / headers (request) array of {key: string, value: string, enabled: bool}
order (collection / request) integer from 0 to 2147483647 - see Ordering
parentId (collection) string: a collection id, or null or "" for the root
every other plain string field (name, description, url, bodyType, an example's body and contentType, a certificate's host and passphrase, ...) string; the 400 is Invalid '<field>': must be a string (got <type>)

Object-shaped fields are stored as JSON blobs, and every reader of one degrades quietly when it is not an object - variables reads back empty, a request body is dropped, and auth resolves to none, so a request the caller believes carries credentials goes out bare. The write is therefore rejected rather than stored: {"variables": 42} and {"auth": "bearer"} are 400s, and the previously stored value is left untouched.

parentId: "" is the root, the same as null (#3451). It is stored as null on POST/PUT /collections (a folder POST /specs/sync creates with "" or null lands under the synced collection), and POST /reorder reads it as null in a move and in a normalize scope, so the tree has one spelling of the root: a collection created with "" is appended among the roots and lists with them. A value that is neither a string nor null (5, true, an object, an array) is a 400 such as Invalid 'parentId': must be a collection id or null (got number). Rows an older engine stored with "" are rewritten to null at startup (the empty-parent pass), so a delete and restore of one comes back where it was instead of re-parented to the root.

A variables key must be one a {{ name }} token can reach (#3251). A token is looked up with the spaces, tabs, CR and LF around its text cut, so a stored key that is empty, whitespace-only, or differs from its trim can never be referenced. The same 400 refuses it, naming the key: Invalid 'variables': key ' x ' has leading or trailing whitespace, or ... key '' is empty or whitespace-only. It applies to POST/PUT /collections, POST/PUT /environments and POST /globals, and the stored value is left untouched. Whitespace inside a key and dots are fine (my var, a.b). Variables a script writes are not checked. An import does not hit this: it trims the names it reads, see POST /import/parse.

Blank names

A collection's or environment's name that is empty or only spaces, tabs, CR and LF is a 400 on POST/PUT /collections and POST/PUT /environments (#3253): Invalid 'name': is empty or whitespace-only. The row is not written. A PUT that does not state name keeps the stored one, so a row that is already blank stays editable. A name with content is stored as written, surrounding spaces included. POST /import/apply and POST /specs/sync are not held to this: they carry names an importer wrote, and a blank one imports as it always did. The MCP create_ and update_ tools for both resources refuse the same name as an input error before calling the engine.

Collection auth

A collection's auth is never {"mode":"inherit"} (#3445). A collection, a folder included, is a link of the chain a request inherits through, so its own inherit would mean nothing the walk could use: the composer steps past it, while a client reading the row would show the parent's credential as the collection's. POST/PUT /collections answer 400 (Invalid 'auth': a collection cannot inherit auth ...) when the body states an auth object whose mode is inherit, and write nothing. A body without auth is not judged (a PUT keeps the stored value), and "auth": null resets to {"mode":"none"}, which is how a collection stops being an auth source. POST /import/apply and POST /specs/sync are not held to this, as with blank names. A row that already stores inherit from before this rule is read as no auth of its own: POST /compose resolves a request beneath it to the nearest ancestor's credential, and a PUT of other fields still succeeds. The MCP create_ and update_ collection tools refuse inherit as an input error before calling the engine.

Auth modes

A stored auth object's mode is one of none, noauth, inherit, bearer, basic, apikey, oauth2, digest, aws, ntlm, hawk, oauth1, edgegrid and jwt, spelled exactly so (#3464). The last seven are stored and never executed: a send names the mode in authNotice and goes out without a credential. Modes match by exact lowercase string, so Bearer, " inherit" or a non-string mode would be stored and then read as a concrete credential that stops the inherit walk and is sent as none. POST/PUT /collections and POST/PUT /requests therefore answer 400 (Invalid 'auth.mode': must be a string, one of: ...) when the body states an auth object whose mode is missing, not a string, or outside that set, and write nothing. inherit stays valid for a request and is refused for a collection (#3445). "auth": null and an absent auth are not judged, and an auth that is not an object is the shape 400. POST /import/apply and POST /specs/sync are not held to this, as with blank names: an importer's unrecognised mode is stored as written, so one odd block cannot fail an atomic import. The MCP create_ and update_ tools for both resources refuse an unknown mode as an input error before calling the engine.

The request body union

body is a discriminated union on mode, and the shape of what it carries depends on which mode it is. The same union is read on the execution endpoints (POST /compose, POST /execute, POST /runs) and stored on a request row, so a body that round-trips through storage sends the same bytes.

mode Carries On the wire
none nothing no body; a POST sends Content-Length: 0 and no Content-Type
json / text content (string) content, verbatim
graphql content (string) the GraphQL-over-HTTP envelope on POST, query parameters on GET (see below)
jsonrpc content (string) the JSON-RPC 2.0 call envelope (see below)
xml content (string) content, verbatim
x-www-form-urlencoded fields percent-encoded key=value&…
form-data fields multipart/form-data, boundary engine-generated
binary file (a file reference) the file's bytes, verbatim (see File references)

fields is an array of {key: string, value: string, enabled?: bool} - the same row shape params and headers use. key is required and must be a string; value defaults to "" and a non-boolean enabled reads as enabled. A form-data row may add contentType, the part's own Content-Type, on a text part as well as a file part (a Postman import writes it for a text row that carries one); a part without it sends none. A form mode carrying no fields array is a 400, as is a fields on a mode whose content is a string. Rows with enabled: false are stored and returned but never sent, so switching one back on needs no re-compose; {{variables}} resolve inside key, value, contentType on a part, and a file reference's src / fileName / contentType (a file part's, or a binary body's file) during composition.

The Content-Type rules follow from the encoding:

  • x-www-form-urlencoded sets Content-Type: application/x-www-form-urlencoded only when the request declares no Content-Type of its own - an explicit header wins.
  • json sets Content-Type: application/json under the same rule (issue #889). It did not until then, and libcurl's default for a CURLOPT_POSTFIELDS body (every mode but form-data and a streamed binary, on every verb) is application/x-www-form-urlencoded - so a request whose body.mode said json went out declaring itself a form. The app's body panel wrote the header row for a request built in the UI, which is why it survived: every request created any other way - MCP create_request, an import, a payload posted straight to /execute - sent the wrong type. A declared header still wins, so application/vnd.api+json reaches the server unchanged.
  • graphql and jsonrpc set Content-Type: application/json under the same rule - a Content-Type the caller wrote wins. graphql only on the method that carries a body at all: a GraphQL GET has no body and derives no Content-Type, since there is nothing to describe (see below).
  • text sets Content-Type: text/plain under the same rule (issue #2464). Until then it derived nothing, by decision - text/csv, a JWT and a raw signature are all text - but an author who wrote no header got libcurl's form type rather than no type. Postman and Bruno send text/plain for the same body. A typed row (text/csv, application/jwt) still wins, and disabledSystemHeaders: ["content-type"] sends none.
  • xml sets Content-Type: application/xml, again only when the caller declared none. It has no envelope and nothing is done to content; the header is the whole of what sets the mode apart from text, which is why an endpoint expecting application/soap+xml keeps the header it was given.
  • form-data always sets its own Content-Type, and a caller-supplied one is dropped. The header has to carry the boundary of the body that was actually encoded, which no caller can name in advance.

  • binary derives its Content-Type from the file, in four tiers, an empty string counting as absent at each: an enabled Content-Type header row, then file.contentType, then the type the file's extension names (one engine table of common types), then application/octet-stream. POST /compose writes the effective type into an empty file.contentType (unless a non-blank Content-Type header row is present, which wins at send anyway), so the composed payload - and a snippet generated from it - names the type the send uses.

No request goes out under libcurl's x-www-form-urlencoded default (issue #2464). libcurl writes that type into any CURLOPT_POSTFIELDS body, and into a bodyless POST, whenever the header list names no Content-Type. So where nothing declares one - a content-type refusal in disabledSystemHeaders, a typed Content-Type row left blank (on any mode but binary, where a blank row is absent), a body mode of none on a POST - the engine hands libcurl its removal line instead, and the request carries no Content-Type at all, as Postman sends a bodyless POST. A bodyless PUT, PATCH or GET never had one. The removal line is not a sent header and is not in requestHeaders.

The graphql envelope

A GraphQL server reads its query out of a JSON object, so a graphql body is enveloped on its way to the wire rather than sent as typed. content may be either shape and the engine normalizes both:

content Sent as
a JSON object with a string query itself, byte for byte
anything else (a bare document, JSON that is not an envelope) {"query": <content>}

The pass-through is byte-exact deliberately: the envelope also carries operationName, variables and whatever else a server has agreed with its clients, and re-serializing it would reorder keys the caller never edited. The app's request builder writes the envelope itself, so its requests take the first row; MCP and raw callers can hand over the document alone and take the second.

One case is neither: content that looks like a JSON object ({ then a quoted key) but does not parse - an envelope whose {{token}} went unresolved, or a mistyped one - is passed through unchanged rather than wrapped. Wrapping a body the engine could not read would turn a broken envelope into a valid request carrying the wrong query. A bare GraphQL document cannot take that shape, so nothing legitimate falls into it.

GraphQL-over-HTTP defines two transports, and the request's method picks between them (issue #1228). Everything above is the POST transport - the envelope goes out as a JSON body. On a GET, the same fields travel as percent-encoded query parameters instead, and the request has no body and no derived Content-Type:

Parameter From
query the envelope's query, or the whole of content when it is a bare document
operationName the envelope's operationName, when present and not null
variables the envelope's variables, JSON-encoded, when present and not null
extensions the envelope's extensions, JSON-encoded, when present and not null

The order the author wrote is the order sent: the parameters follow the envelope's member order, and the keys inside variables and extensions keep theirs (issue #2789), written compactly with no whitespace. The encoding re-renders numbers from their parsed value rather than copying the text: an integer up to 64 bits unsigned (18446744073709551615) is exact, a larger one becomes a double (18446744073709551616 is sent as 1.8446744073709552e+19), and a fraction or exponent form is a double (1e2 is sent as 100.0). The POST transport is unaffected and stays byte for byte.

These parameters are merged into whatever query string the request's URL already has, not used to replace it - a GET sent to /graphql?debug=1 keeps debug=1 alongside query=…. The engine sends a body on a GraphQL GET in three cases, each because dropping the alternative would send a request the caller did not write rather than the one it wrote: content is empty, content is envelope-shaped but does not parse (the same unreadable-envelope case above), or the envelope carries a member this transport has no parameter for, or one of operationName / variables / extensions whose value is not the type the specification gives it. A fourth case is an envelope nested deeper than 128 levels, its own root counted (issue #2672): content is a string, so the request-body depth bound never looks inside it, and encoding variables or extensions would re-serialize them recursively. Like the unreadable envelope it is not split, and the engine does not guess at it. In all four, the request falls back to the POST-style JSON body even though the method is GET.

The jsonrpc envelope

A JSON-RPC 2.0 server refuses a frame that does not declare its version, so a jsonrpc body is completed on its way to the wire in the same place, and by the same rule, as the graphql one. content may be either shape:

content Sent as
a JSON object with a string jsonrpc member itself, byte for byte
a JSON object without one itself plus "jsonrpc":"2.0", and "id":1 if it declares no id
a JSON array (a batch call) itself, verbatim
anything else (a non-object, text that does not parse, or a call nested deeper than 128 levels) itself, verbatim

The added id is the constant 1, never a random or time-derived value: a load run sends the same call thousands of times and a replay has to send the bytes it replays, so a per-send id would make two runs of the same request incomparable. A caller who needs their own ids writes the full frame - which is passed through - and so does a caller sending a notification, the frame with no id that a server must not answer. Members the caller wrote keep the order they wrote them in, and the two the engine may add go on the end.

The member's type is what is checked, not its presence: {"jsonrpc": 2.0} is the JSON number and the spec asks for the string, so such a frame is completed (the version stamped over) rather than sent as the invalid request it is.

A batch array needs nothing done to it - every element carries its own envelope - and passes through for the same reason any non-object does: there is no single call object to complete.

The unresolved-{{token}} caveat is the graphql one, and it matters more here because a JSON-RPC params is where a variable usually sits. Composition resolves the body first (POST /compose), and the envelope rule then runs on the resolved text; a body still holding a token at wire time does not parse, so it is passed through as typed rather than completed into a well-formed request carrying an unresolved template.

File references: binary bodies and file parts

Two body shapes name a file on the machine running the engine. They carry a path, never bytes, and answer to one rule.

A binary body is one whole file:

{
  "mode": "binary",
  "file": {
    "src": "/home/ada/fixtures/avatar.png",
    "fileName": "avatar.png",
    "contentType": "image/png"
  }
}

A form-data file part is a row with "type": "file":

{
  "mode": "form-data",
  "fields": [
    { "key": "caption", "value": "my avatar", "enabled": true },
    {
      "key": "avatar",
      "type": "file",
      "src": "/home/ada/portrait.png",
      "fileName": "profile.png",
      "contentType": "image/png",
      "enabled": true
    }
  ]
}
Member Meaning
type Form rows only: "text" (default) or "file". Any other value is a 400.
src Absolute path of the file. Required.
fileName The name the file goes by. Defaults to the basename of src.
contentType A binary body's Content-Type tier (above); a file part's own Content-Type, else derived from its name (see Sending, below). A text part takes it too (see above).
unresolved Read-only, derived by the engine on every read (below): true when src is a concrete path this machine would refuse. Accepted and ignored on input.

Shape refusals (400):

  • mode: "binary" without a file object, or a file object on any other mode. An engine older than this shape sent a binary body bodiless, which is why the workspace schema moved to version 3 with it.
  • A file part in an x-www-form-urlencoded body - that media type's wire form is a string of pairs and has no file form.
  • A src on a part that is not "type": "file": it names a file nothing would send.

The trust rule. Vayu sends a file under a folder you allowed in Settings (Allowed folders), or a file a person picked (Picked files, #2356). A reference is sendable when its canonical path lies under an allowed folder or equals a picked file's: containment is decided on canonical paths, component by component, so a symlink inside an allowed folder that points outside it is outside, and /data/fixtures-old is not under /data/fixtures; a picked file is the canonical path recorded when it was picked, matched exactly, so a link re-pointed after the pick names another file and is refused. What a request body says about trust is ignored: the unresolved member an older client sends is accepted and dropped, on POST /execute, POST /runs, POST /compose and every write, so no caller can claim a file was chosen. A path composition or a data row fills in is held to the same rule as a literal one. Scripts can never choose a path: the residual pass after the pre-request script resolves a reference's fileName and contentType but never src.

unresolved is derived on read. No stored body carries the key: the request writes (POST/PUT /requests, POST /import/apply, POST /specs/sync) and a run's configSnapshot drop it, and the schema version 6 migration removed it from every body stored before. Every read that hands a body to an editor writes it back as the engine's answer for this machine now: GET /requests, GET /requests/:id, the POST/PUT /requests responses, POST /reorder's request rows, GET /runs/:id's configSnapshot.body and POST /import/parse. true means a concrete path that is neither under an allowed folder nor picked, which the send would refuse; false means an allowed path or one still holding {{ (decided after composition). A reference with no path carries no unresolved at all.

Every enabled reference is checked, in this order, and the first failure refuses the send:

  1. src is empty: "Body file has no file selected - ..." (a part: "Form field 'avatar' has no file selected - ...").
  2. src still holds {{: an unresolved variable.
  3. The file does not exist or cannot be read: "...: cannot read file '<path>' (<reason>)".
  4. Untrusted: "Body file '<path>' was not picked on this machine and is not under an allowed folder - pick it again in the request, or allow its folder in Settings › Files".
  5. Not a regular file (a directory, a FIFO, /dev/zero): refused.
  6. It cannot be opened: refused, naming the path and the reason.

On POST /execute a refusal is the pre-send gate's shape: 200 with statusCode: 0, errorCode: INTERNAL_ERROR and the message above in errorMessage. A streaming execute (stream: true) answers 400 with code unsendable_file. POST /runs checks every file the run can send before the run row exists and answers 400 with code unsendable_file; for a path a data row binds, each distinct bound path is checked and the message starts with data row N: (a scenario's with Step N ('name'): too). A path that changes per iteration in a way no row explains (an identity or generator token) cannot be checked ahead and is refused per submission.

Sending. The check runs once per send and once per run, never per transfer. It opens the file it approved, on the path the check resolved and without following a final symlink, and everything after reads that open file, never the path again: a link re-pointed or a file replaced at the path after the check, or between a run's iterations, is not what is sent. A binary body of at most 4 MiB is read through it in that pass and its bytes are shared by every transfer of the run; a larger one is hashed through it in that pass and every transfer streams from it (Content-Length from the size the open saw; a redirect rewinds it). A form part's file is read from it by every transfer of the send or run. A path a data row binds is the exception: it is checked when the run starts but opened per submission, through the same check again, so a large data file holds no file open per row. A streamed body's or a part's length is the one the open saw; a file truncated below it under the open handle fails the transfer. A part with no declared Content-Type is typed by its filename's extension, then its path's, from libcurl's table (gif, jpg, jpeg, png, svg, txt, htm, html, pdf, xml), else application/octet-stream. A disabled file part is neither checked nor sent.

What a record keeps. A view of a request never carries a file's bytes: the raw-request view shows <file avatar.png, 1234 bytes> in their place. A binary body's send records bodyFile: {fileName, size, sha256} (sha256 lowercase hex; size and sha256 absent when the send was refused before the file was read) - never the path:

Where JSON path
POST /execute response bodyFile (top level)
A design send's or a collection run step's stored trace (GET /runs/:id, result.trace; GET /runs/:id/results) trace.request.bodyFile
A single-request load run config_snapshot.bodyFile, echoed by GET /runs/:id/report as metadata.bodyFile
A scenario run's steps config_snapshot.scenario.steps[i].bodyFile (absent for a step whose path a data row binds)

The older mode spellings form (for x-www-form-urlencoded) and formdata (for form-data) are still accepted on input; responses always use the long names.

Behavior change (pre-1.0)

A create carrying an id is now a 400 on all three resources. External scripts that minted their own ids must drop the field and read the engine's id out of the response, or use POST /import/apply for a whole tree. A PUT whose body id disagrees with the path id is a 400 for the same reason (it used to be silently ignored, so the write landed on the path id).

POST /<resource> used to be a silent upsert on all three resources, so a client could send an update as a POST. That no longer works; external scripts that relied on POST-as-update must switch to PUT /<resource>/:id. Two bugs went with the old behavior and are fixed here:

  • A stale or typo'd id silently created a second record instead of failing, and an id collision silently merged two records into one.
  • POST /environments had no null guard, so {"variables": null} stored the literal four-character text null - JSON that parses but is not an object, so every reader saw an environment with no variables and no error. It now resets to {} like every other resource.
  • environments.isActive was honored only on create; it now follows the rule on both verbs.

Health & Configuration

GET /health

Check engine status and version.

Response:

{
  "status": "ok",
  "version": "0.3.0",
  "workers": 8,
  "dataDir": "/home/someone/.config/Vayu"
}

workers is the workers setting's effective value: the configured count when it is set, otherwise the detected core count - the same value the next run's EventLoop will use, not the machine's raw core count regardless of configuration. It is never 0: a host whose core count cannot be detected reports 4, the fallback the event loop applies too.

dataDir (issue #3328) is the data directory this engine keeps its database, logs and lock file in, the --data-dir it was started with, so a client can tell an engine serving its own data from one serving another's. It is resolved once at startup and always present:

  • absolute: a relative --data-dir (or the default ./data) is resolved against the directory the engine was started in;
  • lexically normalised: . and .. segments and a trailing separator are removed, and on Windows every separator is \;
  • not canonical: a symlink is reported as written, not resolved, so the value compares equal to the path a client passed;
  • UTF-8. A name that is not valid UTF-8 (a POSIX directory name is bytes) has the offending bytes replaced with U+FFFD rather than failing the response.

recovery (optional, issue #922) - present only when this engine startup had to recover the database, and absent on a clean start rather than null:

{
  "status": "ok",
  "version": "0.3.0",
  "workers": 8,
  "dataDir": "/home/someone/.config/Vayu",
  "recovery": {
    "outcome": "started_fresh_quarantined",
    "at": 1755870000000,
    "databasePath": "/home/someone/.config/Vayu/db/vayu.db",
    "quarantinedPath": "/home/someone/.config/Vayu/db/vayu.db.corrupt-1755870000000"
  }
}
Field Meaning
outcome restored_from_backup - <db>.bak passed the same validation and was restored over the corrupt database. started_fresh_quarantined - no backup restored it, so it was moved aside and a fresh one created. backup_also_corrupt - a backup existed, failed the same validation, and was left untouched rather than restored. deleted_corrupt - it was deleted, which an engine older than issue #984 always did and this one does only when the quarantine rename fails
at When that happened, epoch milliseconds
databasePath The database file it happened to
quarantinedPath Where the unopenable database was moved to, readable with sqlite3 <path> .recover. Optional - absent for deleted_corrupt and for markers written before #984, so test for it rather than deriving it from outcome

The node is read from a marker file beside the database and stands until a later recovery overwrites it, so a client that has already told the user about an event should key off at rather than expecting the node to disappear. See db-schema.md.

POST /shutdown

Gracefully shut down the engine. This is the shutdown path the Electron app uses on quit (it is more reliable than a signal on Windows, where SIGTERM does not behave as expected).

The response is sent before shutdown begins, so the client always receives the 200. The handler sets the body and then calls the shutdown callback inline, which only wakes the daemon's main loop; the teardown cannot overtake the response, because stopping the server joins the worker that is writing it. The daemon then stops the server (and with it every mock server, inbox, mock issuer and OAuth callback listener, a paced answer going out at once and a callback's token exchange cancelled), ends and joins every streaming design run (the run ends stopped and its trace's endReason is shutdown, never a user's stopped, #3342), stops and joins active runs (a run still sending ends stopped; one in its natural-end drain has the drain cut short, its in-flight transfers counted as cancelled, and keeps its own end, as for a Stop, issue #3341), refreshes the recovery backup <db>.bak if the session wrote anything (bounded at 2 s and by what is left of the app's 5 s window; on a timeout the previous backup stands, see db-schema.md), closes the database, releases the lock file, flushes the logs and exits.

Response: 200

{
  "status": "ok",
  "message": "Shutdown initiated"
}

GET /config

Get global configuration settings. Backed by the config_entries table. The response is an entries array; each entry carries its value plus the UI metadata the Settings panel renders (label, description, category, default, and optional min/max/options):

{
  "entries": [
    {
      "key": "workers",
      "value": "8",
      "type": "integer",
      "label": "Worker threads",
      "description": "Number of background worker threads. Higher values improve throughput on multi-core systems but increase RAM usage. Default equals CPU core count.",
      "category": "general_engine",
      "default": "8",
      "min": "1",
      "max": "128",
      "requiresRestart": false,
      "advanced": false,
      "keywords": ["cores", "parallelism"],
      "updatedAt": 1234567890
    },
    {
      "key": "defaultHttpVersion",
      "value": "auto",
      "type": "enum",
      "label": "Default HTTP version",
      "description": "Protocol a newly created request starts with...",
      "category": "network_performance",
      "default": "auto",
      "options": [
        { "value": "auto", "label": "Auto" },
        { "value": "http1.1", "label": "HTTP/1.x" },
        { "value": "http2", "label": "HTTP/2" }
      ],
      "requiresRestart": false,
      "advanced": false,
      "keywords": ["h2", "alpn"],
      "updatedAt": 1234567890
    },
    {
      "key": "dbCacheSize",
      "value": "67108864",
      "type": "integer",
      "label": "Database cache size",
      "description": "Memory SQLite keeps per connection for recently used database pages...",
      "category": "general_engine",
      "default": "67108864",
      "min": "1048576",
      "max": "1073741824",
      "unit": "bytes",
      "requiresRestart": true,
      "advanced": false,
      "keywords": ["ram"],
      "updatedAt": 1234567890
    }
  ]
}

Only entries this engine's own build declares are listed (issue #1492): a row a newer engine wrote to the same workspace, then left behind for an older one to reopen, is never in entries - this engine has no label, validator or bounds for it, so serving it would describe a setting it cannot actually explain. POST /config applies the same rule to writes: a key outside this build's catalogue is refused as "Unknown config key", the same message a key with no stored row at all gets.

min and max are present only for entries that declare them (numeric types). options is present only for type: "enum" entries - a JSON array of {value, label}, so the renderer can draw a picker without a second, hand-maintained value-to-label map. value and default are always strings; type is one of integer, number, boolean, string, or enum.

dependsOn (issue #1610) is present only on an entry that means nothing until a boolean sibling in the same category is on - correlationIdHeader carries "dependsOn": "correlationIdEnabled". It is a catalogue fact the seed asserts is internally consistent (a value naming an unknown, cross-category or non-boolean key fails engine startup); POST /config never reads it back. The Settings screen nests the dependent's card immediately beneath its parent's, indented and disabled with a "Turn on \<parent label> to use this" hint while the parent reads "false".

requiresRestart and advanced are booleans, always present:

  • requiresRestart - the running engine keeps the old value until it is restarted; anything else takes effect on the next run, inbox or request that reads it. It is the only statement of that fact: labels and descriptions no longer spell it out, and the app renders one chip from this field (a pending signal in the Dock too, once such a setting has been saved). Consumers must read the field rather than parse the label - the old (Requires Restart) suffix drifted out of step with the mechanism and misinformed the settings screen and the MCP update_config result at the same time. Exactly three entries carry it - dbCacheSize, dbBusyTimeout and dbSynchronous, all read when the database is opened. workers carried it too until #873, which is the same drift in the field's own terms: the engine reads it at the start of every run, so the restart it asked for was never needed. config_route_test.cpp pins the set.
  • advanced - an internal with no everyday user story (dbBusyTimeout, the four oauth2Refresh* watchdog knobs, inboxLivePollIntervalMs, sseIdleTimeoutMs, maxStepsPerIteration, monitorScrapeTimeoutMs, liveMaxRetainedTicks, scriptStackSize - eleven entries). Still live and still settable; the app renders these collapsed under an "Advanced" section at the bottom of their category. The membership rule is citable: if an entry's own description has to say "only if" or "only for", the entry has declared itself advanced.

keywords is an array of strings, always present and empty for the entries that declare none - a client never has to tell "declares none" from "this engine does not send the field". They are extra terms the app's settings search matches on: what a user types that this entry's key, label and description never say ("ram" for dbCacheSize, "deadline" for defaultTimeout, "fsync" for dbSynchronous). They are match terms only and are never displayed, and a seeded keyword never repeats a word the entry already carries - search reaches the other three fields first and ranks them higher, so a duplicate would only push the entry above better matches. A test over the seeded catalogue enforces both halves of that.

unit says what a numeric entry's value measures - ms, sec, days or bytes today - and is omitted when the entry measures nothing, the same shape as min / max / options above rather than a null. Absent means the number is a count (worker threads, retained runs, stored steps); a suffix reading "items" would be noise, so counts declare none. Non-numeric entries never declare one.

The app renders it as the suffix inside the input, which is where a unit is stated once - so a seeded description never spells the same unit out as an "in milliseconds" clause, and a label never carries a (ms) suffix; a test over the catalogue enforces both. Labels are sentence case ("Default request timeout", "Correlation ID"), enforced by a second catalogue test. bytes additionally selects human-readable formatting for the value, the range hint and the default line (104857600 reads as 100.0 MB), which the app used to select from a hardcoded list of three keys - so a byte-valued entry added engine-side was formatted as a raw number until someone edited a TypeScript array. A client that meets a unit it does not know should show it verbatim rather than drop it.

Three entries are seeded as enum today. defaultHttpVersion is the protocol a newly created request starts with (see POST /requests). It is a write-time seed only - changing it never alters a request that already exists, and it is never consulted at execution time. dbSynchronous is SQLite's durability level, whose three values ("0" Off, "1" Normal, "2" Full) are an enumeration rather than a range; it is stored as an enum so the panel draws a picker instead of an integer box the description has to explain. Its default is Normal ("1"). After a power cut or an operating-system crash, Off can corrupt the whole workspace file, Normal cannot corrupt it but may lose the last few seconds of writes, and Full keeps every committed write. proxyMode is the third - see Proxy settings below.

The Settings panel renders entries dynamically, so new keys appear without app changes. The entries below span three categories: the data_retention keys govern how much of a run is kept on disk; maxResponseBodyBytes is limits, because it fails an oversized read in flight and stores nothing; and phaseHistograms joins the three monitor* keys in observability, which governs what a run measures rather than what it keeps:

Key Default Range Effect
maxTraceBodyBytes 5242880 1024–104857600 Largest request/response body stored in a design run's trace_data. Bigger bodies are truncated with bodyTruncated/bodyBytes (see GET /runs/:id).
maxResponseBodyBytes 33554432 1024–1073741824 Largest response body a load-test transfer reads into memory, and what a pm.sendRequest from any of that run's scripts (inline step scripts, script.setup / script.teardown, the deferred tests script) may read. A bigger response fails that request (see POST /runs). Not a storage cap and unrelated to maxTraceBodyBytes, which truncates what a completed design request writes to the database.
maxDesignResponseBodyBytes 33554432 1024–1073741824 Largest response body a design-mode send - POST /execute, and each step of a collection run - reads into memory, and what a pm.sendRequest from that send's scripts (a collection run's setup and teardown scripts included) may read. A bigger response is read up to this point and answered with bodyCapped: true (see POST /execute) rather than failing, because someone is watching for it - a script's own fetch is the exception and refuses, having no way to tell the script its body was cut (see scripting). Separate from maxResponseBodyBytes above, which is the load path's and refuses in every case.
maxElementBodyBytes 1048576 1024–1073741824 Largest response body an extract.json or assert.jsonpath element will parse as JSON, in a design send, a collection run and a scenario load run alike. A bigger response is not parsed at all, instead of paying for - or failing on - a parse of an oversized body, and the step does not pass on it: an assert.jsonpath fails and a required extract.json fails the step, both with the reason, while an optional extract.json reports skipped with it. A body that parses but nests deeper than 100 levels is unreadable the same way, whatever its size, as is one that is not JSON; that depth is fixed, not a setting. The one shared parse per step is reused by every such element, so this is a per-step cost, not a per-element one.
maxSampleBodyBytes 32768 0–104857600 Largest response body kept for a single captured load-run sample. Bigger bodies are stored truncated and marked. Deliberately far below maxTraceBodyBytes: a design run stores one exchange the user asked for, a load run stores tens nobody asked for individually. 0 keeps headers and metadata and no body.
maxSampleBytes 2097152 0–1073741824 Total captured body bytes one load run may store. Once spent, samples keep their headers and metadata and only their bodies are dropped; the report counts them as sampling.sampleBodiesDropped.
maxResponseSampleBytes 268435456 0–1073741824 Total response-body bytes one load run may hold for its post-run test scripts and schema checks. Two orders of magnitude above maxSampleBytes because these bodies are kept whole - a truncated one would fail a check the target passed - so past the budget whole samples are dropped instead, counted as sampling.responseSamplesDropped. 0 retains no sample that has a body.
phaseHistograms true boolean Record DNS/connect/TLS/first-byte/download times for every load-test completion into five HdrHistograms, so the report can carry timingBreakdown.phases percentiles and averages over every completion instead of over the retained trace sample, and the live stream's gate frames can carry cumulativePhases. Costs five atomic histogram writes per completion; see benchmarks.
maxRunsRetained 200 0–100000 Keep at most this many most-recent load and collection runs; older ones (and their metrics/results, including captured response bodies) are pruned at startup and after each run finishes. Design Sends are counted under maxDesignRunsRetained instead and never evict these. 0 = unlimited. Captured data is stored verbatim, so this doubles as its expiry.
maxDesignRunsRetained 100 0–100000 Keep at most this many most-recent design Sends (POST /execute runs); older ones and their stored exchange are pruned at startup and after each Send. Counted apart from maxRunsRetained, so Sends never evict a load or collection run (#2429). 0 = unlimited.
runRetentionDays 30 0–3650 Delete runs older than this many days. 0 = unlimited.
trashRetentionDays 30 0–3650 Destroy collections, requests, environments, saved examples and client certificates deleted more than this many days ago, swept at startup. Until then they are restorable - see Trash. 0 keeps the trash forever.
monitorIntervalMs 1000 250–60000 Scrape cadence for a monitor block that names no intervalMs of its own. Read per run, so a change applies to the next run started. The bounds on a block's own intervalMs are fixed at 250–60000 either way - they exist to stop a cadence that measures the scraper rather than the target.
monitorMaxSeries 8 1–64 How many metric names one run may chart from its monitored endpoint. A longer series list is a 400. Raising it past 4 repeats chart colours (the categorical palette has four line-legible hues).
monitorScrapeTimeoutMs 0 0–60000 How long one scrape may take before it counts as a gap. 0 derives it from the cadence in force for that run - three quarters of the interval. Set it explicitly for an exposition that is slow to render: one taking longer than three quarters of the interval fails every scrape otherwise, and the only other way out is a slower cadence, which also thins the data. A value longer than the interval a run scrapes at is shortened to it (logged once per run), because a scrape that outlives its own cadence puts the loop behind itself.

Proxy settings

Four network_performance entries decide how every outbound request leaves the machine - design sends, load runs, SSE streams, OAuth token acquisition, POST /import/fetch (which spec re-fetch and $ref bundling ride) and the monitor scrape alike. They are read at the point of use, so a change applies to the next transfer with no restart; a load run and a collection run read the policy once at run start and hold it for the run, because libcurl reuses a pooled connection only when its proxy configuration matches.

Key Default Values Effect
proxyMode environment environment, system, manual, off Where the proxy comes from. environment is libcurl's own http_proxy / https_proxy pickup - what a terminal-launched engine already got, and what a desktop launch usually inherits nothing of. system uses proxySystemUrl, which the app resolves from the operating system. manual uses proxyUrl. off sends direct and also disables the environment pickup.
proxyUrl "" curl-shaped URL The proxy for manual mode: scheme://user:password@host:port. The scheme selects the kind (http, https, socks4, socks4a, socks5, socks5h, socks5t); a scheme-less host:port means http://. Credentials in the URL become basic proxy authentication; write an @ in the password as %40 (libcurl ends the userinfo at the first @, so a URL with a second one before the host is a 400). An https proxy is verified against the same trust as the target (the platform's anchors plus customCaCertificates) and the request's verifySSL - see TLS trust settings.
proxySystemUrl "" curl-shaped URL The proxy for system mode, written by the app, not typed by the user. The Electron main process resolves the OS proxy through Chromium and stores the answer here at startup, when the machine wakes, and when the renderer sees the network change. Empty means nothing resolved - see the fallback below. Validated exactly as proxyUrl is, under every mode.
proxyBypass "" hosts separated by commas, spaces or tabs Hosts that skip the proxy, passed to curl's NOPROXY. Each entry is an exact host (localhost), .suffix (a domain and everything under it), a bare suffix, an IPv4 or IPv6 address written bare (::1), ip/N CIDR (10.0.0.0/8), or a single * that bypasses everything. A 400 refuses the shapes libcurl would take as a hostname no transfer dials, so the exemption would silently never apply: a :port, a * inside an entry (*.example.com, local*), a bracketed IPv6, a scheme, a path, or a whitespace or control character other than the comma, space and tab separators (a newline). Hostname characters beyond that are not validated. An entry already stored in one of those shapes (a hand-edited row) is left out of what reaches libcurl, with a warning naming it; the other entries stay.

proxyBypass and an inherited no_proxy interact by mode, deliberately. libcurl consults the process's no_proxy variable whenever CURLOPT_NOPROXY is unset, so:

  • Under manual, this list is the entire rule and is always written, empty or not. An empty list exempts nothing, and an inherited no_proxy is ignored. Anything else means a user who named a proxy in Settings has their traffic silently exempted from it by an ambient variable - which is the same invisible failure the mode exists to fix, and not hypothetical: a container exporting no_proxy=...,127.0.0.1,... bypasses a configured proxy for every local target and says nothing.
  • Under environment, an empty list defers to no_proxy - "do what the environment says" includes the exemptions it names - and a non-empty one overrides it.
  • Under system it follows whichever of those two the mode resolved to: the manual rule once a proxy is in force, the environment rule when nothing resolved.
  • Under off there is no proxy for a bypass list to modify.

system mode has two limitations, and both are disclosed rather than hidden. The engine cannot resolve an OS proxy itself - that answer lives behind Chromium's network stack, which libcurl sees none of - so the resolution is the app's and this setting is the channel:

  • PAC is resolved once, not per request. A PAC script answers per URL and the engine cannot call back into Chromium for every transfer, so the app resolves against one probe URL and that answer applies engine-wide. A configuration returning different proxies for different URLs needs manual.
  • A headless engine falls back to environment. With no app running, proxySystemUrl is empty and system behaves as environment does - not as off, because the environment pickup is the closest thing to "what this machine would do" that a daemon on its own has. An unusable stored value falls back the same way, with the reason logged.

POST /config enforces one cross-field rule these three have and the per-key validation cannot express: proxyMode: "manual" requires a usable proxyUrl, judged against the state the update would leave rather than against the keys in the body, so setting the mode alone is a 400 and so is clearing the URL while the mode is already manual. A malformed URL is rejected under any mode; a valid URL stored while the mode is off is kept untouched, which is how a proxy is switched off temporarily without losing it.

A failure of the proxy hop is reported as its own error code, PROXY_ERROR, rather than as the target's:

  • an unresolvable proxy hostname (previously CONNECTION_FAILED, which sent people debugging an endpoint that was never reached);
  • a proxy that is down, so connecting to it is refused (#3257). The refused socket is the proxy's whatever the target is, and the target was never dialled. This holds in every mode, environment included, because the decision reads libcurl's own record that a proxy was in the path (CURLINFO_USED_PROXY) and not the configured URL; the same refusal with no proxy in the path stays the target's CONNECTION_FAILED;
  • a SOCKS handshake failure;
  • a 4xx answered to a CONNECT, which an https:// target makes the proxy see - including the 407 a proxy demanding authentication returns, which curl reports as a generic receive error and which previously surfaced as INTERNAL_ERROR;
  • a forwarding proxy's 407 on a plain http:// request (#3257), which needs no CONNECT and so comes back as an ordinary response that read as the server's own answer. POST /execute (and the other single-request sends: the connection test, pm.sendRequest, the OAuth token fetch, the import fetch) reports it as PROXY_ERROR with status 0 and the message "The proxy answered 407 Proxy Authentication Required: check the proxy's credentials". A 407 is the proxy's only when a proxy carried the transfer and no tunnel stands between the engine and the server: a 407 a server sends directly, or through an established CONNECT tunnel, stays a response with its status.

A load run keeps counting a proxy's 407 as a status, as it does any other status the proxy returns on a forwarded http:// request: the load path does not reinterpret completed transfers, so the run's status distribution shows the 407s and its error counts do not. A proxy that is down is PROXY_ERROR there too, since that mapping reads the failed transfer.

The code is appended to the error enumeration, so the numeric values stored in existing traces are unchanged.

Two more failures of the target's answer have their own codes (issue #2462): TOO_MANY_REDIRECTS, when the server redirected past the request's maxRedirects (usually a loop), and BAD_CONTENT_ENCODING, when the response declares a Content-Encoding that its bytes are not in or that this libcurl has no decoder for. Both previously came back as CONNECTION_FAILED, which sent people looking for a network fault when every hop had been answered. errorMessage opens with a plain statement - Too many redirects: the server redirected more than N times (see Maximum redirects). Maximum (N) redirects followed, which is the engine's own text and ends there (the engine follows redirects itself), or The response could not be decoded: the server sent Content-Encoding X., which is followed by libcurl's own text. The codes are appended to the enumeration like PROXY_ERROR, so stored numeric values are unchanged, but a script that tested err.code === 'CONNECTION_FAILED' (pm.sendRequest) or pm.response.errorCode === 'CONNECTION_FAILED' for these two failures now sees the new spelling. A load run records them under the error types too_many_redirects and bad_content_encoding.

A target that answers in something other than HTTP/1.x is PROTOCOL_MISMATCH (issue #3306), error type protocol_mismatch. The usual case is an h2c server (HTTP/2 over cleartext) sent a request over http://: Vayu speaks HTTP/1.1 there whatever httpVersion says (the Protocol paragraph under POST /execute), and the server answers with its binary HTTP/2 preface, which libcurl reports as Received HTTP/0.9 when not allowed. That failure used to come back as INVALID_URL, which sent people to a URL that was fine. errorMessage opens with The server answered in a protocol other than HTTP/1.x: followed by libcurl's text, and when the request asked for http2 and the hop that failed was http:// (after any redirect) it adds HTTP/2 is only negotiated over https://; this server may speak h2c, which Vayu does not send. A scheme the transfer refuses, a redirect onto ftp:// included, is still INVALID_URL. The code is appended like the others, and a script sees it as err.code (pm.sendRequest) or pm.response.errorCode.

A send still in flight when the engine shuts down is cancelled rather than waited on (issue #2683), and so is a pm.sendRequest one of its scripts is making: the send answers, and its trace records, CANCELLED with errorMessage Request cancelled, about a second after the shutdown began.

A buffered send whose caller hangs up before the answer is cancelled the same way (issue #3383), together with an OAuth 2.0 token it is fetching and a pm.sendRequest one of its scripts is making: the engine reads the connection every 100ms and the transfer ends at its next progress tick, about a second later. The run is recorded stopped, never completed; its result row holds what the exchange reached, CANCELLED for a transfer that was cut. A transient send records nothing, as always. "Hangs up" is the connection reading end-of-stream, and TCP cannot tell that from a caller that only shut down its sending side, so a client that half-closes after its request is treated as gone: keep the connection open until the answer is read. A streaming send (stream: true) is not watched: it is handed off at its 202 and outlives the call that started it, and POST /runs/:runId/stop is what ends it.

Cookies are unaffected by any of this: libcurl owns the wire cookies and matches them on the origin host, never the proxy hop.

Default request headers

Five network_performance entries decide what Vayu adds to a request nobody wrote it into (issue #1229, and #2468 for the Expect header). They are read at the top of a request or a run, so a change applies to the next send; a load run reads them once at run start, as it does the proxy policy.

Key Default Values Effect
negotiateCompression true boolean Ask for a compressed response on a Send, a collection or scenario run, and a script's own pm.sendRequest. The value advertised is what this libcurl can decode, read off curl_version_info - gzip, deflate plus br and zstd where the build has them - and libcurl decodes the response before the engine sees it. Off sends no Accept-Encoding at all.
loadNegotiateCompression true boolean The same decision for a load run, separate because compression is part of what a load test measures: off measures a server's uncompressed ceiling, on measures what its clients actually get.
sendExpectContinue false boolean Let libcurl send Expect: 100-continue on a large body. libcurl adds that header on its own to an HTTP/1.1 body over 1 MiB (1048577 bytes and up) and then waits about a second for an interim reply a server that ignores the header never sends, so with this off the engine removes it with libcurl's Expect: removal line and the transfer sends the body at once. One key for a Send, a collection run and a load run alike. The removal line is not a sent header, so it is not in requestHeaders.
correlationIdEnabled false boolean Send a header carrying a fresh identifier with every request, so one send - or one iteration of a load run - can be found in a server's log. Off by default: it is a header the target did not ask for.
correlationIdHeader X-Vayu-Request-Id header name Which name that identifier goes out under. Vendor-namespaced by default so it collides with nothing a gateway defines; set it to X-Request-ID or X-Correlation-ID for infrastructure that reads one of those. POST /config refuses a value that is not a header name (RFC 9110 token), because a broken name would otherwise put a broken line on every request afterwards.

Three rules hold for all of them, and for the User-Agent the engine has always added:

  • A header the request carries wins. Nothing here overwrites a name the request already names, so a browser's User-Agent, a hand-typed correlation id, or an Accept-Encoding: identity is sent exactly as written. A request that names Accept-Encoding itself also gets no decoding: libcurl hands back what arrives, which is what typing that header asks for.
  • Any of them can be refused per send, with disabledDefaultHeaders on POST /execute or POST /runs.
  • None of them is stored. They are applied at send time, so a saved request cannot carry a stale one. A request saved before this change is stripped of the rows an older app wrote into it, once, at startup: X-Vayu-Version always, an X-Request-ID whose value is a bare UUID, and a User-Agent whose value is a Vayu/.... A correlation id or a User-Agent someone typed is left alone.

The correlation id is generated per transfer, not per composition, so every iteration of a load run carries its own.

Expect is the one default the engine takes away rather than adds. With sendExpectContinue off, a request that names no Expect gets libcurl's removal line, whatever its size or verb. A typed Expect: 100-continue is the way to send one on purpose: it goes out as typed with the key off, and is recorded in requestHeaders. A typed Expect with a blank value is sent empty, like any blank row (see requestHeaders), and recorded with the value ""; libcurl adds no 100-continue of its own beside it, so the body goes out without the wait and without a removal line. With the key on nothing is appended, so libcurl decides (over 1 MiB, on HTTP/1.1), and the Expect row GET /request-defaults declares is the one a send refuses with disabledDefaultHeaders, which removes libcurl's line again. With the key off that refusal changes nothing: the line is already removed.

Every size the API reports is the bytes Vayu holds - bodySize, a stored trace's bodyBytes, a load sample's body_bytes. With negotiation on those are the decoded bytes, because libcurl decodes before the engine counts; with it off they are the identity response, which is the same number. What crossed the network compressed is not measured, and rawRequest is where the negotiated Accept-Encoding line itself can be read back.

TLS trust settings

One more network_performance entry decides who the engine trusts, and it reaches the same six outbound paths the proxy settings do.

Key Default Values Effect
customCaCertificates "" PEM text (text entry) Certificate authorities to trust in addition to the ones this platform already trusts. Pasted content, not a path: a path breaks when the file moves and cannot be shown back in Settings. POST /config refuses text that holds no -----BEGIN CERTIFICATE----- block, and names a pasted private key for what it is. It then parses every certificate block with OpenSSL and answers 400 naming the first one that does not, counted from 1 (certificate 2 of 3 does not parse); only the parse is asked, never validity or expiry.

The engine materializes the bundle as ca-bundle.pem beside its database and points CURLOPT_CAINFO at it, rewriting the file only when the setting's content changes. A block that does not parse in a value stored before that check is left out of the file and logged (a warning naming the setting and the block's position), because OpenSSL abandons a bundle file at its first bad block and the platform's anchors would go with it. Native trust is preserved - the mechanism differs by TLS backend, and each is stated rather than assumed:

Platform Backend What the bundle does
Linux OpenSSL (default paths + CURL_CA_FALLBACK) CURLOPT_CAINFO replaces the default bundle, so the materialized file is the platform's own anchors concatenated with the pasted ones. The system bundle is located the way curl locates it: CURL_CA_BUNDLE / SSL_CERT_FILE, then libcurl's compiled-in cainfo, then the standard distribution paths.
macOS OpenSSL Same as Linux, and the anchors are read from /etc/ssl/cert.pem and merged into the materialized file. CURLSSLOPT_NATIVE_CA is also set on every macOS handle, pasted CA or not: when a certificate does not verify against the file, the Keychain is asked, so a root or an admin-installed CA the Keychain trusts verifies with nothing pasted.
Windows OpenSSL, selected explicitly (issue #851; Schannel before it) The anchors live in the certificate store and Windows ships no PEM bundle to merge with, so the materialized file holds the pasted certificates alone and CURLSSLOPT_NATIVE_CA - set on every Windows handle, pasted CA or not - loads the store beside it. A machine that exports CURL_CA_BUNDLE puts a file back in reach and the merge runs there as it does on Linux.

Three things make that table checkable rather than a claim. The backend column itself is asserted on each CI platform - both its name and that this process selected it rather than inheriting whatever libcurl chose - so it is read off the build rather than out of a port file, the mistake that left the macOS row wrong until issue #818. The selection is not a formality on Windows: the curl port's http2 feature depends on curl[ssl], which resolves to Schannel there, so that libcurl carries both backends and picks between them by reading CURL_SSL_BACKEND from the environment. The engine names OpenSSL before curl initializes, which is what stops a stray environment variable from moving every request onto a backend where client certificates do not work at all. Issue #858 tracks getting Schannel out of the build entirely. CURLOPT_CAINFO is the one transport option a backend can refuse outright, so the engine checks the return code and logs an error naming the backend if it ever does - and the test suite asserts on every CI platform that this build's backend accepts it. And where the anchors come from a file, the suite asserts they were actually found; where they come from the store, that the build accepts the flag that loads it. Either way a merge with nothing to merge would narrow trust to the pasted certificate alone while this page still promised the opposite, so NativeStoreVerificationTest closes it on a wire: a public certificate has to verify with nothing pasted, and go on verifying once an unrelated CA is.

CURLSSLOPT_NATIVE_CA asks the backend to keep consulting the OS store. It is set unconditionally on Windows, where it is the anchor source, and on macOS, where the Keychain backs the file; on Linux it is set whenever a bundle is in force, and the merge above is what carries the guarantee.

What the Windows certificate store does not give you. OpenSSL reads it through the Windows crypto API rather than being the OS verifier, so three things Schannel did on its own do not happen:

  • Root certificates only. Intermediates cached in the store are not supplied to the chain builder (curl 12155), so a server that does not send its full chain can fail on Windows where it verified before. Pasting the intermediate into customCaCertificates fixes it.
  • No on-demand root fetch. Windows can download a missing trusted root when Schannel asks for one; nothing here asks, so only roots already in the store count.
  • No revocation through the store. Schannel passed CERT_CHAIN_REVOCATION_CHECK_CHAIN; OpenSSL does not revocation-check the chain unless told to, and the engine does not tell it to on any platform - so Windows now behaves like Linux and macOS here rather than being the strict one.

A certificate that still fails to verify fails at handshake time with libcurl's own SSL_ERROR - the validation on the way in is about the shape of the paste, deliberately, so a chain curl would accept is never refused by a parser of ours.

A TLS connection that never answers is an SSL_ERROR too, whatever code libcurl put on it. The mapping needs that rule because the interesting refusals do not arrive as TLS errors: under TLS 1.3 the server's verdict about the client - a certificate it will not accept, or one it demanded and did not get - reaches us after our own handshake has finished, so libcurl reports the generic receive error of a connection that went away, carrying the alert in its message. A key the stored passphrase does not open arrives as a generic argument error in the same way. All three used to surface as INTERNAL_ERROR, which says the failure was ours. The rule applies only where the mapping has no answer of its own, and only to an https transfer that produced no response line at all - so a 4xx, a timeout, a refused connection and a proxy failure all keep the code they had (issue #802).

Per-request, verifySSL: false turns verification off for one endpoint entirely (see POST /execute); trusting the authority here is the answer that keeps verification on everywhere else.

An https:// proxy is a second TLS handshake with the same trust. libcurl decides the proxy's certificate with options of its own (CURLOPT_PROXY_CAINFO, CURLOPT_PROXY_SSL_OPTIONS, CURLOPT_PROXY_SSL_VERIFYPEER / _VERIFYHOST) that do not inherit what the target's handshake was given, so the engine writes each of them from the same values as its target-side twin: a proxy whose certificate a pasted authority signed verifies, and verifySSL: false covers the proxy leg as well as the target. No client certificate from the registry is ever offered to a proxy - an entry names a host the user trusts with that identity, and a proxy is not it. A proxy certificate that is refused is an SSL_ERROR whose message says the proxy's certificate was not accepted, so the target's is not blamed.

In-progress (running/pending) runs are never pruned, and neither are runs pinned as baselines (see PUT /runs/:runId/baseline); neither kind counts toward maxRunsRetained or maxDesignRunsRetained. Each cap counts only its own kind: load and collection runs under maxRunsRetained, design Sends under maxDesignRunsRetained; runRetentionDays applies to every kind.

GET /request-defaults

What the engine will add to a request that names none of it - the set a client renders beside the request's own headers instead of re-deriving it from the config entries above.

{
  "headers": [
    { "name": "User-Agent", "value": "Vayu/0.25.0", "generated": false },
    { "name": "Accept-Encoding", "value": "gzip, deflate", "configKey": "negotiateCompression", "generated": false },
    { "name": "X-Vayu-Request-Id", "generated": true, "configKey": "correlationIdEnabled" },
    { "name": "Expect", "value": "100-continue", "configKey": "sendExpectContinue", "generated": false }
  ]
}

The Expect row appears only while sendExpectContinue is on, under both scopes, and describes what libcurl may send above 1 MiB rather than a header on every request.

A default that is switched off is absent rather than listed as disabled. generated: true means the value is made per send, so the row carries no value at all - an empty string would be a value a client would print. configKey names the setting that governs the row, and is absent for the User-Agent, which is always added.

?scope=design|load names the send the answer describes, and defaults to design. Compression is the one default the two resolve differently: a design send (a Send, a collection run, a script's own request) reads negotiateCompression and a load run reads loadNegotiateCompression, so with the two disagreeing the Accept-Encoding row is present under one scope and absent under the other. A scope that is neither is refused with 400 and code invalid_scope rather than served the design answer, which would describe a run the caller is not asking about; an empty ?scope= is absent rather than a scope of "", and answers for design.

POST /config

Update one or more configuration entries. Two body shapes are accepted:

Batch - update several keys at once:

{ "entries": { "workers": "16", "defaultTimeout": "30000" } }

Single - update one key:

{ "key": "workers", "value": "16" }

In both shapes, non-string values (numbers, booleans) are coerced to strings. Each key is validated against its registered type and, for integer / number entries, its min/max range; boolean entries must be "true" or "false"; enum entries (e.g. defaultHttpVersion) must equal one of that entry's stored options values. "Unknown" means outside this engine's own catalogue (see GET /config) - a stored row from a different engine's build does not make a key known to this one. Validation is all-or-nothing: if any key is unknown or out of range, nothing is applied and the response is 400 with the specific reason(s):

{ "error": { "code": "invalid_config", "message": "'workers' must be at most 128 (got 9999)" } }

A body that does not parse, or nests deeper than 128 levels (see Request bodies), is a 400 with the same code.

Success response: 200 - the full updated entries array (same shape as GET /config) plus "success": true.

The validation and the write are one lock scope, and the write is one transaction (issue #1453): a reader (GET /config, or an internal reader like the proxy policy resolver that reads proxyMode and proxyUrl as two separate calls) can never observe some of a batch's keys applied and the rest still stale, and a failure partway through the write leaves every row unchanged rather than the ones written before it.

Workspace

POST /workspace/backup

Write one compacted snapshot of the workspace database into backups/ beside it, then prune older snapshots to maxBackupsRetained (issue #987). Takes no body.

{
  "path": "/home/someone/.local/share/vayu/db/backups/vayu-20260827-124932-118.db",
  "sizeBytes": 2097152,
  "createdAt": 1787745600000,
  "pruned": 1
}
Field Meaning
path The snapshot written. The whole point of the response: restoring is a file copy you perform yourself
sizeBytes Its size on disk. A compacted copy, so smaller than the live database
createdAt When it was taken, epoch milliseconds - the stamp its file name carries
pruned How many older snapshots retention removed in the same call

It runs SQLite's VACUUM INTO, which is why it is safe while the engine is working. Copying vayu.db by hand is not: the -wal beside it holds committed transactions the main file does not, so a hand copy is a database missing its most recent writes. VACUUM INTO reads one consistent snapshot and writes a defragmented database complete on its own, and is read-only with respect to the workspace.

A second backup while one is running is a 409. Two concurrent copies would each write a whole second database - unbounded disk for a button someone double-clicked - and the second would race the first's retention pass. Anything else that goes wrong is a 500 naming what SQLite or the filesystem refused; there is no success response with an empty path.

Retention only removes files Vayu wrote: this endpoint's vayu-<stamp>.db, and the vayu-<stamp>-pre-v<N>.db an update saves before it migrates the workspace, which counts toward the same maxBackupsRetained (db-schema.md). A copy you put in that directory yourself is left where it is. 0 keeps every snapshot.

There is deliberately no restore endpoint. A running engine overwriting the database file it holds open is the failure this feature exists to prevent. Restore by hand with the engine stopped - see architecture.md.

Collections

Collections are folders that organize requests in a hierarchy.

GET /collections

List all collections, ordered by order, then createdAt, then id (see Ordering); nothing in the trash.

Query Parameters: - q, limit, offset (optional): one page of the collections whose name holds q, in the {data, pagination} envelope - see Paged lists. A bad limit or offset is a 400 (invalid_limit, invalid_offset).

Response (none of the three):

[
  {
    "id": "col_1234567890",
    "name": "My API",
    "parentId": null,
    "variables": {},
    "order": 0,
    "createdAt": 1234567890
  }
]

POST /collections

Create a collection. Create only - see Resource writes for the shared contract and the null-vs-absent rule.

Request:

{
  "name": "My API",        // Required, no default (null is a 400)
  "parentId": null,         // Optional, null or "" for root (stored as null); a trashed collection is a 409
  "order": 0,               // Optional, 0..2147483647; appended after siblings if omitted - see Ordering
  "variables": {},          // Optional, collection-scoped variables
  "auth": {"mode": "none"}, // Optional, default none; never mode "inherit" - see Collection auth
  "dataSchema": {},         // Optional, the declared data contract - see below
  "openapi": {},            // Optional, the bound spec document - see below
  "specFile": {},           // Optional, the bound spec file - see below
  "dataFile": {}            // Optional, the bound data file - see below
}

Response: The created collection object, carrying the engine-generated id.

Errors: 400 if the body carries an id (the engine owns it), if name is missing or null, if name is empty or whitespace-only (#3253), if a variables key is blank or padded (#3251), if auth states mode inherit (#3445) or a mode outside the known set, if an openapi binding names no stored spec (below), if parentId is neither a string nor null (Accepted field shapes), if order is not an integer from 0 to 2147483647 or an append finds no slot left (Ordering), or on a cycle (below); 409 if parentId names a collection in the trash (below); 413 naming the field, its size and the cap, when a serialized variables / auth / dataSchema / openapi / specFile / dataFile is over the engine's field cap, or a file binding's path or fileName is over its own (below).

A storage failure answers 507, 503 or 500, never 400 - see A storage failure is not a 400.

PUT /collections/:id

Update an existing collection. Update only - a 404 when the id does not exist, never a silent create. The body is a merge-patch: an omitted field keeps its value, an explicit null resets it to the default.

Request:

{
  "name": "Renamed",       // Optional; null is a 400 (no default)
  "parentId": null,         // Optional, null or "" moves it to the root; a trashed collection is a 409
  "order": 3,               // Optional, 0..2147483647; a move with no order appends - see Ordering
  "variables": null,        // Optional, null resets to {}
  "auth": null,             // Optional, null resets to {"mode":"none"}; never mode "inherit" - see Collection auth
  "dataSchema": null,       // Optional, null clears the declared contract
  "openapi": null,          // Optional, null or {} unbinds the spec document; nothing else
  "specFile": null,         // Optional, null unbinds the spec file
  "dataFile": null          // Optional, null unbinds the data file
}

A parentId that changes the collection's parent and states no order appends the collection among its new siblings, rather than carrying a position from the list it just left. See Ordering.

A parentId that takes the collection out of the spec contract that answers for the requests beneath it is removing them from that contract (#3470), the rule PUT /requests/:id applies to one request, with the same meaning of out: every request in the subtree that records an operation (specOperation) and whose nearest binding after the move names another document, none, or the same document from a collection outside the source's contract has its stamp cleared, and the operation is recorded as declined under the binding it left, in the same transaction as the collection's own row, so the source's POST /specs/diff lists it under declined rather than added. The binding after is read against the tree the PUT writes, so an openapi: null in the same body counts: a bound collection unbound and moved out at once clears its requests' stamps, and the decline that records under it is forgotten with the binding's other records (below). A move within one contract keeps every stamp, and so does moving the bound collection itself. The response is the collection; the cleared requests are read back with GET /requests/:id or arrive on the change feed. This is the decline POST /reorder records for a moved folder.

Headers: If-Match (optional), see Conditional updates.

Response: The updated collection object, with its ETag.

Errors: 404 if the collection does not exist; 412 if If-Match no longer names the stored row; 400 on a null or empty or whitespace-only name (#3253), a malformed If-Match, a blank or padded variables key (#3251), an auth that states mode inherit (#3445) or a mode outside the known set, an openapi that is neither null nor {} (binding is POST /specs/bind, issue #3348, below), a parentId that is neither a string nor null (Accepted field shapes), an order that is not an integer from 0 to 2147483647 or an append with no slot left (Ordering) or on a cycle (below); 409 if parentId names a collection in the trash (below); 413 naming the field, its size and the cap, when a serialized variables / auth / dataSchema / openapi / specFile / dataFile is over the engine's field cap, or a file binding's path or fileName is over its own (below).

A storage failure answers 507, 503 or 500, never 400 - see A storage failure is not a 400.

Cycle validation (both verbs): parentId is validated to keep the collection tree acyclic, since a cycle would make the cascade delete below loop forever. Both cases return 400:

  • parentId equal to the collection's own id - message A collection cannot be its own parent.
  • parentId pointing at one of the collection's own descendants (a reparent that would form a cycle) - message Cannot move a collection into its own descendant.

Parent existence is intentionally not checked: the import orchestrator creates collections in bulk, so requiring the parent to exist first would couple to import ordering. Only self-parent and descendant cycles are rejected.

A parent in the trash (both verbs) is a 409, message Collection '<id>' is in the trash - restore it first (issue #1883). That is different from a parent the store has never seen: a trashed parent would leave the collection live but invisible under it, and a purge of the parent would then re-parent it to the root. Only a parentId the body states is checked, so a PUT that does not move the collection is never refused by its stored parent.

dataSchema (both verbs, and POST /import/apply): the data contract the collection declares - which columns its data files carry, so {{data.column}} and pm.iterationData can be checked before a run (issue #599).

{"columns":["id","email"],"declaredAt":1700000000000,"fileName":"users.csv"}

{} means the collection declares no contract, and is what an absent field on create and an explicit null on update both resolve to. A present value must be an object (400 otherwise, like variables and auth), and its contents are validated: columns an array of unique, non-empty strings - at most 1024 of them, each at most 256 characters - declaredAt a number, fileName a string. Each violation is a 400 naming the field (Invalid 'dataSchema.columns': ...) that writes nothing.

The schema is stored; the file's rows are not, anywhere. Where the file is lives in dataFile, below. See Data-driven runs.

openapi (POST /collections, POST /import/apply, and unbinding on PUT): the OpenAPI document this collection is bound to (issue #637).

{"specId":"spec_3f2b1c9a-...","specHash":"<hex sha256>","syncedAt":1700000000000}

{} means bound to nothing, and is what an absent field on create and an explicit null on update both resolve to. A present value must be an object (400 otherwise, like variables and dataSchema). A non-empty one is a binding and is validated further: specId must be a non-empty string that resolves to a stored spec document (400 naming the id otherwise).

PUT /collections/:id only unbinds (issue #3348): {"openapi": null} and {"openapi": {}} both store {}, and any other value is a 400 that names POST /specs/bind, after the 404 and 412 checks. Binding or rebinding an existing collection restamps every request beneath it both ways, which only that route does, in one transaction. Unbinding forgets the operations deletes declined under the old document (issue #3031; see DELETE /requests/:id).

specHash records which version of the document the collection was last synced to; a scenario run of a bound collection stamps both values into its snapshot and report (see GET /runs/:runId/report).

Send the specId; the engine writes the rest (issues #709, #3348): a create stamps specHash from the document the id names and syncedAt from the moment of the write, so a binding cannot be stored without the version that contract coverage and response-schema validation compare against. A specHash or syncedAt the body sends is dropped, never stored: the version is the document's, not the caller's claim about it. A collection's recorded version can still fall behind its document's (a binding an older engine wrote); a run of it reports hash_mismatch, and a PUT that says nothing about openapi leaves it as it is.

Deleting the document is refused while a collection binds it - the binding is never cascaded away, see DELETE /specs/:id.

specFile and dataFile (both verbs; refused by POST /import/apply): the files this collection's Spec and Data tabs are bound to (issue #2765), stored so a workspace backup carries them.

{"path":"/home/me/specs/pets.yaml","fileName":"pets.yaml"}
{"path":"/home/me/data/users.csv","fileName":"users.csv","hash":"<hex sha256>","castNumbers":true}

{} means no file, and is what an absent field on create and an explicit null on update both resolve to, so unbinding is {"specFile": null}. A present value must be an object (400 otherwise). A non-empty one must carry path and fileName as non-empty strings and no member beyond its own: specFile holds those two, dataFile adds an optional hash (64 lowercase hex characters, the SHA-256 of the file's bytes, the digest a run records as dataFileHash) and an optional boolean castNumbers. Each violation is a 400 naming the field or member that writes nothing; a path over 96 KiB or a fileName over 1 KiB is a 413 naming the member, its size and the cap. The path's form is not checked: it is the location on the machine that picked the file, so a Windows path is stored on Linux as written. A stored path grants nothing - a request body may send a file only under the file trust rule - and the engine never opens either file. Neither field appears in POST /export/postman or POST /specs/export. A POST /import/apply collection item carrying either is a 400 with error.item, because an import describes a document from elsewhere; null passes.

DELETE /collections/:id

Delete a collection and all its requests (cascading delete). The delete is soft (issue #988): the collection and every descendant are stamped deleted_at in a single transaction rather than removed, which is why every read surface stops returning them while GET /trash still can. The walk terminates even if the stored parent_id tree contains a cycle (see db-schema.md - collections).

Restore it with POST /trash/:id/restore; destroy it for good with DELETE /trash/:id, which is also what the startup sweep does once trashRetentionDays has passed.

Beneath a bound collection, the delete declines operations (issue #3031), as DELETE /requests/:id does for one request: each request it stamps that records an operation is recorded under the nearest bound ancestor, in the same transaction. Deleting a tag folder is the user declining everything in it. Deleting the bound collection itself records nothing - that is the whole contract going, not a choice about any operation of it - and a purge of a bound collection takes its records with it.

The delete stops every running mock of what it trashed (issue #3449): a mock of the collection itself or of any folder under it, whichever client sent the delete, before the response is sent, so it is gone from GET /mock by then. A mock of a collection outside the subtree keeps running. Restoring the collection does not start its mock again; POST /mock/start does.

Response:

{
  "message": "Collection deleted successfully",
  "id": "col_1234567890"
}

Requests

GET /requests

List requests in a collection, or in every live collection. Results are ordered by order, then createdAt, then id - the same contract GET /collections has for collections. See Ordering for why the tiebreak is part of the contract.

Query Parameters: - collectionId (optional): Collection ID to fetch requests from. Absent, the response is every live request of every live collection, grouped by collectionId and ordered within each group exactly as that collection's own list is - nothing in the trash. - fields (optional): summary answers each row cut to the keys a tree is built from (#2546), described below; absent (or empty), the full request objects. Any other value is a 400 with code invalid_fields, never the full list. The app builds its whole tree at launch from one GET /requests?fields=summary call. - q, limit, offset (optional): one page of the rows whose name holds q, in the {data, pagination} envelope - see Paged lists. Each data row is the row the list would have carried, in the shape fields names, and collectionId scopes it as above. A row that fails to serialize is skipped (as it is in the bare list) and is not counted in total. A bad limit or offset is a 400 (invalid_limit, invalid_offset); a bad fields is refused first.

Summary response (fields=summary): the same rows in the same order as the full form, each carrying exactly id, collectionId, name, method, url, order, createdAt and specOperation, spelled and valued as the full row writes them (specOperation is the object or null). Nothing else is read from the database, so a large body, header set, auth block or element list costs its row nothing, and no row carries truncatedFields.

[
  {
    "id": "req_1234567890",
    "collectionId": "col_1234567890",
    "name": "Get Users",
    "method": "GET",
    "url": "{{baseUrl}}/users",
    "order": 0,
    "createdAt": 1234567890,
    "specOperation": null
  }
]

Response (no fields): An array of request objects, each in the same shape as a GET /requests/:id response: params/headers are arrays of {key, value, enabled} entries and body is a JSON discriminated union (see the requests table in db-schema.md) - with one deliberate exception (issue #1485): a row whose params / headers / body / auth is over the engine's field cap carries that field's documented default here instead of the stored value, and names which fields were substituted in truncatedFields (omitted when nothing was). GET /requests/:id never substitutes - it answers with the field whole, however large.

[
  {
    "id": "req_1234567890",
    "collectionId": "col_1234567890",
    "name": "Get Users",
    "description": "",
    "method": "GET",
    "url": "{{baseUrl}}/users",
    "order": 0,
    "params": [{ "key": "page", "value": "1", "enabled": true }],
    "headers": [{ "key": "Accept", "value": "application/json", "enabled": true }],
    "body": { "mode": "none" },
    "bodyType": "none",
    "auth": { "mode": "inherit" },
    "elements": [],
    "followRedirects": true,
    "maxRedirects": 10,
    "timeout": null,
    "httpVersion": "auto",
    "verifySSL": true,
    "stream": false,
    "disableCookies": false,
    "disabledSystemHeaders": [],
    "disableUrlEncoding": false,
    "postmanProtocolBehavior": null,
    "updatedAt": 1234567890,
    "createdAt": 1234567890
  }
]

followRedirects / maxRedirects / httpVersion / verifySSL / stream are the request's stored execution options. They are always present in the response: a request saved before these columns existed reads back as the engine defaults (true / 10 / "auto" / true / false), which is the behaviour it already had. timeout is the request's own timeout in milliseconds (issue #2937), always present on a stored-row response (GET /requests, GET /requests/:id and the POST / PUT answers): a number, or null when the request states none and sends with the defaultTimeout setting. disableCookies / disabledSystemHeaders / disableUrlEncoding are Postman's per-request protocol settings (issue #1765), always present too (false / [] / false for a request that states none); postmanProtocolBehavior is the imported Postman object they came from, null when there is none - see POST /requests. httpVersion is "auto" | "http1.1" | "http2" - what was requested, not what was negotiated; see POST /execute for the negotiated value on a response.

GET /requests/:id

Fetch a single request by id, in one lookup. The app uses this to load a restored request tab or a design-run copy on cold start, instead of fetching every collection's request list and scanning them for the id.

Path Parameters: - id (required): The request ID to fetch

Response: The request object, in the same shape as a full GET /requests list entry, with its ETag (W/"<updatedAt>", see Conditional updates).

{
  "id": "req_1234567890",
  "collectionId": "col_1234567890",
  "name": "Get Users",
  "description": "",
  "method": "GET",
  "url": "{{baseUrl}}/users",
  "order": 0,
  "params": [],
  "headers": [],
  "body": { "mode": "none" },
  "bodyType": "none",
  "auth": { "mode": "inherit" },
  "elements": [],
  "followRedirects": true,
  "maxRedirects": 10,
  "httpVersion": "auto",
  "verifySSL": true,
  "stream": false,
  "createdAt": 1234567890,
  "updatedAt": 1234567890
}

404 when the request genuinely does not exist. This is distinct from a 5xx: the caller relies on that difference to tell a real deletion from an unreachable engine, and must not treat a transport failure as "deleted".

POST /requests

Create a request. Create only - see Resource writes for the shared contract and the null-vs-absent rule.

Request:

{
  "collectionId": "col_1234567890", // Required, no default (null is a 400)
  "name": "Get Users",               // Required, no default (null is a 400)
  "method": "GET",                   // Required: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
  "url": "{{baseUrl}}/users",        // Required, no default (null is a 400)
  "params": [],                      // Optional, array of {key, value, enabled, in?, valueless?};
                                      // derived from `url`'s query when absent - see below
  "headers": [],                     // Optional, array of {key, value, enabled}
  "body": {"mode": "none"},          // Optional, request body
  "bodyType": "none",                // Optional, mirrors body.mode - see The request body union
  "auth": {"mode": "inherit"},       // Optional, default {"mode":"inherit"}; mode must be a known one - see Auth modes
  "elements": [],                    // Optional, typed behaviours - see Elements. The only
                                      // script source; preRequestScript/postRequestScript/tests
                                      // are refused (400, naming "elements")
  "order": 0,                        // Optional, 0..2147483647; appended after the collection's
                                      // sub-collections and requests if omitted - see Ordering
  "followRedirects": true,           // Optional, follow 3xx responses. Default true
  "maxRedirects": 10,                // Optional, hops while following, clamped to 0..100. Default 10
  "timeout": null,                   // Optional, this request's timeout in ms, 1..86400000.
                                      // Absent/null: the "defaultTimeout" setting - see below
  "httpVersion": "auto",             // Optional: "auto" | "http1.1" | "http2". Absent/null seeds
                                      // from the "defaultHttpVersion" config entry
  "verifySSL": true,                 // Optional, verify the TLS certificate. Default true
  "stream": false,                   // Optional, consume the response as an event stream.
                                      // Default false - see below
  "specOperation": null,             // Optional, which spec operation this request is - see below
  "methodSource": null,              // Optional, which app setting wrote `method` - see below
  "mockResponseMode": "first",       // Optional: "first" | "fixed" | "random". Default "first"
                                      // - which saved example a mock server answers with, see below
  "mockExampleId": null,             // Optional, the example id `mockResponseMode: "fixed"` targets
  "disableCookies": false,           // Optional, keep the cookie jar out of this request. Default false
  "disabledSystemHeaders": [],       // Optional, header names the engine does not add. Default []
  "disableUrlEncoding": false,       // Optional, send the URL as typed, with no percent-encoding.
                                      // Default false
  "postmanProtocolBehavior": null    // Optional, the imported Postman object - see below
}

A query row in params describes the query in url; url is the wire truth. Nothing in the request-composition path reads a query row, so a query parameter that must reach the wire belongs in url: a caller that puts the query only in params stores a request that sends none of it (issue #590). The write keeps the rows in step with the URL (issue #3551). A POST or PUT that states url and no params has its query rows reconciled with the URL's query, the rule the app's Params table follows on every URL keystroke (mergeParamsFromUrl):

  • each enabled row claims the first unclaimed pair whose key its own key writes (under any of the query joins, so an OpenAPI import's a b claims a%20b), rows in stored order, and the merged rows follow the URL's pair order;
  • a claimed row keeps every other member (description, source, ...); one that no longer writes its pair takes the pair's key and value, and valueless follows the pair (true for a bare key with no =);
  • a pair no row claims becomes a fresh {key, value, enabled: true} row (plus valueless: true for a bare key), and an enabled row the URL no longer carries is dropped;
  • a disabled row is kept, after the nearest enabled row before it that the URL still carries, or first when there is none; path rows are left untouched.

Rows that already state the URL's query are left byte for byte, so a host or path edit sent as url alone rewrites nothing. A body that states params stores them as sent, whatever url says, and a body that states neither keeps the stored rows. POST /import/apply and POST /specs/sync reach the same applier: a sync update that applies a request's url without its params reconciles the kept rows with the new URL's query. So a request created from a URL alone (every MCP request) reads back with one row per query pair, and the OpenAPI export, the spec diff and the Postman export see its query. Rows stored before the rule are not rewritten until their next URL-only write, so the Postman export still writes a URL pair no enabled row states into url.query[] (issue

3242), and the app still merges a URL-only query into the Params table when

it opens one, without marking the tab unsaved (issue #3491).

A path row is the one row composition reads (issue #1764). A row carrying "in": "path" is a Postman-style path variable: key is the name without its colon, and the URL keeps the :name segment verbatim ({{baseUrl}}/users/:id). POST /compose writes the row's value in place of the segment at send time - see Path variables there. A row with in absent, "query" or anything else is a query row, and everything that joins or splits the query (the importers' URL join, the Postman and OpenAPI exports) skips path rows. The field needs no schema change: rows are stored verbatim, extra keys included.

stream is the saved half of POST /execute's stream (issue #574). It records that this endpoint is a text/event-stream, which is a property of the endpoint rather than of one send, so the app's Event stream toggle persists here and a bulk import carries it. The engine never acts on the stored value by itself: POST /execute reads the flag off the payload it is given, and the by-id compose path deliberately does not add it, so an existing caller that composes by id keeps getting a buffered send.

timeout is the saved half of POST /execute's timeout (issue #2937): one slow endpoint can wait longer, or a fast one fail sooner, without changing the defaultTimeout setting for every request. It is held to the same 1-86400000 ms, and a number outside it or a value that is not a number is a 400 naming 'timeout' here, on PUT and in POST /import/apply. Absent or null on create stores none, and the request sends with the setting in force at each send rather than a copy of it. POST /compose by requestId emits timeout only when the request states one, so a Send, a sequential collection run, a single-request load run built from the composed payload and a scenario load step all take it, and a request that states none still takes the setting. A Postman collection has no per-request timeout, so POST /export/postman lists one under notCarried (request_timeout); an OpenAPI export carries it in x-vayu-request.settings.

specOperation names which operation of the collection's bound spec this request is (issue #637):

{"operationId": "listPets", "method": "GET", "path": "/pets/{petId}"}

method and path are required inside the object and operationId is optional, because an OpenAPI operation may declare none. path is the templated path from the document, never a concrete URL - it is the identity a re-fetched spec is diffed against - so a path that does not start with / is a 400, as is a missing or empty method / path, a non-object value, or a non-string operationId. null (or absent on create) means the request declares no operation, and both request serializers emit specOperation: null for it - the key is always present, so a client never has to tell "no operation" from "not serialized". Two requests may name the same operation.

methodSource names which app setting last wrote method, still unclaimed by the user (issue #1505). The only value a client writes is "graphql" - the GraphQL body mode setting method to POST on a fresh GET - and null (or absent on create) means no marker: either the user chose method themselves, or nothing has set it. "graphql" is the only accepted value; anything else is a 400. The app clears the marker itself the moment method is written by anything other than the GraphQL switch, so a method the user has since picked is never reverted - the same "still ours" contract KeyValueEntry.source (issue

1481) gives a header row.

mockResponseMode names which saved example a mock server answers with (issue #481 phase 3): "first" (the default, absent or null on create both mean this), "fixed" (the example named by mockExampleId) or "random". Anything else is a 400, the same way an unrecognized methodSource is. mockExampleId follows the same null-vs-absent rule as specOperation: absent keeps the current target, null clears it, and a non-empty string sets it - it is not checked against the request's saved examples at write time, because the target can be created afterwards or deleted later, and a mock server falls back to "first" for either case rather than this write refusing one up front. Deleting the target through DELETE /requests/:id/examples/:exampleId clears mockExampleId to null (issue #3422) and leaves mockResponseMode as it was; restoring the example from the trash does not set it again.

Postman's per-request protocol settings (issue #1765), under the same null-vs-absent rule (absent keeps on update, null resets):

  • disableCookies keeps the cookie jar out of every send of this request: no jar cookie is attached and no Set-Cookie is stored. A Cookie header the request carries still goes out, and a pre-request script's pm.cookies.jar() write is still persisted. With the jar on, a typed Cookie and the jar's matches go out as one Cookie line, the jar's first, never as two (issue #2788). The one case it does not go out is a jar line that reaches libcurl's 8190-byte limit: libcurl drops the typed rows with the jar cookie it leaves off, and the answer says so under warnings (cookie_not_sent, issue #3307).
  • disabledSystemHeaders names headers the engine does not add on its own. It is stored lowercased and deduplicated in first-appearance order, and unioned on every send with the per-send disabledDefaultHeaders (see POST /execute): user-agent, accept-encoding and the correlation id as that list refuses them, accept removes libcurl's implicit Accept: */*, content-type removes the Content-Type a body implies (multipart keeps its boundary header), and with it a Content-Type header row marked "source": "body-mode" - the row the app's Body panel writes and the importer adds for a GraphQL, JSON-RPC or XML body, which is the body's own header, not the user's. A Content-Type row without that marker is the user's and is always sent. Other names (host, content-length, postman-token, ...) are stored for the export and change nothing on the wire.
  • disableUrlEncoding writes the URL as typed rather than percent-encoded: a path variable's value skips Postman's path encode set, an api-key (or OAuth 2.0 query-placed) credential and a substituted {{variable}} skip their rules, and the rest of the URL is not rewritten either (Query encoding), so a"b goes out as a"b, not a%22b, as Postman's toNodeUrl (url, disableEncoding) sends it. With encoding on, a raw space is percent-encoded to %20; with the toggle on it is refused, and the send fails with a message that names the space and the toggle (URL schemes).
  • postmanProtocolBehavior is the Postman item's protocolProfileBehavior, kept for POST /export/postman and sent by nothing. It takes an object or a string holding a JSON object; the string is the spelling the importer writes, because it keeps the source's member order (an object crossing the engine's reader does not). GET answers it as that stored text, a string (or null), the way it is written: a client that sends the record back, as the app's Duplicate does, stores the same bytes, and the copy exports the same protocolProfileBehavior. The string is read again by the engine, so it is held to the request-body depth bound too (see Request bodies): a string nested deeper than 128 levels is a 400.

A non-boolean disableCookies / disableUrlEncoding, a disabledSystemHeaders that is not an array of header-name tokens, or a postmanProtocolBehavior that is not an object, such a string or null is a 400 naming the field, as is a postmanProtocolBehavior string nested deeper than 128 levels (Invalid 'postmanProtocolBehavior': nested deeper than 128 levels); the last two are 413 over the field cap. POST /import/apply answers the same 400, with the item's tempId under error.item, and writes nothing.

Response: The created request object, carrying the engine-generated id.

Errors: 400 if the body carries an id (the engine owns it), if a required field is missing or null, if collectionId names a collection that does not exist (message Collection '<id>' does not exist), on an unrecognized method, on a params / headers entry that is not {key: string, value: string, enabled: bool}, on a methodSource that is not "graphql" or null, on a mockResponseMode that is not "first" / "fixed" / "random", on a mockExampleId that is not a non-empty string or null, on an order that is not an integer from 0 to 2147483647 or an append that finds no slot left (Ordering), on an auth whose mode is not a known one (#3464), or on an httpVersion that is not "auto" / "http1.1" / "http2" (the body names the field and lists the valid values); 413 naming the field, its size and the cap, when a serialized params / headers / body / auth is over the engine's field cap (issue #1485, see below).

A storage failure answers 507, 503 or 500, never 400 - see A storage failure is not a 400.

Unlike a collection's parentId (which may name a collection not written yet, though not one in the trash), a request's collectionId must resolve to a stored collection. A request under no collection is unreachable: no per-collection GET lists it, and no cascade delete ever reaps it. Bulk import is unaffected - POST /import/apply resolves owners from the payload's own temp ids before any row is written.

PUT /requests/:id

Update an existing request. Update only - a 404 when the id does not exist, never a silent create. Merge-patch body, same rule as collections.

Request: any subset of the POST /requests fields, minus id (it is the path). Sending collectionId moves the request to another collection; the id must resolve to a stored collection (400 otherwise), and a move that states no order appends in the destination - see Ordering. An update that states no collectionId is not checked against the request's stored one, so a row stranded before this validation existed stays editable, and repairable by a PUT that moves it somewhere real. A move that takes a request recording an operation (specOperation) out of the spec contract that answers for it is removing it from that contract (#3446): out means the destination's nearest binding names another document, none, or the same document from a collection outside the source's contract (a sibling root bound to it too). The operation is recorded as declined under the source binding, as DELETE /requests/:id records it, and the stamp is cleared in the same write, so the source's POST /specs/diff lists it under declined rather than added. A move within one contract keeps the stamp, a move between the bound collection and a sub-collection bound to the same document included; a body that states specOperation beside the move keeps the stated value. Omitting followRedirects / maxRedirects / timeout / verifySSL / stream / specOperation / methodSource / mockResponseMode / mockExampleId / disableCookies / disabledSystemHeaders / disableUrlEncoding / postmanProtocolBehavior leaves the stored values untouched; sending null resets them to true / 10 / "the defaultTimeout setting" / true / false / "no operation" / "no marker" / "first" / "no target" / false / [] / false / "none". A non-boolean followRedirects, verifySSL or stream, or a non-integer maxRedirects, is ignored rather than rejected. maxRedirects is clamped to 0..100 on the way in. timeout is the exception among them: a value outside 1-86400000 or one that is not a number is a 400 naming 'timeout', and nothing is written. order is held the same way (#3451): a stated value that is not an integer from 0 to 2147483647 is a 400 naming 'order', so {"collectionId": "col_2", "order": "9"} refuses the move rather than making it at the old position - see Ordering.

httpVersion follows the same null-vs-absent rule as the fields above, but validates more strictly: absent keeps the stored value; explicit null resets it to the live defaultHttpVersion config value; a recognized string stores as given; anything else - an unrecognized string, or a non-string - is a 400 naming the field and the valid values, never silently coerced. Changing the global defaultHttpVersion afterward does not retroactively alter a request already saved; only an explicit null on this request re-seeds it.

preRequestScript, postRequestScript and tests are refused. Issue

1514's cut-over is a clean cut, not a transitional alias: any of these three

keys present (even null is accepted as a no-op, but a real value is not) is a 400 naming elements as the replacement. Scripts are elements now - {"kind": "script.pre" | "script.post", "config": {"script": "..."}}.

elements (issue #1513, run by issue #1514's pipeline) takes the array rule: absent keeps the stored list; null resets it to []; a present value must be an array the element registry accepts (see Elements) or the write is a 400 naming the index, the kind and the field. That includes a kind's own rules beyond its schema: a JSONPath outside the supported subset, a pattern RE2 does not compile ('pattern' is not a valid regular expression - <reason>, likewise 'regex' and 'text', #3043), an assert.status with neither a non-empty in nor a range, an assert.jsonpath with none of expected, regex or exists, and one that sets exists beside expected or regex (#3049), and what the engine would otherwise accept and ignore (#3055): a control.throughput naming neither or both of percent and everyN, a timer.think with no ms, gaussian or minMs + maxMs pair, an assert.contains with an empty text in contains mode, and an extract.* variable no {{name}} can read (a brace in it, whitespace at an edge, the data. namespace, $vu or $iteration). The only script source - GET /requests/:id and every full list response carry it and no longer carry preRequestScript / postRequestScript at all.

auth.postman, the Postman block an import kept beside the mapped auth (see db-schema.md), is kept on a write only while mapping it through the Postman importer still gives the auth being written; otherwise it is dropped. So a changed credential never leaves the old one behind in the stored block, whichever client wrote it, and a save that changed nothing keeps it. POST /requests, POST /collections, PUT /collections/:id and POST /import/apply apply the same rule.

Headers: If-Match (optional), see Conditional updates.

Response: The updated request object, with its ETag.

Errors: 404 if the request does not exist; 412 if If-Match no longer names the stored row; 400 on a malformed If-Match, on a null collectionId / name / method / url, a collectionId naming a collection that does not exist, an unrecognized method, a malformed params / headers entry, a malformed specOperation, a methodSource that is not "graphql" or null, a mockResponseMode that is not "first" / "fixed" / "random", a mockExampleId that is not a non-empty string or null, an auth whose mode is not a known one (#3464), a malformed protocol setting (see POST /requests), or an httpVersion that is not "auto" / "http1.1" / "http2"; 413 naming the field, its size and the cap, when a serialized params / headers / body / auth is over the engine's field cap (issue #1485, see below).

A storage failure answers 507, 503 or 500, never 400 - see A storage failure is not a 400.

DELETE /requests/:id

Delete a request. The delete is soft (issue #988) - the row is stamped deleted_at and GET /trash lists it until a purge. Its saved examples stay on the row rather than being removed: every read of them is by request id and runs the owner check first, so they are as unreachable as the request is, and a restore gets them back with it. A purge takes them.

Deleting the request for an operation declines the operation (issue

3031). When the request records an operation (specOperation) and a

collection above it binds a document, the same transaction records that operation under the nearest bound ancestor in spec_declined_operations. POST /specs/diff then lists the operation as declined rather than added, and a policy: "safe" sync never re-creates it, so a sync of the unchanged document cannot bring the request back. Restoring the request from the trash forgets the record, and so does a sync that creates the operation on purpose; purging the request, by hand or by trashRetentionDays, does not - the decision outlives the row it was made on. Unbinding the collection, or binding it to a document with other bytes, forgets every record under it. A sync's own deletes record nothing. Moving the request out of the contract records the same decline (#3446, see PUT /requests/:id and POST /reorder), and so does moving a folder above it out with PUT /collections/:id (#3470); the move clears the stamp, and a restore forgets only the record of a request that still records an operation, so deleting and restoring the moved request later leaves the source's record standing.

Response:

{
  "message": "Request deleted successfully",
  "id": "req_1234567890"
}

Elements

GET /elements/kinds

The element registry's catalogue (issue #1513): every kind a request's or collection's elements array may name, whatever the engine build actually registers - a kind added in one file (engine/src/core/elements/) appears here with nothing else changed, per Elements's extensibility contract. This is what #1516 (app) and #1517 (MCP) render a kind's editor from, and what docs/engine/elements.md's kind table is checked against.

Response:

[
  {
    "kind": "inherit.disable",
    "version": 1,
    "phases": [],
    "label": "Disable inherited element",
    "description": "Drops one element inherited from an ancestor collection, named by id, out of this request or collection's resolved list.",
    "category": "inherit",
    "hotPathClass": "declarative",
    "collectionOnly": false,
    "configSchema": {
      "type": "object",
      "properties": {
        "elementId": {
          "type": "string",
          "minLength": 1,
          "title": "Element to disable",
          "description": "The id of an inherited element to drop from this request or collection's resolved list."
        }
      },
      "required": ["elementId"],
      "additionalProperties": false
    }
  }
]

Every property of every kind's configSchema carries a title and a description (issue

1607), plus, where relevant, x-vayu-group: "advanced" (folds the property under a disclosure)

or x-vayu-unit ("ms", "%" or "B", a numeric suffix to render) - see Elements. A property the engine gives a value when its key is absent also carries default (issue #3045), taken from the constant the kind reads - assert.size op is "lte", an extract.* scope is "collection", timer.pacing and control.throughput perUser are true, timer.throughput perUser is false. An absent key means that default; a client shows it without writing the key.

Phase 0 also registers script.pre and script.post, validate-only like inherit.disable - so a request or collection the startup fold migrated (docs/engine/db-schema.md) can be read back and written as-is without its own elements failing the registry that produced them - plus, in the test build only, a test.echo kind proving the registration path. collectionOnly (issue #1499) is true only for script.setup / script.teardown - the app's Add menu on a request hides a kind marked so, and the registry itself refuses one on a request's own elements with a 400. See Elements for the full kind table.

Trash

What deleting a collection, a request, an environment, a saved example or a client certificate now does, and how to undo it (issue #988; environments

2970; examples #2971; client certificates #2973). DELETE /collections/:id,

DELETE /requests/:id, DELETE /environments/:id, DELETE /client-certificates/:id and, for an example a person saved (origin: "user"), DELETE /requests/:id/examples/:exampleId stamp rows instead of removing them; every other read surface filters stamped rows out, so the tree, the environment list, a request's examples and the certificate registry look the same as after a hard delete, and these three endpoints are the whole of what the stamp buys. An imported example is not trashed: its delete leaves the tombstone a spec sync reads (see DELETE /requests/:id/examples/:exampleId).

Two rules decide what a restore of a collection or request puts back:

  • Cohort. One delete stamps its whole subtree with one timestamp, and a restore clears exactly the rows carrying the timestamp of the row it was given. So restoring a collection cannot resurrect a request the user had deleted separately beforehand - that request stays in the trash and becomes a root of its own again, since its collection is live.
  • Re-parent. A restored collection whose parent is gone, or is itself in the trash, comes back at the tree root (parentId cleared). A request has no such root - collectionId is required - so restoring one whose collection is in the trash is a 409 naming the request and its collection by name, and the trash root to restore first by name and id (issue #3449). That root is the listed entry holding the collection: the collection itself, or the ancestor whose delete took it.

An environment needs neither: it owns no rows and hangs under nothing, so its delete stamps one row, it is always a root, and its restore is unconditional. A trashed environment is never active. The delete clears isActive in the same write, so the active slot is free for another environment, and a restore brings it back inactive: making it active again is a PUT with isActive: true, the client's choice rather than the trash's.

An example hangs under its request, one level below where a request hangs under its collection, and follows the request's rule. Its delete stamps its one row. It is a root only while its request is live: under a trashed request it is part of what that request's entry stands for, and restoring the request leaves the example's own earlier delete in the trash as a root again. Restoring an example whose request is in the trash is a 409 naming the example and its request by name, and the trash root to restore first by name and id: the request, or the collection whose delete took it. One whose request is gone is a 409 saying so, and so is restoring one into a request that already holds the maximum of 100 examples. A stamped example whose request row is gone entirely is listed nowhere. The delete clears the request's mockExampleId when it named the example, and the restore does not set it again: choosing it as the fixed mock answer is the client's write, as making an environment active is.

A client certificate hangs under nothing, like an environment: its delete stamps its one row and it is always a root, named by its target (host, or host:port when the entry names a port). A trashed certificate is never presented. The transport policy every send resolves reads live entries only, so from the delete on no new design send, stream, collection run or load run offers it to its host, and the target is free for a new entry. That is also why a restore can be refused: the registry holds one entry per host and port, so restoring a certificate while a live entry claims its target is a 409 naming that entry. The row keeps its passphrase, stored plaintext like every live entry's, until a purge removes it.

Rows sit in the trash until they are purged: explicitly through DELETE /trash/:id, or by the startup sweep once they are older than trashRetentionDays (default 30; 0 keeps them forever).

GET /trash

Everything deleted and still restorable, newest first. Roots only - the rows a user asked to delete, never what their cascade took with them; that is what collections and requests count, and purgeCollections and purgeRequests count what a purge would destroy. Every deleted environment and client certificate is a root; a deleted request is one while its collection is live, and a deleted example while its request is.

Query Parameters: - q, limit, offset (optional): one page of the roots whose name holds q, newest first, in the {data, pagination} envelope instead of {items, total} - see Paged lists. A cascaded row is not a root and never matches. A bad limit or offset is a 400 (invalid_limit, invalid_offset).

Response (none of the three):

{
  "items": [
    {
      "id": "col_1234567890",
      "kind": "collection",
      "name": "Payments API",
      "deletedAt": 1787745600000,
      "parentId": null,
      "collections": 2,
      "requests": 14,
      "purgeCollections": 3,
      "purgeRequests": 16
    },
    {
      "id": "env_1234567890",
      "kind": "environment",
      "name": "Staging",
      "deletedAt": 1787745500000,
      "parentId": null,
      "collections": 0,
      "requests": 0,
      "purgeCollections": 0,
      "purgeRequests": 0,
      "variables": 6
    },
    {
      "id": "exa_1234567890",
      "kind": "example",
      "name": "200 - created",
      "deletedAt": 1787745400000,
      "parentId": "req_1234567890",
      "parentName": "Create payment",
      "collections": 0,
      "requests": 0,
      "purgeCollections": 0,
      "purgeRequests": 0
    },
    {
      "id": "cert_1234567890",
      "kind": "clientCertificate",
      "name": "api.example.com:8443",
      "deletedAt": 1787745300000,
      "parentId": null,
      "collections": 0,
      "requests": 0,
      "purgeCollections": 0,
      "purgeRequests": 0
    }
  ],
  "total": 4
}

kind is "collection", "request", "environment", "example" or "clientCertificate". A client certificate's name is its target, host or host:port, which is what q matches. parentId is a collection's parent (null at the tree root), a request's owning collection, an example's owning request, or null for an environment and a client certificate. parentName (issue #3449) is the name of the row parentId names, carried by a request and an example entry only, so two same-named entries tell apart by their owner. It is absent on the other three kinds, and on a request or example whose owner row is gone, which no write path leaves behind.

collections and requests are the cohort: the sub-collections (the root not counted) and requests this delete took, which is exactly what a restore puts back. purgeCollections and purgeRequests (issue #3449) are what a purge destroys: every deleted sub-collection and request under the root, whichever delete stamped it, stopping at a live collection as the purge does. They are never below the cohort counts, and exceed them when an earlier delete inside the subtree - a request, or a folder with its requests - is waiting under the root, unlisted. All four are 0 for every kind but a collection. variables is carried by an environment entry only - the number of variables its stored map holds - and is absent, not 0, on the other four kinds. An empty trash is {"items": [], "total": 0}, never a 404.

POST /trash/:id/restore

Put a deleted collection, request, environment, example or client certificate back, with everything the same delete took. Takes no body. An environment comes back exactly as it was deleted except that it is inactive (see Trash), and its answer carries variables like its list entry. An example comes back exactly as it was deleted, order included, but its request's mockExampleId, cleared by the delete, stays null (issue #3422); a client certificate comes back exactly as it was, passphrase included. A restored request, alone or with its collection, takes back the operation its delete declined (issue #3031), so the next sync sees it claimed again.

Response: the entry that was restored, plus what happened to it:

{
  "id": "col_1234567890",
  "kind": "collection",
  "name": "Payments API",
  "deletedAt": 1787745600000,
  "parentId": null,
  "collections": 2,
  "requests": 14,
  "purgeCollections": 3,
  "purgeRequests": 16,
  "restored": true,
  "reparentedToRoot": false
}

Errors:

Status When
404 Nothing in the trash carries that id - a live row, or one already purged
409 A request whose collection is itself deleted or gone; the message names the request and its collection, and the trash root to restore first by name and id
409 An example whose request is itself deleted or gone; the message names the example and its request, and the trash root to restore first by name and id
409 An example whose request already holds the maximum of 100 examples; delete one first
409 A client certificate whose host and port a live entry now claims; the message names that entry, to delete first

DELETE /trash/:id

Destroy a deleted collection, request, environment, example or client certificate for good, with its whole subtree - requests, and the examples they own, trashed ones included; an environment, an example or a client certificate is its one row (a certificate's passphrase goes with it), and an environment takes its cookie jar with it. This is the hard cascade soft delete replaced, asked for deliberately; there is no undo for it.

Unlike a restore, a purge is not limited to the cohort: a row an earlier delete left inside the subtree goes too, because a request under a removed collection is reachable by no read and restorable by nothing. It takes deleted rows only (issue #1883): a live collection under the purged one, which no trash entry ever listed, is moved to the tree root (parentId cleared) with everything under it left as it was.

A purged request's declined operation (issue #3031) stays declined: purging is emptying the trash, not changing one's mind. A purged bound collection takes the declined operations recorded under it, which nothing could read any more.

Response: the entry that was purged, with "purged": true. Its purgeCollections / purgeRequests count what this purge destroyed, an earlier delete's rows under the root included; its collections / requests are still the deleted row's own cohort. A 404 if the trash does not hold that id - which is also what stops a mistyped id from destroying a live collection.

Request examples

Saved example responses for a request: what an importer found next to it (Postman's item.response[], an OpenAPI operation's responses), and the responses a mock server will serve. Nested under the request because an example is owned by exactly one - the owner is checked before the example on every path, so an example reached through the wrong request is a 404, not a cross-request write.

Ordering is part of the contract, not a display preference: the list is returned by order, then createdAt, then id, and a mock server answers with the first example of the matched request. A create that states no order appends after the request's current examples; a bulk import numbers them by payload position, because every row it writes shares one createdAt and would otherwise come back shuffled by the id tiebreak.

Caps. A body over 1 MiB is a 400 rather than a truncation - an example served as if it were whole when it is not is worse than a refused write - and a request holds at most 100 examples. Only live ones count: a tombstoned or trashed example does not, which is why restoring one into a full request is refused (see Trash).

A zero byte in a body ("ab\u0000cd") is preserved: it is stored, listed and served by a mock server whole, never cut at the zero.

origin says who wrote the row (issue #588): "import" for everything an importer or a spec sync produced, "user" for one a person saved from a live response. It defaults to "import", which is honest for every row written before the column existed, and an unrecognised value is a 400 rather than a silent fall back - the OpenAPI spec sync (#627) may replace "import" rows wholesale and must never touch a "user" one, so an absorbed typo would cost a user their saved example. An OpenAPI export carries it on every example in x-vayu-request.examples so a re-import keeps it (#2430).

bodyTruncated says the body stops short (issue #659). A mock server serves a stored example verbatim, with nothing in the response to say anything is missing, so an example saved from a capped trace body (maxTraceBodyBytes) is served as though it were a whole response. Only the client that captured it can know, so the flag is stored rather than inferred - a short body is a legitimate body. It defaults to false, which is honest for every row written before the column existed: import copies a whole documented body, and the app's save-as-example is the only writer that ever had a partial one. The app disclosed this in the example's name until the column landed, which a rename at save time erased.

GET /requests/:id/examples

Response: an array of example objects, oldest first:

[
  {
    "id": "exa_1234567890",
    "requestId": "req_1234567890",
    "name": "200 - A user",
    "status": 200,
    "headers": [{"key": "Content-Type", "value": "application/json", "enabled": true}],
    "body": "{\"id\":1}",
    "contentType": "application/json",
    "order": 0,
    "origin": "import",
    "bodyTruncated": false,
    "createdAt": 1730000000000,
    "updatedAt": 1730000000000
  }
]

An empty array and a missing request are different answers: 404 (message Request not found) means the request does not exist, [] means it has no examples yet.

POST /requests/:id/examples

Create one example. Create only, and the engine owns the id - see Resource writes.

Request:

{
  "name": "200 - A user",   // Required, no default (null is a 400)
  "status": 200,             // Optional, must be 200-599. Default 200
  "headers": [],             // Optional, array of {key, value, enabled}
  "body": "",                // Optional. Default ""
  "contentType": "",         // Optional. Default ""
  "order": 0,                // Optional, appended after the request's examples if omitted
  "origin": "import",        // Optional, "import" | "user". Default "import"
  "bodyTruncated": false,    // Optional. Default false - true when `body` is
                             // only the first slice of the captured response
  "postmanResponse": null,   // Optional. The Postman saved response an import
                             // took this from, as JSON text; null = none
  "savedFrom": null          // Optional, create only. What a save in the app
                             // says produced the response (see below); null = none
}

savedFrom is what the app's save-as-example sends from a live response (#1763): the request as written when it was sent ({{variables}} unresolved) and the server's own reason phrase. The engine builds the example's Postman saved response from it with the exporter's own mapping, so POST /export/postman writes that request as originalRequest even after the request is edited.

"savedFrom": {
  "request": {                          // Required; the request columns' own shapes
    "method": "POST",                   // Required, an HTTP method (any case)
    "url": "{{baseUrl}}/users/:id",     // Required string, as written
    "params": [],                       // Optional array, default []; path rows too
    "headers": [],                      // Optional array, default []
    "body": {"mode": "none"}            // Optional object, default {"mode":"none"}
  },
  "statusText": "Totally Fine",         // Required string; "" = the status table's
  "responseTimeMs": 123,                // Optional number, 0 or more; absent = null
  "receivedAt": 1767225600000           // Optional epoch ms, 0 or more: when the
                                        // response came in; absent = the save's clock
}

The stored copy holds name (null), originalRequest (method, headers, body and url as the export writes a request's, with no auth), status (statusText), code, _postman_previewlanguage, header (the example's own rows), cookie (one entry per cookie the enabled Set-Cookie rows set, in Postman's member order: expires, hostOnly, httpOnly, domain, path, secure, session, value, key; expires is JavaScript's date text in UTC, from Max-Age counted from receivedAt (the engine's clock at the save when absent) when there is one, else Expires, and "Invalid Date" with session: true for a cookie with neither; the attributes are read as RFC 6265 and Postman's cookie store read them: an empty Domain is ignored, a leading . dropped, a Path not starting with / is /, and the space around = is not part of a name or value), responseTime (whole milliseconds) and body (null). When it would be over the 1 MiB cap (a large request body) the example is still created, without it, and a warning is logged; the export then regenerates those members. PUT ignores a savedFrom key.

postmanResponse is what the Postman importer sends (schema version 2): the item.response[] entry as JSON text in the source's member order, name and body replaced by null placeholders. A string rather than an object so the order survives a parse into sorted JSON on the way here; it must parse as a JSON object, and it is capped at 1 MiB. POST /export/postman is its reader, and no read route returns it.

headers is an array of KeyValueEntry, the same shape a request's headers use - not a JSON object. A stored example is re-served rather than only displayed, so repeated names (Set-Cookie) and the author's ordering both have to survive.

Response: the created example object.

Errors: 404 if the request does not exist. 400 if the body carries an id, if name is missing or null, on a status outside 200-599 (rejected rather than clamped - a stored 700 would be re-served as a status line nobody can send, and a 1xx is an interim response a mock cannot serve as its final answer), on a malformed headers entry, on an origin that is neither "import" nor "user", on a body over the cap, or on a postmanResponse that is not a string holding a JSON object or is over its cap. 400 naming the field on a savedFrom that is not an object, whose request is not an object, whose method is missing or not an HTTP method, whose url is not a string, whose params or headers is not an array, whose body is not an object, whose statusText is not a string, whose responseTimeMs or receivedAt is negative or not a number, and on a savedFrom beside a non-null postmanResponse (two writers of one column). 409 when the request already holds the maximum number of examples.

A storage failure answers 507, 503 or 500, never 400 - see A storage failure is not a 400.

PUT /requests/:id/examples/:exampleId

Update one example. Update only - a 404 when the example does not exist, and the same 404 when it exists under a different request. Merge-patch body: absent keeps, null resets to the field's default (name has none, so null is a 400). A status outside 200-599 is a 400 as on create; only a body that names status is judged, so an example stored with a 1xx before create began refusing them can still be renamed. postmanResponse accepts only null, which clears it; any other value is a 400 - it records what a file said, and the export already regenerates each part of it an edit to status or headers makes stale.

Headers: If-Match (optional), see Conditional updates.

Response: the updated example object, with its ETag.

Errors: 404 as above; 412 if If-Match no longer names the stored row; 400 on a malformed If-Match or a rejected field.

A storage failure answers 507, 503 or 500, never 400 - see A storage failure is not a 400.

DELETE /requests/:id/examples/:exampleId

Deleting an imported example is a decision that lasts (issue #722). A spec sync rewrites the origin: "import" examples of every request it applies a change to, so a removed row used to come back on the next sync of any field - even a rename. The engine now keeps the row as a tombstone instead: the example is gone from every read (the list, a mock server, an export, and a GET or PUT on its id, all 404), and a later sync leaves that response status alone rather than writing the document's example for it back. Re-importing the document is a fresh import and does bring it back, which is the only way it returns.

Deleting an example a person saved moves it to the trash (#2971). An origin: "user" example is stamped deleted_at rather than removed: nothing re-creates one, so the row is the only copy of the response. It is gone from the same reads a tombstone is, a second DELETE is a 404, it no longer counts against the 100-example cap, and GET /trash lists it (kind example, parentId its request) while its request is live. POST /trash/:id/restore brings it back as it was; DELETE /trash/:id, or the startup sweep after trashRetentionDays, destroys it.

Either way, a request that named the example as its fixed mock answer stops naming it (issue #3422). When the request's mockExampleId is this example's id, the same write clears it to null, advances the request's updatedAt (so a PUT /requests/:id sent with the old If-Match is a 412) and publishes a request update on GET /changes after the example's delete. mockResponseMode is not touched: a "fixed" request with no target answers with its first example. A mockExampleId naming any other example is left alone, and a restore from the trash does not set it again.

The response is the same either way, because from the caller's side so is the outcome:

Response:

{
  "message": "Example deleted successfully",
  "id": "exa_1234567890"
}

Specs

OpenAPI documents, stored once and bound to collections by collections.openapi (issue #637). A spec is not owned by a collection: several may bind the same document, and unbinding one must leave it there for the others - so it is a top-level resource with no cascade reaching it, and the rule that keeps that safe is the delete refusal below. What it is not is immortal: see the reclamation rule further down.

The document is stored verbatim and its hash is computed engine-side on every write, never taken from the caller. A scenario run of a bound collection stamps specId + specHash into its snapshot and report, and that stamp only means anything because both sides of a later comparison were computed by the same code on the same bytes.

There is deliberately no PUT /specs/:id: a document that changed is a different document, and rewriting one in place would invalidate the hash every run of every bound collection was stamped with. A re-fetch stores a new document and moves the binding.

A document nothing can reach is reclaimed (issue #718). Having no owner is what let these rows accumulate with no way to die - every sync mints one and moves the binding off the last, and DELETE /specs/:id needs an id no route hands out for an unbound document. So the engine sweeps on one rule:

A document lives while a collection binds it, or while a retained run names it in its snapshot under scenario.openapi.specId.

Run-referenced documents live exactly as long as the runs do, so a report's coverage never describes a contract whose source is gone. The sweep runs as part of ordinary housekeeping - at startup, after each run's retention pass, after a POST /specs/sync, and after a DELETE /collections/:id - and spares any document written in the last 10 minutes, because storing a document is the first of the three writes that bind one and a caller may not have sent the PUT /collections/:id yet. A client that stores a document it does not intend to bind should therefore expect it to go: GET /specs/:id will answer 404 once it is unreachable by that rule. Nothing here changes what DELETE /specs/:id refuses, and no cascade was added - a bound document is untouched.

POST /specs

Store one OpenAPI document. Create only, and the engine owns the id - see Resource writes.

Request:

{
  "content": "{\"openapi\":\"3.1.0\", ...}",  // Required, non-empty, at most maxSpecDocumentBytes
  "sourceUrl": "https://api.example.com/openapi.json"   // Optional; null when pasted or uploaded
}

Response:

{
  "id": "spec_3f2b1c9a-...",
  "content": "{\"openapi\":\"3.1.0\", ...}",
  "sourceUrl": "https://api.example.com/openapi.json",
  "fetchedAt": 1730000000000,
  "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "operations": [
    {"operationId": "listPets", "method": "GET", "path": "/pets", "responses": ["200", "default"]}
  ]
}

operations is derived by the engine, never sent (issue #853). It is a fact about the bytes being stored, like hash, so the engine reads them: content is parsed as JSON and then, failing that, as YAML, and the operation index comes off that parse. Sending an operations field is a 400.

Each row carries a method and the templated path as the document keys it, an operationId when the document declares one, and responses - the status patterns the document declares ("200", "4XX", "default"), verbatim and in document order. A document declaring more than 2000 operations is refused with the count and the cap, because a run holds the index in memory for its life.

What the reader does with a document, stated because the answers are visible in the index:

  • Document order is kept, for paths and for each operation's responses.
  • Both formats: openapi: 3.x and swagger: 2.0 (quoted or not). Anything else declares nothing - a stored file that is not a contract stores fine and reports no coverage.
  • A path item that is a $ref is followed one hop, in-document; one that resolves to nothing drops that path rather than failing the write.
  • The seven methods Vayu executes are indexed, trace is not.
  • A repeated operationId is kept on its first declaration only (issue #715); the later operation is indexed by method and path alone.
  • Anchors, aliases and merge keys (<<) are expanded as js-yaml expands them; an alias naming no anchor, a duplicate mapping key, and a document that expands to far more nodes than its own size are each a 400 naming the problem.

A document that declares no operation stores "no index", which is not the same as an empty contract: GET /specs/:id reads it back as null rather than [], and a run of a collection bound to it reports no coverage block at all. POST /import/apply's spec section and POST /specs/sync derive both indexes through the same helper, so a document cannot acquire or lose one depending on which route stored it.

responseSchemas is the second index the engine derives from the same read (issues #628 and #860) - what the document declares each response looks like. Like operations, it is not a field of the body; sending one is a 400:

{
  "refRoots": {"components": {"schemas": {"Pet": {"type": "object"}}}},
  "operations": [
    {
      "operationId": "getPet",
      "method": "GET",
      "path": "/pets/{petId}",
      "responses": [
        {"status": "200", "contentType": "application/json",
         "schema": {"$ref": "#/components/schemas/Pet"}}
      ]
    }
  ]
}

A response schema that refers to itself without describing any value is a 400 (#3018): Response schema of GET /pets (200) refers to itself without describing any value (#/components/schemas/A -> #/components/schemas/A). The loop runs only through $ref, allOf, anyOf, oneOf, not, if/then/else or dependencies, so it never reaches a value and cannot be validated. A recursive schema that steps into a property or an item (a tree node) is fine.

Schemas are JSON Schema, not OpenAPI's dialect: the engine translates nullable into a union with null, draft-04's boolean exclusiveMinimum into draft-07's numeric one, and drops the OpenAPI-only keywords that constrain no body (discriminator, xml, externalDocs, example) - a nullable passed through untouched would report a null the document permits as a type failure, which is a wrong verdict rather than a missing one. Each schema keeps its $refs and refRoots carries the subtrees they point into once (components.schemas, definitions, x-vayu-bundled), so a shared schema is stored once and a recursive one is a pointer rather than an infinite expansion. A response that is itself a $ref is read through, one hop, in either dialect (#/components/responses/x in 3.x, #/responses/X in 2.0) - the shape GitHub's spec uses for nearly every response. status is the pattern verbatim ("200", "4XX", "default"), contentType is a media type (3.x keeps every one the response declares; 2.0 pairs each response with the operation's produces, falling back to the document's, then to application/json), and a schema may be true or false as well as an object. The serialized index is held to the same maxSpecDocumentBytes cap as the document, and one over it is a 400 naming the count and the cap. A status that declares no schema is a status-only row ({"status": "204", "contentType": ""}, no schema), so a response under it reports checked: false instead of being judged by default. An x- extension key under responses is not a status and is indexed in neither list (#3084). A document where no operation declares a status stores "no index", read back as null, and every response of it reports checked: false with the reason no_index.

Both indexes come off one read of the document, which is what makes them agree: a status the schema index carries is a status the operation index lists for the same operation, and the identity in each is the same identity - the repeated-operationId rule included.

sourceUrl is null rather than "" when the document did not come from a URL, so a client can offer a re-fetch for exactly the documents that have somewhere to re-fetch from.

Errors: 400 if the body carries id, hash, fetchedAt, operations or responseSchemas (all engine-computed), if content is missing, null or empty, if sourceUrl is present and not a string or null, or if the document is larger than the live maxSpecDocumentBytes config entry - default 10 MiB, aligned with the engine's JSON field cap. The size rejection names the byte count, the cap and the setting, and is checked on POST /import/apply too, through the same helper; the document is never stored truncated. A content the engine cannot read as JSON or YAML is a 400 naming the line - storing it would leave a row that coverage, a sync and an export can each do nothing with, and none of those is a good place to find out.

A storage failure answers 507, 503 or 500, never 400 - see A storage failure is not a 400.

GET /specs/:id

Response: the whole stored document, content included - rendering and validating it is what every reader wants it for. 404 (message Spec not found) when it does not exist.

Read it for the text: an export, a re-fetch comparison, a $ref resolution. A client that only needs to describe the document should read the metadata route below instead - content here is up to maxSpecDocumentBytes (12 MB for Stripe's published spec), and it is sent in full on every read.

GET /specs/:id/meta

Everything about a stored document except the document (issue #712).

Response:

{
  "id": "spec_3f2b1c9a-...",
  "sourceUrl": "https://api.example.com/openapi.json",
  "fetchedAt": 1730000000000,
  "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "contentBytes": 12058329
}

Every field carries the same value GET /specs/:id would give it - the two are one row seen two ways - and 404 is the same body, so a client that falls back from one to the other does not need two shapes of "not found".

content, operations and responseSchemas are absent, not empty. All three are the fields that make a document big (both indexes are extracted from it and grow with it), and an empty one would be indistinguishable from a document that genuinely has none - the distinction operations: null exists to draw. A reader that needs any of them reads the full route.

contentBytes is the document's size as the engine counts it - the same measure maxSpecDocumentBytes refuses a write by, so a size reported here and the limit it was stored under are in one unit.

This route exists because binding metadata lives on the document: the app's Spec tab paints a source and a fetch date, and getting them used to cost a transfer of the whole spec on every first open of the tab.

DELETE /specs/:id

Delete a stored document.

Response:

{
  "message": "Spec deleted successfully",
  "id": "spec_3f2b1c9a-..."
}

Errors: 404 when it does not exist. 409 while any collection still binds it, a collection in the Trash included, with a message naming the first binder (and a count of the rest) so the caller knows what to unbind without a second round trip:

{
  "error": {
    "code": "conflict",
    "message": "Spec 'spec_3f2b...' is bound by collection 'Pets API' (col_9a1f...); unbind it before deleting the document"
  }
}

A binder in the Trash is named as such (#3446), because restoring it brings its binding back and a document deleted under it would come back named by a collection whose document is gone:

{
  "error": {
    "code": "conflict",
    "message": "Spec 'spec_3f2b...' is bound by collection 'Pets API' (col_9a1f...), which is in the Trash; restore it and unbind it, or purge it, before deleting the document"
  }
}

The refusal is deliberate rather than a cascade to unbound: the caller asked to delete a document, not to edit collections it never mentioned. Unbind with PUT /collections/:id and {"openapi": null}, then delete. Purging a trashed binder runs the orphan sweep, which reclaims the document itself once nothing else binds it.

POST /specs/match

Pair the requests in a collection's subtree with the operations a document declares - what binding a collection that already exists needs, and what an import does not (an import creates the requests, so it stamps each one's identity as it builds it).

Reads only. Nothing is stored, stamped or created, so a caller may ask about a document it has not decided to bind - which is exactly what the app's Spec tab does, showing the counts before the user commits. The write is POST /specs/bind, which matches again over the same walk and the same rule rather than being handed this answer: between a preview and a commit a request may have moved, so what the two share is the rule, not a result carried between them.

Request:

{
  "collectionId": "col_9a1f...",
  "operations": [
    { "operationId": "listPets", "method": "GET", "path": "/pets" },
    { "method": "GET", "path": "/pets/{petId}" }
  ],
  "basePaths": ["/v1"]
}

operations are the same identity rows the engine derives into a document's operations index, validated by the same rule - so a set the store would refuse cannot be matched against here first. They are sent here (unlike on POST /specs, which reads them off the document) because this route matches against a document that has not been stored yet, which is the point of a bind preview. Get them from POST /specs/describe rather than by reading the document yourself (issue #869): that route is the same reader POST /specs/bind derives its stamps from, so a preview and the write it previews cannot pair the requests differently. responses may ride along and is ignored. basePaths is optional: the path parts of the document's server URLs, which POST /specs/describe answers beside the operations (issue #3030). A non-array, or an entry that is not a string, is a 400; an entry that does not start with /, or is the root, names nothing to strip and is ignored.

The requests are not sent. The engine gathers the subtree of collectionId itself, because an OpenAPI import binds the root and files every request under one sub-collection per tag: a caller sending "the collection's requests" would be matching against a set that excludes almost all of them. The walk stops at a sub-collection bound to a different document (issue #3034), taking its descendants with it: a folder that is another contract's own keeps its requests out of this pairing, exactly as POST /specs/bind keeps them out of its stamping. A sub-collection bound to the same document stays in, and an unbound collectionId stops at every bound sub-collection.

Response:

{
  "matched": [
    {
      "requestId": "req_4c8e...",
      "operation": { "operationId": "listPets", "method": "GET", "path": "/pets" }
    }
  ],
  "unmatchedRequests": ["req_7b21..."],
  "unmatchedOperations": [{ "method": "GET", "path": "/pets/{petId}" }]
}

operationId is absent rather than "" for an operation that declares none, the same way a stored spec_operation omits it.

How it matches. Both sides are reduced to a path shape: the origin dropped ({{baseUrl}}, https://api.example.com and a schemeless host alike), the query and fragment dropped, and every placeholder - Vayu's {{petId}}, a request's Postman-style :petId path variable (issue #1764) and the document's {petId} - flattened to {}. Flattening the name too is deliberate: a document that renames its path parameter describes the same endpoint, and a match that turned on the parameter's spelling would report a rename as removed and added. A second pass then offers each remaining request to the templates it could be an instance of, because a hand-built collection writes the id in (/pets/42) - a literal path in the document wins first, which is OpenAPI's own precedence. A segment mixing literal text with a placeholder ({id}.json, {name}:cancel, meta-{ver}, issue #3085) is filled the same way: the text around the placeholders must appear in order and each placeholder takes at least one character, never a /. A third pass reads basePaths (issue #3030): a request written as a literal URL carries the server's base path (https://h/v1/pets) where the document writes /pets, so whatever the first two passes left open is compared again, both ways, with each base path taken off the front of the request's path. A base path is taken off whole segments only (/v1 is not a prefix of /v10/pets), a templated one (/{version}) stands for any one segment (a segment mixing text with a placeholder, /api-{version}, fills as above), and a request that is exactly the base path is the root operation /. The first two passes win, so a document declaring /v1/pets in full claims that request before any base path is stripped. Ambiguity is refused in both directions, in every pass: two requests reducing to one shape, or one request that could be two operations - under two base paths included - leaves all of them unmatched. A wrong identity is worse than none, because POST /specs/sync applies changes by it.

Errors: 400 for a missing or empty collectionId, a missing operations, an operation row the store would refuse, or a basePaths that is not an array of strings. 404 when the collection does not exist - not an empty match, since "this document matches none of your requests" and "you named a collection that is not there" are different answers.

POST /specs/describe

Say what a document is, without storing it: the dialect that claimed it, what it calls itself, every operation it declares and the base paths its servers name. The read behind a bind preview - the app's Spec tab paints its card from this and hands the identities straight to POST /specs/match.

Reads only. Nothing is stored, which is why the document rides in the body: a caller asks about a file the user has not decided to bind, and a route that stored one to describe it would leave a row behind for every file merely looked at. Describing a document that is stored is GET /specs/:id/meta.

Request:

{
  "content": "{\"openapi\":\"3.1.0\", ...}"   // Required, non-empty, at most maxSpecDocumentBytes
}

Response:

{
  "format": "OpenAPI 3.1",
  "title": "Pets API",
  "operations": [
    { "operationId": "listPets", "method": "GET", "path": "/pets" },
    { "method": "GET", "path": "/pets/{petId}" }
  ],
  "basePaths": ["/v1"]
}

format is "OpenAPI 3.1" (an openapi starting 3.1), "OpenAPI 3.0" (any other 3.) or "OpenAPI 2.0 (Swagger)". title is the document's info.title and "" when it states none - never a substitute name, because the caller asked what the document calls itself. operations are in document order, in the shape a request's spec_operation records, operationId absent rather than "" for an operation that declares none - the same rows POST /specs/match takes.

basePaths (issue #3030) is always present, [] when the document states none, and is what POST /specs/match takes beside the operations. For 3.x it is the path of every servers[].url, not only the servers[0] an import turns into {{baseUrl}}, because a collection may have been written against any of them: each {name} with a variables default is substituted first (the importer's rule), then the path after the authority is taken (https://{host}/v1 -> /v1), or the whole URL when it is already a path. A server with no path, or one relative to the document (v1), names none. For 2.0 it is basePath. Trailing slashes are dropped, and the root and repeats are left out.

This is the reader every spec write uses (issue #853), which is the point of the route: the identities answered here are the identities POST /specs/bind will derive from the same bytes. Before issue #869 the app read the picked document itself, so a document the two sides read differently previewed one pairing and committed another.

Errors: 400 for a missing or empty content, bytes over maxSpecDocumentBytes (the same cap a store applies, so a preview cannot succeed where the bind will fail), bytes that cannot be read as JSON or YAML, a document declaring more than 2000 operations, and a readable file that is not an OpenAPI document - the last named as what is missing rather than answered as a contract declaring nothing.

POST /specs/diff

What a re-fetched document would change about the collection bound to it - the read half of a sync (issue #654's comparison, moved engine-side by #854). The app's Sync section is this call; an agent asking "has this contract drifted, and where" is the same one.

Reads only. No document is stored, no binding moved, no request stamped, so a caller may ask about a document it has not decided to apply. Applying is POST /specs/sync, which re-reads everything rather than being handed this answer - the same split POST /specs/match and POST /specs/bind follow.

Request:

{
  "collectionId": "col_9a1f...",
  "spec": { "content": "{\"openapi\": \"3.0.0\", ...}" }
}

Neither the requests nor the bound document are sent. The engine walks the subtree of collectionId itself (an import files its requests under one sub-collection per tag, and the walk stops at a sub-collection bound to a different document, issue #3034) and reads the bound document from the collection's own binding: the three-way rule below is only worth anything if the "previous" side is the bytes actually stored, and a caller that could supply them could turn its own edits into the document's - by accident, with a stale copy.

Response:

{
  "identical": false,
  "added": [
    {
      "operation": { "operationId": "listOwners", "method": "GET", "path": "/owners" },
      "folder": "owners",
      "safe": true,
      "draft": {
        "name": "List owners",
        "description": "",
        "method": "GET",
        "url": "{{baseUrl}}/owners",
        "params": [],
        "headers": [],
        "body": { "mode": "none" },
        "examples": []
      }
    }
  ],
  "declined": [
    {
      "operation": { "operationId": "getPet", "method": "GET", "path": "/pets/{petId}" },
      "folder": "pets",
      "safe": false,
      "draft": { "name": "Get a pet", "...": "as in added" }
    }
  ],
  "removed": [
    {
      "requestId": "req_7b21...",
      "name": "Delete a pet",
      "operation": { "operationId": "deletePet", "method": "DELETE", "path": "/pets/{petId}" },
      "safe": false
    }
  ],
  "changed": [
    {
      "requestId": "req_4c8e...",
      "name": "List pets",
      "boundOperation": { "operationId": "listPets", "method": "GET", "path": "/pets" },
      "operation": { "operationId": "listPets", "method": "GET", "path": "/pets" },
      "matchedBy": "operationId",
      "renamed": false,
      "previousUnknown": false,
      "safe": true,
      "safeFields": ["name"],
      "fields": [
        {
          "field": "name",
          "current": "List pets",
          "next": "List all the pets",
          "userTouched": false
        }
      ],
      "draft": { "name": "List all the pets", "...": "as above" }
    }
  ],
  "unchanged": 12,
  "unmapped": 1
}

identical is decided on the stored bytes - the ones spec_documents.hash is over - rather than on a hash the caller computed, and is the "up to date" answer. The buckets are still reported when it is true, empty.

draft is the request an import of the new document would build: the values behind every next (which is truncated for display), plus the operation's documented responses as examples, so a POST /specs/sync payload is built by choosing which of these fields to send rather than by re-reading the document. The examples here are reported rather than returned to the engine: since issue

869 a sync says whether to refresh a request's imported examples and the rows

come off the document it stores, so this is what an apply would write, shown. unmapped counts requests carrying no operation at all - not part of the comparison, but stated, because a sync that silently ignores half a collection is one nobody can read.

declined is an operation nobody claims because a person deleted its request (issue #3031). Its entries are shaped like added ones, because ticking one is the same create, and an operation is in one bucket or the other, never both. The record a delete left (see DELETE /requests/:id) is followed into the new document by the rule a request's own identity is, below, so an operation the document renamed is still the declined one. A live request claiming the operation - one restored from the trash, or created again by hand - outranks the record, and the operation is in neither bucket.

safe is what an apply with no ticks would do to that entry (issue #871), and safeFields is which of a changed request's fields it would write - empty for a pure rename, which is a real selection rather than an absence. It is core::safe_spec_apply: every operation the document adds, every field it moved that nobody here had edited, no deletions, nothing a person declined, and a request whose bound document could not be read left alone whole. Reported rather than left to the caller because the rules are the ones whose silent failure costs somebody their work, and because the same function decides what POST /specs/sync's policy applies - so the app's pre-ticked boxes and a caller that ticks nothing are one answer rather than two that agree today. safe on a removal and on a declined operation is always false and is carried anyway, so that a reader marking the bucket reads the rule instead of writing it.

How it compares. An operation is followed by its operationId first and by method + path shape second (the same flattening POST /specs/match binds with), so a path moved under a stable id and an id moved under a stable path both stay one operation, while both moving at once is disclosed as a removal plus an addition rather than guessed at. An id two requests claim identifies neither and is skipped; an id whose entry contradicts the endpoint the request records loses to an exact match on that endpoint. renamed says the identity itself moved, so an apply records the new one.

userTouched is three-way: the field is flagged when what the request holds is neither what the new document produces nor what the bound one did - the only evidence that a person put it there, and the flag an apply may not overwrite silently. previousUnknown says the bound document does not declare this operation, so no such claim can be made about it at all, and every userTouched on that request is false. A query typed into the URL is a Params change too: the write that stored the URL derived the query rows from it (see POST /requests, issue #3551), so params is flagged beside url.

Response examples are deliberately not compared. The rule that governs them (origin="import" is replaced, origin="user" survives) only means anything at apply time, so they ride on draft rather than appearing as a difference nothing acts on.

Errors: 400 for a missing or empty collectionId, a missing or empty spec.content, a document larger than maxSpecDocumentBytes, a document that will not read as JSON or YAML (the message names where it broke), or a collection that binds nothing - there is nothing to compare against, and binding is POST /specs/bind. 404 when the collection does not exist. 409 when its binding names a document the store no longer holds, which is a broken binding rather than a bad request.

POST /specs/bind

Bind a collection to an OpenAPI document, in one transaction: the document is stored, the collection's binding moves to it, and every request in the collection's subtree is stamped with the operation it matched or has its stamp cleared. Nothing is created or deleted - that is what a sync is for. It is the one way to bind or rebind an existing collection: PUT /collections/:id with any openapi but null or {} is a 400 naming this route (issue #3348).

The caller sends a document, never a pairing. The engine reads the bytes it is about to store, derives the operations index from them, and matches the subtree with core::match_operations - the same rule POST /specs/match previews with, over the same subtree walk, under the base paths the same read of the document names (the basePaths POST /specs/describe answers, issue

3030). A pairing worked out by the caller

would be a second opinion about what the document declares, and an agent over MCP has bytes and no OpenAPI reader at all.

Request:

{
  "collectionId": "col_9a1f...",
  "spec": {
    "content": "openapi: 3.0.0\n...",
    "sourceUrl": "https://api.example.com/openapi.yaml"
  }
}

spec.content is the document verbatim, JSON or YAML, capped by maxSpecDocumentBytes. sourceUrl is optional and null or absent means the document did not come from a URL. id, hash, fetchedAt, operations and responseSchemas are engine-computed and a 400 if sent, the same rule POST /specs applies.

Response:

{
  "specId": "spec_2b74...",
  "specHash": "8f3c...",
  "syncedAt": 1755000100000,
  "stamped": 12,
  "cleared": 2,
  "unmatchedRequests": ["req_7b21..."],
  "unmatchedOperations": [{ "method": "GET", "path": "/pets/{petId}" }]
}

unmatchedRequests and unmatchedOperations carry the same shapes POST /specs/match answers with, so a caller reads one shape for the preview and the commit.

Stamping goes both ways (issue #718). After a bind, a request's spec_operation is the operation it matched in the bound document, or nothing: cleared counts the requests whose identity was removed because this document does not account for it. That half is not a list the caller states - it is the other side of the same walk - because a bind that wrote only the matches left every non-matcher carrying identity from the previous document, and coverage resolves a stamp by operationId first, so such a stamp claims whichever operation of the new document shares the id rather than going unread.

Nothing outside the subtree is touched, the rule POST /specs/sync follows: a request under another collection keeps its own stamp even when it would have matched. That includes a sub-collection bound to a different document and everything beneath it (issue #3034): its requests carry that document's operation identity, so neither a match nor a clear is applied to them. A sub-collection bound to the same document is in the subtree.

A bind to other bytes forgets the declined operations (issue #3031). The operations deletes declined under the collection (see DELETE /requests/:id) were decisions about the document it was bound to, so a bind whose document hashes differently from the bound one forgets them in the same transaction; a bind to the same bytes keeps them.

Errors: 400 for a malformed body, an engine-owned field, a document over the cap, or one that cannot be read as JSON or YAML - and in that last case nothing is written, so the collection stays bound to whatever it was bound to. 404 when the collection does not exist. 409 when a row moved under the write.

Unbinding is not here: it is PUT /collections/:id with "openapi": null (or {}), which writes one row, leaves every stamp in place - so unbind-then-rebind of the same document is lossless - and has no document to read. It does forget the declined operations, in the same transaction, as a bind to other bytes does.

POST /specs/export

A collection back out as an OpenAPI document - its own bound document updated, or a skeleton describing its requests when it binds none. Which of the two runs is a fact about the collection rather than a parameter; how much a bound export writes is the caller's choice (mode, below).

Reads only. Nothing is stored and the collection is left exactly as it is; a POST because the answer is a document rather than a resource, and because the body carries the format.

Request:

{
  "collectionId": "col_9a1f...",   // Required
  "format": "json",                // Optional - "json" (default) or "yaml"
  "mode": "contract"               // Optional - "contract" (default) or "full"
}

Neither the requests nor the document are sent. The engine reads the whole subtree of collectionId (an OpenAPI import binds the root and files every request under one sub-collection per tag), each request's stored examples, and the bound document itself - stopping at any collection bound to a different document. That boundary is not a filter: the refused collection takes its own descendants with it, because its requests carry another document's operation stamps and operationIds are names generators hand out in every document (listUsers, GET /users), so letting them through would have them claim these operations and rewrite them. A descendant bound to the same document is part of the export, because its requests describe the very operations being patched.

Response:

{
  "text": "{\n  \"openapi\": \"3.0.3\",\n ...",
  "fileName": "petstore.openapi.json",
  "notes": {
    "direction": "document",        // or "skeleton"
    "dialect": "OpenAPI 3.0.3",
    "requestsExported": 12,
    "requestsWithoutOperation": 1,
    "operationsNotInDocument": 0,
    "operationsRemoved": 2,
    "requestsWithoutPath": 0,
    "duplicateOperations": 0,
    "examplesWritten": 4,
    "examplesWithoutMediaType": 1,
    "examplesTruncated": 0,
    "examplesAlreadyDeclared": 3,
    "examplesSampledAtImport": 2,
    "sharedParametersLeft": 1,
    "referencedResponsesLeft": 1,
    "bodiesNotWritten": 2,
    "rowsNotDeclared": 1,
    "operationsEdited": 0,
    "vocabularyNotWritten": false,
    "secretsOmitted": 2,
    "requestsOnlyInExtension": 0,
    "operationsAdded": 0,
    "boundMode": "contract"         // "" for a skeleton
  }
}

Every count is present, zeros included: "0 requests with no operation" is how a bound export states that it carried everything, and a body that omitted its zeros would read as complete whether or not it was.

mode - what a bound export may write. contract, the default, treats the stored document as the API's contract and writes only what the next three paragraphs describe. full writes everything the collection holds, into the document's own dialect (Swagger 2.0 included): each request's name (as summary, only where it differs from the name an import would read) and description, a parameter for every Params or Headers row the operation does not declare (a query stated only in the URL included, since the write derives its rows, issue #3551; 2.0's type and x-example in a 2.0 document), the body as the media type's example (2.0: an in: body or formData parameter, added only where the operation declares none), the auth wherever the operation does not already state it (a scheme the document declares with the same credential is reused, otherwise one is added), saved examples (2.0: the response's examples map), a new operation for every request the document never declared (operationsAdded; a new operation in 3.0 or 2.0 with no saved example gets a default response, which those dialects require), the collection's name, description, base URL and auth at the root, and the x-vayu-* extensions below. It still never rebuilds: schemas, $refs and every member Vayu does not model stay as they were, and a request nobody edited writes nothing new into the standard members - an unedited export in full differs from the stored document only by its x-vayu-* keys. A skeleton ignores mode. Anything else is a 400.

A request's :name path variable is an OpenAPI path parameter (issue

1764): wherever a URL becomes a path, a whole :name segment is written

{name}, as a whole {{name}} segment is, and its path row's value is the parameter's example. A path row is never declared in: query, and x-vayu-request.params keeps each row's in (and a Postman type), so a re-import gives the path row back. A segment with a suffix (:name.json) is left as written, as {{name}}.json is.

A bound export patches the stored bytes, never rebuilds them. Operations no request claims are removed (and a path left with no operations goes with them), a declared parameter whose request row carries a value gets it as example (a declared in: path parameter reads the request's path row of that name, issue

1764; a credential row's value is not written, see "Secrets never leave"), and stored examples become response examples - one as example, several as a named

examples map. Everything else - info, tags, vendor extensions, security, components nothing references - is carried through by simply not being visited, and the dialect is left as it was.

It adds, and never removes what the document declares (#1442). A media object already answering with an examples map keeps every entry it had and gains one; a single example is replaced by the one value that would replace it, and moves into the map under the key example when a second example has to go somewhere. A response that is a $ref is left bare and counted as referencedResponsesLeft: a Reference Object admits no siblings in 3.0, so a content written beside it is ignored by conformant readers and rejects the document at a validator, and the component it names is shared with every operation that references it. An example whose value the document already declares is counted as examplesAlreadyDeclared and written nowhere, and an imported example (origin: import) for a media object that declares no example at all was sampled off that response's schema at import, so it is counted as examplesSampledAtImport rather than written back as though the API had stated it; where the document declares no such response either, the status is not documented from it at all, because putting back a response the contract dropped is not this export's to do. Values are compared as values, so an example whose members are stored in another order than the document writes them is the same example. An export of a spec-origin collection nobody edited is therefore the document it was bound to, structurally unchanged.

In contract mode, the edits it does not write are counted, not silent. It writes parameters and examples: a request body is bodiesNotWritten, a Params or Headers row the operation declares no parameter for is rowsNotDeclared (Authorization and Content-Type excepted - OpenAPI states them as security and as the body's media type), and a request whose method or path no longer matches the operation it is stamped as is operationsEdited - its values still land, in the operation the document declares. A concrete path that fills the operation's template (/users/1 for /users/{id}) still matches, by the rule the matcher stamped it with, and is not counted; neither is one under a server base path the document declares (/v1/users/1 with servers: [{url: /v1}], or a 2.0 basePath). A parameter the operation declares by $ref, or one the Path Item declares for every method under it, is declared: its name is read through the reference, so a row that has a home is never counted as one the document has no place for, and sharedParametersLeft is what says its value was not written.

A Swagger 2.0 document is the one partial case of contract mode, reported as vocabularyNotWritten: operations nothing claims are still removed, but nothing is written into an operation. full writes 2.0's own vocabulary.

A skeleton invents nothing. {{variable}} tokens are written as they stand in paths (resolving them would export one machine's environment as though the contract named it); a {{baseUrl}} server gets a real default when the collection's own baseUrl variable has a value - written as the single-brace {baseUrl} OpenAPI's Server Variable syntax expects, with that value as its default - and the bare double-brace token otherwise, since an undeclared single-brace variable is invalid OpenAPI. A path segment that is exactly one token becomes the OpenAPI {petId} it came from, every Params and Headers row (a query written only in the URL has its rows, issue #3551) is declared without a required it was never given but carries its toggle explicitly as x-vayu-enabled (neither a value nor its absence says whether a row is on), and a body or response is described only where there is a stored example to read a shape off - carrying a description that says the shape is derived. A JSON body holding a {{variable}} token is not valid JSON on its own, so it is written as the text it is and read back the same way, byte for byte, rather than re-quoted into a JSON string.

It carries what OpenAPI can name, for the modes it has names for (#1441). A folder becomes a tag named by its full path (Users/Admin), described by the folder's own description and declared once at the document root and on every operation under it. Auth becomes components.securitySchemes plus a security requirement - basic and bearer as http, an API key as apiKey, OAuth 2 as oauth2 with the flow the request uses - at the document root for the collection's own auth and on the operation only where a request's differs from it. An inherit request is resolved the way POST /compose resolves it, through its folders (the nearest one with a credential, noauth ending the walk), so a request under a folder with its own auth states that folder's scheme; an explicit no-auth request is security: [], one left to inherit gets no override, and a mode with no OpenAPI name (digest, aws, ntlm) gets no security at all. A body is written as the example another tool can send: JSON and JSON-RPC as JSON, GraphQL as the {query, variables} envelope a GraphQL-over-HTTP server receives, XML and text as the text they are, a form as its fields (file parts format: binary) with the enabled text values as the example, a binary body as one file's bytes (type: string, format: binary, no example) - filed under the media type an enabled Content-Type row names (application/vnd.api+json) rather than the mode's generic one; a binary body with no such row is filed under its file's own contentType, else application/octet-stream. What the standard members cannot state exactly travels in x-vayu-request and x-vayu-collection (below), so every one of these reads back as it was.

x-vayu-request and x-vayu-collection carry the rest of the collection (core/vayu_extensions.hpp). A skeleton writes them always, a full bound export too; contract mode writes neither. On an operation, x-vayu-request holds the request as the UI does: name, method, url (verbatim, {{...}} and all), order, the folder path it is filed under, every Params and Headers row as typed (Authorization and Content-Type rows, toggles, duplicates and all), the body in its own mode, the auth exactly as set (inherit included), the non-default settings (followRedirects, maxRedirects, timeout, httpVersion, verifySSL, stream), every saved example with its headers and its origin ("user" or "import", #2430; one that is neither is an unreadable example, and a document with none, as an older Vayu wrote, imports as "import"), and the mock mode with the index of a fixed target. At the root, x-vayu-collection holds the collection's variables (baseUrl included), auth and dataSchema, every folder (path, order, description, variables, auth, elements, empty folders included; order shares its parent's space with the requests' x-vayu-request.order, #2535, so a request between two folders imports there), and the requests no operation can hold - a URL with no path, or a second request on a method and path another already claimed - counted as requestsOnlyInExtension (and under requestsWithoutPath / duplicateOperations, which say why). Another tool ignores both keys; Vayu's importer reads them back (see POST /import/parse).

Secrets never leave. This export has no includeSecrets: every token, password, API-key value, client secret, AWS key and variable marked secret, at every level either key writes, is written as "" and counted as secretsOmitted - except a value that is one {{variable}} reference and nothing else, which names where the secret lives without being one. The auth modes kept as a config bag (AWS, digest, NTLM, Hawk, OAuth 1.0, EdgeGrid, JWT, OAuth 2.0's own config) are blanked by an allowlist of the members known to describe the auth, so a member no list has heard of (Insomnia's IAM secretAccessKey) leaves blank too. OAuth 2.0's extra request parameter lists (tokenParams, authorizationParams, refreshParams) are redacted per row: a row's key, enabled and sendAs stay, and its value is blanked when the key names a credential (client_secret, client_assertion, password, Authorization, X-Api-Key, the other names below), so an audience row leaves intact; a row with no non-empty string key, and any member of a row beside those four, is blanked whole. A credential outside an auth block is blanked by name wherever it is written:

  • a header row whose name is sensitive (Authorization, Proxy-Authorization, Cookie, Set-Cookie, X-Api-Key, X-Auth-Token, X-CSRF-Token, the other names the logger redacts) or is the header the API-key auth in force names - the request's own, or the one its folders resolve to when it inherits - in x-vayu-request.headers and in the parameter that mirrors the row;
  • a query parameter by the narrower name set of the Params table (the same names less the generic code and key, plus secret, signature, x-amz-signature and the like, plus an API-key auth's own parameter), in x-vayu-request.params, in the parameter's example (a :name path row included) and in x-vayu-request.url's query and fragment;
  • the password of a URL's user:pass@ (the user name stays), in x-vayu-request.url, in a skeleton's servers, and in a baseUrl variable (collection or folder) and the server-variable default made from it;
  • the response headers of a saved example in x-vayu-request.examples, by the header names (a Set-Cookie row, in full). A response's headers are never a standard member, so nothing else carries them.

The row and its key stay, the value is "", and a parameter whose value was withheld is still declared with no example - a bound document's own example for it is neither replaced by the credential nor erased. A value is kept only when it is exactly one {{variable}} reference: Bearer {{token}} is blanked, because the text around a reference can hold a literal secret. A body is never judged: a stored example's body, a request body and a script are written as stored, apart from the file-part rule below.

secretsOmitted counts each withheld value once wherever it is written: a header row and the parameter that mirrors it, a URL's query and the Params rows, and a server and the URL it was read from are one credential. A contract export, which writes no x-vayu-request, counts a withheld row at the declared parameter whose example it would have filled; a credential row no operation declares was never going to be written, so it is not counted (rowsNotDeclared still counts it).

A form's file part, and a binary body's file, keep their name, declared file name and content type, never the local path they were read from (src). A path a hand-edited x-vayu-request does carry is read back as written, and sent only once picked or under an allowed folder; an unresolved it states is dropped.

x-vayu-elements carries a request's or the collection's whole elements array verbatim, the same vendor-extension convention x-vayu-enabled already established - never a standard OpenAPI field, so writing it is never "rewriting the user's contract". A skeleton export writes it on every operation and at the document root whenever the corresponding elements array is non-empty; a bound export writes it on an operation the document already declares - in contract mode only into a 3.x document (nothing is written into a Swagger 2.0 document's operations at all), in full mode into either, and at the root. The importer reads it back verbatim, validated against the live element registry - a document hand-edited into an invalid array is not applied and is counted under elements_invalid in meta.skipped (see POST /import/parse) rather than reaching the stored request. Not read on the sync/diff path (POST /specs/diff / POST /specs/sync): DraftRequest, what that path compares a stored request against, deliberately excludes scripts and auth so a re-sync never silently overwrites what a user edited locally, and an element can carry a script.

x-vayu-mock carries a request's mockResponseMode (issue #1649) the same way x-vayu-elements carries its elements - written only when the mode is not "first", the default every unconfigured request already has, so an operation with no mock opinion gains no key at all. {"mode": "random"} needs no target; {"mode": "fixed", "example": "<key>"} names the examples map key (or the doubled key a name collision suffixed, add_named_examples's usual rule) the chosen example was written under, resolved by value rather than assumed - a target this export could not itself write (a truncated body, no recorded media type, a response the document does not declare) is the same "nothing to name" case as the mode staying "first", and gets no key either. Gated like x-vayu-elements: contract mode writes nothing into a Swagger 2.0 document's operations. The importer reads it back next to x-vayu-elements, matching example against the imported example that carries the same OpenAPI examples map key (the engine-side-only specExampleKey provenance field, issue #1457) and setting mockResponseMode / mockExampleId on the imported request; a key the document no longer has an example for degrades the way elements_invalid does - counted as mock_example_missing in meta.skipped and left on pick_example's own "first" default rather than naming a target that is not there. Not read on the sync/diff path, for the same reason x-vayu-elements is not.

Errors: 400 for a missing or empty collectionId, a format other than json/yaml, or a mode other than contract/full. 404 when the collection does not exist. 409 when the collection's binding names a document that is not stored, or when the stored bytes will not read as an OpenAPI object - the export refuses rather than falling back to a skeleton, which would silently replace the document the caller believes they are updating with one that drops everything Vayu does not model.

POST /specs/sync

Apply a re-fetched document to the collection bound to it, in one transaction: the document is stored, the binding moves to it, and the requests the caller selected are created, updated and deleted together. Half of that landing would leave a collection bound to a document its requests do not reflect, which is the state the binding exists to make impossible - so it is refused structurally rather than reported afterwards.

Deliberately not part of POST /import/apply: that route only ever creates, which is what lets it own every id and validate a payload with nothing stored behind it. A sync updates and deletes rows that already exist.

Request:

{
  "collectionId": "col_9a1f...",                       // Required; must be bound to a spec
  "spec": {
    "content": "{\"openapi\":\"3.1.0\", ...}",           // Required, non-empty, at most maxSpecDocumentBytes
    "sourceUrl": "https://api.example.com/openapi.json"  // Optional; null for a file or a paste
  },                                                   // Both indexes are derived - see POST /specs
  "policy": "safe",                                    // Optional - apply the safe ticks and state no rows.
                                                       // Mutually exclusive with the four sections below.
  "collections": [                                     // Optional - tag folders to create
    {"tempId": "t_col", "name": "pets", "parentId": "col_9a1f..."}
  ],
  "create": [                                          // Optional - operations the document added, or declined ones ticked
    {"tempId": "t_req", "collectionTempId": "t_col", "name": "Get a pet",
     "method": "GET", "url": "https://api.example.com/pets/{{petId}}",
     "specOperation": {"operationId": "getPet", "method": "GET", "path": "/pets/{petId}"}}
  ],
  "update": [                                          // Optional - merge-patch by id
    {"id": "req_1234...", "name": "List pets", "specOperation": {...}, "examples": true}
  ],
  "delete": ["req_5678..."]                            // Optional - request ids
}

Response:

{
  "idMap": {"t_col": "col_bb21...", "t_req": "req_cc34..."},
  "specId": "spec_dd45...",
  "specHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "syncedAt": 1730000000000,
  "created": 1, "updated": 1, "deleted": 1,
  "skipped": {"requests": 2, "fields": 3, "deletions": 1, "declined": 1}  // Only for a `policy` call - see below
}

policy is the alternative to stating rows (issue #871). "safe" - the only one - is core::safe_spec_apply, the same answer POST /specs/diff reports per entry as safe / safeFields: every operation the document adds, every field it moved that nobody here had edited, no deletions, none of the operations a person declined by deleting their request (issue #3031), and a request whose bound document could not be read left alone whole. The engine works out the rows, mints the tag folders an added operation needs (matching an existing direct child by name, creating one at most once per call), and writes them through everything below - the same validation, the same id minting, the same transaction. It exists because those rules used to live in the renderer alone, which put applying a drift out of reach of every caller that is not the Spec tab: electron/ may not import src/, so an MCP sync_spec would have needed a copy of the one judgement whose silent failure destroys a person's work.

Sending policy together with collections, create, update or delete is a 400: there is no reading of "the safe ticks, plus these" that is not a guess. A caller that wants anything the policy declines - a deletion, a field somebody edited - states the rows itself, which is what the app does the moment a user changes a tick.

skipped comes back only for a policy call and counts what it refused: requests left untouched entirely, fields the document moved that were not written (whether their request was skipped whole or applied around them), deletions not made, and declined operations not re-created. An explicit payload gets no such key - nothing was declined, because the caller chose the rows. It is reported for the reason the diff bounds its buckets rather than dropping entries: a call that answered only with what it wrote would read as "applied the drift", and the part it did not apply is exactly the part somebody has to decide about.

Five rules the payload cannot opt out of:

  • A delete here is permanent - it does not go to the Trash (issues #988, #1046). Every other delete in the engine is soft: the row is stamped and restorable. A sync is not a person removing a request, it is a reconciliation to a document, and the two differ in where the decision is made - POST /specs/diff reports every removal before anything is written, the app renders them as ticks the user unticks one by one, and policy: "safe" refuses deletions outright, so a deletion here is one a caller stated after being shown it. Leaving those rows stamped instead would put the operations a document no longer declares back in the trash on every sync, where restoring one re-creates a request the document cannot explain. The rows and the examples they own are removed in the sync's own transaction. A caller that wants the deletions recoverable omits them from the payload and issues DELETE /requests/:id per row, which is soft.
  • The bound subtree is the boundary. Every request an update or a delete names, and every collection a created request lands in, must be the collection being synced or one beneath it. Anything else is a 400 naming the item - without this the route would be a way to delete any row by id. A sub-collection bound to a different document (and everything beneath it) is outside the boundary (issue #3034): its requests belong to that document's contract, so a sync of this one cannot update or delete them, and a diff does not list them. A sub-collection bound to the same document is inside.
  • The engine mints every id, as /import/apply does: new rows are named by tempId and translated through idMap, and a body id is a 400.
  • examples is a decision, and the rows are the document's (issue #869). true on an update refreshes that request's imported examples from the document this call is storing; absent (or false) leaves every example alone. A created request always gets the responses its operation documents, so examples on a create item is a 400 - as is a list on an update, which is what a caller sent before this and what let a payload write an example for a response no document describes. A refresh whose request records no operation of the document being stored is a 400 too, rather than a silent no-op. Rows with origin: "user" (issue #588) always survive; the replacements take the block the replaced rows occupied, so a saved example never loses its position - "the first example" is what a mock server answers with. An operation whose documented responses were removed refreshes to no rows, which is how the last import's examples go. An example whose status the user deleted is not written back either (issue #722) - the delete left a tombstone and the refresh skips that status, so a sync of any field cannot undo it. The identity is the status, not the name, because a name carries the document's response description and moves when the document rewords it.
  • A request cannot be moved here. collectionId inside an update item is a 400; use PUT /requests/:id.
  • Creating a declined operation takes the decline back (issue #3031). A create item whose specOperation names the operation a declined entry stands for - followed into the document being stored by the diff's own identity rule - forgets that record in the same transaction, so ticking the entry is the user changing their mind and a later delete of the new request records afresh. The deletes in delete record nothing: the document dropped those operations, nobody declined them.

Errors: 404 when the collection does not exist. 400 when it is bound to no spec, when policy is not "safe" or arrives beside a row section, when a section is not an array, when a payload item is malformed (with error.item naming the tempId or the request id, as /import/apply does), or when the document is over maxSpecDocumentBytes - the same helper POST /specs uses. 409 when an update names a request that no longer exists: nothing about the payload is wrong, the ground the diff was computed against has moved, and re-checking is what the client should do. A delete naming a request that is already gone is not an error - that is the state the caller asked for. Nothing is written unless all of it is.

Reorder

POST /reorder

Reposition collections and requests in one atomic batch - the write path behind a drag-and-drop reorder or a cross-folder move. One drop is one call, one lock scope and one transaction: the batch validates, stages and commits under a single acquisition of the engine's database lock, so nothing partial survives a rejection and no concurrent write - a create computing its append slot, a conflicting batch, a cascade delete - can land between what this batch checked and what it wrote.

Request:

{
  "normalize": [
    {"parentId": "col_1234567890"}
  ],
  "moves": [
    {"type": "request",    "id": "req_1", "order": 0, "collectionId": "col_2"},
    {"type": "collection", "id": "col_3", "order": 1, "parentId": null}
  ]
}

Both arrays are optional (absent or null means none); an empty batch is a 200 that writes nothing.

moves - each entry names one row and the position it takes:

Field Rule
type "collection" or "request"; anything else is a 400
id Non-empty string naming a stored row of that type
order Required, an integer from 0 to 2147483647. Not a float, not negative, not past the column - this endpoint writes dense positions, and each would be a silently truncated, unreachable or wrapped slot. Anything else is a 400, e.g. Invalid move at index 0: 'order' must be an integer from 0 to 2147483647 (got 2147483648)
parentId (collection) Absent keeps the current parent; null or "" moves to the root; any other string moves under that collection, which must exist; anything else is a 400 naming parentId
collectionId (request) Absent keeps the current owner; a string moves to that collection, which must exist

A row may appear in moves at most once - two positions for one row is a 400 naming it, not a last-writer-wins accident of iteration order.

normalize - each entry names a parent, and its children are renumbered dense 0..n-1 in the sibling order before any move applies. The children are the parent's sub-collections and its requests as one list (#2535), so a tie across the two kinds comes out as distinct numbers with the sub-collection first. An entry is {"parentId": <collection id>}, or {"parentId": null} ("" reads the same) for the root collections (the roots hold collections only). The named collection must exist, and parentId must be stated rather than omitted, so a renumber can never land on a scope the caller did not mean. The per-kind shapes engines before #2535 took, {"type": "collection", "parentId": ...} and {"type": "request", "collectionId": ...}, are a 400 naming the shape above: renumbering one kind alone would leave it tied with the other kind's slots.

Normalization exists for the first drop into a collection whose rows predate explicit orders: every row sits at 0, so its displayed position lives only in the tiebreak and there are no slots to shift into. Materializing that order in the same batch is what keeps the other siblings from appearing to jump; a parent with every row at 0 comes out with its sub-collections at 0..m-1 and its requests after them, the order the tie rule already showed. It is idempotent - a scope already dense writes nothing at all.

Where a row is named by both lists, the move wins.

A move out of a spec contract declines the operation (#3446), the rule PUT /requests/:id applies to one request, with the same meaning of out. A request that records an operation (specOperation) and that the batch leaves outside its contract comes back with specOperation: null, and the operation is recorded as declined under the binding it left, in the batch's transaction. A moved collection does this for every stamped request beneath it, as a parentId sent to PUT /collections/:id does (#3470). The binding after and the contract are read against the tree the batch writes, so a request moved into a folder the same batch moves away is judged by where the folder lands. A move within one contract keeps the stamp, and so does moving the bound collection itself. Each request this clears is in the response, a request whose position did not change included.

Validation is complete before the first write. Entry shapes, the existence of every named row and owner, and the acyclicity of the post-move collection graph are all checked first; a failure is a 400 naming the offending row with nothing written. The cycle check reading the post-move shape is what makes two reparents that each look legal alone (A under B and B under A) a deterministic rejection rather than a race. The same pair sent as two PUT /collections/:id calls is caught as well - each update holds its read to its write - but one at a time, so the first reparent is already committed when the second is refused; the batch refuses both and writes nothing.

That rejection is deterministic because the check and the commit share one lock scope: two such batches arriving concurrently are serialized whole, and the second revalidates against the first's committed graph rather than against the shape both of them read. The rows are written as updates, never inserts, so a batch whose row was deleted after it staged fails with a 409 naming the row and writes nothing at all - it never re-creates the deleted row.

Response: the rows as written, in the same serialized shape a list entry carries - not an acknowledgement. A client that drew the drop optimistically settles its caches on these, so a normalization the engine performed is visible without waiting for a refetch.

{
  "collections": [],
  "requests": [
    {"id": "req_1", "collectionId": "col_2", "order": 0, "name": "Get users", "...": "..."}
  ]
}

Errors: 400 for any malformed entry (a per-kind normalize entry included), a row or owner that does not exist, a duplicate move, a cycle, or a batch over 10000 entries. 409 if a staged row is gone by the time the batch commits. In every case nothing at all was written. Body that is not JSON or not an object is also a 400.

Import

POST /import/fetch

Fetch a remote collection or spec by URL, server-side, so the app can import a resource that browser CORS would otherwise block. The engine proxies the GET via libcurl and returns the raw body and content type.

Request:

{ "url": "https://example.com/collection.json", "maxBytes": 10485760 }

The url must be a string whose scheme is http or https, in any case (see URL schemes).

maxBytes is the caller's bound on the response, and the caller states it because this route is one proxy for every import format - a Postman or Insomnia export rides it exactly as an OpenAPI document does. Bounding it by maxSpecDocumentBytes would refuse a collection that imports today with a message naming a setting that governs nothing about it, so the callers that are fetching a spec ($ref bundling and spec re-fetch) pass that live cap themselves and the rest pass nothing.

  • Absent or null means the engine's transport ceiling, 256 MiB. So does a larger value: a bound over the ceiling is clamped to it rather than refused, because maxSpecDocumentBytes can be raised to 100 MiB and an import the setting allows must not be turned into a 400.
  • Anything that is not a positive integer - 0, a negative, a string, a fraction - is a 400. It is not rounded into a bound the caller did not ask for.
  • The bound is on what is read, not on what is returned: the transfer is cut off as soon as the body grows past it, whether the server declared a length or not, so nothing buffers the whole document first. A declared length is what the refusal names as the size.

A fetch is bounded by a stall, not by a total (issue #882). This route used to inherit the 30-second timeout_ms every request carries, which bounds a download's size rather than its health: 10 MB needed better than 340 KB/s merely to arrive, and the failure read Operation timed out after 30001 milliseconds with 4177920 out of 6296254 bytes received for a transfer that had never once stopped. It is now abandoned only after constants::import_fetch::STALL_TIMEOUT_MS below STALL_FLOOR_BYTES_PER_SEC - so a slow link finishes, slowly, and a dead one still ends. What bounds a transfer that never ends at all is maxBytes above, which is the bound that was always meant. Connecting is bounded apart from the stall, at the stall window capped at 30 seconds (issue #2835): the stall window only runs once a connection is made, so a host that never completes the handshake would otherwise hold the fetch for libcurl's 300-second default. Both forms of the route get this: a document must not arrive on one and time out on the other.

reference: true marks a fetch a document asked for, not a person (issue #2364): $ref bundling sends it, with sourceUrl set to the URL of the document the reference was found in. A URL typed into the import dialog or a spec re-fetch sends neither field and is fetched exactly as before, loopback and redirects included.

{ "url": "http://localhost:3000/schemas/pet.json", "maxBytes": 10485760,
  "reference": true, "sourceUrl": "http://localhost:3000/openapi.yaml" }
  • reference is a boolean, default false; sourceUrl is an http or https URL. Absent or null means the default for either; any other shape is a 400, and a malformed sourceUrl is refused even without reference.
  • No redirect is followed. A 3xx is the upstream's answer and is refused as every non-2xx one is (502 The server answered HTTP 302): a hop is a target the document never named.
  • A loopback or link-local peer is refused unless it is the source's own. Judged on the address libcurl connected to, so a name that resolves there (localhost, *.localhost, a DNS record pointing at 127.0.0.1) is caught as surely as a literal. Refused: 127.0.0.0/8, ::1, ::ffff:127.0.0.0/104, the unspecified 0.0.0.0 and ::, 169.254.0.0/16 (cloud metadata lives there), ::ffff:169.254.0.0/112 and fe80::/10. Allowed: a peer on sourceUrl's port (its scheme default when it names none) when either the source host is itself loopback (localhost, *.localhost or a loopback address) and the peer is loopback, or the source host is the peer's address written as a literal - the only way a link-local peer is ever the source's. A source named by a host name that resolves to loopback earns nothing: that is what a rebinding DNS answer looks like. With no sourceUrl, every loopback and link-local peer is refused.
  • The refusal is 502 Couldn't fetch the document: Cannot send this request: Vayu does not fetch a reference from a loopback or link-local address other than its source document's own host and port - not when the URL names one and not when a host name resolves to one, on both forms of the route.
  • The URL is judged before anything is dialled, by the same source rule: a reference whose host names a loopback or link-local address in any spelling, localhost or a *.localhost name is refused with the same 502, and the source's own host and port stay allowed (issue #2605).
  • A proxy you configured is not refused. With a proxy in force the connected peer is the proxy, so the rule passes the one the transport names (manual, or system when it resolved one; matched on its address and port, a localhost proxy URL meeting any loopback address) and the URL check above is what judges the reference. Behind a proxy the engine cannot see where the proxy sends the request next, so a host name the proxy resolves to loopback is the proxy's to answer. A proxy URL with no port is dialled on libcurl's proxy default, 1080 (443 for an https proxy).
  • environment mode stays uncovered, as does system when it resolved nothing and falls back to it. There libcurl reads the proxy from the process environment (http_proxy, https_proxy) and the engine never learns it, so a proxy on loopback picked up that way is still refused for every reference unless it is the source's host and port. Set it as manual to fetch references through it.
  • Vayu's own engine and MCP ports stay refused whatever the source (Reserved local ports); this rule is added to that one, never in place of it.

Response: 200

{
  "content": "...raw response body...",
  "contentType": "application/json"
}

contentType echoes the fetched response's Content-Type header, defaulting to application/octet-stream when absent. The response JSON is serialized with invalid UTF-8 replaced rather than throwing, so binary or malformed content can never turn into a 500.

Errors: - 400 Invalid JSON: <parser message> - the request body did not parse; request body is nested deeper than 128 levels when it nests past the bound. - 400 Invalid URL - url is missing, not a string, or names no scheme. - 400 Invalid URL: scheme '<scheme>' is not supported - only http and https URLs can be sent - url names any other scheme (ftp, file, ...). - 400 Invalid 'maxBytes': must be a positive integer. - 400 Invalid 'reference': must be a boolean. - 400 Invalid 'sourceUrl': must be an http or https URL - also a URL that names no host. - 413 Refused to fetch: <detail> - the response was over the bound in force. The detail names the bound that was applied (the clamped one, not the one asked for) and the size when the upstream declared one. - 502 Couldn't fetch the document: <detail> - the upstream request failed (connection error, transport failure), or a reference's peer was refused (see reference above). - 502 The server answered HTTP <status> - the upstream answered, but with a status outside 2xx. Its body is not the document, so it is not returned as content: handed on, a 404 or 500 page would reach the format reader and be reported as an unrecognised format.

With Accept: text/event-stream the same fetch answers as a stream (issue #882), reporting the download as it arrives. An 8 MB spec behind a URL is otherwise a client with nothing to draw: the buffered form above cannot say a word until libcurl holds the entire body, and the wait is on the upstream download, so no amount of streaming between engine and client would help.

Three events, and the last one is always terminal:

Event Data Meaning
progress {"received": 262144, "total": 8388608} Bytes buffered so far. total is the upstream's Content-Length and is null when it declared none - a chunked response has no denominator, so a client shows bytes received rather than a percentage of a number nobody stated.
result {"content": "...", "contentType": "application/json"} Exactly what the buffered form returns.
error {"status": 413, "error": {"code": "error", "message": "..."}} The failure the buffered form would have answered with.
  • A malformed request is still the 400 above, on both forms: it is decided before any of the response has gone out, while a status is still available to say it with.
  • A failed fetch is an error event, not a status. The response headers left before the download began, so the 200 is already spent - which is why that event carries the numeric status itself. The standard error body could not: its code is a slug, and 413 and 404 both slug to plain error.
  • Progress is throttled to at most one frame per 256 KiB or 100 ms (constants::import_fetch::PROGRESS_EVERY_BYTES / _MS). libcurl reports every ~16 KiB write, which for a 10 MB document is ~640 frames for a bar with a few hundred pixels to cross.
  • Closing the stream stops the download. The engine abandons the transfer as soon as a write to the SSE sink fails, rather than reading the remaining megabytes for a client that has gone.
  • Every caller that sends no Accept gets the buffered JSON unchanged, which is what $ref bundling, spec re-fetch and the MCP tools do.

POST /import/parse

Parse a raw import document into the tree POST /import/apply persists (issue #877). Reads only - nothing is stored, so a preview costs no write.

Every format Vayu accepts, detected by content, in the order the app's dispatcher used to run its parsers in - so a document carrying two formats' keys is claimed by the same one it always was:

Claimed by meta.format
info.schema naming v2.1.0 Postman Collection v2.1
info.schema naming v2.0.0, or info + item[] with no schema Postman Collection v2.0
_postman_variable_scope: "environment" + values[] Postman Environment
_postman_variable_scope: "globals" + values[] Postman Globals
_type: "export" + __export_format: 4 Insomnia Export v4
type: collection.insomnia.rest/5.x or environment.insomnia.rest/5.x Insomnia Export v5
openapi starting 3.1 OpenAPI 3.1
openapi starting 3. (any other 3.x) OpenAPI 3.0
swagger being 2.0 (string or number) OpenAPI 2.0 (Swagger)
the raw text contains <jmeterTestPlan JMeter <version> Test Plan

The bytes are read once, JSON first and YAML second, through the same core::read_document behind POST /specs and POST /specs/describe. This is the only parser: the renderer holds none, which is what makes "exactly one reader has an opinion about a document" true rather than nearly true. JMeter's .jmx is the one exception to "read once through read_document": it is XML, checked on the raw text (issue #1518, is_jmeter_document) before that reader ever runs, since XML fails both of its formats the same way genuinely unrecognised bytes do - see docs/app/import-collections/jmeter.md for the class mapping.

Insomnia v5 (issue #2119) is the YAML document Insomnia 11 and later export, one per collection or environment. It is read through the v4 mapping: the nested collection[] tree (a children array makes a folder) and the environments object with its subEnvironments[] are flattened into v4's resource list, so both versions of one workspace import as the same tree and only meta.format tells them apart. An environment.insomnia.rest/5.x document imports environments only, under importEnvironments like a Postman environment export; with no sub-environment its one environment is named after the document. A gRPC or WebSocket item is counted in meta.skipped as grpc / websocket, as in v4, and cookieJar and certificates are not imported. The member spellings are those of Insomnia's v5 schema; a member spelled otherwise reads as absent.

Variable names are trimmed (#3251). {{ name }} looks a variable up trimmed, and the write routes refuse a stored name that is blank or differs from its trim (Accepted field shapes). The parse therefore trims every variable name it reads (Postman variable[] and values[], an Insomnia environment's data keys, a dotted nested name as a whole) and skips a row whose name trims to nothing, uncounted, as an empty name always was. Two names that trim alike collide and the later row wins, as exact duplicates do. An x-vayu-collection / x-vayu-folder variables object carrying such a name is an invalid extension piece (vayu_extension_invalid) and the standard reading stands. POST /import writes the parsed globals through the same trimmed names. A hand-built POST /import/apply tree is not repaired: a padded name in it is the same 400, and the whole atomic apply fails.

A Postman variable carries its file position as createdAt (#3252). A stored variables object keeps its keys in name order, and the app lists a scope by createdAt (VariableValue shape), so every row of a Postman variable[] or values[] is stamped with one clock reading per parse plus its position in the array: strictly ascending in the file's order, in epoch milliseconds.

Request:

{
  "content": "{\"info\": {...}, \"item\": [...]}",
  "importEnvironments": true,
  "importScripts": true,
  "fileName": "collection.json",
  "sourceUrl": "https://acme.dev/openapi.json",
  "unresolvedRefs": 0
}

Field Type Notes
content string, required The document, verbatim. An OpenAPI import stores exactly these bytes as its spec document, so it is never re-serialized.
importEnvironments bool, default true Off, the environments and global variables a document carries are not built and the counts report 0 - gated at parse time, so a preview shows what will actually be created.
importScripts bool, default true Off, every script imports empty.
fileName string Display only; echoed on meta.fileName. Never stored.
sourceUrl string Recorded on a stored OpenAPI document (so a later sync knows what to re-fetch) and used to resolve a relative servers[0].url.
unresolvedRefs int ≥ 0 External $refs a bundling pass could not reach, counted into meta.skipped as external_ref. Nothing here follows a ref.

Response: 200 - the whole import tree.

{
  "collections": [ { "name": "Sample API", "description": "", "variables": {}, "auth": {"mode":"none"},
                     "elements": [], "children": [], "requests": [] } ],
  "environments": [],
  "globals": {},
  "clientCertificates": [],
  "meta": {
    "format": "Postman Collection v2.1", "requestCount": 2, "folderCount": 1,
    "environmentCount": 0, "globalCount": 0, "exampleCount": 0,
    "skipped": [ { "kind": "unsupported_auth", "count": 1, "requests": ["Get user"] } ],
    "nonExecutableAuth": 0, "unattachedFileParts": 0,
    "unsupportedScriptApis": [ { "request": "Sign in", "names": ["require()", "cheerio"] } ]
  }
}

meta.unsupportedScriptApis (Postman only, issue #2576) is [{request, names}]: each request, folder or collection (by its name) whose imported scripts use a Postman script API Vayu does not run, and which ones - require() of a module off the crypto-js / uuid / lodash / moment / csv-parse/lib/sync / xml2js / chai / ajv / tv4 shelf, script.packages, a bundled library such as cheerio, a host global such as fetch or URL, an undefined pm.* member such as pm.cookies.set, a console method such as console.debug, and the other rows of the table in engine/src/core/script_api_scan.cpp (it does not scan process, window, document or alert). It is absent when empty and for every other format, is not a meta.skipped kind, and never changes what is imported; docs/app/import-collections/postman.md#scripts has the rules.

meta.skipped is one {kind, count} per kind the parse counted, in a fixed kind order. requests, when present, names the requests the count applies to, in the order the walk met them: every count an OpenAPI parse takes while on an operation, Postman's per-request counters (and, for script_unsupported, the folder or collection that declares the script), and Insomnia's file bodies, unsupported auth types, cookie API keys, insomnia scripts and the resources it cannot import. A count that belongs to the document (a second server URL, a malformed section) has none. names, when present, names what the count dropped, never its value: oauth2_unmapped_param, whose names are the keys of the OAuth 2.0 request parameters a Postman parse did not carry, and protocol_behavior_folder, whose names are the folders or collection that declared a setting Vayu cannot apply. A Postman parse also counts body_on_get (#2540), named under requests: a GET or HEAD whose mapped body is not empty and whose resolved protocolProfileBehavior.disableBodyPruning is not boolean true, a body Postman drops before sending and Vayu sends. The parse maps the body as written.

clientCertificates is present, and only ever non-empty, from a Postman parse (issue #1656): a client_certificates registry candidate resolved from a request's own certificate, in the same field shape POST /client-certificates takes (host, port?, certPath, keyPath?, certFormat?, passphrase?). A candidate is resolved only when it would pass that route's own check - a readable PEM pair or PKCS#12 file, a literal (not {{var}}) host, no earlier request in this parse already claiming a different certificate for the same (host, port) - so resolving one is the common case only when the collection's certificate paths are reachable from this machine, which a real-world Postman export's rarely are (its paths name files on the exporting machine). Anything that does not resolve counts into meta.skipped as certificate instead of appearing here. Every other format sends no such key. See docs/app/import-collections/postman.md.

meta.skipped is what the document declared and Vayu cannot represent, counted per kind. The fixed kinds, in the order they are reported (ORDER in ImportTally::items(), engine/src/core/openapi_drafts.cpp):

kind Counted when
websocket, grpc An Insomnia resource that is a WebSocket or gRPC request, which has no Vayu request shape
api_spec An Insomnia design document (api_spec resource)
unit_test An Insomnia unit test or unit test suite
file_body A whole-file body (Postman file, Insomnia binary, an OpenAPI application/octet-stream or format: binary body), imported as a binary body whose file is still to choose
malformed_item A Postman item[] or event[] entry that is not an object, or a saved response that is not an object, whose numeric code is not an integer from 200 to 599, whose body is over 1 MiB, or that comes past the request's first 100 (the request still imports)
unsupported_method A Postman custom HTTP verb (imported as GET), or an OpenAPI trace operation (dropped; HttpMethod has no TRACE)
malformed_spec An OpenAPI path item, parameters list or response whose shape the specification does not allow, stepped over so the rest of the file still imports
example_no_status An OpenAPI response key that is neither default nor a status from 200 to 599 (a 2XX wildcard, a 1xx interim response, junk)
example_no_media_type An OpenAPI response that documents a body (a 3.x content map with entries, a 2.0 examples map or schema) and yields none: no JSON type that yields one, and no declared string or text-family (text/*, */xml, */html) example, a media range (a key containing *) never counting; the example imports without a body (#3424)
default_response An OpenAPI response keyed default - conformant, and counted as information rather than as a loss
external_ref A $ref into another file that a bundling pass could not reach (the request's unresolvedRefs)
duplicate_operation_id An OpenAPI operationId that an earlier operation already declared; the first keeps the id
webhook_operations An operation under a 3.1 top-level webhooks entry: it describes a call the API makes to the user, not a request Vayu can send
deprecated_operation An OpenAPI operation declared deprecated: true; the request model has no such flag, so it imports like a current one
cookie_param An OpenAPI parameter declared in: "cookie", which has no row to land in
unmapped_body An OpenAPI requestBody declaring only media types with no Vayu body mode and no binary schema, one per operation
unresolved_base_url servers[0].url still holds a {variable} with no default, or is relative and the document has no source URL; it is kept as written
no_server_url The OpenAPI document names no server URL, so no {{baseUrl}} variable is created
servers_dropped An OpenAPI 3.x document with more than one servers entry: only servers[0] becomes {{baseUrl}}, and the count is the entries past the first
unsupported_auth A Postman auth block whose type the schema does not define, or an Insomnia authentication.type with no Vayu mode (asap, netrc) or that is not a string; either way it imports as no auth, never inherit (an Insomnia folder's ends the inherit walk as noauth)
security_unmapped_or An OpenAPI operation whose security lists more than one alternative requirement; it stays inherit
security_unmapped_and An OpenAPI operation whose security requirement names more than one scheme at once; it stays inherit
security_unmapped_scheme An OpenAPI operation whose security names a scheme the document never declares; it stays inherit
security_unmapped_mutualtls An operation's security names a mutualTLS scheme, which has no Vayu auth mode; it stays inherit
security_unmapped_openidconnect An operation's security names an openIdConnect scheme, which has no Vayu auth mode; it stays inherit
security_unmapped_type An operation's security names a scheme of any other type with no Vayu mode (an http scheme other than bearer or basic, or no readable type); it stays inherit
security_unmapped_apikey_cookie An operation's security names an apiKey scheme with in: "cookie"; Vayu's API-key mode has only header and query placements, so it stays inherit. An Insomnia API key with addTo: "cookie" that has no place to go is the same kind: a folder's (imported as noauth, ending the inherit walk) or the workspace's (none), which have no header row to hold it, and a request's with no key name, which has no cookie to write. Folders and the workspace are unnamed
apikey_cookie_header An Insomnia request's API key with addTo: "cookie", imported as no auth plus a Cookie: key=value header row (merged into an enabled Cookie row the request already has) - a mapping the user may want to check, not a loss
oauth2_dropped_field A Postman OAuth 2.0 block carrying a pre-fetched accessToken beside an explicit grant configuration; the token is not imported
oauth2_state_regenerated A Postman OAuth 2.0 block with a fixed state; Vayu generates its own per authorization attempt
oauth2_unmapped_param A Postman OAuth 2.0 extra request parameter that was not carried, its key under names
url_without_raw A Postman URL object with no raw form, assembled from its host, port and path - a mapping, not a loss
variable_metadata A Postman variable type with no Vayu counterpart ("any", a custom string), or an environment or globals variable's description
disabled_body A Postman request body whose own disabled is true; it imports as no body rather than sending what the user switched off
certificate A Postman request's own certificate that did not become a registry candidate (no cert.src / key.src, an unreadable file, a {{var}} host, or a conflict for the same (host, port)), plus the candidates left unticked in the preview
proxy_config A Postman request's own proxy override; there is no per-request proxy to import it into, so this count is permanent
protocol_behavior A Postman request's protocolProfileBehavior setting that Vayu stores for the export but does not apply, or host / content-length in its disabledSystemHeaders
protocol_behavior_folder The same, declared on a folder or the collection: counted once per declaring node, its name under names
body_on_get A Postman GET or HEAD with a non-empty body whose resolved disableBodyPruning is not true: Postman does not send it, Vayu does
script_unsupported A Postman enabled event with a script.src, or script text under a listen other than prerequest / test, which has no element to become
script_unsupported_insomnia An Insomnia request, folder or workspace whose imported, non-blank script uses the insomnia object, which Vayu does not define; the script is kept and throws when it runs. Counted once per owner, only with importScripts on, the owner under requests

Three kinds are counted but are not in that order, so they come after it, in first-encountered order: elements_invalid (an elements array, from a document a Vayu export wrote, that fails the element registry's validation and is not applied), mock_example_missing (a stored mock setting that names an example the document does not carry) and vayu_extension_invalid (a piece of an x-vayu-* extension that fails its check; the standard reading stays in place). Not every kind is a loss: default_response and url_without_raw count a mapping the import made rather than something it dropped (see docs/app/import-collections/postman.md), and so does file_body: a whole-file body (Postman file, Insomnia binary, an OpenAPI application/octet-stream or format: binary body) imports as a binary body naming the file, and the count, with its requests, says which bodies have a file to relink or choose. Every file reference an import writes - a binary body's file, a form-data file part - carries the path the document named, which the engine sends only once the file is picked again or lies under an allowed folder. POST /import/parse answers each with the derived unresolved (the trust rule): true for a path this machine would refuse, so the preview can offer to allow its folder. A reference with no path ("src": "") imports as no file chosen; form parts in that state are counted in meta.unattachedFileParts. An import that loses something and says nothing is the defect this list exists to prevent, so a format with nothing to report answers [] rather than omitting the field. A JMeter import's kind is not limited to this list (issue #1518): a .jmx class this parser has no element-kind mapping for is counted under its own literal class name (CookieManager, CSVDataSet, ...), since JMeter's own class list is open-ended - ImportTally::items() emits every kind it was given a count for, the enumerable ones first in the fixed order above, anything else after in first-encountered order. A JMeter ThreadGroup whose threads, ramp-up, duration or loops are not the defaults is counted as ThreadGroup_profile (one per group), and the item's names lists one line per group with the values as written, e.g. Users: 10 threads; ramp-up 5s; 3 loops, so a client can show what to set on the load run; a setUp or tearDown group is counted under SetupThreadGroup / PostThreadGroup, once per sampler left out (docs/app/import-collections/jmeter.md). A JMeter request with both a connect and a response timeout is counted as Timeout_total (one per request, its name in names) because Vayu keeps one total timeout and adds them, and a timeout that is not a number (a ${var}) as HTTPSampler_timeout_unrecognised. meta.folderStrategy (tags / paths / mixed) is present only when an OpenAPI import built folders, since a document that declares no operation tags gets a tree it never spelled out.

A document Vayu exported reads back as the collection it came from. An operation's x-vayu-request and the root's x-vayu-collection (see POST /specs/export) are applied over what the standard members produced: the request's name, method, URL, rows, body, auth, settings and saved examples, and the collection's variables, auth, data contract and whole folder tree. With x-vayu-collection present the document states its own tree, so folders nest as it says, each request is filed under its x-vayu-request.folder, folders and requests take their stored order (below), a request with none stays on the root (no folder named after its path, and no folderStrategy), and the requests no operation could hold are created too. A document is a file anyone can edit, so none of it is trusted: every piece is checked against what the write routes accept before it replaces anything, and a piece that fails is dropped, counted as vayu_extension_invalid, and leaves the standard reading in place - never a refused import. Neither key is read on the sync/diff path, for the reason x-vayu-elements is not.

A folder or request draft may state order, its position among its parent's sub-folders and requests, which share one order space (#2535). A Postman parse states it on every one: the item's position in its parent's item[], so the collection keeps the order Postman runs it in. A JMeter parse (#2573) states it the same way on every sampler and controller folder: its position among the parent's enabled elements in the plan's tree, one count across both kinds, which a ThreadGroup shares with the parent it flattens into. An Insomnia parse, v4 or v5 (#2573), states it as each folder's and request's rank, 0..k-1, among the parent's siblings that import, ordered by ascending metaSortKey (v5's meta.sortKey) with ties in document order; a parent where any such sibling has no numeric key states none, so its folders come first. A Vayu-written OpenAPI document states each request's x-vayu-request.order and each folder's x-vayu-collection.folders[].order; one written before folders carried an order states none, and its requests then follow its folders as they did. No other format states one. The flattening into POST /import/apply (POST /import, and the app's apply of a previewed parse) numbers each parent's children 0..k-1 in one sequence: by stated order, a draft stating none placed as though its parent listed its folders first and its requests after them, and a folder first on a tie. The preview tree lists them in the same order.

Errors: - 400 Invalid 'content': must be the document's text, and 400 Invalid 'content': an empty document is not an import. - 400 Unrecognised format - readable, and no format claims it. Kept as its own sentence: "Vayu does not read this kind of file" and "this file is broken" are different answers. - 400 Couldn't read the document: <detail> - neither JSON nor YAML, with the line named. - 400 Couldn't read the document: this is an Insomnia <kind> export, which Vayu does not read. Export the collection instead. - an Insomnia document that is not a collection or an environment: <kind> reads design document (spec) for spec.insomnia.rest/, mock server for mock.insomnia.rest/, and the type's own prefix otherwise. A collection or environment in a format other than 5.x gets ... this is an Insomnia collection export in format 6.0, which this version of Vayu does not read. It reads format 5. Neither is Unrecognised format, so the app shows the sentence as written. - 400 Malformed Insomnia export: <field> must be an array (or an object) - Insomnia's resource list (v4) or nested tree (v5) broken where the walk needs it, so there is nothing to walk; a v5 field is named by its path (collection[0].children[2]). - 400 Malformed JMeter test plan: <detail> - XML pugixml could not parse, or well-formed XML with no <jmeterTestPlan> root. - 400 Invalid 'importScripts': must be a boolean (and the same for importEnvironments, fileName, sourceUrl, unresolvedRefs). - 413 Import document is N bytes, over the limit of M (raise the 'maxSpecDocumentBytes' setting to allow more).

Body cap (POST /import, /import/parse, /import/document). The management API buffers a request body before a route sees it, so these three routes are bounded from the Content-Length header, before the body is read: a body over maxSpecDocumentBytes plus half again plus 1 MiB (headroom for the JSON string escaping of the document) answers 413 Request body is N bytes, over the limit of M for an import (raise the 'maxSpecDocumentBytes' setting to allow more). The limit is read live, so a raised setting applies to the next request. A chunked body is refused with 411 like on every route (see Request bodies). The exact check on the content string described below still runs after the parse. A client that streams a very large body may see the connection closed rather than the 413, since the body is not read.

POST /import

Parse a document and persist it, in one call - POST /import/parse, the flattening into temp-id'd sections, and POST /import/apply, for a caller with no preview to show (issue #877). This is what the MCP import_document tool wraps. The app deliberately does not use it: a person picks which files of a batch to import and toggles two options between the parse and the apply.

Request: the same body as POST /import/parse.

Response: 200

{
  "idMap": { "c1": "col_<uuid>", "r1": "req_<uuid>" },
  "meta": { "format": "Postman Collection v2.1", "requestCount": 2, "...": "..." },
  "collections": 2, "requests": 2, "environments": 0, "globals": 0
}

Atomicity: the tree is one POST /import/apply transaction, so a refused document creates nothing. The globals a Postman globals export carries are the one write outside it, and they run last and merge: POST /globals replaces the whole set, so running it in front of a write that can still fail would leave a user's globals half-rewritten by an import that then failed. On a key collision the imported value wins - the caller asked for this file's variables, and skipping them would be a silent no-op - but the stored row keeps its createdAt (or its lack of one), so a replaced global keeps its place in the list (#3252). A Postman import's clientCertificates candidates (issue #1656) are also outside the tree's transaction, applied best-effort inside POST /import/apply itself after it commits; a candidate POST /import/apply cannot register is skipped, never fails the call.

Errors: every error of POST /import/parse, plus every error of POST /import/apply (including the per-item 400s naming a tempId).

POST /import/document

Read a document's bytes (JSON or YAML) into a JSON DOM, through the engine's one reader. Stores nothing and interprets nothing: this is what the bytes are, where POST /specs/describe says what they declare.

One caller, and it is the reason the route exists: the app's ref-bundler.ts walks a multi-file OpenAPI document to inline the files it references before anything is parsed or stored, and finding and rewriting those $refs needs a tree. A YAML reader in the renderer to get one was the last thing keeping a second parser in app/src after issue #877.

Request: {"content": "openapi: 3.0.0\npaths: {}\n"}

Response: 200 {"document": { "openapi": "3.0.0", "paths": {} }} - in the document's own key order, which is a promise a JavaScript object cannot keep (it orders integer-like keys numerically ahead of the rest).

Errors: - 400 Invalid 'content': must be the document's text. - 400 Invalid 'content': <detail> - neither JSON nor YAML. - 413 Document is N bytes, over the limit of M (raise the 'maxSpecDocumentBytes' setting to allow more).

POST /import/apply

Persist an entire parsed import - collections, their requests, environments, and the OpenAPI documents they bind - in one atomic call. Items reference each other by opaque temp ids the client invents; the engine generates every real id via generate_id and returns the translation in idMap. A fifth section, clientCertificates (issue #1656), is not part of that atomic tree or its temp-id namespace - see its own bullet below.

This is what replaced ~500 sequential POST /collections + POST /requests calls for a 500-request import, and with it the only reason those endpoints ever accepted a client-supplied id - which they no longer do (see The engine owns every id).

Request:

{
  "specs": [
    { "tempId": "s1", "content": "{\"openapi\":\"3.1.0\", ...}",
      "sourceUrl": "https://api.example.com/openapi.json" }
  ],
  "collections": [
    { "tempId": "c1", "parentTempId": null, "name": "My API", "order": 0,
      "variables": {}, "auth": {"mode":"none"},
      "openapi": {"specTempId": "s1"},
      "elements": [] },
    { "tempId": "c2", "parentTempId": "c1", "name": "Users", "order": 0 }
  ],
  "requests": [
    { "tempId": "r1", "collectionTempId": "c2", "name": "List users",
      "method": "GET", "url": "https://api.example.com/users",
      "params": [], "headers": [], "body": {"mode":"none"}, "bodyType": "none",
      "auth": {"mode":"inherit"}, "order": 0,
      "examples": [
        { "name": "200 - A user", "status": 200, "headers": [], "body": "{}",
          "contentType": "application/json" }
      ] }
  ],
  "environments": [
    { "tempId": "e1", "name": "Prod", "variables": {} }
  ],
  "clientCertificates": [
    { "host": "api.example.com", "port": 8443, "certPath": "/home/alice/certs/client.pem",
      "keyPath": "/home/alice/certs/client-key.pem", "certFormat": "pem" }
  ]
}

  • All five sections are optional; absent or null means "none of that kind" (the null-vs-absent rule). An empty payload is a 200 with an empty idMap.
  • Every item needs a non-empty string tempId, unique across the four tree sections (they share one namespace, because idMap is one flat map) - clientCertificates items carry no tempId at all, see below. Temp ids are never stored.
  • A collection's parentTempId and a request's collectionTempId must name a collection tempId in the same payload; references may point forward, so a child may appear before its parent. parentTempId is null (or absent) for a root.
  • Every other field is the one the matching POST /<resource> accepts, with the same defaults and the same null rule - the engine runs the same per-resource field appliers for both paths. id is not accepted here: the engine owns ID generation on this path.
  • order is optional, and a stated one is written as given. An omitted order appends after the parent's existing children and then in payload order: each row gets the next slot of its parent (the per-item default cannot do this in bulk, because none of the payload's own siblings are stored yet). A parent's sub-collections and requests share those slots (#2535): the sub-collections that state no order take them first, in payload order, and then its requests, so a request with no order lands after its folder's sub-collections rather than tied with the first of them. The roots hold collections only. The app's importer states every order below the roots, one sequence per parent in the order the parse placed the drafts (see POST /import/parse), and deliberately omits it on its root collections, so an import into a non-empty workspace lands after the roots already there instead of colliding with their 0, 1, 2....
  • A request may carry examples, an array of saved example responses. They are nested rather than a fourth section because nothing references them: they need no tempId, get engine-generated ids, and so do not appear in idMap. Each entry takes the fields POST /requests/:id/examples accepts, through the same field applier, and an entry that fails validation is a per-item 400 naming the request's tempId. origin is among those fields: a spec or Postman import leaves it at its "import" default, which is what those rows are, and a Vayu OpenAPI export re-imported passes through the origin it wrote into x-vayu-request.examples (#2430), so a user-saved example stays "user". An entry with no order takes its payload position, so the stored order is the order the source file listed the responses in.
  • A specs item carries content (required, non-empty) and an optional sourceUrl; its hash and fetchedAt are engine-computed and a per-item 400 if sent, and the size cap is the same live maxSpecDocumentBytes that POST /specs enforces, through the same helper. Spec rows are written before the collections that bind them, in the same transaction.
  • A collection binds a spec through openapi.specTempId (a spec in this payload, resolved through the temp-id map exactly as collectionTempId is) or openapi.specId (one already stored). Sending both is a per-item 400, and so is either one that resolves to nothing. The resolved value is stored as openapi.specId; specTempId is never persisted. The binding's specHash and syncedAt are stamped by the engine from the document - the one this payload just wrote, or the stored one an openapi.specId names - so an imported collection is bound to a version and its runs are measured against the contract (issue #709). A specHash or syncedAt the item sends is dropped, never stored (issue #3348).
  • A clientCertificates item is a client_certificates registry candidate (issue #1656), in the same field shape POST /client-certificates takes (host, port, certPath, keyPath, certFormat, passphrase) - id is refused here too. Unlike every other section it carries no tempId (nothing else in the payload references a certificate) and is applied after the tree's own transaction commits rather than inside it: the engine reuses POST /client-certificates's own check-and-write, which takes its own lock, and taking it from inside the tree's transaction would deadlock. A candidate that fails that route's own checks (an unreadable file, a (host, port) pair another row already claims) is skipped rather than failing the call or naming an item error - the tree it does not reference has already committed by the time this section runs, and nothing in the response says which candidates landed. The engine registers every candidate it is sent: the app sends only the ones the user ticked in the preview, so an empty array registers nothing. Each registration is logged at info (http: host, port and certificate path, never the passphrase or the key), and a skipped candidate at warning. Only a Postman preview's own clientCertificates array (POST /import/parse) ever populates this; every other format sends [].
  • Up to 10,000 items per call (collections + requests + environments + specs + nested examples + clientCertificates - they are rows this call allocates and writes, so they count).

Response: 200

{ "idMap": { "c1": "col_<uuid>", "c2": "col_<uuid>", "r1": "req_<uuid>", "e1": "env_<uuid>", "s1": "spec_<uuid>" } }

Every tempId sent appears in idMap. Nested examples do not - they carry no tempId to map.

Atomicity: validation runs over the whole payload before anything is written, and the write itself is a single SQLite transaction. A 400 therefore means nothing was persisted - there is no partial tree to clean up.

Errors: every 400 uses the standard error object, and the per-item ones add an item key inside it (the offending tempId) so a large import can name what broke:

{ "error": { "code": "bad_request", "message": "Duplicate tempId 'c1'", "item": "c1" } }

Messages, by case: - 400 Invalid JSON: <parser message> - the body did not parse; request body is nested deeper than 128 levels when it nests past the bound. - 400 Body must be a JSON object. - 400 Invalid 'collections': must be an array - a section was present but not an array (same for requests / environments / specs). - 400 Invalid collection at index 2: 'tempId' must be a non-empty string. - 400 Invalid collection at index 0: 'id' is not accepted - the engine assigns ids; reference items by 'tempId'. - 400 Duplicate tempId 'c1', with item: "c1". - 400 Unknown parentTempId 'c9', with item: "c2", and the same for collectionTempId - including a collectionTempId that names an environment rather than a collection. - 400 Unknown openapi.specTempId 's9', with item: "c1", and 400 Spec 'spec_...' does not exist for an openapi.specId that resolves to no stored document. - 400 Cycle in parentTempId references at 'c1', with item: "c2" - a cycle (including a self-parent) in the payload's own parent graph. The stored-tree walk that guards POST /collections cannot see this one, because none of these rows exist yet, and a cycle makes cascade delete loop forever (issue #79). - 400 Missing required field: name, with item: "c1", and the other per-field errors of the matching POST /<resource>, including a wrong-typed field ("name": 42), which is a 400 rather than a 500. - 400 'specFile' is not part of an import: it binds a file on this machine, set with PUT /collections/:id, with item: "c1", and the same for dataFile (issue #2765); null passes. - 400 Import too large: 10001 items exceeds the limit of 10000 per call. - 500 <detail> - the transaction itself failed; nothing was written.

Export

POST /export/postman

A collection and everything beneath it as a Postman Collection v2.1.0 document, written the way Postman's own "Export > Collection v2.1" writes one (core/postman_export.hpp). It is the inverse of the Postman importer: a collection imported from a Postman export and exported again gives back the same document, _postman_id aside, and exporting, importing and exporting again is byte-identical. Each item[] lists a collection's sub-folders and requests in its one sibling order (#2535), so a request that sits before or between folders is written there, which is where Postman runs it; the Postman importer reads that order back.

Reads only. Nothing is stored. The whole subtree is exported, with no stop at a collection bound to another OpenAPI document.

Request:

{
  "collectionId": "col_9a1f...",   // Required, non-empty
  "includeSecrets": false          // Optional - default false
}

includeSecrets: false writes every credential as "": a bearer token, a basic or digest or NTLM password, an API-key value, an OAuth 2.0 client secret or password-grant password, an AWS key pair or session token, and the value of a variable marked secret. The auth modes kept as a config bag (AWS, digest, NTLM, Hawk, OAuth 1.0, EdgeGrid, JWT, OAuth 2.0's own config) are blanked by an allowlist of the members known to describe the auth, not by credential name, so a member no list has heard of (Insomnia's IAM secretAccessKey) leaves blank. OAuth 2.0's extra request parameter rows, in its config and in a kept Postman block alike, keep their keys; a row's value is blanked when its key names a credential (client_secret, client_assertion, password, Authorization, X-Api-Key, the other names a header or query parameter is blanked by). A credential outside an auth block is blanked too, by name, wherever the document writes a value as typed or as recorded:

  • a request header whose name is sensitive (Authorization, Proxy-Authorization, Cookie, Set-Cookie, X-Api-Key, X-Auth-Token, X-CSRF-Token, the other names the logger redacts) or is the header an API-key auth in force for the request names, enabled or not; the row and its name stay. The auth in force is the request's own, or the nearest folder's when it inherits;
  • a query parameter by the narrower name set of the Params table (the same names less the generic code and key, plus secret, signature, x-amz-signature and the like, plus an API-key auth's own parameter), in the Params rows and in the URL's raw query and fragment, and the password of the URL's user:pass@ (the user name stays);
  • on every saved example, the recorded request's headers and URL by the same rules, the response's header[] by the header names (a Set-Cookie row included, in full), and the value of every cookie[] entry whatever its name (the name, path, flags and expiry stay). An example written from the request's current state carries the request's own blanked rows.

A value that is exactly one {{variable}} reference names a secret without being one and is kept. Each blanked value is counted in secretsOmitted; a credential the document writes twice with one source - a query parameter in the URL and in the Params table, an example's originalRequest copied from the request - is counted once, while a Set-Cookie row and the cookie[] value it sets, or a recorded Authorization header and the auth beside it, are two written values and count twice. A body is never judged (a response example's body, a request body outside the form-data file rule) and cookie names are not either, so neither is blanked. true writes everything as stored, which is what Postman's own export does, and is byte for byte what it was before these rules.

Response:

{
  "text": "{\n\t\"info\": {\n\t\t\"_postman_id\": \"9a1f...\",\n ...",
  "fileName": "Pet Store.postman_collection.json",
  "notes": {
    "requestsExported": 12,
    "foldersExported": 3,
    "secretsOmitted": 2,
    "notCarried": [
      { "code": "vayu_elements", "count": 4,
        "message": "Assertions, extractors, timers, controllers, metrics and setup or teardown scripts have no Postman equivalent" }
    ]
  }
}

  • text is JSON.stringify(document, null, "\t"): tab-indented, no trailing newline, keys in the order Postman writes them. info.schema is https://schema.getpostman.com/json/collection/v2.1.0/collection.json; info._postman_id is the collection id when that is a UUID, the UUID an engine id ends in (col_<uuid>), or else a version-8 UUID derived from the id. No _exporter_id or _collection_link is written.
  • fileName is <collection name>.postman_collection.json, with every character a filesystem refuses (<>:"/\|?* and control characters) replaced by _.
  • foldersExported counts the folders beneath the collection, not the collection itself.
  • notCarried has one entry per kind of stored thing the format cannot carry, in a fixed code order, each with its count and a short phrase; an empty array means everything was carried.
Code Written when the collection holds
vayu_elements An element other than a pre-request or post-response script (assertion, extractor, timer, controller, metric, setup or teardown script)
script_settings A script with a name or the load-test inline setting
jsonrpc_bodies A JSON-RPC body, written as a raw JSON body holding the completed frame (jsonrpc and id added as on send)
unsupported_bodies A body in a mode Postman has no equivalent for, left out
unsupported_auth An auth mode Postman has no equivalent for, left out
oauth2_settings An OAuth 2.0 turned-off automatic token fetch or refresh, a token query parameter name, or an empty header prefix (an audience, resource and the extra request parameter lists are written as Postman's tokenRequestParams, authRequestParams and refreshRequestParams)
form_file_names A form-data file part whose file name differs from its path's own
body_file_details A binary body whose file states its own contentType, or a file name that differs from its path's own - Postman's file mode carries only src
http_version A request's HTTP version other than auto
event_stream A request consumed as an event stream
request_timeout A request with a timeout of its own (Postman has only an app-wide one)
mock_response_mode A mock response mode other than first
truncated_examples An example saved from a cut-off response, written with the partial body
example_content_types An example content type no Content-Type header row states
variable_types A variable typed json, or a secret typed number, boolean or json, whose one type slot holds secret (number and boolean are otherwise written as Postman's own types); each row counted once
data_contracts A collection or folder data-file contract
spec_bindings A collection or folder bound to an OpenAPI document
spec_operations A request stamped as an OpenAPI operation
rows_without_key A header, param or form row with a value but no name, left out
typed_auth_headers A request with an enabled header row named like the header its auth in force writes (Authorization for bearer, basic and an OAuth 2.0 token placed in the header; the key of an API key in a header), written with noauth - counted once per request

An auth a Postman import kept its original block for (auth.postman, see docs/engine/db-schema.md) is written as that block, while it still maps to the stored auth; everything below describes the rest.

A header the user typed under the name the auth in force writes wins in Vayu (apply_auth skips a name the request already carries, case-insensitively and whatever its value), while postman-runtime lets the auth overwrite the header. The request is therefore written with auth: {"type": "noauth"} (also over an imported auth.postman block) and counted as typed_auth_headers, so the header Postman sends is the one Vayu sends. Nothing is written for an auth that writes no header (a blank bearer token, an API key with no name or placed in the query, an OAuth 2.0 token placed in the query) or for a disabled row; a folder's or collection's auth is left as it is.

What maps where: folders are item groups (a folder's sub-folders and requests are written as one list in sibling order, a folder first on a tie); a request's inherit auth is an absent auth and its none is noauth, while a collection's or folder's none is an absent auth and its noauth is noauth; aws auth is awsv4; body modes json / text / xml are raw with that options.raw.language (or the language a Postman import kept as rawLanguage, none at all for "", while importing it again would still give its stored mode), graphql is graphql with the variables as the pane's text, x-www-form-urlencoded is urlencoded and form-data is formdata with a file part's src and any part's contentType, binary is file with file.src (file: {} when no file is chosen); url.query[] is every stored query row in stored order (a turned-off one disabled: true), then the pairs of the URL's own query that no enabled row states, in URL order, so a request stored with its query only in url before the write kept the rows in step (see POST /requests, issue #3551) keeps it - Postman and Newman read query[] over raw, and a row matches a pair by key and value (as the row is written into the URL), each row accounting for one pair so a repeated key is not doubled; script.pre / script.post are the prerequest / test events, one event per element in element order, a turned-off one written disabled: true (Postman's runtime skips it, as Vayu does); saved examples are response entries with an originalRequest (see below).

protocolProfileBehavior. A request imported with one (its postmanProtocolBehavior) is written as that object, member order, explicit defaults and keys Vayu does not apply included, with each key Vayu owns checked against the stored setting (issue #1765): strictSSL (verifySSL), followRedirects, maxRedirects, disableUrlEncoding and disableCookies keep the imported spelling while it reads as the stored value (absent or not the right type reading as the default) and are otherwise overwritten in place, or appended when absent; disabledSystemHeaders is kept while its names set to true are the stored set, and otherwise written as {name: true} in stored order; disableBodyPruning and every other key are the imported object's. Without one, the object is generated in the order strictSSL, followRedirects, maxRedirects, disableUrlEncoding, disableCookies, disabledSystemHeaders, disableBodyPruning, each only where it differs from Postman's default: strictSSL: false, followRedirects: false, a maxRedirects other than 10, true for either flag, the non-empty header list, and disableBodyPruning: true on a GET or HEAD that sends a body. A folder or collection is never given one: an import flattens a folder's protocolProfileBehavior onto the requests below it (#2538), so its applied settings come back on those requests and a key Vayu does not apply is lost.

Saved examples. An example imported from Postman carries the saved response it came from (request_examples.postman_response), and so does one saved in the app from a live response (savedFrom on POST /requests/:id/examples); either is written back from it in the source's member order: originalRequest (the request as it was recorded, not the request's current state), responseTime, _postman_previewtype and any other member as stored; name, code and body from the example's own fields. The status text is the stored one while status is still the code it was recorded with, header[] (its name fields and number values included) while headers still reads the same, cookie while the enabled Set-Cookie rows (name in any case, and value) still read as the recorded header[] has them (an edit to those rows rebuilds cookie from them, a Max-Age counted from the export, so a removed row's value is not exported; an unrelated header edit keeps it byte for byte), and the preview language and type while the declared Content-Type is unchanged; an edit to any of those regenerates the part it made stale. A member the source left out (code, status) stays out until an edit gives it a value. The recorded request's auth is written in v2.1's attribute-array shape (a v2.0 file states it as an object, which the v2.1 schema refuses), and with includeSecrets: false it is blanked like any other credential and counted in secretsOmitted, as are the credentials in the recorded request's headers and URL, the response's Set-Cookie and other sensitive header[] rows and the values in cookie[]. An example with no stored response (saved in Vayu before #1763 or from a response restored from a stored run, or imported from OpenAPI) gets originalRequest from the request's current state, the status text from the engine's reason-phrase table and _postman_previewlanguage from its Content-Type (Text when it states none), with cookie: [].

Errors: - 400 Invalid body: must be an object. - 400 Invalid 'collectionId': must be a non-empty string. - 400 Invalid 'includeSecrets': must be true or false. - 404 Collection not found.

POST /export/postman-environment

One environment as a Postman environment export (core/postman_export.hpp), the inverse of the Postman environment importer: importing the document gives back the same variable names, values, enabled flags, secret flags and types, apart from json (below). Reads only.

Request:

{
  "environmentId": "env_9a1f...",  // Required, non-empty
  "includeSecrets": false          // Optional - default false
}

includeSecrets: false writes the string value of every variable marked secret as "", counted in secretsOmitted; the row stays, still typed secret, so the name is visible for the person importing it to fill in. A secret whose value is exactly one {{variable}} reference names a secret without being one and is kept, uncounted. true writes every value as stored.

Response:

{
  "text": "{\n\t\"id\": \"env_9a1f...\",\n\t\"name\": \"Production\",\n ...",
  "fileName": "Production.postman_environment.json",
  "notes": {
    "variablesExported": 6,
    "secretsOmitted": 1,
    "notCarried": [
      { "code": "variable_types", "count": 2,
        "message": "JSON variable types have no Postman equivalent, and typed secrets were written as secret" }
    ]
  }
}

  • text is JSON.stringify(document, null, "\t"): tab-indented, no trailing newline. The document is {id, name, values, _postman_variable_scope: "environment"}: id is the environment's id, values holds one {key, value, type, enabled} row per variable in the stored order, and no export timestamp is written. A row has no description.
  • A row's value is the stored value as the text a send uses (#3245): a string verbatim, a number or boolean as its JSON text (5 is "5", true is "true"), an object or array as compact JSON ({"a":1}), an absent or null value "". Its type is secret for a secret variable, else the stored string, number or boolean, else default, Postman's unset marker. enabled is the stored flag, true when absent.
  • fileName is <environment name>.postman_environment.json, with every character a filesystem refuses replaced by _ (environment when nothing is left of the name).
  • variablesExported counts the rows written. A stored variables column that does not parse as an object exports as no variables.
  • notCarried holds one variable_types entry for the types a row could not carry: a variable typed json, which Postman has no type for, is written as default, and a secret typed number, boolean or json is written as secret, Postman's row having one type slot (#3252). The entry's count is how many rows, each counted once. No entry means every type was carried. A stored createdAt is not written; Postman's row has no place for it.

Errors: - 400 Invalid body: must be an object. - 400 Invalid 'environmentId': must be a non-empty string. - 400 Invalid 'includeSecrets': must be true or false. - 404 Environment not found.

POST /export/run-report

A finished load run as a document to share (issue #2127): its report, the configuration it ran with and its time series, with everything that could carry a credential or a payload left out (core/run_export.hpp). The document's schema is run-export.schema.json, JSON Schema draft-07 with additionalProperties: false at every level. Reads only.

Request:

{
  "runId": "run_5a7c...",      // Required, non-empty
  "format": "json",            // Optional - "json" (default), "markdown", "html"
  "series": "full",            // Optional - "full" (default) or "none"
  "baseRunId": "run_e8f0..."   // Optional - a second finished load run
}

json, markdown and html are written. The formats are one table (RUN_EXPORT_FORMATS), so each adds a row and its renderer, and a row to engine/tests/fixtures/run-export-formats.json, which the app's format registry and the MCP server's list are held to. Every format renders the same document, so what the rules below leave out is left out of all of them. series: "none" leaves timeSeries out; full reads every tick of GET /runs/:runId/metrics, paged at its 50000-tick maximum to the end. html draws the series, so it reads every tick whatever series says. baseRunId is checked like runId (below) and fills the document's comparison; without it comparison is null.

Response:

{
  "text": "{\n  \"schema\": \"vayu.run-report\",\n  \"schemaVersion\": 1, ...",
  "fileName": "Create order 2026-10-05 0810.run.json",
  "mimeType": "application/json",
  "notes": { "urlCredentialsOmitted": 1 }
}

  • text is the document: for json two-space indented with invalid UTF-8 replaced, for markdown the report below, for html the page below.
  • mimeType is application/json, text/markdown for markdown or text/html for html.
  • fileName is <title> <UTC start, YYYY-MM-DD HHmm>.run.json (.run.md for markdown, .run.html for html), with every character a filesystem refuses replaced by _ (the rule POST /export/postman uses; run when nothing is left). The title is the one the run's reference line uses (below).
  • notes.urlCredentialsOmitted counts the values the URL rule below dropped.

What the document carries is an allowlist. Every member is copied from the report or the run's stored snapshot by name, so a field the report gains later is absent here until it is added on purpose:

  1. No results[], no trace (trace, rawRequest, sentHeaders), no captured sample, anywhere. A trace records what was sent, credentials included, and a sample holds response headers and bodies verbatim.
  2. config holds the method; the url after redact_url_credentials (core/vayu_extensions.hpp: a user:pass@ password dropped and the user name kept, a credential-named query or fragment value emptied, a lone {{variable}} kept); headerNames and paramNames, names only, whether enabled or not; body as {mode, bytes}, bytes the size of the body text as stored and null for a body that is not text; auth as {mode}; and the report's metadata.configuration tuning object. Never a header or parameter value, never the body.
  3. Text the engine copied from a script or a response is carried as counts only: schemaValidation keeps failuresTotal and drops failures[], a lifecycle outcome drops its message, messages, console and their dropped counts, an element row (a step's or the run's elements) drops messages, console and their dropped counts (#3127), and the report's auth section (whose lastError is a token endpoint's words) is left out.
  4. Text the user wrote (the request name, the run comment, the data file's display name, step, transaction, metric and series names) is carried as written.
  5. Within a section a value is copied only when it is a scalar or a list of scalars; anything deeper is named member by member.

The document ("schema": "vayu.run-report", "schemaVersion": 1; a breaking change bumps the integer and is noted here):

Member Holds
generatedAt, engineVersion Epoch milliseconds of the export; the engine's version
run id, reference, type (load), status, startTime, endTime, name (the request name, or null), comment (or null), baseline
verdict {state, stoppedEarly, reason}, derived below
config As in rule 2
report summary, latency, statusCodes, errors, and when the run has them rateControl, timingBreakdown, stream, slowRequests, sampling, warnings, scenario (step and transaction aggregates, and a scenario load run's exact assertions), monitor, testValidation, capacity, coverage, schemaValidation (counts), lifecycle (outcomes), elements, thresholdValidation, assertions (the run's assertion block, #3537), customMetrics - each as GET /runs/:runId/report documents it, less what the rules above leave out
timeSeries One entry per tick: elapsed_seconds, requests_completed, requests_failed, current_rps, current_concurrency, throughput, error_rate, status_codes, status_seconds, latency_p50_ms, latency_p95_ms, latency_p99_ms (the tick's own second, as stored: the three percentiles are absent from a second with no completion, issue #2386, and the HTML charts skip that point rather than drawing 0 ms; status_seconds is as stored with any entry that is not {second >= 0, span >= 1, counts} of five counts >= 0 dropped, an empty list kept, and the key absent from a tick stored before issue #2866); absent for series: "none"
comparison null without baseRunId; otherwise {baseRunId, baseReference, differences, deltas, statusCodes}, below
notCarried [{code, message}], one entry per kind of thing this run held that the document left out, in the order traces_and_samples, request_values, message_text, credential_refreshes

statusCodes, errors.byStatusCode and a tick's status_codes are objects, code to count, in the document: the report itself writes the first two as [[code, count], ...] pairs.

run.reference is the Copy for agent run line (MCP: Naming what the user means) with the start in ISO-8601 UTC, because a file is read away from the locale and zone the app would print it in: Vayu run "Create order" (run_5a7c...) - load test, POST /v1/orders, 2026-10-05T08:10:00Z, completed. The title is the request name unless it is the default New Request, else the collection a collection load run ran, else the method and path; the URL is cut to its path.

verdict reads the report fields the app's run verdict reads (judgeRun in app/src/components/shared/run-outcome.ts): status, summary.totalRequests and summary.errorRate, summary.drainCut, thresholdValidation, and the report's top-level assertions block, for a single-request run and a scenario load run alike (#3537). A failed check is a failed assertion of either population (exact.failed or sampled.failed), an errored element execution (errored) or a failed teardown (teardownFailed); like an errored request, it keeps met budgets from reading passed without failing a run that declared no budget for it. The first matching row wins:

status and budgets state reason
stopped not_judged stopped
failed, no budget missed failed run_failed
A declared budget missed (thresholdValidation.failed > 0) failed budgets_missed
A Stop cut the run's own drain (summary.drainCut.cancelled > 0; #3538) not_judged drain_stopped
No budget declared not_judged no_budgets
Every budget met, some requests errored (summary.errorRate > 0) not_judged budgets_met_with_errors
Every budget met, an assertion failed (assertions.exact.failed or assertions.sampled.failed > 0; #2820, #3458) not_judged budgets_met_with_assertion_failures
Every budget met, an element execution errored (assertions.errored > 0) not_judged budgets_met_with_element_errors
Every budget met, a teardown failed (assertions.teardownFailed > 0) not_judged budgets_met_with_teardown_failures
Every budget met, none of the above passed budgets_met

reason names the first failed check; the Markdown and HTML line names every one (below). A cut drain removed the run's slowest requests from every figure, so what is left is not judged however well it did: its line is 15 requests were still unanswered when the drain was stopped, and a budget the answered requests already missed still fails the run. A report with no assertions block (a run that asserted nothing and errored nowhere, or one stored before the block whose old fields derive none) has no failed check. engine/tests/fixtures/run-verdict-conformance.json pins this table to the app's: the engine's suite replays it through the export and the app's through reportOutcome.

stoppedEarly is status == "stopped".

A summary that is not a whole-run measurement (issues #2895, #2905). report.summary carries two optional booleans, each present only when true (the GET /runs/:runId/report flags of the same name): partial for a run the engine died under and reconciled at the next start, whose counts are its last saved tick's, and summaryMissing for a failed load run that stored no summary, whose counts are not whole-run totals. In both, report.latency is absent (the schema no longer requires it, #2938): a crashed run flushed no rows to take a percentile from, and the sampled rows of a failed run with no summary are not the run's latency. The Markdown and HTML latency table then reads - in every row. The verdict is not changed by either; the Markdown and HTML reports word it (below).

comparison diffs the run (the target) against baseRunId the way the app's vs-baseline strip and the MCP compare_runs tool do (compareReports): the engine's copy is core/run_compare.hpp, and engine/tests/fixtures/run-compare-conformance.json pins all three to the same answers. Its members:

  • baseRunId, and baseReference, the base run's line written as run.reference is.
  • differences[]: {field, base, target} for every way the two runs were not the same experiment, in the order run_type (Send, Load test or Collection run; the export takes load runs only, so it does not arise here today), mode, concurrency (virtual users; for a ramp the start level and ramp time too), target_rps, duration (only past a 2x ratio; an unfinished run's status is appended, "3 s, stopped"), status, http_version (auto differs from nothing), data_file (name and the first 8 characters of its hash, then , numbers read as numbers when dataFileCastNumbers is set; none against one is a difference, and so is one file read both ways, #2540, since the hash is of the bytes), request (method and URL with the query, fragment and userinfo cut), compression and expect_continue (#2516; allowed against not allowed, an absent key reading as not allowed). The two values are strings formatted as the app shows them. Every report the export reads carries metadata.runType, so a mode, concurrency or target_rps only one run recorded is listed, its missing side not recorded (the shared rule leaves such a field unknown when either report lacks runType); any other field only one report carries is unknown and not listed. Read these before the deltas: a short stopped run against a long one always looks like a regression.
  • deltas[]: {metric, base, target, delta, pctChange, direction}, one per metric in this order:
metric direction
latency.p50, latency.p90, latency.p95, latency.p99, latency.avg, latency.max lower-is-better
summary.avgRps, summary.throughput higher-is-better
summary.errorRate lower-is-better
summary.totalRequests neutral - it moves with how long a run was told to run

delta is target - base and pctChange is delta / base * 100. A value a report lacks is null, and so is every figure computed from it; pctChange is null against a zero base. So is a figure the report says the engine did not record (#2904), judged per run: summary.summaryMissing (a failed run with no summary) nulls that run's summary.* metrics and its latency, and summary.partial (reconciled after a crash) nulls its latency alone, so the other run's value stands and the delta is null. The base's own headline numbers are the entries' base values. - statusCodes: {code: {base, target}} over every code either run saw, a code one run never saw counting 0.

The Markdown report

format: "markdown" renders the document above as plain GitHub-flavoured Markdown, to paste into a pull request or an issue, or to save as <title> <UTC start>.run.md (core/run_export_markdown.hpp). It is a pure function of the document: it reads no database and no report, so it can say nothing the document does not. No raw HTML and no images. Its size does not grow with the run: the time series is never read, and a table fed by an open set (status codes, error types, warnings) shows ten rows and folds the rest into one Other (<n> codes) row, so a 2-hour run that saw 300 status codes is still under 6 KB. The tables a plan or a spec feeds (steps, transactions and the contract's operations) show twenty rows in document order, the order of the plan and never sorted by count, and fold the rest into one and <n> more steps row.

The sections, in order:

  1. # <title>, then the run's reference line in a code span (the same line run.reference holds).
  2. The verdict, from the document's verdict and never recomputed: **Passed** - 3 of 3 budgets met, **Failed** - p95 <= 30 ms missed (41 ms) (every missed budget, or not evaluated for one the run could not measure), **Not judged** - no budgets declared. Met budgets that did not pass, and no budgets, name every failed check of report.assertions in this order, after the error rate when requests errored: 150 assertions failed, 4 assertions failed in the sampled replay or 150 assertions failed, 4 more in the sampled replay; 3 elements errored; 1 teardown script failed (**Not judged** - 3 of 3 budgets met, but 0.4% of requests errored, 68 assertions failed, **Not judged** - no budgets declared; 91 assertions failed in the sampled replay, #3537). A cut drain is its count alone: **Not judged** - 15 requests were still unanswered when the drain was stopped (1 request was, #3538). For a stopped run a line Stopped early at 3 s of 20 s follows, and for a run with summary.partial or summary.summaryMissing one sentence each follows that, saying the totals are the last saved tick's or not whole-run totals, and that latency was not recorded (the latency table then reads - in every row, #2938).
  3. ## Run: target (<METHOD> <url>, or Collection run, 3 steps per iteration - the step count is report.scenario.steps, left off when the document holds no per-step stats), mode, virtual users, duration, start (ISO-8601 UTC), engine version and the comment. A capacity run reads its configuration as a search: Search from 1 up to 128 virtual users (the first level and the ceiling), Deadline 300 s, ran 62.4 s (the configured deadline, then summary.testDuration, because the search ends when it finds its limit) and a Step row with configuration.stepDuration as it was sent (5s, or a number of seconds).
  4. ## Results: requests, a Skipped requests row only when summary.skippedRequests is above 0 (625 requests skipped: the load generator stalled for 2.5 s, from skippedRequests and stalledMs, issue #2911; absent or 0 prints no row), requests per second (avgRps, labelled as the whole run with the drain included), responses per second while sending (completedWhileSending / sendingDurationSeconds, issue #2882, only when the report has both), error rate with its split into HTTP errors and no response, bytes in and out, and the throughput and error-rate budgets that judged them. The error rate is the report's, never derived from the counts.
  5. ## Latency: min, p50, p90, p95, p99, p999 and max, with the budget that judged each (<= 30 ms - missed). A scenario run's table opens with the line *All steps pooled.*: it is one histogram over every step, and the per-step figures are the Sequence table's. A streaming run's table opens with *Each stream's full duration.* (after that line, for a run that is both).
  6. ## Stream, only for a run whose document has report.stream, which a streaming run carries and every other run lacks (#3240). A line saying what the Latency table above is (The Latency table above is each stream's full duration, not the time to its first event.: a stream's latency is its whole transfer, so it grows with the events the server sends), then a table of Streams (completions), Events (totalEvents), Events per second (eventsPerSecond, in events/s) and Streams ended at a cap (capped), then a table with a p50, p95, p99 and max row of the events each stream delivered (events, whole counts) and, as a Time to first event (ms) column, of the time to each stream's first event (timeToFirstEvent). That column is left off when the document has no timeToFirstEvent, which the engine omits when no stream delivered a timed event, so a zero never stands for a figure that was not measured. A figure the document lacks reads -.
  7. ## Capacity, only for a run whose document has report.capacity: the stop reason in bold and what the search found (`Latency budget exceeded
  8. Sustained 41 virtual users at 403 req/s, with a p99 of 178 ms against a 200 ms budget.), then where the limit sits (The limit lies between 41 and 51 virtual users: it held 41 and gave out at 51, where p99 reached 226 ms.), why it stopped in the document's own figures (p99 stayed above the budget across two consecutive measurements of the level (each 5s long).), the budget, error limit and step length the search ran under, and a table of the levels it judged: virtual users, throughput, p99, plusErrors (%)andSamplesonly when some level carries them (a run stored before the engine reported them has neither). A level the search measured twice reads51 (re-measured), and a p99 or error share past its limit says(over budget)or(over limit)in words. The sentences are the app's Capacity summary's (components/shared/CapacitySummary.tsx, with the stop reasons' labels and detail lines incomponents/shared/capacityStop.ts): the stop-reason table inrun_export_view.cppandcapacityStop.tsword the same stops, so a change to one is a change to both. A reason neither table knows (a newer engine's) prints under its raw key with no detail line. What the search found depends on why it stopped: a measured capacity when the target gave out (slo_exceeded,errors_exceeded),At least N virtual users held the budgetwhen it ran out of ceiling, time or patience (cap_reached,deadline,stopped), the saturation level when throughput plateaued, andThe search ended before it finished measuring a single levelwhenlevelsis empty. A latency here is spelled178 msas the rest of this report spells it, not178ms` as the app does.
  9. ## Contract, only when the document has report.coverage or report.schemaValidation, which a run of a collection bound to an OpenAPI document carries and every other run lacks (#3036). Up to three lines, each present when its section is: Coverage: 3 of 5 operations covered; declared-response coverage 80.0% (8 of 10). (the percentage is the document's declaredResponseCoveragePct, never recomputed from the counts); Schema validation (sampled): 100 responses sampled, 90 checked (87 valid, 3 failed), 10 unchecked., which says sampled unless the section has exact: true (a collection run, which checked every step: Schema validation (every step checked): 100 responses, ...), because a load run's check walks a reservoir; and Unchecked: body is not JSON or nests too deeply (6), no schema for the status (4)., the three commonest uncheckedReasons with the rest counted (and 2 more reasons), worded as the app's response-viewer/validation-reasons.ts words them, shorter, and a code it does not know under its raw key. A table follows with a row per coverage.operations[] entry in document order (method and path, operation id, requests sent, declared responses hit and missed), folded past twenty rows into and <n> more operations. The path and operation id are the spec author's text, escaped as every name is.
  10. ## Sequence, only for a scenario run whose document counts iterations or lists steps: one line (2,110 iterations started, 2,090 completed, 15 abandoned, 5 cut short - abandoned and cut short only when above zero, cut short being started less completed less abandoned, as the app derives it), then a table with a row per step in plan order: executed, errors, Assertions (2,080 passed, 18 failed, summed from the step's assert.* and script.* element tallies, an error counted as failed, with each miss of a required extractor added to the failed count because it failed the step; deferred to a post-run replay for a script the engine only replays afterwards; - for a step that asserts nothing) and its p50, p95 and p99. Step names are free text and escaped as every name is.
  11. ## Transactions, only when the run declared any: name, count, errors and p50, p95 and p99 per report.scenario.transactions[] entry.
  12. ## Errors, only when there were any: by status code (HTTP 503), then by transport error type. A request that got no response is listed once, under its error type: status code 0 counts the same requests, so no row reads HTTP 0 (issue #2400). A No response row (the app's words) appears only when the error types sum to less than code 0, which is a run stored before the per-type counts, whose types stop at the error store's cap; its count is the remainder (code 0 minus the types' sum), so the requests no type names are not lost and none is listed twice. With no error types at all it holds the whole of code 0. The HTML report reads the same table.
  13. ## Compared with <base reference>, only when the document has a comparison: each metric's base, this run, change and a word from the delta's own direction (improved, regressed, unchanged for a change of exactly zero, - for a neutral metric that moved, such as the request count, which is neither better nor worse, or not compared for a figure one run lacks), then one line per comparison.differences[] entry.
  14. ## Warnings from report.warnings, and the footer Generated by Vayu <version>. No request or response data is included. A warning's names are appended as : a, b, c (the first five, then and N more) unless its message already ends with : and every name joined by ,, which is how the engine writes an unresolved-variable warning, so each name appears once.

Every table is padded to its widest cell so it reads as a table before it is rendered. All free text (the title, URL, comment, error types, warning text) goes through one escape_markdown_cell: line breaks and control characters become a space, and \, `, |, <, >, [, ], *, ~, an & that would write an entity, an _ that is not inside a word and a leading block marker (#, -, +, 1.) are backslash-escaped, so a request named a | b <script> cannot split a table or start a tag. Numbers are spelled the same on every host, whatever its locale: , groups thousands and . marks decimals. A latency or rate has two decimals below 10 (trailing zeros dropped) and none from 10, <0.01 for a positive value that would round to 0; a percentage has one decimal and <0.1 likewise. The tiers are pinned by engine/tests/fixtures/run-export-number-tiers.json.

engine/tests/fixtures/run-export/<case>.document.json and <case>.golden.md hold the renderer to its exact bytes for each shape of run (run_export_markdown_test.cpp); a deliberate change to the output is regenerated with VAYU_UPDATE_GOLDEN=1, never edited by hand.

The HTML report

format: "html" renders the same document as one self-contained page, to open in a browser, attach to a ticket or print: <title> <UTC start>.run.html (core/run_export_html.hpp). Like the Markdown report it is a pure function of the document, so it can say nothing the document does not.

It holds the Markdown report's sections in the same order (title and reference line, verdict, run, results, latency with its budgets, a streaming run's events, a capacity search's result, the contract's coverage and schema checks, a scenario's sequence and transactions, errors, comparison, warnings), written as semantic HTML - one h1, tables with th scope, a description list for the run - from the same reading of the document, so the two cannot word a verdict or a capacity result differently. Stream (#3240), Capacity, Sequence and Transactions (#2819) are sections of paragraphs and tables like the rest, each present only when the document has it: the Stream section is the Latency note above its totals and distribution tables, the capacity sentences are paragraphs above the levels table, the iteration line is the paragraph above the steps table, the Contract section (#3036) writes its coverage, validation and unchecked-reason lines as paragraphs above its operations table, and a level or assertion count past its limit carries the same word beside its colour ((over budget), 18 failed). A table's one-line caption (a scenario run's latency table, All steps pooled.) is its <caption>; the partial and missing-summary sentences sit in the verdict's band, one paragraph each. Above the title sits a one-line brand (the Vayu mark at 28 px, then the wordmark Vayu run report, muted; the mark has an empty alt because the wordmark names the product). The mark is shared/icon_png/vayu_icon_64x64.png, embedded as a base64 data: URI (run_export_html_logo.hpp) because it exists only as a raster; the test suite compares the embedded bytes with that file. Then come three charts drawn from timeSeries, then the footer, which names the engine version:

  1. Throughput (req/s) and virtual users, two stacked panels sharing the x-axis.
  2. Latency p50, p95 and p99 in ms, with the p95 budget as a labelled dashed line when the run declared one. The axis stretches to reach the budget, so a generous budget is drawn however far above the data it lies.
  3. Responses by class: 2xx/3xx, 4xx, 5xx and No response (status code 0). A class that saw no response is not drawn and has no label. The chart reads the series one of two ways, chosen once for the whole timeSeries:
  4. When any tick carries status_seconds (issue #2888, runs stored after #2866), it is responses per second: one point per entry at counts[i] / span, at the end of the entry's span (second + span), the entries kept once per second (the last wins) and in second order, with 3xx counted into 2xx/3xx. The ticks' own timing moves nothing, and a tick without the key adds no point. A series whose every status_seconds is empty draws no status chart.
  5. Otherwise (a run stored before #2866) it is responses per tick: a tick carries cumulative counts, so each class is drawn as what it gained since the previous tick, a count that moved backwards adding nothing.

Every y-axis starts at 0 and names its unit, the x-axis is seconds from the start of the run, and each line is labelled where it ends instead of in a legend; the percentile lines differ in lightness, not hue, since red and amber mean failure here. Each chart has an accessible name and a <desc> giving every series' minimum, maximum and the time of its peak, read from every tick. A line is drawn from at most 480 points: a longer series is cut into 240 stretches and each keeps its lowest and highest value, so a one-tick spike survives, and the file stays under 300 KB for a run of any length.

The page loads nothing and runs nothing. There is no script, no <link>, frame or font and no url(...); the one image is the brand mark above, an inline data:image/png URI, so it is the only src attribute and it cannot fetch anything. A Content-Security-Policy meta tag (default-src 'none'; style-src 'unsafe-inline'; img-src data:) enforces that: no request leaves the page. The only href values are # anchors to the page's own sections: the target URL is text, never a link. The charts are inline <svg>, which is why hovering a line shows its summary natively. Every string written into the page (name, comment, URL, error keys, warning text, data file name) goes through one escape_html, in text and attribute position alike.

The page follows the reader's colour scheme (color-scheme: light dark, the palette switched by prefers-color-scheme, no toggle) and prints light on A4 (@page margin 14 mm, sections and charts kept whole, the verdict band printed in colour). Pass and fail are always a word beside the colour (Passed, Failed, Not judged, met, missed); the palette holds 4.5:1 for text and 3:1 for graphics in both schemes (run_export_html_test.cpp measures it).

engine/tests/fixtures/run-export/<case>.golden.html pins the bytes for nine shapes of run, among them a capacity search, a scenario run and two streaming runs, regenerated like the Markdown goldens.

Errors:

Status error.code When
400 bad_request The body is not an object; runId missing or empty; format not one of the table's names; series not full or none; baseRunId not a non-empty string, or equal to runId
400 unsupported_run_type The run or the base is a design or collection-sequence run
404 not_found The run or the base does not exist
409 run_in_progress The run or the base is pending or running: its numbers are not a result yet. A stopped run is a result

Environments

GET /environments

List every environment, except those in the trash (#2970).

Response:

[
  {
    "id": "env_1234567890",
    "name": "Production",
    "variables": {
      "baseUrl": {
        "value": "https://api.example.com",
        "enabled": true,
        "secret": false
      }
    },
    "updatedAt": 1234567890
  }
]

POST /environments

Create an environment. Create only - see Resource writes for the shared contract and the null-vs-absent rule.

Request:

{
  "name": "Production",    // Required, no default (null is a 400)
  "description": "",        // Optional
  "isActive": false,        // Optional; true deactivates every other environment
  "variables": {            // Optional, null resets to {}
    "baseUrl": {
      "value": "https://api.example.com",
      "enabled": true,
      "secret": false
    }
  }
}

Response: The created environment object, carrying the engine-generated id.

Errors: 400 if the body carries an id (the engine owns it), if name is missing or null, if name is empty or whitespace-only (#3253), or if a variables key is blank or padded (#3251); 413 naming the field, its size and the cap, when a serialized variables is over the engine's field cap.

A storage failure answers 507, 503 or 500, never 400 - see A storage failure is not a 400.

PUT /environments/:id

Update an existing environment. Update only - a 404 when the id does not exist, never a silent create. Merge-patch body, same rule as collections.

variables replaces the whole map, so a caller doing a partial edit reads the current map first and sends the merged result under the version it read, If-Match: W/"<updatedAt>" (this is what the MCP update_environment tool does; see Conditional updates). Sending variables: null resets it to {} - it no longer stores the literal string null, which is the bug this verb split fixed. isActive is honored here too; it used to be read only on create.

Writing isActive: true is how a client switches the active environment, and one request does the whole switch: the engine deactivates whichever environment held the flag in the same transaction, so at most one row is ever active and a client sends no companion write to clear the old one. Clearing entirely is isActive: false on the environment that holds it. The engine still never applies the active environment to a request - every execution names its own environmentId - but because the choice is stored rather than kept client-side, it survives a restart and is shared by every client on the same database. See db-schema.md.

Request:

{
  "name": "Production",    // Optional; null is a 400 (no default)
  "variables": {},          // Optional, null resets to {}
  "isActive": true          // Optional, null resets to false; true is the switch
}

Headers: If-Match (optional), see Conditional updates.

Response: The updated environment object, with its ETag.

Errors: 404 if the environment does not exist; 412 if If-Match no longer names the stored row; 400 on a null or empty or whitespace-only name (#3253), a malformed If-Match or a blank or padded variables key (#3251); 413 naming the field, its size and the cap, when a serialized variables is over the engine's field cap.

A storage failure answers 507, 503 or 500, never 400 - see A storage failure is not a 400.

DELETE /environments/:id

Delete an environment. The delete is soft (#2970): the row is stamped deleted_at, its isActive is cleared in the same write, and GET /trash lists it until a purge. From then on every route here treats the id as missing - GET /environments leaves it out, PUT and a second DELETE are a 404, POST /export/postman-environment is a 404, and an environmentId naming it composes and sends as an id naming nothing: an empty scope, so its {{names}} stay unresolved.

Restore it with POST /trash/:id/restore, which brings it back inactive; destroy it for good with DELETE /trash/:id, which is also what the startup sweep does once trashRetentionDays has passed. Its cookie jar is kept while it is in the trash, out of GET /cookies, so a restore brings its session back; a purge drops it.

Response:

{
  "success": true
}

Errors: 404 if no live environment has that id, a trashed one included. A storage failure answers 507, 503 or 500 - see A storage failure is not a 400.

Global Variables

GET /globals

Get global variables (singleton). An engine that never saved any answers the empty set at updatedAt: 0. The row is created by the first POST /globals, the first import carrying globals, or the first script or extractor write to a global (pm.globals.set, an extract.* element with scope: globals): a POST /execute or collection run on a workspace with no globals stores what its scripts set rather than discarding it.

Response:

{
  "id": "globals",
  "variables": {
    "apiKey": {
      "value": "xxx",
      "enabled": true,
      "secret": false
    }
  },
  "updatedAt": 1234567890
}

The answer carries the row's ETag, W/"<updatedAt>" (W/"0" for the never-written row), which a later POST /globals may name in If-Match.

POST /globals

Set global variables.

Request:

{
  "variables": {
    "apiKey": {
      "value": "xxx",
      "enabled": true,
      "secret": false
    }
  }
}

Headers: If-Match (optional), see Conditional updates.

Response: The saved globals object, with its ETag.

Errors: 412 if If-Match no longer names the stored row (the stored updatedAt rides inside the error); 400 on a malformed If-Match, a non-object variables or a blank or padded variables key (#3251). None writes anything.

Globals is a singleton, so there is no create/update pair: a POST replaces the whole set rather than merging into it. Every write is therefore a create as far as the null-vs-absent rule goes - variables absent and variables: null both mean the default, {}. A caller that keeps the globals it did not name reads first, merges, and saves under the version it read with If-Match: W/"<updatedAt>" (this is what the MCP update_globals tool does). The engine judges the tag in the same lock acquisition as the write, so a save that landed after the caller's read turns its write into a 412 rather than a silent loss.

variables: null used to store the literal four-character text null, which parses as JSON but is not an object. GET /globals returns {} for anything it cannot read as an object, so the failure showed up as globals silently disappearing rather than as an error. A non-object variables (42, a string, an array) had the same effect and is now a 400 - see Accepted field shapes.

Change feed

POST /changes/subscriptions

Issues the id one GET /changes stream opens with.

{ "subscription": "k3Zq...43 base64url characters" }

The id is 32 random bytes from libsodium, single-use: the first GET /changes that presents it spends it, whether that stream is then refused for a full feed or served, and a second GET with it is a 403. A client asks for a new one before every connection, a reconnect included. At most 64 issued ids wait unspent (change_feed::MAX_PENDING_SUBSCRIPTIONS); asking for more drops the oldest. This is a POST so a web page cannot send it: a page's request carries an Origin, which the gate refuses, so a page can neither learn an id nor open a stream.

GET /changes

GET /changes?subscription=<id>: Server-Sent Events, one change event per committed write of a collection, a request, an example, an environment, the globals or a trash entry, whoever made it: the app, the MCP server (in-app or stdio), vayu-cli or a script against this API (#3420). A client that caches those rows subscribes once and refetches what an event names, instead of polling or trusting a cache forever.

event: ready
id: 1789000000000000
data: {"lastEventId":1789000000000000}

event: change
id: 1789000000000001
data: {"kind":"request","id":"req_1","op":"update","collectionId":"col_1"}

event: change
id: 1789000000000002
data: {"kind":"example","id":"exa_1","op":"delete","requestId":"req_1"}

data of a change:

Field Meaning
kind collection, request, example, environment, globals, or clientCertificate, the last only for what changes the trash (its delete, restore and purge; a certificate's create and update are not on the feed)
id The row's id; globals for the globals singleton
op create, update, delete (gone from every live read: moved to the trash, or an imported example kept as a tombstone), restore (back from the trash) or purge (destroyed for good: from the trash, by retention, or a spec sync's hard delete of a live request)
collectionId The collection the row sits in: a request's collection, a sub-folder's parent. Absent for a root collection and every other kind
requestId An example's request. Absent for every other kind

What one write publishes. One event per row the write committed, after its transaction commits, so a write that rolled back publishes nothing. A bulk write (POST /import/apply, POST /reorder, POST /specs/sync, POST /specs/bind) publishes one per row it wrote, in write order and with consecutive ids; a row a sync names for deletion that is already gone publishes nothing. A cascade is one event on the row the caller named: deleting, restoring or purging a collection publishes one collection event for it, and the sub-folders, requests and examples that went or came with it (a purge's re-parenting of a live sub-folder included) ride on it, so a client refetches the tree. A save that makes an environment active publishes for that environment only; the ones it deactivated are read off the same list. A trash restore or purge names the entry's own kind. A delete that finds nothing live publishes nothing.

Ids. id: increases by one per event. The first id of a process is its start time in microseconds plus one, so an id kept from an earlier engine process is below every id this one issues, and its resume is a reset rather than a replay of the wrong process's events. An id stays below 2^53, exact as a JavaScript number.

Every stream opens with one ready or reset, whose id: and lastEventId say where the stream stands: ready at the newest id on a fresh subscription, so an EventSource that drops before its first change still resumes from it; ready at the resume point on a resume the feed still covers, followed by every change after it; reset otherwise. Subscribe before the first read of the data the feed describes, so no write falls between the two.

Resume with Last-Event-ID (what EventSource sends on its own retry) or ?lastEventId=<id> (for a client reconnecting by hand); the header wins when both are given. A value that is not a non-negative integer is a 400 with code invalid_last_event_id, the inbox stream's rule.

reset: refetch everything. The engine keeps the last 1024 events (change_feed::MAX_RETAINED_EVENTS). A resume from an id older than that, or from one this process never issued, opens with event: reset, and a connected reader that falls a whole ring behind between two polls (an import larger than the ring) is sent one mid-stream. The stream then continues from the reset's id. Treat it as "every cached row may be stale".

A stream needs a subscription. subscription is the id POST /changes/subscriptions issued. Without it the answer is a 400 with code subscription_required; an id that was never issued, was dropped or is already spent is a 403 with code unknown_subscription. Neither holds a reader slot. A scriptless GET is all a web page can send without an Origin, so a page can neither read the feed nor fill its slots to lock the app out.

Several readers, a bounded number. There is no single-reader claim: every stream reads the same feed. Each one parks a pool thread, so at most 8 are open at once (change_feed::MAX_READERS); another is a 503 with code change_feed_full and Retry-After: 15, the keep-alive interval within which a closed stream's slot is noticed and freed. The id of a refused stream is spent: ask for another.

A stream writes : keep-alive after 15 quiet seconds and ends when the client goes or the engine stops. It reads only; opening one changes nothing.

Cookies

The engine keeps a cookie jar for design-mode requests (POST /execute and the pm.sendRequest calls inside it), so a session set by one request is sent on the next. One jar per environment, plus one for requests sent with no environment selected; in memory only, for the life of the engine process, and never written to disk. Load runs neither read nor write it.

A cookie set during a redirect chain stays with the origin that set it: it is stored in the jar as any other, and a later hop of the same send carries it only when that hop goes to the same origin - see POST /execute for what a redirect that changes origin does to cookies. The Set-Cookie lines of those intermediate hops are reported on the answer's redirects member, whether or not a later hop carried them.

libcurl caps what it attaches: 150 jar cookies, and a Cookie line of 8190 bytes. A send that hits either still succeeds and says so in its warnings (cookie_limit_reached, cookie_not_sent; see POST /execute): the answer's, or for a streaming send, whose 202 carries none, the stored trace's. The 8190-byte cap also drops the request's typed Cookie rows, which share the line; the 150 cap does not.

libcurl also silently discards what a response sets past three limits: a Set-Cookie line over 5000 bytes, a cookie whose name and value together pass 4096 bytes, and every cookie after the first 50 of one response. The answer (a stream's stored trace) says so under warnings (cookie_dropped_oversized, cookie_dropped_too_many), naming a dropped cookie and never its value. A request sent with disableCookies has no jar and so no warning: libcurl's cookie engine is off and drops nothing.

Under load the same three limits apply to a scenario load run's per-virtual-user cookies, and what they drop is counted across the run in one cookies_dropped run warning that names no cookie. A single-request load run keeps no cookies, so it drops none. The two outgoing caps above are not detected under load.

A storage failure answers 507, 503 or 500, never 400 - see A storage failure is not a 400.

SameSite is parsed and ignored, on purpose: an API client has no cross-site initiator to restrict, so every cookie whose domain, path and Secure flag match is sent whatever its SameSite value (Strict, Lax or None).

GET /cookies

Every jar that holds anything, one entry per scope, in scope-key order (the no-environment jar first), each jar's cookies in its own line order.

A jar whose environment is in the Trash is left out of both forms (issue #3349). The jar is kept, so POST /trash/:id/restore brings the environment's session back with it and it is listed again; a purge (DELETE /trash/:id) drops it. The same goes for a jar keyed by an environmentId that names no stored environment. The no-environment jar is always listed.

Query Parameters: - q, limit, offset (optional): one page of the cookies whose name or domain holds q, in the {data, pagination} envelope - see Paged lists. A page is flat: the scopes are walked in the order above and each cookie row carries its scope's environmentId beside the cookie fields ({environmentId, name, value, domain, path, secure, httpOnly, expires}). A bad limit or offset is a 400 (invalid_limit, invalid_offset).

Response (none of the three):

{
  "scopes": [
    {
      "environmentId": "env_staging",
      "cookies": [
        {
          "name": "session",
          "value": "abc123",
          "domain": ".staging.example.com",
          "path": "/",
          "secure": true,
          "httpOnly": true,
          "expires": 1767225600
        }
      ]
    }
  ]
}

environmentId is null for the no-environment jar - null rather than "" so a client cannot mistake it for an id. expires is unix seconds, or 0 for a session cookie (one that lives until the engine exits). A scope with no cookies left is not reported.

This route lists what a jar holds, not what a URL would carry. The URL-scoped reads of the script API (pm.cookies, jar().getAll(url)) match a secure cookie over https://, and over http:// only for localhost, 127.0.0.1 and ::1, which libcurl sends it to as trustworthy origins.

DELETE /cookies

Clear one jar, or all of them.

Query parameters:

Parameter Meaning
(none) Clear every jar
environmentId=<id> Clear that environment's jar
environmentId= Clear the no-environment jar

The three cases are the null-vs-absent rule in a query string: an empty value is a real scope - the one no id can name - and not a mistake.

Response:

{
  "cleared": 3
}

cleared counts the cookies dropped; clearing a scope that holds nothing is a 200 with 0, not an error. Clearing every jar also clears the ones GET /cookies leaves out because their environment is in the trash, and cleared counts their cookies too: clearing everything leaves no credentials behind.

Client certificates

An mTLS endpoint asks the client to present a certificate, and a certificate is a property of where you are calling, not of one request - the transfer that needs it is as often an OAuth token fetch, a redirect or a script's pm.sendRequest as it is the request you are looking at. So the engine keeps a registry of host to certificate and applies the matching entry itself, on every outbound path: design sends, load runs, SSE streams, pm.sendRequest, the OAuth token endpoint, POST /import/fetch and the monitor scrape. Nothing on a request names a certificate.

Rows are read into the transport policy at the point of use, so a change reaches the next transfer without a restart - and, exactly like the proxy, a load run and a collection run read the registry once at run start and hold it, because libcurl reuses a pooled connection only when its TLS identity matches.

A redirect is matched hop by hop on a design send, a stream and a load run. POST /execute (buffered or stream: true), the pm.sendRequest calls inside it, the OAuth token fetch, a typed POST /import/fetch and every request of a load run follow a redirect one transfer per hop, and the registry is asked about each hop's own host and port: a send that starts at http://host and is redirected to an mTLS https://host presents the entry that answers for the second, and a hop no entry answers for presents nothing.

Matching is by host, and most specific wins. A host is either an exact name (api.example.com) or the one wildcard form, *.example.com, which is read as a label suffix: it answers for api.example.com and a.b.example.com, never for example.com itself and never for notexample.com. That is the whole syntax - a * anywhere else is a 400 naming the form, rather than a row stored as a hostname no transfer can ever equal - and a wildcard never answers for an address literal (127.0.0.1), which only an exact entry matches.

Three tiers decide which entry answers, closest host first:

Tier Beats Example against api.eu.example.com:8443
1 An exact host beats every wildcard api.eu.example.com wins over *.eu.example.com, even if only the wildcard names the port
2 A longer wildcard beats a shorter one *.eu.example.com wins over *.example.com
3 Within one host, the port beats the catch-all *.example.com + port: 8443 wins over *.example.com + port: null

The order is total, so the answer never depends on the order rows were added: two entries can only rank equally by naming the same host and the same port, and the second such write is a 409. Host comparison is case-insensitive (rows are stored lower-cased), and an IPv6 host is registered without its brackets (::1).

Paths, not contents. The row holds the paths of the certificate and key files and the engine opens them at send time, so the private key never enters the database. The passphrase is the one exception - it is stored, in plaintext, the same as every other saved credential (see db-schema.md) - and it is never sent back: reads carry hasPassphrase instead.

Both file paths are checked when the entry is written, and an unreadable one is a 400 naming the file. That is deliberate: a path that is not there otherwise fails at handshake time as an SSL error against the endpoint, which reads as "the API is broken" rather than "this setting is wrong".

A cert-authenticated exchange says so. POST /execute returns clientCertificate on the response, the entry the final hop presented ("" when none matched it), and the stored trace carries the same value under the same name, so a restored response names the entry a live one named. A certificate is presented in a TLS handshake only, so the field is "" for an http:// final hop whatever the registry holds for that host (#3260).

The row says what format its certificate is in, and the engine tells libcurl so. certFormat is pem - a PEM certificate with its key in a second file - or p12, a PKCS#12 bundle carrying both, and it becomes CURLOPT_SSLCERTTYPE on every transfer. Which formats work is a property of the build's TLS backend:

Backend Builds Presents
OpenSSL Linux, macOS, Windows pem and p12
Schannel none since issue #851 p12 only

Mutual TLS works on all three platforms as of issue #851. It did not before: Windows built against Schannel, and curl's Schannel client-certificate path cannot complete the handshake - it imports the bundle with PKCS12_NO_PERSIST_KEY and the key that yields is one Schannel's credential path cannot use, so the transfer failed with SEC_E_INTERNAL_ERROR ... The Local Security Authority cannot be contacted (issue #842). Nothing in Vayu's configuration changed that, so #851 changed the backend instead.

Before moving any leg back to Schannel, read closed issue #842. The defect above is still open upstream: curl 8.21.0 carries two entries for it in its own KNOWN_BUGS (curl issues 17626 and 3145), one of them naming the exact call, and #842 is the measurement record - every driver, with a legacy-PBE and a PBES2 bundle alike. A change that returns to Schannel has to re-instate the wire skip #851 deleted. Schannel also takes no PEM pair at all, so a pem entry would fail at handshake time again, which before issue #833 (when the engine named no type) meant a Windows build could present nothing a user registered.

Both formats are asserted on a wire on every leg (a design send, an SSE stream, a load run and a pm.sendRequest against a listener that demands a client certificate).

A PKCS#12 entry names no key file, because the bundle carries the key: a row that names one is a 400 rather than a stored path nothing would read, and keyPath comes back "". The passphrase field covers both formats - libcurl reads it as the PEM key's passphrase and as the bundle's import password.

The format is checked against the file, and defaulted from it. Leave certFormat out and the engine reads the first bytes of certPath - a PEM marker or the ASN.1 SEQUENCE a DER bundle opens with - and stores what it found, falling back to pem for a file it cannot classify. Name it and it is kept, but a contradiction (a bundle registered as pem, or the reverse) is a 400: the alternative is libcurl's parse error against the endpoint, which is the misdiagnosis this registry exists to end. A file the engine cannot classify is left for the backend to judge rather than refused here.

GET /client-certificates

Every registered entry; a trashed one is not listed.

Response:

[
  {
    "id": "cert_7f3c1a2b",
    "host": "api.example.com",
    "port": 8443,
    "certPath": "/home/ada/certs/client.pem",
    "keyPath": "/home/ada/certs/client.key",
    "certFormat": "pem",
    "hasPassphrase": true,
    "createdAt": 1767225600000,
    "updatedAt": 1767225600000,
    "usable": true
  },
  {
    "id": "cert_2b9d4e60",
    "host": "internal.example.com",
    "port": null,
    "certPath": "/home/ada/certs/moved.pem",
    "keyPath": "/home/ada/certs/moved.key",
    "certFormat": "pem",
    "hasPassphrase": false,
    "createdAt": 1767225600000,
    "updatedAt": 1767225600000,
    "usable": false,
    "problem": "certificate file '/home/ada/certs/moved.pem' is not a readable file"
  }
]

port is null - not 0 and not omitted - for an entry that answers on every port. keyPath is "" for a p12 entry, which stores no key path at all.

usable is whether the engine would present the entry, judged by the check a write runs (and the transport policy re-runs on every row it reads) against the files as they are now. A row can fail it after being written: a file moved or deleted, or a row edited around the routes. The engine then leaves that entry out of every send, and problem says why - the failed check's own sentence, or for a certFormat the engine does not know, a sentence naming it. problem is absent on a usable row. Only this list carries the two fields; the POST and PUT responses do not, since those refuse an unusable row.

POST /client-certificates

Register a certificate for a host. Create only - the engine owns the id, so a body carrying one is a 400 (see the engine owns every id).

Body:

Field Required Meaning
host yes Hostname, no scheme, port or path - or *.example.com for every subdomain of it. Stored lower-cased.
port no The port this entry is specific to; null or absent means every port.
certPath yes Path to the certificate file. Must be readable now.
certFormat no pem or p12. Absent or null reads it off certPath, falling back to pem.
keyPath for pem Path to the private key file. Must be readable now, and must be absent for p12.
passphrase no The key's passphrase, or a PKCS#12 bundle's import password. Write-only.

The uniqueness check and the write are one lock scope. Proving no other row already claims this host + port and writing the new row happen under one acquisition of the database lock, so two creates for the same target racing each other cannot both pass the check before either writes - the second is answered with the 409 below rather than landing beside the first.

Errors:

Status When
400 A host that could never match (carries a scheme, a path, a port, or brackets, or a * outside the *.example.com form), a port outside 1..65535, a non-integer port, a missing host / certPath, a pem entry with no keyPath, a p12 entry that names one, a certFormat outside pem / p12, a certFormat the file's own bytes contradict, a file that is not readable, or a body id.
409 Another entry already claims this host + port. Two rows for one target would make the certificate presented depend on row order, so the second is refused with the id of the first rather than silently shadowing it.

A storage failure answers 507, 503 or 500, never 400 - see A storage failure is not a 400.

PUT /client-certificates/:id

Update an entry. Update only - a missing id is a 404, never a silent create. Merge-patch under the null-vs-absent rule: an absent field keeps its value, port: null widens the entry to every port, passphrase: null clears a stored one, and keyPath: null clears the key path - which is how an entry moves from pem to p12, since a bundle may not name one. certFormat: null re-reads the format off certPath.

Validation runs on the merged row, not on the body, so a PUT that moves only keyPath still proves the pair works together - and a PUT that names certFormat: "p12" without clearing keyPath is a 400, because the merged row would be a bundle naming a key file.

A storage failure answers 507, 503 or 500, never 400 - see A storage failure is not a 400.

DELETE /client-certificates/:id

Delete an entry. The delete is soft (#2973): the row is stamped deleted_at and GET /trash lists it, named by its target, until a purge. From then on it is never presented: the transport policy reads live entries only, so the next design send, stream, collection run or load run to its host goes without it. Every route here treats the id as missing - GET /client-certificates leaves it out, PUT and a second DELETE are a 404 - and its host + port is free for a new entry. The certificate and key files themselves are never touched - the registry only ever held the way to find them. The stored passphrase stays on the trashed row until it is purged.

Restore it with POST /trash/:id/restore, which is a 409 while a live entry claims the same host + port; destroy it for good with DELETE /trash/:id, which is also what the startup sweep does once trashRetentionDays has passed.

Response:

{
  "success": true
}

Errors: 404 if no live entry has that id, a trashed one included. A storage failure answers 507, 503 or 500 - see A storage failure is not a 400.

Allowed folders (file roots)

The folders a request-body file may be read from without being picked file by file - one half of the trust rule, beside the picked files. Stored in file_roots (schema version 3); read once per design send and once per run, so a change applies to the next send. POST and DELETE need the grant secret in X-Vayu-Grant-Secret and answer 403 (grant_secret_required) without it, before the body is parsed; an engine started without a secret refuses both. GET needs nothing.

GET /file-roots

Every allowed folder, ordered by path, as a bare array:

[{ "id": "froot_...", "path": "/home/ada/fixtures", "createdAt": 1764000000000 }]

POST /file-roots

Allows a folder. Body: { "path": "/abs/dir" }. Create only; the engine owns the id, so a body id is a 400.

  • 201 with the row. path is stored canonical (symlinks resolved, . and .. folded, no trailing separator).
  • 400 when path is missing, not a string, not absolute, or not an existing directory.
  • 400 when the canonical path is a filesystem or drive root (/, C:\), the user's home folder, or a folder that contains it (/home, /Users, C:\Users), the message naming which: each would allow nearly every file a request could name. Containment is by path component, case-folded on a drive letter. A folder inside the home folder is fine.
  • 409 when the canonical path is already allowed, naming the existing row's id.

DELETE /file-roots/:id

Stops allowing a folder; the folder and its files are untouched. {"success": true}, or 404 when no such row exists.

Picked files (file grants)

The files a person picked, each sendable from wherever it lies - the other half of the trust rule, beside the allowed folders (#2356). Stored in file_grants (schema version 6); read once per design send and once per run, like the folders. A grant is matched exactly against a reference's canonical path, so it covers that one file and nothing beside it. POST and DELETE need the grant secret in X-Vayu-Grant-Secret and answer 403 (grant_secret_required) without it, before the body is parsed; an engine started without a secret refuses both. GET needs nothing.

GET /file-grants

Every picked file, ordered by path, as a bare array:

[{ "id": "fgrant_...", "path": "/home/ada/Downloads/body.bin", "createdAt": 1764000000000 }]

POST /file-grants

Records a picked file. Body: { "path": "/abs/file" }. Create only; the engine owns the id, so a body id is a 400.

  • 201 with the row. path is stored canonical (every symlink resolved, . and .. folded), so a link re-pointed after the pick no longer matches.
  • 400 when path is missing, not a string, empty, holds a {{variable}} (a grant names one file, never a template), is not absolute, or is not an existing regular file - a directory, a device or a pipe is never granted.
  • 409 when the canonical path is already granted, naming the existing row's id, as a second spelling of an allowed folder is.

DELETE /file-grants/:id

Forgets a picked file; the file itself is untouched, and a body naming it is refused from then on unless an allowed folder holds it. {"success": true}, or 404 when no such row exists.

Transport diagnostics

POST /diagnostics/connection

Send one request under the transport policy in force and report which hop answered. Proxy, custom CAs and the client-certificate registry all fail at the first real request otherwise, and libcurl's message there names the endpoint rather than the setting - which is how "my API is down" gets filed against a proxy that was never configured correctly.

{ "url": "https://api.example.com/" }

The probe is a HEAD, with verification on (that is the subject of the test), redirects off (a redirect would move the test to a host the caller never named and report its proxy and certificate as this one's) and a fixed 10-second deadline.

{
  "url": "https://api.example.com/",
  "outcome": "proxy_failed",
  "errorCode": "PROXY_ERROR",
  "detail": "Received HTTP code 407 from proxy after CONNECT",
  "proxy": { "mode": "manual", "url": "http://corp.example:8080" },
  "clientCertificate": ""
}
Field Meaning
outcome ok, proxy_failed, tls_failed, timed_out or failed. Deliberately coarser than ErrorCode: these are the answers that lead a reader to a different setting. proxy_failed covers every PROXY_ERROR: an unresolvable or down proxy, a refused CONNECT, and a forwarding proxy's 407 on an http:// target.
proxy.mode The proxyMode in force. Always present.
proxy.url The proxy the probe went through, with its user:password@ removed (the body reaches a screen and an agent's context). Absent when the probe went direct. Under manual, and system with a resolved URL, it is the setting in force, left out when the probe completed without a proxy (a proxyBypass entry); a probe that failed still names it, since a failure at the proxy hop may not read as proxied. Under environment, and system with nothing resolved, it is what libcurl read from http_proxy / https_proxy / all_proxy for the target's scheme - reported only when libcurl really proxied the probe (CURLINFO_USED_PROXY), so a no_proxy exemption reads as direct.
proxy.source "environment" when proxy.url is not a Vayu setting: libcurl chose the proxy from the process environment. Absent otherwise. With source set and no url, the probe was proxied but the variable could not be read back.
clientCertificate The registry entry that answered for this host, "" when none did - always so for an http:// probe, since a certificate is presented in a TLS handshake only (#3260). Always present, like POST /execute's.
status The status line. Present only on ok.
errorCode / detail The engine's ErrorCode spelling and the message: libcurl's own, or for a forwarding proxy's 407 on an http:// target (#3257) the engine's sentence naming the proxy. Absent on ok.

A failed connection is a 200. The test succeeded in answering; only a malformed body or a URL that is not http/https is a 400.

It never returns the response body, headers or redirect chain, and a test asserts that. This is a diagnostics surface on the localhost API, not a general fetch proxy - that is POST /import/fetch, behind its own byte bound.

Webhook Inbox

An inbox is a second HTTP listener the engine opens on request. It accepts any method on any path, records what arrived, and answers a canned response - nothing else. That is what makes testing the receiving side of a webhook a local operation: point the sender at the inbox URL instead of a cloud tunnel, and the payload never leaves the machine.

Lifetime is the engine process. An inbox is not a stored resource: there is no create/update split (POST creates, PUT updates applies to collections, requests and environments), ids are not restorable across restarts, and POST /inbox/start is a verb path for that reason. Stopping an inbox frees its listener but keeps the record - and therefore its captures - readable until the engine exits; DELETE /inbox/:inboxId is what removes both. After an engine restart the app names the inboxes, issuers and mocks that stopped with it in one notice (app/src/lib/services-stopped-by-restart.ts).

Binding is a trust decision. The default is 127.0.0.1. Any other address is refused unless the caller also sends "confirmNonLoopback": true, and the inbox reports loopback: false from then on so a client can badge it. See architecture.md for why only the inbox listener may bind wide and the management API never may. An inbox holds at most 96 connections at once: 32 being served (a canned delayMs wait occupies one for its whole duration) and 64 waiting for one. A connection past that is closed at accept, which the sender sees as a reset, so an inbox bound past loopback cannot be held open by idle connections until the engine runs out of file descriptors. Every other on-demand listener (mock server, mock issuer, OAuth callback) has the same bound.

Bounds. Three are settings (GET/POST /config, category Services), read once when an inbox starts - so a change applies to the next inbox started, and a running listener keeps what it was started with:

Setting Default Range What it bounds
inboxMaxBodyBytes 65536 256 - 8388608 Stored body per capture. Past it the body is kept as a prefix with bodyTruncated: true, cut on a character boundary so a prefix of text is still text; bodyBytes is always the size as received
inboxMaxCaptures 500 1 - 10000 Captures retained per inbox, oldest evicted first. Also the ceiling on one limit of the capture list
inboxLivePollIntervalMs 250 25 - 5000 How often a watched inbox checks for new captures - the delay between a webhook landing and its event

Three are not settings, deliberately. A request over 8 MiB is refused at the transport with a 413 and recorded nowhere: that bounds what an unauthenticated remote caller can make the engine buffer, which is not the local user's preference to spend. The canned response's delayMs is capped at 30000: it holds a listener thread for its whole duration. A stop, a delete or the engine shutting down ends the delay at once, and the canned answer then goes out without the rest of it. The request target - path and query together - is capped at 8192 bytes by the transport, past which it answers 414.

The transport also answers 400, closes the connection and records nothing for a request it cannot read unambiguously (RFC 9112 §3): a request line whose parts are not separated by single spaces, a request target holding a #, an HTTP/1.1 request with no Host, a request with more than one Host or with a byte outside uri-host [ ":" port ] in it. A request carrying both Transfer-Encoding and Content-Length is captured and answered, and then the connection is closed. The request line and headers together must arrive within 5 seconds.

Below that cap the path's length does not matter, and "any path" is meant literally: an inbox routes every request to its capture without matching the path against anything, so a signed callback URL, a per-delivery token in the path or a deeply nested tenant route is recorded like any other (issue #1140).

A multipart/form-data body (a file upload, curl -F) is captured raw, as sent, with its boundaries and parts, and is cut at inboxMaxBodyBytes like any other body (issue #3110). An application/x-www-form-urlencoded body is captured the same way up to the 8 MiB transport ceiling rather than refused at 8192 bytes with an empty 413 (issue #3111). The capture's Content-Type header is the sender's.

A compressed body is stored as sent. A sender that declares Content-Encoding: gzip, deflate, br or zstd (an OpenTelemetry or Sentry exporter, a log shipper) is captured and answered with the canned response like any other; the inbox does not decompress, so body holds the compressed bytes (base64, as any non-text body is), bodyBytes is their compressed size, the cut at inboxMaxBodyBytes applies to them, and the capture's Content-Encoding header is the sender's. Only the inbox listener does this: the management API refuses a compressed request body, and an unrecognised coding such as identity was always passed through.

CORS follows the inbox's allowedOrigins (issue #2367), the same policy a mock server applies (see Mock Server), so a browser-hosted sender can read the canned response:

  • None listed (the default): every answer carries Access-Control-Allow-Origin: * and Access-Control-Expose-Headers: *, whatever the request's Origin, and never Access-Control-Allow-Credentials or Vary. Every page in the browser can read the canned response; none can read one sent with the user's cookies.
  • A list: a request whose Origin is a listed origin gets that Origin echoed, Access-Control-Allow-Credentials: true and the rest of the answer below. Any other request - an unlisted origin, the literal null a sandboxed frame or file:// page sends, no Origin at all - is still captured and answered, with no Access-Control-* header, so the browser keeps the answer from the page. Vary: Origin is on every answer under a list. Origins are compared canonically: scheme and host case-folded, a default port dropped, so https://App.Example:443 matches a listed https://app.example.

A real preflight (a request carrying Access-Control-Request-Method) is answered 204 and never reaches the capture, the canned delay or the canned status - a preflight must get a 2xx or the browser aborts before the real request arrives, so a canned response configured with a non-2xx status (to exercise a sender's retry path) would otherwise break every browser-hosted sender silently. It carries the grant above (and Access-Control-Allow-Methods / -Allow-Headers echoing what was asked, Access-Control-Max-Age: 600), or under a list for an unlisted origin no CORS header at all. A header the canned response sets that names Access-Control-* or Vary is dropped rather than echoed, since the engine already answered those and a replayed grant would undo a refusal; a credentialed answer (a listed origin) rewrites the wildcard Access-Control-Expose-Headers into the canned response's own header names, per the Fetch spec's rule that * there is a literal name, not a wildcard, under credentials.

POST /inbox/start

Start a listener. Every field is optional - an empty body starts a loopback inbox on a free port that answers 200 with no body.

Request:

{
  "port": 0,
  "bind": "127.0.0.1",
  "confirmNonLoopback": false,
  "allowedOrigins": [],
  "response": {
    "status": 200,
    "body": "",
    "headers": {},
    "delayMs": 0
  }
}

Field Meaning
port 0 (default) picks a free port
bind Default 127.0.0.1; anything outside 127.0.0.0/8 and ::1 needs confirmNonLoopback. Loopback is decided by parsing the address, so a hostname that merely starts 127. (or localhost.example.com) is not loopback and needs the confirmation. 0.0.0.0, :: and [::] bind every interface; the response then names where to send (reachableAt, below)
response.status 100-599
response.headers String values only; a Content-Type here is used verbatim
response.delayMs 0-30000, applied before every reply
allowedOrigins Default [] (CORS *, no credentials). Up to 32 origins granted credentialed CORS, each http:// or https:// plus a host and an optional port, at most 512 bytes: no path (a trailing / included), query, fragment, user name or password, no * and not null. Stored and echoed canonical (scheme and host lowercased, a default port dropped); fixed for the inbox's life, PUT does not change it

An out-of-range value is a 400 naming the field rather than a fallback to the default: a listener quietly answering something other than what it was asked to is invisible on both sides of the wire. A bind that fails is a 409 with code inbox_bind_failed; a non-loopback bind without confirmation is a 400 with code inbox_non_loopback_bind. An allowedOrigins that is not an array, holds too many entries, or holds one that is not an origin is a 400 bad_request naming the entry (allowedOrigins[1]) and what is wrong with it.

A port another engine listener is already running on - an inbox or a mock issuer - is refused with that same 409, naming the holder ("inbox inbox_2f1c is already listening there"). The engine checks that itself rather than letting the bind report it: listeners are bound with SO_REUSEPORT, so on Linux a second bind on the same address and port succeeds and the kernel then splits arriving connections between the two listeners, each capturing an effectively random half. A port held by a process outside the engine is still reported by the bind (Couldn't bind <address> - the address may be in use or unavailable); port: 0 is never refused this way, since the kernel does not hand out a port it is already using.

Response:

{
  "inboxId": "inbox_2f1c...",
  "url": "http://127.0.0.1:41235/",
  "bind": "127.0.0.1",
  "port": 41235,
  "running": true,
  "loopback": true,
  "captureCount": 0,
  "allowedOrigins": [],
  "response": { "status": 200, "body": "", "headers": {}, "delayMs": 0 }
}

captureCount is how many captures the inbox is holding right now - what a DELETE /inbox/:inboxId would destroy with it. Every route that returns an inbox fills it, so a client can word a confirmation without a second round trip.

url is where a sender sends, which is the bind address unless the inbox is bound to every address (0.0.0.0, :: or [::], each needing confirmNonLoopback): that is no address a sender can use, so url is the first non-loopback IPv4 address of the machine, and reachableAt lists a URL for every one (the machine has several; url is only the first the OS names):

{
  "url": "http://192.168.1.20:41235/",
  "bind": "0.0.0.0",
  "reachableAt": ["http://192.168.1.20:41235/", "http://10.0.0.7:41235/"]
}

reachableAt is on the wire for a wildcard bind only, and lists IPv4 addresses only. A machine with no non-loopback IPv4 address reports reachableAt: [] and a url on 127.0.0.1. It is read from the interfaces each time the inbox is read, not fixed at start, so it follows a change of network.

GET /inbox

Every inbox this process has started, running or stopped: {"data": [ ... ]}, each entry the object above.

PUT /inbox/:inboxId

Update the canned response, live - the next caller receives the new one, with no restart and no captures lost. Merge-patch: an absent field keeps what the inbox is serving. The body may be the response object itself or {"response": {...}}, so a client can send back what start handed it. 404 for an unknown id.

Atomic against a concurrent update, the same guarantee the resource PUTs above give (issue #1454): the read, the merge and the write are one acquisition of the inbox's own lock, not the database's - the canned response lives in memory - so two clients patching one inbox at the same moment each merge onto what the other just committed rather than onto the response as both of them found it.

POST /inbox/:inboxId/stop

Stop the listener. Returns the inbox with running: false. Captures survive; 404 for an unknown id. A stop is not a delete - DELETE /inbox/:inboxId is.

DELETE /inbox/:inboxId

Stop the listener, drop the record, and delete its captures with it: {"inboxId": "...", "capturesDeleted": 12}. 404 for an unknown id.

A running inbox is stopped rather than refused - one call, because the caller's intent is that the inbox be gone. That is safe rather than racy because the teardown joins every in-flight handler before returning, so nothing can still be capturing when the rows are cleared. The order is stop, then clear, then drop the record: a database failure therefore leaves the inbox in place - stopped, and deletable again - rather than orphaning captures no inbox could list.

The captures dying with the record is the point, and is why stop keeps them: they go by explicit user intent here, instead of the record living to the end of the process to protect them. There is deliberately no restart route: delete and start a new inbox. A restart would have to decide what happens to the existing captures, and this way the user decides.

GET /inbox/:inboxId/requests

The captures, newest first, in the standard {data, pagination} envelope.

Query parameters: limit (default 50, capped at 500), offset (default 0).

{
  "data": [
    {
      "id": 12,
      "inboxId": "inbox_2f1c...",
      "receivedAt": 1767225600000,
      "method": "POST",
      "path": "/hooks/order",
      "query": "attempt=2",
      "headers": { "Content-Type": "application/json" },
      "body": "{\"id\":7}",
      "bodyEncoding": "utf8",
      "bodyBytes": 8,
      "bodyTruncated": false,
      "remoteAddr": "127.0.0.1"
    }
  ],
  "pagination": { "total": 1, "limit": 50, "offset": 0, "hasMore": false, "returned": 1 }
}

id is the capture's storage id and also its SSE event id (see below). headers joins a repeated name with ,. query is the raw query string without the ?.

bodyEncoding says how to read body (issue #3109). A JSON string holds only UTF-8 and a sender can post any bytes, so "utf8" means body is the stored text itself, and "base64" means the stored bytes were not valid UTF-8 text (or held a NUL) and body is their standard, padded base64. It is decided when the capture is read, so every capture carries it, and bodyBytes is the size as received in both cases, never the length of the encoded string. A body the byte cap cut is first trimmed back to a character boundary, so a cut inside a multi-byte character leaves utf8 text rather than turning the whole prefix into base64; bodyTruncated still says it was cut. path and query are recorded raw, exactly as the sender spelled them: percent-escapes such as %2F and %20 are kept, so a signature over the path or a copied capture URL still matches the request received. Neither is classified: a byte in either that is not UTF-8 is answered as U+FFFD.

DELETE /inbox/:inboxId/requests

Clear the captures, keeping the listener: {"inboxId": "...", "cleared": 12}.

GET /inbox/:inboxId/live

Server-Sent Events, one event per capture, each carrying the same object as the list above (bodyEncoding included) and an SSE id: equal to the capture's id. A reconnect that sends Last-Event-ID resumes after that capture, so nothing is missed across a drop. The stream ends when the inbox is stopped.

?lastEventId=<id> is the same resume point as a query parameter, for a client that reconnects by hand: browser EventSource sets Last-Event-ID only on its own retry and exposes no way to set a header on a fresh connection. The header wins when both are given, being the more recent of the two. A value that is not a non-negative capture id is refused with 400 and code invalid_last_event_id rather than resumed from the start, which would replay every retained capture as though it had just arrived.

One stream per inbox. A second concurrent watcher is refused with 409 and code inbox_live_in_use: each SSE handler occupies a cpp-httplib pool thread for its whole life, so N watchers on one inbox is N parked threads.

A claim whose holder stopped writing is taken over, not refused. A stream learns its socket died only when its next write fails, up to one inboxLivePollIntervalMs later, so a client reconnecting inside that window used to meet a 409 it could not recover from. A holder that has not written successfully for two poll intervals (at least 100ms) is not writing, and its slot goes to the newcomer; the evicted stream ends on its next write. Every live stream writes at least a keep-alive each interval, so a genuinely live watcher is never evicted and a second concurrent one is still refused.

Mock Server

A mock server is a listener that answers a collection's saved examples on the paths its requests describe. It is what examples are for: import a spec, and the responses it documented become a running upstream you can build a frontend against, or point a Vayu load run at, without a cloud plan or a second machine.

A mock serves the stored body verbatim, including a partial one. An example whose bodyTruncated is true holds only the first slice of the response it was captured from, and the mock answers with those bytes and the recorded headers as though they were a whole response - nothing on the wire says otherwise, and the flag deliberately does not change what is served. It is disclosure, not behaviour: the app paints a "Partial body" chip on the row so the choice to serve it is a made one (issue #659).

A 204 or 304 example is served with no body, no Content-Length and no Content-Type (RFC 9110 §6.4.1), whatever its stored body says; the rest of its headers are kept. The same holds for a 1xx example stored before create began refusing them (#3117). A real preflight's synthesized 204 carries no Content-Length either.

Example bodies are served literally. A {{variable}} or a dynamic value such as {{$guid}} in a stored body or header is sent as those characters: the mock resolves no variables, unlike Postman's mock servers, which a collection moving from Postman may expect. Resolving them would be a feature, not a docs fix.

Lifetime is the engine process, exactly as for an inbox and an issuer - a verb path starts it, ids are not restorable across restarts, and stopping one drops its record. There is no stopped state to read: a mock holds nothing that outlives its listener, unlike an inbox and its captures. Trashing the collection a mock serves, or any collection above it, stops the mock the same way (DELETE /collections/:id), and a restore does not start it again. A mock an engine restart stopped is named in the app's restart notice, as an inbox is.

Load-testing against a mock is a supported workflow, and it is the one this listener exists for as much as frontend development: a mock is a known-latency, zero-cost upstream on the same machine, so a run against it measures the generator rather than someone else's service, and costs nobody a bill. Start the mock, then point a run at one of its paths:

curl -s localhost:9876/mock/start -d '{"collectionId":"col_abc123","latencyMs":5}'
# -> {"mockId":"mock_5f2a","url":"http://127.0.0.1:43117", ...}

curl -s localhost:9876/runs -d '{
  "mode":"constant_rps","targetRps":500,"duration":"30s",
  "url":"http://127.0.0.1:43117/pets","method":"GET"
}'

latencyMs is what makes the baseline realistic rather than degenerate, and errorRatePct is how a run's error handling and threshold verdict get exercised without breaking a real service.

Loopback only. There is no bind field. Unlike an inbox - which serves capture-and-echo and nothing else, so a LAN-visible one is defensible - a mock re-serves stored response bodies verbatim, and a recorded response can carry whatever the real one did. See architecture.md.

The route table is a start-time snapshot. It is built once, from the collection and every collection under it (an OpenAPI import files its requests in a folder per tag, so the subtree is the only useful unit), and a running mock does not reload edits: stop it and start it again. An example saved from the app's response viewer (issue #588) is an edit like any other - it is appended after the request's existing examples, so a restart keeps answering with the same first one, and the new row is only reachable once the mock is restarted.

How a request is matched.

  • The stored URL is reduced to a path: scheme and host - or the {{baseUrl}} variable standing in for them - the query and the fragment are all dropped. A leading variable goes whole and is never resolved, so a path carried inside its value is lost: with baseUrl set to https://x/v1, a request stored as {{baseUrl}}/pets is mocked at /pets, not /v1/pets, and a caller that keeps /v1 in its URL matches no route. Put the prefix in the stored URL ({{baseUrl}}/v1/pets) to have the mock serve it.
  • All three template spellings are one wildcard segment: {{petId}} (Vayu and Postman), {petId} (OpenAPI) and :petId (Postman's other form). A wildcard matches exactly one non-empty segment. The normalization is pinned to the importers' own by engine/tests/fixtures/path-template-conformance.json, which both suites read - the app writes these URLs and the mock reads them back.
  • Specificity wins, not registration order: /pets/mine answers GET /pets/mine even when /pets/{{petId}} was stored first.
  • A trailing slash and a repeated / are the same route.
  • Requests that share a method and path are one route (#3115). The query is dropped, so GET /q?kind=a and GET /q?kind=b (a Postman collection's "login ok" and "login fail") cannot be told apart: one of them answers both and the other shows 0 hits for good. Among routes of equal specificity the first that has a saved example answers, else the first in sidebar order, so an example-less request listed above one with an example no longer turns the path into a 501. Two routes are duplicates only when they have the same method, the same number of segments and the same literals in the same positions (a wildcard's name does not count): /a/{{x}}/b and /a/b/{{y}} are equally specific but answer different paths, so neither is shadowed. The start response counts the shadowed requests (duplicateRoutes) and GET /mock/:mockId/routes marks each one and names the request that answers in its place.
  • A HEAD is answered by the GET route of that path (#3118) when no HEAD request is stored for it: the GET's status and headers (its Content-Length included) and no body, so curl -I on a mocked path works. A stored HEAD request still wins.

What a miss says. The message is most of the debugging value, so the three outcomes are distinct rather than one blanket 404:

Case Status code Message names
No request has that path 404 mock_no_route The method and path, and how many routes are served
The path matches, the method does not 404 mock_method_mismatch The matching path template and the methods it is served for
A route matched but its request has no saved example 501 mock_no_example The request's name, and that an example must be saved or imported

CORS follows the mock's allowedOrigins (issue #2367). A mock server answers whatever calls it - most often a browser page on another origin, not only curl - and what it answers with is often a recorded response, so which pages may read it is the caller's to state:

  • None listed (the default): every response carries Access-Control-Allow-Origin: *, whatever the request's Origin, plus Access-Control-Expose-Headers: * so a page's fetch can read a header the example set, and never Access-Control-Allow-Credentials or Vary. Every page in the browser can read the mock; none can read a response sent with the user's cookies.
  • A list: a request whose Origin is a listed origin gets that Origin echoed with Access-Control-Allow-Credentials: true, and Access-Control-Expose-Headers names the example's own headers, since the Fetch spec reads * there as a literal name, not a wildcard, once credentials are in play. Any other request - an unlisted origin, the literal null a sandboxed frame or file:// page sends, no Origin at all - is still served, with no Access-Control-* header, so the browser keeps the response from the page. Vary: Origin is on every response under a list. Origins are compared canonically: scheme and host case-folded, a default port dropped, so https://App.Example:443 matches a listed https://app.example. A list also pins the Host: the mock answers 403 to any request, a preflight included, whose Host is not 127.0.0.1:<port>, localhost:<port> or [::1]:<port> of its own port (the management API's rule), so a page that DNS rebinding has made same-origin with the mock cannot read it. A mock with no list answers any Host.

A header the example itself carries under Access-Control-* or Vary is dropped rather than echoed, since the engine already answered those and a replayed grant would undo a refusal. The grant applies to a miss too - a 404 with no CORS headers reads in a browser as an opaque "CORS error" instead of the mock_no_route / mock_method_mismatch / mock_no_example body above.

A real preflight - a request carrying Access-Control-Request-Method - is always answered synthetically (204, with the grant above plus Access-Control-Allow-Methods / -Allow-Headers echoing what the browser asked for and Access-Control-Max-Age: 600, or under a list for an unlisted origin no CORS header at all), whether or not a route is stored for that path under OPTIONS: breaking the preflight to surface a stored route's 404/501 would break the browser request behind it for nothing. It does not count toward a route's hits or appear in GET /mock/:mockId/activity. A plain OPTIONS request carrying neither header is ordinary traffic and is served or missed like any other verb.

Bounds (rails, not settings): at most 8 mock servers at once (a listener thread each), at most 2000 routes in one table, and latencyMs capped at 30000 - it holds a listener thread for its whole duration, until a stop ends it.

POST /mock/start

Request:

{
  "collectionId": "col_abc123",
  "port": 0,
  "latencyMs": 0,
  "errorRatePct": 0,
  "allowedOrigins": []
}

collectionId is required. port 0 (the default) binds a free one. latencyMs (0 - 30000) delays every answer; errorRatePct (0 - 100) replaces that share of answers with a synthesized 500 carrying mock_injected_error. allowedOrigins (default []) lists up to 32 origins granted credentialed CORS (see above), each http:// or https:// plus a host and an optional port, at most 512 bytes: no path (a trailing / included), query, fragment, user name or password, no * and not null. It is stored and echoed canonical (scheme and host lowercased, a default port dropped). Every out-of-range value is a 400 rather than a clamp, and an allowedOrigins entry that is not an origin is a 400 bad_request naming the entry (allowedOrigins[1]) and what is wrong with it.

Response:

{
  "mockId": "mock_5f2a",
  "collectionId": "col_abc123",
  "collectionName": "Pet Store",
  "url": "http://127.0.0.1:43117",
  "port": 43117,
  "latencyMs": 0,
  "errorRatePct": 0,
  "routeCount": 12,
  "routesWithoutExample": 3,
  "duplicateRoutes": 0,
  "createdAt": 1735689600000,
  "allowedOrigins": []
}

url has no trailing slash - it is a base to concatenate a path onto. routesWithoutExample is the number that explains an otherwise empty-looking mock, which is why it is reported rather than left to be discovered one 501 at a time. duplicateRoutes is the number of requests shadowed by another with the same method and path (see above): rows that can never answer, whatever their query says. It is 0 for a collection with none.

Errors: 404 for a collection that does not exist; 400 mock_no_requests when the collection and its subtree hold none (a listener that 404s everything is never what the caller meant); 400 mock_too_many_routes past the table bound; 409 mock_limit_reached at the server budget; 409 mock_bind_failed when the requested port is taken, naming the holder when this engine is the one holding it.

GET /mock

{"data": [...]} - every running mock, in the shape above.

GET /mock/:mockId/routes

The table the mock is serving. This is how "the mock 404s that path" gets diagnosed without sending a request per guess.

{
  "data": [
    {
      "requestId": "req_1",
      "requestName": "Get pet",
      "method": "GET",
      "path": "/pets/{{petId}}",
      "hasExample": true,
      "mode": "first",
      "hits": 3,
      "status": 200,
      "exampleName": "200 OK"
    }
  ]
}

status is 0 when hasExample is false - there is no example whose status it could be. mode is the request's mock_response_mode ("first" / "fixed" / "random"); hits is how many times this route has answered a request, since the mock started. exampleName is the example that would answer for "first" or "fixed" - it is absent for "random", since which one answers varies per request. 404 for an unknown mock.

A request that shares its method and path with another (see "How a request is matched") is shadowed: its row carries "shadowed": true and "shadowedBy": {"requestId": "req_2", "requestName": "login ok"}, naming the request that answers for both. Both members are absent - not false - on every row that is not shadowed, including the one that answers. A shadowed row keeps hits: 0, and its hasExample / status describe its own examples, which are never served.

GET /mock/:mockId/activity

What this mock has served, newest first: {"data": [...]}, at most limit entries (query param, default 50, capped at 200; a non-numeric value is a 400). Each entry is one inbound request, whichever of the three ways it was handled:

{
  "data": [
    {
      "at": 1735689600123,
      "method": "GET",
      "path": "/pets/1",
      "requestId": "req_1",
      "requestName": "Get pet",
      "exampleId": "ex_1",
      "exampleName": "200 OK",
      "status": 200,
      "injectedError": false
    }
  ]
}

requestId / requestName are null when nothing in the route table matched the path at all, and also for an injected failure (injectedError: true): the error-rate roll happens before route resolution, so an injected 500 never reaches route matching, even when a route would have matched. exampleId / exampleName are null alongside them, and also when the matched route had no saved example (status: 501). injectedError: true marks a synthesized errorRatePct failure. 404 for an unknown mock. Like the route table, this log is discarded when the mock stops - there is nothing to read after that.

POST /mock/:mockId/stop

Stops the listener and drops the record: {"mockId": "...", "stopped": true}, or 404. In-flight answers are joined before this returns; one inside its configured latencyMs is answered at once, without the rest of the delay.

Authentication

The engine resolves auth server-side. Every request's auth object (on POST /execute and POST /runs) is applied to the outgoing request before it hits the wire:

auth.mode Effect
none / inherit No-op (inherit is resolved by POST /compose before it reaches an execution endpoint; one arriving unresolved is a warning in the logs)
bearer Authorization: Bearer <token>, the token trimmed of the spaces and tabs around it (#2467); a token empty once trimmed writes no header at all and the send carries an authNotice saying so (#3203)
basic Authorization: Basic <base64(user:pass)>, as typed - a password may end in a space
apikey Header key: value, or ?key=value when in: "query"; the key and the value are trimmed of the spaces and tabs around them (#2467); a key empty once trimmed writes nothing and the send carries an authNotice saying so (#3203)
oauth2 Acquires/caches a token (below) and injects it per tokenPlacement; a token placed in the header yields to an Authorization header the request carries, and is then not fetched at all (#3202, below)
any other mode (digest, aws, ntlm, hawk, oauth1, edgegrid, jwt, which an import can store) Not executed: the request is sent without authentication, never refused, and the /execute answer and the stored trace carry an authNotice saying so (#2474)

When it is applied. As the request is built, before any pre-request script runs - so the script's pm.request holds the header - unless a credential (a bearer token, a basic username or password, an apikey key or value) still holds a {{name}} that is not a data column or the iteration identity. Such a name is one composition found no variable for, or any name a scope answers in a request a pre-request script runs before (it is listed in deferredVariables) or in a step of a collection run whose plan writes a variable (Scenario runs), and that auth is applied after the pre-request script and the residual-token pass instead, each credential resolved against the scopes as the script left them (#2473, #2521), so pm.environment.set("password", …) reaches a basic pair before it is base64-encoded. That is Postman's order; the script then does not see the header in pm.request.headers, and an Authorization it sets wins by the rule below. A data column or the identity in the same credential is bound first. A name nothing answers is encoded as written. A script that assigns pm.request.auth replaces this block in either case: the credential applied before it is taken off, a waiting one is never applied (#3131, see Mutating the request).

oauth2 follows the same order on a single send and a collection run's step (#2521). A config in a request that a pre-request script runs before (on a sequential run, in any step of a plan that writes a variable), or holding a {{name}} that nothing defines, is left as written by POST /compose, resolved in every string after the pre-request script, and only then is its token acquired; the token cache key is computed from that resolved config, so a script that sets a clientId or an accessTokenUrl selects its own cached token, and a client secret or scope it sets reaches the token endpoint when a token is fetched (neither is part of the key, so a token already cached under the same key is reused). The wait on the identity provider is left out of engineMs, as a fetch at the build is, and a token that cannot be acquired answers authErrorCode as it does at the build. A load run acquires its token once, when it is planned and before any script runs, from the stored values: its composition (deferDynamicVariables) resolves the config, and a name nothing defines is refused with a 400 that names it (invalid_run_config for a single request, invalid_scenario for a collection). A script that sets an OAuth 2.0 variable has no effect under load, however many iterations or virtual users run it, and nothing is re-acquired per iteration; the one change to a run's token after it starts is the mid-run refresh of the token cache. The same order holds wherever a script can run between the build and the send:

Send Applied after
POST /execute (buffered and stream: true) the pre-request script
A collection run's step that step's pre-request script, each iteration
A collection load run's step that submission's step.before elements (an inline script.pre) and the residual pass over its virtual user's scope
A single-request load run declaring requestElements whose submissions are copied (a step.before kind, data rows, a bind token or deferred auth) that submission's step.before elements and the residual pass over the run's scopes (a script.setup included)

A single-request load run without requestElements has no such pass. When it names an environmentId or a requestId, the build leaves such credentials alone and its start-of-run pass (POST /runs) resolves and applies them once, after the request's own names, so a basic pair and a query-placed api key are encoded with their values (#3288); without either, the build encodes the name as written. Under load a name nothing answers is never a refusal: it is sent as written and counted like any other unresolved token (#1503), except inside a basic pair's base64, where it never was countable.

An apikey with in: "header" whose key is not a header name once trimmed (X Key) is refused, with nothing written: the failure is AUTH_FAILED with an authErrorCode of invalid_header_name. The message names the offending byte and not the key, which arrives already resolved and may be a secret. An apikey whose key is empty or only padding, in the header or the query, and a bearer token that is empty or only padding are not refused: nothing is written (never Authorization: Bearer with nothing after it), the request is sent without that credential, and the send carries an authNotice saying so (#3203), so a variable left unset on purpose does not fail a run. A token or key that resolves empty after the pre-request script is judged the same way. A bearer token with spaces inside it keeps them: only the ends are trimmed.

A user-supplied header always wins over the one auth would write: Authorization over bearer/basic/oauth2, and a header named like the API key's key over apikey (in: "header"; the key name is matched against the request's own headers). Header names are matched case-insensitively, so authorization or x-key against X-Key counts. A query-located API key is a URL parameter and is appended regardless. The app's code snippets apply the same rule (engine/tests/fixtures/auth-header-precedence.json).

An oauth2 block whose token goes in the header fetches nothing when the request already carries an Authorization header (#3202). The header the request typed is sent, no token is acquired, and the token cache, the targetPolicy and the endpoint are not consulted, so a token endpoint that is down, refused by the policy or unreachable cannot fail the send. The send says so: authNotice reads the request's own Authorization header was sent; no OAuth 2.0 token was fetched (see authNotice), and no Authorization is recorded as written by auth. The rule holds wherever auth is applied: at the build, after a pre-request script, in a collection run's step, and in a load run, whose POST /runs pre-flight reads the payload's headers the way the run will and so does not fetch (or fail on) a token it would not send. It applies to the Authorization header only: an oauth2 block with tokenPlacement: "query" writes a URL parameter, has nothing to yield to, and is fetched and appended as before. The header is read when auth is applied, so one a pre-request script sets spares the fetch only when the auth waits for that script (When it is applied); otherwise the token was already fetched and the script's header replaces what auth wrote.

Redirects. With followRedirects on, a redirect to a different scheme, host name or port drops the Authorization header and a typed Cookie, so bearer, basic and an oauth2 token placed in the header stop at the first origin. Nothing else is dropped: an apikey with in: "header" - and any other header the request carries - is sent to the origin the redirect leads to, including over http after an https hop. That is a documented exception, not an oversight: it is the rule libcurl applied while it followed redirects, kept as it was. A design send, a stream and a load run all run the engine's own redirect loop, so the three cannot disagree about what reaches the next origin. A query-located key is part of the URL as sent; the next hop is whatever the response's Location names, so the key reaches it only if that URL repeats it. Set followRedirects: false on a request whose key must not leave the origin it was sent to; the app says this beside the API Key fields. A design send makes the downgrade visible: each entry of the answer's redirects records the url its request went to and schemeDowngrade, true when that request was https and the next one http (see redirects) and pm.response.redirects shows them to a post-request script. A load run and a stream record no hops. (engine/tests/redirect_credentials_test.cpp)

OAuth 2.0 token cache

Tokens are acquired once and cached (SQLite oauth_tokens, keyed by a deterministic cacheKey = accessTokenUrl \x1f clientId \x1f credentialsId \x1f username-if-password-grant, then one segment per extra parameter list that has a row the engine would send, in the order authorizationParams, tokenParams, refreshParams: \x1f <list>:<key>=<value>, further rows joined by \x1e, the pairs sorted by key, then value, byte-wise). A row whose key names a credential (client_assertion, assertion, an X-Api-Key or Authorization header, the names an export blanks: core::vayu_ext::names_param_credential) is written as <key>= with its value left out, because the key is returned as cacheKey, stored as the cache row's primary key and can reach a log; a rotated assertion therefore keeps the token it was cached under. Row order and sendAs do not change the key; a config with no such row keys exactly as it did before the lists existed. scope, audience and resource are not read, so a distinct credentialsId (or an extra parameter row) is what separates two tokens that differ only in those. The recipe is oauth::cache_key (engine/include/vayu/http/oauth_client.hpp), and the app's computeOAuth2CacheKey matches it byte for byte against the shared vectors in engine/tests/oauth_client_test.cpp. Expiry uses a skew of min(45s, lifetime/2), so a 30s token is reused for 15s; a missing expires_in means non-expiring. One refresh is in flight per cache key (#3344): however many sends, runs and POST /oauth2/token calls find the same token expired at once, the provider sees one grant_type=refresh_token post, and the others wait for it, each under its own timeout and cancel, and answer with the row it wrote. If that refresh fails (it timed out or was cancelled), a waiting call makes its own rather than reporting the other call's error. A refresh whose refresh token the provider refuses (invalid_grant or invalid_client; every other refresh failure keeps the row, see POST /oauth2/token) deletes the cached row only while the row still holds the refresh token that was refused, so a rotating provider's invalid_grant for a spent token never deletes the token that replaced it; an authorization_code user is not sent back to sign in by a race. A refresh that issues no new refresh token keeps the old one in the same write. A load run also refreshes its token during the run: a watchdog re-acquires a header-placed, expiring token oauth2RefreshLeadMs (default 60s) before it expires and writes the new one into this same cache row (see Load Test Mode). A collection load run does the same for the tokens its steps were planned with (#3199): one watchdog per distinct cache key, however many steps send it, and every such step sends the newest token from its first submission on. It is skipped - the token is fetched once and reused for the whole run - for a query-placed token, autoRefreshToken: false, a non-expiring token, an authorization_code grant with no refresh token, and a send that carries its own Authorization header, for which no token was fetched (#3202). That list is plan_oauth2_refresh's plus the header check (engine/src/http/auth_resolver.cpp); the app's isMidRunRefreshable mirrors all of it but the header case - change one, change both. A collection step is also skipped when its auth waited on its scripts, and when it writes the token under a different headerPrefix than the first step sharing its cache key (plan_scenario_auth_refresh, engine/src/core/auth_refresh.cpp).

POST /oauth2/token

Acquire (or return a cached) token for an OAuth2Config. Supports the client_credentials, password, and authorization_code grants; the authorization_code grant requires an interactive code exchange (see below).

Request:

{
  "config": { "grantType": "client_credentials", "accessTokenUrl": "https://idp/token",
              "clientId": "...", "clientSecret": "...", "scope": "openid" },
  "force": false,
  "interactive": { "code": "...", "codeVerifier": "...", "redirectUri": "..." }
}

force: true bypasses the cache (refreshes via the refresh token when present, else re-acquires). interactive is only used for the authorization_code grant, and it always exchanges the code and overwrites the cached row, whatever force says and whether the cached token is fresh, expired or refreshable (the old refresh token is not carried over).

Client credentials sent in the Authorization: Basic header are form-encoded before they are base64-encoded, as RFC 6749 section 2.3.1 specifies, so a secret holding +, / or = travels as %2B, %2F, %3D. A provider that expects them raw (as Postman and curl -u send them) needs credentialsPlacement: "body", which puts client_id and client_secret in the form instead. The default is basic_auth_header.

scope, audience and resource are sent in the form of a fresh grant when set; a refresh sends none of them. Three optional config lists add parameters of the user's own (issue #2536), each an array of {key, value, enabled, sendAs?}: tokenParams on a fresh grant, refreshParams on a refresh, and authorizationParams in the authorize URL's query (below). sendAs puts a row in the form (body, the default), the token URL's query (url) or a request header (header). A row is not sent when it is enabled: false, has no string key, has an unknown sendAs, or is named like a parameter the engine writes itself (grant_type, client_id, client_secret, code, redirect_uri, code_verifier, refresh_token, username, password, scope, state, code_challenge, code_challenge_method, response_type); a body or url row naming a form parameter already written (an audience the config sends) and a header row naming a header already set (Authorization, Content-Type, Accept, case-insensitively) are skipped too, so the engine's value wins and no name is sent twice. A malformed list or row is skipped, never refused. Values are resolved with the rest of the config, by POST /compose or after the pre-request script (see When it is applied), and a {{data.*}} token in one is refused like one anywhere else in the config.

Response (200):

{
  "cacheKey": "https://idp/token...",
  "accessToken": "ya29...",
  "tokenType": "Bearer",
  "scope": "openid",
  "expiresIn": 3600,
  "createdAt": 1234567890000,
  "expiresAt": 1234567893600,
  "hasRefreshToken": true
}

expiresAt is null for a non-expiring token; scope is omitted when empty. Errors carry an oauth2_* code: 400 invalid config, 401 oauth2_provider_error when the token endpoint answered without a token, 409 interactive authorization required, 502 network error, 504 oauth2_timeout when the token endpoint did not answer in time. A 401's message always names the endpoint's status (#3201): a 4xx JSON answer, or an RFC 6749 error under any status below 500, reads Token endpoint refused the request (HTTP 400): invalid_client (bad secret); a 5xx, or a body nothing could read, reads Token endpoint error (HTTP 503), with : unparseable response when the body was neither JSON nor a form. The provider's reply rides inside the error as providerStatus, providerError and providerErrorDescription, each left out when absent. A body that is not JSON is read as the legacy form-encoded token response only under an application/x-www-form-urlencoded, text/plain or absent Content-Type, and never when it opens with <, so a gateway's HTML page is not decoded as a form. The token request is bounded by the defaultTimeout setting (this route takes no timeout of its own), and the bound covers the whole acquisition: a refresh the provider rejects falls back to a fresh grant that gets only what the refresh left (issue #2833).

Only a refusal of the refresh token itself clears the cached token: a refresh answered 400 or 401 with an RFC 6749 error of invalid_grant or invalid_client deletes the row (while it still holds that refresh token) and falls back to a fresh grant, which for authorization_code is the 409 above. Every other refresh failure keeps the row, so the next call refreshes again (issue #3360). A refresh the endpoint could not answer - a 5xx, a 429, or a reply carrying no RFC 6749 error, an unparseable body included - is a 502 oauth2_network_error whose message reads Token refresh failed: Token endpoint error (HTTP 503): unparseable response, still carrying providerStatus and the rest of the provider's reply. Any other refusal of a refresh (invalid_scope, say) answers as the 401 oauth2_provider_error above. A fresh grant's failure is unaffected: it is always that 401. The same bound holds for the token exchange of the interactive flow below. A token response nested past 100 levels is treated as unparseable (401 oauth2_provider_error, "unparseable response"), never cached (issue #2413).

GET /oauth2/token?key=<cacheKey>

Inspect the cached token for a key (used by the UI status row). Always 200.

{ "found": true, "expired": false, "token": { "...": "serialized token" } }

Returns { "found": false } when no token is cached.

DELETE /oauth2/token?key=<cacheKey>

Clear a cached token. 200 { "deleted": true } (false if nothing was cached).

Interactive Authorization Code flow

For the authorization_code grant the engine owns PKCE (S256), the state value, and the code exchange; the app only opens the browser. In loopback mode the engine binds an ephemeral 127.0.0.1 listener; in embedded mode (providers that reject loopback redirects) the app captures the redirect URL and hands it back.

Method / Path Purpose
POST /oauth2/authorize/start {config, mode?} → {attemptId, authorizeUrl, redirectUri, expiresAt}
GET /oauth2/authorize/:attemptId Poll status → {state: "pending"\|"completed"\|"failed"\|"not_found", error?, cacheKey?}; reads only
POST /oauth2/authorize/complete {attemptId, callbackUrl} → status (embedded mode)
DELETE /oauth2/authorize/:attemptId Cancel → {cancelled: true}

The authorize URL carries response_type, client_id, redirect_uri, state, scope, audience, resource and the PKCE pair, then each authorizationParams row under the rules above, whatever its sendAs (a navigation has no body or headers); a row naming a parameter already in the URL is skipped.

An attempt times out 5 minutes after it starts. expiresAt is that instant in epoch milliseconds, the one deadline a client waits on. The engine enforces it whether or not anyone polls: within a second of expiresAt the attempt is failed with Authorization timed out and its loopback listener is closed, so an abandoned attempt never keeps its port. On success the token is written to the cache and cacheKey is returned. A settled result stays readable for 10 minutes from the start, then the attempt answers not_found.

GET /oauth2/authorize/:attemptId reads only: polling never settles, fails or tears down an attempt. An attempt past expiresAt reads as failed with Authorization timed out from that instant on, and a callback or completion arriving after it cannot change that.

At most 16 attempts may be unsettled at once, embedded ones included; the next start is refused with 429 oauth2_authorize_limit_reached. A settled attempt holds no listener and leaves the count.

Cancelling an attempt (DELETE), or the engine shutting down, cancels a token exchange still in flight for it, the loopback callback's and an embedded POST /oauth2/authorize/complete's alike: the callback's tab is told the exchange failed, and the completion answers 404. A completion (the loopback callback and POST /oauth2/authorize/complete alike) always exchanges its code and replaces any token already cached under that key.

The loopback callback reads nothing before state, error included: a request with a missing or wrong state answers 400 and the attempt keeps waiting, so an IdP that omits state on its error redirect leaves the attempt pending until it times out. A callback with the right state after expiresAt answers 410. A loopback attempt settles once, and the first settlement wins: a later callback with the right state answers 409 and changes nothing.

Local mock issuer

A built-in OAuth 2.0 issuer for developing and testing auth flows offline - no real identity provider, so no 2FA prompts, provider rate limits or "suspicious login" mail in the dev loop. Each issuer is an independent 127.0.0.1 listener serving /token and /authorize; point any OAuth 2.0 config's accessTokenUrl at the tokenUrl it returns.

It is not an IdP. JWKS/RS256, OIDC discovery documents, token introspection, consent screens and multi-tenant realms are deliberate non-goals.

Method / Path Purpose
POST /mock-issuer/start Start one → {issuerId, issuerUrl, tokenUrl, authorizeUrl, signingKey}
GET /mock-issuer List the running issuers
PUT /mock-issuer/:id Update failureMode / slowMs / expiresInSeconds live
POST /mock-issuer/:id/stop Stop one → {stopped: true} (404 if unknown)

Start body (every field optional):

{
  "port": 0,
  "expiresInSeconds": 3600,
  "claims": { "sub": "alice", "roles": ["admin"] },
  "clients": [{ "clientId": "cid", "clientSecret": "s3cret" }],
  "failureMode": "none",
  "slowMs": 2000,
  "issueRefreshTokens": true
}

port: 0 (the default) binds an ephemeral port; an explicit port another engine listener already holds is a 500 with code mock_issuer_bind_failed naming that listener, for the same SO_REUSEPORT reason the inbox refuses one. clients empty accepts any client id; with clients configured, an id must be one of them and, at /token, one carrying a secret must present it (Basic header or body - both RFC 6749 §2.3.1 placements); /authorize checks the id only. A field present with the wrong type or an out-of-range value is a 400 (mock_issuer_invalid_config) rather than a silent fallback to the default - a mock issuer running with an expiry other than the one asked for would defeat the purpose. At most 8 issuers run at once (429 mock_issuer_limit_reached).

The issuer's own endpoints:

  • POST /token - client_credentials, password, authorization_code and refresh_token grants, application/x-www-form-urlencoded as RFC 6749 §3.2 requires. Answers {access_token, token_type: "Bearer", expires_in, refresh_token?, scope?}. Authorization codes are single-use and expire after 5 minutes; a refresh grant rotates its token (the presented one is spent).
  • GET /authorize - auto-approves and 302s straight back to redirect_uri with code and state, so the interactive flow completes with zero human steps. PKCE is verified when a code_challenge is present; code_challenge_method must then be S256 (plain is refused rather than quietly accepted). An unknown client or a missing redirect_uri answers in place rather than redirecting (RFC 6749 §4.1.2.1).

The access token is an HS256 JWT signed with the per-issuer signingKey the start call returned - hand that key to the service under test as its shared secret and it can verify the mock's tokens. The payload is the configured claims plus iss, iat, exp and jti (these four always win, since they describe the token being issued), with sub, client_id and scope filled in only when the claims did not set them.

failureMode is what makes retry and error handling testable, and can be flipped on a running issuer with the PUT:

Mode /token answers
none Normally
slow Normally, after slowMs (at once when the issuer stops first)
server_error 500 {"error": "temporarily_unavailable"}
invalid_client 401 {"error": "invalid_client"}

Issuers bind 127.0.0.1 only - never configurable, because they mint bearer tokens and the engine has no route auth. State is in-memory: a restart forgets every issuer, and stopping one drops its codes and refresh tokens with it.

Execution

POST /compose

Compose a request without sending it: resolve {{variables}} and inherit auth engine-side and return the execute-ready payload that POST /execute and POST /runs accept unchanged (issue #226). Pure - no traffic, no run row - which is what lets a client (e.g. MCP's allowlist gate) inspect the resolved request before anything is sent. Composition is still the only place a payload is composed; a payload that skips it is sent byte-for-byte as supplied. Since issue #1008 the execution endpoints are not silent past that point either: a name composition could not answer keeps its braces (issue #1009) instead of resolving to "", and both POST /execute and a scenario step resolve it once more, after the pre-request script and before the send, against whatever the script just wrote. Since issue #2521 the same is true of every name a variable scope does answer, in a request that a pre-request script (its own, a folder's or the collection's) runs before: composition leaves it written and lists it in deferredVariables, because the script may change the value; a collection run's plan does the same in every step when any element in it writes a variable. A value composition did substitute is finished text and is never re-resolved - see POST /execute and Scenario runs for what that changes.

Request - at least one of requestId / request is required:

{
  "requestId": "req_1234567890",   // Optional: compose the saved request
  "request": {                      // Optional: an inline unresolved request
    "method": "POST",
    "url": "https://{{host}}/users",
    "headers": [{ "name": "X-Token", "value": "{{token}}" }],
    "body": { "mode": "json", "content": "{\"name\":\"{{name}}\"}" },
    "auth": { "mode": "inherit" },
    "elements": []
  },
  "collectionId": "col_1234567890", // Optional: chain scope for an inline request, echoed on the answer
  "environmentId": "env_1234567890", // Optional: environment scope
  "dataColumns": ["username", "city"], // Optional: bare names a bound row will substitute
  "deferDynamicVariables": true      // Optional: this payload is for a run that repeats it
}
  • dataColumns (issue #1007) names the columns of the data file a caller will bind a row from after this compose call - an array of column names, never values, since a plan is composed once and a row is bound per iteration. Every name it lists is left written as it stands, exactly as the reserved {{data.*}} namespace already is, for a later per-row bind to join - {{username}} behaves as {{data.username}} always has, deferred rather than resolved from a same-named variable. Absent or null means no dataset: composition resolves exactly as it did before this field existed. Refused with 400 invalid_compose_request when the field is present and not an array, or holds an entry that is not a string or is the empty string. A data.-prefixed entry is accepted but redundant - the reserved namespace answers that spelling first regardless of whether it is also listed here, so either way it is deferred. See {{data.*}} puts the row into the request itself and D18 for the precedence this buys.

  • deferDynamicVariables (issue #995) says this payload is being composed for a run, which will send it many times. A generator resolved here would be one value repeated by every iteration of every virtual user - the uniqueness {{$randomUUID}} is written for, lost exactly where concurrency makes collisions matter - so with the field true every name the dynamic table generates is left written as it stands, the way {{data.*}} and the identity names already are, and the run's executor generates a fresh value per occurrence immediately before each send. It also resolves an OAuth 2.0 config now, cache key included: a run acquires its token once, when it is planned, from the stored values (a script's write to an OAuth 2.0 variable has no effect under load), and every virtual user sends that one, so without the field (a Send) the config is left for the send to resolve after the pre-request script (see Authentication). Absent, null or false composes exactly as it did before this field existed, which is what a Send, a preview and a script's replaceIn want: composed once, sent once. Refused with 400 invalid_compose_request when present and not a boolean. Two limits worth knowing: an unknown {{$typo}} is unaffected (nothing would generate it either way, so it keeps its braces - issue #186), and a generator inside the auth block is generated here even when the field is true, because apply_auth encodes a credential when the request is built and a token left for the bind would go out as base64 of its own text. That is a generator's case alone: a credential carrying a {{data.*}} or a {{$vu}} defers the whole build and is bound before the encoding (issue #1055), and one carrying a name no scope answered defers it until after the pre-request script (#2473, see Authentication), where a generator has nothing to wait for. A scenario plan's steps are composed with it internally, so a collection run needs no field at all (a sequential run's steps keep their OAuth 2.0 config for after the script, as a Send does; a collection load run's resolve it at planning).

  • requestId composes the stored request wholesale: URL, headers (every enabled row with a key, in row order, as {name, value} lines - a repeated name repeated, each in the spelling typed, issue #2466), body, auth (absent auth defaults to inherit), the resolved elements list (collection chain root→leaf, then the request's own, each stamped with its origin, disabled and blank script.* entries dropped the same way - see Elements), the stored execution options (followRedirects / maxRedirects / httpVersion / verifySSL, always emitted; the request's own timeout, emitted only when it states one, so a request that states none sends with the defaultTimeout setting in force at the send, issue #2937), its Event stream setting as stream, always emitted (issue #3561: a caller that hands the payload to POST /execute gets 202 {runId, eventsUrl} for a streaming request unless it states stream itself) and its requestName (the script sandbox reads it as pm.info.requestName; omitted when the row's name is empty). The request's own collection scopes resolution; collectionId is only a fallback for a request without one. An unknown id is a definitive 404.

  • request is an inline unresolved request in the POST /execute body shape. Given alongside requestId, its fields lay over the stored ones before resolution - how an override like "retarget this saved request at another URL" works. Given alone, collectionId scopes the variable chain and the inherit walk. Unknown scope ids degrade to an empty scope rather than erroring - composition works with no collection or environment at all. That rule is for the app and direct callers: the MCP server checks an environmentId against GET /environments before composing and refuses one that names no environment (MCP).

deferredVariables

Composition decides from the composed elements (never from a flag the caller sends) whether a pre-request script runs before the send: an enabled, non-blank script.pre on the request, on a folder above it or on the collection, after an inherit.disable entry and a disabled-by-id entry have been applied and an inline elements array has been laid over the stored one. A script.setup does not count - it runs once, before a collection run's first step. When a pre-request script does run, every {{name}} that a variable scope answers is left written in the URL, the :name path rows, header names and values, body content and form-field strings, and the credentials of an auth block that is not OAuth 2.0 (an OAuth 2.0 config defers too on a Send and a sequential run, as Authentication describes), and the response lists the names in deferredVariables: a sorted array of the names as written, omitted when nothing was deferred. POST /execute and POST /runs resolve them after the script, against the variable scopes as the script left them, and ignore the member itself - it describes this answer, not the request, so a client that posts the composed payload onward may leave it or drop it (the app and the MCP server drop it). A request no pre-request script runs before is composed exactly as it was before issue #2521: no deferredVariables. A collection run's plan, which composes each step engine-side and returns nothing, defers the same names in every step of a plan in which any element writes a variable before some send, scripted or not (Scenario runs).

Four kinds of name resolve at composition whatever a script does, each exactly once:

  • the {{data.*}} namespace and the names listed in dataColumns, which the per-iteration bind answers;
  • a $ name - a dynamic variable (generated once here, or by the run's executor under deferDynamicVariables) or the iteration identity ({{$vu}}, {{$iteration}});
  • a name whose value, followed through the scopes, reaches a token the bind owns ({{user}} holding {{data.user}}), so the bind finds the token it needs;
  • a file path: the src of a form-data file part or a binary body file, which the later pass never resolves, so a script cannot choose which file is sent.

A name nothing defines stays written as it always did, and is not listed.

Deferral also moves refusals to the send. A header value or name that depends on a deferred variable cannot be checked here, so the refusals described under Errors below (unsendable_header, empty_header_name, invalid_header_name, colliding_header_names) are made by the residual pass at send time instead, in the same words and under the same codes: a buffered POST /execute answers statusCode: 0 with the code as refusalCode, and a streaming send answers a 400 carrying it.

collectionId on the answer

The answer names the collection whose chain this composition read, as collectionId: the leaf, so a sub-folder's id rather than its root's. That is the stored request's own collection for requestId, else the body's collectionId, and the member is omitted when composition read no chain: an inline request with no collectionId, or one naming a collection that does not exist or is in the Trash (issue #3461). Like deferredVariables it is composition's own answer, never taken from the input: a collectionId inside request is dropped, so an inline request cannot claim a scope composition did not read.

It is what lets an inline request keep its scope past composition. A request composed by requestId, or sent with one linked (the app's Send does both), carries the id onward and POST /execute reads the stored request's collection again; an inline one that links no row (MCP's ad-hoc run_request with a collectionId, a direct caller) has nothing else to name it, so without the member the names deferred past its pre-request script would meet no collection scope at the send, and the script would read an empty pm.collectionVariables. POST /execute and POST /runs read it as described under POST /execute. An engine older than issue #3461 neither writes nor reads it, and ignores it in a body.

Query encoding

With disableUrlEncoding off, a URL is sent as Postman sends it, by every writer: Send, a load or collection run, a streaming request, MCP and pm.sendRequest put out one request line for one URL (issue #2465, core::encode_url_as_postman in core/url_encoding.hpp, after postman-url-encoder 3.0.8's toNodeUrl). Each component is percent-encoded by its own Postman set, every one of which holds the C0 controls, space, DEL and every byte above ~ (each UTF-8 byte):

  • the path by PATH_ENCODE_SET, which adds ", <, >, backtick, { and };
  • the query by QUERY_ENCODE_SET, which adds ", ', < and > (a backtick, the braces and a backslash are not in it);
  • the fragment by FRAGMENT_ENCODE_SET, which adds ", <, > and backtick;
  • user info by USERINFO_ENCODE_SET, the path set plus / : ; = @ [ \ ] ^ |, with the last @ ending it.

Two normalisations come with it: a backslash before the query becomes /, and the host is lowercased and a non-ASCII one written by its punycode name (Non-ASCII hosts). Leading whitespace is dropped, as Postman's parser drops it. So GET http://H/a"b{c}?q='<x> goes to host h as GET /a%22b%7Bc%7D?q=%27%3Cx%3E, and GET http://h/a b?q=é as GET /a%20b?q=%C3%A9. % is in no set, so an escape such as %41 is sent as typed and nothing is encoded twice: a pre-signed URL's signature is sent unchanged, as is every byte no set holds (+, |, ^, [, ], !, ' outside the query). A {{token}} nothing answered is kept whole, where Postman would encode its braces in the path. The rule is applied where every driver takes its URL (wire_url) and at the end of composition, so POST /compose answers the line that will be sent. Every check made beside the transfer reads that same URL - the scheme rule, the reserved-port refusal, the DNS pin and the client-certificate match - so a leading space or a backslash cannot make the typed text name another scheme, host or port than the one dialled: localhost:9876/x with a leading space is refused as it is without one, and https://h/ with one pins and matches port 443. With disableUrlEncoding on the URL goes out exactly as typed (a non-ASCII host still by its punycode name), and libcurl refuses a raw space: the send fails with status 0 and error code INVALID_URL, and a message that names the space and the toggle (Cannot send this request: the URL contains a space or control character; percent-encode it, or turn Send URL without encoding off), derived from scanning the URL and not from libcurl's wording.

Where the engine itself writes a query pair into a URL, it uses Postman's rule (issue #1771, core::encode_query_component in core/query_encoding.hpp, pinned to the app's Params table by engine/tests/fixtures/query-encoding-conformance.json), read from postman-url-encoder 3.0.8's toNodeUrl over postman-collection's QueryParam.unparse:

  • Encoded as %XX (uppercase hex): Postman's QUERY_ENCODE_SET - the C0 controls, DEL, every byte above ~ (each UTF-8 byte), space, ", #, ', < and > - plus & in a key or a value and = in a key only (a value cannot split a pair, because a parser splits on the first =).
  • Everything else goes out as typed: +, |, /, ?, :, @, [, ], {, } and %, so an escape already in the text is never encoded twice. A whole {{token}} is kept verbatim, with the text around it encoded.
  • The writers are an apikey auth with in: "query" and an OAuth 2.0 token with tokenPlacement: "query" (a value a|b+c=d goes out as ?k=a|b+c=d; key= is written even for an empty value), and the join of a Postman import's query rows into the stored URL (POST /import/parse), which writes a row with an empty value as key= and a valueless: true row (Postman's "value": null) as a bare key. A request with disableUrlEncoding writes the pair as typed.
  • A value known only at send time is URL text, not a row: a {{variable}} substituted into the URL (by composition, a data row's bind, or the residual pass after the pre-request script). Postman substitutes into the URL string, parses it again and then encodes it, so a value's & and = split pairs as they would typed, a ? it brings into the head opens the query, and a # opens the fragment. Each component then encodes the value by its own Postman set (issue #2465): the query by QUERY_ENCODE_SET above, alike in a key and a value (the &/= step of a row never applies); the path by PATH_ENCODE_SET (see Path variables), so http://h/users/{{name}} with name = "John Doe" sends /users/John%20Doe; the fragment by FRAGMENT_ENCODE_SET (the C0 controls, DEL, every byte above ~, space, ", <, > and backtick). GET {{base}}/?q={{term}} with term = "a b#c" sends /?q=a%20b, with #c as the fragment (which is not sent), and ?{{qs}} with qs = "a=1&b=2 c" sends ?a=1&b=2%20c. Where a value lands is read left to right from the URL written so far, substituted values included: in the scheme and authority a / opens the path unless it follows a : or a / (so :// is not a path), the first ? opens the query, # opens the fragment. A layered value is resolved whole and encoded once. The scheme and the authority are never percent-encoded (the host is lowercased and written by its ASCII name, as above), so a {{base}} holding https://x/p?k=a b has its query part encoded and nothing else changed. disableUrlEncoding writes every value as typed.
  • A pair a script adds with pm.request.url.query.add, upsert or pm.request.url.addQueryParams is a row and is written by the row rule above (scripting).
  • A pm.sendRequest URL is encoded whole after its variables resolve, by the same encode_url_as_postman, and disableUrlEncoding does not apply to it (scripting). A script and Send write the same request line for every URL; tests/url_encoding_test.cpp (PostmanUrlEncodingAgreement) pins it.
  • OpenAPI, Insomnia and JMeter imports join with encodeURIComponent instead: the OpenAPI sync diff compares stored URLs against that form, and neither other source uses Postman's set.

URL schemes

Only http and https URLs are sent, on every send path: Send, a load or collection run, a streaming request, History replay, MCP, pm.sendRequest, an OAuth 2.0 token request, POST /import/fetch and the server-vitals monitor. The scheme is read case-insensitively from the URL as it stands just before the transfer - after composition, a data row's bind, the pre-request script and the residual pass, and as the transfer is handed it (Query encoding) - so a {{baseUrl}} that resolves to file:///etc is refused like a typed one, and so is file:///etc with a leading space. A refused send never reaches the network: status 0, error code INVALID_URL, and the message Cannot send this request: scheme 'file' is not supported - only http and https URLs can be sent, naming the scheme as written. A pm.sendRequest gets the same code and message as its callback's err.

A scheme is what libcurl reads as one: letters, digits, +, - and . after a leading letter, followed by :/. A URL with no scheme is sent as before, with the scheme libcurl guesses from the host - http for localhost:8080/x or example.com/x. Every transfer handle is also held to http,https (CURLOPT_PROTOCOLS_STR), which covers what the URL check cannot see: a guessed scheme (ftp.example.com/x would be FTP). It fails as status 0 with error code INVALID_URL and libcurl's own message (Protocol "ftp" is disabled), and nothing is read. A redirect's Location never reaches the handle's allowlist: the engine follows redirects itself and refuses a Location naming another scheme before making the hop, as status 0 with error code INVALID_URL and the message Protocol "ftp" is disabled (in redirect), worded as libcurl worded it. A Location that does not parse is INVALID_URL too, with The redirect target URL could not be parsed: and the reason. The libcurl the engine links carries every protocol curl builds by default, so the check and the option, not the build, are what restrict each transfer to http and https.

A URL libcurl cannot parse is also status 0 with error code INVALID_URL. When the URL the transfer was handed holds a space, a C0 control character or DEL, which is how one reaches libcurl once disableUrlEncoding is on (or a space sits in the host), the message says so instead of repeating libcurl's component wording (URL rejected: Bad query): Cannot send this request: the URL contains a space or control character; percent-encode it, or turn Send URL without encoding off. The last clause is left out when the toggle is already off, because it is no remedy. The scan is of the bytes, not of libcurl's text, and a malformed URL with none of them keeps libcurl's message.

Non-ASCII hosts

A host written with non-ASCII characters is dialled by its ASCII (punycode) name, on every send path: Send, a load or collection run, History replay, MCP, pm.sendRequest, an OAuth 2.0 token request and GraphQL introspection. https://bücher.example/ goes to xn--bcher-kva.example, which is the name DNS resolves, the Host header and TLS SNI carry and the server certificate is checked against. It is the name Postman sends to (url.domainToASCII, UTS #46 nontransitional processing): uppercase and full-width letters are mapped (BÜCHER, ABC), and ß is kept, so faß.de is xn--fa-hia.de, not fass.de. The stored URL keeps the spelling that was typed; a composed URL, and so pm.request.url in the request's own scripts, carries the ASCII name, because composition ends with the encoder the send uses (Query encoding).

The conversion is ada's, the WHATWG URL library Node's domainToASCII is built on, applied to the one URL every driver hands libcurl (which is built without IDN support), so it matches Postman case for case, the IDNA hyphen rules included: Node does not enforce them, so bücher-.example and ab--cd.bücher.example convert. The conversion rewrites only the host, and an ASCII host, an unresolved {{host}} included, is not converted; the rest of the URL is written as Query encoding says. The raw request a response carries shows the punycode name, because that is what was sent. Everything that compares a host beside the transfer uses the same name - the cookie jar, the DNS cache, the client-certificate registry, the proxy bypass list and a proxy URL - so a cookie, certificate or bypass entry written with either spelling applies to both.

A host with no ASCII name at all, such as xn--iñvalid.com (a punycode label that does not decode) or one holding a space, is refused before anything is sent: status 0, error code INVALID_URL, and a message naming the host. Postman sends such a host as typed and the lookup fails; libcurl without IDN would refuse it as "IDN support not present", which names the wrong cause.

Reserved local ports

No request the engine sends reaches Vayu itself: the engine's own port (the --port it bound, 9876 by default) and the MCP server's port (9877) are refused on this machine, on every send path - Send, a load or collection run, a streaming request, History replay, MCP, pm.sendRequest, an OAuth 2.0 token request, POST /import/fetch and the server-vitals monitor. The API's gate admits a loopback request with no Origin, which is exactly what the engine's own client sends, so without this a request in an imported collection could read and write everything the API holds (issue #2355).

"This machine" is any loopback spelling - 127.0.0.0/8 (127.1 and other shorthand included), ::1, ::ffff:127.0.0.1, localhost in any case with or without a trailing dot - and the unspecified 0.0.0.0 and ::, which connect to the local host. Every other port on loopback is sent as usual. The rule is applied twice:

  • The URL the transfer is handed (Query encoding), before anything is dialled: status 0, error code INVALID_URL, and the message Cannot send this request: Vayu does not send requests to its own engine port 9876 on this machine - not when the URL names it, a redirect leads there or a host name resolves there (MCP port 9877 for the other). This holds with a proxy configured too.
  • The address libcurl connected to, for every connection a transfer uses, before a byte of the request is written. This is what refuses a redirect to one of those ports and a name that resolves to loopback (*.localhost, a DNS record pointing at 127.0.0.1), with the same code and message. With a proxy in force the connected address is the proxy's, so this half cannot see the origin behind it; the URL check above still applies, and where a proxy you configured forwards to is your choice.

A $ref fetched through POST /import/fetch with reference: true runs a wider rule on the same connected-address check: every loopback and link-local peer is refused unless it is the source document's own host and port (issue #2364, see POST /import/fetch). It is added to the reserved ports, so a source on one of them does not open it. The rule passes the proxy the transport names and judges the reference's URL instead (issue #2605); the reserved ports do not: a proxy on one of them is still refused.

Path variables

A :name segment of the URL is answered by the request's own in: "path" Params row of that key (issue #1764) - the inline request.params when the inline request carries a params array, the stored row's otherwise (so an inline url override still reads the stored rows). This runs before the URL's own {{var}} pass, on the URL as written, and follows Postman's parse (postman-url-encoder/parser, postman-collection's Url.parse / Url.getPath):

  • A segment is a path variable when it is a whole path segment - after the authority, between / and the next /, ?, # or the end - that starts with :. The name runs to the first ., and a suffix after it stays (:id.json sends 7.json); : alone or :.x names nothing. A {{variable}} token is opaque, a backslash is a /, and a port (host:8080), the query and the fragment are never read.
  • Only an enabled row answers; among several rows of one key the last enabled one does. Postman's VariableList answers with the last row whatever its disabled flag, but Postman's editor has no toggle for a path variable; Vayu's does, and a disabled row answers nothing. A segment with no such row stays literal, which is also how every request stored before #1764 composes: a :x segment with no path row is sent as written.
  • The value is {{var}}-resolved exactly as the URL is, then written in place of :name percent-encoded as Postman encodes it: Postman joins the raw value into the path (Url.getPath) and encodes the path with postman-url-encoder's PATH_ENCODE_SET, which is the C0 controls, DEL and every byte above it (UTF-8, %XX with uppercase hex), space, ", <, >, `, #, ?, { and } - and nothing else. So a / in a value makes more segments (a b/c sends /users/a%20b/c), @ : , ; = & + ! $ ' ( ) * and % go out as typed (user@x.com, 12:30, 100%, and an imported a%40b.com is not encoded twice), and a ? or # is %3F / %23, so a value never ends the path. A whole {{token}} in the value is kept verbatim rather than encoded (see the next point).
  • A value that still holds a {{token}} after that resolution - a bound data column, a deferred {{$guid}}, a name a pre-request script sets - is not written yet: its segment stays :name in the composed url, and the row goes out in the composed payload's params as {"key": "id", "value": "{{username}}", "in": "path"}, its value resolved as far as composition could. Whatever answers the token later - the per-iteration bind, or the residual pass after the pre-request script - writes the answer into the segment through the same encoding, so a data cell a b?c goes out as /users/a%20b%3Fc, never with a raw space and a query. A token nothing answers is written verbatim, as composition keeps one. Until then a pre-request script reads pm.request.url with the :name still in it.
  • A value that resolves to the empty string leaves the segment literal (:id goes out as written), as Postman's Url.getPath (it writes only a non-empty string) and Insomnia's applyPathParametersToUrl both do.

The composed payload's url is the substituted URL, and its params holds exactly the path rows still waiting (absent when none is; an inline request's own params is consumed, never echoed). /execute, /runs and a scenario plan step (which is composed through this same path) read that params back and write each waiting value into its :name segment once it is answered, at the latest just before the send: a run with no residual pass writes it after the bind, or once at the start for a load run that binds nothing (a raw run naming an environmentId or requestId writes the values its start-of-run pass answered there, the rest after the bind). A caller posting its own params path rows to /execute or /runs gets the same writing.

What gets resolved: the URL, header keys and values, body content and fields, and every string inside the winning auth block - after inherit is walked (leaf→root; an explicit noauth terminates the walk, none is stepped over) and before any OAuth 2.0 cache key is derived from the config: the key is always computed from the resolved config, here for a run, after the pre-request script for a Send (below). A request no pre-request script runs before is resolved here, once. One that has one keeps what the script may change as {{name}}, as deferredVariables describes. Script text is never interpolated - a {{...}} in a script is user JavaScript. Resolution semantics (precedence, unknown names, dynamic variables, the D17 malformed-data rules) are specified in variable-resolution and pinned by the shared conformance fixture (engine/tests/fixtures/variable-resolution-conformance.json).

Response: 200 with the composed payload - the POST /execute body shape, with requestId / environmentId echoed so the result can be POSTed onward unchanged, the collectionId whose chain it read, and deferredVariables when a pre-request script defers names (above). An auth that resolves to "send nothing" is an absent auth field. headers always comes back as the line array (issue #2466), whichever shape an inline request used, so a repeated header survives compose to execute; it is absent when there are no lines.

Errors use the engine's single nested shape (see the top of this page), with specific codes:

  • 404 {"error": {"code": "request_not_found", "message": "..."}} - unknown requestId.
  • 400 {"error": {"code": "invalid_compose_request", "message": "..."}} - malformed JSON, neither requestId nor request, or a field of the wrong type.
  • 400 {"error": {"code": "unsendable_header", "message": "..."}} - a variable substituted into a header name or value, or into a credential the engine writes into a header line as it stands (a bearer token, an api key sent in a header), carries a byte no header line can hold. Basic auth's pair and an api key sent in the query are encoded before they reach the wire, and an OAuth 2.0 config is not a header, so a variable in those composes unchanged. This is the one payload composition rejects over a value rather than over its shape, and it is deliberate: a header line ends at CRLF and has no escape for it, so ok\r\nX-Admin: true arriving from an environment variable does not sit in the header - it ends the line and makes the remainder a header nobody wrote. The message names the variable, because composition is the last layer that knows which one carried the byte. A NUL is refused with it: the engine spells a header key + ": " + value for curl_slist_append, which reads to the first NUL, so the rest of the line would go out missing rather than refused. The same bytes remain ordinary text in a URL, a body and a form field's value, which compose unchanged. For a request a pre-request script runs before, a variable written into a header or a header-line credential is not substituted here (see deferredVariables), so the same refusal, naming the variable, is made after the script: statusCode: 0 and refusalCode: "unsendable_header" on a buffered send, a 400 with that code on a streaming one. A header row is refused with nothing rewritten first.

A header carrying either byte from any other origin - a script's assignment to pm.request.headers, a credential typed with the byte in it, an import, a payload posted straight to POST /execute - is refused one step later, before any transfer starts: the response carries statusCode: 0 and an errorCode of INTERNAL_ERROR whose message names the header instead of a variable. The same refusal covers a multipart part's field name, declared filename and per-part content type, which libcurl writes into that part's own header block. A bound {{data.column}} is refused earlier still, at bind time, naming the column and the row (see Scenario runs). - 400 {"error": {"code": "colliding_header_names", "message": "..."}} - two header names written differently resolved to one, so the request would send that header twice where its rows show two different names. {{tenant_header}}: acme beside a literal X-Tenant: legacy is two X-Tenant lines once the variable answers X-Tenant, and no row says so. Names are compared without case, so a {{h}} resolving to authorization refuses beside an Authorization the caller typed. The message names both spellings as written, never the name they produced (a variable can hold a secret); nothing is repaired, for the reason a forged header is refused rather than stripped.

Only a collision resolution produced is refused. Two names the caller wrote alike - X-Dup and x-dup typed on two rows, or one {{h}} typed twice - are a repeated header they can see, and every one of those lines is sent, in order (issue #2466) - the same distinction the bind-time refusal draws (see Scenario runs). The execute-time residual pass refuses the same collision in the same words, since it resolves names the same way: a buffered send answers statusCode: 0 with an errorCode of INTERNAL_ERROR carrying the message and this code as refusalCode, exactly as the pre-send gate answers its own refusals, while a streaming send - which has not answered yet - is a 400 with this same code and fails its run row. A script's own pm.sendRequest refuses it as well, with the call named in front of the same wording, because it too resolves header names (issue #1067). - 400 {"error": {"code": "empty_header_name", "message": "..."}} - a header name resolved to the empty string, so the line would go out under no name at all. {{blank}}: acme with blank holding "" is not a header the caller can see: the name is empty, and what libcurl is handed is the line ": acme". A name of nothing but spaces and tabs counts as empty: it is trimmed to nothing first (see invalid_header_name, below). Nothing further down refuses it - the pre-send gate reads a header's text for the bytes that end a line early, and an absent name ends nothing - so composition is where it is caught. The message names the name as written, which is all there is to name; what it produced is nothing.

Refused however the name got there, unlike the collision above. A collision has to be one resolution produced, because two names the caller typed are two entries they can see; a name that is not there is nothing to see whoever wrote it. Both flattenings that feed composition drop such a row before it arrives - a stored request's headers and the app's - so what this catches beyond a produced name is a payload built by hand. The execute-time residual pass refuses it in the same words and under this same code, in each of the two shapes it answers a refusal in (above), and for this rule it reads every header name rather than only the ones still holding a token (issue #1095) - so a name a pre-request script has just emptied and an empty key posted straight to POST /execute are refused there as well. The collision rule keeps the narrower reach and loses nothing by it: a request that arrives already resolved cannot carry a collision, two names that are already equal being already one key. pm.sendRequest has refused it since its own header names began resolving, with the call named in front of the same wording, and a data row that binds a name away is refused at bind time with the row in front of it (see Scenario runs). - 400 {"error": {"code": "invalid_header_name", "message": "..."}} - a header name that is not an RFC 9110 token once the spaces and tabs around it are trimmed (issue #2467): X Bad (an interior space), X:Bad (a colon), X-é (a byte outside ASCII). The message quotes the name as written - {{h}}, not what the variable resolved to, which can be a secret - and says which character cannot appear in one. Nothing is rewritten into a different header: the trim below is for padding, which has one reading, and this refusal is for what has none. The same refusal, under the same code, answers a headers name posted to POST /execute or POST /runs and the execute-time residual pass (a buffered send answers statusCode: 0 with INTERNAL_ERROR, a streaming send a 400, as above), which is where a name a pre-request script defined, or one a script's variable completes, is judged; a script's pm.sendRequest and a data cell bound into a name refuse the same way, with the call or the row in front of the wording. A {{token}} nothing answered is not judged, since like every unanswered token it is sent as written, but the text around it is: X-{{a}}-b passes, X Bad {{x}} and Evil: injected{{ (a {{ that closes no token is ordinary text) are refused, quoted as written.

Header names are trimmed, then checked. A name loses the spaces and tabs (SP and HTAB, nothing else) at either end before it is checked or sent, wherever it enters: a stored request's header rows, a composed or resolved name, and the headers of POST /execute and POST /runs. Authorization therefore goes out as Authorization, not as the line Authorization : Bearer x with a space before its colon. A row whose key is only padding is no row, as an empty key always was. A value is not trimmed. Two lines written X-A and X-A are a repeat the caller typed, sent as two lines, not a collision. In the object form of headers two keys that differ only by padding or case fold to one line (the last value wins), because an object has one slot per key; the array form sends both.

POST /execute

Execute a single HTTP request (Design Mode). Returns immediate response with test results.

A body nested deeper than 128 levels in any field answers 400 request body is nested deeper than 128 levels (code bad_request) before anything is recorded or sent (issue #2417). The one exception is a data cell, held to its own bound of 100 below.

The request's auth (see Authentication) is resolved before the pre-request script runs, so pm.request reflects the real outgoing headers - unless a credential still holds a name that waits for that script (one compose could not answer, or any name of a request a pre-request script runs before), when it is applied after that script instead (#2473, #2521). If a non-interactive OAuth 2.0 token cannot be obtained, the engine still returns 200 but the body carries statusCode: 0, an errorCode of AUTH_REQUIRED (interactive sign-in needed) or AUTH_FAILED, and an authErrorCode hint. The hint is the same whether the token was sought at the build or, for a config that waited for the script, after it.

A name still written after compose is resolved after the pre-request script and before the send (issues #1008 and #2521). Composition still runs first and is still the only place a payload is composed. Two kinds of name reach this pass: an unknown ordinary {{name}}, which keeps its braces at compose time instead of becoming "" (issue #1009), and, in a request that a pre-request script (its own, a folder's or the collection's) runs before, every name a scope answers, which compose leaves written and lists in deferredVariables. Either is resolved here against the variable scopes as the pre-request script left them, and there is no flag for the caller to set: the braces in the payload are the whole signal. This is what makes the canonical imported auth pattern work: a pre-request script does pm.environment.set("token", …) and the same send's Authorization: Bearer {{token}} carries the fresh value - on every run, not only the first, which is Postman's order - rather than the previous run's token or "". In a pre-request script, pm.request.url and pm.request.headers therefore still hold the {{token}} as written, and resolve after the script ends. A credential that waited (above) is applied once this pass has answered, against the same scopes, so a basic pair carries the value a script set rather than base64 of its token. It resolves the same fields composition does - the URL, header names and values, body content, and the five strings a form field carries, plus the value of a :name path variable composition left waiting (written into its segment, encoded, as the pass ends; see Path variables) - by the same resolver and the same rules (scope precedence, nested resolution, cycles, the 8-level bound); a value composition already substituted is finished text and is not touched again. {{data.column}} is left alone here too - the data namespace is bound per iteration by whoever owns the row. A request skipped by pm.execution.skipRequest() resolves nothing, having nothing left to send. A header value or name this pass resolves is checked by the rules compose applies, before anything is rewritten, and a refusal is answered with statusCode: 0, the sentence in errorMessage and the rule's code in refusalCode (unsendable_header, empty_header_name, invalid_header_name, colliding_header_names, and the two codes of targetPolicy below); a streaming send answers a 400 under the same code. The member is absent on any other answer. A preview, a tab title, the unresolved-token painting and "Copy as cURL" show what compose returned, so for a scripted request a preview shows {{token}} where the wire will carry the value the script set (the Code section says so). A load run runs this pass per submission only where it has one (a collection load run's steps, a single-request run that declares requestElements), and under load it never refuses: see Authentication and Scenario load runs.

Request:

{
  "method": "POST",
  "url": "https://api.example.com/users",
  "headers": [                         // Optional, the lines to send, in order - see below
    { "name": "Content-Type", "value": "application/json" }
  ],
  "body": {
    "mode": "json",
    "content": "{\"name\":\"John\"}"
  },
  "requestId": "req_1234567890",      // Optional, links to saved request
  "requestName": "Create user",       // Optional, read by scripts as pm.info.requestName
  "environmentId": "env_1234567890",  // Optional, uses environment variables
  "collectionId": "col_1234567890",   // Optional, the collection scope of a request no row names - see below
  "timeout": 30000,                    // Optional, ms, 1-86400000 - see below
  "elements": [                        // Optional, typed behaviours - see Elements. The only
                                       // script source; preRequestScript/postRequestScript(s)/tests
                                       // are refused (400, naming "elements"), and so is a list
                                       // the element registry refuses - see below
    { "kind": "script.post", "config": { "script":
      "pm.test('Status is 200', () => pm.expect(pm.response.code).to.equal(200));" } }
  ],
  "allowScriptRequests": false,        // Optional, default false - see below
  "followRedirects": true,             // Optional, default true
  "maxRedirects": 10,                  // Optional, default 10
  "verifySSL": true,                   // Optional, default true - stored per request and
                                       // settable in the request builder's Settings tab
  "httpVersion": "auto",               // Optional: "auto" | "http1.1" | "http2", default "auto"
  "transient": false,                  // Optional, default false - see below
  "persistVariables": true,            // Optional, default true - see below
  "includeParsedBody": true,           // Optional, default true - see below
  "origin": { "kind": "app" },         // Optional, who started the run - see below
  "targetPolicy": {                    // Optional, the hosts this send may reach - see below
    "allowAll": false, "allowedHosts": ["api.example.com"]
  },
  "stream": false,                     // Optional, default false - see below
  "maxStreamDurationMs": 600000,       // Optional, streaming only - see below
  "maxStreamEvents": 100000,           // Optional, streaming only - see below
  "data": { "id": "7" },               // Optional, one data row - see below
  "disabledDefaultHeaders": [],        // Optional, headers Vayu adds that this send refuses
  "disableCookies": false,             // Optional, default false - stored per request, see below
  "disabledSystemHeaders": [],         // Optional, default [] - stored per request, see below
  "disableUrlEncoding": false,         // Optional, default false - stored per request, see below
  "bodyModeHeaders": ["Content-Type"]  // Optional, which `headers` the body mode wrote - see below
}

headers is the request's header lines, in send order (issue #2466): an array of {"name", "value"} objects, each sent as its own line in the order given and in its own spelling, so a name may repeat (Link, Forwarded, two Accept rows, X-Dup beside x-dup) and the authored order is the wire order. The older object form ({"Accept": "application/json"}) is still accepted and behaves as it always did: one line per key, so it cannot repeat a name. A line without a string name and a string value, or headers of any other type, is a 400. A name is trimmed of the spaces and tabs around it and what is left must be an RFC 9110 token: one that is not (X Bad, X:Bad, X-é) is a 400 with code invalid_header_name quoting the name, in either shape and before any run row exists (a name still holding a {{token}} waits for the residual pass below, which judges it once resolved); a name of only padding is the empty name the residual pass refuses (empty_header_name). The refusal and the trim are the ones POST /compose documents. POST /runs reads the same field the same way, and refuses a single-request run's bad name with the same 400 before the run row exists. What the engine adds (an auth header, the body-implied Content-Type, the defaults) is added only under a name no line already carries, compared without case; a typed Authorization sent twice is sent twice and auth adds none.

timeout is the whole-transfer deadline in milliseconds (issue #1917), held to 1-86400000 and defaulting to the defaultTimeout setting when absent or null. A stored request's own timeout (issue #2937) reaches this field the same way: POST /compose by requestId writes it into the payload only when the request states one, so a composed send takes the inline overlay's timeout, else the stored request's, else the setting. A number outside that range, or a value that is not a number, is a 400 naming 'timeout' before any run row exists and with nothing sent: libcurl reads 0 as "no timeout", and a negative value is a rejected option the transfer then runs without. POST /runs holds the same bound (see its run config table). Connecting (TCP and the TLS handshake) is additionally capped at 30 seconds (issue #2835), so a timeout above that does not extend how long a dead target is waited on. A streaming send does not apply it to the transfer (see stream below) but refuses a malformed one all the same. In a load run the latency histograms hold one hour at most (issue #2790): a completion longer than that, a timeout above 3600000 that ran out, is counted at one hour, so a percentile or max it reaches reads about 3600000 ms (within 0.1%) rather than the true duration, and the sample is never left out. The same deadline bounds the OAuth 2.0 token request an auth block makes (issue #2833), a refresh, the wait for another call's refresh of the same token, and the fresh grant a rejected refresh falls back to counted together: a token endpoint that does not answer within it fails the send as AUTH_FAILED with authErrorCode oauth2_timeout, and the request itself is never sent. It is also the default timeout of every pm.sendRequest the send's scripts make, buffered or streamed; a call's own timeout option replaces it, and the script's remaining budget can only lower either (Scripting).

requestId, environmentId and collectionId must be strings (issue

1917, collectionId since #3461): an id of any other JSON type

("requestId": 7) is a 400 naming the field - 'requestId' must be a string (got number) - before any run row exists. Absent and null mean no link. POST /runs reads the same three fields under the same rule.

The collection scope of a send is decided once (issue #3461): the collection of the request row requestId names, when there is a live one, and otherwise collectionId, the member POST /compose writes on an inline request's answer - composition's own precedence, so a request field and a script read one chain. Its chain is what the pre-request and post-request scripts read and write (pm.collectionVariables answers the leaf's names and its ancestors', and a set() is stored on the leaf alone, never on an ancestor), what the names deferred past the pre-request script resolve against, and what the run's configSnapshot is masked against. An id naming nothing, unknown or in the Trash since composition, is an empty collection scope and the send goes out, never a refusal, as composition treats it. The field rides into configSnapshot with the rest of the payload, which is how a stored run records the scope it sent under.

disabledDefaultHeaders refuses what the engine would add (issue #1229). The engine adds a small declared set to every request that does not name it - see Default request headers - and a testing tool has to be able to send exactly the request that was written, including one with no User-Agent at all. Names are matched case-insensitively; the field is accepted on POST /execute and POST /runs alike. A value that is not an array of header names is a 400 naming the field, because a malformed opt-out would otherwise read as one that did nothing. A name matching no current default is accepted and does nothing: config can switch a default off between the moment a client read the declared set and the moment it sends. A name is checked as a header token only, so User-Agent, Accept-Encoding and Content-Type are all accepted (until issue #1765 the correlation-id validator refused those three with a 400).

disableCookies / disabledSystemHeaders / disableUrlEncoding are the request's stored Postman protocol settings (issue #1765; see POST /requests). POST /compose always emits them from the stored row and the app always sends them, on POST /execute and POST /runs alike, because each defaults to off: an omitted true would send the jar, the header or the encoding the user turned off. disabledSystemHeaders is unioned with disabledDefaultHeaders, which stays the per-send, never-stored opt-out, and is refused on the same shape rules. disableCookies takes the jar off the buffered and the streaming send and off a scenario load run's per-virtual-user session (the step neither sends nor updates it); a single-request load run never tracks cookies at all.

bodyModeHeaders names the headers the body mode wrote (issue #1765): the header names whose last row carried "source": "body-mode", compared without case. A headers line has no room for the marker, so POST /compose emits this list from a stored request's rows (only when it names something) and the app sends it beside an inline request's headers; inline headers replace the stored ones, so the stored list is dropped with them. A name in it that disabledSystemHeaders or disabledDefaultHeaders refuses is left off the wire, as Postman leaves off the body's Content-Type as a system header; a name not in it is the user's and is sent. A value that is not an array of strings is a 400.

stream consumes a text/event-stream response live (issue #573) instead of buffering it. It changes the execution model, so it is declared rather than detected: the engine creates the run row, hands the transfer to a managed consumer worker, and answers 202 at once with the run and the URL its events arrive on. Nothing about a non-streaming send changes.

{
  "runId": "run_1234567890",
  "eventsUrl": "/runs/run_1234567890/events",
  "status": "running"
}

The worker parses SSE frames into a bounded in-memory ring that GET /runs/:runId/events relays, and writes a bounded events node into the run's stored trace when the stream ends, so History restores the timeline. The cookie warnings a buffered send answers with (issue #3315) are written to the same stored trace, at its top level; the 202 carries none.

What the reply's bytes become depends on the final response's Content-Type (issue #3238), read per redirect hop, compared without case and without its parameters. A text/event-stream reply's bytes are its events and the stored response.body stays empty. Any other reply (a JSON 404, NDJSON, chunked text) also keeps its bytes as response.body, up to maxDesignResponseBodyBytes, the bound a buffered send reads under. Past it the body is a prefix and the trace says so with bodyCapped: true, as on a buffered send; the stream itself still ends only by the rules below. Such a reply is still fed to the SSE parser, so a server that streams SSE under the wrong type still delivers its events. Either way the stored response carries bodyBytes, the body bytes the server delivered, whatever was kept: the relay carries no body, so the stored trace is where it lands.

A UTF-8 byte-order mark at the very start of the stream is dropped, as the EventSource specification requires (issue #1917); without that the first line's field name would carry the mark and the first event would be lost. One mark is dropped, however its three bytes are split across reads, and only at the start.

Every stream ends, and the run says why. Seven terminations, never "the timeout happened to fire":

Reason What happened
completed The server closed the stream
stopped POST /runs/:runId/stop
shutdown The engine shut down under the stream (POST /shutdown or a signal), which no user asked for (#3342). The run ends stopped, as a load run still sending does; this reason is what tells it from a user's Stop
maxStreamEvents The event cap was reached; the list ends exactly at the cap, however the server packed events into writes (an unterminated event behind the last one is not flushed)
maxStreamDurationMs The duration cap elapsed, counted from the first hop of a redirect chain
idleTimeout Nothing arrived for sseIdleTimeoutMs on a made connection; a header line counts as arriving, and each redirect hop's own connect is bounded by the connect deadline below, not counted as silence. The stream ends within a couple of seconds of the setting (the engine checks about once a second)
error The transfer failed (a refused or timed-out connect, TLS, a protocol error, a redirect the chain refused); the run ends failed with the error fields set. Also what an end nobody recorded reads as, which the engine logs, since it is not known to be a completion

The whole-transfer timeout is deliberately not applied to a stream - it would kill a healthy one mid-flight. Two deadlines apply instead: connecting (TCP and the TLS handshake, on every redirect hop) is bounded by the smaller of timeout and 30 seconds (issue #2835), and once connected the idle one bounds silence; the two caps above are what bound a stream that talks forever. A connect that runs out ends the stream as error with errorCode TIMEOUT, as a refused connection does, never as idleTimeout. maxStreamDurationMs (1000–86400000) and maxStreamEvents (1–10000000) override the configured defaults per request; sending either without "stream": true is a 400, since a cap that quietly did not apply is worse than no cap.

Refused with a 400 rather than silently reinterpreted:

  • a non-boolean stream ('stream' must be a boolean);
  • "stream": true with "transient": true - a stream is its run row: the row is what eventsUrl names, what carries the status, and what a stop finds, and a transient execution creates none.

Scripts run on a streaming request (issue #575), and were refused until they did. The pre-request script runs before the transfer starts, exactly as on a buffered send, so its pm.request edits reach the wire. The post-request script runs once, after the stream has terminated, and reads the bounded stored list as pm.response.events with pm.response.totalEvents and pm.response.eventsTruncated beside it - a script runs to completion, its timers included, before anything is reported, so a live per-event callback is not a feature that was skipped but one the runtime cannot have. See Scripting.

Because the route has already answered 202, a streaming run's script output has nowhere to be returned: the trace's scripts node is the only route it takes. That node is not a streaming feature - every design send stores it (issue #725), with the same four keys the buffered response body carries (testResults, consoleLogs, preScriptError, postScriptError). One engine object fills both, so a live pane and a restored one cannot disagree. A run whose scripts said nothing stores no node at all.

Tuning: sseMaxRetainedEvents, sseMaxEventBytes, sseMaxStoredEvents, sseMaxStreamDurationMs, sseMaxStreamEvents and sseIdleTimeoutMs (see GET /config).

transient runs the request without recording it (issue #382). The execution is otherwise identical - same composition, the cookie jar named by environmentId, the same scripts, the same response body - but the engine creates no run row: nothing appears in GET /runs, no result trace is written, and the count-based retention prune does not run, so no existing run is evicted. Because the trace is where the post-auth request headers would have landed, a transient execution is also the only way to send with resolved credentials and leave none of them on disk.

Absent and null both mean false; a present non-boolean is a 400 ('transient' must be a boolean) rather than a silent false, because a caller that asked for privacy must not be quietly refused it. The flag is not valid on POST /runs - a load or scenario run is the row it creates (the run id is the endpoint's return value), so sending it there is a 400 with errorCode: "invalid_run_config".

The one caller today is the app's GraphQL schema introspection (lib/graphql/introspect.ts), a background fetch the user never made. MCP's run_request deliberately does not set it: an agent's runs belong in History like anyone else's, and the tool builds its payload from named arguments, so an agent cannot supply the flag either.

origin says who started the run (#1817): {"kind": "app" | "mcp" | "other", "client": "<name>"}, stored on the run row (runs.origin / runs.origin_client, see the runs table) and returned on every run shape - GET /runs rows, GET /runs/:runId and PUT /runs/:runId/baseline - as origin: {kind, client}. It is client-asserted metadata, not identity: any caller can claim any kind and nothing authorises on it; History reads it to say which runs an agent started. The app sends {"kind": "app"}; the MCP server sends {"kind": "mcp", "client": "<clientInfo.name>"} with the name its client gave in the initialize handshake.

  • Absent or null stores other with no client. other is also what every run recorded before the field existed reads as.
  • client is kept for mcp only and dropped for app and other. It is trimmed of whitespace and cut to 128 characters (on a character boundary, never inside a UTF-8 sequence); one that is empty after trimming stores no client. Otherwise it is stored exactly as sent: turning an identifier into a product name is the client's job, so a new MCP client needs no engine change.
  • A non-object origin, a kind outside the three (a missing one included) or a non-string client is a 400 naming the field, for example 'origin.kind' must be one of app, mcp, other, before any run row exists and with nothing sent. A transient send reads and validates it the same way and stores nothing.
  • The object is kept out of config_snapshot: the row's two columns are its one record.

POST /runs takes the same field under the same rules.

targetPolicy holds the send to the hosts its caller allows (#2521): {"allowAll": boolean, "allowedHosts": string[]}, both members optional. The MCP server checks its allowlist against the composed URL, but a pre-request script can assign pm.request.url or set the variable a deferred {{host}} resolves from, so the caller also hands the engine the rule and the engine applies it to what it is about to send. It is the caller's session rule, changing per request, and rides on the payload rather than in config.

  • What is judged. The host of the URL as it will be dialled (the wire URL, after the pre-request script, the residual pass and the URL encoding), and, before any token is read from the cache or fetched, the host of an OAuth 2.0 config's accessTokenUrl and refreshTokenUrl (whichever are set, both whether or not this send would reach the refresh one, so the answer does not depend on what the cache holds), each also as the token request will dial it (#3162), so http://evil.example\@idp.example/token is judged as evil.example. A script can set an accessTokenUrl as easily as the request's URL, and the token request carries the client secret; a refused target fetches no token.
  • The match is the MCP server's: the hostname as a WHATWG URL parser reports it (no port; an IP literal in its canonical spelling, an internationalised name by its punycode form), compared exactly with each allowedHosts entry once that is trimmed and lower-cased. There is no wildcard. allowAll: true passes any host that can be determined. A host that cannot be - an empty one, or one still holding a {{template}} nothing answered - is refused whatever the policy says. {} allows no host.
  • A refusal never reaches the network. A buffered send answers statusCode: 0, an errorCode of INVALID_URL, the sentence naming the host in errorMessage, and refusalCode target_not_allowed (a host the policy does not list) or target_host_unknown (no determinable host); an OAuth 2.0 token endpoint it refuses at the build is answered the same way, and not as an auth failure. A streaming send answers a 400 carrying the same code before its stream opens.
  • A malformed policy - not an object, an allowAll that is not a boolean, an allowedHosts that is not an array of strings, or any other member (so a misspelt allowedHost cannot quietly allow nothing) - is a 400 with code invalid_target_policy, before anything is recorded or sent. Absent or null, a send reaches whatever its request names.
  • It is never stored. The top-level member is dropped from a run's config_snapshot (as origin is), and a run holds it in memory only.
  • What it does not cover: the hops of a redirect a server answers with, and the requests a script makes with pm.sendRequest.

POST /runs takes the same field; see there for how a collection or load run is held to it.

data binds one row to this send (issue #601). It is the single-send half of a run's scenario.data: every {{data.column}} in the URL, the header names and values, the body and both halves of every form field is substituted against it, and both scripts read it as pm.iterationData with pm.info.iteration 0 and pm.info.iterationCount 1 - the send is row 0 of 1. Without the field nothing changes: {{data.*}} goes out written as it stands and pm.iterationData is undefined.

The row's own keys are also its bound bare names (issue #1007): the send derives its dataColumns set from data's keys itself, so a bare {{username}} binds from the row exactly as {{data.username}} does, at the same precedence D18 gives it. A bare name the row does not carry is not deferred in the first place - it is an ordinary {{name}}, resolved from the scopes at compose time or, if nothing there answers either, by the residual pass after the pre-request script (issue #1008).

An object of name/value pairs, never the array a run sends - one row. The row is bounded by maxScenarioDataBytes (the same setting a run's whole set is measured against) and composes freely with transient and stream: a streaming send binds the row before the transfer opens, so the URL and headers it opens with are the bound ones.

Refused with a 400, before any run row exists and with nothing sent:

What Message
data is not an object 'data' must be an object of name/value pairs (got array). A single send binds one row; a set of rows is a collection run.
over the byte cap 'data' is N bytes, over the limit of M (raise the 'maxScenarioDataBytes' setting to allow more)
a column nested deeper than 100 levels 'data' column 'name' is nested deeper than 100 levels - refused before the row is measured (issue #2362); a column nested exactly 100 levels is accepted
a token names a column the row lacks the binder's own sentence, naming the token, the row and the row's columns
a null cell, a header collision, a header name bound to nothing, an unwritable XML placement the binder's own sentence - identical to a run's, see Scenario runs
an OAuth 2.0 config carries a {{data.*}} token Auth credentials carry {{data.client}} in an OAuth 2.0 configuration, and no row can reach it: ...

Credentials bind here too (issue #642). A {{data.user}} in a basic-auth username, a bearer token or an api key is substituted from the row like any other field, and it is bound before the credentials are encoded - so basic auth base64s the row's values, and an api key in the query is encoded by the query rule after the substitution rather than before. This is the same deferral a collection run performs per iteration (issue #591): the credentials are parsed and kept typed, the request is built without resolving them, and the auth is applied once the row has reached it.

OAuth 2.0 is the one mode a row cannot reach, and it is refused by name rather than sent wrong. Its token is acquired against the token endpoint instead of being written into the request, so there is no moment at which a bind could happen - exactly the reason a scenario run refuses the same config. Use a static credential there, or move the data token into the request itself.

requestName is script identity, not an HTTP field - it never reaches the wire. The scripts read it as pm.info.requestName (with requestId as pm.info.requestId); a client sends it because Send executes editor state, which may be unsaved and therefore have a name no stored row carries. Absent, the engine falls back to the name of the row named by requestId, so linking an id is enough. An empty string is treated as absent - a script reads undefined rather than "" - and a non-string is a 400 ('requestName' must be a string). See scripting.md.

allowScriptRequests lets this payload's scripts use pm.sendRequest. Absent, null or non-boolean all mean false, and that default is a security control rather than a convenience (issue #302): Vayu's MCP target allowlist is checked in the MCP server, before it calls this endpoint, and held by the engine to the URL a send is about to dial (targetPolicy), so a request issued from inside a script with pm.sendRequest never passes either. Denying unless a caller asks means a client that forgets gets a script that cannot send rather than unchecked egress. The app's Send and load runs send true; the MCP server never does. POST /runs reads the same field for a script.post element's deferred validation (its requestElements, below), so one script behaves the same on both. Read before the stream branch, so a streaming send's scripts are governed by it exactly as a buffered send's are - the app sends it on both halves of Send (issue #653). See scripting.md.

elements is the only script source, and it runs (issue #1514's cut-over, replacing #1513's preRequestScript(s) / postRequestScript(s)). A caller still sending any of preRequestScript, preRequestScripts, postRequestScript, postRequestScripts or tests - even naming one with null is accepted as a no-op, but a real value is not - is refused with a 400 naming elements as the replacement, before any run row exists. For the by-id path, an element list a caller supplies inline is laid over POST /compose's own resolved chain (collection root to leaf, then the request's own, minus anything disabled or named by an inherit.disable entry, each stamped with origin: {kind: "collection" | "request", scope, id, name?}) exactly as any other inline field overlays the stored one; an inline-only send has no chain to resolve one from, so its elements carry no origin. scope is collection for the root, folder for every collection below it and request for the request's own (#2522); kind keeps its two values. It is what each script result's scope (below) is read from, falling back to kind for an origin that carries none.

elements is validated like a stored request's (#3052): a list the element registry refuses (an unrecognized kind, a setting the kind does not declare, a pattern that does not compile, an assertion with nothing to compare against, a repeated id, a script.setup on the request, a value that is not an array) is a 400 carrying the message POST /requests answers for the same list, before any run row exists and with nothing sent. An entry without an id is given one rather than refused. The list is a composed one, so an entry whose origin.kind is collection (a collection or folder level) is judged as a collection's own, each on its own: it may be a script.setup or script.teardown, and ids repeated across levels are allowed. Every other entry is judged together as a request's, and an Item N in a refusal counts within those. null or an absent elements sends none.

vayu::core::ElementPipeline runs the compiled list at each phase this send reaches: script.pre elements at step.before, immediately before the transfer (so a pm.request edit reaches the wire); extract.* / assert.* / script.post elements at step.after, once the response (or, for a streaming send, the terminated stream) is in. Every level's script runs, in list order, and each one's tests and console lines are added to the step's result rather than replacing an earlier level's (#2522). assert.* outcomes append to the same pm.test() channel a script.post element's assertions do, so the response body's testResults and consoleLogs (see below) do not distinguish a declarative assertion from one a script wrote by hand. The response body and the stored trace both carry an elements array beside scripts - one entry per element that ran, each {id, kind, name?, origin, required?, outcome, message?, waitedMs?} (name the element's own label, when it has one; required present, as true, only for an element whose config.required is, which makes an extractor's missing a failed send) with outcome one of ok | failed | missing | skipped | error (a disabled element reports skipped without its apply ever running; a script element reports error with the thrown message when its script threw and failed with the first failed pm.test as its message when only assertions did not hold; an assert.* that reports error because its own config cannot be judged, a row stored before #3043, also adds a failed entry to testResults under the same message, so the send fails) - see Elements.

The pre-request script can change what is sent. Its pm.request edits - method, url, headers, body - are applied to the request before it goes out, and because auth is resolved before the script runs, a script-set Authorization overrides the one the engine applied. A credential that waits on the script (#2473) is applied after it instead, and a script-set Authorization still wins: auth never replaces a header the request already carries. requestHeaders and rawRequest in the response below, and the stored trace behind GET /runs/:id, all report the post-script request. A value the engine cannot send (a non-string url, an unknown method) rejects the whole write-back, leaves the request unchanged, and is reported as preScriptError. See scripting.md.

Redirect policy. followRedirects defaults to true, so omitting it follows every 3xx and the final response is returned as the answer, with the earlier hops' status and header lines on its redirects member (field notes below the response example) - send followRedirects: false to make the 3xx itself the answer. A chain longer than maxRedirects (default 10) fails the send with TOO_MANY_REDIRECTS rather than returning the last 3xx. Both clients send these explicitly for exactly that reason (see api-integration). POST /runs accepts the same three fields with the same defaults, so a load test can be run under the policy the request was configured with.

TLS verification. verifySSL defaults to true and is stored on the request (requests.verify_ssl, the Settings tab's Verify TLS certificate row). Both clients send it on every execute and every load test rather than eliding the default, for a stronger reason than the redirect policy above: an omitted false verifies the certificate the user turned verification off for, so the request fails against the one host the setting exists for. Off skips both the chain and the hostname check (CURLOPT_SSL_VERIFYPEER and CURLOPT_SSL_VERIFYHOST), which is why the app paints the state as a warning. To keep verification on for a host with an internal authority, add the CA under TLS trust settings instead.

A redirect hop's cookie stays with the origin that set it. On a design send, a stream and a scenario load run's per-virtual-user session, a Set-Cookie returned by one hop is stored in the cookie jar under the origin that set it, exactly as before, but is applied to the follow-up request only when that request's origin - scheme, host and port - is the same. A redirect that changes any of the three therefore starts without the hop's cookie: that includes a port-only change (127.0.0.1:8080 to 127.0.0.1:9090) and a hop to a sibling domain. A same-origin hop is unchanged, and a hop back to the origin that set the cookie carries it again. Later requests use the jar as normal. This is Vayu's own rule, held by the engine's redirect loop, and it is not configurable. The reason is the one behind curl 8.21.0's hardening (http: don't pass on set cookies to new origins, which the engine picked up with the vcpkg baseline bump of #679): what one origin handed the client is not the next origin's to read. libcurl's cookie engine matches by host and path alone, so without the rule a cookie set on 127.0.0.1:8080 would ride a redirect to 127.0.0.1:9090. A flow that depended on a cookie surviving a cross-origin hop (a login that bounces through an identity provider is the usual shape) sends the follow-up request without it. A hop's Set-Cookie is reported in redirects whether or not a later hop carried it, so the member says what the server sent, not what went on to the next origin.

Protocol. httpVersion selects which HTTP version curl attempts: "auto" lets ALPN negotiate (curl's own default), "http1.1" forces HTTP/1.1, and "http2" attempts h2 over TLS and falls back to 1.1 (CURL_HTTP_VERSION_2TLS - against a plain http:// URL this silently negotiates 1.1, since h2 is not offered over cleartext). A server on http:// that speaks only h2c answers that HTTP/1.1 request with its HTTP/2 preface, and the send fails as PROTOCOL_MISMATCH with a hint naming h2c (the transport error codes are described under Proxy settings); serve it over TLS or let it accept HTTP/1.1, since Vayu never sends h2c. This is what was requested; the response's own httpVersion (below) reports what was actually negotiated, and the two can differ. The renderer always sends this field on every execute, never eliding it even when it equals the default - the same rule followRedirects follows, and for the same reason: an omitted field lets an engine-side default win silently. MCP's saved-request paths get the same guarantee from POST /compose, which always emits a stored request's execution options; its two ad-hoc tools (run_request / start_load_run) forward httpVersion only when the caller supplies it, since there is no saved request behind an ad-hoc call for an omission to silently override (see mcp.md). It governs both Send and load test - POST /requests/PUT /requests/:id is where a request's protocol is actually stored (see Requests above); POST /runs (below) is simply the run-shaped way of stating the same field, not a second store.

Response:

{
  "status": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "application/json"
  },
  "headerLines": [
    { "name": "Content-Type", "value": "application/json" }
  ],
  "redirects": [
    {
      "status": 302,
      "statusText": "Found",
      "headerLines": [
        { "name": "Set-Cookie", "value": "session=abc; Path=/" },
        { "name": "Location", "value": "/users" }
      ],
      "url": "https://api.example.com/login",
      "schemeDowngrade": false
    }
  ],
  "requestHeaders": { "accept": "*/*" },
  "requestHeaderLines": [
    { "name": "accept", "value": "*/*" }
  ],
  "rawRequest": "GET /users?access_token=... HTTP/1.1\n...",
  "authQueryParam": "access_token",
  "body": { "id": 1, "name": "John" },
  "bodyRaw": "{\"id\":1,\"name\":\"John\"}",
  "bodyEncoding": "utf8",
  "bodySize": 20,
  "bodyCapped": false,
  "httpVersion": "HTTP/1.1",
  "httpVersionDowngraded": true,
  "warnings": [],
  "timing": {
    "totalMs": 245.5,
    "wireMs": 245.1,
    "queueWaitMs": 0.4,
    "dnsMs": 5.2,
    "connectMs": 12.3,
    "tlsMs": 45.1,
    "firstByteMs": 180.2,
    "downloadMs": 2.7,
    "engineMs": 3.4
  },
  "testResults": [
    {
      "name": "Token was issued",
      "passed": true,
      "source": "pre",
      "scope": "collection"
    },
    {
      "name": "Status is 200",
      "passed": true,
      "source": "test",
      "scope": "request"
    }
  ],
  "consoleLogs": [
    { "source": "pre", "scope": "collection", "level": "log", "message": "token refreshed" },
    { "source": "test", "scope": "request", "level": "error", "message": "unexpected shape" }
  ],
  "validation": {
    "checked": true,
    "valid": false,
    "matchedStatus": "200",
    "matchedContentType": "application/json",
    "failures": [
      { "path": "/id", "message": "Value type not permitted by 'type' constraint." }
    ],
    "failuresTotal": 1,
    "unevaluatedKeywords": [{ "keyword": "unevaluatedProperties", "count": 2 }]
  }
}

bodyEncoding says how to read bodyRaw (issue #2458), and it is always present. "utf8": the whole body is valid UTF-8 with no NUL byte, bodyRaw is that text and body its JSON parse (or null). "base64": anything else - an image, a PDF, application/octet-stream, Latin-1 or Windows-1252 or UTF-16 text, a compressed body libcurl did not decode, text containing a NUL - and bodyRaw is the bytes in standard padded base64, body is null, and bodySize is still the number of bytes, not the length of the base64. The check reads the whole body, not a sniffed prefix, and the engine decodes no declared charset: a body that is valid UTF-8 is "utf8" whatever its Content-Type says, and one whose charset=utf-8 is wrong is "base64", left for the client to decode by the declared charset. A header value that is not UTF-8 has no such field and is answered with U+FFFD in place of each bad byte.

bodyRaw of a "utf8" answer is the byte-exact text received; body is the parsed convenience copy, whose member order is unspecified and in which a duplicate key collapses to the last value. A client that shows or re-saves the body should use bodyRaw, as the app does (issue #2459).

body is also null on a "utf8" answer that is valid JSON in two cases (issue #2544): the request sent includeParsedBody: false (below), or the text is longer than 4 MiB (MAX_PARSED_RESPONSE_BODY_BYTES), whatever the request sent. Past that size the engine does not build the parsed copy at all, because a JSON tree costs several times its text and the answer is serialised from it once more; bodyRaw still carries the whole body, up to maxDesignResponseBodyBytes below. The key is always present. Scripts, the schema check and the stored trace read the body itself, so none of them is affected.

So a response the server answered is a 200 whatever its bytes are; the end of this section has the 500 that remains.

bodyCapped says the body is a prefix (issue #1157). A design-mode send reads at most maxDesignResponseBodyBytes (Settings → Limits, default 32MB); a response past that stops being read there, and body / bodyRaw / bodySize describe what arrived rather than what was sent. The status and the headers are the server's own - they arrive before the body - so this is a successful response carrying a flag, not a transport failure. The field is always present, so a client can tell "not capped" from an engine too old to say, and re-sending under the same setting reads the same amount: raise the setting to read more. Two consequences worth stating, since both follow from reading less: a cut JSON body no longer parses, so body is null and a test script's pm.response.json() throws, and validation below reports checked: false with body_not_json rather than inventing a schema failure. A body nested past 100 levels counts as not JSON for the same check, so a deep body is never walked by the schema validator (issue #2413).

The cap falls on a byte count, so it can land inside a UTF-8 character. For a capped body only, bodyEncoding is decided with that incomplete last character (at most three bytes, and only bytes some continuation could still make valid) left out, and a "utf8" bodyRaw ends before it: a text body stays text rather than turning to base64 over its last character. bodySize still counts every byte read, so it can exceed the UTF-8 length of bodyRaw by up to three. A "base64" body is never trimmed, and a body that was not capped is judged whole. The stored trace makes the same decision on the same bytes.

This is not the stored trace's bodyTruncated (see GET /runs/:id), which is maxTraceBodyBytes shortening a body for storage after the whole of it was read and shown - a re-send recovers from that one. A design run whose live response was capped stores trace_data.response.bodyCapped, so a restored response says what the live one said.

A body the live answer sent as bodyEncoding: "base64" is stored the same way: trace_data.response.body holds the base64 and trace_data.response gains "bodyEncoding": "base64". The key is written only then; absent means the stored body is the text itself, which is what every row written before the field holds. A collection run's step traces follow the same rule.

validation is what the response was against the schema its contract declares (issue #628), and it is absent entirely for a request whose collection ancestry binds no OpenAPI document. That absence is load-bearing: a response nobody judged against a contract did not fail one, so there is no checked: false for it either.

The same object is stored on the design run's trace_data.validation, so a restored response shows the verdict the live one did rather than recomputing it. A streaming send carries none - an event stream is not a document a response schema describes.

testResults lists both scripts' assertions in execution order, each naming the script that made it in source ("pre" / "test", the spellings consoleLogs uses) - pm.test is bound in both phases, and until issue #810 a pre-request assertion failed a collection-run step while appearing in no list. An entry stored before that carries no source; it is a test script's, which is all the list held.

A request runs the scripts of every level it inherits from - the collection's, each folder's from the outermost in, then its own - and every level's results are listed (#2522). Each testResults and consoleLogs entry names its level in scope: collection, folder or request. It is not level, which a console line already uses for the console method. An entry stored before the field carries no scope and is the request's own; so is one from a payload whose elements carry no origin. success folds the same way: a failing pm.test at any level is a failed assertion, and the first level that throws is the error. preScriptError / postScriptError hold the thrown message as they always have when the request's own script threw (never empty or a bare null: a script that runs out of memory reads Script ran out of memory at the 1 MiB limit, see Error Handling); when an inherited level threw, they name it - "Collection pre-request script failed - ", "Folder test script failed - ". An assert.* or extract.* element's entry carries the scope of the level that declared it.

The four script keys are stored the same way (issue #725). testResults, consoleLogs, preScriptError and postScriptError are returned in the body above and written to the design run's trace_data.scripts as one object, so a response restored from History carries the assertions the live one showed. This used to hold for a streaming send only, which made a restored ordinary send's Tests pane empty whether its assertions passed or never ran. A send whose scripts said nothing stores no scripts node at all - absent means no scripts, not no results - and a transient execution stores neither, as it stores nothing.

Field Meaning
checked Whether anything was actually validated
valid Present only when checked. A body with no failures
reason Present only when not checked - the code, see below
failures[] path (a JSON Pointer into the body; an unexpected property is at its own pointer, /o/z with unexpected property 'z') and message, capped at 10
failuresTotal Every failure found, including any past the cap
unevaluatedKeywords[] Schema keywords the validator could not evaluate, by name and count
matchedStatus / matchedContentType Which declared response answered, verbatim

A status answers to the most specific pattern that covers it - exact, then 2XX, then default - the same rule contract coverage counts by, shared rather than restated, over the same set of statuses: every one the operation declares, whether or not it carries a schema (#3028). A declared 200 with only a description therefore answers a 200 itself and is no_schema_for_status; a default or 4XX beside it never judges that body. A media type matches exactly first, then a declared */* or application/*, among the media types that carry a schema.

unevaluatedKeywords is the dialect disclosure and is not decoration. The validator reads draft-07; OpenAPI 3.1 schemas are JSON Schema 2020-12, whose unevaluatedProperties, prefixItems and dependentSchemas a draft-07 reader silently ignores - so a schema that meant to forbid something would permit it. Every such keyword is named and counted, which makes a valid: true beside one narrower than it looks rather than wrong.

propertyNames is the one draft-07 keyword on that list, and only when it is nested (#2729): valijson builds a propertyNames subschema from its parent's node path, so it validates the schema's root keyword but passes every body for one inside properties, patternProperties, additionalProperties, a dependencies schema, an allOf/anyOf/oneOf/not member, items or a $ref target. Each nested occurrence is counted once, a $ref target reached twice included; the root keyword is validated and counted only when a $ref back to # reaches it from below. In a script, pm.response.to.have.jsonSchema fails in both polarities on such a schema, as it does for any unevaluated keyword.

reason codes (all mean bound to a document, and still not judged):

Code What happened
no_operation The request carries no spec_operation - it is not an operation
no_index The bound document declares no response, or its schema could not be read (including one that refers to itself without describing any value, which is refused before it can run)
hash_mismatch The stored document no longer hashes to what the binding recorded
never_stamped The binding names a document and no version of it, so nothing can be compared - re-bind the collection. Distinct from hash_mismatch because a sync of an unchanged document would not repair it
operation_not_declared The document does not declare this identity (the operation is not in the spec, or declares no response at all)
no_schema_for_status Nothing the operation declares covers this status, or the status that answers it declares no schema to check a body against
no_schema_for_content_type The status matched; none of its media types did
no_response A transport error - there was no response to check
body_not_json The body is not JSON (or nests past 100 levels, which counts as not JSON), and a JSON Schema cannot describe it

headers is keyed by the lower-cased header name, and a name the response sent more than once holds every value folded with ", " - the RFC 7230 §3.2.2 equivalence for comma-list headers. So two Set-Cookie lines read back as one "session=abc; Path=/, csrf=xyz; Path=/" entry rather than the last one alone. headerLines is the lossless form of the same headers (issue #2460): one {name, value} object per line the final response sent, in wire order, with the name in the case it arrived in and the value trimmed of the optional whitespace around it (RFC 9110 §5.5). A name sent twice is two entries, and a Set-Cookie is always its own entry, so a client lists headers as received and reads each cookie from its own line. It is always present on a design answer, an empty array when no headers arrived, so a client can tell "none" from "an engine too old to say" - the same rule as httpVersion. A streaming send (stream: true) reports it on the completed trace, while its open frame carries the folded headers map only. The map is unchanged and stays what assertions and the MCP headers member read; pm.response.cookies and MCP's headerLines read the lines. Splitting a folded Set-Cookie out of headers is now needed only for a row stored before this field and an answer from an older engine, and it must split on a comma followed by name=, since an Expires= value contains a comma of its own (a cookie value that holds one is indistinguishable from a boundary there, which is why headerLines exists). The same headers fold holds for the response headers stored on a design run's trace_data.response and on captured load-run samples, which come off the same parse. The stored trace_data.response also carries headerLines, written only when non-empty; a load-run sample keeps the folded map alone, because the load path is the hot path and records no lines.

redirects lists the redirect responses the send followed (issue #2461), in the order they arrived, each as {status, statusText, headerLines, url, schemeDowngrade} with headerLines shaped as above. headers and headerLines hold the final hop only, so a Set-Cookie or Location on an earlier hop - the 302 that answers a login and sets the session cookie - is readable nowhere else. url is the URL of the request that hop answered: the URL the send went to for the first hop, the previous hop's Location resolved against it for each later one (userinfo is removed), with the value of the request's auth-written query parameter, and of any query parameter named like a credential, blanked; "" when libcurl reported none. schemeDowngrade is true when that request went over https and the next one over http: the one hop on which an API-key header, which a redirect does not withhold, travels in clear text (see the Redirects paragraph under Authentication). A row stored before these two members existed lacks them. Only 3xx responses are hops: a 1xx interim response such as 100 Continue is not. It is always present on a design answer, an empty array when nothing was followed (followRedirects: false always gives an empty one, the 3xx being the answer), and holds at most maxRedirects entries (every hop when maxRedirects is negative, which sets no limit), so a loop that ends in TOO_MANY_REDIRECTS reports the hops it made. The stored trace_data.response carries it too, written only when non-empty; a load-run sample records none. It reports what the server sent: see the cross-origin paragraph above for why a hop's cookie is not necessarily one a later hop carried. A post-request script reads the same hops as pm.response.redirects (code/status/headers for status/statusText/headerLines), absent where the chain is not recorded.

warnings lists what the engine did to the exchange that the response does not show (issue #3307), each as {code, message} in the order it was found: code is a stable snake_case identifier a client branches on, message the sentence a person reads. A warning never fails the send. It is always present on a design answer, an empty array when there is nothing to say, so a client can tell "no warnings" from an engine too old to warn. The stored trace_data carries it at the top level, beside clientCertificate and not inside response, because a send that failed before any header block arrived has no response node and can still have warned; it is written only when non-empty, so a row stored before the field reads as having none. A load-run sample records none. Codes are listed here as the engine starts producing them:

  • cookie_not_sent: libcurl would not let the Cookie line pass 8190 bytes and left out the first jar cookie that did not fit, named in the message (the name only, never a value). It also drops every typed Cookie row with the line, so requestHeaders carries no Cookie entry then. libcurl skips the jar cookies after the named one without saying so.
  • cookie_limit_reached: more than 150 jar cookies matched the URL and libcurl sent the first 150. A typed Cookie row is still sent in this case.

  • cookie_dropped_oversized: a response carried Set-Cookie headers libcurl discarded unread, because the line was over 5000 bytes (counted from after Set-Cookie: to the end of the line) or the cookie's name and value together were over 4096. One warning counts them, across every hop, and names up to five (name only, cut at 64 bytes; a line that names no cookie, or whose name is not text, is counted but not named).

  • cookie_dropped_too_many: a single response set more than 50 cookies and libcurl ignored the rest. The count restarts with each hop's response, so 30 cookies on each of two hops is not an overflow; one warning gives the total ignored over the chain. It counts the Set-Cookie lines libcurl would have stored, so a later cookie it rejects for another reason (a public suffix, a __Secure- prefix) can make the count one too high.

cookie_not_sent and cookie_limit_reached are read off libcurl's own notices at any log verbosity, once per cookie however many hops of a redirect chain report them. The two cookie_dropped_* codes are counted from the response's header lines instead, only on a send that has a cookie jar. A streaming send (stream: true) reports all four by the same rules, on its stored trace alone. Under load the same two checks feed the run's cookies_dropped warning instead (see GET /runs/:runId/report).

rawRequest is the header block libcurl actually sent, captured from the transfer's last outbound header frame and followed by the request body when that frame declares one (Content-Length above zero, or Transfer-Encoding: chunked). So it carries what libcurl added on its own - the cookies the cookie jar matched, Accept, Content-Length, and an h2 request rendered in HTTP/1 form - none of which appear in requestHeaders. The jar's cookies and the request's typed Cookie rows share one Cookie line, the jar's first and the typed rows after them joined with "; " (issue #2788); a redirect to another scheme, host or port drops the typed part, as it drops a typed Authorization. The app's Headers tab lists the sent request from this block, line by line in wire order, so the tab shows the whole wire while the script-visible record stays the engine's. When the final hop sent no body, the string ends at the blank line that closes the header block: a POST answered 301, 302 or 303 is re-sent as a body-less GET (any other method keeps its name and loses its body, a streamed file body included), without the Content-Type and Content-Length lines that described the body, so the body it started with is not shown on a request that never carried it (issue #2462). 307 and 308 keep the method and the body, and so does the view.

requestHeaders is the sent record: the composed headers as the transfer issued them on its first hop. After a followed redirect that changes the request (a POST answered 303, which becomes a GET) the final hop's own header block is rawRequest's. It carries what the engine derives at send time - the body-implied Content-Type (text/plain for a text body since issue #2464), and every default header this send adds (the User-Agent, the negotiated Accept-Encoding, an enabled correlation id) - and drops a form-data Content-Type, which libcurl writes itself with the boundary. An enabled header whose value is empty or only whitespace is sent empty on every transport (issue #3220) and recorded with the value "": a header line with nothing after the colon is libcurl's spelling for remove this header, so the engine writes libcurl's Key; form instead, which sends Key: with no value. A blank row never removes a header; refusing one of the engine's defaults is disabledDefaultHeaders' job. A blank Accept or Expect row is therefore sent empty in place of libcurl's own Accept: */* or Expect: 100-continue. Two blank rows keep a meaning of their own and are neither sent nor recorded: a blank Content-Type means no Content-Type (on a binary body, absent, so the file's type applies; see the body union), and a blank Cookie row joins nothing into the cookie line. A disabled row is never sent. The record does not carry libcurl's own additions or the jar's Cookie line; those are rawRequest's alone. A test script's pm.request.headers reads this same set (see scripting.md), so an assertion about what was composed to go out reads the same set the engine recorded; the Headers tab lists rawRequest's header block instead, which is that set plus the transport's own lines.

requestHeaderLines is the same record unfolded (issue #2466): one {name, value} entry per line the transfer appended, in wire order, a repeated name repeated and each in its own spelling - the request's own lines first, in the order the request gave them, then what the engine derived. Always present, an empty array when nothing was recorded. requestHeaders stays one value per name for the readers written against it: a repeated name's values are joined with ", ", a Cookie's with "; ", under the first line's spelling - and that folded form is what pm.request.headers shows, since the scripting API is single-valued.

The stored trace keeps this map too, as trace_data.request.sentHeaders beside the composed request.headers (issue #664), and the unfolded lines as trace_data.request.sentHeaderLines (issue #2466) - so a restored response pane's sent-headers disclosure shows the set the live one showed, derived User-Agent and body-implied Content-Type included, rather than the composed map's different answer. Both maps are stored because they answer different questions: the composed one is what a pre-request script saw and what reseeds a request tab from a run. The key is absent on a step that sent nothing and on every row written before the field, so a reader falls back to request.headers - restore-response.ts's sentSide is that reader. A load run's sampled capture records no sent headers at all: its deferred replay and the Samples viewer both keep reading the composed map, as scripting.md documents. That map can differ from the wire in the way this record exists to state - the derived User-Agent and body-implied Content-Type are absent, and a blank Content-Type or Cookie row, which is not sent, is listed - and for load samples that divergence is recorded as permanent rather than treated as a gap to close (issue #677 item 7). Which completions become samples is decided when they finish, so a sent record for the few that are kept would have to be built for every transfer, and a load run exists not to charge the hot path for what it throws away.

Values in rawRequest are not redacted: this field exists to say exactly what went out. On a followed redirect it is the final hop - its method, its headers and the body that hop carried, if any - matching the response beside it. A transfer that failed before sending anything (DNS failure, connection refused) has no frame to read, and falls back to a request synthesized from what was composed.

The stored trace keeps the same string, as trace_data.request.rawRequest on the design run this execute created (and on each step row of a scenario run) - so reopening a run shows the raw request the live view showed, cookies included, rather than one rebuilt from headers that never had them. Its body half is capped at maxTraceBodyBytes like body is, and the key is absent both on a step that sent nothing and on rows written before the field existed; see db-schema. The redaction posture is the live field's, for the reason Security records: a trace is the record of what was sent.

The answer and the stored trace also name what auth wrote (#1835, #1845), as two additive keys: authQueryParam, the raw (unencoded) name of the query parameter apply_auth appended to the URL for an API key with in: "query" or an OAuth 2.0 token with tokenPlacement: "query", and authHeaders, the array of header names an API-key block filled. The URL alone cannot say which query parameter is a credential, and a reader that masks one (the MCP server) needs the name. In the trace they sit on trace_data.request; in this answer they sit at the top level, beside rawRequest, written by the same function (record_auth_provenance) so the two cannot disagree. Each key is absent when auth wrote none of that kind, never an empty string or array - unlike the response fields above, which are always present - and absent on rows written before the field; the values beside them stay raw. A streaming send answers 202 before any of this exists, so only its stored trace carries them. A pre-request script that retargets the URL can leave authQueryParam naming a parameter the final URL no longer carries.

And they say when auth was not sent at all (#2474): authNotice, a plain string, appears when the request's auth.mode is one the engine stores but does not execute (digest, aws, ntlm, hawk, oauth1, edgegrid, jwt; an import can bring any of them in). The request is still sent, without authentication, and the notice says so, naming the mode:

"authNotice": "auth mode 'ntlm' is not executed by Vayu; the request was sent without authentication"

It appears too when an executed mode had nothing to write (#3203): a bearer token, or an apikey key, that is empty once trimmed of its spaces and tabs. The request is sent without that credential rather than refused:

"authNotice": "the bearer token is empty; the request was sent without an Authorization header"

and, for the API key, "the API key has no name; the request was sent without it". It also appears when an oauth2 block placing its token in the header yielded to the Authorization header the request carried, so no token was fetched (#3202): the request's own Authorization header was sent; no OAuth 2.0 token was fetched.

It follows the same rules as the two keys above: one writer for both homes, absent when empty (no auth, and an executed mode that wrote its credential, or skipped it under a header the request already carries), absent on rows written before the field, and on a streaming send only in the stored trace. A pre-request script that assigns pm.request.auth replaces the notice along with the credential: the record then describes the script's auth, so it is absent unless the script's own token or key name is empty. A collection run's stored step traces carry it through the same trace writer; a load run sends such a request the same way and raises no run warning for it.

consoleLogs entries carry their own source and level. source is which of the request's two scripts wrote the line ("pre" for the pre-request script, "test" for the post-request one) and level is the console.* method that was called - "log", "info", "warn" or "error". Releases before this one sent a flat string[] with the source encoded as a "[pre] " text prefix and no level at all, which was indistinguishable from a script logging that string itself; a client that may talk to an older engine should read a bare string as {"source": "test", "level": "log"}, or "pre" when the prefix is present. The field is omitted entirely when neither script logged anything. Each script execution keeps at most 1000 lines and 1 MiB (64 KiB a line); a script that passes either ends its entries with one warn line saying output was dropped. See scripting.md.

httpVersion on the response is the protocol actually negotiated (CURLINFO_HTTP_VERSION after the transfer), e.g. "HTTP/1.1" or "HTTP/2" - an outcome, not an echo of the request's own httpVersion field, and deliberately a different value space (see requests.http_version for the full distinction). It is "", not omitted, when nothing was negotiated (e.g. the connection never reached a server) - empty rather than guessing "HTTP/1.1" and presenting a guess as fact. The same field is stored in a design run's trace_data.response and reported back unchanged by GET /runs/:runId and GET /runs/:runId/report.

httpVersionDowngraded is true when the request explicitly asked for "http2" and the connection negotiated something older - the one thing the two httpVersion fields cannot say on their own, since neither knows about the other. It is always present (never omitted), so a client can tell "not downgraded" from "an engine too old to say". Only an explicit http2 counts: "auto" promises nothing and "http1.1" got what it asked for, so neither can be downgraded. A transfer that negotiated nothing at all (httpVersion "") is false - that is a transport failure, and errorCode already reports it.

A plaintext http:// URL always reports true for an explicit "http2". CURL_HTTP_VERSION_2TLS offers h2 over TLS only, so a cleartext request never attempts it - the fallback noted above under the request's httpVersion is exactly the case this field is for, and it is honest rather than a false positive: h2 was asked for and HTTP/1.1 was used. A local dev server on http:// with the protocol set to HTTP/2 will show the warning on every request; either switch the request to auto, or serve over TLS. A server there that speaks only h2c never gets as far as a downgrade: it cannot read the HTTP/1.1 request, so the send fails as PROTOCOL_MISMATCH with the h2c hint instead, and auto meets the same failure without the hint.

This exists because the failure it names is invisible otherwise: a 200, a latency and a body look identical whether or not the protocol you asked for was granted. Windows shipped from v0.11.0 to v0.14.0 with HTTP/2 unreachable and every request silently on HTTP/1.1 (#215); nothing in the API said so. The same field is stored on a design run's trace_data.response, and load runs and collection runs carry the whole-run count as summary.httpVersionDowngraded in GET /runs/:runId/report.

One timing convention. The eight phase keys above (totalMs through downloadMs) are the same *Ms names the stored trace uses (record_design_result / load_strategy → results[].trace in GET /runs/:runId/report), and the design-mode writer stores all eight unconditionally - so a live response and one restored from the stored trace carry the same fields with the same names, Wire/Queue included. Traces written by earlier releases differ two ways, and readers must tolerate both: stored rows omitted zero-valued phases and all of totalMs/wireMs/queueWaitMs (see db-schema.md), and the live response named its keys without the suffix (firstByte, dns, …) - consumers of the raw /execute body written against that dialect must switch to the *Ms names.

refusalCode and authErrorCode say why a send never went out. Both are absent from an answer that was sent. A buffered send refused after the build and before the transfer (the residual pass of a name or header, the auth applied after the pre-request script, a targetPolicy verdict) answers statusCode: 0 with the sentence in errorMessage and the rule's code in refusalCode: unsendable_header, empty_header_name, invalid_header_name, colliding_header_names, target_not_allowed, target_host_unknown, or an auth code. authErrorCode is the hint of an auth failure (errorCode AUTH_REQUIRED or AUTH_FAILED), whether the token was sought at the build or, for a config that waited for the script, after it (where it repeats refusalCode, #2521). A streaming send answers the same codes as a 400 before its stream opens.

wireMs and queueWaitMs split totalMs at the wire (#2394). totalMs is perceived: submission to completion. wireMs is libcurl's CURLINFO_TOTAL_TIME less the time libcurl held the transfer waiting for a connection slot (CURLINFO_QUEUE_TIME_T, bounded by PRETRANSFER_TIME because curl 8.23 counts a wait again each time the transfer is passed over), and queueWaitMs = totalMs - wireMs is everything before the wire: the generator's own queue and that slot wait. The phases are measured after the slot wait too, so firstByteMs is the target's own. A design send has no slot to wait for, so its queueWaitMs stays a sliver. Over a followed redirect chain the phase fields accumulate: every hop's libcurl timers are summed (add_phase_times), so firstByteMs is then the sum of each hop's wait, not one server's, and dnsMs, connectMs, tlsMs and downloadMs are sums the same way. The app's Timing tab says so when the response's redirects is non-empty.

timing.engineMs is Vayu's own cost for the exchange (#2132), the ninth key and the only one a buffered /execute alone carries. It is the time from the handler receiving the request to the answer being assembled, less the transfer (wireMs), the pre- and post-request scripts (pm.sendRequest inside them included) and the time spent waiting on an OAuth 2.0 identity provider's token endpoint (a token fetched on first use, or refreshed because it expired; a cached token costs a lookup and stays in). What it counts is request composition, the rest of auth resolution, the cookie jar, residual {{token}} resolution, the element pipeline other than the user's scripts (extractors, assertions, metrics) and building the response; queueWaitMs, the sliver between the engine's stopwatch and libcurl, is part of it. A design send blocks on no timer, so there is no timer wait to leave out. It does not count the wire, scripts, the token endpoint, the hop from the Electron shell to the engine, persisting the run row and trace, serialising the body, or the renderer drawing it: the figure is taken once, before the write, and that same value is both returned and stored on the trace as a flat engineMs, so a restored response shows what the live one did. It is absent - not 0 - from a streaming send (the route answers 202 before any exchange finishes), from the auth-failure reply (no exchange ran), and from rows stored before this key existed.

Variables the scripts and extractors wrote are persisted, and only those. After the post-request elements run, the engine writes back the three variable scopes (the run's environment, globals, and the executed request's collection) - but only for a scope whose variables a script or an extract.* element actually changed, a name removed included (an unset, or an extractor's miss with no default, #3053). A run that sets no variable writes nothing at all, so it does not move a collection's or environment's updatedAt. Each variable round-trips whole, createdAt included; see VariableValue shape for why that field must survive and who may stamp it.

persistVariables: false keeps them within the send (#1904). Every script and extractor still runs, a value one sets is visible to the elements after it, and the response (or a stream's trace) reports their outcomes and testResults as usual; only the write-back above is skipped, on both the buffered and the streaming path, so no environment, collection or globals row changes. Absent and null mean true, which is what the app's Send relies on; a present non-boolean is a 400 ('persistVariables' must be a boolean) before any run row exists, for the reason transient's is. It is independent of transient: that flag decides whether the run is recorded, this one whether the variables are. MCP's run_request sends false whenever write access is off (MCP).

includeParsedBody: false leaves the parsed copy out (#2544). The answer's body is null and the engine skips the parse that would build it; bodyRaw, bodyEncoding, bodySize, the scripts' pm.response, the validation node and the stored trace are what they would have been. It is for a client that reads bodyRaw only and should not pay for a second copy of every body. Absent and null mean true; a present non-boolean is a 400 ('includeParsedBody' must be a boolean) before any run row exists, by the rule transient's follows. A body past 4 MiB is never parsed whatever this says (see the response section above). A streaming send has no body in its 202 and ignores the flag.

A run row the database cannot write is a 500. A recorded send whose run row cannot be stored (a busy or locked database, a full disk, an I/O error) answers 500 Couldn't create the run record before anything is sent, the same as POST /runs. The app retries a 5xx and treats a 4xx as a verdict, so a momentary lock no longer reads as a refused request (#2353). A transient send writes no row and is unaffected.

A send that fails once its row exists is a 500 with a body, and a failed row (#2458). Anything that throws after the run row is written - building the answer, running the exchange, handing a stream to its worker - answers 500 Execution failed: <reason> in the usual {"error": {"code", "message"}} shape and marks the row failed, even when its result had already been recorded, so GET /runs/:runId never shows a send the caller got no answer for as running or completed. A body the engine cannot hold as text is not such a failure: it is a 200 with bodyEncoding: "base64", above.

POST /runs

Start a load test run (Vayu Mode).

Request:

{
  "method": "GET",
  "url": "https://api.example.com/users",
  "headers": [],             // Optional, {name, value} lines in send order (or the older object) - see POST /execute
  "body": {
    "mode": "none",
    "content": ""
  },
  "mode": "constant_rps",    // "constant_rps", "constant_concurrency", "ramp_up", "iterations", or "capacity"
  "concurrency": 100,        // Target in-flight requests (constant_concurrency / ramp_up target / iterations); the ceiling for capacity
  "startConcurrency": 1,     // Ramp start concurrency (ramp_up); first level searched (capacity)
  "duration": "60s",         // Duration, ms/s/m/h (constant_rps / constant_concurrency / ramp_up); the deadline for capacity
  "rampUpDuration": "10s",   // Ramp time, ms/s/m/h (ramp_up mode; start may be above target)
  "sloMs": 200,              // p99 budget the search looks for the edge of (capacity mode)
  "stepDuration": "5s",      // How long each level is held before it is judged (capacity mode)
  "iterations": 1000,        // Number of iterations (iterations mode)
  "targetRps": 1000,         // Target requests per second (constant_rps only; a 400 on any other mode)
  "maxInFlight": 10000,      // Optional; see "maxInFlight" note below - constant_rps only
  "requestId": "req_1234567890",      // Optional, links to saved request
  "requestName": "Create user",       // Optional, read by the deferred validation script as pm.info.requestName
  "environmentId": "env_1234567890",  // Optional, what {{variables}} resolve against - see below
  "collectionId": "col_1234567890",   // Optional, the composed collection scope when no requestId row names one - see below
  "origin": { "kind": "mcp", "client": "claude-code" },  // Optional, who started the run - see below
  "targetPolicy": { "allowAll": false, "allowedHosts": ["api.example.com"] },  // Optional, the hosts this run may reach - see below
  "requestElements": [],     // Optional step-level elements for THIS request - see below
  "data": [],                // Optional data rows, one object per row - see below
  "dataFileName": "users.csv",  // Optional, only beside data: the file's display name - see below
  "dataFileHash": "<sha256>",   // Optional, only beside data: 64 lowercase hex chars - see below
  "dataFileCastNumbers": true,  // Optional, only beside data: the file's numbers were read as numbers - see below
  "thresholds": {},          // Optional pass/fail budgets - see below
  "carriedBudgets": [],      // Optional, which of those budgets were carried over rather than set - see below
  "elements": {},            // Optional element-pipeline override, either run shape - see below
  "lifecycleElements": [],   // Optional script.setup/script.teardown for THIS run only - see below
  "monitor": {},             // Optional server-vitals scrape - see below
  "followRedirects": true,   // Optional, default true - see POST /execute
  "maxRedirects": 10,        // Optional, default 10
  "httpVersion": "auto",     // Optional: "auto" | "http1.1" | "http2", default "auto" - see POST /execute
  "stream": false,           // Optional, single-request only - consume each response as text/event-stream; see below
  "maxStreamDurationMs": 600000,  // Optional, streaming only (a collection run's streaming steps) - see below
  "maxStreamEvents": 100000,      // Optional, streaming only (a collection run's streaming steps) - see below
  "stream_metrics": true     // Optional - feed the histograms behind the report's `stream` section
}

A body nested deeper than 128 levels in any field answers 400 request body is nested deeper than 128 levels (code invalid_run_config) before any run row exists (issue #2417). The exception is a data or scenario.data cell, held to its own bound of 100 and refused in its own words (see below).

httpVersion on POST /runs is not a per-run override of a stored request - it is simply how this endpoint states which protocol the run uses at all, the same way method and url state the rest of the request. The renderer always sends the saved request's own httpVersion here (there is no second, load-test-only protocol control in the app); MCP's ad-hoc start_load_run - which has no saved request behind it - is the caller that actually depends on this field to specify a protocol in the first place. An explicit null is treated exactly like an absent key. An unrecognized string is a 400 naming the field and the valid values, the same validation POST /requests uses.

requestId / environmentId / collectionId on POST /runs are read exactly as on POST /execute: a non-string is a 400 naming the field ('environmentId' must be a string (got boolean)) and no run row is created. A single-request run's collection scope is decided by the same rule (the linked request's collection, else the composed collectionId, issue #3461), for its scripts, its residual pass and its snapshot's masking alike. A single-request run that names any of the three resolves a {{name}} still in its URL, path values, headers or body against the same scopes a Send reads (the environment, that collection's chain, globals) (#3253). It is one pass at run start, over the request every submission shares, never one per submission, so a request holding no {{ costs nothing more. An id naming nothing is an empty scope, as on POST /execute, never a refusal. The pass leaves every token the per-submission bind owns: {{data.*}} and a bare column of the run's data, {{$vu}} / {{$iteration}}, and a generator such as {{$guid}}, generated per submission. It runs before script.setup, so a setup write does not reach a request it resolved. A run whose submissions are copied skips it, leaving its request to the per-submission residual pass described under the requestElements array, which reads what script.setup wrote: one whose requestElements hold a step.before kind (a script.pre, the only one this path admits), or that declares requestElements beside data rows, a token the bind owns, or a credential waiting on the scripts. A run whose requestElements only read the response (assert.status, step.after kinds) and has none of those sends one shared request, and takes this pass (#3288). Which of the two a run is gets decided on its request before this pass, so a stored value that is itself a generator moves the run onto the copy path having already answered the name it filled, and a setup write to that name is lost. Credentials holding a name these scopes may answer are held back from the build on a run whose submissions do not wait on their scripts for them, and resolved and applied by this pass after the request's own names (#3288), so a bearer token, an api key in a header or the query and a basic pair all go out with their values; one whose credential also holds a token the bind owns ({{$iteration}}) has its stored names answered here and is bound per submission. A credential holding no token is applied when the request is built, as before. A name nothing answers is sent as written and counted in the report's unresolved_tokens warning, never refused; a credential the pass cannot apply (an api-key header name that resolves to something that is not a header name, a value a header line cannot carry) is counted the same way and the run goes on.

origin on POST /runs is the same object, read by the same reader and under the same rules as on POST /execute (#1817): who started the run, client-asserted metadata rather than identity, other when absent, client kept for mcp only, and a malformed one a 400 naming the field before the run row exists. It applies to every run shape this endpoint starts, a scenario's included.

targetPolicy on POST /runs is the object POST /execute documents (#2521), read by the same reader: a malformed one, an unknown member included, is a 400 with code invalid_target_policy before the run row exists, and it is never stored in the run's config_snapshot. What differs is where the verdict is made:

  • A single-request run has its OAuth 2.0 accessTokenUrl and refreshTokenUrl hosts judged in the pre-flight, before any token is fetched and before the run row exists: a refusal is a 400 whose code is target_not_allowed or target_host_unknown. The request's own URL is judged at each submission, in the event loop after the transferability checks: a host the policy refuses fails that submission as an INVALID_URL error whose message names the host, counted like any other error, and nothing is sent.
  • A collection run (scenario) has the token endpoints of each step's OAuth 2.0 config judged when the plan is resolved wherever the token is acquired then, a 400 under the same codes with no run row. A sequential run then judges each step's final URL after that step's pre-request script, as a buffered send does (and a config that waited for the script, at its step), and a collection load run judges each submission as a single-request load run does.
  • A load run's monitor.url (either shape) is a second host the run contacts, once per scrape for as long as it runs, and the scrape loop sends with no policy of its own, so its host is judged when the run is validated, by the same match (#3121), on the URL as the scrape will send it (after the encoding pass that turns a \ into a /, as for a send's final URL): a host the policy does not list, or one it cannot determine (a {{template}}, which the scrape would send as written), is a 400 under target_not_allowed or target_host_unknown whose message names monitor.url, before the run row exists and before anything is sent. A caller that wants a monitor on another host lists that host too.

An omitted targetPolicy restricts nothing. Redirect hops and pm.sendRequest are outside it.

Streaming under load (stream)

POST /runs reads stream, maxStreamDurationMs and maxStreamEvents through the same parser POST /execute uses, so the two endpoints agree on the spelling, the types and the ranges - a load run declares a stream exactly as a send does. It was a 400 here until this landed, because a load run's completion accounting has no place for a response that never ends. What changed is that a load stream always ends.

Under load a stream is bounded by construction. Both caps are always in force - the payload's, or the sseMaxStreamDurationMs / sseMaxStreamEvents settings when the payload names none - and neither can be set to zero-for-unbounded. That is not tidiness: the load loop is completion-driven (in_flight() = sent - completed, concurrency refilled per completion), so a transfer that never completes leaks its slot for the rest of the run.

Reaching a cap is a successful completion, not a timeout and not an error: it is the stream's intended end under load, so it lands in the run's success counts, its latency histogram and its status-code distribution like any other 200. Three other endings stay exactly what they were:

Ending Reported as
A cap in maxStreamEvents / maxStreamDurationMs Success, stream.capped incremented
The server closing the stream Success, not counted in stream.capped
maxResponseBodyBytes exceeded Error - a refusal to buffer, unchanged. The event cap bounds how many events arrive, not how large one is
The whole-transfer timeout Error - it sits a grace period past the duration cap, so reaching it means the cap never fired

Events are counted on the write path by a frame counter that agrees with the design path's parser about what an event is: a frame carrying no data field is not one, so comment-only keep-alives do not inflate the tally.

The same count reaches the live frames as the events arrive (issue #3236): streamEvents, eventsPerSecond and streamsOpen on every frame, and streamTimeToFirstEvent on gate frames, so a run of long streams shows its progress before the first one ends rather than zero completions until then. A single-request streaming run carries them, and so does a collection load run with a streaming step (issue #3304), whose streamsOpen counts only its streaming steps' transfers; a run with no stream, and a design (sequential) collection run, which has no live frames, carry none of the four.

On a single-request run, stream is refused beside transient (as on a send) and each cap is refused without stream - a cap on a non-streaming run reads as a bound the caller expects to apply, and ignoring it is how an unbounded run gets mistaken for a capped one.

A collection run (scenario) streams the steps whose stored request has stream set (#3235), and only those. The plan reads the flag off each stored request, so the run declares nothing: maxStreamDurationMs and maxStreamEvents are accepted without stream here, range-checked as above, and bound every streaming step, each falling back to its sse* setting on its own. A step that does not stream ignores them. A top-level stream is a 400 (invalid_run_config) on a collection run, true or false: it cannot make a stored request stream or stop one streaming, so accepting it would let a caller believe it did either. A collection load run sends a streaming step through the same event loop as a streaming single-request run, so the table above holds per step: a cap or the server's close ends it as a success, its events land in the report's stream section, its stored exchange keeps its event count (so GET /runs/:runId/samples reads its events back), and the step's own timeout (or the run's) bounds only its connect phase - the whole-transfer timeout is the duration cap plus the 5s backstop. A load run's natural end waits for the longest streaming step's cap plus that backstop, or for the run's timeout where that is longer (its ordinary steps are still bounded by it), before cancelling what is still in flight. A sequential (design-mode) collection run sends a streaming step through the single-request client by the same rules: a cap or the server's close ends it as a pass, its own timeout bounds only its connect phase, and a POST /runs/:runId/stop ends the stream in flight rather than waiting out its cap (a stream the server had not yet answered is a cancelled step). The body is the text/event-stream bytes, held to maxDesignResponseBodyBytes like any step's (reaching it ends the stream, with bodyCapped); the step's stored trace carries the parsed events node (items, totalEvents, eventsTruncated) a load sample's does, and the run's summary and report gain the same stream section, which its stream* budgets judge. A duration cap that passes before any status line is a timeout error naming the cap.

The data rows (a data-driven load run)

A single-request run may carry a top-level data array - one flat object per row - and bind it into the request it repeats (issue #993):

{
  "method": "POST",
  "url": "https://api.example.com/orders/{{data.id}}",
  "mode": "constant_concurrency",
  "duration": "30s",
  "concurrency": 50,
  "data": [
    { "id": "1", "email": "ada@example.com" },
    { "id": "2", "email": "grace@example.com" }
  ]
}

One row per request sent, claimed off a run-wide cursor that wraps: a run longer than the set repeats it from the top, so the file bounds which values go out and never how many requests do - that is the load profile's job. The row a completion was bound to is recorded as dataRowIndex on every retained result, and the deferred tests script reads that submission's own row as pm.iterationData.

Everything else is the scenario path's, because it is the same code: the same validation (an array of objects, present-but-empty refused, bounded by maxScenarioDataRows / maxScenarioDataBytes, and a cell nested deeper than 100 levels refused with 'data' row N column 'name' is nested deeper than 100 levels, a row that is not an object and is itself that deep with 'data' row N is nested deeper than 100 levels, and a data that is not an array with 'data' is nested deeper than 100 levels - all checked right after the body is parsed, whatever shape data has, before the engine snapshots the payload), the same {{data.column}} placement rules and escaping, the same credentials-bind-before-they-are-encoded order, and the same refusal of a {{data.*}} in an oauth2 config. Every rejection is a 400 invalid_run_config before the run row exists, so a refused set leaves nothing behind.

Two differences from scenario.data worth stating:

  • iterations is not defaulted from the row count. A load profile already says how long the run is; a collection run without an explicit count takes one pass per row.
  • The two fields cannot be combined. A top-level data beside a scenario block is a 400 naming scenario.data - the two bind differently (per submission here, per iteration and shared by every step there), so a payload carrying both would have one of them silently dropped.

Which file the rows came from (issue #2051) rides beside them as two optional, independent strings: dataFileName, a display name (the app sends the picked file's name), and dataFileHash, the SHA-256 of the file's bytes as 64 lowercase hex characters. The engine stores both verbatim and opens nothing; no path is ever stored. Each is a 400 invalid_run_config when it is not a non-empty string, dataFileName also when it holds a / or \ (a path, not a name), dataFileHash also when it is not that digest shape, and either one is a 400 when sent without data (refused, not ignored). A top-level one beside a scenario block is a 400 naming its scenario.dataFileName / scenario.dataFileHash counterpart, as data is.

How the client read that file (issue #2540) rides beside them as dataFileCastNumbers, a boolean: true when the client typed the file's unquoted numeric cells as numbers (the app's Read numbers as numbers). The rows arrive already typed and the engine never converts them; it records the flag because the hash is of the file's bytes and cannot tell two readings of one file apart. null is absent; any other non-boolean is a 400 invalid_run_config, any value (false included) without data is a 400, and a top-level one beside a scenario block is a 400 naming scenario.dataFileCastNumbers, on the same rules as the two strings.

The rows are never persisted: the stored run snapshot records the row count (dataRowCount) plus the file's dataFileName and dataFileHash when they were sent, and dataFileCastNumbers: true when the numbers were cast (absent, never false, otherwise, so a run recorded before the flag reads as text), never its path or rows, exactly as a scenario manifest does. A cell that binds travels in the request that carried it, so it is stored with whatever traces the run retains.

The thresholds block (pass/fail budgets)

A run may declare budgets it must meet. The engine evaluates them once, when the run reaches a terminal status, and the report comes back with a thresholdValidation section carrying one check per budget and a verdict. Without the block a run is measured and not judged, and its report has no such section at all.

{
  "thresholds": {
    "latencyP50Ms": 20,        // ceiling, ms; > 0 and <= 86400000
    "latencyP95Ms": 40,        // ceiling, ms
    "latencyP99Ms": 50,        // ceiling, ms
    "maxErrorRatePct": 0.1,    // ceiling, percent of the run's requests; 0-100
    "minThroughputRps": 10000, // floor, completed requests per second; > 0
    "maxAssertionFailureRatePct": 0, // ceiling, percent of failed assertions, the worse population; 0-100
    "streamTimeToFirstEventP95Ms": 800, // ceiling, ms, streaming runs; > 0 and <= 86400000
    "streamEventsPerSecondMin": 200,    // floor, events per second, streaming runs; > 0
    "failRun": true            // a missed budget sets status "failed"; default false
  }
}

Every key but failRun is a budget; at least one budget must be present (a thresholds object holding only failRun is rejected the same way an empty one is - it names nothing to judge). An unknown key, a non-numeric or out-of-range budget value, a non-boolean failRun, or an object that declares no budget is a 400 invalid_run_config naming the field - and, like every other run-config rejection, it happens before the run row is created, so a rejected request leaves no trace. A null value reads as absent, the same rule the flat numeric fields follow.

maxErrorRatePct is measured against every response outside 2xx/3xx plus the transport failures that never got one - the one error definition, the same figure summary.errorRate reports and the live tick streams. A request a Stop cancelled is in neither its numerator nor its denominator.

maxAssertionFailureRatePct (issue #1497) is measured against two populations a load run keeps apart (issue #2892). The exact one is every assert.* element outcome, every required extract.* that found no match and every pm.test call an inline script made, counted on every completion. The sampled one is the deferred pm.test replay, run over responses sampled at 1 in response_sample_rate (default 100) - the same tallies the report's testValidation shows. That is a sampling period, not a promise about the count: on a long run the max_response_samples reservoir cap can make the replayed set sparser than 1 in response_sample_rate. actual is the worse of the two failure rates, each 0 when its population is empty, so a sampled pm.test failing half the time beside an inline assertion that never fails reads 50%, not the fraction of a percent a single blended count would give; the budget fails when either population crosses it. The check names both populations, so a reader can see which one the verdict came from:

{ "metric": "maxAssertionFailureRatePct", "limit": 10, "actual": 50.0,
  "passed": false, "evaluated": true,
  "assertionsExact":   { "passed": 2270, "failed": 0 },
  "assertionsSampled": { "passed": 12, "failed": 12 },
  "sampleRate": 100 }

assertionsExact and assertionsSampled are both written on an evaluated assertion check, an empty population as {passed: 0, failed: 0}; sampleRate (the period the replay ran at, keep 1 in N) is written only when assertionsSampled is non-empty. No other check carries these keys, and a check stored before issue #2892 has none of them: its actual is the old blended rate and nothing is backfilled. Unevaluated, like a latency percentile, when the run made no assertion at all - a run with no assert.* element and no test script is unaffected by declaring this budget - and then the population keys are absent too, as actual is.

streamTimeToFirstEventP95Ms and streamEventsPerSecondMin (issue #3234) judge a streaming run's stream section: timeToFirstEvent.p95 and eventsPerSecond, the same figures the report prints. Both are unevaluated, and so count toward failed, on a run with no stream section (one that did not stream, or ran with stream_metrics: false), because a run that streamed nothing measured neither; a floor read as 0 there would fail for the wrong reason. The time-to-first-event budget is also unevaluated when no completion delivered a timed event.

Every run mode is judged (issue #1564): a single-request load run, a scenario load run and a collection (sequential, design-mode) run all evaluate the same thresholds block against their own numbers and store the same thresholdValidation shape. A collection run's error rate and latency percentiles are drawn from the steps it actually sent (a step a script or an unbound data row skipped counts toward neither), and its assertion tally, every assert.* outcome and pm.test call of every step it ran, is all exact: a collection run runs each step's scripts on every send, so its assertion check carries assertionsSampled at zero and no sampleRate. Since a script error no longer ends the iteration (issue #2526), the steps after one are sent and counted too, so the same collection can report a larger denominator than it did before; stopOnError: true restores the old population.

custom.<name>.<stat> (issue #1500) budgets a named metric.record / pm.metrics value - <name> the metric was recorded under, <stat> one of p50, p95, p99, max (a trend), value (a counter's running total or a rate's percentage, whichever the name was declared as) or rate (the same field as value, spelled for a rate metric):

{ "thresholds": { "custom.ttfb2.p95": 50 } } // ceiling, always - >= 0

Unlike the fixed keys, this is a dynamic key family: the route checks the shape (custom. prefix, a non-empty name, a stat from the list above) and that the value is a non-negative number, not that ttfb2 is a name this run's plan actually declares - a metric.record on a step the run never reaches, or a plain typo, is not distinguishable from a not-yet-recorded metric at validate time. Evaluated the same way an unmeasured latency percentile is: evaluated: false when this run's collector never recorded that name, counted toward failed rather than a silent pass. The test is the entry's count (records, not the total - see customMetrics), so a counter nothing recorded through is unevaluated while a counter recorded only by zero is evaluated with actual: 0, which is what lets {"custom.failures.value": 0} pass a run that saw none (#1937). A counter never goes negative: pm.metrics.counter throws on a negative or non-finite increment, and metric.record reports error for one and records nothing. Every run mode is judged, the same rule the fixed keys follow (#1564): execute_scenario_run folds summary.custom_metrics into the same RunSummaryInputs it evaluates thresholds against for a collection (sequential, design-mode) run, not only a load run.

The verdict is the run's, not the process's: a run stopped early is judged on what it measured up to that point, and its status stays stopped whatever the verdict says. The app says so on a stopped run, under the verdict's counts, with how long the run went against how long it was planned for. A run that reached its own end whose config set thresholds.failRun: true and whose budgets it missed ends failed instead of completed; without the flag, or on a run that met every budget, a failing budget is reported but never changes the terminal status. Only a Stop that decided the outcome (one before the strategy returned) makes a run stopped: a Stop that cuts the natural-end drain short leaves the run to its own end, so failRun still judges it (issue #3341, see POST /runs/:runId/stop). The requests that Stop cut are the run's slowest and are in none of its figures, so its summary records them as drainCut (#3538) and a reader judges the run not judged unless a budget already failed it; the stored verdict here is still the budgets' own.

Each check carries evaluated. A latency percentile needs a timed request to mean anything, so a run that recorded none (every request was refused before the wire, cancelled by a Stop or failed before any transfer ran) reports evaluated: false and omits actual entirely rather than the default 0, which would otherwise read as a measured 0ms and trivially satisfy an "at most" ceiling. A request that timed out or lost its connection after the transfer began is timed (see Latency population), so a run where every request timed out is evaluated and its percentiles sit at the timeout. An unevaluated check counts toward failed: a budget the run could not measure was not met. The error rate is the same: a run that sent no request has no share to take, so maxErrorRatePct is evaluated: false there (issue #3540) rather than a clean 0% that passes any ceiling, including 0. The throughput floor has no such gap - a starved minThroughputRps already fails on its own - so it is always evaluated: true.

Carried-over budgets (carriedBudgets)

thresholds says what a run was judged against, not who chose it. The app seeds its load dialog's budgets from an earlier run's (or from the SLO setting), so a budget can reach a run the user never set it for (issue #2195). carriedBudgets is the app's record of which: an array of the thresholds keys it sent as carried over rather than set for this run, spelled as they are in that block - a fixed budget key such as latencyP99Ms, a custom row as custom.<name>.<stat>.

{
  "thresholds": { "latencyP99Ms": 200, "maxErrorRatePct": 1 },
  "carriedBudgets": ["latencyP99Ms"]
}

The engine stores the list in the run's config snapshot as sent and echoes it as the report's metadata.configuration.carriedBudgets; it never reads the entries, so it does not check them against thresholds, and the verdict is computed the same with or without it. Absent or null means none were carried, and the report then has no such key. A non-array, a non-string entry, more than 64 entries, or an entry longer than 512 bytes of UTF-8 is a 400 invalid_run_config naming carriedBudgets, before the run row exists. MCP's start_load_run does not accept the key: an agent declares its budgets explicitly, so none of them are carried over.

The elements block (element-pipeline override)

A scenario load run's elements block overrides how the element pipeline runs across every step of the run (issue #1495), without editing the collection itself.

{
  "elements": {
    "timers": "asConfigured",     // "asConfigured" (default) | "off" | {"fixedMs": N} | {"minMs": N, "maxMs": N}
    "scripts": "asMarked",        // "asMarked" (default) | "allInline" | "allDeferred"
    "includeScriptTime": false,   // default false
    "seed": 42                    // Optional, non-negative integer - seeds this run's RNG
  }
}

Every key is optional; an unknown key or an out-of-set value is a 400 naming the field, the same invalid_run_config shape the scenario block's own unknown-key rule uses, checked before the run row is created.

  • scripts decides whether a script.pre / script.post element runs inline (on the producer/completion hooks, before or after the step's own send) or stays deferred to the post-run tests replay. "asMarked" (the default) reads each element's own config.inline; "allInline" / "allDeferred" force every script.* element of the run one way, regardless of its own marking. extract.* and assert.* are unaffected - they always run inline on a scenario load run.
  • includeScriptTime folds the element pipeline's own elapsed time into a step's recorded latency when true, and into the run's latency figures with it (latency, the per-tick percentiles and a stored result's latencyMs), so the run's max is never below a step's (#2792); by default (false) both are the transfer alone. A stored trace's totalMs, the per-phase timings and the slow_threshold_ms decision stay on the transfer either way.
  • timers (issue #1498) is wired end to end: "asConfigured" (default) runs every timer.* element's own stored config unchanged; "off" silences every timer.* element for the run (waitedMs: 0, no sleep); {"fixedMs": N} or {"minMs": N, "maxMs": N} replace every timer.* element's own computed wait with the same fixed value or uniform range, whatever that element's own config says - "replaced, not merged", the same rule scripts above uses. timer.think's step.between phase now dispatches on a scenario load run too (non-blocking, summed into VirtualUser::ready_at_ms), so this override reaches load runs as well as the sequential run. timer.pacing and timer.throughput schedule their wait before that step's ElementContext exists at all (Element::scheduled_ready_delay_ms, see Load paths); every mode reaches them there too, through the run's own copy of the override (SharedScheduleState::timers_override, issue #1620), so a run with timers: "off" defers neither kind under load and a run with "fixedMs" or {"minMs", "maxMs"} schedules their wait from that value rather than the element's own everyMs / targetPerMinute.
  • seed (issue #1498) is an optional non-negative integer that seeds this run's RNG, making a timer.think element's gaussian or uniform-random wait reproducible. A scenario load run derives one independent generator per virtual user from this seed rather than sharing one across worker threads. Omitted, the run seeds from std::random_device as before, and every draw is non-reproducible.

Not reported at the run-summary level: there is no summary.timers aggregate. What a timer.* element waited is per-step, per-element - waitedMs on that element's entry in the step trace's elements array (see The step trace) - not rolled up into GET /runs/:runId / the completion report's summary object.

Not part of this block: a single-request POST /runs payload's step-level attachment point is the separate requestElements array below, not this one - this block is accepted on either run shape (the validator does not distinguish them), and on a single-request run it overrides what requestElements declares, the same way it overrides a scenario's stored elements. The run's own boundary, script.setup / script.teardown, is a third array again, lifecycleElements, further below.

The requestElements array (a single-request run's own step-level elements)

A single-request POST /runs payload's own place to attach step-level elements to the one request it sends (issue #1594): before this, a single-target load run ran no element pipeline at all, so the same request's extract.* / assert.* / timer.think / script.* elements that run in a design send, a sequential collection run, and a scenario load run's steps never ran under a single-target load run. An array of element descriptors, the same shape a request's own stored elements column holds:

{
  "requestElements": [
    { "kind": "script.pre", "config": { "script": "pm.request.headers['X-Sig'] = sign()", "inline": true } },
    { "kind": "assert.status", "config": { "in": [200] } },
    { "kind": "script.post", "config": { "script": "pm.test('ok', function () { pm.expect(pm.response.code).to.eql(200); })" } }
  ]
}

Validated the same way a stored elements column is (Registry::validate per entry, a bad kind or config a 400 naming the index); id and enabled are optional, defaulting to a generated id and true. The list may be a composed one, so an id is unique only within the level that declares it (the origin kind, scope and id POST /compose stamps; an entry with no origin is the request's own level), and may repeat across levels, the same per-level id rule as POST /execute (#3101): a duplicated collection, or a folder repeated down a chain, repeats its ids. The owner rules differ: every level here is judged as a request's own list, so a collection-only kind stays refused (below) where /execute accepts it at a collection level. A repeat within one level is a 400, and the Item N in a refusal counts within that level's entries. Refused outright beside a scenario block, whose steps already carry their own resolved elements from the plan. This is the field MCP's start_load_run renames a composed request's chain-then-own elements onto, since POST /compose answers under the plain elements key and this endpoint's own elements key means something else (the override block above) - see mcp.md.

Only the kinds this run shape's own hooks actually dispatch are accepted: extract.*, assert.*, timer.think, script.pre/script.post - the same phase-0 set issue #1514 gave the design send (extract.* includes extract.header). A control.* or metric.* kind or timer.pacing/timer.throughput is a 400 naming the element by its kind label and where it was declared (from the collection 'Orders' for a collection or a folder under it, set on this request, read from the entry's origin; element '<id>' for an entry that carries none) - not by position, because a composed list interleaves inherited elements with the request's own (#3050). It is never silently accepted and left inert: those need per-VU controller and pacing state (controller_state, SharedThroughputCounters, pacing_state) this run shape's single-submission model has no equivalent of, and admitting one without running it would report "ok" in summary["elements"] for behaviour that never happened. Run a sequence that needs a controller as a "scenario" instead, where its steps carry that state. A disabled entry ("enabled": false) is not refused: the pipeline skips it before its apply runs, so a switched-off pacing timer inherited from a collection does not block the run. It is still validated like any other entry, so a malformed config fails now rather than when it is switched on.

A collection-origin script.setup / script.teardown is refused as a request's own (#3070). POST /compose emits an enabled collection's or folder's run-boundary scripts stamped origin.kind: "collection", but this array is validated as a request's own list and Registry::validate refuses the two kinds there: they belong to the collection's own run (or to lifecycleElements, below), not to one request's submission. The app's load dialog and MCP's start_load_run leave them out of the payload they build, so only a hand-written client sees the 400.

vayu::core::ElementPipeline runs the compiled list per submission, the same phases a design send uses: script.pre at step.before, extract.* / assert.* / script.post at step.after. A script.* element runs inline only when marked or forced. Unlike a design send or a sequential collection run, a load submission has no persistent per-VU object to defer a script onto, so a script.pre or script.post element runs inline, per submission, only when its own config.inline is true or this run's elements.scripts override (above) is "allInline"; left unmarked with no override, script.post still runs, but deferred - on the run's completion replay, the same way a plain tests string used to - while script.pre simply never runs at all, because there is no pre-request replay to defer it to. RunContext::script_element_runs_inline is the one place that decision is made, shared with the scenario load path's own step dispatch. timer.think's wait is folded into maintain_concurrency's own backpressure (RunContext::reserve_think_wait) rather than a blocking sleep on a worker thread, so a request-level timer costs no new thread the way the scenario load path's per-VU wait does. That is the closed loop only: every mode but constant_rps. A constant_rps run skips timer.think (#3541): its pacer sends on a schedule, so there is no next request for a wait to hold back, and a reservation would only fill maxInFlight with slots no request holds, dropping arrivals and inflating peakConcurrency. The element is tallied skipped in summary["elements"], nothing is reserved, and the report carries one think_timer_skipped_open_loop warning. The element is not refused, because an inherited timer would then block load-testing every request under its collection in the default mode.

A script.pre element's edits reach the wire, and its scope's writes reach later {{tokens}} in the same submission. When a run's submissions are copied (its requestElements hold a script.pre, or sit beside data rows, a token the bind owns or a credential waiting on the scripts; see POST /runs for the shared-request run that is not), each submission resolves against a small, request-scoped variable overlay (vayu::http::routes::ScopeOverlay) layered over the run's flattened base scopes, and the residual-token pass (resolve_residual_tokens, Request composition) runs against that view before the transfer - so a pm.environment.set (or a pm.request edit) an inline script.pre makes is visible to any {{token}} compose left written on that same request (one it could not answer, or one it deferred past the script, #2521), the same guarantee a scenario load run's per-VU overlay gives its own steps. Nothing shares this overlay across submissions - each one gets its own, discarded after - which is what keeps many concurrent submissions from writing through one shared map.

An inline element's pm.info carries the run's request identity (#3460). bind_submission_identity (load_strategy.cpp) binds the submission's iteration, its virtual user (1) and its data row (#3124), and the run's requestId / requestName, resolved once when the run starts by the same read_run_script_identity (run_manager.cpp) the deferred replay reads - the payload's own fields, the linked row's name when only an id was sent. A run started from no saved request reads both as undefined, inline and deferred alike.

The lifecycleElements array (a single-request run's own setup/teardown)

A single-request POST /runs payload's own place to declare script.setup / script.teardown (issue #1573): it has no collection row to declare them on, and the elements block above is a per-step override, not a place to author new behaviour. An array of element descriptors, the same shape a collection's own elements column holds:

{
  "lifecycleElements": [
    { "kind": "script.setup", "config": { "script": "pm.environment.set('token', 'x')" } },
    { "kind": "script.teardown", "config": { "script": "pm.sendRequest(...)" } }
  ]
}

Restricted by kind to the two elements that dispatch at a run's own boundary rather than a step's - any other kind is a 400 naming the index and the kind, not silently ignored or run as if it were one of the two. Each entry's config is validated against that kind's own schema (the same Registry::validate a collection's elements column is checked against); id and enabled are optional, defaulting to a generated id and true. Refused outright beside a scenario block - a scenario collection already has a real elements column for this, so declaring both would be two sources of truth for the same run boundary.

script.setup runs once, before the run's first submission (before test_start is captured, so its own time is never folded into the run's duration figures, live or stored: the live stream's elapsedSeconds reads 0 until it ends); a throwing setup, or one that fails a pm.test, fails the run - Failed, nothing sent, its outcome under the report's lifecycle.setup - the same as a collection-backed run. script.teardown runs once, after the last submission settles, and sees pm.info.run (requestsSent, errorRate, assertionsPassed, assertionsFailed); a throwing teardown is recorded under the report's lifecycle.teardown and never changes the run's terminal status. Both read and write the same variable scopes every other script of the run shares - the environment named by environmentId, and the collection scope of the request requestId links, when the run links one, else of the composed collectionId (issue #3461); a bare URL run naming neither gets no collection scope. Unlike a collection-backed run, script.setup / script.teardown alone do not make what a script writes reach the request: the stored values do, through the start-of-run pass (POST /runs, #3253), but that pass runs before script.setup, and the residual-token pass (see above) runs only on a run whose submissions are copied. So a pm.environment.set in script.setup reaches a later {{token}} only when the run declares requestElements and its submissions are copied (a script.pre among them, or data rows, a token the bind owns or a credential waiting on the scripts beside them); a run whose requestElements only read the response sends the stored value. With lifecycleElements alone, pm.sendRequest (external side effects) and the lifecycle outcomes in the report are the only things observable from this run shape's own script.setup/teardown. See elements.md for the shared dispatch mechanism a collection-backed run uses for the same two kinds.

The monitor block (server vitals)

A run may name a metrics endpoint on the target, which the engine scrapes for the life of the run on its own thread. The samples are stored per run and served by GET /runs/:runId/monitor, streamed live as monitor frames on GET /runs/:runId/live, and summarised in the report's monitor section. Without the block nothing is scraped and none of those three carry anything.

Only a load run reads the block. A scenario payload with no load mode is a collection run, which has no scrape lifecycle, so it is refused (below) rather than accepted and never scraped; add a mode beside scenario to scrape.

{
  "monitor": {
    "url": "http://localhost:9100/metrics",  // required; http(s), loopback and private allowed (not Vayu's own ports)
    "intervalMs": 1000,                      // optional, defaults to `monitorIntervalMs`; 250-60000
    "format": "prometheus",                  // optional, default "prometheus"; or "json"
    "series": [                              // required; 1 to `monitorMaxSeries` names
      "node_cpu_seconds_total",
      "process_resident_memory_bytes"
    ]
  }
}

format decides how the body is read:

  • prometheus - the text exposition format. Comment and blank lines are skipped, a trailing exposition timestamp is ignored, and a value that is not a finite number (NaN, +Inf) is dropped. Series are matched by name, and samples sharing a name across label sets are summed, so node_cpu_seconds_total{cpu="0"} and {cpu="1"} chart as one series. A series entry is therefore a bare name: one holding a { (a label filter such as http_requests_total{code="500"}) or whitespace could never match, and is refused (below).
  • json - a flat object of numbers, where series lists the keys to read. A key that is absent or non-numeric is skipped. A key may hold any character, { and spaces included.

A name the body does not carry is absent from that sample rather than zero. A scrape that reads nothing at all stores no row and sends no live frame, and the report counts it under one of two causes, because they need different fixes:

  • a failure (monitor.failures) - no 2xx answer: a transport error, a timeout, or a status outside 2xx. monitor.lastError names the most recent one's cause.
  • a no-match (monitor.noMatchScrapes) - a 2xx answer whose body carried none of the requested names (a mistyped name, or a body in the other format). The endpoint answered; what it was asked for is wrong.

Neither fails the run. After five consecutive failures the engine logs once and backs off to twice the configured interval until a scrape is answered; a no-match is an answer, so it ends the backoff rather than extending it. A scrape still in flight when the run ends is cancelled rather than waited out, and counts as neither.

Three of the limits are settings rather than constants: intervalMs defaults to monitorIntervalMs when the block omits it, the series ceiling is monitorMaxSeries, and how long a single scrape may take is monitorScrapeTimeoutMs (see GET /config). All three are read per run, so a change applies to the next run started - no restart. The interval bounds are fixed, because a cadence below 250ms measures the scraper rather than the target and one above a minute records nothing on a short run.

The scrape budget has no field on the block: it is about the endpoint being scraped, which is the same one run after run, so it lives with the other engine settings. Left at its default of 0 it tracks the cadence at three quarters of it - raise it when a heavyweight /metrics renders too slowly for that, and the cadence stays where you set it.

Loopback and private addresses are deliberately allowed: this is a local tool scraping the user's own infrastructure. The one exception is every outbound path's: the engine's own port and the MCP port are refused (Reserved local ports). An unusable block (no url, a non-http(s) scheme, no series, more than monitorMaxSeries, an out-of-range intervalMs, an unknown format, or under prometheus a series name holding a { or whitespace) is a 400 invalid_run_config naming the field, before the run row is created.

A monitor block beside a scenario that carries no load mode (absent, empty or not a string) is likewise a 400 invalid_run_config naming 'monitor'.

A run carrying a targetPolicy is held to it here too: the url's host must be one the policy allows, or the run is a 400 under target_not_allowed / target_host_unknown naming monitor.url, before the run row exists (#3121). The URL is judged as the scrape will send it, so a \ in it counts as the / it is sent as. Loopback and private hosts get no exemption from a policy; without one, "Loopback and private addresses are deliberately allowed" above is the whole rule.

The scenario block (collection runs)

A run may instead state its work as an ordered collection - the collection runner's sequence primitive. The block replaces the single request, so a payload carrying it needs no top-level method / url, and states its iteration count inside the block rather than through mode / duration / iterations:

{
  "scenario": {
    "source": "collection",         // required; the only accepted value today
    "collectionId": "col_123",      // required
    "recursive": false,             // optional, default false - descend into sub-collections
    "iterations": 1,                // optional; defaults to the data row count, else 1
    "data": [ { "user": "a" } ],    // optional inline rows; see maxScenarioDataRows
    "dataFileName": "users.csv",    // optional, only beside data: the file's display name, never a path
    "dataFileHash": "<sha256>",     // optional, only beside data: SHA-256 of the file's bytes, 64 lowercase hex
    "dataFileCastNumbers": true     // optional, only beside data: the file's numbers were read as numbers
  },
  "environmentId": "env_123",       // optional, and what {{variables}} resolve against
  "stopOnError": false              // optional, default false - see Outcomes under Scenario runs
}

The collection is resolved into an ordered, fully composed plan once, before anything is sent, in the order the sidebar displays top to bottom: direct requests by requests.order and - with recursive - each collection's sub-collections and requests as one sibling list, depth-first, a request running where it sits and a sub-collection's whole subtree where the sub-collection sits, under the sibling order in Ordering (a sub-collection first on an order tie). The run follows the render (issues

431, #2535). Each step is

composed through the same path POST /compose uses, so a step's request and its resolved elements (every collection, folder and request level's scripts, each run in turn and each reported with its level, #2522) are what a Send of that request would run. A collection edited mid-run therefore cannot change the sequence underneath itself, and no execution path re-reads the database for request data.

A valid block answers 202 {runId} and creates a run with type: "scenario" - unless a load mode sits beside it, which makes it a scenario load run with type: "load" instead. The lifecycle is a load run's either way - the run is registered, streams over GET /runs/:runId/live, stops through POST /runs/:runId/stop and reports through GET /runs/:runId/report - and only the executor differs. See Scenario runs below for what it does while it runs and what it leaves behind.

Every rejection is a 400 with error.code: "invalid_scenario", raised before any run row exists - an empty or oversized sequence is never silently run as a smaller one:

Input Rejected because
source absent, or anything but "collection" The discriminator exists for a future stored scenario; an unknown value must not fall through to the collection path.
collectionId absent, not a string, or empty There is nothing to resolve. The id is echoed back when it names no collection.
The collection (with recursive applied) has no requests An empty sequence is a mistake, not a zero-step run.
A step's composition fails The message names the step index, request name and id.
More steps than maxScenarioSteps The whole plan is held in memory for the run's life; the message carries the count and the cap.
recursive present and not a boolean
iterations present and not a whole number in 1-2147483647 It is read as a count, so 0, a fraction and a string are each a run nobody asked for.
data present and empty A data set that binds nothing is a mistake - omit the field to run without one.
data not an array, or a row that is not an object
More data rows than maxScenarioDataRows The message carries the count and the cap.
A data cell nested deeper than 100 levels (constants::spec_document::MAX_READ_DEPTH) Refused before the row is measured or kept, because both recurse and a cell nested far enough overflows the stack (issue #2362). The message names the row and the column: 'scenario.data' row 1 column 'tag' is nested deeper than 100 levels. The check runs right after the body is parsed and whatever shape data has: a row that is not an object but is itself nested that deep answers 'scenario.data' row 1 is nested deeper than 100 levels, and a data that is not an array, nested that deep, answers 'scenario.data' is nested deeper than 100 levels. A wrong shape within the bound keeps the refusals above. A cell nested exactly 100 levels is accepted.
A data array larger than maxScenarioDataBytes The row count cannot catch a few very large rows, and the engine's general body cap (Request bodies) sits far above this and refuses a whole payload without naming what in it was too large.
A step carrying a {{data.*}} token in a run sent without data Nothing would bind it, so the literal token would be sent. The message names the step and the token. The step's credential fields are scanned as well as its request.
A step with a {{data.*}} token (or the iteration identity) in its oauth2 config The token is acquired against the token endpoint (once, when a load plan is resolved; at the step's send in a sequential run), never bound per iteration, so no iteration exists for a row to reach it. Refused with or without a data set.
A step of a collection load run with a {{name}} in its oauth2 config that no variable answers (invalid_scenario; a single-request run is refused the same way under invalid_run_config, see Auth pre-flight) A load run acquires each step's token once, when the plan is resolved and before any script runs, from the stored values, so the name would reach the token endpoint as written. A script's write to an OAuth 2.0 variable is ignored under load and nothing is re-acquired per iteration (the only change after the start is each step's mid-run refresh). The message names the step and the token (#2521, #2742). A sequential run defers such a name to its step's send instead.
A step whose OAuth 2.0 token endpoint host the run's targetPolicy refuses Judged before the endpoint is posted to. The code is the policy's, target_not_allowed or target_host_unknown, not invalid_scenario (#2521).
dataFileName or dataFileHash present and not a non-empty string, or dataFileHash not 64 lowercase hex characters Stored verbatim as what the run was driven by (issue #2051), so a value that cannot name a file, or a second spelling of one digest, is refused rather than recorded.
dataFileName or dataFileHash sent without data It would describe rows the run never bound - refused, not ignored (issue #1503).
dataFileName holding a / or \ A display name, never a path (issue #2051): a path would be stored and listed back to every reader of the run. Send the file's name alone.
dataFileCastNumbers present and not a boolean, or sent without data (false included) How the client read the file (issue #2540), stored beside its name and hash; on the same rules, so a value that is not an answer, or one describing rows the run never bound, is refused rather than recorded. null is absent.
A scenario key other than source, collectionId, recursive, data, dataFileName, dataFileHash, dataFileCastNumbers, iterations An unrecognised key used to change nothing and still answer 202 (issue #1503) - refused by name so a typo or a knob a future engine reads is never silently ignored.

A cycle in the collections.parent_id tree terminates the recursive walk rather than hanging it, exactly as the cascade delete in DELETE /collections/:id does.

Five settings bound a scenario (see GET /config). Four are in the limits category, which is where a ceiling that rejects an oversized input lives; maxScenarioStoredSteps is data_retention, because it bounds what a finished run keeps rather than what one may ask for:

Key Default Range Effect
maxScenarioSteps 200 1-10000 Largest plan one run may resolve to. The sequence is composed up front and held in memory, and a load-mode scenario allocates a latency histogram per step, so this bounds memory rather than expressing a preference.
maxScenarioDataRows 1000 1-1000000 Largest inline data array. The app parses the CSV/TSV/JSON/JSONL file and sends the rows - the engine never reads a file from disk - so this bounds the payload that decision costs.
maxScenarioDataBytes 16777216 1024-104857600 Largest inline data array measured in bytes of JSON. The row bound alone does not bound the payload, since one row may hold a megabyte in a single cell.

| maxScenarioStoredSteps | 5000 | 0-1000000 | Per-step results rows one run stores; 0 stores every step. Steps that did not pass are kept first, successes fill the rest, and what was thinned is reported in the run summary. | | maxStepsPerIteration | 0 | 0-1000000 | How many steps one iteration may execute before it is cut off. pm.execution.setNextRequest can send an iteration backwards, so a cycle would otherwise run forever. 0 derives the bound from the plan - ten times its step count, never below 100 - so a straight-through iteration can never trip it. |

The two data bounds are also enforced by the app before the run, against the file it is about to parse, so a set this endpoint would refuse is named while the file can still be changed. The file format those rows come from - which extensions are read, the header row's rules, quoting, encoding, and what a CSV cell's type becomes - is the app's contract and is documented once, in Data-Driven Runs. This endpoint only ever receives rows.

Scenario runs

A scenario run executes every step of the plan, in order, once per iteration. Each step is the POST /execute exchange - pre-request script, send through the environment's cookie jar, test script - so a step behaves exactly as a Send of the same request does, and the two cannot drift apart.

What carries between steps.

  • Variables. The environment, globals and collection scopes are loaded once at run start, mutated in memory by every step's scripts, and written back once, when the run ends (through the same diff that keeps a Send from rewriting a scope no script touched). The collection scope is each step's own (#3248): the chain from the root collection, through the collection being run, down to the folder the step's request sits in, that folder the one a script's pm.collectionVariables.set writes, as on a Send of the same request. Each collection is read once, so what one step writes into a folder is what a later step in that folder, or in a folder below it, reads; a sibling folder does not see it. A script.setup and script.teardown read and write the collection that declares them (#3456): the run's lifecycle set is every collection from the root down to the one being run and, on a recursive run, every folder beneath it, set up root first and torn down in reverse (see lifecycle under GET /runs/:runId/report). Every collection a script changed is written back to its own row in the one write at the end, which comes after script.teardown (#3249): a teardown's pm.environment.set / pm.globals.set is saved with the steps' writes. A load run persists no variable, a teardown's included.
  • Cookies. The environment's jar, unchanged - so a step that logs in leaves a session the next step sends.

A plan in which anything can write a variable resolves its {{names}} at each send (issue #2521). The plan is composed once, at run start, and its sequence stays fixed for the run. When any step of it carries an enabled, non-blank element that writes a variable scope before some send - a script.pre, a script.post (a test script), a script.setup, or any extract.* kind, on the request, a folder above it or the collection; a script.teardown alone does not count, because it runs after the last send - every step keeps each name a scope answers written, scripted or not, and each iteration resolves them immediately before that step's send, against the scopes as every script and extractor up to and including the step's own pre-request script left them, read through the step's own folder chain (#3248), so a sub-folder's {{name}} in a recursive run is its folder's value. That is Postman's order: a login whose test script or extractor stores a new token is followed by a step whose Bearer {{token}} carries that token, on every run and every iteration, and not the one the environment held when the run started. The same four kinds of name as in deferredVariables still resolve at composition, and an OAuth 2.0 config defers only on a sequential run (a load run acquires its token at plan time).

A plan with no such element is resolved once, before the first send, exactly as before: a name that already had a value when the run started is fixed for the whole run, which is what keeps a collection edited mid-run from changing the sequence underneath it.

A name composition could not answer (issue #1008) is resolved the same way. Since #1009 that name keeps its braces instead of resolving to "", so each step resolves it again, immediately before that step's own send, against the scopes as every script up to and including that step's own pre-request script left them - not just through pm.environment.get(...) and a pm.request edit, though a script can still reach it that way too. That is what lets a step early in the plan fetch a token and a later step's Bearer {{token}} carry it with no script of its own. A step's own request holds one search per field, and a plan where every name was already defined at run start and nothing writes a variable pays that and nothing else.

The exceptions are the two reserved namespaces below, which neither pass touches: {{data.*}} and the {{$vu}} / {{$iteration}} identity (issue

994). Composition leaves both alone so the runner can bind them per

iteration, and neither is a name any script scope answers either. A bare name the run's dataColumns names travels the same way (issue #1007): composition defers it exactly as it defers {{data.*}}, and the per-row bind substitutes it before the step's pre-request script ever runs - so neither pass sees it unresolved, and neither can answer it from a same-named environment variable instead of the row.

Scripts additionally read pm.info.iteration (0-based), pm.info.vu (1-based) and pm.info.iterationCount. See scripting.md for which run shapes report which.

A run with data binds one row per iteration. Row i % rows binds to iteration i, and the run's scripts read it as pm.iterationData - get(name) and toObject(), read-only, and undefined for a run sent without data. With iterations absent the row count is the iteration count; with both given the explicit count wins and the index wraps. The rows reach the run's worker and nowhere else: they are not persisted, and the snapshot records the row count (dataRowCount) plus the file's dataFileName and dataFileHash when they were sent, and dataFileCastNumbers: true when its numbers were read as numbers, never its path or rows. The full contract is in scripting.md.

{{data.column}} puts the row into the request itself. pm.iterationData is read after a step's request was built, so it cannot change where the request goes; the data.* namespace can. A step whose URL, header or body carries {{data.email}} has it substituted with that iteration's row, per iteration, immediately before the send. A form-data part's contentType binds the same way, on a text part as on a file part.

The {{data.column}} spelling is reserved and disjoint from the variable tiers - not a fourth, higher tier. {{data.id}} and {{id}} are different names, so a data set can neither shadow nor be shadowed by a global, collection or environment variable through that spelling, and adding a data file to an existing collection cannot change what its other tokens resolve to. Composition (POST /compose, and the plan resolution that shares it) leaves a data.* token written exactly as it stands for that reason; {{data.}} with no column after it names nothing and follows the ordinary unknown-name rule instead.

A bare column name is a second, different rule and it is a tier (issue

1007). Postman binds a dataset's columns to bare names, so an imported

data-driven collection is written {{username}} rather than {{data.username}}, and while a row is bound that row's own bare column names answer above the active environment - see D18 in variable resolution for the full ladder and the tradeoff it makes against #402's guarantee above. Which bare names a bind owns is not global - it is stated per composition, as the dataColumns field, or filled by the engine itself where it already knows the dataset (a scenario plan's steps, a single-request load run, a send carrying one row). A bare name not in that set resolves as an ordinary variable, exactly as it did before this rule existed; only a name the set names is deferred by composition the way data.* always was, for the run's per-row bind (core::apply_data_template) to join through the identical walk - the same escaping, the same missing-column and null-cell refusals, the same header rules, for either spelling. There is no second, looser substitution path for the bare one.

Where a token participates. Exhaustively, and identically for both spellings: the URL (path and query string alike, so a token in a stored request's params reaches it once they are joined into the URL), every header name and header value, the raw body, both halves of every form field (x-www-form-urlencoded and form-data), and the credential fields of the request's auth - the bearer token, basic auth's username and password, and an api key's name and value. Script text is never interpolated at all (a script reads its row through pm.iterationData, or through pm.variables for a bare name - see scripting.md).

The pass runs over the composed text, not the text as it was authored, so a token that arrived as a variable's value binds like any other: a variable endpoint whose value is /u/{{data.id}} leaves {{data.id}} in the URL after composition - it is rescanned since issue #1009, but the data. namespace is deferred to bind time (issue #1007), so this token survives it - and the data pass then binds it. That is usable, and it is also why the no-data refusal below says "or from the variable value it was written into" - the token it names may not appear anywhere in the request as you wrote it.

{{$vu}} and {{$iteration}} are the second reserved namespace (issue

994), and they bind at the same moment out of the same walk - a field carrying

one of each is one string, so both are split once and joined together. They need no rows behind them: {{$vu}} is the virtual user's own 1-based number in a scenario run and 1 in every other shape (one request repeated is one user's iterations, whatever the concurrency), and {{$iteration}} is that user's 0-based iteration, the submission index on a single-request run, and 0 on a plain POST /execute. A variable named $vu does not answer for the identity, for the reason a variable named data.id does not answer for the column, and {{$vus}} is an ordinary unknown $name that keeps its braces. They bind everywhere a data.* token does, credential fields included (issue #1055): a credential carrying either name defers its build and is bound before apply_auth encodes it, on every run shape rather than only on one carrying rows, because the identity comes from the iteration rather than from a row. A credential that also holds a name only a variable scope answers takes the row first and is applied after the pre-request script (#2473), on every send that runs one (see Authentication). An OAuth 2.0 config is the exception and is refused by name - its token is acquired before any iteration exists.

A run binds only what it was given rows for. A POST /runs carrying scenario.data binds per iteration, one carrying the top-level data binds per submission, and a POST /execute carrying a data object binds that one row. A request sent without rows performs no data pass at all, so a {{data.*}} token in it reaches the wire as the literal text {{data.id}} - no substitution, and no warning, since composition leaves the reserved namespace written as it stands by design. The no-data refusal below is the scenario path's alone: a single request has no plan to refuse before it starts, so a raw API or MCP caller putting {{data.*}} into one without rows is asking for the literal braces and gets them.

Credentials bind before they are encoded. A credentials file behind basic auth is the canonical data-driven run, so a step whose credentials carry a {{data.*}} keeps them unresolved in the plan and applies its auth per iteration instead: the row is bound first, and only then does the username and password become one base64 Authorization, or an api key become a percent-encoded query parameter. Every other step still resolves its auth once, when the plan is composed.

OAuth 2.0 is the exception, and it is refused rather than ignored. Its token is acquired against the token endpoint, never bound per iteration, so no iteration exists for a row to reach - a {{data.*}} anywhere in an oauth2 config is a 400 at POST /runs naming the token, with or without a data set. A sequential run acquires a step's token at its send, after the step's pre-request script, so an oauth2 config naming a variable the script sets resolves then; a collection load run acquires once at planning and refuses a name nothing answers.

Which columns a collection expects is a separate, declared thing - see dataSchema under Collections and Data-driven runs. Declaring it changes no binding rule; it is what lets the refusal above name the columns, and what the app checks a picked file against before the run.

What a cell renders as. The CSV/TSV path produces strings unless the file opted into number reading (#2540), so the first row is the ordinary case; a JSON or JSONL file may carry any type:

Cell Substituted text
String The string, byte for byte - no quoting round trip
Number As JSON writes it: 7, -1.5
Boolean true / false
Object / array Compact JSON: {"a":1}, [1,2]
null Nothing - the bind errors instead, see below

Placement is typed, and that is the point. In a JSON body, a token written inside a string literal produces a string and a token written outside one produces the value's own JSON type:

{ "id": "{{data.id}}", "n": {{data.n}}, "flag": {{data.flag}} }

sends "id":"42", "n":2, "flag":true for a JSON file's {"id":"42","n":2,"flag":true}. Write "n":"{{data.n}}" instead and the number arrives quoted; that is the knob, not a bug.

A value cannot break the document it lands in. For a body whose text is a JSON document - json, jsonrpc, and a graphql body written as the {"query": ...} envelope - a token inside a string literal binds escaped, so a cell carrying ", \ or a newline arrives as its own text inside valid JSON rather than ending the string early. A token outside a string literal is not escaped, which is what keeps typed placement working. Nowhere else is anything escaped: a URL, a header, a form field and a text body take the rendered value byte for byte, and a bare (un-enveloped) GraphQL document is escaped once, later, when the engine wraps it.

An xml body has quoting rules of its own rather than JSON's, so it gets its own encoding - decided per token from where in the document that token sits, because XML has no single escape set the way a JSON string literal does:

Position Encoding
Element text &, <, > escaped as entities
Attribute value the above, plus the quote delimiting that attribute (" or ', whichever the author wrote)
<![CDATA[…]]> verbatim - a ]]> in the value is written ]]]]><![CDATA[>, which reopens the section instead of ending it
A tag or attribute name (<{{data.tag}}>) verbatim - no escape is legal in a name
Inside <!--…--> or <?…?> none - the bind is refused, naming the token

The last row is a refusal rather than an encoding because every candidate is wrong there: a comment is not sent as content at all, a processing instruction is markup addressed to the parser, and a value carrying --> or ?> would end the construct and send a document the author did not write. It errors the step like a missing column does, for every row alike.

The mode decides this, not the content: a text body holding XML still takes the cell byte for byte.

A token naming a column the bound row does not carry errors the step before anything is sent, with a message naming the token, the row index and the columns the row does have. Substituting an empty string would send a request quietly pointing somewhere else, which is the failure this namespace exists to remove.

A cell carrying a CR or LF bound into a header errors the same way. A header line ends at CRLF, so a cell holding ok\r\nX-Admin: true does not put that text in the header - it ends the header and makes the remainder a header of its own, forged by the data file. There is no escape for a line break in a header the way there is for a quote in a JSON body, so the row is refused rather than encoded around, naming the token and the row. The rule covers a header name, a header value, and a credential written into a header line (a bearer token, an api key sent in a header); basic auth's pair and an api key sent in the query are base64- and percent-encoded before they reach the wire, so they bind unchanged. JSON and JSONL rows keep native strings - there is no CSV grammar to have stripped the newline - so this is an ordinary cell, not an exotic one.

The cell is one of three origins the rule covers, and they share one definition of what a header may hold. A {{variable}} substituted into a header, or into a credential written into a header line, is refused by POST /compose with unsendable_header, naming the variable; every other origin - a script, a credential typed with the byte in it, an import, a raw POST /execute payload - is refused before the transfer starts, naming the header. That last gate also covers a NUL (which truncates the line rather than forging one) and a multipart part's field name, filename and content type.

Two headers that bind to one name error the same way. X-{{data.h}} resolving to authorization beside a literal Authorization, or two templated names resolving alike, would send that header twice where the request's rows name two different headers - so the row is refused instead, naming the header as it is written, the name it produced and the row. Two headers written alike are not this: they are a repeat the author typed and can see, and every row sends both (issue #2466); this refusal exists only for the rows that produce one.

A header name a row binds to nothing errors the same way (issue #1095), and is reported ahead of a collision when a row does both - two names that bind to nothing collide on a name neither of them has, which is not what the file's author needs to be told. {{data.header_name}}: acme whose cell is blank would otherwise send the line ": acme", under a name nobody wrote and with a value they did mean, once per iteration. The message is the one every layer that can leave a header nameless shares, with the row in front of it; the column is inside the header as written, where that wording names it. A name a bind merely shortens is not this rule - X-{{data.h}} with a blank cell binds to X-, which is a name a request can carry.

A cell that is present but null errors the same way, naming the token and the row. It is the same failure one type down - the token says the value comes from the file and the file says there is none - and writing "" for it would send {"n": } for a typed placement or a quietly blank field for a quoted one. A column that is legitimately optional belongs in a script, through pm.iterationData (see scripting.md), where null is a value a branch can read.

A run sent without a data set at all whose plan still carries a data.* token is refused outright, before any run row exists: nothing would bind the token, so every iteration would send the literal text {{data.id}}. The 400 names the step and the token, and - when the collection declares a data contract - the columns it declares, so the message says which file to run with rather than only that one is missing:

step 1 (request 'Fetch user', id 'req_a') carries {{data.id}}, but this run has
no 'scenario.data' set. ... (declared columns: id, email)

Starting such a collection as a quick smoke check means running it with a data file - a one-row set is enough - because the run this refuses would not have exercised the endpoint either.

Each step execution writes one results row carrying the design-mode trace plus iteration, stepIndex, stepName, requestId and outcome, and - for a run with data - dataRowIndex, the row that iteration bound. The step whose error ended its iteration short of the plan's end also carries stepsNotRun, defined under Outcomes below; it is absent, never 0, on every other row. A step whose extractors found nothing carries extractorMisses (#3053), how many of them did, on the same absent-at-0 terms (the rule is in Elements). A step whose request still held a {{name}} when it went to the transfer carries unresolvedTokens (#3248), how many distinct names, on the same terms: the residual pass answers every name the step's scopes define, so a name counted here is one nothing defined, sent as written, never refused. A step refused or skipped before the transfer carries none. Bodies are capped by maxTraceBodyBytes; the row count is capped by maxScenarioStoredSteps as described above.

A step whose scripts said anything additionally carries a scripts node (issue #724) - the same object and the same four keys POST /execute returns and a design send stores, so a step's assertions read the same inside a run as they do on a single send. It is the only route those results take: a collection run answers 202 long before its scripts have run, so nothing about a step is ever returned live. A step whose scripts said nothing stores no node at all. The results.error summary line ("3 tests failed - ") is unchanged and stays what the outcome is derived from; the node is the list that line summarises.

Every level's scripts run and every level's results land in that node (#2522): the collection's, each folder's from the outermost in, then the request's own, in that order, each testResults and consoleLogs entry carrying a scope of collection, folder or request (absent on a trace stored before the field, read as request). A failing pm.test at any level fails the step, and a script that throws at any level errors it; when the level that threw is not the request's own, the step error names it - "Collection pre-request script failed - ...", "Folder test script failed - ..." - where the request's own throw keeps "Pre-request script failed - ..." / "Test script failed - ...". When more than one level throws, the first one is reported.

A step of a collection bound to an OpenAPI document additionally carries a validation node (issue #681) - the same object and the same shape POST /execute returns - saying whether its response matched the schema that document declares. Absent for an unbound collection and for a step that sent nothing. By default the verdict is its own channel and changes no outcome; failOnSchemaError: true on the run makes a schema failure fail a step that passed everything else. The run's rollup is schemaValidation in the report.

Outcomes are passed, failed, skipped, errored and stopped:

Outcome Meaning Effect on the iteration
passed The request completed and every assertion held. Continues.
failed A pm.test assertion did not hold, at the collection, a folder or the request. Continues - the request itself completed.
errored, step The step did not run clean: the pre-request or test script threw, at any level (a thrown error, a script timeout, a refused pm.request write-back, a top-level pm.response.to.have.status(...) that did not hold), or the exchange did not complete (a transport failure, a request timeout, a request refused before the wire, a {{data.*}} token the row could not bind). Continues with the next plan position, as Postman and Newman do by default. With stopOnError: true it ends the iteration instead.
errored, flow control The runner refused the step's flow control: an unresolved or ambiguous setNextRequest (or control.switch / control.loop) target, or the maxStepsPerIteration cap. Ends the iteration, whatever stopOnError says. The next iteration still runs.
skipped A pre-request script called pm.execution.skipRequest(), so nothing was sent. The row carries the request and no response. Continues with the next step.
stopped A Stop (POST /runs/:id/stop) or an engine shutdown cut the step short (#3397): its transfer, the late OAuth 2.0 token request ahead of it, or one of its scripts' pm.sendRequest was cancelled, or one of its scripts was ended while it ran (#3460). The row carries the cancelled response (status 0, Request cancelled). Ends the run. No later step is sent or stored, and the step is no error: not in errored, failed, stepsNotRun, the status distribution, coverage or the assertion tally.

Either kind of errored is the same outcome on the row, in the summary's errored count and on the step frame, with the error in results.error; the table's split is only about what the iteration does next. An HTTP error status is not an outcome: a step that answered 4xx or 5xx with every assertion holding is passed, and the summary's failedRequests counts it. The five outcomes are disjoint and sum to stepsExecuted, a skipped step included (passed + failed + errored + skipped + stopped; a summary stored before

3397 has no stopped and reads it as 0). A step that completed before the

Stop landed keeps the outcome it earned. A scenario load run reports the other four under the same arithmetic and reads a step's flow control the same way: a no-response step and a thrown inline script are errored (#2947), a step that errored has its own jump (control.switch, control.loop) dropped, and a jump the run cannot honour is the errored of the step that set it (#2974). A load run stores no step rows, so that error's text, the same sentence, is the stepError of a run warning in the engine log. What differs there is a step that got no response: on a load run it ends its iteration, so a load run's errored is not the sum of its steps' noResponse, and iterationsAbandoned is its iteration-abort count. On a collection run a transport failure continues the iteration like a script error does, as Postman's and Newman's runners do by default; a later step that reads a response that never arrived errors on its own row. A step that errored while the iteration continues has its own flow control ignored - a setNextRequest, skipRequest or setNextRequest(null) from a script that then threw is an instruction from code that did not finish, so the iteration walks to the next plan position (see scripting.md).

The run's summary also carries the HTTP/2 fallback count (#3262). Every sent step's trace has httpVersionDowngraded (see POST /execute), and the runner adds those up into the stored summary's http_version_downgraded, the key a load run writes, so the report's summary.httpVersionDowngraded is the same figure in both run kinds. It counts requests, not steps: a step the plan skipped sent nothing and is never in it, and a request that asked for http2 and got HTTP/1.1 is one for every iteration it ran in. It is written as 0 for a run that counted and saw none, so only a summary stored before #3262 lacks the key.

stopOnError is a top-level boolean on POST /runs, default false, type-checked before the run row is created (null reads as the default, and a non-boolean is a 400 invalid_run_config naming the field). Set, every errored step ends its iteration, a transport failure and a script error alike, which is Newman's --bail shape and what a collection run did before issue #2526. It is a collection-run (design-mode) key: a scenario load run does not read it. It rides the stored snapshot as sent and is echoed in the report's scenario section, so two runs that differ only in it never read as the same run.

stepsNotRun counts the plan positions an error cost: when an errored step ends its iteration, the positions after it that the iteration had not already attempted. It rides the step row (and the step frame) that ended the iteration when it is above zero, and the report's scenario.stepsNotRun sums it over the run. An iteration that ends any other way adds nothing: setNextRequest(null) and a forward jump are a script's decision, not a loss, and a stop is the user's: a stopped step adds nothing under stopOnError either. iterationsCompleted keeps its meaning - an iteration an error ended still completed.

A run whose steps failed still reaches completed: the outcome of the work is in the steps, and only the runner itself failing makes the run failed. A stop ends the step in flight - its send, its late token request and its scripts' pm.sendRequest all carry the run's stop as their cancel, so it lands within about a second rather than after a request timeout - and is otherwise honoured between steps, so a stopped run does not finish the iteration it was in. An engine shutdown stops an active run the same way.

A step's scripts can redirect the sequence. pm.execution.setNextRequest(name) runs a named request next instead of the one that follows, setNextRequest(null) ends the iteration, and pm.execution.skipRequest() (pre-request scripts only) sends nothing and marks the step skipped. A target that names no step in the run, or one that two steps share, fails the step by name rather than guessing, and maxStepsPerIteration above is what stops a cycle. Both refusals end the iteration whatever stopOnError says, and a step whose script errored has its redirect ignored. The full contract, including everywhere the two methods throw, is in scripting.md.

The stored snapshot carries a step manifest, never the composed plan. runs.config_snapshot holds the block as validated - with data replaced by its row count - plus {index, requestId, name, method, url} per step, where url is the stored, uncomposed one. The composed plan carries resolved Authorization headers and, for an apikey auth with in: "query", a live key in the URL; it lives in memory for the run's life and nowhere else.

Controller elements redirect the sequence too (issue #1515). control.if, control.once and control.throughput skip a step the same way pm.execution.skipRequest() does; control.switch jumps to a named member the same way setNextRequest(name) does - one flow-control channel, not two, so the rules above (an unresolved target fails the step by name, a cycle trips maxStepsPerIteration) apply identically. control.loop, on a folder, walks its members a fixed number of times per iteration by looping back to the folder's first member. See elements.md for the kind table and every config shape.

control.transaction reports its own percentiles. A folder carrying one sums every member's own response latency, at microsecond precision, into a named total per pass, and the run's summary gains scenario.transactions[] = { name, count, errors, latency: { min, p50, p90, p95, p99, max } }, omitted for a transaction the run never closed. A pass closes when the iteration leaves the folder (#3054): after the folder's last member whether it was sent, skipped by a controller or failed before an answer, or after any member from which the iteration jumps out of the folder or ends. So count is one per iteration that attempted a member, and a pass whose every member was skipped, or that a Stop interrupted, is not counted. errors counts the passes in which a member was an error by the report's own definition: no response, a status outside 2xx/3xx, or a failed assertion. includeTimers: true (issue #1569) also folds a between-member timer.* wait into that sum - excluded by default, and always excluded for a wait after the folder's own last member, which is outside the transaction's span. elements.md has the full close rule. The same shape reports on a scenario load run's summary, top-level rather than under scenario - see below.

Scenario load runs

Adding a load mode beside the scenario block runs the same plan as a load test: concurrency virtual users, each walking the sequence on its own, closed-loop on the event loop. The absence of mode is what still means a design-mode collection run, so a payload written before this existed keeps its meaning exactly.

{ "mode": "constant_concurrency", "concurrency": 50, "duration": "60s",
  "scenario": { "source": "collection", "collectionId": "col_1" } }
Field Meaning here
concurrency The number of virtual users - what k6 and JMeter mean by it. Each holds its own position in the plan and its own cookies.
duration Wall-clock length, for constant_concurrency and ramp_up. Virtual users keep starting iterations until it is up.
iterations (top level) mode: "iterations" only: total passes over the plan across all virtual users. Distinct from scenario.iterations, which the design-mode runner reads.
startConcurrency / rampUpDuration ramp_up only, as for a single-request run.

Rejected with a 400 (error.code: "invalid_run_config"), before any run row exists:

Input Rejected because
mode: "constant_rps" with a scenario An open-loop arrival rate over a multi-step sequence is an arrival-rate executor, which Vayu does not implement. Refused rather than silently run closed-loop.
mode: "capacity" with a scenario The search judges one p99 per level and a sequence has one per step, so which of them the knee is measured against is a question the mode does not answer.
rps / targetRps above zero, on any mode It is an open-loop arrival rate, and a scenario run is closed-loop by design: no scenario mode reads it, so it is refused rather than ignored.
An unknown mode

maxInFlight is moot and is ignored with a warning: in-flight requests are bounded by the virtual-user count by construction, so concurrency is the only knob.

What differs from a design-mode collection run:

  • The run's type is load, not scenario. It publishes metrics ticks over GET /runs/:runId/live (not step events) and reports RPS and percentiles like any load run.
  • Cookies are per virtual user, empty at the start of each iteration, and the environment jar is untouched. One session shared between 1,000 virtual users is not the thing being measured.
  • Variables are each step's own folder's (#3248), as in a design-mode collection run: the environment and globals the run loaded, and the chain from the root collection down to the folder the step's request sits in, each entry as the run's script.setup scripts left it. All of it is read once, before the first request, so a recursive run sends a sub-folder's {{name}} with that folder's value whether or not the plan carries a script. A script.setup and script.teardown read and write the collection that declares them, from the same lifecycle set a design-mode run uses (#3456; see lifecycle under GET /runs/:runId/report), so what a folder's setup writes reaches the steps in that folder and the folders below it. Nothing a load run's scripts write is saved.
  • The element pipeline runs here too, per virtual user (issue #1495). extract.* and assert.* always run - before the send (step.before) and after the response (step.after). A script.pre / script.post element runs there only when its own config.inline is true, or the run's elements override forces it; unmarked, a step's scripts still stay deferred, keyed per step, exactly as before this issue - see the next bullet. Each virtual user writes through its own overlay, never the run's shared scopes, so a name one user's step 1 writes (an extract.json's target, an inline script's pm.environment.set) is visible only to that same user's later steps, never to another user's concurrent one. A collection write stays on the step's own folder (#3248): it answers that user's later steps in the folder and in folders below it, not a step in a sibling folder. Those saved names outlive the iteration that wrote them (#3044): a control.once login's extracted token still answers every later iteration of that user. An extractor's miss with no default unsets its name the same way (#3053): for that user alone, a value the run's stored scopes hold included, until the user sets it again. What resets at each iteration boundary is the user's cookies and its run-local scope (pm.variables.set); a bound data row's columns are the new row's. pm.execution still throws - a script cannot redirect the sequence under load. A controller element can (issue #1515): control.if, control.once and control.throughput skip a step the way pm.execution.skipRequest() would, counted in the run's summary skipped key rather than the 0 every scenario load run reported before this; control.switch and control.loop jump the plan (issue #1569), resolved the same way a script's own setNextRequest would be and guarded by the same maxStepsPerIteration cycle limit the sequential run uses. control.throughput's perUser: false shares one budget across every virtual user instead of one per user, and control.transaction's includeTimers folds a between-member timer.* wait into its reported sum - both issue #1569 too.
  • A script that did not run inline stays deferred, keyed per step. After the run drains, that step's own post-request script is replayed against the responses that step produced, and the tallies appear on that step's entry in the breakdown as tests (see scenario.steps below). A step with several un-inlined, enabled script.post elements replays each one as its own script, in order, against every sample (issue #3125): a const one declares is not visible to the next, while a variable-scope write is. Their pm.test results add up, and an element that calls none and does not throw counts as one pass. An inline element runs in its own fresh context during the run; a disabled one never runs and tallies skipped. A step that carries no script, whose script ran inline this run, or whose script never got a sampled response, carries no tests object at all rather than a row of zeros.

Sampling is keyed per step for the same reason: the run's max_response_samples budget is split evenly across the steps that carry a deferred script (floored at one apiece), so the last step of a forty-step plan is sampled instead of being crowded out by the first. The whole-run testValidation section still reports the aggregate - it says something failed, and the per-step tests say where. - Data rows are claimed from one shared cursor, one per virtual-user iteration, wrapping when they run out - so two virtual users never start with the same row while unclaimed rows remain, which is what a credentials file is for. Once every row has been claimed the cursor wraps and rows are reused, concurrently: a 10-row file under 50 virtual users, or any duration-mode run past the row count, has several users on one row at a time. Size the file to the concurrency if the rows must stay exclusive. Every step of an iteration binds that iteration's row. scenario.iterations still has no meaning here: the run repeats until its duration is up, and the row count does not bound it.

A {{data.column}} naming a column its bound row does not carry fails that step: nothing is sent, the step's errors count in the breakdown moves, and the run's error list carries an entry with error_type: "data_binding_failed" naming the token, the row and the row's columns. It is never substituted with an empty string. A null cell, two headers binding to one name, and a header name a row binds to nothing fail the same step the same way.

Every retained result carries dataRowIndex on its trace, which is how a failure is attributed to a row when no per-step results rows exist. Absent for a run sent without data. - A step that got no response ends its iteration (a transport error, or a step never sent) and its virtual user starts the next one. It is never stranded. So does a control.switch or control.loop jump the run cannot honour (a target no step answers to, or one past maxStepsPerIteration), as on a collection run, with the step that set it errored (#2974). A step that answered with an HTTP error status (4xx/5xx) counts in its errors but does not end the iteration: a response arrived, and the next step runs. - No per-step results rows are stored - one row per step per iteration per virtual user is what a load run exists not to keep. The report's scenario.steps breakdown is the per-step record instead:

"scenario": {
  "iterations": 480, "iterationsCompleted": 474, "iterationsAbandoned": 6,
  "stepsExecuted": 954, "passed": 906, "failed": 30, "errored": 6,
  "skipped": 12, "virtualUsers": 50,
  "assertions": { "passed": 432, "failed": 30 },
  "steps": [
    { "index": 0, "name": "Log in", "requestId": "req_a", "method": "POST",
      "executed": 480, "errors": 6, "httpErrors": 0, "noResponse": 6,
      "unresolvedTokens": 0, "extractorMisses": 3,
      "latency": { "min": 1.2, "p50": 4.0, "p95": 9.1, "p99": 12.4, "max": 30.2 },
      "elements": [
        { "id": "el_1", "kind": "extract.json", "name": "Session token",
          "origin": { "kind": "request", "scope": "request", "id": "req_a", "name": "Log in" },
          "passed": 471, "failed": 0, "missing": 3, "error": 0, "skipped": 0, "deferred": 0 }
      ] },
    { "index": 1, "name": "Get me", "requestId": "req_b", "method": "GET",
      "executed": 462, "errors": 30, "httpErrors": 30, "noResponse": 0,
      "unresolvedTokens": 3,
      "preRequestScript": "skipped",
      "latency": { "min": 0.9, "p50": 3.1, "p95": 7.8, "p99": 10.0, "max": 22.5 },
      "elements": [
        { "id": "el_2", "kind": "control.if", "passed": 462, "failed": 0, "missing": 0, "error": 0, "skipped": 12, "deferred": 0 },
        { "id": "el_3", "kind": "assert.status", "passed": 432, "failed": 30, "missing": 0, "error": 0, "skipped": 0, "deferred": 0 }
      ],
      "tests": { "sampled": 20, "passed": 20, "failed": 0,
                 "console": [ { "level": "log", "text": "user 42 loaded" } ] } }
  ]
}

This run ended by its iteration count: 6 of its 480 iterations lost their login to no response and were abandoned there, and the other 474 completed. Get me was reached 474 times; its control.if skipped 12 of them and 462 ran, 30 of those answered a status its assert.status rejected. So stepsExecuted is 480 + 474 = 954, which is the 942 steps that ran plus the 12 skipped, and the four outcomes are 906 + 30 + 6 + 12 = 954. Three of the 474 logins answered without a token: the extractor's miss unset {{token}}, so Get me sent it unresolved three times.

iterations is the iterations started, not the iterations asked for, and three counts account for them: iterationsCompleted (the iteration reached its last step, or a script ended it with setNextRequest(null) or a forward jump), iterationsAbandoned (a step that got no response, or a jump the run could not honour, ended it) and the iterations still running when the deadline or a Stop ended the run. The last has no key of its own; it is derivable:

  • iterations = iterationsCompleted + iterationsAbandoned + cut at the end, so the iterations cut at the end are iterations - iterationsCompleted - iterationsAbandoned

That term is 0 for a run that ended by its iteration count, as the example above did (480 = 474 + 6 + 0), and positive for one a deadline or Stop ended mid-iteration: 1,150 started, 1,140 completed and none abandoned is 10 cut. The app's Steps tab shows it as "Iterations cut short" beside the other two.

One histogram is allocated per plan step at run start, which is the other thing maxScenarioSteps bounds.

A step's errors follows the run's one error definition (issue #2124): a status outside 2xx/3xx, or no response at all. It is the sum of two disjoint counts. httpErrors is the responses that arrived with a 4xx or 5xx; the step's latency includes them, and the iteration carries on to the next step. noResponse is the executions that got nothing back (a transport error, booked under status 0 like the run's own distribution, or a data-binding failure that sent nothing); these end the iteration, as a jump the run could not honour does, and a refused jump is in neither count: it is an outcome (below), not a request error. A noResponse execution whose transfer ran (a timeout, a reset, a DNS or TLS failure) is also in the step's latency, so a step that times out reports its timeout in p99 and max; one that never reached the wire (a data-binding failure, a refused header, a skip) adds a count and no duration. The step's histogram follows the same population as the run's, and includeScriptTime applies to a failed step as it does to an answered one (issue #2384), folding the same pipeline time into the run's latency as into the step's, so the run's max is never below a step's (#2792).

At the top of the section, passed, failed, skipped and errored are the collection run's outcomes (Outcomes under Scenario runs,

2824), counted per step execution and disjoint. A load run has no stopped:

a step its Stop cancelled is in no count at all (#2136). errored is an execution that got no response, one whose inline script.pre or script.post threw (a thrown error, a script timeout, a refused pm.request write-back, an inline pm.execution call; #2947), or one that set a jump the run could not honour (#2974). A throw outranks a failed assertion and a skip, and a refused jump outranks every other outcome, as on a collection run. The no-response kind and the refused jump end their iteration; a throw does not, and only drops the step's own jump, so a script bug changes the load the target receives only where the step that threw also asked to jump. errored is therefore not the sum of every step's noResponse: the iteration-abort count is iterationsAbandoned. failed is one whose response arrived and in which an inline assertion did not hold (an assert.* element, a required extract.* miss, an inline script's pm.test), counted once however many failed in it. skipped is one a controller (control.if, control.once, control.throughput) stopped before the wire, and passed is the rest. An HTTP error status no assertion rejected is passed: the step's httpErrors and the report's summary.failedRequests count it. stepsExecuted is every step reached, a skipped one included, and a step's executed is every execution of it that was not skipped (a skipped one whose script.pre threw, or whose control.loop repeat was refused, is in it as errored, and adds nothing to noResponse or the latency), so two identities hold:

  • passed + failed + errored + skipped = stepsExecuted
  • the sum of steps[].executed, plus skipped, = stepsExecuted

A deferred script's tests replay after the run against sampled responses, so they fail and error no step here; they are the step's tests and the report's testValidation. A run stored by engine 0.45.0 or earlier keeps the definition it was written under: failed was the sum of every step's httpErrors, and passed was stepsExecuted less failed and errored, its skipped steps included. Nothing rewrites a stored run.

assertions (#2820) is the run's exact assertion population, { passed, failed }: every assert.* outcome, every required extract.* miss and every inline script's pm.test call, counted on each completion. It is the figure a maxAssertionFailureRatePct check reports as assertionsExact. It counts assertions where failed above counts step executions, so an execution that failed three assertions is one failed step and three assertions.failed. summary.errorRate stays HTTP-only: a run whose every assertion failed against 200s reads an errorRate of 0, a non-zero assertions.failed and every asserting step failed. The deferred replay of an un-inlined script is the sampled population (the step's tests, the report's testValidation) and is never in it. Absent, never {0, 0}, for a run that made no such assertion, for a sequential collection run and for a run stored before the field existed. The report's top-level assertions (#3537) carries it as exact, beside the sampled replay, the errored element executions and the failed teardowns.

tests is the step's deferred validation - a script that did not run inline this run - and is absent for a step whose script ran inline instead (its outcome is in elements), asserted nothing, or drew no sample - "no assertions" and "no failures" are different answers. Beside its sampled/passed/failed it carries console? and consoleDropped? (#3127): what that step's replayed scripts logged, as [{level, text, count?}], the first 10 distinct lines across the step's samples, each cut to 500 bytes, kept whatever the script's verdict and with count when it was logged more than once (absent means once), and how many occurrences a full list turned away. The list is the step's own, so a line two steps both log appears under each; both keys are absent when the step's replay logged nothing (consoleDropped also when nothing was turned away).

elements (issue #1495) is the step's per-element tally, { id, kind, name?, origin?, required?, passed, failed, missing, error, skipped, deferred } one entry per compiled element that ran at least once this run (an id a collection's element and the request's own share is two entries, each with its own counts and origin) - absent for a step with no elements or none that ever ran, the same convention tests follows. Each count is one outcome word of the sequential trace (#3051): passed is ok, and failed, missing (an extractor that found nothing, or a metric.record with nothing to read) and error (an element that could not run its check, a script that threw) are counted apart. name is the element's own label and origin the level it was composed from, each present only when the element carries one; required is present, as true, only for an extractor whose config sets it, and it is what makes that element's missing a failed step. deferred (issue #2144) counts a script.post element left to the replay above: it does run, later, and its assertions are the step's tests. skipped counts every other skipped outcome: a disabled element, an un-inlined script.pre (no replay to go to), a controller's skip, an optional extract.json over a body it could not read, and an inline script.* the run's Stop cut short, its pm.sendRequest cancelled (#3371) or the script itself ended (#3460), whose tests and throw are then counted nowhere.

A script.pre or script.post that ran inline also says why it failed and what it logged (#3127), since a load run keeps no trace to read it from:

{ "id": "el_4", "kind": "script.post", "passed": 0, "failed": 0, "missing": 0,
  "error": 480, "skipped": 0, "deferred": 0,
  "messages": [
    { "kind": "error", "text": "Error: boom", "count": 480 },
    { "kind": "test", "text": "status is 201: expected 200 to equal 201", "count": 480 }
  ],
  "console": [ { "level": "log", "text": "saw 200", "count": 470 },
    { "level": "warn", "text": "slow body" } ],
  "consoleDropped": 37 }

messages lists the errors the script threw (kind: "error", a timeout included) and each failing pm.test as name: message (kind: "test"); console lists its console lines with their level (log, info, warn, error). Each list holds the first 10 distinct entries the run produced, in the order first seen, however many executions repeated one, and each text is cut to 500 bytes on a character boundary, ending in ...[truncated]. An entry produced more than once carries count, how many times (the first included); count is absent on an entry produced once, so the common case and a row from an earlier engine read the same. The two lists fill apart, so a script that logs on every iteration cannot crowd out why it failed. messagesDropped / consoleDropped count the occurrences a full list turned away (a repeat of a dropped entry counted each time; a repeat of a kept one counts on that entry's count instead), so a list without its dropped count is the whole set of distinct entries. Every one of the four keys is absent when it would be empty or 0, so a row from an earlier engine reads the same. A single-request run's summary.elements rows carry the same keys. The run export (POST /export/run-report) leaves all four out.

transactions (issue #1515), a sibling of steps rather than a member of it - a control.transaction spans a folder, not one step:

"transactions": [
  { "name": "checkout", "count": 480, "errors": 0,
    "latency": { "min": 8.1, "p50": 14.2, "p90": 22.0, "p95": 26.5,
                 "p99": 33.0, "max": 55.4 } }
]

One entry per declared control.transaction name that closed at least once this run, allocated up front from a scan of the plan - never discovered mid-run - so recording into it, like every other controller here, takes no lock. count and errors follow the collection run's rule (#3054): a pass closes when the virtual user's iteration leaves the folder, including an abandoned iteration, and errs when a member got no response, answered outside 2xx/3xx or failed an inline assertion.

unresolvedTokens (issue #1503) counts, per step, how many of its executions sent a {{token}} composition the residual-token pass still could not answer - issue #1495 added a real resolution attempt here (against the executing virtual user's own scope overlay, see elements.md), but the load path's rule is unchanged: never refused, only counted, so a name still unanswered (or a header-name collision the attempt itself produced) goes on the wire regardless. preRequestScript is "skipped" for a step whose script.pre did not run inline this run and absent otherwise - a step whose script.pre did run inline reports its real outcome in elements instead, never both. Neither unresolvedTokens nor preRequestScript ever fails the run by itself; both also feed the top-level warnings array below. extractorMisses (#3053) counts the step's extractions that found nothing and so unset their variable, across every virtual user and iteration; it is absent at 0. A miss is filed under its element's missing too (or skipped, for an optional extract.json that could not read the body), and a miss a default answered is neither: the rule is in elements.md.

Response:

{
  "runId": "run_1234567890",
  "status": "running"
}

tests, postRequestScript(s) and preRequestScript(s) are refused outright (refuse_legacy_script_fields), the same rule POST /execute, PUT /requests/:id and PUT /collections/:id already applied since issue

1514 - a payload carrying any of the five names (a real value, not null)

is a 400, before the run row exists. The name it points a caller at depends on the shape: requestElements for a single target (this endpoint's own elements means the run-level override, not a script source, and pointing there would send a caller straight into a second refusal), plain elements for a scenario (its steps read theirs off the bound collection's stored elements, which no field on this payload can name more precisely). POST /runs was the one route that still read the old names on a single target - it had nothing else to run a script through until its own element pipeline existed - and issue #1594 closed that gap: requestElements (above) is a single target's own script slot now, the same way a scenario's steps already read theirs off the plan's compiled elements. A caller still sending tests gets the same refusal every other route already gives; MCP's start_load_run never sends it - it folds the agent-facing postRequestScript / tests argument into a script.post entry of requestElements client-side (see mcp.md).

A script.pre element only reaches the wire when it is marked to. The ad-hoc preRequestScript(s) field itself is refused (see above, same as tests) - a pre-request script only ever rides as a stored script.pre element now, on either run shape. Unmarked (config.inline unset, no elements.scripts: "allInline" override), it never runs - there is no pre-request replay to defer it to, unlike script.post - so a request that signs itself in one is sent unsigned. Since issue #1503 this is no longer silent on the scenario shape: a step whose request carries an un-inlined pre-request script reports preRequestScript: "skipped" on its scenario.steps entry, and the run's warnings array carries one line naming how many steps did. The single-target shape reports the same fact differently (see requestElements above): an un-inlined script.pre element's own entry in summary["elements"] counts every submission under skipped (never deferred, which is only for a script.post the replay runs) instead of a separate warning line.

Accepted ranges. The numeric config is range-checked before the run row is created, so a rejected request leaves no pending row behind. A violation is a 400 whose error.code is invalid_run_config rather than the per-status default, and whose message names the offending field and why the bound exists:

Field Accepted Rejected because
success_sample_rate 1-100000 It is a sampling period (keep 1 in N), used as counter % rate. A 0 was a division by zero that killed the daemon mid-run.
response_sample_rate 1-100000 Same modulo, same crash.
max_response_samples 0-1000000 Each retained sample holds a full response body, and the vector is reserved up front; a negative value casts to ~1.8e19.
max_response_sample_bytes 0-1073741824 The whole-run budget for those bodies, held in memory for the run and its retention window. The count cap above bounds the store only for a target whose bodies are small - at 1 MiB each, 1000 samples is ~1 GB. 0 retains no sample that has a body. Defaults to the maxResponseSampleBytes setting.
max_success_results 0-1000000 Each retained record holds a serialised timing breakdown, and the store is reserved up front. 0 means unlimited.
max_slow_results 0-1000000 Same store, same reserve, separate budget. 0 means unlimited. It caps the slow traces kept, never the report's slowRequests.count, which counts every slow completion.
slow_threshold_ms 0-86400000 ms 0 disables outlier capture; a negative threshold would mark every completion an outlier and fill the slow store with the whole run.
max_sample_body_bytes 0-104857600 A captured body is copied on the completion callback, so the cap bounds hot-path work. 0 keeps headers and metadata and no body. Defaults to the maxSampleBodyBytes setting.
max_sample_bytes 0-1073741824 The whole-run capture budget; every byte under it is held in memory until the run flushes. Defaults to the maxSampleBytes setting.
max_exemplar_results 0-100000 Each retained exemplar holds a captured exchange. 0 means unlimited.
phase_histograms boolean Per-run override for the phaseHistograms setting. false skips the bank entirely: the run's report carries no timingBreakdown.phases, its avg*Ms fall back to the retained trace sample, and its live gate frames carry no cumulativePhases.
save_timing_breakdown boolean Read as a bool inside the run-context constructor, which threw on a string after the row was written - the same stranded-pending failure duration had.
capture_response_bodies boolean Same read, same constructor, same failure.
concurrency 1-10000 Connections are eagerly pre-allocated per worker before any traffic flows, so -1 (a natural "unlimited" guess) allocated until malloc failed.
startConcurrency 1-10000 The ramp is seeded with this many in-flight requests before the first duration check, and it is read as a size_t, so a negative start is ~1.8e19 of them.
maxInFlight 1-1000000 It is a pending-request ceiling read as a size_t, so -1 or 0 removes the backpressure the field exists to provide instead of tightening it, and an open-loop run against a slow target then accumulates in-flight requests for its whole duration. The ceiling is not the concurrency guard: that one bounds an eager per-worker connection pre-allocation, while this bounds a counter that pre-allocates nothing, and the engine's own default - max(targetRps × 10, 1000) - reaches 500,000 at the load dialog's 50k RPS maximum, so a lower bound would refuse ceilings the engine picks for itself.
timeout 1-86400000 ms A transfer that never times out never completes, leaving the run stuck running and unstoppable. Absent or null, the run uses the defaultTimeout setting, as POST /execute does (#2798). In a scenario run, sequential or load, it is what a step whose stored request states no timeout of its own sends with; a step that states one sends with its own (#2937), and fetches and refreshes its OAuth 2.0 token under it too. It also bounds the run's other OAuth 2.0 token fetches (the pre-flight's, and each step's at plan time and every mid-run refresh) and is the default timeout of a pm.sendRequest from any script of the run: a sequential run's step, setup and teardown scripts, and a load run's inline step scripts, script.setup / script.teardown and deferred tests script (#2833, #2841). Latency percentiles and max saturate at one hour (3600000 ms): a longer completion is counted there, not dropped (#2790).
duration string, positive, optional unit (ms|s|m|h) A JSON number threw out of the run-context constructor after the row was written, stranding it pending forever behind an opaque 500.
stepDuration string, positive, optional unit (ms|s|m|h) capacity only, and read by the same parser duration is - so it is gated by the same rule rather than by a second copy of it.
rampUpDuration non-negative, optional unit (ms|s|m|h); a JSON number is seconds; 0 is an instant ramp Read by ramp_up only, but checked in every mode, like duration. It was not checked here at all, so "10sec" created a row that went running and then failed. Checked by asking the run-time reader itself, so it accepts exactly what the ramp will read - zero and a JSON number included, both of which duration refuses.
iterations 1-2147483647 An iterations run stops on its request count alone, read as a size_t, so -1 was ~1.8e19 requests and a run that never ended until stopped. The ceiling is the one scenario.iterations has.
rps / targetRps 0-1000000, fractions allowed The open-loop arrival rate per second; 0 asks for none. The ceiling is the highest RPS cap the app and MCP settings can be raised to. constant_rps needs one of the two positive, and every other mode refuses a positive one - see below.
stream boolean Accepted since streaming under load landed; read through the same parser POST /execute uses. A non-boolean is a 400 rather than a silent buffered run the caller would wait forever for. Refused on a collection run, either value: there a step streams when its stored request does (#3235).
maxStreamDurationMs 1000-86400000 ms Streaming only - refused without stream on a single-request run; on a collection run accepted alone and applied to the steps whose stored request streams. Defaults to the sseMaxStreamDurationMs setting.
maxStreamEvents 1-10000000 Streaming only - refused without stream on a single-request run; on a collection run accepted alone and applied to the steps whose stored request streams. Defaults to the sseMaxStreamEvents setting.
stream_metrics boolean Whether the run feeds the per-completion event and time-to-first-event histograms, and, on a single-request streaming run, its live event tally. false leaves the report's stream section out entirely rather than zeroing it, and the live frames' stream keys with it. Run-config only - there is no engine-wide setting beside it, because the cost is paid only by runs that stream.
sloMs 1-60000 ms capacity only. A non-positive budget has no edge to find, and one past a minute is longer than the transfers any realistic run measures. Matches the app's own clamp on the p99 threshold setting.
carriedBudgets array of at most 64 strings, each at most 512 bytes of UTF-8 Stored in the snapshot and echoed in every report, and nothing downstream reads the entries, so these bounds are the only ones the list gets. See Carried-over budgets.

An absent field, or an explicit null, is always accepted - every one of them has a default. The route erases every top-level null before anything reads the config, so a null runs exactly as the absent key would and the stored config snapshot carries none (#1893); it used to pass this check and then throw in the run's own reader, after the row existed. The ceilings are crash guards, not policy: each client caps itself far lower (the load dialog offers concurrency ≤ 1000; the MCP start_load_run tool has a user-settable cap in Settings).

The defaults an absent field takes are the run_config::DEFAULT_* constants in engine/include/vayu/core/constants.hpp: duration 60 s for a constant or ramp-up run, concurrency 100 for a constant or ramp-up run and 10 for an iterations run, iterations 1000, rampUpDuration 10 s, startConcurrency 1. A capacity run's duration defaults to its own 300 s search deadline instead. timeout is the exception: it defaults to the defaultTimeout setting (30 s unless changed in Settings), read when the run starts, for a single-request and a scenario run alike. A scenario step's own stored timeout (#2937) wins over both for that step's transfers. A pm.sendRequest keeps the run-level value, except from a sequential run's step scripts, which take their step's timeout as a Send's scripts take the Send's. None of them is written to the stored snapshot; only what the body carried is, so a replayed snapshot that carried no timeout takes the setting in force at its own start.

A rate belongs to constant_rps, in both directions. Both checks sit in validate_run_config (check_constant_rps_rate and check_rate_only_on_constant_rps, routes/execution.cpp) and answer a 400 with error.code invalid_run_config; rps is read first, and targetRps when rps is absent or 0.

  • A mode of constant_rps with neither field positive is refused. It used to run the closed-loop path at the default concurrency while the stored config and the report still said constant_rps (#1893).
  • Any other mode with either field positive is refused, naming the field and the mode (#2396). A rate used to switch constant_concurrency to open loop and to give every other mode's event-loop workers a token bucket of rate ÷ workers, so a ramp reported its own throttle as latency, while the config and the report still named the declared mode. An unrecognised mode is held to this too. 0 asks for no rate and is accepted on every mode.
  • A body with no mode is constant_rps, as the executor reads it: it may carry a rate, which paces it open-loop, and without one it holds concurrency in flight closed-loop, as it always has.

The executor chooses by mode as well (open_loop_rate in load_strategy.hpp): a rate that reaches a closed-loop mode without passing this route, in a stored config, does not open the loop. No mode throttles the event loop's workers with a rate of their own: a constant_rps run is paced by its pacing thread alone (#2801).

One field is rejected by presence, not by range: transient. It is POST /execute's no-run-row flag (issue #382) and has no meaning here, because a load or scenario run is the row it creates - the run id is what this endpoint returns, and the live stream, the report and the scenario step store are all keyed by it. Ignoring the flag would leave a caller believing the run left nothing behind while it wrote the largest trace the store holds, so a present transient (true or false) is a 400 with error.code invalid_run_config. An explicit null is absent, as everywhere else here.

The sample rates are additionally clamped to ≥ 1 inside the metrics collector, so the modulo cannot divide by zero even for a caller that bypasses this route.

What a run stores, and for how long. A completed request is recorded in the aggregate counters always; whether its detail survives is decided by three independent budgets:

Budget Filled by Bounded by
Sampled timing traces 1 in success_sample_rate completions, only while save_timing_breakdown is on max_success_results
Slow-request traces any completion at or past slow_threshold_ms, regardless of save_timing_breakdown max_slow_results (the traces only: the slow count is an aggregate counter)
Response samples (post-run test scripts) 1 in response_sample_rate completions max_response_samples, and max_response_sample_bytes
Per-status exemplars (captured responses) the first three completions of each distinct status code that no other budget already stored max_exemplar_results

None of these budgets bound the report's timingBreakdown.phases: the per-phase histograms are fed by every completion and hold counts rather than records, so the phase distribution, and the avg* fields read from its means, are the whole population no matter how hard the stores above thin. Only a run without the bank falls back to averaging the sampled subset.

Two properties are worth relying on. An outlier never consumes a sampling slot: a run whose target degrades does not silently stop sampling ordinary traffic because everything became slow. And each store is a reservoir - past its bound a later record displaces a uniformly chosen incumbent instead of being refused - so what a long run retains describes the whole run rather than its first few seconds, and sampling in the report says how many records that thinning cost.

The exemplar budget is the one exception to the reservoir rule, and deliberately so: an exemplar that gets displaced is not an exemplar, so past its bound a later candidate is refused and counted rather than evicting an incumbent.

It is also the last budget consulted, not the first. A completion that is already an outlier stays charged to the slow budget and a sampled one stays charged to the sampling budget - claiming an exemplar never moves a record out of the store that wanted it, because the first few completions of a status code are often exactly where a run's outliers are. What the exemplar claim decides is whether the response body is captured, which is independent of which budget pays: a completion that is both sampled and a claimed exemplar is stored in the sampling budget and keeps its body.

Response capture. capture_response_bodies (boolean, default true) decides whether the retained samples carry their response headers and body. On by default is only defensible because capture is failure-and-outlier-shaped rather than uniform - errors, slow outliers and the per-status exemplars, never the 1-in-N slice - so a healthy run captures a handful of exchanges. Set it to false and the collector is byte-for-byte what it was before capture existed: no gate is consulted, no exemplar is claimed, nothing is copied, and no rows are written. What is captured is read back with GET /runs/:runId/samples and described in result_bodies.

Shutdown refuses new runs. Once the daemon has begun draining its run workers, POST /runs answers 503 with the message Engine is shutting down rather than accepting a run nothing will ever execute. The window is small - the HTTP server stops before the drain begins - but it is not empty, and a request already in a handler when the drain starts must not be able to spawn a worker past it (see RunManager::shutdown). The row the route had already written is marked failed first, and so is the row of a run that throws while starting (answered 500, naming the error): no answer but a 202 leaves a pending row behind (#1893).

A run row the database cannot write is a 500. A busy or locked database, a full disk or an I/O error while recording the run is the engine's failure, not the payload's, so POST /runs answers 500 Couldn't create the run record. The app retries a 5xx and treats a 4xx as a verdict, so a momentary lock no longer reads as a refused request (#2319).

Auth pre-flight. When auth.mode is oauth2, the run route resolves the token before creating the run and warms the cache for the workers. An unauthorizable config is rejected up front with 409 (interactive sign-in required) or 400, carrying the /oauth2 error codes and, when the token endpoint answered, its reply inside the error object as POST /oauth2/token carries it (providerStatus, providerError, providerErrorDescription, #3201), so a bad token never surfaces as a silently-failed run. A load run acquires once, before any script, from the stored values (a script that sets an OAuth 2.0 variable has no effect under load, and nothing is re-acquired per iteration), so an oauth2 config still holding a {{name}} when the run starts (one that nothing defines, or one posted without being composed for a run with deferDynamicVariables) is a 400 invalid_run_config naming it (a collection load run's step is invalid_scenario, see Scenario runs); and a targetPolicy that refuses the config's token endpoint is a 400 under the policy's code, before anything is posted.

Concurrency model. constant_concurrency, ramp_up, and iterations are closed-loop: the engine holds in-flight requests at a target (concurrency, or the ramp curve from startConcurrency to concurrency) - when a request completes, another is issued. Throughput is a result (concurrency ÷ latency), not an input. constant_rps is open-loop: it dispatches at targetRps regardless of how fast responses return. The mode chooses the loop; a rate is constant_rps's field alone (see above).

maxInFlight. A hard cap on concurrent in-flight requests. It applies only to constant_rps (the open-loop rate mode), where it bounds how many requests may be outstanding before the engine drops new ones; default ≈ max(targetRps × 10, 1000), accepted range 1-1000000. That range holds the default formula across the whole advertised RPS span (50k RPS → 500,000), which is why it is not the concurrency guard - a ceiling of 10,000 would reject explicitly what the engine already does implicitly. For the closed-loop modes the concurrency target is the in-flight bound, so maxInFlight is ignored there. It is not what bounds a catch-up burst: when the pacing thread stalls (a host sleep, a blocked thread), its next tick sends what the schedule owed up to 100 ms past the instant the tick was due (MAX_CATCH_UP_BACKLOG, core/load_pacing.hpp) and skips the rest (#2911). Skipped requests are never sent and are counted as skippedRequests, apart from the maxInFlight drops, with stalledMs the schedule time they cover (skippedRequests ÷ targetRps). What the tick does send still passes the maxInFlight headroom, and nothing meters it per worker (#2801). Ordinary timer jitter is far inside the window and is caught up in full at any rate.

Durations. duration and rampUpDuration take a string holding a number with an optional unit: ms, s, m, h, matched as a whole suffix ("500ms" is half a second, not 500 minutes); rampUpDuration also takes a JSON number of seconds. A bare number is seconds - "60" == "60s" - which is also how the MCP duration cap reads the field. Fractions are allowed ("1.5s"), case and spacing are ignored ("30 S"). A value the engine cannot read - an unknown unit, a non-number, a negative - is a 400 with error.code invalid_run_config naming the field, before the run row exists, rather than being silently replaced by the default (see Accepted ranges above).

constant_rps is time-bound, and its shortfall is recorded. Request k (counting from 1) is owed at k / targetRps, so nothing leaves at t = 0 and, when targetRps × duration is whole, the last request is owed at the deadline itself. Each tick submits floor(targetRps × elapsed since the start) minus what it has already taken, so a rate above 1000 is delivered as asked rather than floored to a multiple of 1000, and a late tick owes what the ticks it swallowed would have, sending up to the catch-up window above and skipping the older backlog (skippedRequests). Requests that come due while in-flight is at maxInFlight are dropped at that instant, not deferred: the run ends at its wall-clock duration, and droppedRequests (in the run summary and per-tick metrics) carries what the rate owed but could not issue. sent + skipped + dropped is therefore exactly floor(targetRps × duration), the run's requestsExpected (200 req/s for 20 s: 4000; 33.3 req/s for 3 s: 99), for a run that reaches its deadline. A product that is whole in decimal is read as whole even where binary lands just below it (0.57 req/s for 100 s owes 57).

Capacity semantics. capacity is the one mode whose target is not a function of elapsed time. It holds startConcurrency for stepDuration, judges the level, and then steps up by 25% (at least +1) while the level stayed inside its budget. A level's p99_ms is the percentile of every completion at the level after its first three live ticks, which measure the transition to the new target, read from one histogram; it is not a mean of 100 ms window percentiles, which a level with a periodic pause would pass. Its rps is the mean throughput over the same ticks, and its error_pct the share of the requests completed over them that were errors, by the one definition every surface reports (a status outside 2xx/3xx, or no response; a Stop-cancelled request is neither). Its samples is the count of completions that histogram held; a level of only refused connections is judged on its errors with samples 0 and a p99_ms that measured nothing. A level breaches when its p99 exceeds sloMs or its error share exceeds 1% (constants::capacity::ERROR_RATE_PCT, no run-config knob): a target answering fast 503s is not sustaining the level. The search stops - and names the reason in the report - after two consecutive breaching judged levels (one breaching measurement re-measures the same level rather than ending the search): slo_exceeded when the last one's p99 is over sloMs, errors_exceeded when its p99 is inside sloMs and only its error share is over the limit. It also stops when two step-ups buy under 5% more throughput (plateau; the report then names the level where throughput stopped growing as saturation*, which is lower than maxHealthy*, the last level tried), when concurrency is reached (cap_reached), when duration runs out (deadline), or when the operator stops the run before the search has ended (stopped); a Stop that arrives only after the search ended on its own leaves the reason it had (issue #3341).

An omitted duration on a capacity run defaults to 5 minutes, not the 60 seconds every other mode falls back to: this mode walks a level every stepDuration, so a minute is a dozen levels and a search that almost always ends deadline rather than finding anything. Any client enforcing its own duration ceiling has to account for that per-mode default rather than assuming one number - the MCP tool's cap does.

The search steers by what the metrics thread publishes each live tick rather than sampling the collector itself, so it takes nothing away from what GET /runs/:id/live streams. A level in which no request was timed (latencySamples 0, percentiles null on the frame) and no error was counted is not judged and stays open: reading it as "answered instantly" would climb straight past the limit. A request that timed out is timed (see Latency population), so a level of nothing but timeouts has samples, is judged, and reports a p99 near the timeout - the level fails its latency limit, which is the right verdict. A refused connection records no latency but is counted, so a level of nothing but refusals is judged too, at a p99 of 0 and an error share of 100%, and fails its error limit. A level is also not judged until it has counted at least one completion: the error share is read from status counts that can trail the latency samples by a tick, and judging before they arrive would read a failing level as error-free. capacity is rejected on a scenario run with a 400: the search judges one p99 per level and a sequence has one per step.

Ramp semantics. ramp_up interpolates linearly from startConcurrency to concurrency over rampUpDuration, then holds concurrency for the rest of duration. A startConcurrency above concurrency is a valid descending ramp. If duration is shorter than rampUpDuration, the run stops partway up (or down) the curve. A run whose duration equals rampUpDuration reaches concurrency at the end of the ramp, with no hold after it: when the run's time is up, the controller refills once more to the target its last instant is owed, so the peak does not depend on when it last woke (#2913). That refill sends only what the last target it refilled toward was below the end target: it does not replace requests that completed after the run's time was up, so a run already at its end target (a flat ramp, a ramp shorter than duration, a descending ramp) sends nothing once duration has passed (#3545).

Response bodies are capped. A load-run request reads at most maxResponseBodyBytes (Settings → Data & retention, default 32MB) into memory. Every in-flight request holds its own body, so an uncapped one multiplies by concurrency; a response past the cap fails that request rather than being buffered. It is reported like any other transport failure - statusCode: 0 with an errorCode of INTERNAL_ERROR and a message naming maxResponseBodyBytes - and the truncated prefix is kept as the body. Design mode (POST /execute, and each step of a collection run) has its own cap and its own answer: maxDesignResponseBodyBytes, also 32MB, reached by a send that keeps what it read and reports bodyCapped: true on an otherwise ordinary response. It sends one request at a time, so the concurrency argument above does not apply to it - what does is that the body crosses to the app and is held there as well, and that failing a response the user asked to see would be the wrong trade where showing them the first 32MB of it is not. Neither setting reads the other: raising the load cap does not change what a Send reads.

A script's own fetch (pm.sendRequest) is a third read, and it takes the bound of the path it runs on: the design bound in a Send's or a collection step's scripts, the load bound in a load run's deferred tests script, which runs once per sampled response. It refuses at that bound rather than keeping a prefix, on either path, because nothing on the object it hands the script could say the body was cut - see scripting.

Wire method and body. A body is sent with whatever method the request names: a GET carrying one stays a GET on the wire (Elasticsearch-style search bodies work), where it previously went out as a POST. The one combination that cannot be sent is HEAD with a body - curl's HEAD support drops the body - so it is refused rather than silently changed: statusCode: 0, errorCode: INVALID_METHOD, and a message saying so. This holds identically for POST /execute and POST /runs.

Failed requests still report timing. A transfer that fails (timeout, connection refused, capped body) carries whatever curl measured before it failed - wireMs, the phase breakdown, and bytes/throughput counts - instead of reporting zeros. No phase (dnsMs, connectMs, tlsMs, firstByteMs, downloadMs) is ever negative: tlsMs is 0 for plain HTTP and for a reused keep-alive connection rather than the negative value it used to store.

Metrics & Statistics

What counts as an error

A load run counts a request as an error when its response status is outside 2xx/3xx, or when it got no response at all - a transport failure (a timeout, a refused connection, a DNS or TLS failure), recorded under status code 0. A 3xx is a success. The count is derived from the run's status-code distribution (vayu::count_status_failures, issue #2124), so every surface reports the same number: the live tick's totalErrors / errorRate, the stored tick's requests_failed / error_rate, the stop response's summary.errors / summary.errorRate, the report's summary.failedRequests / summary.errorRate, the maxErrorRatePct budget and pm.info.run.errorRate.

Each of those count surfaces also splits the errors in two, HTTP errors (a response came back, with an error status) and No response:

Surface HTTP errors No response
Live tick (GET /runs/:runId/live) httpErrors noResponse
Stored tick (GET /runs/:runId/metrics) http_errors no_response
Stop response (POST /runs/:runId/stop) summary.httpErrors summary.noResponse
Report (GET /runs/:runId/report) summary.httpErrorRequests summary.noResponseRequests

A request POST /runs/:runId/stop cancels before it is answered is not an error (issue #2136), whether the Stop landed while the run was sending or cut its natural-end drain short (issue #3341). It got no outcome from the target, so it is counted on its own, as cancelled, and is in no other count: not the total, not the status-code distribution, not either half above, not the error rate. A healthy target stopped mid-run therefore reads errorRate 0 however many requests were in flight. The surfaces that carry it:

Surface Cancelled
Live tick (GET /runs/:runId/live) cancelled
Stored tick (GET /runs/:runId/metrics) cancelled
Stop response (POST /runs/:runId/stop) summary.cancelled
Report (GET /runs/:runId/report) summary.cancelledRequests

The cancelled requests of a drain a Stop cut are also counted once more, as drainCut: {cancelled} (issue #3538): on the stored summary, the report's summary and the load row's resultSummary, and only there, never on a run a Stop stopped or one the Stop cancelled nothing from. They are the requests that outlived the sending window, the slowest and the hung, so leaving them out of every figure leaves the run judged on its fastest answers: a reader treats such a run as not judged once no budget failed it (verdict). They are still not errors.

So totalRequests is the requests that got an outcome, successfulRequests + failedRequests, and every request the run sent is in exactly one of totalRequests and the cancelled count. Only a Stop's cancellation is exempt. When a run reaches its natural end and no Stop has been requested, a request still in flight after its effective timeout (the run's timeout, else the defaultTimeout setting) plus a 2s grace is cancelled too, except in a streaming run, whose bound is its maxStreamDurationMs plus grace (the 5s stream backstop plus the same 2s, issue #2834), so a stream still within its cap is never cut. A collection run with a streaming step waits for whichever of the two bounds is longer (issue #3235). A non-stream request cancelled there never answered: it stays an error, under status code 0, and its stored error record carries error_type cancelled (errors.types in the report).

A request libcurl re-sent on a new connection is not an error either (issue #2799). When the server drops or refuses a kept-alive connection after reading a request and before writing a byte of the answer (an idle timeout, a per-connection request cap, an HTTP/2 refused stream), libcurl replays the request on a fresh connection on its own; no option turns that off short of giving up connection reuse. The replayed request is one request with one outcome: counted once in totalRequests and the status-code distribution, a success or an error by the status of its last attempt, and with a latency that covers both attempts. What the target saw is not hidden: each replay is counted in the report's summary.connectionReplays and raises the run's connection_replayed warning, so the target received totalRequests + connectionReplays requests. A non-idempotent request (a POST) may have run twice there.

Latency population

A load run's latency figures all describe one set of requests: every request whose transfer ran, answered or not. That is a response of any status (a 4xx or 5xx included) and a request that failed after the transfer began, where the duration is the time until it gave up (a timeout is about its timeout; a reset, a DNS or TLS failure and a body over the byte cap count the same way). The set feeds the report's latency block (p50 to p999, max), the live tick's windowed latencyP50Ms / latencyP95Ms / latencyP99Ms, its per-second secondP*Ms and cumulative cumulativeP*Ms, the stored ticks' latency_p*_ms, avgLatencyMs and avgQueueWaitMs, the trailing-window means (windowAvg*Ms live, window_avg_*_ms stored), the exports, and the latencyP50Ms / latencyP95Ms / latencyP99Ms budgets. The mean is the sum over the set divided by the set's size, so it agrees with the percentiles and the max. It is not divided by totalRequests.

Left out, because they have no duration to report:

  • a request a Stop cancelled (cancelled), and a request cancelled at a run's natural end after its effective timeout plus the grace (a streaming run's maxStreamDurationMs plus grace), which is an error with no duration;
  • a request refused before the wire: one dropped at the maxInFlight cap (droppedRequests), an invalid URL or an unsendable header, a residual {{token}} or file-rule refusal, a data-binding failure. An invalid URL includes one libcurl itself refuses before it resolves or connects (a URL it cannot parse, such as a space sent as typed with Send URL without encoding on, or a scheme it guessed for a URL naming none) (#2412).

So a run where 5% of requests hit a 2000 ms timeout reports a p99 and max near 2000 ms, and a latencyP99Ms budget below that fails it. totalRequests, errorRate, httpErrors, noResponse and cancelled do not depend on this set. The per-phase histograms of the timing breakdown stay answered-only: a request that failed has no connect, TLS or first-byte split to report. A scenario step's histogram follows the same rule as the run's.

Where libcurl reports the failure, the test is whether the transfer reached the network, not which error it ended with. A reply libcurl cannot read comes back with the same code as a refused URL, but after a real hop, so it is timed. A redirect to a scheme the engine does not send and an unparsable redirect Location are the engine's own refusals, reported by the engine rather than libcurl; the hops before them were answered, so they are timed too. So are a DNS failure, a refused connection, and a client certificate or CA file libcurl cannot read: libcurl reads those files during the TLS handshake, after the TCP connect, so that failure has a duration. (A client certificate whose file is already unreadable when the run resolves its transport is dropped there, with a logged error, and the request goes out without it.)

A stored error row carries the same duration (#2412): its latencyMs in results[], the Samples tab, and the results.latency_ms column hold the time until the transfer gave up, so a request that timed out at 2000 ms is stored at about 2000 ms. A request with no duration (refused before the wire, or cancelled at a run's natural end) is stored at 0. The row has no other way to say "no duration", and 0 can also be a real reading under a coarse clock, so the two cannot be told apart from a stored row; a load run stored by an engine before #2412 holds 0 for every error. That bounds one report: a run whose summary holds no latency (a failed run that wrote no summary, or one the engine died under, whose summary is rebuilt from its last tick and flagged summary.partial) is reported from its stored rows alone, and there every stored row, a 0 included, is in the percentiles and the mean, which divides by the rows stored rather than by this population. A run that finished on its own reports from its summary, which this does not affect. Those two reports write no latency block at all (#2938), so none of this reaches a reader for them.

The sequential collection runner follows the same population, with two differences: its latency block is computed exact nearest-rank over every sent step's duration rather than from an HDR histogram, and a run in which no step sent stores a count of 0 and the report omits the block (issue #2389).

GET /runs/:runId/metrics

Paginated historical time-series (JSON) for a run's charts. The response is always JSON - any format query param is ignored.

Query parameters: - limit - max records per page (default 5000, invalid/≤0 falls back to 5000, capped at 50000). - offset - skip N records (default 0, negative floored to 0). - maxPoints - return the whole series as at most this many ticks (capped at 50000; anything but a positive integer is treated as absent). limit and offset are then ignored. See Downsampling with maxPoints.

Per-tick rows carry the latency percentiles of their second (latency_p50_ms / latency_p95_ms / latency_p99_ms, snake_case): every 100 ms window since the previous row merged as one histogram before the percentile is read (issue #2385), so a stall anywhere in the second is in its row. They sit alongside rps/throughput/concurrency/status codes, so the history view can rebuild the percentiles-over-time chart, the response-time-vs-concurrency scatter, and the capacity-breakpoint / saturation stats from stored data. The live tick that wrote a row carries the same three figures as secondP50Ms / secondP95Ms / secondP99Ms. A row stores no sample count, and a second with no completion has none of the three keys (issue #2386), the frame's secondSamples 0 and null percentiles: absent rather than null because the run export types them as numbers. Rows an engine older than issue #2386 stored hold 0 for such a second, and rows older than issue #2385 hold the last 100 ms window of their second instead.

Response:

{
  "data": [
    {
      "timestamp": 1234567890,
      "elapsed_seconds": 10.5,
      "requests_completed": 1500,
      "requests_failed": 5,
      "http_errors": 5,
      "no_response": 0,
      "cancelled": 0,
      "current_rps": 150.5,
      "current_send_rate": 151.0,
      "window_avg_in_flight": 6.7,
      "window_avg_latency_ms": 44.8,
      "window_avg_queue_wait_ms": 0.3,
      "current_concurrency": 100,
      "send_rate": 150.0,
      "throughput": 149.5,
      "backpressure": 0,
      "error_rate": 0.33,
      "dropped_requests": 0,
      "skipped_requests": 0,
      "stalled_ms": 0,
      "bytes_sent": 48000,
      "bytes_received": 1920000,
      "status_codes": { "200": 1495, "404": 3, "500": 2 },
      "status_seconds": [ { "second": 10, "span": 1, "counts": [149, 0, 1, 0, 0] } ],
      "latency_p50_ms": 38.5,
      "latency_p95_ms": 95.1,
      "latency_p99_ms": 12.0
    }
  ],
  "pagination": { "total": 1, "limit": 5000, "offset": 0, "hasMore": false, "returned": 1 }
}

requests_failed is the producer's own error count, written into the tick at write time, by the one error definition and from the same status-code snapshot as that tick's status_codes; http_errors and no_response split it. cancelled is the requests a Stop cancelled so far, outside all three (issue #2136); a tick stored before that issue has no cancelled key. It is not derived at read time from error_rate and requests_completed any more - that derivation depended on the order the EAV rows came back in, and reported 0 failed requests for every bucket of every run. A tick an engine older than issue #2124 stored has no http_errors / no_response, and its requests_failed counted no-response failures only.

current_rps and current_send_rate are completions and dispatches per second over the trailing window ending at the row's tick (issue #2393): at least the last second, divided by the window's actual span (one second plus up to one tick interval), and until a run has a second of ticks, everything since its first tick. window_avg_latency_ms and window_avg_queue_wait_ms are the mean latency and queue wait of the latency population that completed in the same window, null when nothing did. window_avg_in_flight is the mean number of requests in flight over the same window (issue #2821): the time requests spent in flight during the window, divided by its span (issue #3567). A request is in flight from its submission to the event loop until it completes, its queue wait inside the generator or libcurl included, and it counts for every part of the window it was open in, so requests open across the whole window with none completing read their count, and a request longer than the window never reads above one. A virtual user in a timer wait (timer.think, timer.pacing, timer.throughput) has none in flight, and neither does a request refused or skipped before it reached the event loop (a maxInFlight drop, a data-binding failure, a step a controller skipped). A request a Stop cancels after submission was in flight until the cancellation. With no think time it equals the virtual user count. It is a number, 0 for a window with nothing in flight, never null. Before issue #3567 the same key held the latency the window's completions carried divided by its span, which read 0 while a request longer than the window was still open and spiked when it completed; rows stored before the change keep that value under the same key. The live frame of the same tick carries the same five values as currentRps, currentSendRate, windowAvgInFlight, windowAvgLatencyMs and windowAvgQueueWaitMs. current_concurrency and backpressure are instantaneous: see the live frame's activeConnections and backpressure below, which they equal. A run whose virtual users wait in step aliases them between 0 and the user count, which is what window_avg_in_flight answers instead. send_rate and throughput are cumulative: requests sent and completed since load start, divided by the time since load start, so they flatten a change of rate the window shows within a second. A tick stored before issue #2393 has none of the three new keys, and its current_rps divided the completions since the previous row by the time since it. A tick stored before issue #2821 has no window_avg_in_flight.

status_seconds (issue #2866) is the seconds the row's gate closed, each with the responses that completed in it, by class: second counts from load start (the clock elapsed_seconds counts from), span is 1, and counts is [2xx, 3xx, 4xx, 5xx, error], where error is a response with no status (code 0) or a code outside 200-599. A second is closed 250 ms after it ends, so a row usually holds one second, two when its gate's cadence crosses two second ends, and [] when none closed since the last gate. Across a run's rows the seconds run on from 0, one entry each, and a second in which nothing completed is an entry of zeros. Each response is counted by the clock it completed at, not by the tick that read it, so counts[i] / span is a class' rate that a batch landing near a tick does not move; the difference of two rows' status_codes counts what landed between their ticks instead. The live gate frame of the same tick carries the same entries as statusSeconds. The second still open when the run ends is stored nowhere, and the seconds that close after the last row ride the final live frame only. A tick stored before the issue has no status_seconds.

A missing run returns 404 with the message Run not found.

Storage. Each data[] entry is one stored row of metric_ticks - the engine writes the tick object once, at write time. Two things follow:

  • Pagination is tick-aligned: limit/offset count ticks, so pagination.total is the number of ticks (not rows), and a page boundary can no longer return a tick with half its fields zeroed.
  • elapsed_seconds keeps counting across pages, since it is stored with the tick: the seconds since load start, the same reading the live frame of that tick carries as elapsedSeconds (issue #2881). No tick is stored before load start, and the first stored tick reads between 0 and about 1.0 (the 1 Hz gate counts from the metrics thread's start, so after a setup script it can land anywhere up to one interval after load start). A run an engine older than that issue stored counts from its first stored tick instead, so its first tick reads 0, about one second behind the live clock.

A run with no ticks returns 200 with an empty data array - only a run that does not exist is a 404.

Downsampling with maxPoints

Without maxPoints the answer is exactly the paged series above (issue #2547 adds no key to it). With it, the engine reads every stored tick and answers in one response:

  • If the run has at most maxPoints ticks, every tick comes back unchanged.
  • Otherwise each run of ticksPerBucket = ceil(total / maxPoints) consecutive ticks, in stored order, is folded into one; the last bucket may be shorter, and a one-tick bucket is that tick unchanged.

The envelope gains two top-level keys on this path only:

{
  "data": [ ... ],
  "pagination": { "total": 86400, "limit": 2000, "offset": 0, "hasMore": false, "returned": 1964 },
  "bucketed": true,
  "ticksPerBucket": 44
}

pagination.total is the stored tick count, limit echoes maxPoints, returned is the number of data entries and hasMore is always false. bucketed is false and ticksPerBucket is 1 when the series already fit.

Most tick fields are cumulative (a run total or a rate over the run so far), so a folded tick is its bucket's last tick, with a few keys replaced:

Field Folded value
timestamp, elapsed_seconds The last tick's
requests_completed, requests_failed, http_errors, no_response, cancelled, dropped_requests, skipped_requests, stalled_ms, bytes_sent, bytes_received The last tick's (run totals)
error_rate, send_rate, throughput The last tick's (run-long rates)
status_codes, custom_metrics The last tick's (cumulative maps)
latency_p50_ms, latency_p95_ms, latency_p99_ms The max over the bucket, its worst second
current_concurrency, backpressure The max over the bucket
current_rps The mean over the bucket's ticks
current_send_rate The mean over the bucket's ticks (#2393)
window_avg_in_flight The mean over the bucket's ticks (#2821): each covers about its own second, so this is the bucket's mean in flight
window_avg_latency_ms, window_avg_queue_wait_ms The mean over the bucket's ticks that carried a number, null when none did (#2393)
status_seconds Every entry of the bucket's ticks merged into one (#2866): the first entry's second, span the seconds the entries cover and counts summed per class, so counts[i] / span is still responses per second; [] when the ticks closed no second
Any other key The last tick's

The latency fields are never averaged: each row's percentile is of its own second, so the bucket's max is an upper bound on the bucket's percentile, not an estimate of it, and a one-second spike survives into the bucket that holds it. A second with no completion carries none of the three keys (issue #2386) and so takes no part in the max: a bucket has them only when one of its seconds completed something. A bucket of rows an engine older than issue #2386 stored reads 0 only when none of its seconds completed anything, which is what those rows store for such a second. Rows an engine older than issue #2385 stored hold the last 100 ms window of their second instead, and the max is then taken over those windows. A key no tick in the bucket carried (http_errors on an older row, custom_metrics on a run that recorded none) is never added.

Only GET /runs/:runId/metrics and GET /runs/:runId/monitor (the same parameter, folded differently) downsample. The run-report export (POST /export/run-report) and the MCP get_run_timeseries and get_run_monitor tools read the raw rows.

GET /runs/:runId/monitor

Paginated server vitals scraped during the run - the samples the monitor block collected. Same {data, pagination} envelope and the same limit / offset rules as GET /runs/:runId/metrics, so one pagination reader covers both.

Query parameters: - limit - max records per page (default 5000, invalid/≤0 falls back to 5000, capped at 50000). - offset - skip N records (default 0, negative floored to 0). - maxPoints - return the whole series as at most this many samples (capped at 50000; anything but a positive integer is treated as absent). limit and offset are then ignored. See Downsampling the monitor series.

Its own endpoint rather than extra keys on the tick objects: that key set is the /metrics contract, and these samples land on the user's scrape cadence rather than the tick cadence, so they do not line up row for row.

Response:

{
  "data": [
    {
      "timestamp": 1234567890,
      "series": { "node_cpu_seconds_total": 3.75, "process_resident_memory_bytes": 1048576 }
    }
  ],
  "pagination": { "total": 1, "limit": 5000, "offset": 0, "hasMore": false, "returned": 1 }
}

timestamp is wall-clock Unix ms - when the engine scraped, not an elapsed offset - because the scrape starts with the run while a tick's elapsed_seconds counts from load start, after any script.setup; a stored tick carries the same wall clock, so joining the two series onto one timeline is what timestamp is for. A series the target did not report in that scrape is absent from its series object rather than zero.

The two fields are read off different clocks, which is why they can disagree. timestamp is wall time, so it moves when the host's clock is adjusted, while every elapsed figure the engine reports (elapsed_seconds here, and a run's duration and rates) is measured on a monotonic clock that an NTP step or a manual clock change cannot move. Over a run that spans an adjustment, the difference between two timestamp values is therefore not exactly the difference between their elapsed_seconds; the elapsed pair is the one that measures how long the run actually took.

A run that configured no monitor returns 200 with an empty data array; only a run that does not exist is a 404. Samples are deleted with the run, like every other child row.

Downsampling the monitor series

maxPoints here is the same contract as on /metrics (issue #2611), read from the same monitor_samples rows in stored order (by timestamp, then insertion):

  • Without it the answer is exactly the paged series above; no key is added.
  • With a series of at most maxPoints samples, every sample comes back unchanged and bucketed is false.
  • Otherwise each run of ticksPerBucket = ceil(total / maxPoints) consecutive samples is folded into one (the key keeps the tick series' name, though a bucket here holds samples); the last bucket may be shorter, and a one-sample bucket is that sample unchanged.

The envelope is the one the tick series answers with: pagination.total is the stored sample count, limit echoes maxPoints, offset is 0, hasMore is false, returned is the number of data entries, plus bucketed and ticksPerBucket on this path only.

A folded sample is {timestamp, series} like any other:

Field Folded value
timestamp The last sample's
each series.<name> The max over the bucket's samples that carried it

The max keeps a one-scrape spike in a gauge (cpu, memory, a queue depth) that a mean would flatten, and for a monotone counter it equals the last reading. A name no sample in the bucket carried is never added to the folded series, so a gap in the target's reporting stays a gap; a non-number value is skipped. The MCP get_run_monitor tool does not pass maxPoints and reads the raw samples.

GET /runs/:runId/live

Stream live metrics for a run via Server-Sent Events, replayed from a retained in-memory tick topic. The engine produces one wire-ready metrics tick per liveTickIntervalMs (default 100ms) into a per-run buffer; this endpoint replays that buffer from offset 0 (or, for a reconnecting client that names a resume point, from the frame after it) and then tails new ticks until the run finishes, ending with a complete event. Because the topic is retained for liveRetentionMs (default 60000ms) after completion, a client that connects late - even after a sub-second run has already finished - still receives the full series. There is no attach race.

Events:

event: metrics
id: 0
data: {"runId":"...","timestamp":1234567890,"elapsedSeconds":10.5,
       "totalRequests":1500,"totalSuccess":1495,"totalErrors":5,"errorRate":0.33,
       "httpErrors":5,"noResponse":0,"cancelled":0,
       "currentRps":150.5,"currentSendRate":151.0,
       "sendRate":150.0,"throughput":149.5,
       "activeConnections":100,"backpressure":0,"phase":"sending","droppedRequests":0,
       "skippedRequests":0,"stalledMs":0,
       "avgLatencyMs":45.2,"avgQueueWaitMs":0.4,
       "windowAvgInFlight":6.7,"windowAvgLatencyMs":44.8,"windowAvgQueueWaitMs":0.3,
       "latencySamples":15,"latencyP50Ms":38.5,"latencyP95Ms":95.1,"latencyP99Ms":156.7,
       "cumulativeP50Ms":36.0,"cumulativeP95Ms":90.2,"cumulativeP99Ms":160.4,
       "bytesSent":48000,"bytesReceived":1920000,
       "requestsSent":1500,"requestsExpected":0,
       "status2xx":1495,"status3xx":0,"status4xx":3,"status5xx":2,
       "statusCodes":{"200":1495,"404":3,"500":2}}

event: complete
data: {"event":"complete","runId":"run_1234567890","status":"completed"}

status is the run's own terminal status - completed, stopped or failed - and it is what tells a client which of the three happened while the run is ending, rather than after the stored report has been fetched (issue #1415). complete is sent only once the run has written that status (issue #2140): the last tick can land while the run is still finishing - flushing results, replaying deferred scripts and schema validation, running script.teardown, storing the summary - and the stream stays open, sending nothing, until that pass ends. status is omitted only when the engine gave up waiting, 60s after the last tick was sent (LIVE_SETTLE_TIMEOUT_MS), or the status write itself failed. A client must read that as "ask the report", never as success: the field is absent on that frame, not null, and a client older than it saw no status at all.

elapsedSeconds is the time since load started, the instant the report's testDuration is measured from: after the request is built and any script.setup has run, immediately before the first submission (issue #2395). Until then the run is still setting up, and every frame carries elapsedSeconds: 0 with sendRate and throughput at 0, because both divide by it. The last frame, published just after load ends, therefore reads within a fraction of a second of the report's testDuration. currentRps and currentSendRate do not divide by it: they divide by the trailing window's own span on the monotonic clock (issue #2393), so they read 0 while nothing is sent, and a window that reaches back before load start counts that idle time in its span. An engine older than that issue counted from when the run was registered, so a slow setup ran its live clock ahead of the report and dragged the rates down. The last frame's sendRate is still not the report's: the report divides requests sent by the sending window, which ends before the end-of-run drain, where a live frame divides by everything elapsed so far (GET /runs/:runId/report, issue #2392).

A capacity run's frames carry one more key, the search's state (the capacity row of the field reference below), here three seconds into the search's third measurement:

data: {..., "capacity":{"level":16,"levelElapsedMs":3000,"levelsJudged":2}}

A scenario run streams step events instead of metrics ticks. One per step execution, on the same ring and the same monotonic id: numbering, so Last-Event-ID resume works identically and a client that reconnects mid-run replays the steps it missed:

event: step
id: 3
data: {"iteration":1,"stepIndex":0,"name":"Log in","outcome":"passed",
       "statusCode":200,"latencyMs":42.7,"dataRowIndex":1,
       "requestId":"req_abc123",
       "tests":{"passed":2,"failed":0},"extractorMisses":1,
       "unresolvedTokens":1,
       "validation":{"checked":true,"valid":true,"matchedStatus":"200",
                     "matchedContentType":"application/json",
                     "failures":[],"failuresTotal":0}}

event: complete
data: {"event":"complete","runId":"run_1234567890","status":"completed"}

status carries the same three values and the same absent-means-ask rule as on the metrics stream above.

outcome is one of passed, failed, skipped, errored, stopped - see Scenario runs. dataRowIndex is present only for a run with data, on the same terms as on the stored row, so a step reads the same live and after a reload. stepsNotRun follows the same rule: present only on the step whose error ended its iteration short of the plan's end, with how many plan positions that cost (see Outcomes under Scenario runs), and absent rather than 0 everywhere else. extractorMisses is the stored row's count of extractions that found nothing (#3053), on the same terms, and unresolvedTokens its count of names the step sent unresolved (#3248). validation is the step's schema verdict (issue #681) in the same shape and on the same terms - absent for a step of an unbound collection and for one that sent nothing, and byte-identical to the node its stored trace carries, so a watched run and a read-back one agree. tests is how many of the step's assertions held (issue #724) - two numbers, because the ring is fixed-size and a script may make hundreds of them; the list itself rides the stored scripts node. It counts exactly the assertions that node lists - both script phases, every level's (#2522), and assert.* elements beside them - and is absent for a step that asserted none: 0 passed would read as a result. requestId names the stored request the step ran (issue #831) - the same id stamp_step_identity writes onto the stored trace, so a step read live and the same step read back from the report name one request, and a client watching a run can offer the way back to it before the rows are written. One id is constant-size, which is why it rides the frame where the assertion list does not; absent when the plan step names no stored request, because an empty id is not a request. A stopped step carries no tests and no validation: what its scripts made of a cancelled send is no verdict. A scenario run publishes no metrics ticks: its work is sequential, so per-tick aggregates would be a rate of one request at a time rather than anything about the sequence.

Its stream opens with one plan frame (issue #1398), published before the first step:

event: plan
id: 0
data: {"stepsPerIteration":4,"iterations":3,"stepsExpected":12}

stepsPerIteration is the plan's length, steps in one pass over it. iterations is how many passes the engine resolved - a data set's row count where the run named no explicit count of its own. stepsExpected is stepsPerIteration * iterations, an upper bound rather than a promise, on the same terms as a scenario load run's requestsExpected while it runs (the live frame table below): an errored step can end its iteration (see Outcomes under Scenario runs), POST /runs/:id/stop ends the run, setNextRequest can walk an iteration in fewer steps than the plan holds, and the maxStepsPerIteration cap can end one that walks in more. It rides the same monotonic id space as the step frames that follow - the same ring, so Last-Event-ID resume works identically - and a client that attaches after the frame has aged out of the retained ring simply never sees it: it should read that as no total rather than compute a fraction of a number nobody sent, and show an indeterminate bar the way it would against an older engine that never sent this frame at all. One frame ahead of the work rather than a number on every tick, because this run publishes no ticks to carry one: the load path's total rides its metrics events precisely because that path has them. (A collection run's report likewise reads its latency from the stored summary, not from ticks: see the report.)

A run with a monitor block also streams monitor events, one per successful scrape, interleaved with its metrics ticks on the same ring and the same monotonic id: numbering - so Last-Event-ID resume replays both kinds in the order they happened:

event: monitor
id: 12
data: {"timestamp":1234567890,
       "series":{"node_cpu_seconds_total":3.75,"process_resident_memory_bytes":1048576}}

The payload is byte-identical to one data[] entry of GET /runs/:runId/monitor, so the live overlay and the history overlay are drawn from the same rows. A scrape that read nothing emits no frame.

Field reference (every key of a metrics frame; MetricsCollector::get_current_stats() builds all but the trailing-window keys (eventsPerSecond among them) and a capacity run's capacity, which the metrics thread adds on every tick, and the second*, cumulativeLatency, cumulativePhases, streamTimeToFirstEvent, statusSeconds and scenario keys, which it adds on a gate tick):

Field Meaning
totalRequests / totalSuccess / totalErrors Completed counts; totalErrors by the one error definition
httpErrors / noResponse totalErrors split: an error status came back, or no response did
cancelled Requests a Stop cancelled before they answered; in none of the counts above (issue #2136)
errorRate totalErrors as a percentage of the status-code distribution's total
currentRps / currentSendRate Completions / dispatches per second over the trailing window (issue #2393): at least the last second (LIVE_RATE_WINDOW_MS), divided by its actual span, and everything since the first frame until the stream has a second of frames. 0 for a window with nothing in it. A gate frame's pair is its stored row's current_rps / current_send_rate
sendRate Requests dispatched per second, cumulative: requestsSent over the time since load start
throughput Responses received per second, cumulative: totalRequests over the time since load start
activeConnections Transfers active in the curl workers at the sample, the stored tick's current_concurrency. Instantaneous: a virtual user in a timer wait holds none, so a run whose users wait in step reads 0 or the user count depending on where the sample lands. windowAvgInFlight is the mean
backpressure In flight at the sample: requests sent but not yet settled (RunContext::in_flight), plus, on a closed-loop single-request run only, every slot a timer.think wait still holds. A scenario run's timer waits are not counted, because its dispatcher treats a waiting virtual user as not in flight, and a constant_rps run reserves none, because it skips the timer (#3541). The same figure as the stored tick's backpressure and the high-water mark behind the report's peakConcurrency, so on a single-request think-timer run it exceeds requestsSent - totalRequests, and once a Stop has cancelled requests it is requestsSent - totalRequests - cancelled
phase Where the run's worker is at the sample (issue #3568), on every frame: setup, sending, draining (the strategy returned on its own and backpressure is the in-flight requests the natural-end drain waits out, no longer new load), summarising or settled. A run moves forward only and may skip one; see Stop semantics for what a Stop does in each. Live only: no stored row carries it, and an older engine sends no such key
droppedRequests Requests discarded at the maxInFlight cap (never sent)
skippedRequests / stalledMs constant_rps only (#2911): requests a stalled pacer owed beyond its 100 ms catch-up window and skipped (never sent, not in droppedRequests), and the schedule time they cover in ms, skippedRequests ÷ targetRps. 0 on every other mode
avgLatencyMs Mean perceived latency over the same requests as the percentiles and the max (Latency population): answered requests plus those that failed after their transfer ran
avgQueueWaitMs Mean time queued before the wire, inside the generator or in libcurl waiting for a connection slot (#2394), over the same requests as avgLatencyMs (Latency population)
windowAvgLatencyMs / windowAvgQueueWaitMs The same two means over only the requests that completed in the trailing window currentRps covers (issue #2393), from the difference of the run's sums and counts across it; null when nothing completed in it. A gate frame's pair is its stored row's window_avg_latency_ms / window_avg_queue_wait_ms
windowAvgInFlight Mean requests in flight over the same trailing window (issue #2821): the time requests spent in flight during the window divided by its span (issue #3567), so a request open across the window counts whether or not anything completed. A request is in flight from submission to completion, queue wait included, and a Stop's cancellation ends it; a timer wait between requests and a request refused or skipped before it reached the event loop are not. With no think time it equals the virtual user count, and it does not alias the way activeConnections does. 0 for a window with nothing in flight, never null. A gate frame's value is its stored row's window_avg_in_flight
latencySamples How many completions the tick's window held, the population of the three below (issue #2386). 0 says the window had no completion, which no percentile can say
latencyP50Ms / latencyP95Ms / latencyP99Ms Live windowed percentiles over the latency population - the last tick's window (100 ms at the default cadence) sampled from a phaser-based hdr_interval_recorder; null when latencySamples is 0, never a 0 ms reading (issue #2386; an engine before it wrote 0). The capacity search steers by these
cumulativeP50Ms / cumulativeP95Ms / cumulativeP99Ms The same percentiles over every completion so far, the span avgLatencyMs covers, merged from every window sampled up to this tick; on every frame, null until something has completed. The final report's latency block is the same population read from the run's own histogram
secondSamples, secondP50Ms / secondP95Ms / secondP99Ms Gate frames only (issue #2385): the frame of the tick that wrote a stored row, about once a second, carries that row's figures - every window since the previous gate merged, and how many completions they held. The final frame carries them too, for the partial second since the last gate, which is stored nowhere. The percentiles are null when secondSamples is 0. Absent from every other frame
cumulativeLatency Gate frames only (issue #2782), the final frame included: the run-so-far latency distribution, {minMs, p50Ms, p75Ms, p90Ms, p95Ms, p99Ms, p999Ms, maxMs, count}, over the same completions as the cumulative*Ms keys. null until something has completed, never zeros. The final frame merges the last window after the drain, so its figures are the report's latency block. Absent from every other frame
cumulativePhases Gate frames only (issue #2782): {dns, connect, tls, firstByte, download}, each {meanMs, p50Ms, p95Ms, p99Ms, maxMs, count}, from the same per-phase histograms as the report's timingBreakdown, which every successful completion feeds. null until a completion has recorded its phases; absent when the run has the phase histograms off, so absent means "not measured" and null means "nothing yet". Read while the run is still recording, one phase at a time, so a mid-run reading's phase counts can differ from each other and from its frame's counts by the completions that landed between the reads; the final frame is read after the drain and its means are the report's avg*Ms. Absent from every other frame
streamEvents / streamsOpen Streaming runs only (issue #3236; a single-request run with stream, or a collection load run with a streaming step, #3304), on every frame, and only while stream_metrics is on: the events delivered so far, counted on the write path as they arrive rather than when a stream completes, so a run of long streams is not blank until the first one ends; and the streaming transfers open at the sample, which on a collection run that mixes streaming and ordinary steps is fewer than activeConnections (that one counts every transfer). A stream leaves streamsOpen however it ends (a cap, the server's close, an error, a Stop), so the settled frame reads 0. Once the run settles, the final frame's streamEvents equals the report's stream.totalEvents, the unterminated last frame a close completes included; a run a Stop ended also counts the events of the streams it cancelled, which the report does not. Absent from every other run's frames, never zeroed
eventsPerSecond Streaming runs only (issue #3236), on the same frames as streamEvents: events per second over the trailing window currentRps covers, from the difference of streamEvents across it. 0 on the first frame and for a window with nothing in it. Live only: no stored row carries it
streamTimeToFirstEvent Gate frames only (issue #3236), on the runs that carry streamEvents: {p50, p95, p99, max, count} in milliseconds, from submission to the first event, over the streams completed so far, from the histogram behind the report's stream.timeToFirstEvent; a stream still open is not in it. Absent until a completed stream delivered a timed event, and from every other frame
bytesSent / bytesReceived Cumulative wire bytes: every hop's headers and body, each counted once, so a followed redirect counts its own response (body included) and, for a 307/308, the request body it sent again (issue #2893)
requestsSent / requestsExpected Progress for bounded modes (drives ETA). A scenario iterations run starts requestsExpected at iterations x steps per iteration, an upper bound while it runs because an abandoned iteration never sends its later steps; a natural end settles it to the sent count, so the final frame reads 100%. A stopped run keeps the upper bound (issue #2914)
capacity Capacity runs only (issue #2928), on every frame from tick 0: where the search stands, {level, levelElapsedMs, levelsJudged, stopReason?}. level is the concurrency being measured, 0 until the first level opens (tick 0 is emitted before it does). levelElapsedMs is the time since that level opened, 0 while level is 0, and held at the moment the search ended once it has. levelsJudged counts the levels judged so far, a re-measured level once per measurement, so the report's capacity.levels holds that many rows. stopReason appears once the search has ended, with the value the report's capacity.stopReason carries, stopped included, and is absent while it runs. The four are published together, so one frame never pairs a level with another level's time or count. Absent from every other run's frames, never zeroed
status2xx–status5xx Per-class counts
statusCodes Full per-code distribution map
statusSeconds Gate frames only (issue #2866), the final frame included: the seconds since load start that closed since the previous gate, [{second, span, counts}] with span 1 and counts [2xx, 3xx, 4xx, 5xx, error], each response counted in the second it completed in. A gate frame's entries are its stored row's status_seconds, drained once for both, so live and History hold the same seconds; the final frame's are the seconds closed since the last gate, which only it carries. [] when no second closed. Absent from every other frame
scenario Gate frames only (issue #2823), the final frame included, and only on a scenario load run: the sequence so far, {iterations, iterationsCompleted, iterationsAbandoned, stepsExecuted, steps: [{index, name, executed, errors}]}, one steps entry per plan step in plan order. The same counters as the stored summary's scenario block (iterations, iterations_completed, iterations_abandoned, steps_executed, and each step's executed and errors), read while the workers still write, so a mid-run reading's figures can differ from each other by the completions that landed between the reads; the final frame is read after the drain and equals the summary. No latency: a step's percentiles are in the report alone. Absent from every other frame and from every frame of any other run

Read order within one tick. The metrics thread snapshots the status-code distribution first, then get_current_stats() reads the completed count (totalRequests) afterwards, and the stored row's requests_completed is read after the same snapshot. So totalErrors, errorRate and the status* keys all come from the earlier snapshot and totalRequests, totalSuccess and throughput from the later read. A completion landing between the two makes status2xx + status3xx up to one tick of completions lower than totalSuccess, and a client's totalErrors / totalRequests marginally lower than the frame's errorRate. The skew is invisible at the default 1 Hz cadence, and the order is the safe one: errorRate divides by the snapshot's own total, so no rate exceeds 100 percent.

Each metrics event carries an id: equal to its zero-based offset. The browser's built-in EventSource retry automatically replays this id as Last-Event-ID on its own intra-connection retries (no application code needed), and the stream resumes from Last-Event-ID + 1.

?lastEventId=<id> is the same resume point as a query parameter, for a client that reconnects by hand: EventSource sets Last-Event-ID only on its own retry and exposes no way to set a header on a fresh connection. The header wins when both are given. Frame ids start at 0, so lastEventId=0 means "I saw frame 0" rather than "from the start"; absence is what means the start. A value that is not a non-negative frame id is refused with 400 and code invalid_last_event_id rather than resumed from the start, which would replay every retained tick to a client that already holds them - the change feed and inbox streams' rule.

Replay window. The in-memory tick topic is a bounded ring, so a long run's memory does not grow with its duration. Its span is liveReplayWindowMs (default 300000, i.e. 5 minutes) and the tick count is derived from that window and the configured cadence - liveReplayWindowMs / liveTickIntervalMs, 3000 ticks at both defaults. The bound is a duration rather than a fixed count because the cadence is itself configurable: one tick count would mean a 30-second window at liveTickIntervalMs=10 and a 50-minute one at 1000. liveReplayWindowMs = 0 means the full run (no time limit). Whatever the pair, the ring is capped at liveMaxRetainedTicks (default 50,000, ~50 MB), so a fast cadence reaches that ceiling before a long window does. Raising it is cheap at stock settings - the window, not the ceiling, is what sizes the ring.

Ids keep counting past an eviction, so they stay monotonic; a Last-Event-ID older than the retained window resumes from the oldest retained tick rather than replaying from 0, which means a client that was disconnected for longer than the window sees a gap, not a duplicate flood.

The window also bounds the replay-from-0 path, which the bundled app takes on a first attach: a dashboard attaching mid-run rebuilds its chart from the retained ring. Its Reconnect resumes with ?lastEventId= instead and is sent only the frames after the last one it holds. That is why liveReplayWindowMs is the same setting as the app's live-chart window rather than a second one to keep aligned - the app's Settings → Live Dashboard → Chart window picker reads and writes this entry (GET/POST /config), so the span the engine retains and the span the chart displays cannot disagree. Editing it here and editing it there are the same action.

The final metrics event is emitted only once the run's worker has actually settled. On POST /runs/:runId/stop the engine keeps ticking while in-flight requests are cancelled and counted as cancelled, so the last live numbers agree with the stored report rather than freezing at the moment of the stop request.

Application-level reconnect: a client that closes the EventSource itself (e.g. after observing readyState === CLOSED) and opens a new connection resumes with ?lastEventId=<id of the last frame it held>, because a fresh EventSource sends no Last-Event-ID and would otherwise start at offset 0 and replay the entire retained topic, duplicating ticks already shown. A connection that names no resume point is the first attach and does start at 0. The other recovery is to converge on the stored report via GET /runs/:runId/report (the same path used at normal run end).

Responses: - 200 - SSE stream (active run, or finished run still within the retention window). - 404 - no live topic for the run. The flat body is {"error", "code", "hint"} and code says which of two cases it is (#2775): - live_expired - the run is stored but its topic aged out past liveRetentionMs; error is Live metrics for this run are no longer retained. - run_not_found - the engine has no run by that id; error is Run not found or expired.

Both hint Use /runs/:runId/report for the stored report, and a client should fall back to the stored report in either case (for run_not_found the report then answers its own 404). code is for clients to branch on; the bundled app has no reader for it yet. MCP's get_live_metrics reads it (#2779): live_expired answers that the buffer expired and the run still exists, naming get_run_report, and run_not_found keeps the unknown-id text.

Tuning: liveTickIntervalMs (live tick cadence, 10–1000ms), liveReplayWindowMs (retained replay span and the dashboard's chart window, 0–3600000ms; 0 = full run), liveMaxRetainedTicks (the tick ceiling for that window on both sides, 1000–500000) and liveRetentionMs (post-completion retention, 0–600000ms; 0 disables retention) are configurable via POST /config.

GET /runs/:runId/events

Relay a streaming run's events via Server-Sent Events (issue #573). Started by POST /execute with "stream": true, which returns this URL as eventsUrl.

The endpoint replays the run's retained events, then tails until the stream terminates, and closes with a complete event naming the termination reason. complete is sent only once the post-request script has run and the run row and trace are stored (#3239), so a GET /runs/:runId/report made on it already reads the result and a terminal status. Like the live-metrics topic, the ring is retained for liveRetentionMs after the stream ends, so a client that connects late - even after a short stream has already finished - still receives the whole series.

Events:

event: open
id: 0
data: {"statusCode":200,"statusText":"OK","headers":{"content-type":"text/event-stream"}}

event: message
id: 1
data: {"event":"token","data":"Hello","sourceId":"42","receivedAt":1234567890}

event: complete
data: {"runId":"run_1234567890","reason":"completed","totalEvents":128}

  • open is published once, as soon as the response's header block arrives, so even a late consumer learns what the stream connected to. A reply with no body (a 204, a bodiless 401, an empty 200) still publishes it, with its status, before complete (#3342). With followRedirects on it describes the hop the stream ends at: a redirect the stream follows publishes no open, and its body is neither an event nor counted. Neither does an interim 1xx (a 100 Continue) nor a proxy's answer to CONNECT: a tunnel refused there ends the stream as error with no open. A stream that failed before any response arrived has none either, and neither does one that ends on a redirect the engine refuses to follow (too many hops, an unsendable scheme).
  • message carries one upstream event: its event name (message when the origin sent none), its data (multiple data: lines joined with \n), the origin's own id: as sourceId, and receivedAt. An event larger than sseMaxEventBytes is stored as a prefix and says so in band, with dataTruncated: true and dataBytes (the size as sent) - never silently cut.
  • complete's reason is one of completed, stopped, shutdown, maxStreamEvents, maxStreamDurationMs, idleTimeout, error; see POST /execute. No frame carries the exchange's warnings (issue #3315): they are on the stored trace, which the report already holds when complete arrives.

sourceId is not the resume point. id: on the wire is this relay's own frame offset, which is what ?lastEventId= / Last-Event-ID takes; sourceId is what the origin would want back. Conflating them would make one of the two resumes silently wrong.

Resume picks up at the frame after the one named, so a dropped consumer re-renders nothing. The header wins over the query parameter when both are present (EventSource cannot set a header on a fresh connection, so a client owning its retry uses the parameter). Unlike the inbox's capture ids, frame ids start at 0, so lastEventId=0 means "I saw frame 0" rather than "from the start"; absence is what means the start. A present-but-unreadable value is a 400 (invalid_last_event_id) rather than a silent replay from 0. A resume point older than the retained window is fast-forwarded to the oldest retained frame rather than looping on ids that will never come back.

One consumer at a time. Each stream parks a cpp-httplib pool thread for its whole life, so a second concurrent watcher is a 409 (run_events_in_use) - but a claim whose holder has stopped writing for two keep-alive intervals is taken over instead of refused, since EventSource treats a 409 as fatal and a reconnect racing the previous socket's death would otherwise kill the stream for good.

Responses: - 200 - SSE stream (live stream, or finished one still within the retention window). - 400 - unreadable lastEventId / Last-Event-ID. - 409 - already being streamed. - 404 - no stream for this run, or it expired past liveRetentionMs; the body hints GET /runs/:runId/report, whose trace carries the stored events node.

Runs

GET /runs

List test runs (design mode, load tests and collection runs), newest first (start_time DESC, id DESC - the only order the UI uses; the id tiebreak makes the order total, so runs sharing a millisecond page in a fixed order and a page boundary inside such a tie neither repeats nor skips a row). Rows carry a compact summary rather than the full configSnapshot, so the polled history sidebar stays cheap as history grows.

Each row's summary is derived from that run's config_snapshot, and the derivation is cached per run id (issue #1150): a snapshot is written once, when the run is created, so a repeated poll re-serves what the previous one built instead of re-parsing one snapshot per row every tick - 50 at the default page size, up to 500 at the cap. The cache is bounded and holds nothing a request cannot rebuild, so it changes no answer - a run deleted between polls is gone from the list because the query no longer returns it, not because anything was invalidated. This route also logs at debug, not info: it is the one endpoint a visible client polls, and an info line here reached the console of every engine started at the default app verbosity, every five seconds.

Query parameters (every one optional; the answer is always the paginated envelope): - limit - page size (default 50, invalid/≤0 falls back to 50, capped at 500). - offset - rows to skip (default 0, negative floored to 0). - before - a keyset cursor, <startTime>:<id>: the page starts after that row (#2978). Pass the previous page's pagination.nextBefore unchanged; the value is split on its first :, so an id holding one is read whole. Where offset makes SQLite step over every row before the page, a cursor page seeks idx_runs_start_time to the row and reads about limit rows however deep it is, and it does not shift when a new run starts between two pages. Every filter below still applies, and total still counts the whole filter, not the rows after the cursor. A value that is not an integer, a : and a non-empty id is a 400 with code invalid_before; before beside a non-zero offset is a 400 with code before_with_offset (an offset of 0 is the same as none). offset stays for a client that jumps to a page number. - type - design | load | scenario (an unrecognised value is ignored, not an error). - status - a RunStatus string (pending | running | completed | failed | stopped; unrecognised ignored). - requestId - exact match on the run's linked request. - collectionId - exact match on a run's stored scenario.collectionId, read out of the snapshot as JSON. This is the deliberate opposite of q below: it matches the field, never the text around it, so a design run whose URL happens to contain the id does not come back. A collection run records the path, and so does a load run driven over a collection (#3544); a single-request design or load run never does, so it can never match. Add type=load to leave the collection's sequential runs out. An id nothing has run is an empty page, not an error. A collection's most recent run is ?collectionId=<id>&limit=1, since the list is already start_time DESC. - q - case-insensitive substring over the stored config_snapshot text (SQL LIKE). It searches the raw snapshot, so it may over-match JSON keys or structure - acceptable for a search box. - baseline - true lists only runs pinned as baselines, false only unpinned ones (any other value is ignored, like an unrecognised type). Leaving it out lists both, so omit it rather than passing false to mean "either". A request's current baseline is ?baseline=true&requestId=<id>&limit=1, and a collection's ?baseline=true&type=load&collectionId=<id>&limit=1, since the list is already start_time DESC - the lookups both the history view's vs-baseline strip and the MCP compare_runs tool make. - origin - app | mcp | other, exact match on the run's stored origin.kind (#1817; see POST /execute). Like an unrecognised type, any other value is ignored rather than refused, so a client on a newer vocabulary than the engine gets a wider list, never an error. A run recorded before the field existed matches other. There is no client filter: narrowing to one MCP client is done client-side over the rows this returns.

Every parameter composes with every other; each one left out is a wildcard.

summary carries exactly these seventeen snapshot keys: url, method, mode, duration, concurrency, iterations, targetRps, startConcurrency, rampUpDuration, comment, followRedirects, maxRedirects, requestName, dataFileName, dataFileHash, dataFileCastNumbers, and httpVersion. The first sixteen are each omitted when absent from the snapshot (a malformed snapshot yields an empty summary, never a 500); httpVersion alone is always present. iterations and targetRps (issue #2437) are what the run was sent, never a default the engine filled in: an iterations run's request count, and a paced run's rate. targetRps is the one rename - the POST /runs body may name the rate rps or targetRps, the row reports it as targetRps (the rate the engine paced at: rps, or targetRps when rps is absent, null or zero), and the report's configuration does the same. A field the run was not sent has no key here even though the engine ran its default (see POST /runs); a client that wants a default visible sends it. startConcurrency and rampUpDuration (issue #1935) are the ramp-up knobs, so only a ramp_up run has them, e.g. "startConcurrency": 2, "rampUpDuration": "10s" beside "concurrency": 50; they are the same two keys the report's configuration carries. requestName is the request's name as the client sent it when the run started - never re-read from the requests table, the same trust model url and method already have here - so a request renamed or deleted since does not change what a past run's row says it invoked, and a run whose client omitted the field (or one recorded before it existed) has no key at all rather than a fabricated name. It reaches config_snapshot the same way url/method do: whatever the client's POST /runs or POST /execute body carried; the renderer sends it from execIdentity (execute-mapping.ts), the same field POST /compose's requestId path already stamps for the script sandbox's pm.info.requestName. dataFileName and dataFileHash (issue #2051) name the file a single-request run's data rows came from, by display name and SHA-256 of its bytes (64 lowercase hex), never its path; a run sent without a file name has neither. dataFileCastNumbers (issue #2540) is true when that file's numbers were read as numbers, and absent otherwise. Every run since issue #1488 adds an eighteenth, acceptEncoding: true when the run negotiated a compressed response (negotiateCompression for a collection run, loadNegotiateCompression for a load run - see Default request headers), false when it did not, and omitted, not defaulted, for a run recorded before that issue - the baseline comparison (below) is the one reader that treats an absent key as false, matching what every such run actually sent. A raw POST /runs body of "httpVersion": null (erased before execution, so it behaves exactly like an absent key - see POST /runs) lands in the stored snapshot verbatim, and a run predating this field has no key at all; neither case recorded a protocol, so both normalize to the literal string "auto" rather than being omitted, which would misrepresent "nothing was recorded" as "we lost it". Do not read "auto" on an old run as the protocol it used: a load run stored before 0.11.0 hardcoded CURL_HTTP_VERSION_2TLS, and every run before it went out as HTTP/1.1 regardless, because nghttp2 was not linked. The full snapshot stays available on GET /runs/:runId. That route does not build a summary row at all: it returns the full configSnapshot, which already holds every key above. The same seventeen keys are on the row PUT /runs/:runId/baseline answers with, since both are built by one function; that row carries no resultSummary.

A collection run (type: "scenario") carries none of the single-request keys above (url through dataFileCastNumbers): its work is a sequence, so there is no single url, method or mode to report. Its row instead carries a nineteenth key, scenario, present on scenario runs only:

"scenario": {
  "collectionId": "col_1234567890",
  "iterations": 3,
  "recursive": true,
  "stepCount": 12,
  "dataFileName": "users.csv",
  "dataFileHash": "<sha256>",
  "dataFileCastNumbers": true
}

stepCount is the length of the snapshot's step manifest, not the manifest itself - a row that shipped every step's name, method and URL would undo the reason summary exists. The manifest stays on GET /runs/:runId. Each of the seven keys is omitted when the stored snapshot has no such key: dataFileName and dataFileHash (issue #2051) are the data file a run's scenario.data came from, so a run sent without one has neither, and dataFileCastNumbers (issue

2540) is present, as true, only when that file's numbers were read as numbers.

hasWarnings (issue #1527) is summary's twentieth key, true on a run whose stored summary.warnings array (issue #1503) is non-empty and omitted otherwise - a run still in progress, one whose terminal write failed, or one that finished with nothing to say. Unlike the other keys above, it is not read out of config_snapshot and not part of the cached compact summary: it is a completion-time fact, read fresh off the row on every poll, so a history surface that polled a still-running run sees the glyph appear on the next poll after it finishes, never stuck at the answer its first poll cached. The full warnings array itself stays on GET /runs/:runId's summary.

baseline is on every row, true only for a run pinned through PUT /runs/:runId/baseline. It is also on GET /runs/:runId, so a client that opened a run directly can draw the pin without listing.

origin is on every row and on GET /runs/:runId: {"kind", "client"}, who started the run as the starting client asserted it (#1817; the rules are on POST /execute). client is the MCP client's name for an mcp run and null otherwise, and on an mcp run whose client sent no name. A run recorded before the field existed reads {"kind": "other", "client": null}. Metadata, not identity: nothing authorises on it.

resultSummary is what a design run's row says about the exchange: statusCode and latencyMs, and nothing else. A design run is one request and one response, so its outcome fits on the row and a page of them costs one extra query. The two numbers rather than the whole result GET /runs/:runId attaches: it carries the exchange's trace, request and response bodies included, which is a per-row cost a list cannot take. A design run with no stored result - still running, or one whose result write failed - omits the key rather than reporting statusCode: 0, which is the wire's own way of saying the request never reached a server.

A load run's row carries its own resultSummary once the run is terminal (completed, failed or stopped; #2130), read from the whole-run summary the run stored, never from its result rows, which are many and unbounded:

Key Meaning
rps Achieved requests per second over the run, the report's summary.avgRps
p95Ms 95th-percentile latency in milliseconds, the report's latency.p95; omitted when the run timed no request (latency.count 0), not a stored 0
errorRate Percentage (0-100) of the run's status-code distribution that was errors: a status outside 2xx/3xx, or no response at all
verdict "passed" or "failed": the run's verdict against its declared thresholds, the same one the report's thresholdValidation.verdict prints
assertions The run's assertion block (#3537), the report's top-level assertions as it serves it, for both load run kinds: exact and sampled (each {passed, failed}), errored and teardownFailed. Beside errorRate, not folded into it
assertionsPassed, assertionsFailed assertions.exact plus assertions.sampled, for readers older than the block (#2820, #3458). A required extract.* miss is in assertionsFailed, the count a maxAssertionFailureRatePct check's assertionsExact reports. errored and teardownFailed are not in it
capacity A capacity run's headline (#2930), the same three keys of the report's capacity section: stopReason, and maxHealthyConcurrency / kneeConcurrency each only when the search found that level
drainCut {cancelled}, the requests a Stop cut from the run's own drain (#3538), the report's summary.drainCut. Present only on such a run, which a reader treats as not judged unless verdict is "failed"; verdict itself stays the budgets' own

Each key is omitted when the stored summary does not record it, never zeroed: errorRate is absent when the run recorded no status codes, and verdict is absent when the run declared no budgets - it was never judged, which is not the same claim as passing. The three assertion keys are absent together, for a run that made no assertion and errored nowhere. A run stored before #3537 reads as it did: a scenario load run's assertions is its scenario.assertions as exact alone, absent on a run stored before #2820, and a single-request run's is its assert.* and script.* rows of elements as exact (counted per execution, a required extract.* miss not in it) and its testValidation as sampled; neither has errored or teardownFailed. A scenario load run whose every deferred pm.test failed against 200s reads "resultSummary": { "rps": 172.0, "p95Ms": 12.4, "errorRate": 0, "assertions": { "exact": { "passed": 0, "failed": 0 }, "sampled": { "passed": 0, "failed": 91 }, "errored": 0, "teardownFailed": 0 }, "assertionsPassed": 0, "assertionsFailed": 91 }. capacity is absent on every run that was not a capacity search; inside it, maxHealthyConcurrency is absent when the very first level already breached the budget and kneeConcurrency when the search ended without the target giving out, the report's rules for the same keys. A capacity search that stopped on its latency budget reads "capacity": { "stopReason": "slo_exceeded", "maxHealthyConcurrency": 48, "kneeConcurrency": 64 }. A run whose drain a Stop cut with 15 requests unanswered reads "verdict": "passed", "drainCut": { "cancelled": 15 } when the answered requests met every budget. A pending or running load row, and a terminal one with no stored summary (the engine stopped before writing it), carries no resultSummary at all.

verdict is the verdict as stored, even for a stopped run, whose partial data the app shows as "Not judged" rather than passed or failed. errorRate uses the same failure definition as the report's summary.errorRate, over the stored status-code distribution, and is omitted when no distribution is stored.

A collection run's row (type: "scenario") carries one once it is terminal too (#2954), read from the scenario block of the stored summary under the same rule: nothing for a pending or running row, nothing for a terminal row whose summary is not stored yet. The five counts are the step outcomes, which are disjoint:

Key Meaning
passed, failed, skipped, errored, stopped How many steps ended each way, the report's scenario.passed / failed / skipped / errored / stopped. errored is a step whose script threw or whose exchange did not complete, kept apart from failed so a run whose steps only errored does not read clean; stopped is a step a Stop or a shutdown cut short (#3397), absent for a run stored before it
verdict As on a load row: the run's verdict against its declared thresholds, absent when it declared none, and as stored even for a stopped run

Each key is omitted when the stored summary does not record it, never zeroed, and a stored summary with no scenario object (a run stored before collection runs wrote one) adds no resultSummary. A clean four-step run reads "resultSummary": { "passed": 4, "failed": 0, "skipped": 0, "errored": 0, "stopped": 0 }: the zeros are recorded counts. The load figures (rps, p95Ms, errorRate) are not on this row; the report has them.

endTime is null while a row's status is pending or running and the stored value once it is completed, failed or stopped (#2953). The database seeds the column with startTime when a run is created, which would read as a run that took no time, and clears it to 0 once a load or collection run is running (#3340); a client takes "still going" from the null, and the same rule holds for GET /runs/:runId, the report's metadata.endTime and the PUT /runs/:runId/baseline row.

Response (envelope):

{
  "data": [
    {
      "id": "run_1234567890",
      "requestId": "req_1234567890",
      "environmentId": null,
      "type": "load",
      "status": "completed",
      "startTime": 1234567890,
      "endTime": 1234567891,
      "baseline": true,
      "origin": { "kind": "app", "client": null },
      "summary": {
        "url": "https://api.example.com/users",
        "method": "GET",
        "mode": "constant_rps",
        "duration": "60s",
        "concurrency": 100,
        "comment": "nightly",
        "followRedirects": true,
        "maxRedirects": 10,
        "httpVersion": "auto"
      },
      "resultSummary": { "rps": 98.7, "p95Ms": 41.3, "errorRate": 0.4, "verdict": "passed" }
    },
    {
      "id": "run_1234567891",
      "requestId": "req_1234567890",
      "environmentId": null,
      "type": "design",
      "status": "completed",
      "startTime": 1234567892,
      "endTime": 1234567893,
      "baseline": false,
      "origin": { "kind": "mcp", "client": "claude-code" },
      "summary": { "url": "https://api.example.com/users", "method": "GET", "httpVersion": "auto" },
      "resultSummary": { "statusCode": 200, "latencyMs": 34.2 }
    }
  ],
  "pagination": {
    "total": 812,
    "limit": 50,
    "offset": 0,
    "hasMore": true,
    "returned": 50,
    "nextBefore": "1234560001:run_1234560001"
  }
}

hasMore is read off the rows: the engine fetches one row past limit, so it holds on a cursor page, which has no offset to add to total. nextBefore is the cursor naming this page's last row whenever hasMore is true (an offset page included, so a client can switch to cursors after its first page) and null on the last page. A cursor page echoes offset: 0.

GET /runs/:runId

Get details for a specific run.

Response: The run object shown in GET /runs (id, requestId, environmentId, type, status, configSnapshot, startTime, endTime, baseline, origin). endTime is null until the run's status is completed, failed or stopped, as on the list row.

While the engine holds the run active, the object also carries phase, where its worker is: setup, sending, draining, summarising or settled (issue #3568), the same value as the live frame's phase. draining means the run's own end has come and it is waiting out the requests still in flight, which a Stop cuts short without changing the outcome. The phase is never stored, so a run no longer active (finished, or the engine restarted) has no phase key at all; read status there.

For a design run that has at least one stored result, the response also carries a result object with that run's single exchange - the only other place it appears is GET /runs/:runId/report, whose results array and metadata.configuration are load-test concepts and are absent for a design run. result is design-only by construction: it serves the first stored row on the assumption that there is exactly one, and a scenario run has one per step - its steps are read from the report's results array instead.

{
  "id": "run_1234567890",
  "requestId": "req_1234567890",
  "environmentId": null,
  "type": "design",
  "status": "completed",
  "configSnapshot": { "...": "the run payload as composed, credentials withheld" },
  "startTime": 1234567890,
  "endTime": 1234567891,
  "baseline": false,
  "origin": { "kind": "app", "client": null },
  "result": {
    "timestamp": 1234567891,
    "statusCode": 200,
    "statusText": "OK",
    "latencyMs": 42.1,
    "error": "optional, only when the request failed",
    "trace": { "request": { "...": "..." }, "response": { "...": "..." } }
  }
}

trace.error_type / trace.error_message are present when the exchange failed, and trace.response when it did not or when the failure came after a header block arrived (issue #3423): an undecodable body, a timeout mid-body, too many redirects. Such a failure is still reported at statusCode 0, and its trace keeps the headers, headerLines, httpVersion and body the live answer showed beside the error, so a client must not read the presence of response as success. A failure that received no header block (a refused connection, an unresolved host, a failed handshake) has no trace.response. A proxy's answer counts as a header block: a proxy's refusal, or headers on the tunnel it opened, are kept as the live answer shows them.

Every trace.response carries bodyBytes (issue #3423), the body's length in bytes, which a client cannot recount from body because a JSON string's length is not its UTF-8 size. It is the length the engine held, which for a bodyCapped response is the prefix the read cap kept; a streaming run's is the body bytes the server delivered (issue #3238), which its body can be shorter than (an event stream stores none, any other reply at most maxDesignResponseBodyBytes; see POST /execute). A row stored before #3423 carries it only on a cut or streamed response.

If the engine truncated a body for storage (over maxTraceBodyBytes), the affected trace.request and/or trace.response object carries "bodyTruncated": true, and trace.request gains "bodyBytes": <original length>; a storage cut keeps the response's bodyBytes rather than restating it. Absent when the body fit. A text body then holds the first maxTraceBodyBytes bytes of the original, less an incomplete last UTF-8 character the cut would leave, so it can be up to three bytes shorter and never ends in a U+FFFD the server did not send. Clients surface this as a "body truncated for storage" notice and re-send to fetch the whole body. A trace.response with "bodyEncoding": "base64" (see POST /execute) is measured in decoded bytes: its body is the base64 of the first maxTraceBodyBytes bytes rounded down to a multiple of three, so the slice still decodes, and bodyBytes counts decoded bytes.

configSnapshot.body is capped the same way, independently of the trace (issue #1486): content over maxTraceBodyBytes is cut to that length and the body object gains the same bodyTruncated / bodyBytes pair. A run can be truncated on one side and not the other, since each is written by its own call into sanitize_config_snapshot.

configSnapshot withholds the composed request's credentials (issue #1803): auth is reduced to {"mode": ...}, a header named in the shared secret set (Authorization, Cookie, X-Api-Key, ...) or by the request's apikey auth keeps its name with the value "<redacted>", and every value of a variable marked secret in the payload's scopes (globals, environmentId, the collection chain of requestId's request, else of the composed collectionId, issue

3461; for a scenario run, the chain of the run

collection and of every folder a step sits in, so a recursive run masks a secret held on a sub-folder, issue #3270) is written as <redacted> wherever it landed in url, params, headers or body, in its raw, percent-encoded (strictly, and as composition writes a query value, a path, a fragment and user info, which leave / @ & : + ' raw where the strict form escapes them), JSON-escaped and XML-escaped forms (a JSON body holds pa"ss as pa\"ss). A value under four characters is not masked. result.trace is the record of what was sent and keeps it all. A run stored before this change returns its snapshot as it was written.

A load or collection run's configSnapshot also carries defaultHeaders (issue #1488), the run's resolved decision at start about what the engine would add to a request nobody wrote it into - never re-read for the send itself (see Default request headers), kept only so a later run's report can say whether the two measured under the same conditions:

"defaultHeaders": { "userAgent": "Vayu/0.26.0", "requestId": false, "acceptEncoding": true, "expectContinue": false }

expectContinue (issue #2516) is whether sendExpectContinue let libcurl add Expect: 100-continue to a body over 1 MiB, which makes it wait up to a second for the server's answer before sending. A run recorded before it has no such key, and a comparison reads that as false, which is what the run sent.

Absent on a design run (it carries no throughput to compare) and on any run recorded before this issue.

POST /runs/:runId/stop

Stop a running load test or collection run. The engine signals the run, waits up to 5s for its worker to settle, and answers with a summary of what the run actually did. A collection run's summary is optional; see Stopping a collection run below.

What a Stop means depends on the phase it lands in (issue #3341). A load run moves through setup, sending, draining, summarising and settled, and the first Stop is latched with the phase it arrived in. The phase is never stored; while the run is active it is published as phase on every live metrics frame and on GET /runs/:runId (issue #3568).

  • A Stop before the strategy returns (setup or sending) decides the outcome, and the run ends stopped. The queued backlog is thrown away rather than sent, and transfers already in flight are cancelled (removed from curl and completed as a CANCELLED "Request cancelled"), so the target stops receiving traffic immediately and the stop's latency does not belong to the upstream. A cancelled request was submitted, so it is counted, but not as an error (issue #2136): it is summary.cancelled, outside totalRequests, errors and errorRate (see What counts as an error). Every request the run sent is in exactly one of totalRequests and cancelled.
  • A Stop after the strategy returned on its own (draining) decides nothing about the run's end. A run that ends naturally lets its in-flight requests finish, but only up to its effective timeout (its own timeout, else the defaultTimeout setting) plus a 2s grace, except a streaming run, whose bound is its maxStreamDurationMs plus grace (the 5s stream backstop plus the same 2s, issue #2834). A Stop in that drain cuts it short at once: the transfers still in flight are cancelled and counted as cancelled, not as errors, because the operator asked for it. The run keeps its own end - completed, or failed when thresholds.failRun judges it so - and its sending window is what it would have been without the Stop, since the Stop ended no sending. When the Stop cancelled anything, the summary records it as drainCut: {cancelled} (issue #3538), and the run reads not judged ("15 requests were still unanswered when the drain was stopped") unless a budget it already missed fails it: the requests the Stop cut are the slowest the run sent, and judging what is left would pass a run on its fastest answers. A Stop in either phase also ends the deferred test replay and any script still running (#3460): the running script stops at its next interrupt poll and no further sample is replayed, so testValidation.samplesTested counts the samples the replay reached and the worker settles within the 5s below instead of after each remaining sample's scriptTimeout. script.teardown still runs after a Stop latched before it (see scripting.md, "A Stop ends the script itself").
  • A drain that hits its deadline with no Stop cancels what is still outstanding the same way, and because nobody asked for that one to stop, it is an error with no response, not a cancellation. Without that bound an upstream that never answers would hold the run in running indefinitely.

POST /shutdown follows the same rules: it also cuts a natural-end drain short and leaves the run completed.

Response (active run). status is the stored status once the worker has written a terminal one; before that it is stopped when the Stop decided the outcome, and running when it landed after the run's own end (the draining phase), where the worker has not yet written the completed or failed it will end with. running there is accurate rather than a failure to stop: the drain is already cancelled, and the terminal status follows once the worker writes it. When the worker has not settled within the 5s, the answer also carries message: "Stop signalled; the run had not settled within the 5s grace period; read the report" (#3342); a run that settled carries none.

{
  "status": "stopped",
  "runId": "run_1234567890",
  "summary": {
    "totalRequests": 1500,
    "errors": 5,
    "httpErrors": 3,
    "noResponse": 2,
    "cancelled": 12,
    "errorRate": 0.33,
    "avgLatencyMs": 38.9
  }
}

errors and errorRate are the one error definition, the same figures the live tick and the report show; httpErrors and noResponse split errors. cancelled is the requests this stop cancelled, counted in none of them.

avgLatencyMs is the same average the final report and the live ticks show: the latency sum over the latency population, divided by the number of requests in it. It is not divided by totalRequests (which counts requests that carry no latency, so it would report a lower figure here than everywhere else for the same run) nor by the success count (a timeout's duration is in the sum).

A run that is already finished answers {"status": "<status>", "runId": ..., "message": "Run already <status>"}; one that is not in memory answers {"status": "stopped", "runId": ..., "message": "Run was not active"}. That is a buffered design send, or a run still pending before its worker started (#3340): the row moves to stopped from pending or running only, so the stop stands. A worker that had not started yet finds the row stopped and ends without sending; one that started in the meantime is signalled too. A buffered send's exchange still completes and its result is stored, under a row that stays stopped; only a hang-up of the POST /execute call cancels it (see above). A run whose row is gone by the time the move is tried answers 404.

A streaming design run (POST /execute with "stream": true) is stopped here too: the endpoint asks its consumer worker to end the transfer, waits up to the same 5s, and answers {"runId": ..., "status": ..., "message": ..., "totalEvents": N}. The worker owns the terminal write, so the run reaches its status with its trace and its true event count together, and status is the one it stored (#3342):

status message When
stopped Stream stopped The transfer read the stop; the stream's complete event carries "reason": "stopped"
completed The stream had already ended The server had closed the stream, or a cap had ended it, before the transfer read the stop (its post-request script was still running)
failed The stream failed before the stop took effect The transfer had already failed
running Stop signalled; the run had not settled within the 5s grace period; read the report The worker had not stored a result within the 5s, usually a slow post-request script; the stop still stands

A stream that had already terminated keeps the reason it recorded rather than being rewritten as a user stop.

Stopping a collection run

A sequential collection run (a scenario run, issue #2822) feeds no load collector, so its answer is read from the summary its worker stores once it has stopped, the same one the report reads:

{
  "status": "stopped",
  "runId": "run_1234567890",
  "summary": {
    "totalRequests": 31,
    "errors": 2,
    "httpErrors": 2,
    "noResponse": 0,
    "errorRate": 6.45,
    "avgLatencyMs": 12.5,
    "stepsExecuted": 40
  }
}

totalRequests is requests sent and stepsExecuted is steps, as in the report: a step the plan skipped is a step and not a request. errors, httpErrors, noResponse and errorRate come from the stored status-code distribution over those requests, and avgLatencyMs is the stored latency block's avg (0 when no step sent). There is no cancelled: a collection run keeps no count of what its stop cancelled. status is the run's stored status. A sequential run has no drain, so a Stop always lands while it is sending and decides the outcome: the run ends stopped.

The summary is absent when the worker has not stored one within the 5s, or could not store it. The answer is then {"status": "<stored status>", "runId": ..., "message": "Stop signalled; read the report"}, usually with status running; when the 5s ran out, message says so, as for a load run above. The stop still stands: read the run's report once it reports a terminal status. A scenario load run is a load run and answers from its collector as above.

GET /runs/:runId/report

Get the final report for a completed run. The response is a nested object; conditional sections appear only when relevant (e.g. rateControl only for constant_rps, testValidation only when a test script ran, thresholdValidation only when the run declared budgets, assertions only when a load run asserted or an element errored, capacity only for a capacity run, auth only when the run's OAuth 2.0 credential could be refreshed mid-run, coverage only for a run measured against a bound spec, schemaValidation only for a run that checked at least one response against one).

The whole-run aggregates come from the run's stored summary (written once when the run reaches a terminal status - see db-schema.md), combined with the sampled results rows for the timing breakdown and the results[] array (at most 100 rows, failures first - see "results[] is not a uniform sample" below). A run with no summary has either not reached a terminal status yet (metadata.status is pending or running) or failed without writing one; its report is built without it rather than erroring. The response shape is the same either way. A load run the engine died under is marked failed at the next start and given the totals of its last persisted tick instead (see "A run the engine died under" below).

A report read while the run is pending or running is therefore partial: metadata.status says the run is still in flight, and thresholdValidation is absent even when the run declared budgets, because the verdict is computed from the summary written at the end, and metadata.endTime is null (#2953), not the seed or the 0 the database holds for it. Read metadata.status before treating a report as final.

A design or scenario run stores its results rows just before its status flips, and a client fetching once in that gap needs them with their traces, so its partial report is built from the rows stored so far. A partial report of a load run reads no results row at all (issue

2659): it is the one a client re-reads on a timer, and a load run writes its rows only as it

finishes, in chunks (see results), so a report built from them is all zeros while the run sends and a growing prefix of the flush after. Its figures come from the run's in-memory counters instead, the ones the live stream reads: summary.totalRequests, successfulRequests, failedRequests with its httpErrorRequests / noResponseRequests split, cancelledRequests, errorRate, statusCodes and errors.byStatusCode, droppedRequests, skippedRequests, stalledMs, peakConcurrency, avgQueueWaitMs, bytesSent, bytesReceived, httpVersionDowngraded, connectionReplays, and avgRps, throughput, sendRate and avgInFlight over the time from startTime to the read, which testDuration and totalDurationSeconds report (#3340). latency is absent, because the percentiles come from histograms the run is still writing and arrive with the summary. results[] is empty and resultsStored is 0 (resultsCap is unchanged), errors.types is {}, errors.withDetails is 0, and timingBreakdown and slowRequests are absent. In the moment between the summary write and the status flip the aggregates are the summary's, as for a finished run, still with no row read. A run whose row says running but which the engine no longer holds answers the same shape with every count at zero.

A run the engine died under (issue #2895) is marked failed when the next engine starts (reconcile_orphaned_runs, see db-schema.md). A load run that persisted at least one metric tick is given a summary built from its last one, and its report carries summary.partial: true. The figures are the run's up to that tick: totalRequests, the success/failure split, errorRate, statusCodes and errors.byStatusCode (all from the tick's cumulative status distribution), cancelledRequests, testDuration (the tick's elapsed seconds), avgRps (completions over that time, not the tick's trailing rate), sendRate, throughput, droppedRequests, skippedRequests, stalledMs, bytesSent and bytesReceived. What the tick does not measure for the whole run is absent rather than 0: avgInFlight, connectionReplays, sendingDurationSeconds, completedWhileSending, peakConcurrency and avgQueueWaitMs (issue #2963), while setupOverhead and httpVersionDowngraded are 0, sampling is absent, and the report has no latency block (issue #2938): the percentiles come from the stored results rows, of which such a run has none, so omitting the block says "not recorded" where a block of zeros would read as steps that answered instantly. A failed load run with no summary at all, because it wrote no tick or failed on a path that writes none, carries summary.summaryMissing: true, and its counts are not whole-run totals (those of whatever sampled results rows were stored, often 0) and whose report has no latency block either, even where sampled rows exist, and no peakConcurrency or avgQueueWaitMs. Both keys are absent, never false, on every other report. A client that shows a figure from a report carrying either one says the figure was not recorded rather than showing it as measured.

metadata.scenario appears on every collection run, finished or not (issue

3569), and on no other: collectionId, iterations, recursive, the data

file's dataFileName / dataFileHash / dataFileCastNumbers and stepCount, each omitted when the snapshot lacks it. It is the run's snapshot identity, echoed as the list row's scenario is, and not the top-level scenario breakdown, which is built from the stored summary and is absent for a run the engine did not finish. A client that names a collection run reads it here; the manifest's per-step steps array is not repeated, only its count.

metadata.openapi appears only for a run whose collection was bound to a spec when the run was planned (issue #637). It is echoed from the run's snapshot rather than re-read from the collection: a report has to say what the run was measured against, and the binding is free to have moved since. An unbound run carries no openapi key at all - absent rather than an empty object, so "not measured against a spec" has one spelling.

The binding is resolved by walking from the run's collection up to the root and taking the nearest bound ancestor, the same walk a single request's design-mode validation uses (issue #716). An import binds the root and files every request under tag sub-collections, so running one tag folder is measured against the document its root binds. When the binding came from an ancestor rather than from the collection the run named, the node carries "inherited": true - absent otherwise, like every other finding here. The run still enumerates only its own subtree, so the coverage below is partial by construction: most of the contract's operations are honestly uncovered, and that flag is what lets a reader tell scoped-run truth from a collection that has stopped calling its API.

coverage says which of that spec's operations the run exercised and which of their declared responses it saw (issue #629). It is present only for a scenario run - design or load - of a collection bound to a document that carries an operation index, and absent, never zeros, for every other run: an unbound collection, a single-request run, and a document stored before the index existed all report no block rather than a contract covered zero of.

Field Meaning
operationsTotal / operationsCovered Declared operations, and how many got at least one request
declaredResponsesTotal / declaredResponsesHit / declaredResponseCoveragePct Declared status patterns (an x- extension key under responses is not one), and how many the run produced
undeclaredStatusesSeen Distinct (operation, status) pairs the document declares nothing for
operations[] Per operation: sent, statusesSeen, declaredHit, declaredMissed, undeclaredSeen, and transportErrors / otherStatusResponses / statusesTruncated when non-zero
operations[].statusesTruncated Distinct statuses the operation answered with that appear in neither list - the two are capped at 50 each and undeclaredSeen repeats codes from statusesSeen, so this is not the entries the two dropped between them
transportErrors / undeclaredOperationRequests Whole-run findings, present only when they happened

Rows come back uncovered first - an operation nothing exercised is the finding - and in document order within each group, so two runs of one contract print the same way. A status hits the most specific declared pattern that covers it (exact, then a 2XX range, then default), so an operation declaring both 200 and 2XX that only answered 200 reports 2XX as missed: those are two distinct promises. A transport error counts as a request sent and as no response seen; status 0 is never listed as a status the server sent.

Every number here is exact, not sampled. The engine counts each send and each response as it happens, through a tally that is not the bounded results[] store - so a load run whose rows were thinned to a reservoir still reports every operation it touched. Coverage is computed against the document metadata.openapi names, at the moment the plan resolved, and stored with the run; a binding that has since synced to a newer spec cannot rewrite it.

operationsCovered, operationsTotal and declaredResponseCoveragePct are deliberately plain numbers, shaped like thresholdValidation's counts, so a headless CI gate can threshold on them without the block being reshaped. Nothing thresholds on them today.

schemaValidation says whether the responses a run checked matched the schemas that same document declares (issues #682, #681). It sits beside coverage and is computed against the same document, but on different evidence, and the difference is the block's most important field: coverage counts every send, while this walks whatever the run's mode gave it - the bounded reservoir of responses a load run stored, or every step a collection run executed.

Field Meaning
sampled Responses this pass walked - the denominator for everything else
checked Of those, the ones a declared schema could speak about
valid / failed The partition of checked. valid + failed == checked, always
unevaluated Checked responses whose schema carried a keyword the draft-07 validator could not evaluate (a nested propertyNames included, #2729)
uncheckedReasons Reason code -> count, accounting for every one of sampled - checked
unevaluatedKeywords[] {keyword, count}, so what went unread is named and not only counted
failures[] Bounded examples, at most 10: {step?, status, path, message}. They cover distinct failing steps (the first failure of each, in the order the steps first failed) before repeating one, so a late failing step is not hidden by an early one (#3038)
failuresTotal Every failure found, the cap included - so "3 shown of 90" stays readable
exact true when sampled is the whole population rather than a reservoir - written by a collection run, absent for a load run
failOnSchemaError Whether a schema failure was allowed to fail its step. Collection runs only

The reason codes are the ones POST /execute's validation node uses, unchanged.

Under load these numbers are sampled, and nothing here pretends otherwise. Validation is deferred to run end because a load run refills concurrency on every completion, so a schema walk on that path would cost throughput for the whole run - and would do so invisibly. failed: 0 therefore means "no sampled response failed". sampled is written so a reader always has the denominator; the app renders it beside the tallies for the same reason.

A collection run writes the same block with exact: true, because it sends one request at a time and checks every step - there is no hot path to keep off, so sampled there is the run. The flag exists so a reader is never left to infer the denominator from the run's mode: the same five numbers are a wider claim in one than the other, and only the block knows which. A report written before the flag existed was sampled, which is why absent reads as sampled.

A step's responses are kept when a deferred pass will read them - it carries a script, or it is bound to an operation and the document carries schemas - and the run's sample budget is split evenly across those steps. What was displaced is reported as sampling.response_samples_dropped.

Absent, never zeros, for every run that checked nothing: an unbound collection, a single-request run, a document carrying no response schemas, and a run whose reservoirs held nothing. A run whose responses were never checked did not pass a contract.

Per-step verdicts in a collection run

Each step of a collection run carries its own verdict on its stored trace as a validation node - the same object and the same shape POST /execute returns - and the live step SSE frame carries it too, so a run being watched and the same run read back cannot disagree (issue #681). A step that sent nothing carries no validation at all: there was no response to judge.

failOnSchemaError is a top-level boolean on POST /runs, default false, type-checked before the run row is created. It is read by a collection run (a scenario without a load mode) alone: true on a single-request run or a scenario load run is a 400 with code invalid_run_config naming the flag, because those validate sampled responses once the run drains and never fail a step on them (false and null stay accepted). Left off, a schema failure does not change any step's outcome: it is its own verdict channel, and a response the document does not describe is not a failed assertion. Set, a step that passed everything else and whose response did not match is classified failed, with the first problem in its results.error; a step already failing keeps the error that named it. A step failed only by this gate moves scenario.failed (and the run list's resultSummary.failed), the step's trace outcome and results.error, and schemaValidation; it does not move summary.failedRequests, httpErrorRequests, successfulRequests, errorRate, statusCodes (its 200 stays a 200), the maxErrorRatePct input or summary.assertions. Those are HTTP-only, the same rule a failed assertion follows (see assertions under Scenario load runs).

Response:

{
  "metadata": {
    "runId": "run_1234567890",
    "runType": "load",
    "status": "completed",
    "startTime": 1234567890,
    "endTime": 1234567950,
    "requestUrl": "https://api.example.com/users",
    "requestMethod": "GET",
    "configuration": {
      "mode": "constant_rps",
      "duration": "60s",
      "concurrency": 100,
      "targetRps": 100,
      "followRedirects": true,
      "maxRedirects": 10,
      "httpVersion": "auto",
      "dataRowCount": 2,
      "dataFileName": "users.csv",
      "dataFileHash": "<sha256>",
      "dataFileCastNumbers": true,
      "carriedBudgets": ["latencyP99Ms"],
      "acceptEncoding": true,
      "expectContinue": false
    },
    "openapi": {
      "specId": "spec_3f2b1c9a-...",
      "specHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
    }
  },
  "summary": {
    "totalRequests": 6000,
    "successfulRequests": 5970,
    "failedRequests": 30,
    "httpErrorRequests": 20,
    "noResponseRequests": 10,
    "cancelledRequests": 0,
    "errorRate": 0.5,
    "totalDurationSeconds": 60.4,
    "avgRps": 99.34,
    "testDuration": 60.4,
    "sendRate": 100.0,
    "throughput": 99.34,
    "setupOverhead": 0.12,
    "cleanupOverhead": 0.03,
    "peakConcurrency": 100,
    "droppedRequests": 0,
    "skippedRequests": 0,
    "stalledMs": 0,
    "avgQueueWaitMs": 0.4,
    "avgInFlight": 4.2,
    "bytesSent": 192000,
    "bytesReceived": 7680000,
    "throughputBytesPerSec": 127152.32,
    "httpVersionDowngraded": 0,
    "connectionReplays": 0,
    "sendingDurationSeconds": 60.0,
    "completedWhileSending": 5990
  },
  "latency": {
    "min": 12.3, "max": 1250.5, "avg": 42.1, "median": 38.5,
    "p50": 38.5, "p75": 45.2, "p90": 78.3, "p95": 95.1, "p99": 156.7, "p999": 450.2
  },
  "statusCodes": [[0, 10], [200, 5970], [500, 20]],
  "rateControl": { "targetRps": 100, "actualRps": 100.0, "achievement": 100.0,
                   "requestsSent": 6000, "requestsExpected": 6000 },
  "errors": {
    "total": 30,
    "withDetails": 10,
    "types": { "timeout": 6, "connection_failed": 4 },
    "byStatusCode": [[0, 10], [500, 20]]
  },
  "timingBreakdown": {
    "avgDnsMs": 0.15, "avgConnectMs": 0.42, "avgTlsMs": 0.31,
    "avgFirstByteMs": 3.1, "avgDownloadMs": 0.14,
    "phases": {
      "dns":       { "p50": 0.1, "p95": 0.2, "p99": 1.4,  "max": 12.0, "count": 6000, "mean": 0.15 },
      "connect":   { "p50": 0.3, "p95": 0.9, "p99": 8.2,  "max": 40.1, "count": 6000, "mean": 0.42 },
      "tls":       { "p50": 0.0, "p95": 0.0, "p99": 22.0, "max": 61.0, "count": 6000, "mean": 0.31 },
      "firstByte": { "p50": 2.9, "p95": 4.0, "p99": 6.1,  "max": 30.0, "count": 6000, "mean": 3.1 },
      "download":  { "p50": 0.1, "p95": 0.3, "p99": 0.9,  "max": 4.2,  "count": 6000, "mean": 0.14 }
    }
  },
  "slowRequests": { "count": 12, "thresholdMs": 1000, "tracesStored": 12, "percentage": 0.2 },
  "warnings": [
    { "code": "unresolved_tokens",
      "message": "12 requests sent with unresolved variables: token",
      "count": 12, "names": ["token"] },
    { "code": "pre_request_script_skipped",
      "message": "1 step carries a pre-request script that does not run under load",
      "steps": 1 },
    { "code": "cookies_dropped",
      "message": "4 Set-Cookie headers were dropped across the run by libcurl's cookie engine (a line over 5000 bytes, a name and value over 4096 bytes, or more than 50 in one response), so the virtual users that received them sent their later steps without those cookies.",
      "count": 4 }
  ],
  "stream": { "...": "streaming runs only - see below" },
  "sampling": {
    "errorsDropped": 0, "successTracesDropped": 29000,
    "slowTracesDropped": 0, "responseSamplesDropped": 998000,
    "exemplarsDropped": 0, "sampleBodiesDropped": 12,
    "responseBodiesCaptured": 23, "responseSampleBudgetSpent": false
  },
  "monitor": {
    "samples": 58, "failures": 2, "noMatchScrapes": 0, "lastError": "timed out",
    "series": {
      "node_cpu_seconds_total": { "min": 1.2, "max": 3.9, "avg": 2.6, "count": 58 }
    }
  },
  "testValidation": {
    "samplesTested": 500, "testsPassed": 498, "testsFailed": 2, "successRate": 99.6,
    "console": [ { "level": "warn", "text": "cache miss for /users", "count": 412 } ],
    "consoleDropped": 3
  },
  "thresholdValidation": {
    "checks": [
      { "metric": "latencyP99Ms", "limit": 50, "actual": 47.2, "passed": true, "evaluated": true }
    ],
    "passed": 1, "failed": 0, "verdict": "passed"
  },
  "assertions": {
    "exact": { "passed": 0, "failed": 0 }, "sampled": { "passed": 498, "failed": 2 },
    "errored": 0, "teardownFailed": 0
  },
  "customMetrics": {
    "ttfb2": { "type": "trend", "count": 42, "p50": 10.0, "p95": 40.0, "p99": 47.0, "max": 50.0 },
    "bytesOut": { "type": "counter", "count": 4, "value": 4096.0 },
    "cacheHit": { "type": "rate", "count": 10, "value": 30.0 }
  },
  "auth": { "refreshes": [ { "atSeconds": 3620.4 } ], "refreshFailures": 0 },
  "coverage": {
    "operationsTotal": 18, "operationsCovered": 14,
    "declaredResponsesTotal": 41, "declaredResponsesHit": 29,
    "declaredResponseCoveragePct": 70.7, "undeclaredStatusesSeen": 1,
    "operations": [
      { "operationId": "deletePet", "method": "DELETE", "path": "/pets/{petId}",
        "sent": 0, "statusesSeen": [], "declaredHit": [], "declaredMissed": ["204"],
        "undeclaredSeen": [] }
    ]
  },
  "schemaValidation": {
    "sampled": 40, "checked": 36, "valid": 30, "failed": 6, "unevaluated": 0,
    "uncheckedReasons": { "body_not_json": 4 },
    "failures": [ { "step": "get pet", "status": 200, "path": "/id", "message": "Value type not permitted by 'type' constraint." } ],
    "failuresTotal": 6
  },
  "lifecycle": {
    "setup": [ { "id": "el_setup1", "kind": "script.setup", "outcome": "ok" } ],
    "teardown": [ { "id": "el_teardown1", "kind": "script.teardown", "outcome": "error", "message": "Error: boom",
                    "messages": [ { "kind": "error", "text": "Error: boom" } ],
                    "console": [ { "level": "log", "text": "tearing down" } ] } ]
  },
  "elements": [
    { "id": "el_1", "kind": "assert.status", "name": "Is 200",
      "passed": 9, "failed": 1, "missing": 0, "error": 0, "skipped": 0, "deferred": 0 },
    { "id": "el_2", "kind": "extract.json", "required": true,
      "passed": 8, "failed": 0, "missing": 2, "error": 0, "skipped": 0, "deferred": 0 },
    { "id": "el_3", "kind": "script.post",
      "passed": 0, "failed": 0, "missing": 0, "error": 0, "skipped": 0, "deferred": 10 }
  ],
  "results": [ { "id": 41, "...": "request/response outcomes, failures first" } ],
  "resultsStored": 4812,
  "resultsCap": 100
}

Two clocks, and which rate reads which (issue #2392). testDuration (and totalDurationSeconds, the same figure) is the wall time from load start - the instant of the first submission - to the last request settling, so it includes the end-of-run drain, in which requests still in flight at the deadline are let answer (up to the run's effective timeout, its timeout or else the defaultTimeout setting, plus a grace, except a streaming run, whose bound is its maxStreamDurationMs plus grace). avgRps and throughput are completed requests over that wall time: they describe what the target served, and a run whose requests outlive its deadline reads below its target there by design. sendRate and rateControl describe what the generator sent, and divide by sendingDurationSeconds: load start to the moment the run stopped submitting, before the drain. completedWhileSending (issue #2882) is the requests completed by that same moment, so it is never above totalRequests, and completedWhileSending / sendingDurationSeconds is the response rate while sending, the figure to hold beside sendRate; throughput counts the drain in both its completions and its seconds. A run whose few slow requests time out long after the sending ends reads a throughput far below that rate; a run whose every request takes the same time reads a little above it, because the drain answers the requests the sending window left in flight. rateControl.achievement is requestsSent / requestsExpected x 100, the pacer's own count with requestsExpected = targetRps x duration, and rateControl.actualRps is requestsSent / sendingDurationSeconds. rateControl.requestsSent and requestsExpected are the run totals behind the live metrics frame's fields of the same name. A shortfall there is not only a slow generator: a request dropped at the maxInFlight cap (droppedRequests) was never sent, a request a stalled pacer skipped (summary.skippedRequests, with the schedule time they cover in summary.stalledMs) was never sent either, and a Stop ends the sending early, so a stopped run's achievement is the share of its plan it reached. The app's Rate fidelity card instead divides by what the target owed up to now (targetRps times the time spent sending, capped at the duration; once the sending window is over, the engine's whole count floor(targetRps x duration), so 33.3 RPS over 3 s ending at 99 sent reads 100), so on a Stop it reads the pace. It does so live, and for a stopped run in History from requestsSent, sendingDurationSeconds and the configured duration (issue #2805), while the stored rateControl.achievement stays the plan share and the card states it beside the figure ("stopped at 50% of the planned 60s"). A stopped report without the counts keeps its stored value.

Skips lower the achievement and are shown beside it (issue #2911). summary.skippedRequests is the requests a constant_rps pacer owed beyond its 100 ms catch-up window and chose not to send after a stall of the load generator itself, and summary.stalledMs the schedule time they cover (skippedRequests ÷ targetRps, in ms). They are the run's totals, stored as skipped_requests / stalled_ms in the summary and on every metric tick, and read as 0 from a summary stored before them (the run skipped nothing, it had no cap to skip under). rateControl.achievement is not adjusted for them: a skipped request was owed and never sent, so requestsSent / requestsExpected is the honest share of the plan, and the two counters are what tell a stall from a slow target. sent + skipped + dropped is requestsExpected for a run that reaches its deadline. The run export carries both in report.summary (optional in its schema, absent from a document written before them); its Markdown and HTML renderings print them as one Skipped requests row of the results table when skippedRequests is above 0, apart from maxInFlight drops, which they do not print (droppedRequests has no row).

An iterations run, single-request or scenario, is the one exception: its loop returns on its last submission with the batch before it still in flight, so a window measured to that point would overstate the rate it sustained. Its sendingDurationSeconds is its whole testDuration and its completedWhileSending its totalRequests, unless a Stop ended it, in which case the measured window and the count at its end stand. A run stored before issue #2392 has neither sendingDurationSeconds nor the two counts: its sendRate divided by testDuration, and its rateControl keeps the formula it was stored with, actualRps the completed rate and achievement = actualRps / targetRps x 100. A run stored before issue #2882 has no completedWhileSending, never a 0.

statusCodes and errors.byStatusCode are [[code, count], ...] pairs on the wire, in ascending code order, not objects: each is a std::map<int, size_t>, which nlohmann serialises that way. The app folds the pairs (run-report-transformer.ts) and the MCP comparison reads either form (statusCodeEntries). The stored summary, a live metrics frame and the document POST /export/run-report writes all spell the distribution as an object.

errors is the run's failures three ways. total is the one error definition and byStatusCode its distribution, code 0 being the requests that got no response. types counts those no-response requests by what went wrong (timeout, connection_failed, dns_failed, ...), so its counts sum to byStatusCode's code 0. For a load run, a collection load run included, they are counted as the run happened and stored in its summary (issue #2400), exact past the error store's cap. withDetails is how many error records the run kept, at most maxStoredErrors, so past the cap it is smaller than types adds up to. Load runs stored before issue #2400, and design-mode collection runs, have no stored per-type counts: their types counts the kept records, and past the cap covers only the first maxStoredErrors errors.

slowRequests is present when the run set a slow_threshold_ms above 0. count is every successful completion at or past thresholdMs, counted as it happened (issue #2399), and percentage is count over summary.totalRequests - a denominator that includes failed requests, although only a success is ever marked slow. tracesStored is how many of them the run kept a trace for: the slow store is a reservoir capped at max_slow_results, so past the cap count - tracesStored is what the reservoir dropped (sampling.slowTracesDropped). count: 0 is a run that measured and found nothing slow. A run stored before issue #2399 has no exact count in its summary, so its count is the stored traces again (equal to tracesStored, and never past the cap), and the section is absent when none of its traces was slow.

elements (issues #1594, #1641) is a single-request run's own requestElements outcomes - extract.* / assert.* / timer.* / script.*, tallied across every submission in the row shape a scenario step's elements uses ({id, kind, name?, origin?, required?, passed, failed, missing, error, skipped, deferred}, one count per outcome word,

3051; see Scenario load runs), and an inline script.* row's

messages?, messagesDropped?, console? and consoleDropped?: what it threw, each failing test and its console lines, a bounded distinct sample (#3127, described there). There is one row per element, in requestElements order, so a collection's element and the request's own that share an id (#3101) are two rows, each with its own counts and origin. deferred (issue #2144) counts the submissions an un-inlined script.post was left to the completion replay on: its verdicts are the report's testValidation, drawn from the sampled responses, so it is not a script that never ran. skipped is every other skip: a disabled element, an un-inlined script.pre, an optional extract.json over a body it could not read, or an inline script.* the run's Stop cut short, its pm.sendRequest cancelled (#3371) or the script itself ended (#3460). Absent, not [], for a run that declared no requestElements, one whose elements never ran, and every scenario run - a scenario's own per-step tallies live under scenario.steps[].elements instead (see The scenario block and Scenario load runs), and the two never coexist on one report.

testValidation counts in two units: samplesTested is a number of responses (each sampled response the post-run replay evaluated the plan's script.post against), while testsPassed and testsFailed are numbers of assertions (pm.test calls) across those responses, so testsPassed + testsFailed is not samplesTested once a script holds more than one assertion. successRate is testsPassed as a percentage of assertions. samplesTested is also not summary.totalRequests: the replay buffer is bounded (sampling.responseSamplesDropped) and a request with no response has nothing to test. console? and consoleDropped? (#3127) are what the replayed scripts logged, in the element row's console shape ([{level, text, count?}]): the first 10 distinct lines across every sample, each cut to 500 bytes, kept whatever the script's verdict and with count when it was logged more than once (absent means once), and the count of occurrences a full list turned away. Both are absent when the replay logged nothing (consoleDropped also when nothing was turned away), and on a scenario load run, whose replay keeps one list per step on scenario.steps[].tests instead, so one step's line is never merged into another's.

The failing assertions are named on one synthetic row of results[], the one whose trace carries failures (no captured request has it): failures (each distinct message once, at most 10, a scenario step's name prefixing it), failureCounts (how many times each failed), failuresDistinct (every distinct message, so failuresDistinct - failures.length were turned away), totalFailed and totalPassed (assertions, each occurrence counted). A script failing the same way on every sampled response is one entry with a count, not one entry per sample (#3127). failureCounts and failuresDistinct are absent on a row from an older engine; see results for the stored shape.

thresholdValidation is one check per declared budget with the run's verdict. A maxAssertionFailureRatePct check also names the two populations it judged (issue #2892): assertionsSampled is testValidation's testsPassed and testsFailed, at sampleRate, and assertionsExact is the inline assertions counted on every completion that testValidation does not see. actual is the worse of the two failure rates.

assertions (issue #3537) is every failed check a load run's verdict reads, in one shape for both load run kinds, judged or not:

Key Meaning
exact {passed, failed}: every assert.* outcome, required extract.* miss and inline pm.test call, counted on each completion. A maxAssertionFailureRatePct check's assertionsExact, and a scenario load run's scenario.assertions
sampled {passed, failed}: the deferred replay, testValidation's testsPassed and testsFailed. A replayed script that threw is one failed test here
errored Element executions that ended in error: an inline script that threw, an element that could not run. The summed error of the elements rows (a scenario load run's scenario.steps[].elements), never scenario.errored, which also counts a step with no response
teardownFailed The lifecycle.teardown rows whose outcome is failed or error. A failed setup fails the run instead

Absent for a run that made no assertion and errored nowhere, and for a sequential collection run. A run stored before the block gets one derived from what it stored, carrying only what the readers then read: a scenario load run's scenario.assertions as exact, a single-request run's assert.* and script.* element rows as exact and its testValidation as sampled, never errored or teardownFailed. A member it could not derive is absent, not 0.

customMetrics (issue #1500) is this run's metric.record / pm.metrics values, by name - absent, not {}, for a run that recorded none. A "trend" entry carries count/p50/p95/p99/ max; a "counter" or "rate" entry carries count and value (a running total, or a 0-100 percentage). count is always how many times the name was recorded: a trend's samples, a counter's records (four increments of 1024 are count: 4, value: 4096, never the total; #1937), a rate's evaluations. A counter's increments are finite and never negative - see custom.<name>.<stat>. The same shape rides every GET /runs/:runId/metrics tick, and custom.<name>.<stat> reads it for a threshold.

timingBreakdown averages every completion. phases comes from five HdrHistograms fed by every successful completion, and each phase carries its mean beside its percentiles; the avg* fields are those means (issue #2782), so avgTlsMs and phases.tls.p99 describe the same completions, and the last live gate frame's cumulativePhases means equal them. phases is absent when phaseHistograms was off, nothing succeeded, or the run predates the bank. Without it, and for a run stored before the means existed (its phases carry no mean), the avg* fields fall back to the run's retained trace sample - the 1-in-success_sample_rate completions stored while save_timing_breakdown is on, plus any slow-request outliers - and are absent for a run that stored no traces. Read each half by its own key: the object's presence proves neither.

phases is what answers "was the latency the server or the connection path". A tls.p50 of 0 beside a large tls.p99 is a run re-handshaking under load - most requests reused a connection, a minority did not - which the average over both flattens into a number that looks merely mediocre. count is the number of completions behind each distribution and is identical across the five.

warnings (issue #1503) is what the run did not do, even though it finished and its other numbers may look fine: a request sent with a {{token}} composition never resolved (a scenario load run, and a single-request run that declares requestElements, re-resolve what composition left against the executing virtual user's or submission's own scopes before sending, so a name an inline script or extractor set is answered; a single-request run without requestElements resolves its request once, at run start, against the scopes an environmentId or requestId names, and runs no pass at all when it names neither, so either way a value a pre-request script would have set goes on the wire literally), or a step whose pre-request script this mode never executes - one that did not run inline (issue #1938: elements.scripts: "allInline", or the element's own inline: true under asMarked, runs it and raises no warning). Neither refuses the run - a literal {{ can be deliberate in a body - they are counted, not fixed. Each entry carries code and a human-readable message; unresolved_tokens also carries count (requests affected) and names (a few of the unresolved names, capped); pre_request_script_skipped carries steps (how many carried a script.pre that did not run inline). per_host_limit_raised (#2394) is of another kind: the run did everything, but opened more connections per host than eventLoopMaxPerHost says, because each worker's share of the virtual users (ceil(concurrency / workers)) was larger; it carries configured (the setting) and effective (the per-host limit each worker ran with). It appears only when the run asked for virtual users, a config that carries concurrency (#2801): a run that sets none is sized from the eventLoopMaxConcurrent default and gets the same raise, but has no virtual users to cover and no warning about them. connection_replayed (#2799) is another: libcurl re-sent count requests on a new connection after the server dropped or refused a reused one before answering, so the target received that many more requests than the run counted, each of those requests' latency covers both attempts, and a non-idempotent one may have run twice; count equals summary.connectionReplays, and it is raised only when that is above 0 (see What counts as an error). cookies_dropped (#3307) means libcurl's cookie engine discarded count Set-Cookie headers from the run's responses, summed over every response and redirect hop: a line over 5000 bytes, a cookie whose name and value pass 4096, or one past the 50th of its response, the limits a design send reports per cookie (see Cookies). A virtual user that lost a session cookie this way sent its later steps without it. The message names no cookie. Only a scenario load run's steps carry cookies, so only it can raise this; a step with disableCookies drops nothing. The outgoing caps (a Cookie line over 8190 bytes, more than 150 jar cookies) are not detected under load: reading libcurl's notice needs CURLOPT_VERBOSE on every transfer. think_timer_skipped_open_loop (#3541) is raised once by a constant_rps single-request run that sent anything and whose requestElements hold an enabled timer.think: the pacer sends on a schedule, so the timer was skipped on every submission (each tallied skipped under summary.elements) and held no slot. Its message is "A think timer does not apply to a constant-rate run: requests are sent on a schedule, not one after another", and it carries timers (how many enabled timers were skipped). A closed-loop mode runs the timer and raises nothing. Absent, not an empty array, for a run with nothing to report - which is every run before this field existed and every run that genuinely had nothing to say. unresolved_tokens covers every load shape alike (issue #1540): a single-request run with no data set and a scenario step report the same warning for the same mistake.

lifecycle (issue #1499) is script.setup / script.teardown's outcomes - what ran once at the run's own boundary, never at a step. Each key is present only when that phase ran at least one element (ElementOutcome's usual shape: id, kind, name?, origin, outcome, message?, waitedMs?, plus the two lists below); absent entirely, not {}, for a run whose collections (or, for a single-request run, whose own lifecycleElements array - issue #1573) declared neither. A collection run's elements come from its lifecycle set (#3456): every collection from the root down to the one being run and, on a recursive run, every folder beneath it in sidebar order, a folder before the folders nested in it. setup lists them in that order and teardown in reverse, and each row's origin is {kind: "collection", scope: "collection" | "folder", id, name}, naming whose script it was. A script.setup outcome other than "ok" or "skipped" means setup refused the run before it sent anything: status is Failed, no step ran, and the run still stores a summary whose lifecycle.setup holds every setup that ran up to and including that outcome with its message (#3455), every other section above absent or zeroed - so a reader who finds one here knows why the rest of the report is empty. The collections after the refusing one set up nothing. No teardown runs on such a run, so it has no teardown key. A script.teardown outcome of "error" carries the thrown message but never changes status: a teardown failure is reported, not fatal. A script that ran and failed only pm.tests is "failed", its message the first failing test, as a script.post's is. A script element's row also carries messages (what it threw, then each failing test, as {kind: "error" | "test", text}) and console (each console line, as {level, text}) - the entry shape, the cap of ten distinct entries, the count on a repeat and the messagesDropped / consoleDropped counts of an element row's lists (#3127), each key present only when the script said something. A script the run's Stop cut short is "skipped", with a message saying which way: its pm.sendRequest was cancelled (#3371), or the script itself was ended while it ran (#3460). The run ended under it, nothing failed, and the app shows the row muted rather than as a failure.

A streaming run adds a stream section and no other run carries one:

"stream": {
  "completions": 480,
  "totalEvents": 19200,
  "capped": 480,
  "eventsPerSecond": 320.0,
  "events": { "min": 40, "max": 40, "p50": 40, "p90": 40, "p95": 40, "p99": 40, "count": 480 },
  "timeToFirstEvent": { "p50": 412.0, "p95": 655.0, "p99": 803.0, "max": 910.0, "count": 480 }
}

Absent for every run that did not stream, and for one started with stream_metrics: false - not zeroed, because "this run was not a stream" and "this stream delivered nothing" are different answers, and a run whose target closed every connection before the first event is where telling them apart matters.

events is the per-completion distribution, not the run's total: 480 streams of 40 events each have a p50 of 40, not of 19200. eventsPerSecond is the whole-run rate, derived from the same testDuration the report's rps uses so the two are comparable. Both are reported because one long stream and 250 short ones can share a rate while being entirely different runs. A stream that delivered nothing is a 0 in events like any other count (#3240), so a run whose target closed every connection before the first event reads min, max and every percentile as 0 beside totalEvents: 0. The figures are exact up to 2,046 events per stream and within 0.1% above.

capped counts the completions a cap ended rather than the server. In the example above every stream hit the event cap - the events percentiles all sitting exactly on it is the tell - so those counts measure the caps, not the target.

timeToFirstEvent (issue #3234) is the per-completion distribution, in milliseconds, of how long each stream took to deliver its first event: from the moment the request was submitted, the origin latency is measured from, to the write that completed the first frame carrying a data field. It is not timingBreakdown.phases.firstByte, which ends at the response headers: an LLM gateway answers 200 at once and then thinks, so its wait lands in the download phase and firstByte reads fast for a stream whose first token was slow. count is the completions that delivered an event, so a stream the target closed before its first event, a silent one a cap ended, and one whose only event was an unterminated frame the close completed are all left out (the last arrived at the close, and no time for it was measured). The object is absent when no completion delivered a timed event.

A capacity run adds a capacity section and no other mode carries one:

"capacity": {
  "sloMs": 200,
  "maxErrorPct": 1,
  "stopReason": "slo_exceeded",
  "maxHealthyConcurrency": 48, "maxHealthyRps": 23400, "p99AtMaxHealthyMs": 41.2,
  "kneeConcurrency": 64, "kneeP99Ms": 312.0, "kneeErrorPct": 0.4,
  "levels": [ { "concurrency": 1, "rps": 980, "p99Ms": 1.4, "errorPct": 0, "samples": 4900 } ]
}

stopReason is one of slo_exceeded, errors_exceeded, plateau, cap_reached, deadline or stopped - see Capacity semantics. maxErrorPct is the error-share limit each level was judged against, and errorPct / kneeErrorPct are percentages (0-100) on the same scale, so a reader can mark an over-limit level without knowing the constant. The optional groups are omitted rather than zeroed, and the distinction carries information:

  • maxHealthy* is the highest level tried that stayed inside the budget, and is absent when the very first level already breached it (on latency or on errors). The search found no sustainable capacity, which is not the same claim as a capacity of zero. On a plateau stop it is the last level tried, which overshoots: read saturation* for the plateau.
  • knee* is absent unless stopReason is slo_exceeded or errors_exceeded. A run that ended at its ceiling, its deadline, or on a plateau inside the budget never watched the target give out, so it has no knee to report.
  • saturation* (saturationConcurrency, saturationRps, saturationP99Ms) is present only when stopReason is plateau: the lowest healthy level whose throughput the best healthy level beat by under 5%, i.e. where more concurrency stopped buying work. A run that stopped any other way never observed a plateau and carries none.
  • maxErrorPct, kneeErrorPct and levels[].errorPct are absent from a run stored before the search judged errors (#2815): it never measured an error share, and a 0 would call every level clean.
  • levels[].samples is the number of completions the level's histogram held when the level was judged (#2926), i.e. what p99Ms was computed over. A 0 means the level measured no latency (only refused connections), so its p99Ms of 0 is "nothing measured", not "answered instantly". It is absent from a run stored before the field existed, never 0, for the same reason as the error share.

levels[] is one entry per level judged, in order - bounded by construction (a search holds tens of levels, not thousands). A level that breached once and was re-measured appears twice, at the same concurrency; the level still being measured when the run ended does not appear at all, because it was never judged.

auth appears only for a run whose OAuth 2.0 credential could be renewed while it ran - a header-placed, expiring token with autoRefreshToken on (see db-schema.md for the full eligibility list). Each entry in refreshes is when a renewal landed, in seconds from the run's start. refreshFailures plus a lastError string is the other half of the answer: the run kept sending the credential it had, so 401s in statusCodes from that point on are explained here rather than by the target. A renewal still in flight when the run ends is cancelled rather than waited out, and is not a failure. The section is absent for a run that could never refresh, which is not the same claim as a run that watched and never needed to (that one reports an empty refreshes array). A collection load run that keeps several tokens current (one per distinct cache key its steps send, #3199) reports them in this one shape: every renewal in refreshes, in order of atSeconds, refreshFailures summed, and lastError the most recent failure of any of them.

A scenario run adds a scenario section and no other run type carries one:

"scenario": {
  "iterations": 3, "iterationsCompleted": 3, "stepsExecuted": 6,
  "passed": 4, "failed": 1, "skipped": 0, "errored": 1,
  "stepsStored": 6, "stepsDropped": 0, "stepsNotRun": 0, "stopOnError": false,
  "stopped": 0,
  "transactions": [
    { "name": "checkout", "count": 3, "errors": 0,
      "latency": { "min": 8.1, "p50": 14.2, "p90": 22.0, "p95": 26.5, "p99": 33.0, "max": 55.4 } }
  ]
}

stepsStored versus stepsExecuted is the honest reading of results[]: a run that filled maxScenarioStoredSteps reports fewer rows than it ran, with every failed, errored and skipped step among the ones kept (a stopped one is kept like a success). On a collection run (design mode) stepsExecuted counts steps and summary.totalRequests counts requests sent (issue #2822): a step the plan skipped (control.if, control.throughput, pm.execution.skipRequest()) is a step and not a request, while a request that got no response is one, under status 0. statusCodes, successfulRequests, failedRequests and errorRate come from the distribution the runner stored over those same requests, never from the kept rows, where a skipped step is a status-0 row: they describe the whole run past maxScenarioStoredSteps and agree with a maxErrorRatePct check's actual. A run in which every step was skipped reports totalRequests 0 and an empty statusCodes. A summary stored before #2822 has no distribution: its totalRequests is the step count and the split comes from the kept rows.

passed, failed, skipped and errored mean the same in both run kinds (#2824, the Outcomes table under Scenario runs): one per step execution, disjoint, with an HTTP error status that no assertion rejected counted as passed and in summary.failedRequests. stepsExecuted is every step reached, a skipped one included, so in both passed + failed + errored + skipped + stopped = stepsExecuted, stopped read as 0 where it is absent. A scenario load run's steps[].executed counts every execution that was not skipped, so there the sum of steps[].executed, plus skipped, also equals stepsExecuted; a collection run has no steps array. A scenario load run stored by engine 0.45.0 or earlier keeps its old numbers: failed was the sum of every step's httpErrors, and passed was stepsExecuted less failed and errored, skipped steps included.

stepsNotRun is how many plan positions errors cost the run - summed over every iteration an errored step ended, the positions after that step the iteration had not attempted (Outcomes under Scenario runs). stepsExecuted beside a non-zero stepsNotRun is a run that did less than its plan, not a complete one with an error in it. stopOnError is the run's own setting, echoed because the same counts describe a different run under it. Both are written by a collection run (design mode) only: a scenario load run's section carries neither, and a summary stored before issue #2526 carries neither either. stopped (#3397) is the steps a Stop or a shutdown cut short, which no failure count includes and which take no failure's place among the kept rows; it is likewise a collection run's alone, absent for a scenario load run (whose stop-cancelled steps are in no count) and for a summary stored before it.

assertions (#2820) is the other way round: a scenario load run's alone, { passed, failed } over the exact population (every assert.* outcome, required extract.* miss and inline pm.test call, never the sampled replay testValidation reports), the report's top-level assertions.exact. It counts assertions where failed above counts step executions, so an execution that failed three is one failed step and three assertions.failed. It is absent for a run that made no such assertion, a collection run in design mode and a run stored before it; Scenario load runs has the rest.

transactions (issue #1515) is a sibling of steps, not a member of it - a control.transaction spans a folder, not one step - and is absent, never [], for a run with no control.transaction element or one whose folder never closed. One entry per declared name that closed at least once, in the same shape scenario.transactions documents elsewhere on this page.

latency.* and the enriched summary fields (peakConcurrency, avgInFlight, droppedRequests, skippedRequests, stalledMs, avgQueueWaitMs, bytesSent/Received, throughputBytesPerSec) come from the run's stored summary, not from the per-tick metrics rows. latency_ms in results is perceived latency.

A collection run's summary omits the load-only figures (issue #2822). A sequential run feeds no load collector, so sendRate, throughput, peakConcurrency, droppedRequests, avgQueueWaitMs, bytesSent, bytesReceived, throughputBytesPerSec, setupOverhead and cleanupOverhead are absent rather than 0; avgRps is requests sent over testDuration. A scenario load run is a load run and carries every one of them.

A collection run's latency block (issue #2389) is the stored latency its runner wrote, over the latency population of the sequential path: every step whose transfer ran, answered or not, and not a step the plan skipped or one refused before the wire. That is the sample the run's latency*Ms budgets judge, from one computation, so latency.p99 equals the actual of a latencyP99Ms check. Unlike the HDR histogram the load paths read, the figures are exact nearest-rank over the full sample (avg is its mean), and they are not read from the results[] rows, which can include a skipped step's 0 ms and are thinned past maxScenarioStoredSteps. A collection run in which no step sent has no latency block rather than zeros. A summary written before this existed carries no latency and reports from the stored rows as before.

summary.failedRequests and summary.errorRate are the one error definition, recounted from the run's status-code distribution; summary.httpErrorRequests and summary.noResponseRequests split failedRequests and always sum to it. summary.totalRequests is successfulRequests + failedRequests, the requests that got an outcome, and errorRate is failedRequests over it.

summary.cancelledRequests is the requests a POST /runs/:runId/stop cancelled before they answered (issue #2136): sent, never an outcome, and so in none of the figures above - a healthy target stopped mid-run reports errorRate 0 beside them. Always present: 0 for a run nothing cancelled, and for a run whose stored summary predates the count, because only the stored summary records it (the status-code distribution never held them). summary.drainCut ({cancelled}, issue #3538) is present only when a Stop cut the drain of a run that ended on its own: the part of cancelledRequests still unanswered when the drain was stopped, which keeps the run's verdict not judged unless a budget already failed it.

summary.partial (true) marks a run the engine died under, whose figures are its last persisted tick's; summary.summaryMissing (true) marks a failed load run with no summary at all, whose counts are not a measurement. Neither report has a latency block (issue #2938). Each flag is absent otherwise, never false; "A run the engine died under" above says what each figure then holds.

summary.httpVersionDowngraded is the count of this run's transfers that asked for HTTP/2 and negotiated something older - see httpVersionDowngraded on a response. A collection run counts its sent requests the same way (#3262, Scenario runs); a collection run stored by an engine older than that fix reads 0 here although its steps' traces may say otherwise. It is the only figure in summary that describes the report's validity rather than its performance: non-zero means the latency and throughput beside it were measured over a protocol other than the one metadata.configuration.httpVersion names.

0 is "none recorded", not "none happened". An engine from 0.15.0 always emits the key - including for a run whose stored summary predates the count, and for one reported from its sampled results because that summary was malformed or never written, neither of which can produce a figure. The key is absent only from an engine older than 0.15.0. That is deliberately a weaker guarantee than the per-response httpVersionDowngraded, which is exact for the exchange it describes.

summary.connectionReplays is the count of requests libcurl re-sent on a new connection after the server dropped or refused a reused one before a byte of the answer (issue #2799). The extra sends are in no other count, not totalRequests, the error counts or noResponseRequests: each replayed request is counted once, by the outcome of its last attempt, so the target received totalRequests + connectionReplays requests (see What counts as an error). A non-zero value also raises the connection_replayed warning. Absent and 0 are different answers: 0 is a run whose engine counted and saw none (the key is always stored, zero included), and absent is a run stored before the count existed, or one reported from its sampled results because its summary was malformed or never written. A partial report of a running load run reads it from the live counter.

summary.avgInFlight is the mean number of requests in flight over the run (issue #2821): the time requests spent in flight, summed over every request, divided by testDuration (issue #3567). A request is in flight from its submission to the event loop until it completes, its queue wait inside the generator or libcurl included, and a Stop's cancellation ends it, so a request the Stop cancelled counts the time it was open. A virtual user in a timer wait between requests has none, and neither does a request refused or skipped before it reached the event loop (a maxInFlight drop, a data-binding failure, a step a controller skipped). A step's script time (elements.includeScriptTime) is not part of it. With no think time it equals the virtual user count, and over that count it is the run's utilisation. A run stored before issue #3567 keeps the old figure under the same key: the latency sum of the latency population divided by testDuration, which left out cancelled requests and folded in included script time. peakConcurrency beside it is the high-water mark of the instantaneous in-flight gauge (the live stream's backpressure), which the load generator reads after each batch of submissions in every mode: the closed-loop controller behind constant_concurrency, ramp_up, iterations, capacity and every scenario run, and the open-loop pacer behind constant_rps (issue

2912). The once-a-second metrics sample is a backstop writer. A

closed-loop single-request run's gauge counts the slots a timer.think wait holds too; a constant_rps run's counts requests alone, because it skips the timer (#3541). The peak is the most requests ever in flight at once, so on a run whose users wait in step it can read the full user count though most of the run had far fewer in flight; avgInFlight is the figure that measures utilisation. avgInFlight is present for a load run stored since issue #2821, 0 included; absent for a run stored before it, a collection (design-mode) run, and a run reported from its sampled results, never a 0 nobody measured.

summary.setupOverhead and summary.cleanupOverhead (issue #2894) are the two stretches of a load run outside testDuration, in seconds. setupOverhead runs from the run's own thread taking it up to load start: reading the run's settings, building its request or plan, and the script.setup pass (a collection's, or a single request's lifecycleElements), so a slow setup script shows here and never in testDuration. cleanupOverhead runs from the end of load, the drain included in testDuration before it, to the run's background threads (the metrics tick, the token-refresh watchdog, the monitor scrape) having stopped, before the deferred script and schema passes and the summary write. Both read 0 for a failed run's best-effort summary, a partial report of a running run, a run reported from its sampled results, and a collection (design-mode) run, none of which times them. A run stored before the issue stored the cleanup figure under the setup name: its report carries that figure as cleanupOverhead and has no setupOverhead, rather than a setup time nobody measured.

sampling says how much each bounded store thinned away: all zeros means the error, trace and tested-response sets are complete, and a non-zero count means they are a uniform sample of the whole run (reservoir retention) rather than a truncated prefix of it. The section is absent on a run recorded before it was reported, which is not the same claim as "nothing was dropped". It does not describe results[], which has its own selection rule below.

results[] is not a uniform sample (#2210). A non-scenario run returns at most 100 stored rows. When it stored more, the rows are chosen by value: every row with a failing status (anything outside 2xx/3xx, including the 0 of a transport failure) takes a slot first, up to the cap, and rows that succeeded fill the remainder in storage order. The chosen rows are listed in timestamp order, ties broken by row id, whichever way they were selected. A Scenario run keeps every stored step (bounded at write time by maxScenarioStoredSteps, see stepsStored). Two top-level keys, always present, say whether the array was cut: resultsStored is the number of rows stored for the run and resultsCap is the cap applied (equal to resultsStored for a scenario run). resultsStored > resultsCap is the only signal that results[] is a selection and not the whole set; both sit beside results rather than inside sampling because that section is optional.

responseSamplesDropped counts responses the post-run test scripts and schema checks never saw, for either of the two bounds on that store: the count cap (max_response_samples), and the byte budget (max_response_sample_bytes) that drops a whole sample once the run's retained bodies would exceed it. Both mean the same thing to a reader - this response was not validated - and neither ever stores a cut body, because a deferred check reading one reports a failure the target never produced. They differ in one way worth knowing: the count cap displaces an incumbent, so the tested set stays a uniform sample of the run, while an exhausted byte budget stops admitting - a run that spends it is graded on the part of the run whose bodies fit. The counter cannot say which bound applied on its own; responseSampleBudgetSpent is the answer (issue #1192). true means the byte budget ended at least one sample, so the tested set is drawn from the part of the run whose bodies fit; false means only the count cap displaced anything, so the tested set stays a uniform sample of the whole run. It is written by every run recorded since the marker existed, and is absent on a summary written before that - absent means "not known", not "not spent", which matters because weakening the uniform claim for every pre-marker run would cost the accurate message in the case that is nearly all of them: only a target whose retained bodies average more than ~256 KiB reaches the budget at the defaults. The app's retention note drops its uniformity sentence only when the key reads true; absent or false both keep it.

Three of its keys are about captured responses rather than retention: responseBodiesCaptured is how many exchanges the run stored (see GET /runs/:runId/samples), and is also the run's own marker that it holds response data stored verbatim - non-zero is what the Samples tab warns on. sampleBodiesDropped counts samples whose headers were kept but whose body was dropped once the run's maxSampleBytes budget was spent. exemplarsDropped counts per-status exemplars refused because max_exemplar_results was full, which only a target answering with more distinct status codes than that limit can reach. All three are absent on runs recorded before 0.15.0.

monitor is present only for a run that declared a monitor block - absent is "this run scraped nothing", never "the target reported zeros". samples counts scrapes that read at least one requested name; the others are split by cause. failures counts the scrapes that got no 2xx answer, and lastError, present once one has, names the most recent one's cause: HTTP <status>, or one of timed out, unreachable, host not found, TLS handshake failed, proxy failed, URL refused, too many redirects, undecodable body, response too large and transport error. It is never the transport's own message, which can quote the URL. noMatchScrapes counts the 2xx answers that carried none of the requested names. So samples: 0 with a non-zero failures says the endpoint was unreachable or erroring for the whole run, and samples: 0 with a non-zero noMatchScrapes says it answered every time but the names matched nothing. A series that never produced a reading is absent from series for the same reason. noMatchScrapes and lastError are absent on a run recorded by an engine that predates them, whose failures count no-matches too. The per-sample readings are served separately by GET /runs/:runId/monitor.

results[].id is the results row id, and the join key against GET /runs/:runId/samples. It is absent on reports served by an engine older than 0.15.0. The rows are listed by timestamp, not by id.

metadata.configuration carries the load-test tuning knobs present in the snapshot (mode, duration, concurrency, iterations, startConcurrency, rampUpDuration, timeout, comment, followRedirects, maxRedirects - each omitted when absent, and recording what the run was sent, never a default the engine filled in; issue #2437) plus httpVersion, which is always present with the same "auto"-when-unknown normalization GET /runs's summary uses (see above), and acceptEncoding (issue #1488) and expectContinue (issue

2516), read out of the snapshot's defaultHeaders and omitted on the same

terms as GET /runs's summary key acceptEncoding (expectContinue is on the report only, not in the list row: only the comparison reads it). rps in the raw snapshot is renamed to targetRps here, and rps is read first (targetRps is the rate only when rps is absent, null or zero), as in GET /runs's summary. dataRowCount is the size of the data set a run bound, and dataFileName / dataFileHash (issue #2051) the file it came from, by display name and SHA-256 of its bytes, never its path, with dataFileCastNumbers: true (issue

2540) when that file's numbers were read as numbers. A single-request run's

are read off the snapshot's top level; a collection run's off its scenario manifest, so every report of a run that named a file carries them here, and a run that named none has no such key. carriedBudgets (issue #2195) is the list of thresholds keys the client sent as carried over from an earlier run rather than set for this one, echoed as sent and omitted when the run sent none (see Carried-over budgets); GET /runs's summary does not carry it. A capacity run's own two knobs (issue #2925), stepDuration (the string the run was started with, as duration is) and sloMs, are echoed as sent, on a capacity run only and omitted when it left one at its default: the search's effective budget is the report's capacity.sloMs. A run of any other mode has neither key, whatever its snapshot holds. POST /export/run-report carries both in config.configuration.

GET /runs/:runId/samples

Get the response headers and body a load run captured for its retained samples. Paginated; no deprecated alias - the endpoint is new in 0.15.0, so there is no pre-consolidation spelling for it to keep working.

Deliberately not part of GET /runs/:runId/report. That path loads every results row for the run and JSON-parses each trace_data to accumulate aggregates that never look at a body, and the dashboard polls it; at 1000 samples carrying 32 KiB bodies, folding them in would turn every poll into ~32 MB read from SQLite and parsed. So the bodies live in their own tables and are fetched here, per page, only when a reader actually expands a sample.

Query params:

Param Default Notes
limit 50 Capped at 500; a non-numeric value falls back to the default
offset 0 Floored at 0

What a run captures - and does not - is described under result_bodies: every error, the slow outliers, and the first three of each distinct status code, within maxSampleBodyBytes per body and maxSampleBytes for the run. A uniformly sampled success carries no body by design.

Response:

{
  "data": [
    {
      "resultId": 41,
      "response": {
        "headers": { "content-type": "application/json", "server": "nginx" },
        "body": "{\"error\":\"upstream timeout\"}",
        "bodyEncoding": "utf8",
        "bodyBytes": 28,
        "contentType": "application/json"
      }
    },
    {
      "resultId": 42,
      "response": {
        "headers": { "content-type": "image/png" },
        "bodyBytes": 20480,
        "contentType": "image/png",
        "binary": true
      }
    }
  ],
  "pagination": { "total": 23, "limit": 50, "offset": 0, "hasMore": false, "returned": 23 }
}

resultId is the results row this exchange belongs to - join it against results[].id on the report rather than re-deriving an order.

The response node always carries headers and bodyBytes (the size as received, before any truncation). The rest is conditional, and each key means something the bytes alone cannot say:

Key When present Meaning
body Not binary The stored bytes, as bodyEncoding says. "" when the response had none, or when the body was dropped
bodyEncoding Not binary "utf8": body is the stored text. "base64": the stored bytes are not valid UTF-8 text (or hold a NUL) and body is their standard, padded base64
bodyTruncated true only body is a prefix; the response was larger than maxSampleBodyBytes. Same convention design-mode traces use
bodyDropped true only The run's maxSampleBytes budget was spent before this sample: headers kept, body not. Distinct from an empty response body
binary true only Stored as a descriptor - bodyBytes and contentType, no bytes. See result_bodies for why a binary body is never stored as text
contentType Non-empty The response's Content-Type
events Streams only What the stream delivered, in the trace's events shape (see below). Absent for every sample that did not stream

bodyEncoding: "base64" is not binary: true (issue #3159). binary is decided when the sample is captured, from the Content-Type and the first 1024 bytes, and such a body is never stored. A body that passed that sniff is stored as text, and bodyEncoding is decided when the sample is read, over every stored byte, because a JSON string holds only UTF-8: a NUL or a byte that is not UTF-8 past the first 1024 lists the whole body as base64, with bodyBytes still the size as received, never the encoded length. A body the maxSampleBodyBytes cap cut inside a multi-byte character is first trimmed back to a character boundary, so it stays utf8 with bodyTruncated set rather than turning the whole prefix into base64.

A streamed sample carries its events (0.17.2). events is {items, totalEvents, eventsTruncated} - the same node a streaming design run stores on its trace, minus endReason: under load a stream ends by server close or by one of two caps (maxStreamEvents / maxStreamDurationMs) and nothing per sample records which, so no reason is named rather than one invented. The list is parsed out of the stored body on read, bounded by sseMaxStoredEvents, and totalEvents is the count taken on the wire - so a capture the maxSampleBodyBytes cap cut still reports the whole stream's length, with eventsTruncated covering both that cut and the stored-events cap. The events are parsed from the stored bytes whatever bodyEncoding says, and a byte in an event that is not UTF-8 is answered as U+FFFD. See result_bodies for why the count is stored and the list is not.

"events": {
  "items": [ { "event": "token", "data": "hello", "sourceId": "42" } ],
  "totalEvents": 4000,
  "eventsTruncated": true
}

Captured data is stored verbatim - no redaction, consistently with design-mode traces, which already store request headers as sent. A response Set-Cookie is captured along with everything else. It is deleted with the run, so maxRunsRetained is its expiry.

A run that captured nothing is an empty page, not an error; an unknown run id is a 404 in the shared error shape.

Response (404):

{ "error": { "code": 404, "message": "Run not found" } }

PUT /runs/:runId/baseline

Pin (or unpin) any run - design, load or scenario alike. PUT rather than POST per the create vs update split: the run already exists, and this updates it. There is no deprecated alias; the endpoint is new.

Two things follow from a pin, and both are the point of it:

  • Retention never expires it. prune_runs skips a baseline under both count caps and the age cap, and a pinned run does not count toward maxRunsRetained or maxDesignRunsRetained either - a pin a cap could expire is not a pin, and pins crowding a cap would evict the recent history the cap exists to keep.
  • Clients can find it: GET /runs?baseline=true&requestId=<id>&limit=1, or ...&collectionId=<id>&... for a load run over a collection.

The engine's own meaning of the flag stops there - it holds no opinion about why a run is kept. A client's vs-baseline comparison is a narrower, load-only reading of the same flag: only a load run has the percentiles and throughput a diff needs, so a comparison lists type=load alongside baseline=true (GET /runs?baseline=true&type=load&requestId=<id>&limit=1) rather than treating any pinned row as its baseline - otherwise a more-recently-pinned design or scenario run of the same request would shadow it.

Several runs may be pinned at once (one per request or collection is the expected use). The engine records the pin and holds no opinion about which baseline applies to which run - that selection is the client's, so a pin never unpins anything else.

Request body - baseline is required and must be a boolean:

{ "baseline": true }

Response 200: the updated run row, in the same shape GET /runs lists (including summary and origin, but never resultSummary), so a client can patch its cached row instead of re-listing.

400 when the body is not JSON, has no baseline, or baseline is not a boolean - including null. Unlike the merge-patch resource updates, an unusable value here is refused rather than ignored: this body has exactly one field, so ignoring it would answer 200 to a request that changed nothing.

{ "error": { "code": "bad_request", "message": "Invalid 'baseline': must be a boolean" } }

404 when no run has that id.

DELETE /runs

Clear run history: delete every run - design, load and scenario alike - except the ones retention never deletes either (issue #2429):

  • a run pinned as a baseline (see PUT /runs/:runId/baseline) is kept - the pin is a promise to keep the run, and a bulk clear does not break it. Unpin first, or name the run in DELETE /runs/:runId, to remove one;
  • a run whose stored status is still running or pending is kept and left running. Stop it, then clear again.

Each run goes with its metrics, results and captured bodies, through the same cascade and the same batched pass as retention: batches of 100, each in its own transaction, and each row re-read under that batch's lock, so a run pinned or started while the clear is under way is spared. A deleted run is gone for good; runs have no trash. The call takes no body and no query parameters.

Response 200:

{
  "deleted": 2,
  "keptPinned": 1,
  "deletedIds": ["run_1712345678901", "run_1712345678902"]
}

deleted is the length of deletedIds, the runs this call removed, so a client can close whatever was showing one. keptPinned counts the pinned baselines stored once the clear finished; a run kept for being in flight is in neither number. An empty history answers {"deleted": 0, "keptPinned": 0, "deletedIds": []}.

DELETE /runs/:runId

Delete a run and all associated metrics/results.

An active run is stopped first. Deleting a run that is still executing used to remove its rows while its worker kept writing new metrics and results against the same id - orphan rows that no run owns, and a run that partially reappeared as it finished. So a run that is still active is stopped exactly as POST /runs/:runId/stop stops it, and the rows are removed only once its worker has completed its final writes. Expect the call to take as long as the stop does (up to ~5s for a large run).

If the worker has not settled within that window nothing is deleted and the call returns 409 - a half-deleted run racing a live writer is worse than a delete that has to be retried. The stop still stands, so a retry a moment later succeeds. A run whose stored status is running but which has no worker (the daemon restarted under it) has nobody to race and is deleted immediately.

Response:

{
  "message": "Run deleted successfully",
  "runId": "run_1234567890"
}

409 Conflict (still stopping - nothing was deleted):

{
  "error": {
    "code": "conflict",
    "message": "Run is still stopping; it was not deleted. Retry once it reports a terminal status."
  }
}

Scripting

GET /scripting/completions

Get script engine API completions for UI autocomplete.

Response:

{
  "version": "1.0.0",
  "engine": "quickjs",
  "completions": [
    {
      "label": "pm.test",
      "kind": 1,
      "insertText": "pm.test(\"${1:test name}\", function() {\n\t${2:// assertions}\n});",
      "detail": "pm.test(name: string, fn: () => void)",
      "documentation": "Define a test with assertions..."
    }
  ]
}

An entry whose kind is 28 (Monaco's Snippet kind) carries two extra members no other entry does: context, one of "pre", "test" or "both", which script kind the template belongs in; and group, one of "Variables", "Request", "Response", "Tests", "Signing" or "Logging", the heading it is listed under. A client uses the pair to build a filtered, grouped snippets picker for whichever panel - Pre-request or Tests - the author has open, rather than offering the whole table regardless of where it would run. Neither field is present on a non-snippet entry.

GET /scripting/types

The same pm.* surface as TypeScript declarations, for Monaco's TypeScript worker. A completion list can only populate a dropdown; the declarations are what give hover documentation over an existing call, signature help while typing arguments, and go-to-definition within the surface.

The declarations are generated from the completion table above, not maintained separately - a hand-written pm.d.ts in the app would be a second declaration of a surface the engine owns, and the two would drift the first time a method was added to one and not the other. The derivation works because a completion entry already carries its type: a function's detail is its signature, a field's detail is its type. See engine/src/http/routes/script_types.cpp.

Output is deterministic - the same table always produces byte-identical text, so a client may cache on version.

Response:

{
  "version": "1.0.0",
  "engine": "quickjs",
  "libUri": "ts:vayu/pm.d.ts",
  "typeDefinitions": "interface VayuExpectation {\n\tequal(expected: any): VayuExpectation;\n…"
}

Field Description
libUri Model URI the app registers the declarations under (addExtraLib)
typeDefinitions The .d.ts source

The file also declares the names a script may reach for that the sandbox lacks, with the reason as documentation: the host globals of a browser or Node (fetch, URL, Buffer, ...), and the libraries Postman bundles that the require() shelf does not carry (cheerio, Backbone), whose hover names the replacement Postman itself gives. require, CryptoJS, _, tv4 and xml2Json are declared as what they are, with a declare module for each name on the require() shelf (crypto-js #2578, uuid #2650, lodash

2651, moment #2652, csv-parse/lib/sync #2653, xml2js #2654, chai #2655, ajv and tv4 #2656) and one require

signature keyed on those names, so a name off the shelf is a type error. Postman's postman object and its pre-pm.* globals (tests, responseBody, responseCode, ...) are not among them: they run (#2577), and are declared from the completion table like pm itself, each as the value it is.

It also carries interface augmentations for standard-library members the runtime runs but the TypeScript bundled with the editor does not declare yet (RegExp.escape, Math.sumPrecise, JSON.rawJSON, Uint8Array.fromBase64 and toHex, and their siblings), under their own banner; a row retires when that TypeScript declares its members (#3485).

That is not padding: the app suppresses "Cannot find name" (2304), so a name that is merely undeclared draws nothing. A name typed never makes the call, member access or assignment that follows an error ("not callable", "property does not exist"). never is assignable to everything, so a bare read passes (console.log(cheerio)).

Declaring a name does not reserve it: the app compiles each script as a module (moduleDetection), so a script's own const data = ... shadows the declared data instead of redeclaring it. A test executes typeof <name> in the real script engine for every root, so the list cannot drift from the runtime, and an entry leaves the table in the commit that makes the runtime provide it.

The assertion chain is one interface, read by leaf rather than by path (#1209). A completion label is a dotted spelling - to.have.deep.property is what someone types - and not the shape of the object: create_expectation installs to, have, deep and property on the same expectation, and every one of them hands that expectation back. So the generator takes each label's last segment as the member and every earlier segment as evidence that word is a chainer, and emits a single VayuExpectation where every chain word is a property of that type and every matcher a method returning it - chai's own model. Read as a path tree it emitted two interfaces instead, and a matcher was reachable only along the one route some label happened to spell, so .to.be.a('string').and.match(/x/) was an editor error on a chain the engine runs. Where two labels share a leaf (to.have.property, to.have.deep.property, to.have.nested.property), the plainest spelling declares the member and the longer ones fold their documentation into its hover under their own labels.

The guard is set equality rather than a list of names: TheDeclaredChainIsTheObjectTheRuntimeBuilds reads the interface's members out of the generated text and the expectation's out of the real script engine (Object.getOwnPropertyNames, so no terminal getter is triggered) and fails on a member either side has alone. A matcher added to the runtime and not to the table now reddens instead of being missing.

Two things the generated file still cannot get from the table, both handled in script_types.cpp and guarded by script_types_test.cpp:

  • Which label roots open the chain. that.is.not.empty is a chain and console.log is a global, and nothing in either entry says which; the chain roots (to, and, and chai's twelve language chains) are named in the generator, so a label rooted at one is filed under the chain rather than declaring a top-level that nothing binds.
  • Unparseable parameter lists. Two entries document an overload in prose TypeScript cannot parse (upsert({ key, value }) | (name, value)). Those fall back to (...args: any[]), keeping the member callable rather than emitting a file that does not compile.

The declarations are compiled, not just grepped

script_types_test.cpp asserts on substrings of the generated text - every listed member appears, the chain returns the chain, an optional field keeps its type. That cannot catch the class of defect where a declaration contains every right name and still does not type-check, and four of those shipped (#463): pm.cookies.jar() emitted twice with the object overload winning, every jar method's signature emptied by the () inside its own label, pm.info.eventName read as prose and typed void, and two pm.expect chains shorter than the documentation beside them.

So the durable guard compiles every ```javascript block mentioning pm. in scripting.md and pm-api-compatibility.md against the real declarations and requires zero errors, with the app's own compiler options and suppressed codes. The same suite compiles scripts that use the absent names and requires the error each should draw, and scripts that declare one themselves and requires none. The documentation and the declarations then hold each other up: an example the editor would squiggle fails the suite, and so does a declaration that stops describing what the docs recommend.

It needs a TypeScript compiler, which ctest does not have, and the generator needs the engine, which vitest cannot run. The two halves meet at one checked-in artifact - the same shape as variable-resolution-conformance.json:

Where What
engine/tests/fixtures/script-typedefs.d.ts The generated declarations, checked in
ScriptTypesTest.TheCheckedInDeclarationsMatchTheGenerator Pins that file to the generator byte-for-byte, so the copy cannot drift
app/src/hooks/script-typedefs.docs-compile.test.ts Compiles the docs' blocks against it

A change to the surface therefore shows up as a diff in the declarations the editor will serve. Regenerate deliberately:

VAYU_UPDATE_SCRIPT_TYPEDEFS=1 ctest --preset linux-dev -R ScriptTypes

HTTP Status Codes

Code Meaning
200 Success
400 Bad request (invalid JSON, missing required fields, invalid OAuth 2.0 config)
401 OAuth 2.0 provider rejected the token request
404 Resource not found
409 OAuth 2.0 interactive authorization required (/run pre-flight, /oauth2/token)
412 A whole-record PUT or a POST /globals whose If-Match no longer names the stored row (precondition_failed, Conditional updates)
429 A start refused at its cap: oauth2_authorize_limit_reached (16 unsettled sign-in attempts), mock_issuer_limit_reached (8 mock issuers)
500 Internal server error, including a storage failure that is neither a full disk nor a lock (resource writes)
502 Upstream network error (OAuth 2.0 token endpoint, /import/fetch proxy)
503 Engine is shutting down (POST /runs, see below), or the database stayed locked past its busy timeout (a resource write; carries Retry-After: 1)
504 OAuth 2.0 token endpoint did not answer within the defaultTimeout setting (/oauth2/token, oauth2_timeout)
507 The disk holding the data is full (a resource write, insufficient_storage)

Notes

  • All timestamps are Unix milliseconds (since epoch)
  • Variable substitution uses {{variableName}} syntax
  • Environment variables are resolved in order: environment → collection → global
  • Load test metrics are collected every 100ms
  • SSE connections timeout after 30 seconds of inactivity