Assertions give you targeted, machine-readable checks that must all pass for a spec execution to be considered successful. Write them in theDocumentation Index
Fetch the complete documentation index at: https://docs.markapidown.net/llms.txt
Use this file to discover all available pages before exploring further.
## Assertions section of any endpoint spec file and MarkApiDown evaluates them after every request — in local runs, in CI pipelines, and in AI agent workflows. A single failing assertion sets exit code 1, making it straightforward to block merges or deployments on broken contracts.
Where assertions live
Add an## Assertions section after ## Expected response in your endpoint spec file. Each assertion is a bullet point in the form - <path>: <operator> [value]:
## Assertions vs ## Expected response
These two sections serve different purposes and work best together:
## Expected response
A full-body diff against a recorded snapshot. MarkApiDown compares the
entire response body and highlights any fields that differ. Ideal for
catching unexpected changes across the whole response shape.
## Assertions
Targeted checks on specific fields, headers, or the status code. Each
assertion is independent and named, so failures pinpoint exactly which
contract was broken — great for CI and contract testing.
## Expected response to document the full shape of the response and catch regressions. Use ## Assertions for the specific invariants that must hold for the endpoint to be considered correct.
Assertion operators
status: <code> — exact status check
Asserts that the HTTP response status code equals the given value exactly.
body.<path>: exists — field presence check
Asserts that the field at <path> is present in the response body (not null and not missing). Use dot-notation or bracket-notation to navigate nested structures.
body.<path>: <value> — exact value check
Asserts that the field at <path> equals the given value exactly. Works for strings, numbers, and booleans.
body.<path>: in [value1, value2, ...] — membership check
Asserts that the field at <path> is one of the listed values. Useful for validating enum-like fields without pinning to a single value.
headers.<name>: contains <substring> — header substring check
Asserts that the response header <name> contains the given substring (case-insensitive). Most commonly used to verify Content-Type.
body.<path>: matches <regex> — pattern check
Asserts that the string value at <path> matches the given regular expression. Use this for format validation — slugs, UUIDs, email addresses, and similar patterns.
Path syntax reference
Navigate the response body using dot-notation for object properties and bracket-notation for array indices. Combine them freely for deeply nested structures.| Path expression | Navigates to |
|---|---|
body.id | Top-level id field |
body.data.token | token nested inside data |
body.items[0].id | id of the first element in items array |
body.results[2].user.email | email inside the third result’s user object |
A complete assertions example
The following spec combines multiple assertion operators to validate a user creation endpoint:Exit codes and CI integration
When one or more assertions fail,mad exec exits with code 1. A successful run exits with code 0. Use this in any CI pipeline to block on contract failures:
JUnit output for CI dashboards
Pass--output=junit to produce a JUnit XML report that CI platforms (GitHub Actions, GitLab CI, Jenkins, CircleCI) can parse and display as a test results summary: