The WireMock admin API is described in OpenAPI 3.0. The spec file plus an instance of Swagger UI can be accessed from a running WireMock instance under /__admin/docs/, e.g. http://localhost:8080/__admin/docs/.

Below is the full API reference:

WireMock (3.12.0)

Download OpenAPI specification:Download

WireMock offers a REST API for administration, troubleshooting and analysis purposes

Stub Mappings

Operations on stub mappings

Get all stub mappings

query Parameters
limit
integer
Example: limit=10

The maximum number of results to return

offset
integer

The start index of the results to return

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "mappings": [
    ]
}

Create a new stub mapping

Request Body schema: application/json
id
string

This stub mapping's unique identifier

uuid
string

Alias for the id

name
string

The stub mapping's name

object (request-pattern)
object (response-definition)
persistent
boolean

Indicates that the stub mapping should be persisted immediately on create/update/delete and survive resets to default.

priority
integer >= 1

This stub mapping's priority relative to others. 1 is highest.

scenarioName
string

The name of the scenario that this stub mapping is part of

requiredScenarioState
string

The required state of the scenario in order for this stub to be matched.

newScenarioState
string

The new state for the scenario to be updated to after this stub is served.

postServeActions
object

A map of the names of post serve action extensions to trigger and their parameters.

Array of objects

The list of serve event listeners

metadata
object

Arbitrary metadata to be used for e.g. tagging, documentation. Can also be used to find and remove stubs.

Responses

Request samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Response samples

Content type
application/json
{
  • "id": "76ada7b0-49ae-4229-91c4-396a36f18e09",
  • "priority": 3,
  • "request": {
    },
  • "response": {
    }
}

Delete all stub mappings

Responses

Reset stub mappings

Restores stub mappings to the defaults defined back in the backing store

Responses

Persist stub mappings

Save all persistent stub mappings to the backing store

Responses

Import stub mappings

Import given stub mappings to the backing store

Responses

Get stub mapping by ID

path Parameters
stubMappingId
required
string
Example: 730d3e32-d098-4169-a20c-554c3bedce58

The UUID of stub mapping

Responses

Response samples

Content type
application/json
{
  • "id": "76ada7b0-49ae-4229-91c4-396a36f18e09",
  • "priority": 3,
  • "request": {
    },
  • "response": {
    }
}

Update a stub mapping

path Parameters
stubMappingId
required
string
Example: 730d3e32-d098-4169-a20c-554c3bedce58

The UUID of stub mapping

Request Body schema: application/json
id
string

This stub mapping's unique identifier

uuid
string

Alias for the id

name
string

The stub mapping's name

object (request-pattern)
object (response-definition)
persistent
boolean

Indicates that the stub mapping should be persisted immediately on create/update/delete and survive resets to default.

priority
integer >= 1

This stub mapping's priority relative to others. 1 is highest.

scenarioName
string

The name of the scenario that this stub mapping is part of

requiredScenarioState
string

The required state of the scenario in order for this stub to be matched.

newScenarioState
string

The new state for the scenario to be updated to after this stub is served.

postServeActions
object

A map of the names of post serve action extensions to trigger and their parameters.

Array of objects

The list of serve event listeners

metadata
object

Arbitrary metadata to be used for e.g. tagging, documentation. Can also be used to find and remove stubs.

Responses

Request samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Response samples

Content type
application/json
{
  • "id": "76ada7b0-49ae-4229-91c4-396a36f18e09",
  • "priority": 3,
  • "request": {
    },
  • "response": {
    }
}

Delete a stub mapping

path Parameters
stubMappingId
required
string
Example: 730d3e32-d098-4169-a20c-554c3bedce58

The UUID of stub mapping

Responses

findStubMappingsByMetadata

Find stubs by matching on their metadata

Request Body schema: application/json
required
One of
equalTo
required
string
caseInsensitive
boolean

Responses

Request samples

Content type
application/json
{
  • "matchesJsonPath": {
    }
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "mappings": [
    ]
}

