Skip to main content

API V2 reference (beta)

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.

API V2 is in beta

API V2 may still change before it's generally available. API V1 keeps working as before, and the API V1 reference still covers it.

V2 names the engines w3c_validator, axe and accesslint, and it returns two kinds of results that V1 doesn't: AccessLint Core issues and Axe Core manual reviews. If you're moving an integration over, Migrating from V1 covers the renames and the new endpoints.

Current version

The Rocket Validator API is currently in version v2.

All endpoints have the prefix:

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

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

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

we'll use this:

GET /api/v2/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/v2/reports \

     --header 'authorization: Bearer $API_TOKEN'

Ruby

require 'uri'

require 'net/http'

require 'openssl'



url = URI("https://rocketvalidator.com/api/v2/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

Python

import http.client



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



payload = ""



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



conn.request("GET", "/api/v2/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/v2/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/v2/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/v2/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/v2/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/v2/reports \

   --header 'authorization: Bearer $API_TOKEN'

Reports

Create a Report

Send a POST request to /api/v2/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/v2/reports

{

  "data": {

    "attributes": {

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

      "max_pages": 100

    }

  }

}

List your Reports

GET /api/v2/reports

Get a Report

GET /api/v2/reports/$REPORT_ID

Delete a Report

DELETE /api/v2/reports/$REPORT_ID

Web Pages

List the Web Pages on a Report

GET /api/v2/reports/$REPORT_ID/web_pages

Get a Web Page on a Report

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

W3C Validator Issues

List W3C Validator issues on a Web Page

GET /api/v2/reports/$REPORT_ID/web_pages/$WEBPAGE_ID/w3c_validator_issues

Get a W3C Validator issue on a Web Page

GET /api/v2/reports/$REPORT_ID/web_pages/$WEBPAGE_ID/w3c_validator_issues/$ISSUE_ID

Axe Issues

List Axe issues on a Web Page

GET /api/v2/reports/$REPORT_ID/web_pages/$WEBPAGE_ID/axe_issues

Get an Axe issue on a Web Page

GET /api/v2/reports/$REPORT_ID/web_pages/$WEBPAGE_ID/axe_issues/$RULE_ID

Axe Manual Reviews

List Axe manual reviews on a Web Page

GET /api/v2/reports/$REPORT_ID/web_pages/$WEBPAGE_ID/axe_manual_reviews

Get an Axe manual review on a Web Page

GET /api/v2/reports/$REPORT_ID/web_pages/$WEBPAGE_ID/axe_manual_reviews/$RULE_ID

AccessLint Issues

List AccessLint issues on a Web Page

GET /api/v2/reports/$REPORT_ID/web_pages/$WEBPAGE_ID/accesslint_issues

List AccessLint issues by category on a Web Page

GET /api/v2/reports/$REPORT_ID/web_pages/$WEB_PAGE_ID/accesslint_issues/$CATEGORY

Get an AccessLint issue on a Web Page

GET /api/v2/reports/$REPORT_ID/web_pages/$WEBPAGE_ID/accesslint_issues/$CATEGORY/$RULE_SLUG

Common W3C Validator Issues

List Common W3C Validator issues on a Report

GET /api/v2/reports/$REPORT_ID/common_w3c_validator_issues

Get a Common W3C Validator issue on a Report

GET /api/v2/reports/$REPORT_ID/common_w3c_validator_issues/$COMMON_W3C_VALIDATOR_ISSUE_ID

Common Axe Issues

List Common Axe issues on a Report

GET /api/v2/reports/$REPORT_ID/common_axe_issues

Get a Common Axe issue on a Report

GET /api/v2/reports/$REPORT_ID/common_axe_issues/$RULE_ID

Common Axe Manual Reviews

List Common Axe manual reviews on a Report

GET /api/v2/reports/$REPORT_ID/common_axe_manual_reviews

Get a Common Axe manual review on a Report

GET /api/v2/reports/$REPORT_ID/common_axe_manual_reviews/$RULE_ID

Common AccessLint Issues

List Common AccessLint issues on a Report

GET /api/v2/reports/$REPORT_ID/common_accesslint_issues

List Common AccessLint issues by category on a Report

GET /api/v2/reports/$REPORT_ID/common_accesslint_issues/$CATEGORY

Get a Common AccessLint issue on a Report

GET /api/v2/reports/$REPORT_ID/common_accesslint_issues/$CATEGORY/$RULE_SLUG

Mutings

List your Mutings

GET /api/v2/mutings

Get a Muting

GET /api/v2/mutings/$MUTING_ID

Schedules

List your Schedules

GET /api/v2/schedules

Get a Schedule

GET /api/v2/schedules/$SCHEDULE_ID

Devices

List all Devices

GET /api/v2/devices

Get a Device

GET /api/v2/devices/$DEVICE_ID

Guest Accounts

List all your Guest Accounts

GET /api/v2/guest_accounts

Get a Guest Account

GET /api/v2/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/v2/reports

PATCH /api/v2/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.