# Rocket Validator API

> Canonical HTML version: https://rocketvalidator.com/docs/api-v2/index
> Attribution: Rocket Validator (https://rocketvalidator.com)
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

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 <a href="https://jsonapi.org/" target="_blank">JSON API</a>.

> **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](https://rocketvalidator.com/docs/api/index) 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](https://rocketvalidator.com/docs/api-v2/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 <a href="https://rocketvalidator.com/registration/new" target="rocket">sign up</a> for a new account and then generate an <a href="https://rocketvalidator.com/api/tokens" target="rocket">API token</a>. Check out the <a href="https://rocketvalidator.com/docs/api-v2/authorization">Authorization</a> 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

``` bash
curl --request GET \
     --url https://rocketvalidator.com/api/v2/reports \
     --header 'authorization: Bearer $API_TOKEN'
```

#### Ruby

``` 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

``` 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
<?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

``` javascript
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

``` java
HttpResponse<String> response = Unirest.get("https://rocketvalidator.com/api/v2/reports")
.header("authorization", "Bearer $API_TOKEN")
.asString();
```

#### Swift

``` 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:
>
> ``` bash
> 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**
>
> ```json
> {
>   "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](https://rocketvalidator.com/docs/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.