Delete stub mappings matching metadata

Request Body schema: application/json
One of
equalTo
required
string
caseInsensitive
boolean

Responses

Request samples

Content type
application/json
{
  • "matchesJsonPath": {
    }
}

Requests

Logged requests and responses received by the mock service

Get all requests in journal

query Parameters
limit
string
Example: limit=10

The maximum number of results to return

since
string
Example: since=2016-10-05T12:33:01Z

Only return logged requests after this date

Responses

Response samples

Content type
application/json
{
  • "requests": [
    ],
  • "meta": {
    },
  • "requestJournalDisabled": false
}

Delete all requests in journal

Responses

Get request by ID

path Parameters
requestId
required
string
Example: 12fb14bb-600e-4bfa-bd8d-be7f12562c99

The UUID of the logged request

Responses

Response samples

Content type
application/json
{
  • "id": "12fb14bb-600e-4bfa-bd8d-be7f12562c99",
  • "request": {
    },
  • "responseDefinition": {
    }
}

Delete request by ID

path Parameters
requestId
required
string
Example: 12fb14bb-600e-4bfa-bd8d-be7f12562c99

The UUID of the logged request

Responses

Empty the request journal Deprecated

Responses

Count requests by criteria

Count requests logged in the journal matching the specified criteria

Request Body schema: application/json
required
scheme
string
Enum: "http" "https"

The scheme (protocol) part of the request URL

host
string

The hostname part of the request URL

port
integer [ 1 .. 65535 ]

The HTTP port number of the request URL

method
string^[A-Z]+$

The HTTP request method e.g. GET

url
string

The path and query to match exactly against. Only one of url, urlPattern, urlPath or urlPathPattern may be specified.

urlPath
string

The path to match exactly against. Only one of url, urlPattern, urlPath or urlPathPattern may be specified.

urlPathPattern
string

The path regex to match against. Only one of url, urlPattern, urlPath or urlPathPattern may be specified.

urlPattern
string

The path and query regex to match against. Only one of url, urlPattern, urlPath or urlPathPattern may be specified.

object

Path parameter patterns to match against in the : { "": "" } form. Can only be used when the urlPathPattern URL match type is in use and all keys must be present as variables in the path template.

object

Query parameter patterns to match against in the : { "": "" } form

object

application/x-www-form-urlencoded form parameter patterns to match against in the : { "": "" } form

object

Header patterns to match against in the : { "": "" } form

object

Pre-emptive basic auth credentials to match against

object

Cookie patterns to match against in the : { "": "" } form

Array of String equals (object) or Binary equals (object) or String contains (object) or String does not contain (object) or Regular expression match (object) or Negative regular expression match (object) or NOT modifier (object) or Before datetime (object) or Before datetime (object) or Before datetime (object) or JSON equals (object) or JSONPath match (object) or XML equality (object) or XPath match (object) or JSON Schema match (object) or Absent matcher (object) or Logical AND matcher (object) or Logical AND matcher (object) or Has exactly multi value matcher (object) or Has exactly multi value matcher (object) (Content pattern)

Request body patterns to match against in the : { "": "" } form

object

Custom request matcher to match against

Array of objects

Multipart patterns to match against headers and body.

Responses

Request samples

Content type
application/json
{
  • "method": "POST",
  • "url": "/resource",
  • "headers": {
    }
}

Response samples

Content type
application/json
{
  • "count": 4
}

Remove requests by criteria

Removed requests logged in the journal matching the specified criteria

Request Body schema: application/json
required
scheme
string
Enum: "http" "https"

The scheme (protocol) part of the request URL

host
string

The hostname part of the request URL

port
integer [ 1 .. 65535 ]

The HTTP port number of the request URL

method
string^[A-Z]+$

The HTTP request method e.g. GET

url
string

The path and query to match exactly against. Only one of url, urlPattern, urlPath or urlPathPattern may be specified.

urlPath
string

The path to match exactly against. Only one of url, urlPattern, urlPath or urlPathPattern may be specified.

urlPathPattern
string

