Insomnia API Client — User Guide

Insomnia is an open-source, cross-platform API client for designing, debugging, testing, and mocking APIs. With a single desktop application you can send requests over REST, GraphQL, WebSockets, Server-Sent Events (SSE), gRPC, and Socket.IO, design APIs against the OpenAPI specification, organize work into collections, run collections and test suites, and ship the same workflows into CI/CD with the companion inso command-line tool.

This guide is written for people who use Insomnia: developers debugging an API, QA engineers building test suites, API designers writing OpenAPI specs, and platform teams wiring Insomnia into a pipeline. It covers the desktop app and the inso CLI end to end — every protocol, every storage mode, the scripting API, and the troubleshooting you will actually hit.

Note

Insomnia is built by Kong and is licensed under Apache-2.0. The desktop app is free to use without an account through the local Scratch Pad, and most everyday features are available on the free plan. Some collaboration features (organizations, Git Sync, SSO) require an account or a paid subscription. This guide notes where an account is required.

1. Quick Start

This section gets you from a fresh install to your first successful request in a few minutes.

1.1 Install and launch

1. Download Insomnia for macOS, Windows, or Linux from insomnia.rest.
2. Install and launch the app.
3. On first launch you can either log in / create a free account or click Use the local Scratch Pad to start immediately with no account.

Tip

Choose Scratch Pad if you just want to try the app or work entirely offline. Everything you do in the Scratch Pad is stored locally and never leaves your machine. You can sign in later without losing your work.

1.2 Send your first request

1. Create a Collection (the container for related requests).
2. Click + and choose HTTP Request.
3. In the URL bar, pick the method (GET) and type a URL, for example https://httpbin.org/get.
4. Press Send (or Ctrl/Cmd + Enter).
5. The response appears in the right-hand pane: status code, time, size, headers, and a formatted body.

200 OK · 142 ms · 318 B
{
  "args": {},
  "headers": { "Host": "httpbin.org", ... },
  "url": "https://httpbin.org/get"
}

Tip

The URL bar accepts a full curl command or a raw URL with query parameters — paste either and Insomnia parses it into a request.

1.3 The three things to learn next

2. Installation and Requirements

2.1 Desktop application

Insomnia ships as a packaged desktop application for the three major platforms. Install it the same way you install any other desktop app for your OS (drag to Applications on macOS, run the installer on Windows, use the AppImage/.deb/.rpm on Linux).

Note

Insomnia uses the native libcurl library to make HTTP requests. This is what gives it deep control over TLS, redirects, proxies, and HTTP versions — but it also means the desktop app, not a browser engine, is doing the networking.

2.2 The inso CLI

inso is a standalone command-line companion that runs your Insomnia collections, tests, and linting outside the desktop app (typically in CI). It is distributed as:

• a self-contained binary (no Node.js required to run it), and
• an npm-installable package for Node environments.

npx (no install)

npx insomnia-inso --version

Global npm install

npm install -g insomnia-inso
inso --version

Standalone binary

# Download the binary for your platform, then:
./inso --version

Important

inso reads the same data your desktop app uses. It can locate your locally installed Insomnia data automatically, or you can point it at a Git project folder or an exported .yaml/.db.json file with -w, --workingDir. See §8.

2.3 System notes

• Large responses (~20 MB and above) can be memory-heavy and may slow or crash the app on low-RAM machines. Prefer downloading large response bodies to a file.
• Insomnia checks for updates automatically by default; you can change or disable this in Preferences (see §9.4).

3. Projects, Collections, and Storage

Insomnia organizes your work in a hierarchy. Understanding it is the key to everything else.

Organization                (a workspace for you or your team — requires an account for teams)
└── Project                 (a storage-scoped grouping)
    ├── Collection           (a set of requests + folders, for debugging/testing)
    └── Design Document       (an OpenAPI spec + its generated request collection)

• A Request is a single call (HTTP, GraphQL, gRPC, WebSocket, SSE, Socket.IO).
• A Folder (request group) nests requests and can carry its own environment, auth, and scripts that child requests inherit.
• A Collection is the top-level container you send and run.
• A Design Document holds an OpenAPI specification you author, lint, and preview.

3.1 Storage backends

