Developers

API reference

Read sites, scans and accessibility issues, and start scans, from your own tools. The API is part of the Agency Pro plan. Base URL: https://api.everyvisitor.app/v1. Download the OpenAPI 3.1 document.

Authentication

Create a key in Settings → API keys (organisation owners only) and send it in the Authorization header. Keys start with psk_ and are shown once. A key has the read scope, and optionally scan:write to start scans. Keep keys on your server, never in browser code.

curl "https://api.everyvisitor.app/v1/sites" \
  -H "Authorization: Bearer $PLAINSIGHT_API_KEY"

Rate limits

Each key can make 60 requests a minute. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit you get 429 with a Retry-After header in seconds. API scans share the plan’s daily manual-scan allowance per site.

Errors

Errors use one shape with a stable code. A site, scan or issue in another organisation always returns 404, never 403.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Site not found.",
    "details": {}
  }
}

HTTP status codes
Status	Meaning
400	The request is invalid (VALIDATION_ERROR).
401	Missing, invalid or revoked key (API_KEY_INVALID).
402	The organisation is read-only; reads still work (BILLING_REQUIRED).
403	The key lacks a scope (API_KEY_SCOPE), or the plan has no API access (PLAN_LIMIT).
404	Not found, or in another organisation.
409	A scan is already running for that site (SCAN_IN_PROGRESS).
422	A business rule stopped it, such as an unverified site or a used-up allowance.
429	Rate limit reached (RATE_LIMITED).

Sites

List sites

get/sitesScope: read

Every site in the organisation with its latest score and open problem counts.

Parameters for List sites
Parameter	In	Description
status	query	One of: pending_verification, active, paused, error.
q	query	Search by name or URL.
sort	query	One of: score, name, lastScan, openCritical.

Request

curl "https://api.everyvisitor.app/v1/sites" \
  -H "Authorization: Bearer $PLAINSIGHT_API_KEY"

Response 200

{
  "data": {
    "sites": [
      {
        "id": "01929b3e-5f0a-7c3d-9a1b-2c3d4e5f6a7b",
        "name": "Oakhaus",
        "rootUrl": "https://oakhaus.com",
        "platform": "shopify",
        "clientName": "Oakhaus Ltd",
        "status": "active",
        "scanFrequency": "weekly",
        "pageLimit": 250,
        "standard": "wcag22aa",
        "score": 82,
        "lastScanId": "01929b40-1111-7c3d-9a1b-2c3d4e5f6a7b",
        "nextScanAt": "2026-10-27T02:00:00.000Z",
        "openCritical": 2,
        "openSerious": 7,
        "createdAt": "2026-08-12T09:15:00.000Z"
      }
    ]
  }
}

Get a site

get/sites/{siteId}Scope: read

Site detail with the latest scan summary and the score trend of the last 12 scans.

Parameters for Get a site
Parameter	In	Description
siteIdrequired	path

Request

curl "https://api.everyvisitor.app/v1/sites/<siteId>" \
  -H "Authorization: Bearer $PLAINSIGHT_API_KEY"

Response 200

{
  "data": {
    "site": {
      "id": "01929b3e-5f0a-7c3d-9a1b-2c3d4e5f6a7b",
      "name": "Oakhaus",
      "rootUrl": "https://oakhaus.com",
      "platform": "shopify",
      "clientName": "Oakhaus Ltd",
      "status": "active",
      "scanFrequency": "weekly",
      "pageLimit": 250,
      "standard": "wcag22aa",
      "score": 82,
      "lastScanId": "01929b40-1111-7c3d-9a1b-2c3d4e5f6a7b",
      "nextScanAt": "2026-10-27T02:00:00.000Z",
      "openCritical": 2,
      "openSerious": 7,
      "createdAt": "2026-08-12T09:15:00.000Z"
    },
    "score": 82,
    "trend": [
      {
        "scanId": "01929b40-1111-7c3d-9a1b-2c3d4e5f6a7b",
        "score": 82,
        "date": "2026-10-20T02:31:00.000Z"
      }
    ]
  }
}

Issues

List issues for a site

get/sites/{siteId}/issuesScope: read

Parameters for List issues for a site
Parameter	In	Description
siteIdrequired	path
status	query	Comma-separated: open, regressed, needsReview, fixed, ignored.
impact	query	Comma-separated: critical, serious, moderate, minor.
wcag	query	A WCAG criterion such as 1.4.3.
template	query
q	query
page	query	Default 1.
limit	query	Default 50.

Request

curl "https://api.everyvisitor.app/v1/sites/<siteId>/issues" \
  -H "Authorization: Bearer $PLAINSIGHT_API_KEY"

Response 200

