How to Use 'Insomnia' for GraphQL Testing

A Lighter Client Built for GraphQL

Postman handles GraphQL, but it was designed REST-first and it shows — every GraphQL request in Postman is really just a POST with a query string stuffed into the body. Insomnia treats GraphQL as a first-class citizen: it fetches and displays the schema, autocompletes field names as you type, and shows documentation inline. It is also a noticeably lighter, faster application if you only need request testing without Postman's broader team and mocking features.

Installing Insomnia

Download the desktop app from insomnia.rest/download for Windows, macOS, or Linux. It is free for individual use. On first launch you can create a local-only workspace without signing up for an account, which is enough for everything covered here.

Creating a GraphQL Request

Click New Request (or the + button in your workspace), give it a name, and select GraphQL as the request type instead of the default HTTP. Enter your GraphQL endpoint URL — most GraphQL APIs expose a single endpoint rather than many REST routes:

https://api.example.com/graphql

As soon as you enter a valid, reachable endpoint, Insomnia automatically sends an introspection query in the background to fetch the API's schema — assuming the server has introspection enabled, which most development and many production GraphQL APIs do.

Writing and Autocompleting a Query

In the query editor pane, start typing a query. With the schema loaded, Insomnia autocompletes field names, argument types, and even flags required arguments you have left out:

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

Hover over any field name and Insomnia shows its type and description straight from the schema's docstrings — the same documentation a tool like GraphiQL would show, without leaving your request client.

Passing Query Variables

Below the query editor is a separate Query Variables pane (or a tab labeled "Vars" depending on version). Since the query above references $id, define it there as JSON:

{
  "id": "42"
}

Keeping variables separate from the query body matches how GraphQL requests actually travel over HTTP — the server receives query and variables as distinct fields in the same JSON POST body, and Insomnia mirrors that structure directly in the UI.

Authenticating Requests

Click the Auth tab within the request. For a token-protected API, choose Bearer Token and paste in your token, or choose OAuth 2.0 if the API requires a full token exchange flow — Insomnia can handle the authorization code or client credentials grant and automatically attach the resulting access token to subsequent requests.

Managing Environments

Click the environment dropdown in the sidebar (usually labeled No Environment by default) and choose Manage Environments. Define a base environment with variables like:

{
  "base_url": "https://api.staging.example.com/graphql",
  "auth_token": "eyJhbGciOiJIUzI1NiIs..."
}

Reference these in your request URL or headers with double curly braces, the same convention Postman uses:

{{ _.base_url }}

Insomnia's variable syntax includes the _. prefix by default (referring to the current environment object), which trips up people coming from Postman the first time they see it.

Inspecting Schema Documentation Directly

Click the Schema button (often in the top-right of the request pane, sometimes labeled with a document icon) to open a searchable, browsable view of every type, query, mutation, and field the API exposes — without writing a query at all. This is useful for exploring an unfamiliar API's capabilities before you commit to writing anything.

Testing Mutations

Mutations work identically to queries — just write the mutation instead of a query in the same editor:

mutation CreatePost($title: String!, $body: String!) {
  createPost(title: $title, body: $body) {
    id
    title
  }
}

Set the corresponding variables and send it exactly like a query. The response pane below shows the returned JSON, including any errors array GraphQL returns for partial failures — worth checking even when the HTTP status is 200, since GraphQL servers commonly return errors inside a 200 response body rather than through HTTP status codes.