> ## Documentation Index
> Fetch the complete documentation index at: https://moeck.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> MockServer exposes a REST API over HTTP or HTTPS. All endpoints use the PUT method with JSON request bodies.

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.

<Note>
  The full API is documented as an OpenAPI 3 specification on [SwaggerHub](https://app.swaggerhub.com/apis/jamesdbloom/mock-server-openapi/5.15.x). Use it for interactive exploration and schema details.
</Note>

## 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:

<CodeGroup>
  ```bash create an expectation theme={null}
  curl -X PUT "http://localhost:1080/mockserver/expectation" \
    -d '{
      "httpRequest": {
        "method": "GET",
        "path": "/view/cart"
      },
      "httpResponse": {
        "statusCode": 200,
        "body": "some_response_body"
      }
    }'
  ```

  ```bash verify the request theme={null}
  curl -X PUT "http://localhost:1080/mockserver/verify" \
    -d '{
      "httpRequest": {
        "method": "GET",
        "path": "/view/cart"
      },
      "times": {
        "atLeast": 1
      }
    }'
  ```
</CodeGroup>

## 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 |