---
title: 'Assertions'
description: 'Complete reference for HTTP check assertions — all types, operators, and examples.'
section: 'Reference'
canonical_url: 'https://yorkermonitoring.com/docs/reference/assertions'
---

# Assertions

Assertions validate HTTP check responses against expected conditions. Each assertion is an object with a `type` field that determines the available properties. All assertion types are validated through `AssertionSchema`, a Zod discriminated union.

To add assertions to an HTTP monitor, include them in the `assertions` array within `httpConfig` (API) or the monitor definition (YAML).

**Inheritance rule:** Monitor-level assertions **replace** defaults entirely. They are **not merged** with `defaults.http.assertions`. This matches Terraform/Checkly semantics -- if you define any assertions on a monitor, all default assertions are ignored for that monitor.

---

## `status_code`

To assert on the HTTP response status code:

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `type` | `"status_code"` | Yes | -- | Assertion type. |
| `operator` | `string` | No | `"equals"` | `equals` \| `not_equals` \| `less_than` \| `greater_than` |
| `value` | `number` | Yes | -- | Expected status code. |

### Operators

| Operator | Meaning |
|---|---|
| `equals` | Status code must exactly match `value`. |
| `not_equals` | Status code must not match `value`. |
| `less_than` | Status code must be less than `value`. |
| `greater_than` | Status code must be greater than `value`. |

### Examples

Assert an exact status code (operator defaults to `equals`):

```yaml
assertions:
  - type: status_code
    value: 200
```

Assert the status code is not a server error:

```yaml
assertions:
  - type: status_code
    operator: less_than
    value: 500
```

Assert a redirect:

```yaml
assertions:
  - type: status_code
    operator: equals
    value: 301
```

Exclude a specific status:

```yaml
assertions:
  - type: status_code
    operator: not_equals
    value: 404
```

---

## `response_time`

To assert that the response completes within a time limit:

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `"response_time"` | Yes | Assertion type. |
| `max` | `number` | Yes | Maximum response time in milliseconds. |

The assertion passes if the total response time is less than or equal to `max`.

### Examples

Response must complete within 3 seconds:

```yaml
assertions:
  - type: response_time
    max: 3000
```

Strict performance requirement (500ms):

```yaml
assertions:
  - type: response_time
    max: 500
```

---

## `body_contains`

To assert that the response body contains a specific string:

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `"body_contains"` | Yes | Assertion type. |
| `value` | `string` | Yes | String that must appear in the response body. |

The match is a simple substring check. It is case-sensitive.

### Examples

Check for a success indicator:

```yaml
assertions:
  - type: body_contains
    value: '"status":"ok"'
```

Check for HTML content:

```yaml
assertions:
  - type: body_contains
    value: "Welcome to Acme"
```

---

## `body_matches`

To assert that the response body matches a regular expression pattern:

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `"body_matches"` | Yes | Assertion type. |
| `pattern` | `string` | Yes | Regular expression pattern to match against the response body. |

The pattern is applied to the full response body. It uses standard JavaScript regex syntax.

### Examples

Match a version string:

```yaml
assertions:
  - type: body_matches
    pattern: '"version":"\\d+\\.\\d+\\.\\d+"'
```

Match any success status in JSON:

```yaml
assertions:
  - type: body_matches
    pattern: '"status":"(ok|healthy|running)"'
```

Match a UUID in the response:

```yaml
assertions:
  - type: body_matches
    pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
```

---

## `body_json_path`

To assert on a specific value within a JSON response using JSONPath expressions:

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `type` | `"body_json_path"` | Yes | -- | Assertion type. |
| `path` | `string` | Yes | -- | JSONPath expression (e.g., `$.status`, `$.data.items[0].name`). |
| `operator` | `string` | No | `"equals"` | `equals` \| `not_equals` \| `contains` \| `exists` |
| `value` | `any` | No | -- | Expected value. Not required when operator is `exists`. |

### Operators

| Operator | Meaning |
|---|---|
| `equals` | The value at the JSONPath must exactly match `value`. |
| `not_equals` | The value at the JSONPath must not match `value`. |
| `contains` | The value at the JSONPath (string) must contain `value` as a substring. |
| `exists` | The JSONPath must resolve to a non-undefined value. `value` is ignored. |

### Examples

Assert a JSON field has a specific value:

```yaml
assertions:
  - type: body_json_path
    path: "$.status"
    value: "healthy"
```

Assert an array has items (check existence):

```yaml
assertions:
  - type: body_json_path
    path: "$.data.items[0]"
    operator: exists
```

Assert a nested value is not null:

```yaml
assertions:
  - type: body_json_path
    path: "$.user.email"
    operator: not_equals
    value: null
```

Assert a string field contains a substring:

