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

# HTTP Assertions

> Define health criteria for DevHelm HTTP monitors with status code, response time, body, JSON path, header, TLS, and redirect assertions

Assertions define what "healthy" means for your HTTP monitor. Each check evaluates all assertions and records a pass or fail result. A failed `fail`-severity assertion causes the check to fail; a failed `warn`-severity assertion records a `DEGRADED` hint without triggering a `DOWN` incident.

## Severity levels

| Severity | Behavior                                                                                    |
| -------- | ------------------------------------------------------------------------------------------- |
| `fail`   | Check is marked as failed. Contributes to incident trigger rules.                           |
| `warn`   | Check passes but records a `DEGRADED` severity hint. Can trigger `degraded` incident rules. |

## Assertion types

### status\_code

Validate the HTTP response status code.

| Field      | Type   | Required | Description                                   |
| ---------- | ------ | -------- | --------------------------------------------- |
| `expected` | string | Yes      | Expected status code (e.g., `"200"`, `"2xx"`) |
| `operator` | string | Yes      | `equals`, `contains`, `matches`, `range`      |

```yaml theme={null}
assertions:
  - config:
      type: status_code
      expected: "200"
      operator: equals
    severity: fail
```

Use `range` to match a range of status codes:

```yaml theme={null}
assertions:
  - config:
      type: status_code
      expected: "200-299"
      operator: range
    severity: fail
```

### response\_time

Fail when response latency exceeds a threshold.

| Field         | Type    | Required | Description                                      |
| ------------- | ------- | -------- | ------------------------------------------------ |
| `thresholdMs` | integer | Yes      | Maximum acceptable response time in milliseconds |

```yaml theme={null}
assertions:
  - config:
      type: response_time
      thresholdMs: 2000
    severity: fail
```

### response\_time\_warn

Record a degraded hint when response time is elevated but not critical.

| Field    | Type    | Required | Description                       |
| -------- | ------- | -------- | --------------------------------- |
| `warnMs` | integer | Yes      | Warning threshold in milliseconds |

```yaml theme={null}
assertions:
  - config:
      type: response_time_warn
      warnMs: 1000
    severity: warn
```

<Tip>
  Use `response_time` with `fail` severity for outage detection and `response_time_warn` with `warn` severity for early degradation alerts.
</Tip>

### body\_contains

Check that the response body contains a specific substring.

| Field       | Type   | Required | Description                             |
| ----------- | ------ | -------- | --------------------------------------- |
| `substring` | string | Yes      | Text to search for in the response body |

```yaml theme={null}
assertions:
  - config:
      type: body_contains
      substring: '"status":"ok"'
    severity: fail
```

### json\_path

Extract a value from a JSON response using JSONPath and compare it.

| Field      | Type   | Required | Description                                                           |
| ---------- | ------ | -------- | --------------------------------------------------------------------- |
| `path`     | string | Yes      | JSONPath expression (e.g., `$.status`)                                |
| `expected` | string | Yes      | Expected value                                                        |
| `operator` | string | Yes      | `equals`, `contains`, `less_than`, `greater_than`, `matches`, `range` |

```yaml theme={null}
assertions:
  - config:
      type: json_path
      path: $.status
      expected: healthy
      operator: equals
    severity: fail
```

### header\_value

Validate a response header value.

| Field        | Type   | Required | Description                                                           |
| ------------ | ------ | -------- | --------------------------------------------------------------------- |
| `headerName` | string | Yes      | Response header name                                                  |
| `expected`   | string | Yes      | Expected value                                                        |
| `operator`   | string | Yes      | `equals`, `contains`, `less_than`, `greater_than`, `matches`, `range` |

```yaml theme={null}
assertions:
  - config:
      type: header_value
      headerName: content-type
      expected: application/json
      operator: contains
    severity: fail
```

### regex\_body

Match the response body against a regular expression.

| Field     | Type   | Required | Description                |
| --------- | ------ | -------- | -------------------------- |
| `pattern` | string | Yes      | Regular expression pattern |

```yaml theme={null}
assertions:
  - config:
      type: regex_body
      pattern: '"version":\s*"\d+\.\d+\.\d+"'
    severity: fail
```

### ssl\_expiry

Alert before TLS certificates expire. Requires `verifyTls: true` (the default).

