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,axeandaccesslint, 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/reportswe'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
GETkind 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
--urlparameter 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.