Insomnia is an API client built by Kong for sending requests and inspecting responses. It is known for a clean, distraction-free interface and support for HTTP, REST, GraphQL, gRPC, SOAP, and WebSocket in one place. Developers reach for it when they want something lighter than a heavy IDE-style tool but still capable of real testing work.
This guide shows how to test an API in Insomnia from start to finish. You will create a request collection, send and inspect a response, set up environments so you can switch base URLs and tokens, and use the test suites feature to write assertions that run automatically. The examples use a public API so you can follow along immediately.
Install Insomnia and create a request
Download Insomnia from the official Kong site and install it for your platform. On first launch, Insomnia asks whether you want to sign in. You can choose to work locally without an account if you prefer, and Insomnia stores your data on your own machine. Cloud sync is optional and is what changed in version 8, which we cover below.
Insomnia organizes work into collections and documents. Click Create in the dashboard and choose Request Collection. Give it a clear name like “User API tests.” Inside the collection, click the + button and choose HTTP Request.
A request needs a method and a URL. Pick GET and enter a real endpoint. The JSONPlaceholder service works well for practice:
GET https://jsonplaceholder.typicode.com/users/1
Click Send. The right pane shows the response body, the status code, the response time, and the size. Insomnia pretty-prints JSON automatically and lets you filter the body with a JSONPath or XPath query, which is handy when a response is large.
Configure methods, parameters, and authentication
For anything beyond a simple read, you will set more on the request. Insomnia groups these under tabs below the URL bar.
The Body tab handles request payloads. For a POST, pick JSON and enter the data:
{
"name": "Daniel Okafor",
"email": "daniel.okafor@example.com"
}
Insomnia sets the Content-Type header for you when you choose a body type. The Query tab lets you add query string parameters without editing the URL by hand, which keeps a long URL readable and lets you toggle individual parameters on and off. The Headers tab is for anything else the API expects, such as a custom X-Request-Id or an Accept header to negotiate the response format.
The Auth tab handles credentials. Insomnia supports a long list of schemes: Bearer Token, Basic Auth, API Key, OAuth 1.0 and 2.0, AWS IAM, and others. Pick the scheme your API uses and fill in the fields. For a token-protected API, choose Bearer Token and paste the token, or better, reference an environment variable so the token is not hardcoded. If you are unsure which status codes to expect back, the reference on HTTP status codes REST APIs should use is a good companion.
Set up environments and variables
Environments let you avoid repeating values and make it easy to switch targets. In Insomnia, an environment is a JSON object of variables attached to a collection.
Click the environment dropdown near the top of the sidebar and open Manage Environments. The Base Environment holds shared values. Add sub-environments for each target:
{
"base_url": "https://jsonplaceholder.typicode.com",
"auth_token": "your-token-here"
}
Create a second sub-environment for production with different values. Reference a variable in any request with the template syntax {{ _.base_url }}, so a URL becomes:
GET {{ _.base_url }}/users/1
Switch the active environment from the dropdown and every request that uses the variable updates. Insomnia also supports template tags, small functions you can drop into a field to generate a timestamp, a UUID, or to pull a value from a previous response. That last one lets you chain requests, for example capturing a token from a login response and feeding it into later requests.
The response template tag is worth a closer look because it is how Insomnia handles request dependencies without scripting. You add a tag that says “use the body of the login request, at the JSONPath $.token,” and drop it into the Authorization header of every protected request. When you run a protected request, Insomnia runs the login request first if needed, extracts the token, and substitutes it. The chain stays declarative, so there is no glue code to maintain. For the wider idea of grouping related checks, see the API test case example walkthrough.
Write test suites with assertions
Sending a request shows you the response. To check the response is correct, automatically, you use Insomnia’s test suites feature, sometimes shown as the Unit Tests tab on a collection.
Open your collection and switch to the Tests view. Create a test suite, then add individual tests inside it. Each test is a small piece of JavaScript. Insomnia uses the Chai assertion library and gives you a helper to send a request and grab its response. A test looks like this:
const response = await insomnia.send();
expect(response.status).to.equal(200);
You can be more specific by parsing the body and checking fields:
const response = await insomnia.send();
const body = JSON.parse(response.data);
expect(response.status).to.equal(200);
expect(body.email).to.equal("daniel.okafor@example.com");
expect(body).to.have.property("id");
Each test in the suite targets a request from your collection, picked from a dropdown, so the test knows what to send. Click Run Tests and Insomnia executes every test in the suite, showing each one as passed or failed with the time it took. This is your regression check: run the suite after a change and you immediately see whether the API still behaves.
How you organize suites matters as the count grows. A common pattern is one suite per resource, so all the article tests sit together and all the user tests sit together. Inside a suite, keep each test focused on a single behavior: one test for the happy path, separate tests for the not-found case and the validation-error case. When a test fails, its name and its narrow scope should tell you what broke without you having to read the assertion code. For a deeper look at writing good checks, the guide on API assertions explains what to assert and what to skip, and the test suites for API test automation article covers structuring suites as they grow.
Run from the command line with Inso
A GUI is fine for development, but automation needs something headless. Insomnia ships a command line companion called Inso. After exporting or syncing your collection, you run your test suite from a terminal:
inso run test "User API tests"
Inso exits with a non-zero status code if any test fails, which is exactly what a CI pipeline needs to mark a build as broken. You can wire this into GitHub Actions or any other runner so your Insomnia tests execute on every push, catching a broken endpoint before it reaches a teammate or production. Inso can also lint your API specification and generate test reports in standard formats, which makes it useful beyond just running suites. The article on automating API tests in CI/CD shows the general pattern, which applies cleanly to Inso.
The version 8 cloud change, and an alternative
Insomnia 8 moved toward a cloud-first model. By default it pushed users to create a Kong account and store projects in the cloud. That decision frustrated part of the community, since earlier versions had been fully local and offline-friendly. Later releases restored a clearer local-only or “Scratch Pad” option, but the episode left some teams looking for alternatives, especially in environments where data cannot leave the building.
If that describes you, Apidog is worth a look. It is an all-in-one API platform covering design, debugging, mocking, testing, and documentation, and it imports Insomnia exports so you do not start over. Apidog lets you build assertions visually without writing JavaScript, while still supporting scripts when you want them. Because the API spec, the test data, and the mock server share one project, your tests stay aligned with the real contract instead of drifting. You can download Apidog and import an Insomnia collection to compare side by side. For a broader survey, the list of online API testing tools that are free covers several options.
Insomnia is still a strong, focused client, particularly for solo developers and small teams who value its minimal, distraction-free interface and quick startup. The right choice depends on how your team works and how much of the API lifecycle you want to handle in one place rather than spreading across separate tools.
Frequently asked questions
Is Insomnia free to use?
Insomnia has a free tier that covers individual use, including sending requests and running test suites locally. Paid plans add team collaboration and larger cloud sync limits. You can use the core client without paying, and recent versions let you work fully locally if you prefer not to use cloud sync.
What protocols does Insomnia support?
Insomnia handles HTTP, REST, GraphQL, gRPC, SOAP, and WebSocket. The request setup differs per protocol, but the response inspection and, for HTTP-based requests, the test suite assertions work consistently across them.
How do I write assertions in Insomnia?
Use the test suites feature. Open the Tests view on a collection, create a suite, and add tests. Each test is JavaScript that calls insomnia.send() to run a request, then uses Chai-style expect assertions on the status, headers, or parsed body. Run the whole suite with the Run Tests button.
What changed in Insomnia 8?
Insomnia 8 shifted to a cloud-first default, prompting users to sign in to a Kong account and sync projects to the cloud. Some users disliked the mandatory account flow and the move away from a purely local app. Later updates added clearer local-only options, but the change pushed some teams to evaluate alternatives.
Can I run Insomnia tests in a CI pipeline?
Yes. Use Inso, the command line companion. Export or sync your collection, then run inso run test "<suite name>" in your pipeline. Inso returns a non-zero exit code on failure, so CI can fail the build automatically when an API test breaks.