Assertions & Validation

Assertions define what a correct API response looks like. Maeris supports six categories of assertion types and can auto-generate a complete assertion set from a single live API response using Claude AI — saving you from writing every check by hand.

Assertion Commands

# List all assertions for an API maeris assertion list --api "Get User" # Create a new assertion maeris assertion create \ --api "Get User" \ --nature response \ --type value \ --path "body.status" \ --value "active" # Update an existing assertion maeris assertion update <assertion-id> --value "verified" # Delete an assertion maeris assertion delete <assertion-id>

Assertion Types

Maeris supports the following assertion categories:

Structure

Validates the shape of the response. Checks that required fields are present, have the correct data types (string, number, array, object, boolean), and that no unexpected fields appear if strict mode is enabled.

Example: body.id must be a number; body.email must be a string.

Value Domain

Validates that a field's value falls within an expected set or range. Supports exact match, enum membership, regex pattern, numeric range, and string length constraints.

Example: body.status must be one of ["active", "inactive", "pending"].

Uniqueness

Validates that array items contain no duplicate values on a specified field. Useful for ensuring list endpoints don't return duplicate IDs.

Example: All items in body.users[*].id must be unique.

Referential

Validates foreign-key style relationships — that a field's value matches a value returned by another API in the same flow. Useful for chained flows where an ID created in step 1 should appear in step 2's response.

Dataset

Validates aggregate properties of returned arrays: minimum count, maximum count, exact count, or that the array is non-empty. Also supports sorting assertions (e.g., results must be sorted by created_at descending).

Performance

Validates that the API responds within a specified time budget. Set a maximum response time in milliseconds. Failures are flagged as performance regressions in your run results.

Example: Response time must be under 500ms.

Auto-Generating Assertions

Instead of writing assertions manually, Maeris can analyze a live API response and auto-generate a comprehensive set of assertions using Claude AI:

# Auto-generate assertions for an API by running it once maeris assertion generate --api "Get User"

This fires a real request, captures the response, and generates assertions covering:

HTTP status code equals the observed value (e.g., 200)
All top-level response fields are present and have the correct type
String fields match observed patterns (e.g., email format, UUID format)
Numeric fields are within a reasonable range based on the observed value
Boolean fields have the expected value
Response time is under the observed time plus a 20% buffer

Review generated assertions before saving

Auto-generated assertions are presented for review before being saved. You can accept all, reject specific ones, or edit values directly from the confirmation prompt.

Listing Assertion Types

To see all available assertion types and their parameters:

maeris assertion types

Next Steps

After setting up assertions, combine your APIs into multi-step chains using flows. See the API Flows (Multi-Step Chains) guide.