Tool Parameters¶

The run_test_api tool accepts the following parameters. Parameters are grouped by category: request definition and assertions.

Request parameters¶

Parameter	Type	Required	Default	Description
`api_name`	`str`	Yes	—	A human-readable name for the test (used in output)
`curl_command`	`str`	No	`None`	A raw cURL command. When provided, all other request parameters are parsed from it
`base_url`	`str`	Yes*	`None`	The base URL (e.g. `https://api.example.com`). Required unless `curl_command` is used
`endpoint`	`str`	Yes*	`None`	The API endpoint path (e.g. `/v1/users`). Required unless `curl_command` is used
`method`	`str`	No	`"GET"`	HTTP method (GET, POST, PUT, DELETE, PATCH, etc.)
`headers`	`dict[str, str]`	No	`None`	Dictionary of request headers
`payload`	`dict[str, Any]`	No	`None`	Dictionary of request body data (sent as JSON)

* Required when curl_command is not provided.

Assertion parameters¶

All assertion parameters are optional. When omitted, the tool executes the request and returns the raw response without validation.

Parameter	Type	Description
`required_status_code`	`int`	Assert the response has an exact status code (e.g. `201`)
`required_status_code_range`	`str`	Assert the status code falls within a range (e.g. `"2xx"`, `"200-299"`)
`required_response_fields`	`list[str]`	Assert that specific fields exist in the JSON response. Supports dot notation for nested fields
`required_response_contains`	`str`	Assert the response body contains a substring

Usage examples¶

Minimal request (structured mode)¶

run_test_api(
    api_name="health-check",
    base_url="https://api.example.com",
    endpoint="/health",
)

Request with assertions (structured mode)¶

run_test_api(
    api_name="create-user",
    base_url="https://api.example.com",
    endpoint="/v1/users",
    method="POST",
    headers={"Authorization": "Bearer xxx"},
    payload={"name": "test"},
    required_status_code=201,
    required_response_fields=["id"],
)

cURL mode¶

run_test_api(
    api_name="create-user",
    curl_command="curl -X POST https://api.example.com/v1/users -H 'Authorization: Bearer xxx' -d '{\"name\":\"test\"}'",
    required_status_code=201,
    required_response_contains="id",
)