AcuityScan API

Authentication

Every request must carry a valid API token. Two headers are accepted — pick whichever fits your client. You can only have one active token at a time, and the plaintext is only visible at creation; if you lose it, revoke and mint a fresh one in /settings.

Authorization: Bearer asc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

— or —

x-api-key: asc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are bound to your account, not to any one IP — use them from any host. Your plan tier is re-checked on every request, so a downgrade demotes API access immediately (even on previously-minted tokens). Revoke the token in /settings if it leaks.

Rate limit

250 requests / 24 h per Agency account.The window is a rolling 24 hours from your oldest in-window call.

When you exceed:

HTTP/1.1 429 Too Many Requests

{ "error": "API daily cap reached (250/day). Resets at 2026-05-14T...Z.",
  "code": "rate_limit",
  "used": 250,
  "cap": 250,
  "resetAt": "2026-05-14T..." }

Need more? Email support@acuityscan.com with your use case.

Endpoints

All endpoints return JSON. All POST bodies take a domain field. Base URL: https://acuityscan.com.

curl -X POST https://acuityscan.com/api/v1/scan \
  -H "Authorization: Bearer asc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "example.com" }'

curl https://acuityscan.com/api/v1/scan/latest?domain=example.com \
  -H "Authorization: Bearer asc_live_xxx"

curl -X POST https://acuityscan.com/api/v1/tools/email \
  -H "Authorization: Bearer asc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "example.com" }'

curl -X POST https://acuityscan.com/api/v1/tools/dns \
  -H "Authorization: Bearer asc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "example.com" }'

curl -X POST https://acuityscan.com/api/v1/tools/ssl \
  -H "Authorization: Bearer asc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "example.com" }'

curl -X POST https://acuityscan.com/api/v1/tools/performance \
  -H "Authorization: Bearer asc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "example.com" }'

curl -X POST https://acuityscan.com/api/v1/tools/seo \
  -H "Authorization: Bearer asc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "example.com" }'

curl -X POST https://acuityscan.com/api/v1/tools/accessibility \
  -H "Authorization: Bearer asc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "example.com" }'

curl -X POST https://acuityscan.com/api/v1/tools/privacy \
  -H "Authorization: Bearer asc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "example.com" }'

curl -X POST https://acuityscan.com/api/v1/tools/mobile \
  -H "Authorization: Bearer asc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "example.com" }'

When the target site refuses our scanner

Many real-world sites are behind a WAF or bot manager (Cloudflare, Akamai, Imperva, DataDome, etc.) that challenges automated traffic with a JavaScript test before letting it through to the origin. Our scanner can't solve that challenge, so the modules that need to read the page's HTML can't complete.

The response still returns 200 OK. The top-level blocked object tells you which modules were affected and how bad the block was. overallScore is either a partial average (modules that ran) or null depending on severity.

{
  "domain": "example.com",
  "overallScore": null,
  "moduleResults": { ... },
  "blocked": {
    "detected": true,
    "severity": "major",
    "vendor": "Cloudflare",
    "affectedModules": ["seo", "privacy", "mobile"],
    "affectedWeight": 0.30,
    "message": "Cloudflare blocked our scanner from reading..."
  }
}

Recommended client code: branch on result.blocked.severity. For major, don't treat overallScore as comparable to other scans (it's null). For partial, surface the message and treat the score as a partial audit. Individual moduleResults[id].blocked carries per-module vendor + reason if you need fine-grained detail.

Error codes

Every error response carries { error, code }. Thecode is the machine tag; branch on it.

We ship an open-source Model Context Protocol server that wraps every endpoint above as an MCP tool. Drop it into Claude Desktop, Cursor, or Continue and ask in plain English: “run a full AcuityScan on stripe.com.”

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "acuityscan": {
      "command": "npx",
      "args": ["-y", "@acuityscan/mcp"],
      "env": {
        "ACUITYSCAN_API_KEY": "asc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor, Continue, and other MCP clients use the same command / args / env shape. Full setup guides in the repo.