Docs

Scan a URL, get structured WCAG violations back as JSON, and fail your build on the ones you have not already accepted.

Quickstart

Scan a page and print the violations:

# Node 20+. No install step.
npx @skiplink/cli scan https://example.com

Or call the API directly:

curl -X POST https://api.skiplink.dev/v1/scan \
  -H "Authorization: Bearer $SKIPLINK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "standard": "wcag22aa"}'

{
  "id": "scn_9f2c1axkqp",
  "url": "https://example.com",
  "standard": "wcag22aa",
  "status": "done",
  "engine": { "axe_core": "4.12.1", "chromium": "151.0.7922.34" },
  "score": 71,
  "summary": { "critical": 2, "serious": 9, "moderate": 14, "minor": 3 },
  "violations": [
    {
      "rule": "color-contrast",
      "impact": "serious",
      "wcag": ["1.4.3"],
      "selector": ".hero__subtitle",
      "html": "<p class=\"hero__subtitle\">Ship faster</p>",
      "message": "Contrast ratio 3.03:1, needs 4.5:1",
      "fingerprint": "f_887e25a5",
      "fingerprint_loose": "f_002b8cf4"
    }
  ]
}

The free tier is 500 scans a month and needs no card.

Add it to CI

GitHub Actions:

# .github/workflows/a11y.yml
name: Accessibility
on: pull_request

jobs:
  a11y:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: skiplink/action@v1
        with:
          urls: https://staging.example.com
          baseline: .skiplink/baseline.json
          token: ${{ secrets.SKIPLINK_TOKEN }}

Already have a test suite? Check the pages your tests reach — behind a login, on localhost, mid-checkout — with @skiplink/playwright or @skiplink/cypress. Every route shares one baseline file. All four routes compared.

Any other CI system runs the CLI. It needs Node 20+ and nothing else.

npx @skiplink/cli scan https://staging.example.com \
  --baseline .skiplink/baseline.json --fail-on new

Baselines

Point a scanner at a site that already exists and you get a wall of red — the average home page has 56 detectable violations. Nobody fixes 56 issues to unblock a deploy, so the check gets deleted. A baseline is a committed file listing violations you have seen and chosen not to block on; the gate then fails on what is new.

# Once, after reviewing what it finds:
npx @skiplink/cli scan https://staging.example.com \
  --baseline .skiplink/baseline.json --update-baseline
git add .skiplink/baseline.json

# Every build after that:
npx @skiplink/cli scan https://staging.example.com --baseline .skiplink/baseline.json

Get a key

Create an account with an email and a password, confirm the six-digit code we email you, and the welcome flow walks you to a working CI gate. Keys are created and revoked in the dashboard.

A key is shown exactly once. We store only a hash, so it can be replaced but never recovered — which is also why revoking one takes effect on the very next request.

Authentication

Send your key as a bearer token. Keys look like skl_live_… and are shown once at creation — only a hash is stored, so there is no recovery, only reissue.

Authorization: Bearer skl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The CLI reads SKIPLINK_TOKEN from the environment. Never commit a key; in CI it belongs in a repository secret.

Manage keys

GET /v1/keys

Lists active keys with prefix, name, creation and last-use time. Never key material.

POST /v1/keys

Issues another key, up to 20 active per account, and returns the plaintext once. Takes an optional name so you can tell them apart later.

DELETE /v1/keys/{id}

Revokes immediately — the next request with that key gets 401. You may revoke the key you are currently using; locking yourself out is your call to make, and refusing would mean an exposed key stays live while you find another one.

Scan a URL

POST /v1/scan

Blocks for up to 15 seconds waiting for the result. If the scan takes longer you get 202 with a poll_url — the scan is still running, not failed.

Standards

Scan a batch

POST /v1/scan/batch

Up to 50 URLs. Always asynchronous — returns 202 with a scan stub per URL. Takes the same options as a single scan, applied to all of them.

curl -X POST https://api.skiplink.dev/v1/scan/batch \
  -H "Authorization: Bearer $SKIPLINK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com/", "https://example.com/pricing"]}'

A batch is validated whole: if one URL is rejected, none are queued and no quota is consumed. You never have to reason about a partially accepted batch.

Fetch a scan

GET /v1/scans/{id}

Returns the result object. status is queued, running, done or failed. Scans are scoped to the account that created them; another account's id returns 404, not 403.

Account and usage

GET /v1/account

{
  "account_id": "acct_r62e6vzsxs",
  "plan": "growth",
  "usage": {
    "period": 202607,
    "limit": 25000,
    "used": 1834,
    "remaining": 23166,
    "billable_ledger": 1834,
    "overage_allowed": true
  }
}

