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

# Creating a Validation

> From wizard fields to required flags: shape one API check atop a connection, tune timeouts and retries, and expose a slug for prompts.

## Step 1 — Basic Info

1. Open the **Validations** tab and click **+ Add Validation**.
2. Enter a **Validation name**. Make it specific and action-oriented — "Verify order created after checkout", "Confirm product inventory decremented", "Check user profile updated". A name that describes what it verifies is more useful than one that describes the endpoint it calls.
3. Add an optional **Description** explaining what this validation checks and why it matters. Useful context for teammates and for your future self.
4. Select the **Backend connection** this validation runs against. The connection provides the base URL and authentication — the validation adds the specific endpoint path on top of it.
5. Click **Continue**.

## Step 2 — HTTP Request

Configure the API call this validation makes.

## HTTP Method

Select the method that matches the operation:

| Method     | Use for                                                                                                    |
| ---------- | ---------------------------------------------------------------------------------------------------------- |
| **GET**    | Fetching data without modifying anything — reading an order, checking inventory, retrieving a user profile |
| **POST**   | Creating a new resource — submitting a form, creating an order, registering a user                         |
| **PUT**    | Replacing an existing resource entirely                                                                    |
| **PATCH**  | Updating part of an existing resource — changing a name, updating a status                                 |
| **DELETE** | Removing a resource                                                                                        |

For most backend verifications after a UI action, GET is the right choice — you are reading the resulting state, not triggering another state change.

## Endpoint path

Enter the path relative to the base URL defined in the connection. Do not repeat the base URL.

```
Connection base URL:  https://api.yourapp.com
Endpoint path:        /orders/latest
Full request URL:     https://api.yourapp.com/orders/latest  (auto-generated)
```

The full request URL updates automatically as you type, so you can confirm it looks correct before saving.

## Query parameters (optional)

Add key-value pairs appended to the URL as query string parameters. Use for filters, pagination, search terms, or any parameter your endpoint accepts in the URL.

```
Key: user_id      Value: 12345
Key: status       Value: completed
→ Appended as: ?user_id=12345&status=completed
```

## Custom headers (optional)

Add headers specific to this endpoint — content type declarations, feature flags, or endpoint-specific authentication that differs from the connection-level auth. These apply only to this validation, not to other validations using the same connection.

## Step 3 — Response Validation

Define what a successful response looks like.

## Status codes

Select the HTTP status code you expect. Choose from the defaults (200, 201, 202, 204, 400, 404) or enter a custom code. The validation fails if the response code does not match.

For most verification checks after a successful UI action, expect **200 OK**. For creation endpoints called after a form submission, expect **201 Created**.

## Request timeout

Default is 5,000ms (5 seconds). Increase for endpoints that are known to be slow — external payment processors, heavy reporting queries, or endpoints that aggregate data from multiple services.

## Retry attempts and backoff

Configure how many times the validation should retry on failure before reporting a definitive fail result, and the delay between retries. Use retries for eventually-consistent backends where state may not be immediately reflected after a UI action — for example, an order that takes 2–3 seconds to appear in the database after the checkout button is tapped.

| Setting        | Recommendation                                                 |
| -------------- | -------------------------------------------------------------- |
| Retry attempts | 2–3 for eventually-consistent backends, 0 for synchronous APIs |
| Retry backoff  | 1,000–2,000ms — gives the backend time to settle               |

## Expected response data (optional)

Assert that the response body contains specific values. Supports two assertion types:

**JSON Path assertions** Check a specific field inside a JSON response. Enter the JSON path and the expected value.

```
JSON Path: $.order.status        Expected value: completed
JSON Path: $.user.email          Expected value: test@example.com
JSON Path: $.items[0].quantity   Expected value: 1
```

**Regex assertions** Check that the response body matches a text pattern. Useful for flexible matching — checking that a confirmation number follows a format rather than matching an exact value.

```
Pattern: ORD-[0-9]{6}    (matches any order number like ORD-123456)
Pattern: "status":"(completed|processing)"
```

## Extract variables (optional)

Capture a value from the response and store it as a variable for use in subsequent steps. Useful when an earlier validation produces an ID or token that a later validation or task step needs to use.

```
Variable name: order_id
JSON Path:     $.order.id
```

The captured value becomes available as `{{order_id}}` in subsequent prompts and validations within the same task run.

## Mark as required

When enabled, a failure in this validation causes the entire task or suite run to fail — not just the individual step. Use for validations that represent absolute pass conditions: if the order was not created in the backend, the test has failed regardless of what happened on screen.

Leave disabled for advisory checks where a failure is worth noting but should not block the run.

## Step 4 — Advanced Options (Prompt Action)

Configure this validation to be callable inline inside task prompts using `@slug`.

**Enable prompt action** — toggle ON to make this validation available via `@slug` in prompts.

**Action slug** — the identifier you type in a prompt to call this validation. Keep it short, lowercase, and hyphenated.

```
@verify-order-created
@check-inventory-updated
@confirm-user-registered
```

**Description for the AI** — a short sentence explaining what this validation checks, written for Recipe and Mahoraga to understand. This description helps the agent use the validation correctly when it encounters `@slug` in a prompt.

```
Checks that the most recent order exists in the backend with status 'completed'.
Verifies that the product inventory count decreased by 1 after a purchase.
```

**Parameters** — define dynamic inputs the validation accepts when called. Use when the same validation needs to work with different values depending on context — for example, checking a specific user ID or order ID passed from the task.

```
Parameter name: user_id
Parameter description: The ID of the user to verify
```

Reference parameters in the endpoint path or expected values using `{{parameter_name}}` syntax.

## Saving the validation

Click **Save Validation**. The validation appears in the Validations tab, ready to use in task settings or via `@slug` in prompts.

## Editing a validation

Click any validation in the Validations tab to open it. All four steps are editable. Save to apply changes — updated validations take effect on the next run.