Skip to content

Insomnia v4

Insomnia 11 and later export a YAML document instead; that is Insomnia v5, which reads through the mapping on this page.

Parses an Insomnia "Export v4" JSON document into the Vayu draft model. Insomnia exports are a single flat array of typed resources joined by _id/parentId; the parser reconstructs the workspace → request_group → request tree and emits one root collection per workspace.

  • Source: engine/src/core/import_document.cpp
  • Exports:

The parse moved engine-side (issue #877). Every rule on this page is the same rule it always was - the corpus in engine/tests/fixtures/import-conformance.json was recorded from the parser this replaced and is asserted against on every build - it is simply read by engine/src/core/import_document.cpp now, behind POST /import/parse, rather than in the renderer. Module names in C++ style below name that file's functions; the app holds no parser.

Class formatName formatKey
InsomniaV4Parser Insomnia Export v4 insomnia-v4

Implements ImportParser (detect + parse) from ./types. meta.format is set to this.formatName ("Insomnia Export v4").

Detection

detect(parsed) => parsed._type === "export" && parsed.__export_format === 4

Both conditions must hold: the top-level object must have _type === "export" and __export_format === 4 (numeric). No other format versions are accepted by this parser.

Structure & tree reconstruction

An Insomnia v4 export has the shape { _type: "export", __export_format: 4, resources: Resource[] }. Each resource carries _id, _type, an optional parentId, and type-specific fields. There is no nesting in the JSON - hierarchy is expressed entirely through parentId references.

Reconstruction steps in parse():

  1. Index by parent. Build byParent: Map<parentId, Resource[]>, grouping every resource under its parentId (resources with no parentId use the empty-string key ""). This is the single adjacency index used for the whole tree walk.
  2. Find roots. Filter resources for _type === "workspace". Each workspace becomes one root CollectionDraft. Multiple workspaces ⇒ multiple root collections in ImportResult.collections.
  3. Recursive build. buildCollection(node, isWorkspace) walks byParent.get(node._id) and dispatches each child by _type:
  4. request_group → increments folderCount, recurses via buildCollection(child, false), pushed to children.
  5. request → buildRequest(child), pushed to requests.
  6. other handled _types (gRPC / WebSocket / spec / tests) → counted in skippedCounts (see Resource type handling).
  7. any unlisted _type (including environment) → silently ignored by the collection walk; environments are processed separately.
  8. buildRequest(r) increments requestCount and produces a RequestDraft.

Sort order is kept (issue #2573). Insomnia lists a folder's requests and sub-folders together, ascending by each resource's metaSortKey, and a recursive run visits them in that order. The walk sorts a parent's children by that key with a stable sort (ties keep resource order), folders and requests together, and each draft records its rank among the siblings that become drafts as order: 0 to k-1, never the raw key, which is sparse and often negative. The apply numbers a parent's sub-folders and requests in that one sequence, so the sidebar lists them and a recursive run visits them in Insomnia's order. A gRPC, WebSocket, spec or test resource is tallied and takes no position. A parent where any request or folder lacks a numeric metaSortKey states no order for any of its children and keeps the listing every unordered import has, folders first and requests after them, rather than guessing where the unkeyed ones sit among the keyed. A folder of sub-folders only, or an export with no keys, imports as it always did.

Key internal functions: parse (entry), buildCollection, buildRequest, insomniaAuth, insomniaBody, to_env_vars. Counters (requestCount, folderCount, authCtx.nonExec) are closures mutated during the walk.

Resource type handling

Insomnia _type Vayu outcome Notes
workspace Root CollectionDraft One per workspace. isWorkspace = true.
request_group Nested CollectionDraft (folder) Increments folderCount.
request RequestDraft Increments requestCount.
environment EnvironmentDraft (flattened) Processed in a separate pass, not in the collection walk. Gated by importEnvironments. See Environments.
grpc_request Dropped meta.skipped kind "grpc".
websocket_request Dropped meta.skipped kind "websocket".
api_spec Dropped meta.skipped kind "api_spec".
unit_test Dropped meta.skipped kind "unit_test".
unit_test_suite Dropped meta.skipped kind "unit_test" (folded into the same unit_test bucket).
anything else (e.g. cookie_jar, proto_file, request_meta, environment outside its pass) Dropped silently Not counted in meta.skipped.

Skip counting nuance. Only the five _types listed above (grpc_request, websocket_request, api_spec, unit_test, unit_test_suite) are tallied in skippedCounts by the tree walk, and only when they appear as a direct child of a workspace or request_group. A dropped resource parented under something else (or any other _type) does not increment meta.skipped. When emitting SkippedItem[], the raw keys are remapped: grpc_request → "grpc", websocket_request → "websocket", unit_test_suite → "unit_test"; unit_test and api_spec pass through unchanged. Because unit_test and unit_test_suite both map to "unit_test" but are aggregated by their raw key first, an export containing both can yield two separate SkippedItem entries with kind: "unit_test".

A sixth kind, file_body, does not come from a resource _type at all: it counts binary bodies, each imported as a file reference to relink rather than dropped (see Body mapping), and is appended once, after the walk, when the count is non-zero.

Field mapping

Collection (workspace / request_group)

Both build through buildCollection. Differences are gated by isWorkspace.

Insomnia field Vayu CollectionDraft field Notes
name name Falls back to "Imported".
description description Falls back to "".
environment (object, workspace only) variables toEnvVars(node.environment ?? {}) for workspaces; request_groups always get variables: {} (their inline environment, if any, is not read).
authentication auth Mapped via insomniaAuth. Collections may not be inherit: a resulting inherit is coerced to { mode: "none" }.
preRequestScript / afterResponseScript preRequestScript / postRequestScript Only if opts.importScripts; else "". Folder-level scripts are a real Insomnia 9.3+ feature, and its v4 export writes model fields verbatim, so these are the same key names the request path reads. The names are not pinned by a live 9.x export in this repo - an export that spells them differently reads as absent, i.e. the empty strings this parser produced before.
(reconstructed children) children / requests Built from byParent.

Request

Built by buildRequest.

Insomnia field Vayu RequestDraft field Notes
name name Falls back to "Untitled".
description description Falls back to "".
method method Upper-cased; restricted to GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS, otherwise defaults to GET.
url url normalize_template_vars(as_string(url)) - taken verbatim, query string and all, :name path segments included (see pathParameters[] below). The parse then appends the enabled parameters[] to it (see The url/params invariant), which is what Insomnia itself does with its two query sources on send: a URL written https://x/y?a=1 beside a b=2 parameter stores as https://x/y?a=1&b=2.
parameters[] ({name,value,disabled,description}) params map_key_values: name → key, disabled !== true → enabled. A string description is forwarded (any other type is ignored). Rows without a key are dropped. Enabled rows also join the url, per the row above.
pathParameters[] ({name,value}) params rows with "in": "path" Insomnia keeps these per request and writes each into its /:name segment at send time (applyPathParametersToUrl), which is the model a Vayu path row is (issue #1764, the same mapping Postman's url.variable[] gets - see the Postman doc, "Path variables"): each entry becomes a path row after the query rows, name → key, and a :name the URL spells that no entry declares gets no stored row - the Params tab shows an empty one for it until it is edited, so an export does not invent a parameter the source never declared. Nothing is promoted to a collection variable and nothing is counted. One divergence: Insomnia's segment rule (/\/:[^/?#:]+/) lets a name hold a ., while Vayu composes with Postman's rule, where the name stops at the first . - a :file.json parameter named file.json is sent literally.
headers[] ({name,value,disabled,description}) headers Same mapping as params.
settingFollowRedirects ("global" \| "on" \| "off") followRedirects "off" → false, "on" → true; "global" (Insomnia's default, meaning "use the app setting", which follows redirects) and an absent field leave the draft field absent, so the engine default (true) applies. Insomnia has no per-request redirect limit, so maxRedirects is never imported.
settingSendCookies, settingStoreCookies (booleans, both on by default) disableCookies Either one explicitly false sets disableCookies: true. Vayu has a single flag that keeps the request away from the cookie jar in both directions (it neither sends the jar's cookies nor stores the response's), so there is no way to keep one half: switching off either in Insomnia switches off the jar interaction for the request. Absent, true and a non-boolean leave the field absent, so the engine default applies.
body body Via insomniaBody. See Body mapping.
authentication auth Via insomniaAuth. See Auth mapping.
preRequestScript preRequestScript Only if opts.importScripts; else "".
afterResponseScript postRequestScript Only if opts.importScripts; else "". Note the source field is afterResponseScript.
_id - Not propagated to the draft id; used only for tree reconstruction.

map_key_values runs normalize_template_vars over every value and preserves duplicate keys and order.

Template normalization

All variable-bearing strings are run through normalize_template_vars (path_template.cpp). It converts foreign template syntax to Vayu's {{var}} form:

  • {{ x }} and {{ _.x }} (identifier only, whitespace tolerant) → {{x}}. The leading _. namespace Insomnia uses is stripped.
  • Single-brace {x} is left alone here. The rewrite exists for OpenAPI path templates and is opt-in per format (normalize_path_templates(path)); Insomnia templates with {{x}} only, so {x} is literal text.
  • Left verbatim: Nunjucks tags {% ... %} and filtered expressions {{ x | filter }}. The simple-var regex requires an identifier-only body ([\w.$-]+), so a | filter never matches and is passed through unchanged. Vayu has no equivalent, so these remain as literal text.

Applied to: request url; every params and headers value (inside map_key_values); JSON/text/graphql body content and urlencoded/form-data field values; every auth token/username/password/key/value string, and every string inside a digest/ntlm/iam config bag (at any depth); and every environment value (inside to_env_vars).

Body mapping

insomniaBody keys off body.mimeType, stripping any ;charset=... suffix and trimming.

Insomnia body.mimeType Vayu RequestBody Notes
application/json { mode: "json", content } content = normalize_template_vars(body.text).
text/plain { mode: "text", content } content = normalize_template_vars(body.text).
application/graphql { mode: "graphql", content } content = to_graphql_envelope(normalize_template_vars(body.text)) - a bare query document is wrapped into {query}, an envelope passes through (see below). The request also gains a Content-Type.
application/xml, text/xml { mode: "xml", content } content = normalize_template_vars(body.text). The request also gains Content-Type: application/xml, and a declared one (application/soap+xml) wins - both through the same with_required_content_type rule GraphQL uses.
application/x-www-form-urlencoded { mode: "x-www-form-urlencoded", fields } body.params[] → map_key_values (name → key, disabled honored).
multipart/form-data { mode: "form-data", fields } body.params[] through map_key_values, except that a type: "file" param becomes a file row: Insomnia keeps the path in param.fileName, which becomes src (and its basename the declared fileName), a path from the exporting machine, which the parse answer marks unresolved unless this machine already allows it. A file param naming no path becomes a file row with src: "" (no file chosen), counted in meta.unattachedFileParts.
anything else carrying text (application/yaml, text/csv, Insomnia's "Other") { mode: "text", content } content = normalize_template_vars(body.text). Reserved for a non-empty string body.text; the sibling Postman parser's postman_raw_body() fallback behaves the same way. No JSON sniffing happens here - Insomnia states the mime.
anything else with no text (binary: body.fileName set) { mode: "binary", file: { src, fileName, contentType } } src is body.fileName (the path on the exporting machine), fileName its base name, contentType the declared mimeType. Counted as file_body in meta.skipped: a file reference to relink, not a loss.
missing or empty body { mode: "none" } Nothing was lost, so nothing is counted.

GraphQL bodies (to_graphql_envelope in import_document.cpp): Insomnia writes application/graphql for both shapes its editor produces - the GraphQL-over-HTTP envelope ({query, variables}) and, for a hand-written or older request, the bare query document. A bare document stored verbatim went on the wire as the whole HTTP body: not JSON, so a GraphQL server reads no query at all. Nothing showed it, because the query pane's raw-string fallback renders a bare document exactly as it renders a healthy one. It is normalized at import - the one place the shape is known to be GraphQL - and an envelope is returned untouched, so a mislabelled JSON envelope is never double-wrapped.

GraphQL Content-Type (with_required_content_type in import_document.cpp): the envelope is JSON, so the request needs Content-Type: application/json; the request builder adds it only on an interactive mode switch, which an import never performs. Written at import by the engine's port of the mode picker's contentTypeToAdd rule, so a Content-Type the export declares wins and a disabled row does not count as declaring one.

Auth mapping

insomniaAuth(authentication, ctx):

Insomnia authentication.type Vayu RequestAuth Counted?
(absent / no type) { mode: "inherit" } no
inherit (Insomnia's own "Inherit from parent") { mode: "inherit" } no
any type with disabled === true { mode: "none" } no
bearer (no prefix, or a prefix that is Bearer in any case) { mode: "bearer", token } no
bearer with another prefix (e.g. Token, JWT) { mode: "apikey", key: "Authorization", value: "<prefix> <token>", in: "header" } no
basic { mode: "basic", username, password } no
apikey { mode: "apikey", key, value, in } - in is "query" when addTo === "queryParams", else "header" no
apikey with addTo === "cookie" { mode: "none" } and a Cookie: key=value header row on the request (a folder: noauth, the workspace: none, no header row) - see the notes below request: apikey_cookie_header; request with no key name, folder or workspace: security_unmapped_apikey_cookie
oauth2 { mode: "oauth2", config: OAuth2Config } via map_insomnia_oauth2 - executable no
digest { mode: "digest", config } yes
ntlm { mode: "ntlm", config } yes
hawk { mode: "hawk", config } yes
oauth1 { mode: "oauth1", config } yes
iam { mode: "aws", config } - Insomnia names AWS IAM "iam"; Vayu stores it as the aws config bag yes
any other type (asap, netrc, a type that is not a string) { mode: "none" } - never inherit, which would send the parent's credentials in place of the ones chosen (on a folder, noauth: see the notes below) unsupported_auth

Notes:

  • Bearer PREFIX. Insomnia sends Authorization: <prefix> <token>, defaulting an empty PREFIX to Bearer. Vayu's bearer mode always writes Bearer, so a different scheme is preserved as an explicit Authorization header through the apikey mode - the engine writes an apikey header value verbatim, so the wire bytes match what Insomnia sent. A prefix differing only in case (bearer) keeps the native bearer mode: HTTP auth schemes are case-insensitive (RFC 7235 §2.1). The prefix itself goes through normalize_template_vars and the composed value is trimmed, so an empty token yields just the scheme.
  • OAuth2 tokenPrefix maps to OAuth2Config.headerPrefix (absent or empty → "Bearer"), matching map_postman_oauth2's headerPrefix. Vayu executes OAuth2, so an unread prefix would send Bearer and 401 against a server expecting another scheme.
  • disabled takes precedence over type. If authentication.disabled === true, the result is { mode: "none" } regardless of type. If authentication is missing, has no type or has the type inherit (and is not disabled), the result is { mode: "inherit" }.
  • A cookie-placed API key has no slot in Vayu's API-key mode (header and query only). On a request it becomes a Cookie: key=value header row after the request's own headers, with templates normalised like any header; an enabled Cookie row the request already has takes it as a further cookie (theme=dark; key=value) rather than a second header, and a disabled one is left alone. A key with no name has no cookie to write, so it adds nothing: the request is counted and named under security_unmapped_apikey_cookie rather than dropped silently. A folder or workspace has no header row to hold it, so its cookie key is not imported: it is counted as security_unmapped_apikey_cookie (unnamed), the same advice as the OpenAPI kind - add the Cookie header by hand. The kind therefore means "an API key placed in a cookie that Vayu could not carry", whichever of a request, folder or workspace declared it.
  • oauth2 is mapped to an executable OAuth2Config (map_insomnia_oauth2) and does not count. digest/ntlm/hawk/oauth1/iam are stored as opaque config bags (the auth object with type and disabled removed, every string inside it - nested members and array elements included - run through normalize_template_vars) and are not executed by Vayu - a request whose resolved auth is one of them counts toward meta.nonExecutableAuth (see below).
  • The same mapping is used for collection-level auth (workspace/request_group; insomnia_collection_auth). For collections, an inherit result is coerced to { mode: "none" } (collections can never inherit), which the send-time walk passes through. A folder whose authentication is an explicit { type: "none" } (Insomnia's No Authentication, not disabled) maps to { mode: "noauth" } instead: the walk ends there, so a request set to inherit under it sends without auth rather than taking an outer folder's. A folder whose auth Vayu cannot carry is noauth too, for the same reason: a type with no Vayu mode (asap, netrc, counted as unsupported_auth) or a cookie-placed API key (counted as security_unmapped_apikey_cookie) would otherwise be transparent, and the requests under it would silently send an outer folder's or the workspace's credentials in place of the ones the user chose. An absent, empty, inherit or disabled folder auth stays none (transparent), and the workspace's stays none in every case because nothing sits above it.
  • nonExecutableAuth counts requests, not declarations (#2610), the way Postman does since #2537. After the tree is built one pass over the drafts (find_data_only_auth, shared with Postman) resolves each request's auth: its own mode, or for inherit the nearest ancestor's concrete mode (none transparent, noauth terminal). A request whose resolved mode is aws (from iam), digest, ntlm, hawk or oauth1 counts and is named in meta.nonExecutableAuthRequests, in document order (the folders-first listing when the siblings have no metaSortKey). Folders that declare such an auth themselves are named in meta.nonExecutableAuthFolders and a workspace that declares one in meta.nonExecutableAuthCollection (the first such workspace when an export holds several); neither is counted, each member is absent when empty. A request set to No Authentication under an iam folder is not counted; one inheriting through it is.

Environments

Environments are imported only when opts.importEnvironments is true. They are reconstructed and flattened per workspace:

  1. Base environments: environment resources whose parentId is the workspace _id.
  2. Sub-environments: environment resources whose parentId is a base environment _id.

Flattening per base:

  • No sub-envs: emit one EnvironmentDraft from the base's data. Name = base.name ?? workspace.name ?? "Environment".
  • Has sub-envs: emit one EnvironmentDraft per sub-env, with variables { ...baseVars, ...subVars } (sub-env values override base on key collision). Name = sub.name ?? "Environment". The standalone base environment is not emitted when sub-envs exist - its values survive only merged into each sub-env.

Each variable is produced by to_env_vars: keys come straight from the env data object; values are normalize_template_vars(as_string(v)) (arrays and empty objects are JSON-stringified, numbers/booleans coerced to strings), and every variable is { value, enabled: true }. A non-empty object is a namespace, not a value: { "a": { "b": 1 } } becomes the variable a.b (any depth), because {{ _.a.b }} is rewritten to {{a.b}} and the composer looks up that whole name; a sub-environment's { "a": { "b": 2 } } overrides a.b in place and leaves the base's other a.* keys. The same flattening applies to a workspace's own environment data. secret is never set. meta.environmentCount equals the number of emitted EnvironmentDrafts.

Options & lossy behavior

ImportOptions:

  • importScripts - when false, every preRequestScript/postRequestScript is forced to "". When true, they come from preRequestScript and afterResponseScript, on requests and on workspaces/request_groups (see the caveat in the collection field table). A script is stored as written, so one that calls the Insomnia scripting API throws when it runs (Vayu defines pm.*, not insomnia.*): with the option on, each request, folder or workspace whose non-blank script uses insomnia (comments, strings, a property of that name and a script's own variable of that name excluded) is counted once as script_unsupported_insomnia and named. The Postman API notice (meta.unsupportedScriptApis) is not produced for Insomnia.
  • importEnvironments - when false, the entire environment pass is skipped; environments is [] and environmentCount is 0. Workspace-level environment data still populates the root collection's variables independently of this flag.

Lossy / dropped, summary:

  • gRPC, WebSocket, API spec, unit test, and unit-test-suite resources are dropped and counted in meta.skipped (only when encountered as direct children of a workspace/request_group during the tree walk; see counting nuance above).
  • Binary bodies import as binary bodies naming the file, unresolved, and are counted as file_body; a file param with a path imports as an unresolved file row, and one with no path as a file row with no file chosen. An unresolved path is sent only once the file is chosen again in the request, or lies under a folder allowed in Settings > Files.
  • Non-executable auth types (digest, ntlm, hawk, oauth1, iam→aws) are stored but not run; every request whose resolved auth (its own, or inherited from a folder or the workspace) is one increments meta.nonExecutableAuth. oauth2 is executable and excluded.
  • Nunjucks tags and filtered template expressions are preserved as literal text.
  • request_group inline environments and resource _ids are not carried into the draft model.
  • No per-request redirect limit is imported (Insomnia keeps that as an app-wide setting), and no setting* field is read other than settingFollowRedirects, settingSendCookies and settingStoreCookies - URL encoding and timeline size have no Vayu equivalent.

meta: { format: "Insomnia Export v4", requestCount, folderCount, environmentCount, globalCount: 0, skipped, nonExecutableAuth, nonExecutableAuthRequests?, nonExecutableAuthFolders?, nonExecutableAuthCollection? } (no fileName set by the parser itself; globals is always {} - Insomnia has no globals scope).

Malformed exports

Insomnia itself only emits arrays and string mime types, so the shapes below mean a hand-edited or script-mangled file. Each throws Error("Malformed Insomnia export: <detail>"), which ImportModal shows verbatim - previously they surfaced as a raw TypeError ("Cannot read properties of undefined (reading 'map')") or, for a cycle, a RangeError. Nothing is persisted either way: the parse happens before any write.

Input Detail
resources present but not an array `resources` must be an array
a resources entry that is not an object (e.g. null) `resources[<i>]` must be an object
a request's parameters / headers present but not an array request "<name>": \parameters` must be an array`
body.params present but not an array `body.params` must be an array
body present but not an object a request `body` must be an object
body.mimeType present but not a string `body.mimeType` must be a string
a parentId loop (only reachable via a duplicated _id) resource "<id>" appears twice in the folder tree

An absent field is not an error anywhere in that table - only a present-but-wrong shape is.

Shared helpers used

Helper Source Used for
as_string import_document.cpp Coerce any scalar/object to its string form (objects → JSON.stringify).
map_key_values import_document.cpp Map {name,value,disabled} arrays → KeyValueEntry[] (filters keyless rows, normalizes values, derives enabled from disabled).
normalize_template_vars path_template.cpp Template syntax normalization (see Template normalization).

See ./README.md for the full shared-helper reference.