Contents ▼

Protocol Scripts

Protocol scripts are run by Protocol Bots. They operate entirely at the HTTP protocol layer, firing off a sequence of requests, and parsing the responses. Protocol scripts are ideal for monitoring HTTP APIs (REST, GraphQL, etc) and simple static sites.

Each ordinary step in your script makes a single HTTP request. You specify the method, URL, and headers to be sent. If it’s a method that supports a body (like a POST or PUT) you can supply a request body too.

You can think of each HTTP step kind of like a visual representation of a curl command.

HTTP Method

Many URLs, especially RESTful API endpoints, behave differently depending on which HTTP Method you call them with. While GET is the most common, and hence the default, you can use any of the usual HTTP methods.


You didn’t make it this far without knowing what a URL is! For now, let’s just say each step in your monitor needs to specify what URL it is going to hit. Because some monitoring scripts might hit several different domains, the full URL is required for each step.

Request Body

Certain HTTP methods, like POST or PUT, commonly include a request body. Others, like GET, usually don’t.

The body can have any Content-Type you want. An empty body is also acceptable.

You can edit text-based request bodies (JSON, XML, plain text, etc) in Speedway. Binary or unusually large bodies can be loaded through your browser’s file manager.

You might also notice an option called Interpolate variables in request body. This deals with the treatment of variables and expressions that might occur in your request body. If checked, strings like ${variable} and ${expression()} occurring in the request body will be substituted with their respective values, or an empty string if undefined. If unchecked, such strings will be sent literally and not interpolated.

Custom Headers

Speedway sends default HTTP headers with each request, but you can also add your own custom headers. This might be necessary if your site or API requires certain authentication/authorization schemes, among other things.

To add a custom header to a step, select Add custom header under the Add… menu.

HTTP headers are simple name value pairs. If yours are dynamic (in other words, they might be different each time your monitor runs), you can use variables and expressions in either field.

Basic Authentication

While it’s become a little less common in recent years, many APIs still accept HTTP Basic Authentication as a way to pass username and password to identify the caller. The username and password might be an actual username and password, or they might be some kind of API key.

To configure HTTP Basic Authentication for a step, select Add basic authentication under the Add… menu. Enter a username and password, either of which may be literal strings or be comprised of variables and expressions.


You can add special Validators on an HTTP step which will examine the response that comes back from the API. All types of validators are under the step’s Add… menu.

If any validator fails, the entire monitor cycle is deemed a failure, and Speedway will immediately send out notifications if this monitor was previously passing.

Content Validators

This type of validator can quickly check whether the response body includes (or does not include) a certain string.

Response Time Validators

These validators can ensure a request is made and the response fully received within a certain amount of time. This is good for critical API operations that simply must complete quickly.

Response Size Validators

Use these to quickly validate that the response body is within a certain size range. This is often a good way to check for the presence of errors or unreasonably large API responses.

JavaScript Validators

These are the most powerful kind of validator in Speedway! A JavaScript validator lets you specify a custom JavaScript function called validate() that Speedway feeds the response to, after executing an HTTP step.

You can put whatever validation logic you want in the function, and return true or false.

If the validator function returns a true value, then validation is deemed to have passed. If it returns false (or a falsy value such as null or 0) then it is treated as a failure.

The JavaScript runtime environment is described in more detail in Code Blocks.


You can also add Capturers that examine the response coming back from your API. Capturers can be found under the Add… menu on any HTTP step.

Capturers can examine a response and extract a value, storing it in a variable for use by any subsequent step in the same script.

A few real world examples of when you might use capturers in your monitoring scripts are:

  • A monitor is hitting a login endpoint, and needs to extract the dynamic api_key that the API returns after successful login, for later use in the same monitor sequence.
  • You hit an API endpoint to create an invoice, and need to reuse the dynamically created invoice_id later so you can apply a credit.
  • You hit a list endpoint and obtain a list of vehicles, and need to grab the first vehicle_vin_number to hit a detail endpoint.

Capturers are one of the most powerful constructs in Speedway’s approach to monitoring. They set it apart from many of the simple uptime monitoring tools because they allow chained interactions.

Text Capturers

Simple text capturers can extract a string of text from a response header or the response body, using the “sandwich” method of a literal left and right bound. For example, in the string “you have 18 new messages”, you could capture the number of new messages using a left bound of “you have " and a right bound of " new messages”.

Regex Capturers

A regex, or regular expression, is a more sophisticated way to parse strings. We won’t include a full regex primer here, but if you haven’t done much with them yet, they are worth knowing!

Like simple text capturers, regex capturers can extract values from a response header or the response body, but they also support capturing groups to reorder or restructure the value. For example, we could parse the email address "Andy Hawkes" <> with a Regular Expression of ^"(.*?)" <(\S+)>$ and an Output Expression of $2: $1, in which case the extracted value would be stripped of formatting and reordered to Andy Hawkes.

JavaScript Capturers

Most powerful of all, these capturers let you write your own JavaScript function to extract whatever you want from the response. The capturing function can do JSON or XML parsing, looping, conditionals, pattern matching… pretty much anything you can think of that is possible in a scripting language like JavaScript.

Your capturer function should be called capture and return the value that you want to store in the variable for later use.

Here’s a simple example:

function capture (response) {
    return response.json().cars[0].color;

The JavaScript flavor and runtime environment is described in more detail in Code Blocks.