How to ask for a value when you send a request in API Spector

Some values do not belong in a collection or an environment: a one-time code, a password you would rather not save, an id that changes every time you test. API Spector has ask variables for exactly this. You write a placeholder, and the value is requested when you send, not stored anywhere.

Write an ask variable

Anywhere a variable works, in the URL, a query parameter, a header, the body, or an auth field, write {{@Message}}. The @ marks it as an ask variable, and the text is the label you will see. For example:

Authorization: Bearer {{@API token}}

When you send the request, API Spector asks for "API token", you type the value, and it goes out with the request. The value is never written to disk. If the same message appears more than once, you are asked once and it is reused. Leave the box blank and it sends as an empty string; cancel and the request is not sent.

Offer a dropdown of choices

When a value should be one of a fixed set, list the options in square brackets and you get a dropdown instead of a text box:

{{@Environment[dev, staging, prod]}}

Now sending the request offers dev, staging, and prod to pick from, so you do not have to remember or retype them.

Automated runs

The command line and the collection runner cannot stop to ask a person, so ask variables are handled a bit differently there.

From the CLI, supply each value with --ask, which you can repeat:

api-spector run --workspace ./ws --ask "API token=abc123" --ask "Environment=prod"

Any request whose ask variables are not all supplied is skipped and reported as skipped, so an unattended run never sends a blank value or hangs waiting for input.

In the app's Runner, API Spector collects every ask variable used in the run and prompts for them once, up front, before the run starts. You fill them in a single dialog and the whole run proceeds unattended from there.

Why it helps

Keeping a short-lived or sensitive value out of your files is the safe default, but it used to mean editing a variable before each send. An ask variable puts the value where it is used, asks for it only when you send, and never saves it, while --ask keeps the same requests runnable in CI.