Skip to main content
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

ParameterValuesDescription
typeREQUESTSRecorded requests
REQUEST_RESPONSESRecorded requests paired with their responses
RECORDED_EXPECTATIONSExpectations captured from proxied requests
ACTIVE_EXPECTATIONSCurrently active expectations
LOGSLog entries
formatJSON (default)JSON array
JAVAJava code that recreates the expectations
LOG_ENTRIESStructured 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

ValueClears
all (default)Recorded requests, active expectations, and logs
logRecorded requests and logs only
expectationsActive 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.