Skip to main content

API reference

Rocket Validator API

The Rocket Validator API lets you manage your site validation reports and related data like schedules, mutings, devices and guest accounts sending conventional HTTP requests to a standard JSON API.

Current version

The Rocket Validator API is currently in version v1.

All endpoints have the prefix:

https://rocketvalidator.com/api/v1/{endpoint}

For brevity and legibility, the examples might omit the prefix, so instead of this:

GET https://rocketvalidator.com/api/v1/reports

we'll use this:

GET /api/v1/reports

API Quick Start

To start working with the Rocket Validator API, all you need is to sign up for a new account and then generate an API token. Check out the Authorization section to learn how to use this API token to identify your requests.

Example Request

To retrieve the data you need from Rocket Validator, you just need to perform a standard GET, POST, PATCH or DELETE request to the appropiate endpoint. Here are some examples in different programming languages, and below is a cheatsheet on the most common endpoints.

Example code

cURL

curl --request GET \

     --url https://rocketvalidator.com/api/v1/reports \

     --header 'authorization: Bearer $API_TOKEN'

Ruby

require 'uri'

require 'net/http'

require 'openssl'



url = URI("https://rocketvalidator.com/api/v1/reports")



http = Net::HTTP.new(url.host, url.port)

http.use_ssl = true

http.verify_mode = OpenSSL::SSL::VERIFY_NONE



request = Net::HTTP::Get.new(url)

request["authorization"] = 'Bearer $API_TOKEN'



response = http.request(request)

puts response.read_body

Ruby Gem



# Install the gem from https://rubygems.org/gems/rocketvalidator



require 'rocketvalidator'



RocketValidator::V1::Resource.with_api_token(ENV["ROCKET_API_TOKEN"]) do

    page = 0

    reports = RocketValidator::V1::Report.page(1).per(10).to_a



    while reports do

        page = page + 1

        puts "\nPage #{page}: #{reports.length} reports found."



        reports.each do |report|

            puts(report.starting_url)

        end



        reports = reports.pages.next

    end

end

Python

import http.client



conn = http.client.HTTPSConnection("rocketvalidator.com")



payload = ""



headers = { 'authorization': "Bearer $API_TOKEN" }



conn.request("GET", "/api/v1/reports", payload, headers)



res = conn.getresponse()

data = res.read()



print(data.decode("utf-8"))

PHP

<?php



$curl = curl_init();



curl_setopt_array($curl, array(

    CURLOPT_URL => "https://rocketvalidator.com/api/v1/reports",

    CURLOPT_RETURNTRANSFER => true,

    CURLOPT_ENCODING => "",

    CURLOPT_MAXREDIRS => 10,

    CURLOPT_TIMEOUT => 30,

    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,

    CURLOPT_CUSTOMREQUEST => "GET",

    CURLOPT_POSTFIELDS => "",

    CURLOPT_HTTPHEADER => array(

        "authorization: Bearer $API_TOKEN"

    ),

));



$response = curl_exec($curl);

$err = curl_error($curl);



curl_close($curl);



if ($err) {

    echo "cURL Error #:" . $err;

} else {

    echo $response;

}

?>

Node.js

var http = require("https");



var options = {

    "method": "GET",

    "hostname": "rocketvalidator.com",

    "port": null,

    "path": "/api/v1/reports",

    "headers": {

        "content-length": "0",

        "authorization": "Bearer $API_TOKEN"

    }

};



var req = http.request(options, function (res) {

    var chunks = [];



    res.on("data", function (chunk) {

        chunks.push(chunk);

    });



    res.on("end", function () {

        var body = Buffer.concat(chunks);

        console.log(body.toString());

    });

});



req.end();

Java

HttpResponse<String> response = Unirest.get("https://rocketvalidator.com/api/v1/reports")

.header("authorization", "Bearer $API_TOKEN")

.asString();

Swift

import Foundation



let headers = ["authorization": "Bearer $API_TOKEN"]



let postData = NSData(data: "".data(using: String.Encoding.utf8)!)



let request = NSMutableURLRequest(url: NSURL(string: "https://rocketvalidator.com/api/v1/reports")! as URL,

                                        cachePolicy: .useProtocolCachePolicy,

                                    timeoutInterval: 10.0)

