REST API — AIScan Docs

REST API

Run scans programmatically via /api/public/scan — parameters, response shape, and rate limits.

Endpoint

One endpoint, two methods:

GET  https://aiscan.site/api/public/scan?url=<url>
POST https://aiscan.site/api/public/scan
     Content-Type: application/json
     { "url": "<url>" }

No authentication required for public scans. Use API keys for a higher rate limit and to write to your account.

Request

Param	Type	Required	Notes
`url`	string	Yes	Full URL with scheme. AIScan adds `https://` if missing.

Response

The response is the full scan result — the same JSON that powers the web UI.

{
  "url": "https://example.com",
  "platform": { "platform": "wordpress", "confidence": 0.9, "evidence": [...] },
  "overallScore": 72,
  "grade": "B",
  "level": 3,
  "levelName": "Readable",
  "dimensions": {
    "discoverability": { "score": 85, "applicable": true },
    "content":         { "score": 70, "applicable": true },
    "bot_access":      { "score": 60, "applicable": true },
    "capabilities":    { "score": 0,  "applicable": true },
    "commerce":        { "score": 0,  "applicable": false }
  },
  "checks": [
    {
      "id": "D1",
      "name": "robots.txt present & sane",
      "dimension": "discoverability",
      "status": "pass",
      "weight": 6,
      "earned": 6,
      "evidence": "200 OK, 412 bytes, declares Sitemap",
      "remediation": "Serve a non-blocking /robots.txt that references your Sitemap.",
      "fixGuide": { "...": "..." }
    }
  ]
}

See Scoring & Levels for what each field means and the check reference for every id.

Rate limits

Anonymous — 5 requests per minute per IP.
With API key — higher (see API keys).

Don't loop scans. The right pattern is scan → fix → re-scan.

Errors

Status	Meaning
400	Missing or invalid `url`.
422	URL fetched but couldn't be parsed (DNS error, TLS error, blocked).
429	Rate limit hit. Retry after the `Retry-After` header.
500	Server error. Retry once after a short delay; if it persists, open an issue.

Examples

cURL

curl -X POST https://aiscan.site/api/public/scan \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com"}'

JavaScript (fetch)

const res = await fetch("https://aiscan.site/api/public/scan", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com" }),
});
const report = await res.json();
console.log(report.overallScore, report.grade);

Python

import requests
r = requests.post(
    "https://aiscan.site/api/public/scan",
    json={"url": "https://example.com"},
    timeout=60,
)
report = r.json()
print(report["overallScore"], report["grade"])