API Overview - MockServer

MockServer’s REST API lets you create expectations, verify requests, retrieve recorded traffic, and manage server state — all over HTTP. Every control endpoint uses PUT, and request bodies are JSON.

The full API is documented as an OpenAPI 3 specification on SwaggerHub. Use it for interactive exploration and schema details.

Base URL

By default, MockServer listens on port 1080:

http://localhost:1080

For TLS connections, use https://localhost:1080. Pass -k (or --insecure) with curl when MockServer uses a self-signed certificate.

Conventions

All control endpoints use the PUT HTTP method.
Request bodies are JSON. Set Content-Type: application/json if your client requires it.
Responses use standard HTTP status codes to indicate success or failure.
MockServer returns 400 Bad Request with a descriptive message when the request body fails JSON schema validation.

Endpoints

Endpoint	Description
`PUT /mockserver/expectation`	Create or update one or more expectations
`PUT /mockserver/openapi`	Create expectations from an OpenAPI specification
`PUT /mockserver/verify`	Verify a request was received the expected number of times
`PUT /mockserver/verifySequence`	Verify a sequence of requests was received in order
`PUT /mockserver/retrieve`	Retrieve recorded requests, expectations, or logs
`PUT /mockserver/clear`	Clear recorded requests, expectations, or logs
`PUT /mockserver/reset`	Reset all server state
`PUT /mockserver/status`	Get the ports MockServer is bound to
`PUT /mockserver/bind`	Bind MockServer to additional ports

Quick example

Create an expectation and then verify it was matched:

curl -X PUT "http://localhost:1080/mockserver/expectation" \
  -d '{
    "httpRequest": {
      "method": "GET",
      "path": "/view/cart"
    },
    "httpResponse": {
      "statusCode": 200,
      "body": "some_response_body"
    }
  }'

curl -X PUT "http://localhost:1080/mockserver/verify" \
  -d '{
    "httpRequest": {
      "method": "GET",
      "path": "/view/cart"
    },
    "times": {
      "atLeast": 1
    }
  }'

HTTP status codes

Code	Meaning
`201 Created`	Expectation created successfully
`202 Accepted`	Verification passed
`200 OK`	Retrieve, status, bind, clear, or reset succeeded
`400 Bad Request`	Malformed request body — response includes a descriptive error
`406 Not Acceptable`	Verification failed — response body contains the failure message

​Base URL

​Conventions

​Endpoints

​Quick example

​HTTP status codes

Base URL

Conventions

Endpoints

Quick example

HTTP status codes