MockServer

MockServer Control API

Manage state or process (both MockServer & MockServer Proxy)

GitHub OpenAPI

Operations 6

PUT /mockserver/clear clears expectations and recorded requests that match the request matcher #
PUT /mockserver/reset clears all expectations and recorded requests #
PUT /mockserver/retrieve retrieve recorded requests, active expectations, recorded expectations or log… #
PUT /mockserver/status return listening ports #
PUT /mockserver/bind bind additional listening ports #
PUT /mockserver/stop stop running process #

Documentation

📖
Documentation
https://www.mock-server.com/
📖
GettingStarted
https://www.mock-server.com/mock_server/getting_started.html

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/mockserver/refs/heads/main/openapi/mockserver-control-api-openapi.yml

SDKs

📦
GitHubRepository
https://github.com/mock-server/mockserver

Other Resources

🔗
APIsJSON
https://raw.githubusercontent.com/api-evangelist/mockserver/refs/heads/main/apis.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/mockserver-control-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

mockserver-control-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: MockServer Control API
  version: 5.15.x
  description: MockServer enables easy mocking of any system you integrate with via HTTP or HTTPS with clients written in Java, JavaScript and Ruby and a simple REST API (as shown below).
  license:
    url: https://github.com/mock-server/mockserver/blob/master/LICENSE.md
    name: Apache 2.0
servers:
- url: http://localhost:1080/
- url: https://localhost:1080/
tags:
- name: Control
  description: Manage state or process (both MockServer & MockServer Proxy)