{
  "data": {
    "items": [
      {
        "id": "01929b41-2222-7c3d-9a1b-2c3d4e5f6a7b",
        "siteId": "01929b3e-5f0a-7c3d-9a1b-2c3d4e5f6a7b",
        "ruleId": "image-alt",
        "title": "Images must have alternative text",
        "impact": "critical",
        "wcagCriteria": [
          "1.1.1"
        ],
        "wcagLevel": "A",
        "templateKey": "product",
        "selector": ".product-gallery img",
        "htmlSnippet": "<img src=\"/cdn/shoe.jpg\">",
        "status": "open",
        "isRegression": false,
        "occurrenceCount": 48,
        "dueDate": null,
        "fixedAt": null,
        "createdAt": "2026-09-02T02:14:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 50,
    "totalPages": 1
  }
}

Get an issue

get/issues/{issueId}Scope: read

Parameters for Get an issue
Parameter	In	Description
issueIdrequired	path

Request

curl "https://api.everyvisitor.app/v1/issues/<issueId>" \
  -H "Authorization: Bearer $PLAINSIGHT_API_KEY"

Response 200

{
  "data": {
    "issue": {
      "id": "01929b41-2222-7c3d-9a1b-2c3d4e5f6a7b",
      "siteId": "01929b3e-5f0a-7c3d-9a1b-2c3d4e5f6a7b",
      "ruleId": "image-alt",
      "title": "Images must have alternative text",
      "impact": "critical",
      "wcagCriteria": [
        "1.1.1"
      ],
      "wcagLevel": "A",
      "templateKey": "product",
      "selector": ".product-gallery img",
      "htmlSnippet": "<img src=\"/cdn/shoe.jpg\">",
      "status": "open",
      "isRegression": false,
      "occurrenceCount": 48,
      "dueDate": null,
      "fixedAt": null,
      "createdAt": "2026-09-02T02:14:00.000Z"
    }
  }
}

Scans

List scans for a site

get/sites/{siteId}/scansScope: read

Newest first.

Parameters for List scans for a site
Parameter	In	Description
siteIdrequired	path

Request

curl "https://api.everyvisitor.app/v1/sites/<siteId>/scans" \
  -H "Authorization: Bearer $PLAINSIGHT_API_KEY"

Response 200

{
  "data": {
    "scans": [
      {
        "id": "01929b40-1111-7c3d-9a1b-2c3d4e5f6a7b",
        "siteId": "01929b3e-5f0a-7c3d-9a1b-2c3d4e5f6a7b",
        "trigger": "api",
        "status": "queued",
        "queuedAt": "2026-10-21T10:00:00.000Z",
        "startedAt": null,
        "finishedAt": null,
        "pagesPlanned": 250,
        "pagesScanned": 0,
        "score": null,
        "counts": {},
        "errorCode": null
      }
    ]
  }
}

Start a scan

post/sites/{siteId}/scansScope: scan:write

Queues a scan of a verified site. Needs the `scan:write` scope. API scans count toward the same daily allowance as manual scans.

Parameters for Start a scan
Parameter	In	Description
siteIdrequired	path

Request

curl -X POST "https://api.everyvisitor.app/v1/sites/<siteId>/scans" \
  -H "Authorization: Bearer $PLAINSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pagesPlanned":100}'

Response 201

{
  "data": {
    "scan": {
      "id": "01929b40-1111-7c3d-9a1b-2c3d4e5f6a7b",
      "siteId": "01929b3e-5f0a-7c3d-9a1b-2c3d4e5f6a7b",
      "trigger": "api",
      "status": "queued",
      "queuedAt": "2026-10-21T10:00:00.000Z",
      "startedAt": null,
      "finishedAt": null,
      "pagesPlanned": 250,
      "pagesScanned": 0,
      "score": null,
      "counts": {},
      "errorCode": null
    }
  }
}

Get a scan

get/scans/{scanId}Scope: read

Progress while running; score, counts and changes since the previous scan once finished.

Parameters for Get a scan
Parameter	In	Description
scanIdrequired	path

Request

curl "https://api.everyvisitor.app/v1/scans/<scanId>" \
  -H "Authorization: Bearer $PLAINSIGHT_API_KEY"

Response 200

{
  "data": {
    "scan": {
      "id": "01929b40-1111-7c3d-9a1b-2c3d4e5f6a7b",
      "siteId": "01929b3e-5f0a-7c3d-9a1b-2c3d4e5f6a7b",
      "trigger": "api",
      "status": "completed",
      "queuedAt": "2026-10-21T10:00:00.000Z",
      "startedAt": null,
      "finishedAt": null,
      "pagesPlanned": 250,
      "pagesScanned": 250,
      "score": 84,
      "counts": {},
      "errorCode": null
    }
  }
}