# Migrating from V1

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

API V2 uses the same API tokens, JSON:API format, pagination and credit costs as API V1. Most of the migration is renaming. V1 called the engines `html` and `a11y`, while V2 uses the names you see in your reports: W3C Validator, Axe and AccessLint.

API V1 keeps working, so you can move your integration over one endpoint at a time.


> **V1 names have no effect in V2**
>
> V2 ignores the V1 names without raising an error. If you send `perform_html_checks` to V2, or sort reports by `a11y_errors-desc`, you get the defaults. Rename everything listed on this page.

## Base URL

Replace the `/api/v1` prefix with `/api/v2`:

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

## Endpoints

Reports, web pages, schedules, mutings, devices, guest accounts and excluded URLs keep their V1 paths. The engine endpoints take the new names:

| V1 | V2 |
|----|----|
| `/reports/$REPORT_ID/web_pages/$WEB_PAGE_ID/html_issues` | `/reports/$REPORT_ID/web_pages/$WEB_PAGE_ID/w3c_validator_issues` |
| `/reports/$REPORT_ID/web_pages/$WEB_PAGE_ID/a11y_issues` | `/reports/$REPORT_ID/web_pages/$WEB_PAGE_ID/axe_issues` |
| `/reports/$REPORT_ID/web_pages/$WEB_PAGE_ID/raw_html_check` | `/reports/$REPORT_ID/web_pages/$WEB_PAGE_ID/raw_w3c_validator_check` |
| `/reports/$REPORT_ID/web_pages/$WEB_PAGE_ID/raw_a11y_check` | `/reports/$REPORT_ID/web_pages/$WEB_PAGE_ID/raw_axe_check` |
| `/reports/$REPORT_ID/common_html_issues` | `/reports/$REPORT_ID/common_w3c_validator_issues` |
| `/reports/$REPORT_ID/common_a11y_issues` | `/reports/$REPORT_ID/common_axe_issues` |

V2 also adds endpoints that V1 doesn't have:

| Endpoint | Returns |
|----------|---------|
| `/reports/$REPORT_ID/web_pages/$WEB_PAGE_ID/axe_manual_reviews` | The [Axe manual reviews](https://rocketvalidator.com/docs/api-v2/axe_manual_reviews) on a web page |
| `/reports/$REPORT_ID/web_pages/$WEB_PAGE_ID/accesslint_issues` | The [AccessLint issues](https://rocketvalidator.com/docs/api-v2/accesslint_issues) on a web page |
| `/reports/$REPORT_ID/web_pages/$WEB_PAGE_ID/accesslint_issues/$CATEGORY` | The [AccessLint issues in one category](https://rocketvalidator.com/docs/api-v2/accesslint_issues#list-accesslint-issues-by-category) on a web page |
| `/reports/$REPORT_ID/web_pages/$WEB_PAGE_ID/raw_accesslint_check` | The [raw AccessLint check](https://rocketvalidator.com/docs/api-v2/raw_checks) of a web page |
| `/reports/$REPORT_ID/common_axe_manual_reviews` | The [Common Axe manual reviews](https://rocketvalidator.com/docs/api-v2/common_axe_manual_reviews) of a report |
| `/reports/$REPORT_ID/common_accesslint_issues` | The [Common AccessLint issues](https://rocketvalidator.com/docs/api-v2/common_accesslint_issues) of a report |
| `/reports/$REPORT_ID/common_accesslint_issues/$CATEGORY` | The [Common AccessLint issues in one category](https://rocketvalidator.com/docs/api-v2/common_accesslint_issues#list-common-accesslint-issues-by-category) of a report |

## Report and schedule attributes

Reports and schedules use the new engine names, both in the attributes you send and in the ones you get back:

| V1 | V2 |
|----|----|
| `perform_html_checks` | `perform_w3c_validator_checks` |
| `perform_a11y_checks` | `perform_axe_checks` |
| `store_raw_html_checks` | `store_raw_w3c_validator_checks` |
| `store_raw_a11y_checks` | `store_raw_axe_checks` |

`perform_accesslint_checks` and `store_raw_accesslint_checks` are new, on reports and on schedules. `store_incomplete_checks` keeps its name.

A report's `checks` follows the same names. Its `html` key is now `w3c_validator`, `a11y` is now `axe`, and `accesslint` is new. When the report stores manual reviews, `axe` also counts them in `manual_reviews`.

## Web page attributes

| V1 | V2 |
|----|----|
| `html_check` | `w3c_validator_check` |
| `a11y_check` | `axe_check` |

`accesslint_check` is new, and a web page's `status` now takes AccessLint into account along with the other engines. A page whose checks finished with at least one of them skipped reports `skipped`, where V1 returns an error.

## Filters

| V1 | V2 |
|----|----|
| `filter[common_html_issue_id]` | `filter[common_w3c_validator_issue_id]` |
| `filter[common_a11y_issue_id]` | `filter[common_axe_issue_id]` |

`filter[common_axe_issue_id]` takes an Axe rule ID, such as `color-contrast`, instead of the numeric ID that V1 used. Two filters are new: `filter[common_axe_manual_review_id]`, which also takes an Axe rule ID, and `filter[common_accesslint_issue_id]`, which takes an AccessLint rule ID such as `distinguishable/color-contrast`. See [filtering web pages](https://rocketvalidator.com/docs/api-v2/web_pages#list-web-pages-on-a-report).

## Sorting reports

| V1 | V2 |
|----|----|
| `html_issues` | `w3c_validator_issues` |
| `html_errors` | `w3c_validator_errors` |
| `html_warnings` | `w3c_validator_warnings` |
| `a11y_issues` | `axe_issues` |
| `a11y_errors` | `axe_errors` |
| `a11y_warnings` | `axe_warnings` |

You still add `-asc` or `-desc`, as in `sort=axe_errors-desc`. V2 can also sort by `axe_manual_reviews`, `accesslint_issues`, `accesslint_errors` and `accesslint_warnings`. The other [sort keys](https://rocketvalidator.com/docs/api-v2/reports#sorting-reports) work as in V1.

## Resource types and IDs

The JSON:API `type` of each engine resource follows the new names:

| V1 | V2 |
|----|----|
| `html_issue` | `w3c_validator_issue` |
| `a11y_issue` | `axe_issue` |
| `common_html_issue` | `common_w3c_validator_issue` |
| `common_a11y_issue` | `common_axe_issue` |

The new resources are `axe_manual_review`, `common_axe_manual_review`, `accesslint_issue` and `common_accesslint_issue`. A raw check's `kind` is now `w3c_validator`, `axe` or `accesslint`, where V1 returned `html` or `a11y`.

V1 identified accessibility issues by a numeric ID. V2 identifies Axe issues and manual reviews by their Axe rule ID, both on a web page and across a report:

> `GET /api/v2/reports/$REPORT_ID/web_pages/$WEB_PAGE_ID/axe_issues/color-contrast`

## Validation errors

When V2 rejects an attribute, the error's `source.pointer` and `detail` use its V2 name, as in `/data/attributes/perform_axe_checks` and `Perform axe checks is invalid`.