Insomnia API Testing Complete Guide 2026

Insomnia is a polished API client and design tool maintained by Kong, the API gateway company. It positions itself as the design-first alternative to Postman, with strong support for OpenAPI design documents, an extensible plugin system, and the Inso CLI for CI/CD integration. Insomnia Core remains free and works offline, while Insomnia provides paid cloud features for team collaboration. For teams that want a powerful, focused API client with first-class OpenAPI support, Insomnia is one of the strongest tools in the space.

This complete guide covers Insomnia in 2026: installation, building REST, GraphQL, and gRPC requests, organizing with collections and environments, design documents from OpenAPI, the Inso CLI for headless CI runs, custom plugins, and team sync. Real examples cover importing Postman collections, building a regression suite, and integrating with GitHub Actions. By the end you'll be ready to evaluate Insomnia and adopt it where it fits.

Key Takeaways

• Insomnia is a focused API client by Kong (free Core + paid Cloud)
• Supports REST, GraphQL, gRPC, WebSocket
• Design documents let you author OpenAPI directly in the app
• Inso CLI runs tests in CI/CD
• Plugin system for extending functionality
• Local data by default, optional cloud sync
• Strong import support from Postman, OpenAPI, Swagger

---

Installation

# Mac
brew install --cask insomnia

# Windows: download from insomnia.rest
# Linux: snap install insomnia

First Request

1. Click New Request
2. Set method (GET), URL (https://api.example.com/users/42)
3. Add headers
4. Click Send

Workspaces

Workspaces organize related work:

• Collection: Group of requests
• Design Document: OpenAPI spec
• Git Sync: Version-controlled workspace

Collections

My API/
  Auth/
    Login
    Logout
  Users/
    Get Profile
    Update Profile
  Orders/
    List
    Create
    Cancel

Environments

Define per-environment variables:

{
  "base_url": "https://api.staging.example.com",
  "api_token": "secret-token"
}

Subenvironments inherit from a base environment.

Variables In Requests

URL: {{ _.base_url }}/users/42
Header: Authorization: Bearer {{ _.api_token }}

Tests

Insomnia supports JavaScript tests in the "Tests" tab:

const response = await insomnia.send();
const body = response.body;

expect(response.status).to.equal(200);
expect(body).to.have.property('id');
expect(body.email).to.match(/.+@.+/);

Pre-Request Scripts

const response = await insomnia.send({ url: 'https://api.example.com/auth/login', method: 'POST', body: { email: 'test@example.com', password: 'secret' } });
insomnia.environment.set('token', response.body.access_token);

Chaining Requests

Use response references to extract values from previous responses:

URL: {{ _.base_url }}/users/{{ _.last_user_id }}

Where last_user_id is set in a previous request's response.

Design Documents

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Get user
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Success

Insomnia renders this spec interactively, lets you generate requests from it, and validates conformance.

GraphQL

Dedicated GraphQL tab with schema introspection:

query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}

gRPC

Insomnia supports gRPC with protobuf import:

1. Import .proto file
2. Insomnia generates request UI for each RPC
3. Send unary, server streaming, client streaming, or bidirectional requests

Inso CLI

npm install -g insomnia-inso
inso run test "My Test Suite" --env staging

Export a collection from the Insomnia UI:

inso export spec --output api.yaml

CI Integration

name: API Tests
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm install -g insomnia-inso
      - run: inso run test "Regression Suite" --env staging --reporter xunit --reporter-output results.xml
        env:
          API_TOKEN: ${{ secrets.API_TOKEN }}
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: results
          path: results.xml

Plugins

Insomnia has a Node.js plugin API:

// plugin/index.js
module.exports.templateTags = [{
  name: 'jwt',
  displayName: 'JWT',
  args: [{type: 'string', displayName: 'Secret', defaultValue: 'secret'}],
  run(context, secret) {
    const jwt = require('jsonwebtoken');
    return jwt.sign({sub: 'test'}, secret);
  },
}];

Install via plugin manager and reference in templates as {{ _.jwt('secret') }}.

Postman Migration

