Response Assertions and Payload Validation

An assertion is a rule that tells PulseGuard what a healthy response looks like beyond just “the server replied.” Without assertions, a monitor reports UP any time the server returns a response — even if that response is an error page, a maintenance splash screen, or a JSON payload with "status": "degraded". Assertions close that gap by letting you define exactly what the response must contain for the check to pass. When an assertion fails, PulseGuard treats the check as DOWN regardless of the HTTP status code. This catches silent failures that would otherwise go undetected: a 200 OK that contains an error message, a JSON API that returns the wrong field value, or a page that loads but doesn’t render expected content.

Assertion Types

PulseGuard supports five assertion types that you can combine in a single expectation object. All provided assertions must pass for the check to report UP.

Status Codes Check

Verify that the response returns one of the expected HTTP status codes. If the server returns any code not in the list, the check fails.

{
  "expectation": {
    "status_codes": [200]
  }
}

Pass an array of integers to accept multiple valid codes — for example, [200, 201] when an endpoint may return either.

Body Contains

Check that the response body includes a specific substring. The check passes only if the string is found anywhere in the body.

{
  "expectation": {
    "body_contains": "\"status\":\"ok\""
  }
}

Use this for a quick sanity check when you know a healthy response always contains a particular word, phrase, or key.

Body Excludes

Check that the response body does not contain a specific substring. The check fails if the forbidden string is found.

{
  "expectation": {
    "body_excludes": "maintenance mode"
  }
}

This is useful for detecting error states or maintenance pages that return a 200 status code alongside error content.

Body Regex

Apply a regular expression against the full response body text. The check passes only if the regex finds a match anywhere in the body.

{
  "expectation": {
    "body_regex": "\"status\":\\s*\"ok\""
  }
}

Body regex is useful for confirming that key content is present in an HTML page (e.g., a product name, a version string, or a specific element) or that a plain-text or JSON response contains the expected pattern.

Escape special JSON characters in your regex string. A literal " in the pattern becomes \" and a backslash becomes \\.

JSON Path Assertions

Evaluate one or more path expressions against the parsed response body and compare each result to an expected value. This is the most precise assertion type for JSON API responses. The json_path field accepts an object where each key is a dot-notation path (e.g. data.status) and each value is the string the selected field must equal.

{
  "expectation": {
    "json_path": {
      "data.status": "healthy",
      "database.connected": "true"
    }
  }
}

For richer comparisons — including contains, not_equals, and not_contains operators — use json_assertions instead. Each entry specifies a JSONPath selector (with optional $. prefix), an operator, and the expected value.

{
  "expectation": {
    "json_assertions": [
      { "path": "$.status",          "operator": "equals",       "value": "ok" },
      { "path": "$.version",         "operator": "contains",     "value": "2." },
      { "path": "$.errors",          "operator": "equals",       "value": "0" }
    ]
  }
}

Supported operators: equals (==, ===), not_equals (!=, !==), contains, not_contains.

Full Expectation Object

You can combine multiple assertion types in a single expectation object. All assertions must pass for the check to report UP.

{
  "expectation": {
    "status_codes": [200],
    "body_regex": "status.*ok",
    "json_path": {
      "data.healthy": "true"
    }
  }
}

Configure the expectation field when creating or updating a monitor via the dashboard form, the CLI pulse monitors apply command, or the REST API. When using the API, pass expectation as a JSON object in the request body.

Configuring Assertions in the Dashboard

Open the monitor configuration

Navigate to Monitors, click on the monitor you want to configure, and select Edit.

Scroll to the Assertions section

Find the Response Assertions panel below the request configuration fields.

Set the expected status code

Enter the HTTP status code(s) you expect (e.g., 200). Leave blank to accept any response.

Add a body check or JSON assertion

Enter a string in the Body Contains field, a regex pattern in Body Regex, or switch to the JSON tab to specify path-based assertions.

Test before saving

Use the Payload Regex Tester tool to validate your pattern against a sample response body before attaching it to a live monitor. See the Tools overview for details.

Save the monitor

Click Save Changes. PulseGuard applies the new assertions starting from the very next check cycle.

Assertions via the CLI

When managing monitors as code with the pulse CLI, define assertions inline in your YAML manifest:

monitors:
  - name: API Health Check
    url: https://api.example.com/health
    type: HTTP
    method: GET
    interval: 60
    timeout: 10
    expectation:
      status_codes: [200]
      json_path:
        status: "ok"

  - name: Homepage Content Check
    url: https://example.com
    type: HTTP
    method: GET
    interval: 300
    timeout: 10
    expectation:
      status_codes: [200]
      body_contains: "Welcome to Example"

Apply your manifest with pulse monitors apply to sync the configuration to PulseGuard.

Common Assertion Patterns

Use Case	Field	Example
Confirm API returns success status	`status_codes`	`[200]`
Accept multiple valid status codes	`status_codes`	`[200, 201]`
Check health endpoint contains text	`body_contains`	`"status":"ok"`
Detect maintenance splash page	`body_excludes`	`maintenance mode`
Verify page renders expected content	`body_regex`	`Add to Cart`
Check a JSON field value	`json_path`	`{ "database.connected": "true" }`
Validate API version string	`json_assertions`	`$.version contains "2."`
Check nested array value	`json_assertions`	`$.services[0].healthy equals "true"`

Error Reasons

When an assertion fails, PulseGuard records an errorReason alongside the DOWN status. This appears in the event log and is included in alert notifications so you can immediately distinguish an assertion failure from a connection timeout or DNS error.

Overly broad regex patterns can produce false positives if error responses happen to contain matching text. Always test your patterns with the Payload Regex Tester before deploying them on production monitors.

Overview

Full monitor configuration reference and field descriptions.

Monitor Types

Assertion support varies by monitor type — HTTP, GraphQL, WebSocket, and more.

Payload Regex Tester

Test regex patterns and JSON path selectors against live or sample payloads.

Get Started

Monitors

Alerting

Status Pages

Private Probes

Tools

Response Assertions and Payload Validation

Assertion Types

Status Codes Check

Body Contains

Body Excludes

Body Regex

JSON Path Assertions

Full Expectation Object

Configuring Assertions in the Dashboard

Assertions via the CLI

Common Assertion Patterns

Error Reasons

Overview

Monitor Types

Payload Regex Tester

​Assertion Types

​Status Codes Check

​Body Contains

​Body Excludes

​Body Regex

​JSON Path Assertions

​Full Expectation Object

​Configuring Assertions in the Dashboard

​Assertions via the CLI

​Common Assertion Patterns

​Error Reasons

​Related Pages

Overview

Monitor Types

Payload Regex Tester

Assertion Types

Status Codes Check

Body Contains

Body Excludes

Body Regex

JSON Path Assertions

Full Expectation Object

Configuring Assertions in the Dashboard

Assertions via the CLI

Common Assertion Patterns

Error Reasons

Related Pages