> ## Documentation Index
> Fetch the complete documentation index at: https://pulse-41cf5b0d.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Response Assertions and Payload Validation
> Define expectations on HTTP status codes, response body content, JSON fields, and regex patterns to detect silent failures.
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.
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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`.
```json theme={null}
{
"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
Navigate to **Monitors**, click on the monitor you want to configure, and select **Edit**.
Find the **Response Assertions** panel below the request configuration fields.
Enter the HTTP status code(s) you expect (e.g., `200`). Leave blank to accept any response.
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.
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](/tools/overview) for details.
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:
```yaml theme={null}
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.
## Related Pages
Full monitor configuration reference and field descriptions.
Assertion support varies by monitor type — HTTP, GraphQL, WebSocket, and more.
Test regex patterns and JSON path selectors against live or sample payloads.