used is the live counter; billable_ledger is the append-only record invoices are built from. They should agree — when they disagree, the ledger is right.

Monitors

POST /v1/monitors

A monitor is the same gate as CI, pointed at production: it runs on a schedule, holds its own baseline, and notifies you only when a violation appears that it has not already told you about. A tool that alerts on every run is a feed people mute.

Growth plan and above. Each run counts as one scan.

curl -X POST https://api.skiplink.dev/v1/monitors \
  -H "Authorization: Bearer $SKIPLINK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://example.com/checkout",
        "name": "Checkout",
        "interval": "daily",
        "notify_slack": "https://hooks.slack.com/services/..."
      }'

GET /v1/monitors · GET /v1/monitors/{id}

PATCH /v1/monitors/{id} — {"enabled": false} to pause.

DELETE /v1/monitors/{id}

Verifying the webhook signature

A webhook URL ends up in logs, chat messages and screenshots, so treat it as public and check the signature instead. We send Skiplink-Signature: t=<unix>,v1=<hex>, where the signed payload is the timestamp, a dot, and the raw body, HMAC-SHA256 under your webhook secret.

// Node
const [, ts, sig] = header.match(/t=(\d+),v1=([a-f0-9]+)/);
const expected = crypto.createHmac('sha256', secret)
  .update(ts + '.' + rawBody).digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) throw ...;

Reject timestamps more than a few minutes old, or a captured request can be replayed indefinitely.

Client workspaces

POST /v1/workspaces — Agency plan

A workspace is one client: their branding, their scans, their reports. Nothing is shared between workspaces, so a report for one client can never carry another's name.

curl -X POST https://api.skiplink.dev/v1/workspaces \
  -H "Authorization: Bearer $SKIPLINK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "brand_name": "Northwind Digital",
    "brand_color": "#0B6B45",
    "contact": "[email protected]",
    "footer_note": "Confidential — prepared for Acme Corp."
  }'

GET /v1/workspaces · GET /v1/workspaces/{id} · DELETE /v1/workspaces/{id}

Deleting a workspace removes the grouping and its branding. The scans stay — they are your usage history and your evidence of when a page was in what state.

White-label reports

POST /v1/reports — Agency plan

Point it at scans you have already run. Rendering needs a browser, so it returns 202 with a report in queued; poll until done, then download the PDF. A report covers at most 100 pages.

curl -X POST https://api.skiplink.dev/v1/reports \
  -H "Authorization: Bearer $SKIPLINK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace": "wsp_mf3ffeuvxw",
    "title": "Accessibility assessment",
    "client": "Acme Corp",
    "scan_ids": ["scn_9f2c1a", "scn_9f2c1b"]
  }'

GET /v1/reports/{id} · GET /v1/reports/{id}.pdf

Branding is copied into the report when you create it, not read at download time. Re-fetching a report from three months ago gives you the document you sent, with the logo and colours you had then.

The result object

Errors

Errors come back with the HTTP status and a stable machine-readable code:

{ "error": { "code": "blocked_url", "message": "…", "param": "url" } }

URLs we refuse to scan

Scanning means fetching a URL from our infrastructure, so the target has to be somewhere a stranger is allowed to make us go. We refuse anything that is not http or https, anything with credentials in the URL, ports other than 80 and 443, and any hostname resolving to loopback, private, link-local, carrier-grade NAT, or reserved address space — including the cloud metadata endpoint, and including IPv6 transition addresses that wrap a private IPv4 address. Redirect chains are re-checked at every hop.

Limits

Quota headers come back on every scan request: X-Skiplink-Quota-Limit, -Used and -Remaining.

CLI

skiplink scan <url...> [options]

  --baseline <path>      Baseline file. Violations in it do not fail the build.
  --update-baseline      Rewrite the baseline from this run and exit 0.
  --fail-on <level>      new (default) | critical | serious | moderate | minor | never
  --standard <name>      wcag22aa (default) | wcag21aa | wcag2aa | wcag2a | section508 | all
  --format <name>        human (default) | json | github
  --comment-file <path>  Write a markdown report for a PR comment.
  --token <key>          API key. Defaults to $SKIPLINK_TOKEN.
  --wait-for <selector>  Wait for this selector before scanning.
  --timeout <seconds>    Give up waiting for scans. Default 600.
  --quiet                Suppress progress output.

Exit codes

1 and 3 are deliberately distinct. "This page has a new violation" and "we could not find out" are different facts, and a pipeline should be free to retry one and block on the other. A scan that could not run never reports as a pass.