```yaml
assertions:
  - type: body_json_path
    path: "$.message"
    operator: contains
    value: "success"
```

Assert a numeric value:

```yaml
assertions:
  - type: body_json_path
    path: "$.count"
    operator: equals
    value: 42
```

---

## `header_value`

To assert on the value of a response header:

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `type` | `"header_value"` | Yes | -- | Assertion type. |
| `header` | `string` | Yes | -- | Header name (case-insensitive matching at runtime). |
| `operator` | `string` | No | `"equals"` | `equals` \| `contains` \| `exists` |
| `value` | `string` | No | -- | Expected header value. Not required when operator is `exists`. |

### Operators

| Operator | Meaning |
|---|---|
| `equals` | Header value must exactly match `value`. |
| `contains` | Header value must contain `value` as a substring. |
| `exists` | Header must be present in the response. `value` is ignored. |

### Examples

Assert the content type:

```yaml
assertions:
  - type: header_value
    header: "Content-Type"
    value: "application/json"
```

Assert a header contains a substring:

```yaml
assertions:
  - type: header_value
    header: "Content-Type"
    operator: contains
    value: "json"
```

Assert a cache header exists:

```yaml
assertions:
  - type: header_value
    header: "X-Cache"
    operator: exists
```

Assert a security header:

```yaml
assertions:
  - type: header_value
    header: "Strict-Transport-Security"
    operator: exists
```

---

## `ssl_expiry`

To assert that the target's SSL certificate does not expire within a given number of days:

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `type` | `"ssl_expiry"` | Yes | -- | Assertion type. |
| `daysBeforeExpiry` | `number` | No | `14` | Minimum number of days until certificate expiry. |

The assertion fails if the SSL certificate expires within `daysBeforeExpiry` days.

### Examples

Default 14-day warning:

```yaml
assertions:
  - type: ssl_expiry
```

30-day warning for critical services:

```yaml
assertions:
  - type: ssl_expiry
    daysBeforeExpiry: 30
```

7-day warning for non-critical services:

```yaml
assertions:
  - type: ssl_expiry
    daysBeforeExpiry: 7
```

---

## `openapi_conformance`

Validate that the HTTP response conforms to an OpenAPI spec registered in Yorker. Yorker auto-detects the operation by matching the check URL (method + path template) against the spec, or you can pin a specific operation.

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `type` | `"openapi_conformance"` | Yes | — | Assertion type. |
| `specId` | `string` | Yes | — | ID of the API spec stored in Yorker (`spec_...`). |
| `operationPath` | `string` | No | auto-detect | Override operation as `"METHOD /path/template"` (e.g. `"GET /pets/{petId}"`). |
| `validateHeaders` | `boolean` | No | `false` | Also validate response headers against the spec. |

The assertion fails if the response status, body shape, or (when `validateHeaders: true`) headers do not match the OpenAPI operation. Schema drift between requests is detected by hashing the stored spec content — when you update the spec in Yorker, runners automatically invalidate their cached copy on the next check.

### Managing API specs

API specs are managed through the dashboard (**Monitors → API Specs**) or via the REST API:

- Upload raw JSON/YAML: `POST /api/specs` with `sourceType: "upload"` and `content`.
- Link a URL (Yorker fetches and refreshes on demand): `POST /api/specs` with `sourceType: "url"` and `sourceUrl`.

See the [REST API reference](/docs/reference/api) for full spec CRUD.

### Examples

Validate every response against a spec, auto-detecting the operation:

```yaml
assertions:
  - type: openapi_conformance
    specId: spec_payments_v2
```

Pin a specific operation and include header validation:

```yaml
assertions:
  - type: openapi_conformance
    specId: spec_payments_v2
    operationPath: "POST /v1/payments"
    validateHeaders: true
```

---

## Combining Assertions

To apply multiple assertions to a single monitor, include them all in the `assertions` array. All assertions must pass for the check to be considered successful.

```yaml
monitors:
  - name: "API Health"
    type: http
    url: "https://api.example.com/health"
    assertions:
      - type: status_code
        value: 200
      - type: response_time
        max: 2000
      - type: body_json_path
        path: "$.status"
        value: "ok"
      - type: header_value
        header: "Content-Type"
        operator: contains
        value: "json"
      - type: ssl_expiry
        daysBeforeExpiry: 14
```

---

## Assertion Results

When a check runs, each assertion produces a result object in the check result:

```json
{
  "type": "status_code",
  "passed": true,
  "expected": 200,
  "actual": 200,
  "message": null
}
```

| Field | Type | Description |
|---|---|---|
| `type` | `string` | The assertion type. |
| `passed` | `boolean` | Whether the assertion passed. |
| `expected` | `any` | The expected value from the assertion definition. |
| `actual` | `any` | The actual value from the response. |
| `message` | `string` | Human-readable description (present on failure). |