API documentation

Authentication

Create keys in your dashboard under Platform API. Send the key on every request. Keys are shown once; we only store a hash.

Authorization: Bearer ags_live_...

Start a check

tier is free (one page: score, area scores and every issue) or full (up to 5 pages, desktop and mobile). Add an https callback_url to be told when it's finished. Returns straight away with status queued.

curl -X POST https://agorascan.ai/api/v1/scans \
  -H "Authorization: Bearer $AGORASCAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://customer-site.co.uk","tier":"full","callback_url":"https://you.example/hooks/agorascan"}'

Get a check

Statuses: queued, running, complete, blocked (the site refused automated browsers, or is a kind we don't check) and failed.

curl https://agorascan.ai/api/v1/scans/{id} -H "Authorization: Bearer $AGORASCAN_KEY"

{
  "id": "v1WYnvyeEEk4",
  "url": "https://customer-site.co.uk/",
  "status": "complete",
  "tier": "full",
  "report_url": "https://agorascan.ai/w/v1WYnvyeEEk4?t=...",
  "result": {
    "score": 72,
    "categories": [{ "id": "usability", "label": "Usability", "score": 64, "issues": 5 }, ...],
    "summary": "Clear offer, but the main button is easy to miss on phones.",
    "issues": [{
      "id": "a3", "title": "Main button hard to see on phones", "category": "usability",
      "severity": "high", "effort": "quick_win", "page": "https://customer-site.co.uk/",
      "summary": "...", "fix": "...", "rewrites": []
    }, ...],
    "pages": ["https://customer-site.co.uk/", ...]
  }
}

Webhooks

When a check with a callback_url finishes, we POST { "type": "scan.completed", "data": { ...same as GET } }. Check the signature with your webhook secret before trusting it:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, headers, secret) {
  const timestamp = headers["agorascan-timestamp"];
  const expected = "v1=" + createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const given = headers["agorascan-signature"] ?? "";
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
  return fresh && given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

White-label reports

report_url opens a report with your name and colour from your white-label settings, and no AgoraScan pricing or links. Share it with your customer, or build your own view from result.

Errors and limits

• 401 unauthorized: missing, wrong or revoked key.
• 400 invalid_request / invalid_callback: check the JSON body.
• 422 invalid_url / not_allowed: not a public website, or a kind we don't check (adult, gambling, government).
• 429 rate_limited: the key's daily limit is reached (1,000 by default; we can raise it).

Data: you're the controller of your customers' data and we act as your processor under our data processing addendum. Results are kept for 24 months unless you ask us to delete them sooner.