Every project chooses how its data is stored. This is one of Insomnia's defining features — you decide per project whether data ever touches the cloud.

Tip

You can mix backends across projects. Keep a sensitive project Local Vault or Git Sync while collaborating on others via Cloud Sync — there is no all-or-nothing choice.

Important

Private Environments: regardless of the storage backend you pick, you can mark an environment as private so its configuration is always stored locally and never synced to the cloud. Use this for secrets you never want to leave your machine.

3.2 The Scratch Pad

The Scratch Pad is a special always-local workspace available without an account. It is the fastest way to start and the right choice when you cannot send data to any cloud. You can export from the Scratch Pad at any time.

Warning

Some users have reported that exporting the Scratch Pad to a YAML file can produce an empty file in certain builds (community issue #9509). If an export looks empty, see §11 Troubleshooting.

4. Environments and Variables

Environments make requests portable: instead of hard-coding https://api.example.com and a bearer token in every request, you store them once and reference them with template tags.

4.1 Environment levels

Insomnia resolves variables from several scopes, from broadest to narrowest:

Switch the active sub-environment with the environment picker in the sidebar, or with the keyboard shortcut for Switch environment menu.

4.2 Using variables

Reference any variable with the double-brace template syntax:

{{ _.base_url }}/users/{{ _.user_id }}

Type {{ in any URL, header, query, or body field (these fields are full editors) and Insomnia autocompletes available variables.

Tip

Insomnia's template engine is Nunjucks-based. Beyond plain variables, it supports template tags — dynamic values like timestamps, UUIDs, base64/hashing, prompts, and response tags that pull a value out of another request's response. Turn on Nunjucks power-user mode in Preferences to edit raw template syntax.

4.3 The Vault (encrypted secrets)

For secrets you do not want stored in plain text, use the Vault. The Vault is protected by a Vault Key:

• Create a vault key the first time you store a secret.
• The key can be saved locally and (optionally) in your OS secret manager so you do not retype it.
• You can reset, re-validate, or clear the vault key from the app.

Caution

By default, vault secrets are not exposed to pre-request/after-response scripts. To read vault values from scripts you must explicitly enable enableVaultInScripts in Preferences. Leave it off unless a script genuinely needs a secret.

5. Building and Sending Requests

This is the core of the Debug screen. Insomnia supports many protocols; each has a tailored editor.

5.1 HTTP / REST requests

For a standard HTTP request you control:

• Method and URL — including query parameters (edit them inline or in the Query tab; a bulk editor is available).
• Body — choose a body type: JSON, XML, form URL-encoded, multipart form, GraphQL, raw text, binary file, or none. The editor formats and lints JSON/XML/GraphQL.
• Headers — add headers individually or with the bulk header editor. Default headers can be applied automatically.
• Authentication — see §6.
• Docs — a Markdown description tab for documenting the request.
• Scripts — pre-request and after-response scripts (see §10).
• Settings — per-request overrides such as following redirects, SSL validation, and timeout.

Send with Send or Ctrl/Cmd + Enter. The response pane shows the body (with preview modes for HTML, JSON, images, and PDFs), headers, cookies, the timeline (the raw libcurl exchange), and timing.

Tip

Every URL/header/body field is a CodeMirror editor, so you get syntax highlighting, autocompletion of variables and template tags, and inline linting. The downside: very large fields and responses are heavier than plain text inputs.

5.2 Response history and previews

Insomnia keeps a response history per request (default: the last 20 responses, configurable via maxHistoryResponses). You can:

• re-open any past response,
• preview as raw, pretty, HTML, or image,
• save the response body to a file,
• delete a single response or clear all history for a request.

Warning

"Save to File" has been reported to create an empty file in some cases (community issue #9879). If you hit this, try saving from the raw preview, or export the response another way.

5.3 GraphQL requests

Choose GraphQL as the body type to get:

• a GraphQL query editor with schema-aware autocompletion,
• a variables editor,
• the built-in GraphQL Explorer for browsing the schema,
• automatic schema introspection from the endpoint.

5.4 gRPC requests

Create a gRPC Request to call gRPC services:

• import a .proto file or a proto directory, or use server reflection to discover methods,
• pick a method from the method dropdown,
• send unary, server-streaming, client-streaming, and bidirectional-streaming calls,
• edit request messages as JSON.

5.5 WebSocket requests

Create a WebSocket Request to open a persistent connection:

• connect to a ws:// or wss:// URL,
• send messages (text/JSON/binary) interactively,
• view the live event stream of sent and received messages,
• attach headers and authentication to the handshake.

Note

Path parameters and variables are applied to most request types, but a known issue (#9947) reports they may not be applied in WebSocket connections — substitute values manually if a {{ }} tag does not resolve in a WebSocket URL.

5.6 Server-Sent Events (SSE) and Socket.IO

• SSE: open an event-stream endpoint and watch events arrive in real time.
• Socket.IO: connect to a Socket.IO server, emit events, and subscribe to channels.

5.7 Cookies

Each workspace has a Cookie Jar. Insomnia stores cookies returned by responses and sends them automatically on subsequent matching requests. You can view, add, edit, and delete cookies in the cookie manager.

6. Authentication

Insomnia supports a broad set of auth schemes on the Auth tab of a request (or inherited from a parent folder/collection). Configure once on a folder and child requests inherit it.

Tip

OAuth 2.0 token state is stored per request. If you want a clean token on every app start, keep clearOAuth2SessionOnRestart enabled (it is on by default).

6.1 Client and CA certificates

Per workspace you can configure:

• Client certificates (mutual TLS): attach a PEM/PFX certificate + key, scoped to a host.
• CA certificates: provide a custom CA bundle so Insomnia trusts an internal/self-signed authority.

Note

Authenticating with a company CA certificate has tripped some users up (community issue #10024). Make sure the certificate host matches the request host and that the CA is added at the workspace level. See §11.

7. Running Collections and Tests

Insomnia can execute many requests at once, both interactively (the Collection Runner) and as automated unit tests.

7.1 The Collection Runner

Open the Runner from a collection to:

• select which requests (or folders) to run and in what order,
• set an iteration count to repeat the run,
• supply iteration data (a JSON or CSV file) so each iteration uses different values — true data-driven testing,
• add a delay between requests,
• choose the active environment,
• view per-request results, test outcomes, and timing.

Tip

Iteration data columns become variables for that iteration. A CSV with a user_id header lets {{ _.user_id }} resolve to a different value on each pass.

7.2 Unit test suites

The Test screen lets you write test suites containing JavaScript tests that send requests and assert on the responses using a Chai-style expect API. You can:

• create multiple test suites per collection,
• write tests that call a request by name/ID and assert on status, headers, body, and timing,
• run a single test, a suite, or all suites,
• view pass/fail results with execution time.

// Inside a unit test
const response = await insomnia.send();
expect(response.status).to.equal(200);
expect(response.headers.get('content-type')).to.match(/json/);

7.3 Mock servers

Insomnia can mock an API for you. Create a Mock Server (cloud-hosted or self-hosted) and define mock routes that return canned responses. You can generate a request collection that targets the mock, so consumers can develop against the API before the backend exists.

8. Designing APIs (OpenAPI)

A Design Document is a first-class OpenAPI editor.

• Author your spec in the native OpenAPI editor with autocompletion.
• See a visual preview of the API as you type.
• Lint the spec against rules using Spectral (the same engine inso lint uses). Errors and warnings appear inline.
• Provide a custom ruleset (.spectral.yaml) to enforce your organization's API standards.
• Generate a request collection directly from the spec so you can immediately exercise the endpoints you designed.

Tip

Designing and debugging live in the same project. Generate a collection from your spec, debug against a mock or a real server, and keep the spec as the source of truth.

9. Preferences and Settings

Open Preferences (gear icon, or the Show general preferences shortcut). Settings apply app-wide. The most useful ones:

9.1 Request behavior

9.2 Proxy

9.3 Editor and appearance

9.4 Updates

9.5 Privacy and security

Tip

To work fully offline and privately, set storage to Local Vault, disable enableAnalytics, and disable updateAutomatically.

9.6 Keyboard shortcuts

Every shortcut is rebindable under Preferences → Keyboard. Frequently used defaults:

10. Scripting

Insomnia lets you run JavaScript before a request (pre-request) and after a response (after-response). Scripts get a rich insomnia object for reading and mutating the request, environment, and response.

10.1 Where scripts run

• Pre-request script: runs before the request is sent. Use it to set headers, compute signatures, or fetch a token.
• After-response script: runs once the response arrives. Use it to extract values, set variables, or assert in tests.

Scripts run in a sandbox (scriptSandboxEnabled) under strict mode (scriptStrictModeEnabled) by default.

10.2 The insomnia object

The scripting API is exposed as insomnia. Core members:

Each variable scope supports has(), get(), set(), unset(), clear(), replaceIn(), and toObject().

// Pre-request: add a timestamp header
insomnia.request.addHeader({ key: 'X-Timestamp', value: String(Date.now()) });

// After-response: capture a token into the environment
const body = insomnia.response.json();
insomnia.environment.set('access_token', body.access_token);

// Assert in a test
insomnia.test('status is 200', () => {
  insomnia.expect(insomnia.response.code).to.equal(200);
});

// Control runner flow
insomnia.execution.setNextRequest('Get Profile');

Note

The scripting object is named insomnia. Insomnia's scripting model is designed to be familiar to users of other API clients, but document and test against the insomnia.* names shown above — they are the verified surface.

10.3 Data folder access

Scripts (and the runner) can read and write files only within folders you allow. In the desktop app this is governed by your settings (dataFolders); with the CLI you pass -f, --dataFolders. This is a safety boundary — keep it narrow.

11. The inso CLI

inso runs your Insomnia collections, tests, and linting from a terminal — ideal for CI/CD. It reads the same data as the app.

11.1 How inso finds your data

inso resolves data in this order:

1. -w, --workingDir <dir> if provided — point it at an .insomnia folder, a Git project folder, a *.db.json, or an exported export.yaml.
2. Otherwise, your locally installed Insomnia data directory.

You identify what to run by an id (e.g. wrk_..., spc_..., uts_...) or, in interactive mode, by picking from a prompt. In CI use --ci to disable all prompts.

11.2 Global options

These apply to every command:

11.3 inso run collection

Run a request collection.

inso run collection -w ./my-project wrk_abc123 \
  --env production \
  --reporter spec

Caution

--includeFullData=plaintext writes request bodies, responses, and environment values (including secrets) to the report file. inso shows a security prompt unless you pass --acceptRisk. Prefer redact and never commit these reports.

11.4 inso run test

Run unit test suites.

inso run test -w ./my-project uts_abc123 --env staging --reporter min

11.5 inso lint spec

Lint an OpenAPI specification with Spectral.

# Lint a spec by id from a project
inso lint spec -w ./my-project spc_abc123

# Lint a spec file directly
inso lint spec ./openapi.yaml

# Use a custom ruleset
inso lint spec ./openapi.yaml --ruleset ./.spectral.yaml

Tip

If you do not pass --ruleset, inso looks for a .spectral.yml/.spectral.yaml next to the spec. Keep your org's ruleset in the repo so the app and CLI lint identically.

11.6 inso export spec

Export an OpenAPI specification to a file or stdout.

inso export spec spc_abc123 -w ./my-project -o ./dist/openapi.yaml --skipAnnotations

11.7 inso script and inso generate-docs

• inso script <script-name> — run a named script defined in your .insorc config file. Each script entry must itself start with inso. This lets you alias common invocations.
• inso generate-docs — print the CLI's command documentation.

11.8 The .insorc config file

inso reads a config file (default name .insorc, in YAML or JSON) from the working/current directory, or from --config. It can pre-set global options and define reusable scripts:

# .insorc.yaml
options:
  workingDir: ./my-project
  ci: true
scripts:
  lintSpec: inso lint spec spc_abc123
  exportSpec: inso export spec spc_abc123 -o ./dist/openapi.yaml

Run a script with:

inso script lintSpec

11.9 Exit codes and proxies

• inso exits 0 on success and 1 on failure (failed test, lint error, missing data) — perfect for CI gating.
• Proxy environment variables are respected automatically: HTTP_PROXY/http_proxy, HTTPS_PROXY/https_proxy, and NO_PROXY/no_proxy. Flags (--httpProxy, etc.) override them.
• Telemetry can be disabled with INSO_TELEMETRY_DISABLED=1 (or by disabling analytics in the app, which inso reads from your local settings).

11.10 CI example (GitHub Actions)

name: API checks
on: [push]
jobs:
  inso:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint the API spec
        run: npx insomnia-inso lint spec ./openapi.yaml --ruleset ./.spectral.yaml
      - name: Run the test suite
        run: npx insomnia-inso run test -w . uts_abc123 --ci --reporter min

12. Plugins

Insomnia is extensible through plugins installed from the Plugin Hub. Plugins can add template tags, request/response hooks, themes, and more.

• Install, enable, disable, and configure plugins under Preferences → Plugins.
• Reload plugins without restarting using the plugin_reload shortcut.
• Plugins are stored in your plugin path (pluginPath) and can be individually disabled via pluginConfig.

Note

Some capabilities ship as bundled first-party plugins (for example AI and external-vault integrations). These appear automatically; third-party plugins are what you install from the Hub.

13. Importing and Exporting

13.1 Import

Insomnia imports from many sources. Use Import and either scan a file or paste a URL/clipboard:

13.2 Export

Export a collection, design document, or your whole workspace to Insomnia's YAML format. You can also export an OpenAPI spec from a design document (in the app or with inso export spec).

Warning

Exports can contain secrets stored in environments. Review what you are exporting before sharing the file, and prefer Private Environments for values that must never leave your machine.

14. Syncing and Collaboration

14.1 Git Sync

Connect a project to a Git repository to version your API work with your code.

• Clone an existing repo or initialize sync on a project.
• Stage, commit, push, pull/fetch, view diffs and history, and manage branches — all from inside Insomnia.
• Authenticate with GitHub/GitLab (OAuth) or a personal access token / credentials.

Important

Git Sync stores data as files in your repository — Insomnia's cloud is not involved. This is the right choice for teams that must keep API definitions in their own version control.

14.2 Cloud Sync

For real-time collaboration, Cloud Sync stores project data in Insomnia's cloud with branch/snapshot semantics (create snapshot, pull, push, restore, rollback, merge branches). It can be end-to-end encrypted.

14.3 Known sync caveat

Warning

Clearing the local cache while using Git/Cloud sync has been reported to make collections temporarily disappear (#10003). Push/commit your work before clearing caches, and use pull/fetch to restore from the remote if collections vanish locally.

15. AI and MCP features

Recent Insomnia versions include AI-assisted and Model Context Protocol (MCP) capabilities:

• AI-generated commit messages for sync commits.
• An MCP request type and workspace MCP view, letting Insomnia act as an MCP client to language-model tooling.

These features may require an account and an enabled AI plugin. They are optional — none of the core request/test/design workflows depend on them.

16. Troubleshooting

Each entry uses the format Symptom → Cause → Solution → Prevention.

Error: Specification content not found using API spec id

• Cause: inso could not find a spec with that id in the working directory.
• Solution: Verify the id (it starts with spc_) and that -w points at the right .insomnia folder, Git project, or export file. List specs by running the command interactively (without --ci) to pick from a prompt.
• Prevention: Keep a .insorc with the correct workingDir and spec ids.

Error: No environment identified; cannot run requests without a valid environment.

• Cause: No environment was selected and inso could not infer one.
• Solution: Pass -e, --env <id-or-name>. In CI, also pass --ci and ensure the environment exists in the data.
• Prevention: Name environments consistently across stages and reference them by name in .insorc.

Error: CSV file must contain at least two rows with first row as variable names

• Cause: The --iteration-data CSV has only a header (or is empty).
• Solution: Provide a header row plus at least one data row. For JSON, supply an array of key/value objects.
• Prevention: Validate the data file before a CI run.

Error: Uploaded file is unsupported

• Cause: --iteration-data points at a file that is not .json or .csv.
• Solution: Convert the data to JSON (array of objects) or CSV.
• Prevention: Stick to JSON/CSV for runner data.

Error: Environment variable DEFAULT_APP_NAME is not set.

• Cause: inso could not determine the app data directory because DEFAULT_APP_NAME is unset in the environment.
• Solution: Run inso from a normal shell where it can resolve the Insomnia data dir, or pass -w to point at data explicitly so it does not need the default app dir.
• Prevention: Prefer -w in CI rather than relying on a locally installed app.

Symptom: "Save to File" creates an empty file

• Cause: Known issue in some builds (#9879, #9509 for Scratch Pad YAML).
• Solution: Save from the raw response preview, or export via Export / inso. Update to the latest version.
• Prevention: Track the linked issues; keep Insomnia updated.

Symptom: Cannot authenticate with a company CA certificate

• Cause: The CA is not registered at the workspace level, or the certificate host does not match the request host (#10024).
• Solution: Add the CA certificate under the workspace CA settings and confirm the host matches. For mTLS, also add the client certificate scoped to the same host.
• Prevention: Keep a documented CA/client-cert setup per environment.

Symptom: {{ }} variables not applied in WebSocket URLs

• Cause: Known issue (#9947).
• Solution: Substitute the value directly in the WebSocket URL until the fix ships.
• Prevention: Track the issue; test WebSocket URLs after editing variables.

Symptom: App is slow or crashes on a large response

• Cause: Loading very large responses (~20 MB+) is memory-heavy.
• Solution: Save the response to a file instead of previewing; close other tabs.
• Prevention: Avoid previewing multi-MB bodies; use streaming endpoints where possible.

Symptom: Collections disappear after clearing cache with sync on

• Cause: Known sync/cache interaction (#10003).
• Solution: Pull/fetch from the remote to restore. Avoid clearing caches with unsynced changes.
• Prevention: Commit/push before clearing caches.

Symptom: Linux app crashes on launch with write EPIPE

• Cause: Reported on some Linux desktop-file launches (#9951).
• Solution: Launch from a terminal to see logs; try the AppImage build; update to the latest version.
• Prevention: Track the issue; keep the app updated.

Symptom: Windows 12.6.0 won't open

• Cause: Reported startup issue (#9959).
• Solution: Reinstall, or roll back to a known-good version while the fix lands.
• Prevention: Stay on the stable update channel for production work.

17. FAQ

Q: Do I need an account to use Insomnia? No. Use the local Scratch Pad with no account. An account unlocks cloud collaboration, organizations, Git Sync, and SSO; most everyday debugging/testing works without one.

Q: Can I keep all my data off the cloud? Yes. Choose Local Vault or Git Sync storage per project, and mark sensitive environments as Private so they never sync.

Q: Which protocols does Insomnia support? REST/HTTP, GraphQL, gRPC (unary and streaming), WebSockets, Server-Sent Events, and Socket.IO.

Q: Is inso separate from the desktop app? Yes — it is a standalone CLI that reads the same data. Install it independently for CI; you do not need the desktop app on a build agent.

Q: How do I run my Insomnia tests in CI? Use inso run test (or inso run collection) with --ci and a --reporter. It exits non-zero on failure so the pipeline fails. See §11.10.

Q: How do I lint my OpenAPI spec the same way in CI and the app? Both use Spectral. Keep a .spectral.yaml ruleset in your repo; the app's design linter and inso lint spec --ruleset will agree.

Q: Where does Insomnia store my data on disk? In the OS app-data directory: ~/Library/Application Support/Insomnia (macOS), %APPDATA%\Insomnia (Windows), or $XDG_DATA_HOME/~/.config (Linux). inso uses the same location.

Q: How do I migrate from Postman? Use Import and select your Postman collection (v2) and environment exports. Insomnia maps them to collections and environments.

Q: Can scripts read my vault secrets? Only if you enable enableVaultInScripts. It is off by default for safety.

Q: How do I disable telemetry? Turn off enableAnalytics in Preferences (the CLI reads this), or set INSO_TELEMETRY_DISABLED=1 for the CLI.

Q: How do I force HTTP/2 or HTTP/1.1? Set preferredHttpVersion in Preferences, or override per request in request settings.

Q: Can I use Vim or Emacs keybindings in the editors? Yes — set editorKeyMap to vim, emacs, or sublime.

Q: My request needs a client certificate. Where do I add it? Under the workspace certificate settings: add a client certificate (mTLS) scoped to the host, and a CA certificate if the server uses an internal authority.

Q: What's the difference between the Collection Runner and unit tests? The Runner executes a sequence of requests (optionally data-driven) and shows results interactively. Unit tests are reusable assertions you write once and run repeatedly (in the app or via inso run test).