API Flows (Multi-Step Chains)

API Flows let you chain multiple API calls together in a defined sequence, passing values from one response directly into the next request. This is ideal for testing real-world scenarios like logging in, retrieving an auth token, and using that token in a protected endpoint — all in a single automated run.

Flow Commands

# List all flows for the current application maeris flow list # Create a new flow maeris flow create "User Login Flow" # Run a flow maeris flow run "User Login Flow" # Delete a flow maeris flow delete "User Login Flow"

Defining a Flow Map

A flow map defines the sequence of API steps and the dependencies between them. Use maeris flow map set to configure which APIs run in which order:

# Set the step sequence for a flow maeris flow map set "User Login Flow" \ --steps "Login,Get Profile,Get Orders" # The flow will execute: Login → Get Profile → Get Orders

You can also define dependencies to ensure a step only runs after another has completed successfully:

maeris flow map set "User Login Flow" \ --steps "Login,Get Profile,Get Orders" \ --depends "Get Profile:Login,Get Orders:Get Profile"

Parameter Chaining

Flow parameters let you extract a value from one step's response and automatically inject it into a later step's request. Use maeris flow param add to define these mappings:

# Extract "token" from the Login response body and inject it
# into the "Authorization" header of subsequent steps
maeris flow param add "User Login Flow" \
  --from-step "Login" \
  --from-path "response.body.token" \
  --to-step "Get Profile" \
  --to-location "header" \
  --to-key "Authorization" \
  --to-template "Bearer {{value}}"

Supported extraction paths

You can extract values from response.body.field, response.headers.header-name, or response.body.nested.path using dot notation. Array indexing is also supported: response.body.users[0].id.

Example: Login → Token → Protected Call

Here is a complete example of building an authentication flow:

Step 1: Create the flow

maeris flow create "Authenticated API Flow"

Step 2: Define the step sequence

maeris flow map set "Authenticated API Flow" \
  --steps "POST /auth/login,GET /api/user/me,GET /api/orders"

Step 3: Chain the auth token

maeris flow param add "Authenticated API Flow" \
  --from-step "POST /auth/login" \
  --from-path "response.body.access_token" \
  --to-step "GET /api/user/me" \
  --to-location "header" \
  --to-key "Authorization" \
  --to-template "Bearer {{value}}"

Step 4: Run the flow

maeris flow run "Authenticated API Flow"

When executed, Maeris calls POST /auth/login, extracts the access_token from the response, inserts it as an Authorization header, and then calls the subsequent endpoints in sequence.

Viewing Flow Params

# View all parameter mappings for a flow maeris flow param list "Authenticated API Flow" # View the full flow map (steps + dependencies) maeris flow map get "Authenticated API Flow"

Next Steps

Add assertions to your API calls to validate response structure, values, and performance. See the Assertions & Validation guide.