> ## Documentation Index
> Fetch the complete documentation index at: https://moeck.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Expectations API

> Create, update, and load expectations using PUT /mockserver/expectation and PUT /mockserver/openapi.

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

<ParamField body="id" type="string">
  Stable identifier for the expectation. Supply the same `id` to update an existing expectation in place. If omitted, MockServer generates a UUID.
</ParamField>

<ParamField body="priority" type="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.
</ParamField>

<ParamField body="httpRequest" type="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.
</ParamField>

<ParamField body="httpResponse" type="object">
  Return a fixed HTTP response. Use this for the majority of mocking scenarios. Mutually exclusive with `httpForward`, `httpClassCallback`, `httpError`, `httpResponseTemplate`, and `httpOverrideForwardedRequest`.
</ParamField>

<ParamField body="httpForward" type="object">
  Forward the matched request to another host. Provide `host`, `port`, and `scheme` (`HTTP` or `HTTPS`).
</ParamField>

<ParamField body="httpOverrideForwardedRequest" type="object">
  Forward the request with modifications applied before forwarding and/or to the response before returning it.
</ParamField>

<ParamField body="httpClassCallback" type="object">
  Delegate response generation to a Java class on the classpath. Provide `callbackClass` with the fully-qualified class name.
</ParamField>

<ParamField body="httpResponseTemplate" type="object">
  Generate responses dynamically using a JavaScript or Velocity template. Provide `template` and `templateType` (`JAVASCRIPT` or `VELOCITY`).
</ParamField>

<ParamField body="httpError" type="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.
</ParamField>

<ParamField body="times" type="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`)
</ParamField>

<ParamField body="timeToLive" type="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
</ParamField>

### Basic response example

Match `GET /view/cart` and return a plain-text body:

<CodeGroup>
  ```bash curl theme={null}
  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"
      }
    }'
  ```

  ```json body theme={null}
  {
    "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"
    }
  }
  ```
</CodeGroup>

### Limited-use expectation

Match a path exactly twice, then stop matching:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.

<ParamField body="specUrlOrPayload" type="string" required>
  A URL pointing to an OpenAPI JSON or YAML file, a classpath resource path, or the raw spec content as a string.
</ParamField>

<ParamField body="operationsAndResponses" type="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.
</ParamField>

### Load from a URL

```bash theme={null}
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

```bash theme={null}
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"
    }
  }'
```

<Tip>
  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.
</Tip>