The path regex to match against. Only one of url, urlPattern, urlPath or urlPathPattern may be specified.

urlPattern
string

The path and query regex to match against. Only one of url, urlPattern, urlPath or urlPathPattern may be specified.

object

Path parameter patterns to match against in the : { "": "" } form. Can only be used when the urlPathPattern URL match type is in use and all keys must be present as variables in the path template.

object

Query parameter patterns to match against in the : { "": "" } form

object

application/x-www-form-urlencoded form parameter patterns to match against in the : { "": "" } form

object

Header patterns to match against in the : { "": "" } form

object

Pre-emptive basic auth credentials to match against

object

Cookie patterns to match against in the : { "": "" } form

Array of String equals (object) or Binary equals (object) or String contains (object) or String does not contain (object) or Regular expression match (object) or Negative regular expression match (object) or NOT modifier (object) or Before datetime (object) or Before datetime (object) or Before datetime (object) or JSON equals (object) or JSONPath match (object) or XML equality (object) or XPath match (object) or JSON Schema match (object) or Absent matcher (object) or Logical AND matcher (object) or Logical AND matcher (object) or Has exactly multi value matcher (object) or Has exactly multi value matcher (object) (Content pattern)

Request body patterns to match against in the : { "": "" } form

object

Custom request matcher to match against

Array of objects

Multipart patterns to match against headers and body.

Responses

Request samples

Content type
application/json
{
  • "method": "POST",
  • "url": "/resource",
  • "headers": {
    }
}

Response samples

Content type
application/json
{
  • "requests": [
    ]
}

Delete requests mappings matching metadata

Request Body schema: application/json
One of
equalTo
required
string
caseInsensitive
boolean

Responses

Request samples

Content type
application/json
{
  • "matchesJsonPath": {
    }
}

Response samples

Content type
application/json
{
  • "requests": [
    ]
}

Find requests by criteria

Retrieve details of requests logged in the journal matching the specified criteria

Request Body schema: application/json
required
scheme
string
Enum: "http" "https"

The scheme (protocol) part of the request URL

host
string

The hostname part of the request URL

port
integer [ 1 .. 65535 ]

The HTTP port number of the request URL

method
string^[A-Z]+$

The HTTP request method e.g. GET

url
string

The path and query to match exactly against. Only one of url, urlPattern, urlPath or urlPathPattern may be specified.

urlPath
string

The path to match exactly against. Only one of url, urlPattern, urlPath or urlPathPattern may be specified.

urlPathPattern
string

The path regex to match against. Only one of url, urlPattern, urlPath or urlPathPattern may be specified.

urlPattern
string

The path and query regex to match against. Only one of url, urlPattern, urlPath or urlPathPattern may be specified.

object

Path parameter patterns to match against in the : { "": "" } form. Can only be used when the urlPathPattern URL match type is in use and all keys must be present as variables in the path template.

object

Query parameter patterns to match against in the : { "": "" } form

object

application/x-www-form-urlencoded form parameter patterns to match against in the : { "": "" } form

object

Header patterns to match against in the : { "": "" } form

object

Pre-emptive basic auth credentials to match against

object

Cookie patterns to match against in the : { "": "" } form

Array of String equals (object) or Binary equals (object) or String contains (object) or String does not contain (object) or Regular expression match (object) or Negative regular expression match (object) or NOT modifier (object) or Before datetime (object) or Before datetime (object) or Before datetime (object) or JSON equals (object) or JSONPath match (object) or XML equality (object) or XPath match (object) or JSON Schema match (object) or Absent matcher (object) or Logical AND matcher (object) or Logical AND matcher (object) or Has exactly multi value matcher (object) or Has exactly multi value matcher (object) (Content pattern)

Request body patterns to match against in the : { "": "" } form

object

Custom request matcher to match against

Array of objects

Multipart patterns to match against headers and body.

Responses

Request samples

Content type
application/json
{
  • "method": "POST",
  • "url": "/resource",
  • "headers": {
    }
}

Response samples

