Skip to main content
An expectation tells MockServer how to respond when an incoming request matches specific criteria. You submit expectations via PUT /mockserver/expectation with a JSON body describing the request matcher and the action to take.

​
PUT /mockserver/expectation

Create or update one or more expectations. Returns: 201 Created on success, 400 Bad Request if the body is invalid. You can submit a single expectation object or a JSON array of expectations. If you supply an id, MockServer updates the existing expectation with that ID or creates a new one — giving you stable, idempotent updates.

​
Request fields

​
id
string
Stable identifier for the expectation. Supply the same id to update an existing expectation in place. If omitted, MockServer generates a UUID.
​
priority
integer
default:"0"
Match priority. When multiple expectations match a request, MockServer uses the one with the highest priority. Expectations with equal priority are evaluated in the order they were added.
​
httpRequest
object
The request matcher. MockServer evaluates all properties you provide; any property you omit is not checked. Supports matching on method, path, pathParameters, queryStringParameters, headers, cookies, body, and socketAddress. You can also match against an OpenAPI spec by providing specUrlOrPayload (and optionally operationId) instead of individual fields.
​
httpResponse
object
Return a fixed HTTP response. Use this for the majority of mocking scenarios. Mutually exclusive with httpForward, httpClassCallback, httpError, httpResponseTemplate, and httpOverrideForwardedRequest.
​
httpForward
object
Forward the matched request to another host. Provide host, port, and scheme (HTTP or HTTPS).
​
httpOverrideForwardedRequest
object
Forward the request with modifications applied before forwarding and/or to the response before returning it.
​
httpClassCallback
object
Delegate response generation to a Java class on the classpath. Provide callbackClass with the fully-qualified class name.
​
httpResponseTemplate
object
Generate responses dynamically using a JavaScript or Velocity template. Provide template and templateType (JAVASCRIPT or VELOCITY).
​
httpError
object
Simulate a connection-level error. Set dropConnection: true to close the connection immediately, or provide responseBytes (base64-encoded) to send raw bytes before dropping.
​
times
object
Controls how many times this expectation can be matched. Omit for unlimited matching.
  • remainingTimes (integer) — match at most this many more times
  • unlimited (boolean) — if true, match indefinitely (overrides remainingTimes)
​
timeToLive
object
Controls how long the expectation remains active after it is created.
  • timeUnit (string) — e.g. "SECONDS", "MINUTES", "HOURS"
  • timeToLive (integer) — duration in the given unit
  • unlimited (boolean) — if true, the expectation never expires

​
Basic response example

Match GET /view/cart and return a plain-text body: 
curl -X PUT "http://localhost:1080/mockserver/expectation" \
  -d '{
    "httpRequest": {
      "method": "GET",
      "path": "/view/cart",
      "queryStringParameters": {
        "cartId": ["055CA455-1DF7-45BB-8535-4F83E7266092"]
      },
      "cookies": {
        "session": "4930456C-C718-476F-971F-CB8E047AB349"
      }
    },
    "httpResponse": {
      "body": "some_response_body"
    }
  }'

​
Limited-use expectation

Match a path exactly twice, then stop matching: 
curl -X PUT "http://localhost:1080/mockserver/expectation" \
  -d '{
    "httpRequest": {
      "path": "/some/path"
    },
    "httpResponse": {
      "body": "some_response_body"
    },
    "times": {
      "remainingTimes": 2,
      "unlimited": false
    },
    "timeToLive": {
      "unlimited": true
    }
  }'

​
Expectation with TTL

Match exactly once in the next 60 seconds: 
curl -X PUT "http://localhost:1080/mockserver/expectation" \
  -d '{
    "httpRequest": {
      "path": "/some/path"
    },
    "httpResponse": {
      "body": "some_response_body"
    },
    "times": {
      "remainingTimes": 1,
      "unlimited": false
    },
    "timeToLive": {
      "timeUnit": "SECONDS",
      "timeToLive": 60,
      "unlimited": false
    }
  }'

​
Update an expectation by ID

Supply an id to update an existing expectation or create a new one with a known identifier: 
curl -X PUT "http://localhost:1080/mockserver/expectation" \
  -d '{
    "id": "630a6e5b-9d61-4668-a18f-a0d3df558583",
    "priority": 0,
    "httpRequest": {
      "path": "/some/path"
    },
    "httpResponse": {
      "statusCode": 200,
      "body": "some_response_body"
    },
    "times": {
      "unlimited": true
    },
    "timeToLive": {
      "unlimited": true
    }
  }'

​
Bulk create

Submit an array of expectations in one call: 
curl -X PUT "http://localhost:1080/mockserver/expectation" \
  -d '[
    {
      "httpRequest": { "path": "/somePathOne" },
      "httpResponse": { "statusCode": 200, "body": "one" }
    },
    {
      "httpRequest": { "path": "/somePathTwo" },
      "httpResponse": { "statusCode": 200, "body": "two" }
    }
  ]'

​
Forward expectation

Forward matching requests to another host: 
curl -X PUT "http://localhost:1080/mockserver/expectation" \
  -d '{
    "httpRequest": {
      "path": "/some/path"
    },
    "httpForward": {
      "host": "mock-server.com",
      "port": 443,
      "scheme": "HTTPS"
    }
  }'

​
Error simulation

Drop the connection for requests matching a path: 
curl -X PUT "http://localhost:1080/mockserver/expectation" \
  -d '{
    "httpRequest": {
      "path": "/some/path"
    },
    "httpError": {
      "dropConnection": true
    }
  }'

​
PUT /mockserver/openapi

Load expectations automatically from an OpenAPI specification. MockServer generates one expectation per operation in the spec, using the spec’s request schema as the matcher. Returns: 201 Created on success.
​
specUrlOrPayload
string
required
A URL pointing to an OpenAPI JSON or YAML file, a classpath resource path, or the raw spec content as a string.
​
operationsAndResponses
object
Override the response code used for each operation. Keys are operationId strings; values are HTTP status code strings (e.g. "200", "404"). If omitted, MockServer picks the first defined response for each operation.

​
Load from a URL

curl -X PUT "http://localhost:1080/mockserver/openapi" \
  -d '{
    "specUrlOrPayload": "https://raw.githubusercontent.com/mock-server/mockserver/master/mockserver-integration-testing/src/main/resources/org/mockserver/openapi/openapi_petstore_example.json"
  }'

​
Load from a URL with custom response codes

curl -X PUT "http://localhost:1080/mockserver/openapi" \
  -d '{
    "specUrlOrPayload": "https://raw.githubusercontent.com/mock-server/mockserver/master/mockserver-integration-testing/src/main/resources/org/mockserver/openapi/openapi_petstore_example.json",
    "operationsAndResponses": {
      "listPets": "200",
      "createPets": "201",
      "showPetById": "200"
    }
  }'
You can also match against OpenAPI operations inside a regular PUT /mockserver/expectation request by providing specUrlOrPayload (and optionally operationId) inside the httpRequest object. This lets you target a single operation while supplying a custom action.