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:

Operators

Examples

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

assertions:
  - type: status_code
    value: 200

Assert the status code is not a server error:

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

Assert a redirect:

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

Exclude a specific status:

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

response_time

To assert that the response completes within a time limit:

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

Examples

Response must complete within 3 seconds:

assertions:
  - type: response_time
    max: 3000

Strict performance requirement (500ms):

assertions:
  - type: response_time
    max: 500

body_contains

To assert that the response body contains a specific string:

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

Examples

Check for a success indicator:

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

Check for HTML content:

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

body_matches

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

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

Examples

Match a version string:

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

Match any success status in JSON:

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

Match a UUID in the response:

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:

Operators

Examples

Assert a JSON field has a specific value:

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

Assert an array has items (check existence):

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

Assert a nested value is not null:

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

Assert a string field contains a substring:

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

Assert a numeric value:

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

header_value

To assert on the value of a response header:

Operators

Examples

Assert the content type:

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

Assert a header contains a substring:

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

Assert a cache header exists:

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

Assert a security header:

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:

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

Examples

Default 14-day warning:

assertions:
  - type: ssl_expiry

30-day warning for critical services:

assertions:
  - type: ssl_expiry
    daysBeforeExpiry: 30

7-day warning for non-critical services:

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.

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 for full spec CRUD.

Examples

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

assertions:
  - type: openapi_conformance
    specId: spec_payments_v2

Pin a specific operation and include header validation:

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.

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:

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