| Field              | Type    | Required | Description               |
| ------------------ | ------- | -------- | ------------------------- |
| `minDaysRemaining` | integer | Yes      | Minimum days until expiry |

```yaml theme={null}
assertions:
  - config:
      type: ssl_expiry
      minDaysRemaining: 30
    severity: warn
  - config:
      type: ssl_expiry
      minDaysRemaining: 7
    severity: fail
```

<Tip>
  Stack two `ssl_expiry` assertions: `warn` at 30 days for early notice, `fail` at 7 days for urgent action. See the [SSL certificate monitoring guide](/guides/ssl-certificate-monitoring).
</Tip>

### response\_size

Limit the response body size.

| Field      | Type    | Required | Description                    |
| ---------- | ------- | -------- | ------------------------------ |
| `maxBytes` | integer | Yes      | Maximum response size in bytes |

```yaml theme={null}
assertions:
  - config:
      type: response_size
      maxBytes: 1048576
    severity: warn
```

### redirect\_count

Limit the number of redirects followed.

| Field      | Type    | Required | Description                 |
| ---------- | ------- | -------- | --------------------------- |
| `maxCount` | integer | Yes      | Maximum number of redirects |

```yaml theme={null}
assertions:
  - config:
      type: redirect_count
      maxCount: 3
    severity: warn
```

### redirect\_target

Verify the final redirect destination URL.

| Field      | Type   | Required | Description                     |
| ---------- | ------ | -------- | ------------------------------- |
| `expected` | string | Yes      | Expected final URL              |
| `operator` | string | Yes      | `equals`, `contains`, `matches` |

```yaml theme={null}
assertions:
  - config:
      type: redirect_target
      expected: https://www.example.com
      operator: equals
    severity: fail
```

## Operators reference

| Operator       | Behavior                          | Applies to                                                    |
| -------------- | --------------------------------- | ------------------------------------------------------------- |
| `equals`       | Exact string or numeric match     | `status_code`, `json_path`, `header_value`, `redirect_target` |
| `contains`     | Substring match                   | `status_code`, `json_path`, `header_value`, `redirect_target` |
| `less_than`    | Numeric less-than                 | `json_path`, `header_value`                                   |
| `greater_than` | Numeric greater-than              | `json_path`, `header_value`                                   |
| `matches`      | Regex match                       | `status_code`, `json_path`, `header_value`, `redirect_target` |
| `range`        | Numeric range (e.g., `"200-299"`) | `status_code`, `json_path`, `header_value`                    |

## Common patterns

<AccordionGroup>
  <Accordion title="Health check with status + latency">
    ```yaml theme={null}
    assertions:
      - config:
          type: status_code
          expected: "200"
          operator: equals
        severity: fail
      - config:
          type: response_time
          thresholdMs: 3000
        severity: fail
      - config:
          type: response_time_warn
          warnMs: 1500
        severity: warn
    ```
  </Accordion>

  <Accordion title="JSON API validation">
    ```yaml theme={null}
    assertions:
      - config:
          type: status_code
          expected: "200"
          operator: equals
        severity: fail
      - config:
          type: json_path
          path: $.status
          expected: healthy
          operator: equals
        severity: fail
      - config:
          type: header_value
          headerName: content-type
          expected: application/json
          operator: contains
        severity: fail
    ```
  </Accordion>

  <Accordion title="SSL + uptime combo">
    ```yaml theme={null}
    assertions:
      - config:
          type: status_code
          expected: "200"
          operator: equals
        severity: fail
      - config:
          type: ssl_expiry
          minDaysRemaining: 30
        severity: warn
      - config:
          type: ssl_expiry
          minDaysRemaining: 7
        severity: fail
    ```
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="HTTP configuration" icon="gear" href="/monitoring/http/configuration">
    Headers, body, TLS, and auth fields.
  </Card>

  <Card title="SSL monitoring guide" icon="lock" href="/guides/ssl-certificate-monitoring">
    Certificate expiry monitoring patterns.
  </Card>

  <Card title="Incident policies" icon="triangle-exclamation" href="/incidents/policies">
    How assertion failures trigger incidents.
  </Card>

  <Card title="Monitoring as Code" icon="code" href="/mac/yaml/monitors">
    Define assertions in YAML.
  </Card>
</CardGroup>