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

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.