request.httpMethod = "GET"

request.allHTTPHeaderFields = headers

request.httpBody = postData as Data



let session = URLSession.shared

let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in

if (error != nil) {

    print(error)

} else {

    let httpResponse = response as? HTTPURLResponse

    print(httpResponse)

}

})



dataTask.resume()

GET is the default method

In the cURL example above we're explicitly specifying the GET kind of request, but as it's the default, in the rest of the documentation you'll often see that we omit it.

Also, there's no need for the --url parameter and you can just pass the URL endpoint like this:

curl https://rocketvalidator.com/api/v1/reports \

   --header 'authorization: Bearer $API_TOKEN'

Reports

Create a Report

Send a POST request to /api/v1/reports with a JSON payload including the parameters:

  • starting_url. The initial URL where the Spider will start on. Required.
  • max_pages. The Spider will recursively follow internal links found until this limit is reached. Optional, defaults to 10.

Example: POST /api/v1/reports

{

  "data": {

    "attributes": {

      "starting_url": "https://dummy.rocketvalidator.com",

      "max_pages": 100

    }

  }

}

List your Reports

GET /api/v1/reports

Get a Report

GET /api/v1/reports/$REPORT_ID

Delete a Report

DELETE /api/v1/reports/$REPORT_ID

Web Pages

List the Web Pages on a Report

GET /api/v1/reports/$REPORT_ID/web_pages

Get a Web Page on a Report

GET /api/v1/reports/$REPORT_ID/web_pages/$WEB_PAGE_ID

Accessibility Issues

List A11Y issues on a Web Page

GET /api/v1/reports/$REPORT_ID/web_pages/$WEBPAGE_ID/a11y_issues

Get an A11Y issue on a Web Page

GET /api/v1/reports/$REPORT_ID/web_pages/$WEBPAGE_ID/a11y_issues/$ISSUE_ID

HTML Issues

List HTML issues on a Web Page

GET /api/v1/reports/$REPORT_ID/web_pages/$WEBPAGE_ID/html_issues.

Get an HTML issue on a Web Page

GET /api/v1/reports/$REPORT_ID/web_pages/$WEBPAGE_ID/html_issues/$ISSUE_ID.

Common Accessibility Issues

List Common A11Y issues on a Report

GET /api/v1/reports/$REPORT_ID/common_a11y_issues

Get a Common A11Y issue on a Report

GET /api/v1/reports/$REPORT_ID/common_a11y_issues/$COMMON_A11Y_ISSUE_ID

Common HTML Issues

List Common HTML issues on a Report

GET /api/v1/reports/$REPORT_ID/common_html_issues

Get a Common HTML issue on a Report

GET /api/v1/reports/$REPORT_ID/common_html_issues/$COMMON_HTML_ISSUE_ID

Mutings

List your Mutings

GET /api/v1/mutings

Get a Muting

GET /api/v1/mutings/$MUTING_ID

Schedules

List your Schedules

GET /api/v1/schedules

Get a Schedule

GET /api/v1/schedules/$SCHEDULE_ID

Devices

List all Devices

GET /api/v1/devices

Get a Device

GET /api/v1/devices/$DEVICE_ID

Guest Accounts

List all your Guest Accounts

GET /api/v1/guest_accounts

Get a Guest Account

GET /api/v1/guest_accounts/$GUEST_ACCOUNT_ID

API Costs

The Rocket Validator API is free, and requests don't consume credits. You're charged only for the validations they start: one credit per engine, per checked page. See Credits for the full breakdown.

Reading data costs nothing, however many requests it takes. Only the two endpoints that start a validation spend credits:

POST /api/v1/reports

PATCH /api/v1/reports/$REPORT_ID/web_pages/$WEBPAGE_ID

Both return 402 Payment Required when you've run out of credits. The read endpoints keep working.

API Rate Limit

Currently the Rocket Validator is not rate limited, but it will be soon, to ensure reasonable limits in our resource usage. To stay within it when it arrives:

  • Use a high page size when paginating, so each request returns more data.
  • Cache what you display instead of querying the API on every page view.
  • Query from your server rather than from a script running on every page of your site.