TOML Request Reference

This document serves as the complete technical schema and reference for constructing Rumour .toml request files.

The Request Block ([request])

Every Rumour file must contain a [request] block. It defines the core HTTP invocation parameters.

Field	Type	Required	Description
method	String	No	The HTTP method (defaults to GET).
url	String	Yes	The target URL. Supports {{variable}} interpolation.
skip	Boolean	No	If true, Rumour skips executing this file.
pre_request	String	No	Relative path to a Rhai script to run before the request fires.
post_request	String	No	Relative path to a Rhai script to run after the request completes.

[request]
method = "POST"
url = "{{base_url}}/api/v1/users"
skip = false

Note: pre_request and post_request can also be defined at the root level of the file.

Global Tables

These optional tables define the payload and metadata sent with the request.

[headers]

A key-value table of HTTP headers. Keys are treated case-insensitively.

[headers]
Authorization = "Bearer {{auth_token}}"
Content-Type = "application/json"

[params]

A key-value table appended to the URL as a query string.

[params]
limit = "100"
offset = "0"

[variables]

A key-value table for defining local variables scope. These take precedence over environment variables but are overridden by CLI flags.

[variables]
test_user = "admin"
expected_status = "200"

The Body Block ([body])

Defines the payload sent with POST, PUT, or PATCH requests.

Field	Type	Required	Description
type	String	No	The payload format. Supports json, text, form, xml, or binary. (Defaults to json).
raw	String	Yes	The raw string payload to be sent. Supports {{variable}} interpolation.

[body]
type = "json"
raw = '{"email": "test_{{random}}@example.com"}'

The Dependency Block ([dependencies])

Defines which other .toml requests must successfully complete before this request can execute, and specifies which variables to import from them.

Rumour uses this block to automatically construct the execution DAG (Directed Acyclic Graph) for parallel multi-threading.

Array Import Syntax

Used when you want to import multiple variables from a single dependency.

[dependencies]
"../auth/login.toml" = ["access_token", "refresh_token"]
"../setup/create_account.toml" = ["account_id"]

Single Import Syntax

Used when you only need one variable.

[dependencies]
"../auth/login.toml" = "access_token"

The Extract Block ([extract])

Defines extraction rules to pull dynamic data out of the HTTP response and store it in global variable memory for subsequent requests.

Keys are the variable names you want to create. Values are the traversal paths.

Prefix	Description	Example
json.	Traverses a JSON response body using dot notation. Supports [n] arrays.	json.data.users[0].id
header.	Extracts the value of a specific response header (case-insensitive).	header.set-cookie
status	Extracts the raw HTTP status code (e.g., 201).	status
body	Extracts the entire raw response body as a string.	body

[extract]
user_token = "json.token"
session_cookie = "header.set-cookie"

The Assert Block ([assert])

Defines automated validations for the response. If any assertion fails, the entire node is marked as failed.

Root Assertions

Field	Type	Description
status	Integer	Asserts an exact HTTP status code (e.g., 200).
status_range	String	Asserts a range or list of codes (e.g., 200-299 or 200,201).
body_contains	String	Asserts that the exact substring exists somewhere in the response body.
duration	Integer	Asserts that the total network request time does not exceed this amount in milliseconds (SLA).
schema	String	Path to a local .json file containing a Draft-07 JSON Schema to validate the response structure against.

[assert]
status_range = "200-299"
body_contains = "SUCCESS"
duration = 500
schema = "./schemas/user.json"

Advanced JSON Assertions ([assert.json])

Validates specific leaf nodes in a JSON response. The key is the JSON path, and the value is a constraint table.

Supported Constraints:

• equal: Exact value match (strings, numbers, booleans).
• not_equal: Inverse exact value match.
• contains: Substring match.
• exists: Boolean asserting the path is present (even if null).
• greater_than / less_than: Numeric bounds checking.
• regex: Regular expression pattern matching.

[assert.json]
"data.id" = { greater_than = 100 }
"data.email" = { regex = "^[a-z]+@swahira\\.io$" }
"data.deleted" = { exists = false }

Advanced Header Assertions ([assert.headers])

Validates response headers. It supports the same constraints as [assert.json], except for numeric operators.

[assert.headers]
"content-type" = { contains = "application/json" }
"cache-control" = { equal = "no-cache" }

Execution Directives

These root-level keys control how Rumour handles the request execution lifecycle.

Field	Type	Description
name	String	A human-readable display name for the CLI trace output.
skip	Boolean	Skips execution of this file entirely.
retries	Integer	How many times to automatically retry the request on network timeout or assertion failure (Defaults to 0).
ordered	Boolean	If true, forces the node to run sequentially outside of the normal parallel dependency graph.

name = "Flaky Third Party API"
retries = 3
ordered = true