---
title: "register a breakpoint matcher"
method: PUT
path: "/mockserver/breakpoint/matcher"
tags: ["control"]
---

# register a breakpoint matcher

`PUT /mockserver/breakpoint/matcher`

## Request

- Base URL: `http://localhost:1080`
- URL: `http://localhost:1080/mockserver/breakpoint/matcher`
- Auth: none declared

Registers a request matcher that activates breakpoints for forwarded/proxied exchanges. When a proxied request matches the httpRequest definition, the exchange is paused at each specified phase. Returns the assigned matcher id and the registered phases. The clientId field is required — paused items are dispatched over the callback WebSocket (/_mockserver_callback_websocket) to the owning client for interactive resolution.

## Request body

- object
  - `httpRequest` HttpRequest, required: request properties matcher
    - `secure` boolean
    - `keepAlive` boolean
    - `method` union: string value that can be support nottable, optional or a json schema
      - string
      - object
        - `not` boolean
        - `optional` boolean
        - `value` string
        - `schema` Schema (unresolved $ref)
        - `parameterStyle` 'SIMPLE' | 'SIMPLE_EXPLODED' | 'LABEL' | 'LABEL_EXPLODED' | 'MATRIX' | 'MATRIX_EXPLODED' | 'FORM_EXPLODED' | 'FORM' | 'SPACE_DELIMITED_EXPLODED' | 'SPACE_DELIMITED' | 'PIPE_DELIMITED_EXPLODED' | 'PIPE_DELIMITED' | 'DEEP_OBJECT'
    - `path` union: string value that can be support nottable, optional or a json schema
      - string
      - object
        - `not` boolean
        - `optional` boolean
        - `value` string
        - `schema` Schema (unresolved $ref)
        - `parameterStyle` 'SIMPLE' | 'SIMPLE_EXPLODED' | 'LABEL' | 'LABEL_EXPLODED' | 'MATRIX' | 'MATRIX_EXPLODED' | 'FORM_EXPLODED' | 'FORM' | 'SPACE_DELIMITED_EXPLODED' | 'SPACE_DELIMITED' | 'PIPE_DELIMITED_EXPLODED' | 'PIPE_DELIMITED' | 'DEEP_OBJECT'
    - `pathParameters` union
      - object[]
        - `name` string
        - `values` string[]
      - object
        - `keyMatchStyle` 'MATCHING_KEY' | 'SUB_SET'
    - `queryStringParameters` union
      - object[]
        - `name` string
        - `values` string[]
      - object
        - `keyMatchStyle` 'MATCHING_KEY' | 'SUB_SET'
    - `body` union: request body matcher
      - object: binary body matcher
        - `not` boolean
        - `type` 'BINARY'
        - `base64Bytes` string
        - `contentType` string
      - object: json body matcher
        - `not` boolean
        - `type` 'JSON'
        - `json` string
        - `contentType` string
        - `matchType` 'STRICT' | 'ONLY_MATCHING_FIELDS'
        - `matchNumbersAsStrings` boolean
      - object: json matching fields body matcher
      - object: json schema body matcher
        - `not` boolean
        - `type` 'JSON_SCHEMA'
        - `jsonSchema` Schema (unresolved $ref)
      - object: JSON path body matcher
        - `not` boolean
        - `type` 'JSON_PATH'
        - `jsonPath` string
      - object: parameter body matcher
        - `not` boolean
        - `type` 'PARAMETERS'
        - `parameters` union
          - object[]
            - `name` string
            - `values` string[]
          - object
            - `keyMatchStyle` 'MATCHING_KEY' | 'SUB_SET'
      - object: regex body matcher
        - `not` boolean
        - `type` 'REGEX'
        - `regex` string
      - object: string body matcher
        - `not` boolean
        - `type` 'STRING'
        - `string` string
        - `contentType` string
        - `subString` boolean
      - string: substring body matcher
      - object: xml body matcher
        - `not` boolean
        - `type` 'XML'
        - `xml` string
        - `contentType` string
      - object: xml schema body matcher
        - `not` boolean
        - `type` 'XML_SCHEMA'
        - `xmlSchema` string
      - object: xpath body matcher
        - `not` boolean
        - `type` 'XPATH'
        - `xpath` string
      - object: all-of body matcher — matches only when every one of its component body matchers matches the same request body
        - `not` boolean
        - `optional` boolean
        - `type` 'ALL_OF'
        - `bodyAllOf` Body[], required
      - object: binary body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'BINARY'
        - `base64Bytes` string
        - `contentType` string
      - object: json body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'JSON'
        - `json` string
        - `contentType` string
        - `matchType` 'STRICT' | 'ONLY_MATCHING_FIELDS'
        - `matchNumbersAsStrings` boolean
      - object: json schema body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'JSON_SCHEMA'
        - `jsonSchema` Schema (unresolved $ref)
      - object: JSON path body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'JSON_PATH'
        - `jsonPath` string
      - object: parameter body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'PARAMETERS'
        - `parameters` union
          - object[]
            - `name` string
            - `values` string[]
          - object
            - `keyMatchStyle` 'MATCHING_KEY' | 'SUB_SET'
      - object: multipart form-data body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'MULTIPART'
        - `fields` union
          - object[]
            - `name` string
            - `values` string[]
          - object
            - `keyMatchStyle` 'MATCHING_KEY' | 'SUB_SET'
        - `filenames` union
          - object[]
            - `name` string
            - `values` string[]
          - object
            - `keyMatchStyle` 'MATCHING_KEY' | 'SUB_SET'
        - `partContentTypes` union
          - object[]
            - `name` string
            - `values` string[]
          - object
            - `keyMatchStyle` 'MATCHING_KEY' | 'SUB_SET'
      - object: regex body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'REGEX'
        - `regex` string
      - object: string body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'STRING'
        - `string` string
        - `contentType` string
        - `subString` boolean
      - object: xml body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'XML'
        - `xml` string
        - `contentType` string
      - object: xml schema body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'XML_SCHEMA'
        - `xmlSchema` string
      - object: xpath body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'XPATH'
        - `xpath` string
      - object: JSON-RPC body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'JSON_RPC'
        - `method` string
        - `paramsSchema` string
      - object: GraphQL body matcher
        - `not` boolean
        - `optional` boolean
        - `type` 'GRAPHQL', required
        - `query` string, required
        - `operationName` string
        - `variablesSchema` string
    - `headers` union
      - object[]
        - `name` string
        - `values` string[]
      - object
        - `keyMatchStyle` 'MATCHING_KEY' | 'SUB_SET'
    - `cookies` union
      - object[]
        - `name` string
        - `value` string
      - object
    - `socketAddress` SocketAddress: remote address to send request to, only used for request overrides
      - `host` string
      - `port` integer
      - `scheme` 'HTTP' | 'HTTPS'
    - `protocol` 'HTTP_1_1' | 'HTTP_2' | 'HTTP_3': protocol matcher
    - `jwt` Jwt: JSON Web Token (JWT) request matcher — decodes the token carried in a request header (no signature verification) and matches its claims
      - `header` string: name of the request header carrying the JWT (default 'authorization')
      - `scheme` string: authentication scheme prefix stripped from the header value before decoding (default 'Bearer')
      - `claims` object: claim-value criteria; each value may be an exact string, regex or '!'-negated form
      - `issuer` union: string value that can be support nottable, optional or a json schema
        - string
        - object
          - `not` boolean
          - `optional` boolean
          - `value` string
          - `schema` Schema (unresolved $ref)
          - `parameterStyle` 'SIMPLE' | 'SIMPLE_EXPLODED' | 'LABEL' | 'LABEL_EXPLODED' | 'MATRIX' | 'MATRIX_EXPLODED' | 'FORM_EXPLODED' | 'FORM' | 'SPACE_DELIMITED_EXPLODED' | 'SPACE_DELIMITED' | 'PIPE_DELIMITED_EXPLODED' | 'PIPE_DELIMITED' | 'DEEP_OBJECT'
      - `audience` union: string value that can be support nottable, optional or a json schema
        - string
        - object
          - `not` boolean
          - `optional` boolean
          - `value` string
          - `schema` Schema (unresolved $ref)
          - `parameterStyle` 'SIMPLE' | 'SIMPLE_EXPLODED' | 'LABEL' | 'LABEL_EXPLODED' | 'MATRIX' | 'MATRIX_EXPLODED' | 'FORM_EXPLODED' | 'FORM' | 'SPACE_DELIMITED_EXPLODED' | 'SPACE_DELIMITED' | 'PIPE_DELIMITED_EXPLODED' | 'PIPE_DELIMITED' | 'DEEP_OBJECT'
      - `algorithm` union: string value that can be support nottable, optional or a json schema
        - string
        - object
          - `not` boolean
          - `optional` boolean
          - `value` string
          - `schema` Schema (unresolved $ref)
          - `parameterStyle` 'SIMPLE' | 'SIMPLE_EXPLODED' | 'LABEL' | 'LABEL_EXPLODED' | 'MATRIX' | 'MATRIX_EXPLODED' | 'FORM_EXPLODED' | 'FORM' | 'SPACE_DELIMITED_EXPLODED' | 'SPACE_DELIMITED' | 'PIPE_DELIMITED_EXPLODED' | 'PIPE_DELIMITED' | 'DEEP_OBJECT'
    - `not` boolean
    - `respondBeforeBody` boolean: If true, MockServer responds to a matching request before consuming its body and may close the connection. Required: the matcher must not specify a body matcher, and the action must be RESPONSE or ERROR.
  - `phases` string[], required: phases at which matching exchanges will be paused
  - `clientId` string, required: Required. The callback WebSocket client id to dispatch paused items to for interactive resolution. Must be a connected callback client.

## Response `200`

matcher registered successfully

- object
  - `id` string: unique id assigned to this matcher
  - `phases` string[]
  - `clientId` string: echoed back from the request

## Other responses

- `400`: validation error (missing httpRequest, empty phases, unknown phase value, or missing/blank clientId)

---

[API](https://skmtc.dev/mock-server/apis/mockserver-api.md) · [All operations](https://skmtc.dev/mock-server/apis/mockserver-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mock-server/apis/mockserver-api/revisions/9239b693996e?raw)