paths:
  /mockserver/clear:
    put:
      tags:
      - Control
      summary: clears expectations and recorded requests that match the request matcher
      responses:
        '200':
          description: expectations and recorded requests cleared
        '400':
          description: incorrect request format
      parameters:
      - in: query
        name: type
        schema:
          type: string
          enum:
          - all
          - log
          - expectations
          default: all
        required: false
        description: specifies the type of information to clear, default if not specified is "all", supported values are "all", "log", "expectations"
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/RequestDefinition'
              - $ref: '#/components/schemas/ExpectationId'
        description: request used to match expectations and record requests to clear
      operationId: putMockserverClear
      x-operation-id-source: derived
  /mockserver/reset:
    put:
      tags:
      - Control
      summary: clears all expectations and recorded requests
      responses:
        '200':
          description: expectations and recorded requests cleared
      operationId: putMockserverReset
      x-operation-id-source: derived
  /mockserver/retrieve:
    put:
      tags:
      - Control
      summary: retrieve recorded requests, active expectations, recorded expectations or log…
      parameters:
      - in: query
        name: format
        schema:
          type: string
          enum:
          - java
          - json
          - log_entries
        required: false
        description: changes response format, default if not specified is "json", supported values are "java", "json", "log_entries"
      - in: query
        name: type
        schema:
          type: string
          enum:
          - logs
          - requests
          - request_responses
          - recorded_expectations
          - active_expectations
        required: false
        description: specifies the type of object that is retrieve, default if not specified is "requests", supported values are "logs", "requests", "recorded_expectations", "active_expectations"
      responses:
        '200':
          description: recorded requests or active expectations returned
          content:
            application/json:
              schema:
                oneOf:
                - type: array
                  additionalProperties: false
                  items:
                    $ref: '#/components/schemas/Expectation'
                - type: array
                  additionalProperties: false
                  items:
                    $ref: '#/components/schemas/HttpRequest'
                - type: array
                  additionalProperties: false
                  items:
                    $ref: '#/components/schemas/HttpRequestAndHttpResponse'
            application/java:
              schema:
                type: string
                description: Java code for the list of either Expectations or HttpResponses
            text/plain:
              schema:
                type: string
                description: List of recorded log messages
        '400':
          description: incorrect request format
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestDefinition'
        description: request used to match which recorded requests, expectations or log messages to return, an empty body matches all requests, expectations or log messages
      operationId: putMockserverRetrieve
      x-operation-id-source: derived
  /mockserver/status:
    put:
      tags:
      - Control
      summary: return listening ports
      responses:
        '200':
          description: MockServer is running and listening on the listed ports
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ports'
      operationId: putMockserverStatus
      x-operation-id-source: derived
  /mockserver/bind:
    put:
      tags:
      - Control
      summary: bind additional listening ports
      description: only supported on Netty version
      responses:
        '200':
          description: 'listening on additional requested ports, note: the response ony contains ports added for the request, to list all ports use /status'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ports'
        '400':
          description: incorrect request format
        '406':
          description: unable to bind to ports (i.e. already bound or JVM process doesn't have permission)
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Ports'
        description: list of ports to bind to, where 0 indicates dynamically bind to any available port
        required: true
      operationId: putMockserverBind
      x-operation-id-source: derived
  /mockserver/stop:
    put:
      tags:
      - Control
      summary: stop running process
      description: only supported on Netty version
      responses:
        '200':
          description: MockServer process is stopping
      operationId: putMockserverStop
      x-operation-id-source: derived
components:
  schemas:
    SocketAddress:
      description: remote address to send request to, only used for request overrides
      type: object
      additionalProperties: false
      properties:
        host:
          type: string
        port:
          type: integer
        scheme:
          enum:
          - HTTP
          - HTTPS
    StringOrJsonSchema:
      description: string value that can be support nottable, optional or a json schema
      oneOf:
      - type: string
      - type: object
        additionalProperties: false
        properties:
          not:
            type: boolean
          optional:
            type: boolean
          value:
            type: string
          schema:
            $ref: http://json-schema.org/draft-04/schema
          parameterStyle:
            type: string
            enum:
            - SIMPLE
            - SIMPLE_EXPLODED
            - LABEL
            - LABEL_EXPLODED
            - MATRIX
            - MATRIX_EXPLODED
            - FORM_EXPLODED
            - FORM
            - SPACE_DELIMITED_EXPLODED
            - SPACE_DELIMITED
            - PIPE_DELIMITED_EXPLODED
            - PIPE_DELIMITED
            - DEEP_OBJECT
    OpenAPIDefinition:
      description: open api or swagger request matcher
      type: object
      additionalProperties: false
      properties:
        specUrlOrPayload:
          type: string
        operationId:
          type: string
    Ports:
      description: list of ports
      type: object
      additionalProperties: false
      properties:
        ports:
          items:
            type: number
          type: array
    Body:
      description: request body matcher
      anyOf:
      - type: object
        description: binary body matcher
        additionalProperties: false
        properties:
          not:
            type: boolean
          type:
            enum:
            - BINARY
          base64Bytes:
            type: string
          contentType:
            type: string
      - type: object
        description: json body matcher
        additionalProperties: false
        properties:
          not:
            type: boolean
          type:
            enum:
            - JSON
          json:
            type: string
          contentType:
            type: string
          matchType:
            enum:
            - STRICT
            - ONLY_MATCHING_FIELDS
      - type: object
        description: json matching fields body matcher
        additionalProperties: true
      - type: object
        description: json schema body matcher
        additionalProperties: false
        properties:
          not:
            type: boolean
          type:
            enum:
            - JSON_SCHEMA
          jsonSchema:
            $ref: http://json-schema.org/draft-04/schema
      - type: object
        description: JSON path body matcher
        additionalProperties: false
        properties:
          not:
            type: boolean
          type:
            enum:
            - JSON_PATH
          jsonPath:
            type: string
      - type: object
        description: parameter body matcher
        additionalProperties: false
        properties:
          not:
            type: boolean
          type:
            enum:
            - PARAMETERS
          parameters:
            $ref: '#/components/schemas/KeyToMultiValue'
      - type: object
        description: regex body matcher
        additionalProperties: false
        properties:
          not:
            type: boolean
          type:
            enum:
            - REGEX
          regex:
            type: string
      - type: object
        description: string body matcher
        additionalProperties: false
        properties:
          not:
            type: boolean
          type:
            enum:
            - STRING
          string:
            type: string
          contentType:
            type: string
          subString:
            type: boolean
      - type: string
        description: substring body matcher
      - type: object
        description: xml body matcher
        additionalProperties: false
        properties:
          not:
            type: boolean
          type:
            enum:
            - XML
          xml:
            type: string
          contentType:
            type: string
      - type: object
        description: xml schema body matcher
        additionalProperties: false
        properties:
          not:
            type: boolean
          type:
            enum:
            - XML_SCHEMA
          xmlSchema:
            type: string
      - type: object
        description: xpath body matcher
        additionalProperties: false
        properties:
          not:
            type: boolean
          type:
            enum:
            - XPATH
          xpath:
            type: string
    HttpResponse:
      description: response to return
      type: object
      additionalProperties: false
      properties:
        delay:
          $ref: '#/components/schemas/Delay'
        body:
          $ref: '#/components/schemas/BodyWithContentType'
        cookies:
          $ref: '#/components/schemas/KeyToValue'
        connectionOptions:
          $ref: '#/components/schemas/ConnectionOptions'
        headers:
          $ref: '#/components/schemas/KeyToMultiValue'
        statusCode:
          type: integer
        reasonPhrase:
          type: string
    HttpClassCallback:
      description: class callback
      type: object
      additionalProperties: false
      properties:
        delay:
          $ref: '#/components/schemas/Delay'
        callbackClass:
          type: string
    Protocol:
      description: protocol matcher
      enum:
      - HTTP_1_1
      - HTTP_2
    HttpError:
      description: error behaviour
      type: object
      additionalProperties: false
      properties:
        delay:
          $ref: '#/components/schemas/Delay'
        dropConnection:
          type: boolean
        responseBytes:
          type: string
    Delay:
      description: response delay
      type: object
      additionalProperties: false
      properties:
        timeUnit:
          type: string
        value:
          type: integer
    KeyToMultiValue:
      oneOf:
      - type: array
        additionalProperties: false
        items:
          type: object
          additionalProperties: false
          properties:
            name:
              type: string
            values:
              type: array
              additionalProperties: false
              items:
                type: string
      - type: object
        additionalProperties: true
        properties:
          keyMatchStyle:
            type: string
            enum:
            - MATCHING_KEY
            - SUB_SET
            default: SUB_SET
    BodyWithContentType:
      description: response body
      anyOf:
      - type: object
        description: binary response body
        additionalProperties: false
        properties:
          not:
            type: boolean
          type:
            enum:
            - BINARY
          base64Bytes:
            type: string
          contentType:
            type: string
      - type: object
        description: json response body
        additionalProperties: false
        properties:
          not:
            type: boolean
          type:
            enum:
            - JSON
          json:
            type: string
          contentType:
            type: string
      - type: object
        description: json response body
        additionalProperties: true
      - type: object
        description: string response body
        additionalProperties: false
        properties:
          not:
            type: boolean
          type:
            enum:
            - STRING
          string:
            type: string
          contentType:
            type: string
      - type: string
        description: string response body
      - type: object
        description: xml response body
        additionalProperties: false
        properties:
          not:
            type: boolean
          type:
            enum:
            - XML
          xml:
            type: string
          contentType:
            type: string
    KeyToValue:
      oneOf:
      - type: array
        additionalProperties: false
        items:
          type: object
          properties:
            name:
              type: string
            value:
              type: string
      - type: object
        additionalProperties: true
    HttpOverrideForwardedRequest:
      description: override forwarded request
      oneOf:
      - type: object
        additionalProperties: false
        properties:
          delay:
            $ref: '#/components/schemas/Delay'
          requestOverride:
            $ref: '#/components/schemas/HttpRequest'
          requestModifier:
            type: object
            additionalProperties: false
            properties:
              path:
                type: object
                additionalProperties: false
                properties:
                  regex:
                    type: string
                  substitution:
                    type: string
              queryStringParameters:
                type: object
                additionalProperties: false
                properties:
                  add:
                    $ref: '#/components/schemas/KeyToMultiValue'
                  replace:
                    $ref: '#/components/schemas/KeyToMultiValue'
                  remove:
                    type: array
                    additionalProperties: false
                    items:
                      type: string
              headers:
                type: object
                additionalProperties: false
                properties:
                  add:
                    $ref: '#/components/schemas/KeyToMultiValue'
                  replace:
                    $ref: '#/components/schemas/KeyToMultiValue'
                  remove:
                    type: array
                    additionalProperties: false
                    items:
                      type: string
              cookies:
                type: object
                additionalProperties: false
                properties:
                  add:
                    $ref: '#/components/schemas/KeyToValue'
                  replace:
                    $ref: '#/components/schemas/KeyToValue'
                  remove:
                    type: array
                    additionalProperties: false
                    items:
                      type: string
          responseOverride:
            $ref: '#/components/schemas/HttpResponse'
          responseModifier:
            type: object
            additionalProperties: false
            properties:
              headers:
                type: object
                additionalProperties: false
                properties:
                  add:
                    $ref: '#/components/schemas/KeyToMultiValue'
                  replace:
                    $ref: '#/components/schemas/KeyToMultiValue'
                  remove:
                    type: array
                    additionalProperties: false
                    items:
                      type: string
              cookies:
                type: object
                additionalProperties: false
                properties:
                  add:
                    $ref: '#/components/schemas/KeyToValue'
                  replace:
                    $ref: '#/components/schemas/KeyToValue'
                  remove:
                    type: array
                    additionalProperties: false
                    items:
                      type: string
      - type: object
        additionalProperties: false
        properties:
          delay:
            $ref: '#/components/schemas/Delay'
          httpRequest:
            $ref: '#/components/schemas/HttpRequest'
          httpResponse:
            $ref: '#/components/schemas/HttpResponse'
    HttpTemplate:
      description: template to generate response / request
      type: object
      additionalProperties: false
      properties:
        delay:
          $ref: '#/components/schemas/Delay'
        templateType:
          enum:
          - VELOCITY
          - JAVASCRIPT
          - MUSTACHE
        template:
          type: string
    HttpRequest:
      description: request properties matcher
      type: object
      additionalProperties: false
      properties:
        secure:
          type: boolean
        keepAlive:
          type: boolean
        method:
          $ref: '#/components/schemas/StringOrJsonSchema'
        path:
          $ref: '#/components/schemas/StringOrJsonSchema'
        pathParameters:
          $ref: '#/components/schemas/KeyToMultiValue'
        queryStringParameters:
          $ref: '#/components/schemas/KeyToMultiValue'
        body:
          $ref: '#/components/schemas/Body'
        headers:
          $ref: '#/components/schemas/KeyToMultiValue'
        cookies:
          $ref: '#/components/schemas/KeyToValue'
        socketAddress:
          $ref: '#/components/schemas/SocketAddress'
        protocol:
          $ref: '#/components/schemas/Protocol'
    TimeToLive:
      description: time expectation is valid for
      type: object
      additionalProperties: false
      properties:
        timeUnit:
          enum:
          - DAYS
          - HOURS
          - MINUTES
          - SECONDS
          - MILLISECONDS
          - MICROSECONDS
          - NANOSECONDS
        timeToLive:
          type: integer
        unlimited:
          type: boolean
    ConnectionOptions:
      description: connection options
      type: object
      additionalProperties: false
      properties:
        suppressContentLengthHeader:
          type: boolean
        contentLengthHeaderOverride:
          type: integer
        suppressConnectionHeader:
          type: boolean
        chunkSize:
          type: integer
        keepAliveOverride:
          type: boolean
        closeSocket:
          type: boolean
        closeSocketDelay:
          $ref: '#/components/schemas/Delay'
    ExpectationId:
      description: pointer to existing expectation
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
      required:
      - id
    HttpRequestAndHttpResponse:
      description: request and response
      type: object
      additionalProperties: false
      properties:
        httpRequest:
          $ref: '#/components/schemas/HttpRequest'
        httpResponse:
          $ref: '#/components/schemas/HttpResponse'
        timestamp:
          type: string
    Expectation:
      description: expectation
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        priority:
          type: integer
        httpRequest:
          $ref: '#/components/schemas/RequestDefinition'
        httpResponse:
          $ref: '#/components/schemas/HttpResponse'
        httpResponseTemplate:
          $ref: '#/components/schemas/HttpTemplate'
        httpResponseClassCallback:
          $ref: '#/components/schemas/HttpClassCallback'
        httpResponseObjectCallback:
          $ref: '#/components/schemas/HttpObjectCallback'
        httpForward:
          $ref: '#/components/schemas/HttpForward'
        httpForwardTemplate:
          $ref: '#/components/schemas/HttpTemplate'
        httpForwardClassCallback:
          $ref: '#/components/schemas/HttpClassCallback'
        httpForwardObjectCallback:
          $ref: '#/components/schemas/HttpObjectCallback'
        httpOverrideForwardedRequest:
          $ref: '#/components/schemas/HttpOverrideForwardedRequest'
        httpError:
          $ref: '#/components/schemas/HttpError'
        times:
          $ref: '#/components/schemas/Times'
        timeToLive:
          $ref: '#/components/schemas/TimeToLive'
      oneOf:
      - required:
        - httpResponse
      - required:
        - httpResponseTemplate
      - required:
        - httpResponseClassCallback
      - required:
        - httpResponseObjectCallback
      - required:
        - httpForward
      - required:
        - httpForwardTemplate
      - required:
        - httpForwardClassCallback
      - required:
        - httpForwardObjectCallback
      - required:
        - httpOverrideForwardedRequest
      - required:
        - httpError
    RequestDefinition:
      description: request definition
      oneOf:
      - $ref: '#/components/schemas/HttpRequest'
      - $ref: '#/components/schemas/OpenAPIDefinition'
    Times:
      description: number of responses
      type: object
      additionalProperties: false
      properties:
        remainingTimes:
          type: integer
        unlimited:
          type: boolean
    HttpObjectCallback:
      description: object / method callback
      type: object
      additionalProperties: false
      properties:
        delay:
          $ref: '#/components/schemas/Delay'
        clientId:
          type: string
        responseCallback:
          type: boolean
    HttpForward:
      description: host and port to forward to
      type: object
      additionalProperties: false
      properties:
        delay:
          $ref: '#/components/schemas/Delay'
        host:
          type: string
        port:
          type: integer
        scheme:
          enum:
          - HTTP
          - HTTPS