Skip to content

Configuration guide

Read this section to learn how to configure Imposter.

You can get Imposter to create configuration files for you, based on an existing endpoint or OpenAPI specification. If you don't have either of these, it's easy to create the configuration using the following instructions.


Imposter configuration files are in YAML or JSON format. They must be named with a -config.yaml or -config.json suffix. For example: mymock-config.yaml.

Here is an example configuration file:

# simple-example-config.yaml
plugin: rest
path: "/example"
  file: example-data.json

Or, in JSON format:

  "plugin": "rest",
  "path": "/example",
  "response": {
    "file": "example-data.json"

Note: You must specify the plugin to use in the configuration file. See the list of plugins for possible values.

Returning data

You can control the data Imposter sends back using response files. The response file is used by the active plugin to generate a response. For example, the REST plugin might return the content of the file unmodified, whereas the HBase and SFDC plugins use the response file to generate responses that mimic their respective systems.

Response files can be named anything you like; their path is resolved relative to the configuration file.

Simple, static responses

For simple scenarios, use the file property within the response object in your configuration.

In the example above, we are using a static response file (example-data.json) containing the following:

  "hello": "world"

Using the configuration above, if we were to send an HTTP request to the /example path defined in the configuration file, we would see:

HTTP GET http://localhost:8080/example
HTTP/1.1 200 OK
  "hello": "world"

The plugin has returned the contents of the file in the HTTP response.

Your response files can also be templated - that is, contain placeholders substituted at runtime. See templates for more information.

Response configuration options

You can specify other properties of the response, such as status code and headers. Here is a more complete example:

Single resource example

# single-response-config.yaml
plugin: rest
path: "/example"
method: POST
contentType: "application/json"
  file: data.json
  statusCode: 201
    X-Custom-Header: foo

A few things to call out:

  • This endpoint will only be accessible via the POST HTTP method
  • We've indicated that status code 201 should be returned
  • We've set the content type of the response to JSON
  • A custom header will be returned

Multiple resources example

The OpenAPI plugin and REST plugin allow you to specify multiple resources, using the resources array. Each resource can have its own path, method, response behaviour etc.

# multi-response-config.yaml
plugin: rest
- path: "/example1"
  contentType: "application/json"
  method: GET
    file: data1.json
    statusCode: 200
      X-Custom-Header: foo

- path: "/example2"
  contentType: "text/plain"
  method: POST
    statusCode: 201
      X-Custom-Header: bar
    content: |
      This is some
      multiline response data.
Default response configuration

In some cases, you might want to define default response configuration, e.g. a header that should be sent in all responses. To do this, set the defaultsFromRootResponse: true option, as follows:

plugin: rest

# root response config should be inherited
defaultsFromRootResponse: true

    X-Always-Present: Yes

- method: GET
  path: /example1
    content: "Hello world"

- method: GET
  path: /example2
    content: "Lorem ipsum"

In this example, responses to both /example1 and /example2 will have the header X-Always-Present: Yes set, as it is inherited from the root configuration.

See default-response-config for an example.

Default response values

If unset by configuration or a script, the default values for response configuration fields are as follows:

Field Plugin(s) Type Default Example
contentType all String application/json, or determined from static file text/plain
response.statusCode openapi, rest Integer (HTTP status) 200 201
response.content openapi, rest String empty hello world
response.file all String empty data.json
response.headers openapi, rest Map of String:String empty { "X-Custom-Header": "value" }

Conditional responses

You can make Imposter respond with different values based on certain properties of the request.

Conditional responses can be set in your configuration file, or using the script engine.

For information about the script engine, see the Scripting documentation.

Using the configuration file approach, it is possible to configure different response behaviours based on the following request attributes:

Field Plugin(s) Type Example
path all String /example/path
method openapi, rest String (HTTP method) POST
pathParams openapi, rest Map of String:String { "productCode": "abc" }
queryParams openapi, rest Map of String:String { "limit": "10" }
formParams openapi, rest Map of String:String { "user": "alice" }
requestHeaders openapi, rest Map of String:String { "User-Agent": "curl" }
requestBody openapi, rest Request body matching configuration See advanced matching

Here is an example showing a range of fields:

plugin: openapi
specFile: apispec.yaml

  # handles GET /pets?page=1
  - path: "/pets"
    method: GET
      page: 1
      statusCode: 200

  # handles GET /pets/10
  - path: "/pets/:petId"
    method: GET
      petId: 10
      statusCode: 401
      content: "You do not have permission to view this pet."

  # handles PUT /pets/:petId with a request header 'X-Pet-Username: foo'
  - path: "/pets/:petId"
    method: PUT
      X-Pet-Username: foo
      statusCode: 409
      content: "Username already exists."

Matching the request body

You can also match resources based on the request body (both JSON and XML are supported). See advanced matching for details.

Capturing data

Imposter allows you to capture elements of the request. You can use these elements in a response template, a script or add them to a store for later use.

See data capture for more information.

Environment variables

You can use environment variables as placeholders in plugin configuration files.

# A plugin configuration using an environment variable.
plugin: rest
path: /example
  content: "${env.EXAMPLE_RESPONSE}"

Here the environment variable EXAMPLE_RESPONSE will be substituted into the configuration. For example, if the variable was set as follows:


...then the static data Hello will be returned.

You can use environment variables anywhere within your configuration files, for example, in the security section to avoid including secrets in your configuration files.

Default environment variable values

You can use the following syntax to set defaults for environment variables:


For example:


This would resolve to the value foo if the MY_VAR environment variable was empty or missing.


Imposter can require specific header values to authenticate incoming HTTP requests. Read about how to do this.

Config file discovery

By default, Imposter reads configuration files within the configuration directories, but not their subdirectories.

To also load configuration files within subdirectories, set the following environment variable:


Recursive config scan performance

Warning: when using recursive scan for configuration, directories with many files or subdirectories (such as node_modules) can significantly slow down Imposter startup time.

Typically, you would not store your Imposter configuration files within a directory such as node_modules, so it is safe to ignore such paths when scanning for configuration files. The mechanism for this is a file named .imposterignore

When this file is placed in the root of a configuration directory, you can customise which files/directories to ignore by exact match. For example:

# By default, ignore the following files and directories
# when searching for config files


If no .imposterignore file is present in any configuration directory, a default ignore file is used containing sensible defaults.

Scripted responses (advanced)

For more advanced scenarios, you can also control Imposter's responses using JavaScript or Groovy scripts.

See the Scripting section for more information.

Resource matching performance

Resource matching is typically the fastest method of providing conditional responses. This is the case for request properties such as headers, query parameters, path parameters, path and HTTP method. In the case of using JsonPath to query the request body to conditionally match resources, however, the body must be parsed, which is computationally expensive and will result in lower performance.