State API

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

curl -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUESTS"

Retrieve requests filtered by path and method

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

Retrieve recorded requests and responses

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

Retrieve recorded expectations (from proxy traffic)

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

Retrieve active expectations

curl -X PUT "http://localhost:1080/mockserver/retrieve?type=ACTIVE_EXPECTATIONS"

Filtered by request properties:

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

Retrieve log entries

curl -X PUT "http://localhost:1080/mockserver/retrieve?type=LOGS"

Filtered:

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

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.

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

curl -X PUT "http://localhost:1080/mockserver/clear" \
  -d '{
    "path": "/some/path"
  }'

Clear logs only (keep expectations)

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

Clear all recorded requests and logs

curl -X PUT "http://localhost:1080/mockserver/clear?type=log"

Clear expectations only

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

Clear by OpenAPI operation

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

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

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.

PUT /mockserver/reset

Remove all state from MockServer: recorded requests, active expectations, recorded expectations, and logs. Returns: 200 OK. No request body is required.

curl -X PUT "http://localhost:1080/mockserver/reset"

Reset removes everything with no ability to recover. Use clear if you need selective removal.

PUT /mockserver/status

Return the ports MockServer is currently listening on. Returns: 200 OK with a JSON object.

curl -X PUT "http://localhost:1080/mockserver/status"

Response:

{
  "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

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

Bind to free ports (OS-assigned)

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

Response:

{
  "ports": [1080, 1081, 1082]
}

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

REST API

Client SDKs

PUT /mockserver/retrieve

Query parameters

Request body (optional)

Retrieve all recorded requests

Retrieve requests filtered by path and method

Retrieve recorded requests and responses

Retrieve recorded expectations (from proxy traffic)

Retrieve active expectations

Retrieve log entries

PUT /mockserver/clear

Query parameter

Clear everything matching a path

Clear logs only (keep expectations)

Clear all recorded requests and logs

Clear expectations only

Clear by OpenAPI operation

Clear by expectation ID

PUT /mockserver/reset

PUT /mockserver/status

PUT /mockserver/bind

Bind to specific ports

Bind to free ports (OS-assigned)

​PUT /mockserver/retrieve

​Query parameters

​Request body (optional)

​Retrieve all recorded requests

​Retrieve requests filtered by path and method

​Retrieve recorded requests and responses

​Retrieve recorded expectations (from proxy traffic)

​Retrieve active expectations

​Retrieve log entries

​PUT /mockserver/clear

​Query parameter

​Clear everything matching a path

​Clear logs only (keep expectations)

​Clear all recorded requests and logs

​Clear expectations only

​Clear by OpenAPI operation

​Clear by expectation ID

​PUT /mockserver/reset

​PUT /mockserver/status

​PUT /mockserver/bind

​Bind to specific ports

​Bind to free ports (OS-assigned)

PUT /mockserver/retrieve

Query parameters

Request body (optional)

Retrieve all recorded requests

Retrieve requests filtered by path and method

Retrieve recorded requests and responses

Retrieve recorded expectations (from proxy traffic)

Retrieve active expectations

Retrieve log entries

PUT /mockserver/clear

Query parameter

Clear everything matching a path

Clear logs only (keep expectations)

Clear all recorded requests and logs

Clear expectations only

Clear by OpenAPI operation

Clear by expectation ID

PUT /mockserver/reset

PUT /mockserver/status

PUT /mockserver/bind

Bind to specific ports

Bind to free ports (OS-assigned)