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

EndpointDescription
PUT /mockserver/expectationCreate or update one or more expectations
PUT /mockserver/openapiCreate expectations from an OpenAPI specification
PUT /mockserver/verifyVerify a request was received the expected number of times
PUT /mockserver/verifySequenceVerify a sequence of requests was received in order
PUT /mockserver/retrieveRetrieve recorded requests, expectations, or logs
PUT /mockserver/clearClear recorded requests, expectations, or logs
PUT /mockserver/resetReset all server state
PUT /mockserver/statusGet the ports MockServer is bound to
PUT /mockserver/bindBind 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"
    }
  }'

​
HTTP status codes

CodeMeaning
201 CreatedExpectation created successfully
202 AcceptedVerification passed
200 OKRetrieve, status, bind, clear, or reset succeeded
400 Bad RequestMalformed request body — response includes a descriptive error
406 Not AcceptableVerification failed — response body contains the failure message