Import Postman collections via Application → Import Data → From File → upload v2.1 JSON.

Tests, environments, and structure transfer mostly cleanly. Some Postman-specific features need manual conversion.

Git Sync

Connect a workspace to a Git repository for version control:

1. Settings → Git Sync → Connect
2. Provide repo URL and credentials
3. Insomnia commits .insomnia/ files on each save
4. Team members pull/push via the UI

Comparison To Alternatives

Tool	Cost	Design Docs	Plugins	CLI
Insomnia	Free + paid	Yes (OpenAPI)	Yes	Inso
Postman	Free + paid	Limited	Yes	Newman
Hoppscotch	Free + paid	Limited	Limited	Yes
Bruno	Free	No	Limited	Yes

Real Test Suite

{
  "_type": "collection",
  "name": "User API",
  "requests": [
    {
      "name": "Login",
      "method": "POST",
      "url": "{{ _.base_url }}/auth/login",
      "body": {
        "mimeType": "application/json",
        "text": "{\"email\": \"{{ _.test_email }}\", \"password\": \"{{ _.test_password }}\"}"
      }
    },
    {
      "name": "Get Profile",
      "method": "GET",
      "url": "{{ _.base_url }}/me",
      "headers": [
        {"name": "Authorization", "value": "Bearer {{ _.token }}"}
      ]
    }
  ]
}

Tests for Get Profile:

const response = await insomnia.send();
expect(response.status).to.equal(200);
expect(response.body).to.have.property('id');
expect(response.body.email).to.match(/.+@.+/);

Anti-Patterns

Anti-Pattern	Better
Hardcoded credentials	Environment variables
Skipping Inso CLI	Run in CI
No design document	Maintain OpenAPI spec
One huge collection	Split by domain
Forgetting Git Sync	Track collections in git

Authentication Methods

Type	Insomnia Support
Basic Auth	Native
Bearer Token	Native
OAuth 2.0	Native (full flow)
AWS IAM	Native
Hawk	Native
Digest	Native
NTLM	Native
Custom	Headers + plugins

OAuth 2.0 Flows

Insomnia supports all standard OAuth flows:

1. Authorization Code (with PKCE)
2. Client Credentials
3. Resource Owner Password
4. Implicit (deprecated)

For Auth Code, Insomnia opens a browser for the user redirect and captures the callback automatically.

Tips

• Use Bulk Edit on environment variables
• The Generate Code feature exports requests as curl, Node, Python, etc.
• Color-code workspaces for visual identification
• Templates speed up creating similar requests
• Cookie jar persists session cookies across requests

Team Workflow

A 20-person backend team:

1. Each engineer runs Insomnia Core locally
2. Workspaces synced to a private Git repo
3. CI runs Inso CLI on every PR
4. Design documents auto-render in the team wiki
5. Plugins for custom auth (e.g., internal token mint)
6. Insomnia Cloud for cross-team API discovery (paid)

When To Choose Insomnia

• Strong OpenAPI/design-first workflow
• Need gRPC support
• Want plugins to extend tool
• Like polished, focused UI over feature bloat
• Already in Kong ecosystem

When To Choose Alternatives

• Need richest team features (Postman)
• Want fully open source + local files (Bruno)
• Need WebSocket/MQTT (Hoppscotch)
• Heavy Python/Node code preference (libraries directly)

CLI Workflows

# List collections
inso list collections

# Run a test
inso run test "Tests" --env staging

# Export OpenAPI spec
inso export spec --output api.yaml

# Lint a spec
inso lint spec

Conclusion

Insomnia is the design-first API client of choice for teams that want polished tooling without the cloud-locked feel of Postman. The combination of free Core, OpenAPI design documents, Inso CLI, plugins, and gRPC support covers a wide range of API testing scenarios. For backend teams or teams using Kong's API gateway, the integration feels natural.

Start by importing one of your existing collections and exploring the design document workflow. Add Inso to your CI for at least one critical endpoint. Within a sprint you'll know whether Insomnia fits your team's workflow. Visit our skills directory or the Postman API testing guide for comparison.