Insomnia

A feature-rich desktop API client by Kong for REST, GraphQL, gRPC, and WebSocket development. Design APIs with OpenAPI, manage environments, write unit tests, and automate collection runs with the inso CLI.

What is Insomnia?

Insomnia is a desktop API development environment maintained by Kong. It provides a clean, minimal interface for sending HTTP/REST, GraphQL, gRPC, and WebSocket requests. Beyond basic request management, Insomnia includes an OpenAPI design editor, a plugin system for custom behavior, built-in unit testing, and Git-based sync for version-controlled collaboration.

The inso CLI makes Insomnia a CI-friendly tool — you can run test suites, lint OpenAPI specs, and export design documents directly from your pipeline. Combined with Git Sync, Insomnia collections live alongside your codebase and are treated as versioned artifacts.

Key Features

• Multi-protocol requests — REST, GraphQL, gRPC, WebSocket, and Server-Sent Events
• OpenAPI design mode — write or import OpenAPI 3.x specs with live validation and request generation
• Environment management — nested environments (base + override) with template variables and process.env injection for CLI
• Unit testing — write Chai-based tests in the Test tab and run them with inso in CI
• Plugin system — extend Insomnia with request/response hooks, custom themes, and authentication helpers via npm packages
• inso CLI — run tests, lint specs, and export documents from the terminal; integrates with any CI system
• Git Sync — version-control your workspace by committing changes directly to a Git repository
• Authentication helpers — OAuth 2.0, Bearer, Basic, AWS v4, and more — with browser-based OAuth flow support

Installation

# Download Insomnia from the official site
# https://insomnia.rest/download
# Available for macOS, Windows, and Linux (.deb, .rpm, AppImage)

# Install the Insomnia CLI (inso) for CI/CD automation
npm install -g insomnia-inso

# Verify CLI installation
inso --version

Using the inso CLI

The inso CLI reads from an Insomnia workspace export file or a Git-synced workspace directory. Use it to run tests and lint specs as part of your automated pipeline.

# Run unit tests from a collection using inso CLI
inso run test "My API Tests" --env "Staging" --reporter junit

# Lint an OpenAPI specification file
inso lint spec openapi/my-api.yaml

# Export a design document to OpenAPI YAML
inso export spec "My API" --output openapi/my-api.yaml

# Run tests non-interactively in CI
inso run test "Regression Suite"   --env "CI Environment"   --ci   --reporter junit   --output results/junit.xml

Environment Variables

Insomnia uses a template syntax with double curly braces {{ variable }} to reference environment values anywhere in a request — URL, headers, body, or auth fields.

// Insomnia environment — stored per workspace
// Switch environments via the dropdown in the top bar

{
  "base_url": "https://api.example.com",
  "api_key": "{{ process.env.API_KEY }}",   // injects from process env in inso CLI
  "user_id": 42,
  "timeout": 5000
}

// Reference in request URL:
// GET {{ base_url }}/users/{{ user_id }}

// Reference in headers:
// Authorization: Bearer {{ api_key }}

Writing Unit Tests

Open any request, click the Test tab, and write Chai-style assertions. Tests run in the app UI or via inso run test in CI. Group related tests under named test suites for organized reporting.

// Insomnia unit test — written in the Test tab of a request
const response = await insomnia.send();

expect(response.status).to.equal(200);
expect(response.headers['content-type']).to.include('application/json');

const body = JSON.parse(response.body);
expect(body).to.have.property('id');
expect(body.id).to.be.a('number');
expect(body.name).to.be.a('string').with.length.above(0);

Plugin System

Install plugins from npm (insomnia-plugin-*) via Preferences or build your own. Plugins can add request/response lifecycle hooks, custom auth methods, and new themes.

// insomnia-plugin-add-timestamp/index.js
// A simple Insomnia plugin that injects a request timestamp header

module.exports.requestHooks = [
  async (context) => {
    context.request.setHeader(
      'X-Request-Time',
      new Date().toISOString()
    );
  }
];

// package.json for the plugin
{
  "name": "insomnia-plugin-add-timestamp",
  "version": "1.0.0",
  "insomnia": {
    "name": "Add Timestamp Header",
    "description": "Injects X-Request-Time on every request"
  }
}

Insomnia vs Postman

Pros and Cons