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

# State API

> Retrieve recorded requests and logs, clear state selectively, reset everything, check server status, and bind additional ports.

MockServer maintains four types of internal state:

* **Recorded requests** — every request received, whether or not it matched an expectation
* **Recorded expectations** — expectations captured from proxied traffic
* **Active expectations** — expectations currently registered and eligible to match
* **Logs** — structured log entries for all major actions

Use the endpoints below to inspect and manage this state.

***

## PUT /mockserver/retrieve

Retrieve recorded requests, expectations, or log entries. Use the `type` query parameter to select what to retrieve, and the optional `format` parameter to control the output format.

**Returns:** `200 OK` with a JSON array (or log text) in the response body.

### Query parameters

| Parameter | Values                  | Description                                   |
| --------- | ----------------------- | --------------------------------------------- |
| `type`    | `REQUESTS`              | Recorded requests                             |
|           | `REQUEST_RESPONSES`     | Recorded requests paired with their responses |
|           | `RECORDED_EXPECTATIONS` | Expectations captured from proxied requests   |
|           | `ACTIVE_EXPECTATIONS`   | Currently active expectations                 |
|           | `LOGS`                  | Log entries                                   |
| `format`  | `JSON` (default)        | JSON array                                    |
|           | `JAVA`                  | Java code that recreates the expectations     |
|           | `LOG_ENTRIES`           | Structured log format (for `LOGS` type)       |

### Request body (optional)

Pass a request matcher object as the body to filter results. MockServer returns only the items that match. Omit the body to retrieve everything.

### Retrieve all recorded requests

```bash theme={null}
curl -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUESTS"
```

### Retrieve requests filtered by path and method

```bash theme={null}
curl -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUESTS&format=JSON" \
  -d '{
    "path": "/some/path",
    "method": "POST"
  }'
```

### Retrieve recorded requests and responses

```bash theme={null}
curl -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUEST_RESPONSES" \
  -d '{
    "path": "/some/path",
    "method": "POST"
  }'
```

### Retrieve recorded expectations (from proxy traffic)

```bash theme={null}
curl -X PUT "http://localhost:1080/mockserver/retrieve?type=RECORDED_EXPECTATIONS" \
  -d '{
    "path": "/some/path",
    "method": "POST"
  }'
```

### Retrieve active expectations

```bash theme={null}
curl -X PUT "http://localhost:1080/mockserver/retrieve?type=ACTIVE_EXPECTATIONS"
```

Filtered by request properties:

```bash theme={null}
curl -X PUT "http://localhost:1080/mockserver/retrieve?type=ACTIVE_EXPECTATIONS&format=JSON" \
  -d '{
    "path": "/some/path",
    "method": "POST"
  }'
```

### Retrieve log entries

```bash theme={null}
curl -X PUT "http://localhost:1080/mockserver/retrieve?type=LOGS"
```

Filtered:

```bash theme={null}
curl -X PUT "http://localhost:1080/mockserver/retrieve?type=LOGS" \
  -d '{
    "path": "/some/path",
    "method": "POST"
  }'
```

<Note>
  Recorded expectations are populated only when MockServer is running in proxy mode and has forwarded requests. They represent what the real upstream server responded with, ready to be replayed as mocked expectations.
</Note>

***

## PUT /mockserver/clear

Clear recorded requests, active expectations, and/or logs. Use the `type` query parameter to select what to clear and an optional request matcher or expectation ID to narrow the scope.

**Returns:** `200 OK` on success.

### Query parameter

| Value           | Clears                                           |
| --------------- | ------------------------------------------------ |
| `all` (default) | Recorded requests, active expectations, and logs |
| `log`           | Recorded requests and logs only                  |
| `expectations`  | Active expectations only                         |

### Clear everything matching a path

```bash theme={null}
curl -X PUT "http://localhost:1080/mockserver/clear" \
  -d '{
    "path": "/some/path"
  }'
```

### Clear logs only (keep expectations)

```bash theme={null}
curl -X PUT "http://localhost:1080/mockserver/clear?type=log" \
  -d '{
    "path": "/some/path"
  }'
```

### Clear all recorded requests and logs

```bash theme={null}
curl -X PUT "http://localhost:1080/mockserver/clear?type=log"
```

### Clear expectations only

```bash theme={null}
curl -X PUT "http://localhost:1080/mockserver/clear?type=expectations" \
  -d '{
    "path": "/some/path"
  }'
```

### Clear by OpenAPI operation

```bash theme={null}
curl -X PUT "http://localhost:1080/mockserver/clear" \
  -d '{
    "specUrlOrPayload": "https://raw.githubusercontent.com/mock-server/mockserver/master/mockserver-integration-testing/src/main/resources/org/mockserver/openapi/openapi_petstore_example.json",
    "operationId": "showPetById"
  }'
```

### Clear by expectation ID

```bash theme={null}
curl -X PUT "http://localhost:1080/mockserver/clear" \
  -d '{
    "id": "31e4ca35-66c6-4645-afeb-6e66c4ca0559"
  }'
```

<Warning>
  When the log level is set to `DEBUG`, clearing logs marks entries as deleted rather than removing them. This preserves the audit trail for verification and the UI, but the entries no longer affect verification results.
</Warning>

***

## PUT /mockserver/reset

Remove all state from MockServer: recorded requests, active expectations, recorded expectations, and logs.

**Returns:** `200 OK`.

No request body is required.

```bash theme={null}
curl -X PUT "http://localhost:1080/mockserver/reset"
```

<Warning>
  Reset removes everything with no ability to recover. Use `clear` if you need selective removal.
</Warning>

***

## PUT /mockserver/status

Return the ports MockServer is currently listening on.

**Returns:** `200 OK` with a JSON object.

```bash theme={null}
curl -X PUT "http://localhost:1080/mockserver/status"
```

**Response:**

```json theme={null}
{
  "ports": [1080]
}
```

No request body is required.

***

## PUT /mockserver/bind

Bind MockServer to one or more additional ports at runtime. Pass `0` to have the OS assign a free port.

**Returns:** `200 OK` with a JSON object listing all ports now bound (including pre-existing ones).

### Bind to specific ports

```bash theme={null}
curl -X PUT "http://localhost:1080/mockserver/bind" \
  -d '{
    "ports": [1081, 1082]
  }'
```

### Bind to free ports (OS-assigned)

```bash theme={null}
curl -X PUT "http://localhost:1080/mockserver/bind" \
  -d '{
    "ports": [0, 0]
  }'
```

**Response:**

```json theme={null}
{
  "ports": [1080, 1081, 1082]
}
```

<Note>
  Ports bound via this endpoint persist only for the lifetime of the MockServer process. They are not saved to configuration.
</Note>