Content type
application/json
{
  • "requests": [
    ]
}

Find unmatched requests

Get details of logged requests that weren't matched by any stub mapping

Responses

Response samples

Content type
application/json
{
  • "requests": [
    ]
}

Near Misses

Near misses allow querying of received requests or request patterns according to similarity

retrieveNearMissesForUnmatchedRequests

Retrieve near-misses for all unmatched requests

Responses

Response samples

Content type
application/json
{
  • "nearMisses": [
    ]
}

Find near misses matching specific request

Find at most 3 near misses for closest stub mappings to the specified request

Request Body schema: application/json
required
method
string

The HTTP request method

url
string

The path and query to match exactly against

absoluteUrl
string

The full URL to match against

headers
object

Header patterns to match against in the : { "": "" } form

cookies
object

Cookie patterns to match against in the : { "": "" } form

body
string

Body string to match against

Responses

Request samples

Content type
application/json
{
  • "url": "/actual",
  • "method": "GET",
  • "clientIp": "0:0:0:0:0:0:0:1",
  • "headers": {
    },
  • "cookies": { },
  • "browserProxyRequest": false,
  • "loggedDate": 1467402464520,
  • "bodyAsBase64": "",
  • "body": "",
  • "loggedDateString": "2016-07-01T19:47:44Z"
}

Response samples

Content type
application/json
{
  • "nearMisses": [
    ]
}

Find near misses matching request pattern

Find at most 3 near misses for closest logged requests to the specified request pattern

Request Body schema: application/json
required
scheme
string
Enum: "http" "https"

The scheme (protocol) part of the request URL

host
string

The hostname part of the request URL

port
integer [ 1 .. 65535 ]

The HTTP port number of the request URL

method
string^[A-Z]+$

The HTTP request method e.g. GET

url
string

The path and query to match exactly against. Only one of url, urlPattern, urlPath or urlPathPattern may be specified.

urlPath
string

The path to match exactly against. Only one of url, urlPattern, urlPath or urlPathPattern may be specified.

urlPathPattern
string

The path regex to match against. Only one of url, urlPattern, urlPath or urlPathPattern may be specified.

urlPattern
string

The path and query regex to match against. Only one of url, urlPattern, urlPath or urlPathPattern may be specified.

object

Path parameter patterns to match against in the : { "": "" } form. Can only be used when the urlPathPattern URL match type is in use and all keys must be present as variables in the path template.

object

Query parameter patterns to match against in the : { "": "" } form

object

application/x-www-form-urlencoded form parameter patterns to match against in the : { "": "" } form

object

Header patterns to match against in the : { "": "" } form

object

Pre-emptive basic auth credentials to match against

object

Cookie patterns to match against in the : { "": "" } form

Array of String equals (object) or Binary equals (object) or String contains (object) or String does not contain (object) or Regular expression match (object) or Negative regular expression match (object) or NOT modifier (object) or Before datetime (object) or Before datetime (object) or Before datetime (object) or JSON equals (object) or JSONPath match (object) or XML equality (object) or XPath match (object) or JSON Schema match (object) or Absent matcher (object) or Logical AND matcher (object) or Logical AND matcher (object) or Has exactly multi value matcher (object) or Has exactly multi value matcher (object) (Content pattern)

Request body patterns to match against in the : { "": "" } form

object

Custom request matcher to match against

Array of objects

Multipart patterns to match against headers and body.

Responses

Request samples

Content type
application/json
{
  • "method": "POST",
  • "url": "/resource",
  • "headers": {
    }
}

Response samples

Content type
application/json
{
  • "nearMisses": [
    ]
}

Recordings

Stub mapping record and snapshot functions

Start recording

Begin recording stub mappings

Request Body schema: application/json
required
object

Headers from the request to include in the generated stub mappings, mapped to parameter objects. The only parameter available is "caseInsensitive", which defaults to false

object

Criteria for extracting response bodies to a separate file instead of including it in the stub mapping

persist
boolean
Default: true

Whether to save stub mappings to the file system or just return them

