Announcement! Discover and Install plugins from the Insomnia Plugin Hub

For most use-cases, Insomnia’s core feature set will suffice. However, for certain things like custom authentication mechanisms or complex workflows, more advanced behavior may be required.

This document provides an overview of Insomnia’s plugin APIs, which can be used to extend the functionality of Insomnia.



There are three general types of plugins that you can create for Insomnia. A plugin can either add a custom template tag for rendering custom values, or defined a hook which can do things like intercept requests and responses to add custom behavior.

Create a Plugin

A plugin is a NodeJS Module that is placed in a specific directory that Insomnia knows about.

  • MacOS: ~/Library/Application\ Support/Insomnia/plugins/
  • Windows: %APPDATA%\Insomnia\plugins\
  • Linux: $XDG_CONFIG_HOME/Insomnia/plugins/ or ~/.config/Insomnia/plugins/

A plugin directory requires at least two files:

 ├── package.json   # Node module metadata
 └── *.js           # One or more JavaScript files

The package.json must contain an insomnia attribute to be identified as a plugin.

Take a look at the following file to see what a minimal package.json should look like.

Note: If you want to publish an Insomnia plugin on npm and have it display in the Plugin Hub, you must prefix the name with insomnia-plugin-

Example: Plugin package.json file
  "name": "insomna-plugin-base64",  // Npm module name
  "version": "1.0.0",               // Plugin version
  "main": "plugin.js",              // Entry point
   * Insomnia-specific metadata. Without this, Insomnia
   * won't recognize the module as a plugin.
  "insomnia": {                    
    "name": "base64",      // Internal Insomnia plugin name
    "displayName": "Base64 Plugin", // Plugin display name
    "description": "...",  // Plugin description

    // Optional plugin metadata

    // Plugin images for Plugin Hub and other interfaces
    "images": {
      // Plugin Icon
      // Suggested filetype: SVG (for scaling)
      // Suggested dimensions: 48x48
      "icon": "icon.svg", // relative path, relative to package root

      // Plugin Cover Image
      // Suggested filetype: SVG (for scaling)
      // Suggested dimensions: 952w x 398h
      "cover": "cover.svg", // relative path, relative to package root

    // Force plugin hub and other entities to show specific author details
    // Useful for teams / organizations who work on same plugin
    "publisher": {
      "name": "YOUR NAME HERE", // Plugin publisher name, displayed on plugin hub
      "icon": "https://...", // Plugin publisher avatar /  icon, absolute url

    // Plugin Application Support
    // semver target supported, see for more details
    // * targets all versions
    "applications": { 
      "designer": "*",
      "core": "*",
      "cli": "*",
  // External dependencies are also supported
  "dependencies": [],
  "devDependencies": []

Managing Plugins

Plugins can be added from the Plugins tab within the application preferences dialog. They can also be downloaded and installed directly from npm.

Publishing Plugins

Before you publish your plugin, there are two main things you want to ensure if you want your plugin to be recognized by Insomnia and be available through the Insomnia Plugin Hub.

  1. Your plugin's package.json contains the insomnia attribute with the correct structure. See Create a Plugin for more info.
  2. Your plugin's package name is prefixed with insomnia-plugin-

After you have verified that your plugin meets the criteria described above, now you can proceed with publishing your plugin following the npm instructions on publishing a package.

If your package does not show up on the Insomnia Plugin Hub after a few days, please contact us with the name of your plugin and a link to the published npm package.


Navigate to View > Toggle DevTools to open the Chrome Developer Tools. From here, you can debug Insomnia as you would any web project in Chrome.

If you want to focus specifically on the plugin you are developing, you can find it from the Sources tab and/or filter the Console based on the plugin’s file name.

Template Tags

As mentioned, a custom Template Tag can be added, which can then be referenced inside Insomnia’s template system to render custom values.

type RenderContext = {
  // API not finalized yet

type TemplateTag = {
  name: string,
  displayName: DisplayName,
  disablePreview?: () => boolean,
  description?: string,
  deprecated?: boolean,
  liveDisplayName?: (args) => ?string,
  validate?: (value: any) => ?string,
  priority?: number,
  args: Array<{
    displayName: string,
    description?: string,
    defaultValue: string | number | boolean,
    type: 'string' | 'number' | 'enum' | 'model',
    // Only type === 'string'
    placeholder?: string,

    // Only type === 'model'
    modelType: string,

    // Only type === 'enum'
    options: Array<{
      displayName: string,
      value: string,
      description?: string,
      placeholder?: string,
Example: Template tag to generate random number
 * Example template tag that generates a random number 
 * between a user-provided MIN and MAX
module.exports.templateTags = [{
    name: 'random',
    displayName: 'Random Integer',
    description: 'Generate random things',
    args: [
            displayName: 'Minimum',
            description: 'Minimum potential value',
            type: 'number',
            defaultValue: 0
            displayName: 'Maximum',
            description: 'Maximum potential value',
            type: 'number',
            defaultValue: 100
    async run (context, min, max) {
        return Math.round(min + Math.random() * (max - min));

Request/Response Hooks

Plugins can implement “hook” functions that get called when certain things happen. A plugin can currently export two different types of hooks:

type RequestContext = {
    app: AppContext,            // Defined Below
    request: RequestContext     // Defined Below

type ResponseContext = {
    app: AppContext,            // Defined Below
    response: ResponseContext   // Defined below

// Hooks are exported as an array of "hook" functions which get 
// called with the appropriate plugin API context.
module.exports.requestHooks = Array<(context: RequestContext) => void>
module.exports.responseHooks = Array<(context: ResponseContext) => void>

Folder Actions

Actions can be added to the bottom of the folder dialog by defining a folder (request group) action plugin.

type RequestGroupAction = {
    label: string,
    action: (context: Context, { 
        requestGroup: RequestGroup, 
        requests: Array<Request>
    }): Promise<void>

// Folder actions are exported as an array of objects
module.exports.requestGroupActions = Array<RequestGroupAction>
Example: Plugin to send all requests in a folder

module.exports.requestGroupActions = [
    label: 'Send Requests',
    action: async (context, data) => {
      const { requests } = data;

      let results = [];
      for (const request of requests) {
        const response = await;
        results.push(`<li>${}: ${response.statusCode}</li>`);

      const html = `<ul>${results.join('\n')}</ul>`;'Results', { html });

Workspace Actions

Actions can be added to the main app dropdown by defining a workspace action plugin.

type WorkspaceAction = {
    label: string,
    action: (context: Context, { 
        workspace: Workspace,
        requestGroup: Array<RequestGroup>, 
        requests: Array<Request>
    }): Promise<void>

// Workspace actions are exported as an array of objects
module.exports.workspaceActions = Array<WorkspaceAction>
Example: Plugin to export the current workspace


const fs = require('fs');

module.exports.workspaceActions = [{
  label: 'My Plugin Action',
  icon: 'fa-star',
  action: async (context, models) => {
    const ex = await{
      includePrivate: false,
      format: 'json',
      workspace: models.workspace,

    fs.WriteFileSync('/users/user/Desktop/export.json', ex);

Custom Themes

Additional color schemes can be created an installed via the plugin system. A good place to start is to view the bundled themes within the insomnia-plugin-themes module.

type ThemeBlock = {
  background?: {
    default?: string,
    success?: string,
    notice?: string,
    warning?: string,
    danger?: string,
    surprise?: string,
    info?: string,
  foreground?: {
    default?: string,
    success?: string,
    notice?: string,
    warning?: string,
    danger?: string,
    surprise?: string,
    info?: string,
  highlight?: {
    default: string,
    xxs?: string,
    xs?: string,
    sm?: string,
    md?: string,
    lg?: string,
    xl?: string,

type ThemeInner = {
  rawCss?: string,
  styles: ?{
    dialog?: ThemeBlock,
    dialogFooter?: ThemeBlock,
    dialogHeader?: ThemeBlock,
    dropdown?: ThemeBlock,
    editor?: ThemeBlock,
    link?: ThemeBlock,
    overlay?: ThemeBlock,
    pane?: ThemeBlock,
    paneHeader?: ThemeBlock,
    sidebar?: ThemeBlock,
    sidebarHeader?: ThemeBlock,
    sidebarList?: ThemeBlock,
    tooltip?: ThemeBlock,
    transparentOverlay?: ThemeBlock,
Example: Simple dark theme
module.exports.themes = [{
  name: 'my-dark-theme',
  displayName: 'My Dark Theme',
  theme: {
    foreground: {
      default: '#ddd',
    background: {
      default: '#000',
      success: '#87ee59',
      notice: '#f8d245',
      warning: '#f9ac2a',
      danger: '#ff505c',
      surprise: '#f24aff',
      info: '#23dce8',
Example: Styling sub-components
module.exports.themes = [{
  name: 'my-theme',
  displayName: 'My Theme',
  theme: {
    background: {
      default: '#555',
      success: '#59a210',
      notice: '#ae9602',
      warning: '#d07502',
      danger: '#d04444',
      surprise: '#7d69cb',
      info: '#1c90b4',
    foreground: {
      default: '#eee',
    styles: {
      // Different colors in sidebar
      sidebar: {
        background: {
          default: '#2e2f2b',
          success: '#7ecf2b',
          notice: '#f0e137',
          warning: '#ff9a1f',
          danger: '#ff5631',
          surprise: '#a896ff',
          info: '#46c1e6',
        foreground: {
          default: 'e0e0e0',
        highlight: {
          default: '#999',
Example: Custom CSS
module.exports.themes = [{
  name: 'my-dark-theme',
  displayName: 'My Dark Theme',
  theme: {
        rawCss: `
      .tooltip, .dropdown__menu {
        opacity: 0.95;


// context.request functions
type RequestContext = {
    getId (): string,
    getName (): string,
    getUrl (): string,
    setUrl (url: string): void,
    getMethod (): string,
    getHeader (name: string): string | null, 
    hasHeader (name: string): boolean,
    removeHeader (name: string): void,
    setHeader (name: string, value: string): void,
    addHeader (name: string, value: string): void,
    getParameter (name: string): string | null,
    getParameters (): Array<{name: string, value: string}>,
    setParameter (name: string, value: string): void,
    hasParameter (name: string): boolean,
    addParameter (name: string, value: string): void,
    removeParameter (name: string): void,
    setBodyText (text: string): void,
    getBodyText (): string,
    setCookie (name: string, value: string): void,
    getEnvironmentVariable (name: string): any,
    getEnvironment (): Object,
    setAuthenticationParameter (string: any): void,
    getAuthentication (): Object,
    setCookie (name: string, value: string): void,
    settingSendCookies (enabled: boolean): void,
    settingStoreCookies (enabled: boolean): void,
    settingEncodeUrl (enabled: boolean): void,
    settingDisableRenderRequestBody (enabled: boolean): void,
Example: Set Content-Type header on every POST request
// Request hook to set header on every request
module.exports.requestHooks = [
  context => {
    if (context.request.getMethod().toUpperCase() === 'POST') {
      context.request.setHeader('Content-Type', 'application/json');


// context.response functions
getRequestId (): string;
getStatusCode (): number
getStatusMessage (): string
getBytesRead (): number
getTime (): number
getBody (): Buffer | null
setBody (body: Buffer)
getHeader (name: string): string | Array<string> | null
hasHeader (name: string): boolean
Example: Save response to file
const fs = require('fs');

// Request hook to save response to file
module.exports.responseHooks = [
  context => {

Plugins can store persistent data via the storage context. Data is only accessible to the plugin that stored it.

// functions
async hasItem(key: string): Promise<boolean>
async setItem(key: string, value: string): Promise<void>
async getItem(key: string): Promise<string | null>
async removeItem(key: string): Promise<void>
async clear(): Promise<void>
async all(): Promise<Array<{ key: string, value: string }>>

The app context contains a general set of helpers that are global to the application.

// functions
alert(title: string, message?: string): Promise<void>
prompt(title: string, options?: {
    label?: string,
    defaultValue?: string,
    submitName?: string,
    cancelable?: boolean,
  }): Promise<string>
getPath(name: 'desktop'): string
async showSaveDialog(options: { defaultPath?: string } = {}): Promise<string | null>

The data context contains helpers related to importing and exporting Insomnia workspaces.

// functions
async uri(uri: string, options: { workspaceId?: string } = {}): Promise<void>
async raw(text: string, options: { workspaceId?: string } = {}): Promise<void>

// functions
async insomnia(options: { 
    includePrivate?: boolean,
    format?: 'json' | 'yaml'
  }): Promise<string>
async har(options: { includePrivate?: boolean } = {}): Promise<string><br>

The network context contains helpers related to sending network requests.

// functions
async sendRequest(request: Request): Promise<Response>
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us