repeatsAsScenarios
boolean
Default: true

When true, duplicate requests will be added to a Scenario. When false, duplicates are discarded

object or object or object or object

Control the request body matcher used in generated stub mappings

transformerParameters
object

List of names of stub mappings transformers to apply to generated stubs

transformers
Array of strings

Parameters to pass to stub mapping transformers

object

Filter requests for which to create stub mapping

targetBaseUrl
string

Target URL when using the record and playback API

Responses

Request samples

Content type
application/json
{
  • "targetBaseUrl": "http://example.mocklab.io",
  • "filters": {
    },
  • "captureHeaders": {
    },
  • "requestBodyPattern": {
    },
  • "extractBodyCriteria": {
    },
  • "persist": false,
  • "repeatsAsScenarios": false,
  • "transformers": [
    ],
  • "transformerParameters": {
    }
}

Stop recording

End recording of stub mappings

Responses

Response samples

Content type
application/json
{
  • "mappings": [
    ]
}

Get recording status

Responses

Response samples

Content type
application/json
{
  • "status": "Stopped"
}

Take a snapshot recording

Request Body schema: application/json
required
object

Headers from the request to include in the generated stub mappings, mapped to parameter objects. The only parameter available is "caseInsensitive", which defaults to false

object

Criteria for extracting response bodies to a separate file instead of including it in the stub mapping

persist
boolean
Default: true

Whether to save stub mappings to the file system or just return them

repeatsAsScenarios
boolean
Default: true

When true, duplicate requests will be added to a Scenario. When false, duplicates are discarded

object or object or object or object

Control the request body matcher used in generated stub mappings

transformerParameters
object

List of names of stub mappings transformers to apply to generated stubs

transformers
Array of strings

Parameters to pass to stub mapping transformers

object

Filter requests for which to create stub mapping

Responses

Request samples

Content type
application/json
{
  • "filters": {
    },
  • "captureHeaders": {
    },
  • "requestBodyPattern": {
    },
  • "extractBodyCriteria": {
    },
  • "outputFormat": "FULL",
  • "persist": false,
  • "repeatsAsScenarios": false,
  • "transformers": [
    ],
  • "transformerParameters": {
    }
}

Response samples

Content type
application/json
{
  • "mappings": [
    ]
}

Scenarios

Scenarios support modelling of stateful behaviour

Get all scenarios

Responses

Response samples

Content type
application/json
{
  • "scenarios": [
    ]
}

Reset the state of all scenarios

Responses

Files

Manage the files used to support WireMock stubs

Get all file names

Responses

Response samples

Content type
application/json
[
  • "file1.json",
  • "file2.json",
  • "file3.txt"
]

Get file by ID

path Parameters
fileId
required
string
Example: file1.json

The name of the file

Responses

Update or create a file

path Parameters
fileId
required
string
Example: file1.json

The name of the file

Request Body schema: application/octet-stream
string <byte>

Responses

Delete a file if it exists

path Parameters
fileId
required
string
Example: file1.json

The name of the file

Responses

System

Global operations

Update global settings

Request Body schema: application/json
required
One of
median
required
integer
sigma
required
number
type
string
Value: "lognormal"
fixedDelay
number

Responses

Request samples

Content type
application/json
Example
{
  • "median": 0,
  • "sigma": 0,
  • "type": "lognormal",
  • "fixedDelay": 500
}

Reset mappings and request journal

Reset mappings to the default state and reset the request journal

Responses

Shutdown the WireMock server

Shutdown the WireMock server

Responses

Return the version of the WireMock server

Returns the version of the WireMock server

Responses

Response samples

Content type
application/json
{
  • "version": "3.8.0"
}

Return the health of the WireMock server

Returns the health of the WireMock server

Responses

Response samples

Content type
application/json
{
  • "status": "healthy",
  • "message": "Wiremock is ok",
  • "version": "3.8.0",
  • "uptimeInSeconds": 14355,
  • "timestamp": "2024-07-03T13:16:06.172362Z"
}