Developers

Build on AIScan

One HTTP call returns a full AI-readiness audit: score, grade, detected platform, per-check evidence, and ordered fix steps. Machine-readable everywhere — OpenAPI 3.1, RFC 9727 catalog, RFC 9457 errors, and an MCP server your agent can call directly.

Quick start

curl 'https://aiscan.site/api/public/v1/scan?url=https://example.com'

curl -X POST https://aiscan.site/api/public/v1/scan \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $AISCAN_API_KEY' \
  -d '{"url":"https://example.com","fresh":true}'

Endpoints

Endpoint	Purpose
GET\|POST /api/public/v1/scan	Stable scan endpoint. Additive-only contract.
GET /api/public/v1/report/{id}	Read a stored, shareable report by its short id.
POST /api/scan	Server-sent events stream with live per-step progress.
/api/mcp	MCP (streamable HTTP): `scan_website`, `get_fixes`, `get_grade`.
GET /openapi.json	OpenAPI 3.1 description of everything above.

Discovery files: /.well-known/api-catalog (RFC 9727), /openapi.json, /server.json, /llms.txt.

Authentication

Anonymous calls work with no credentials. To lift the IP rate limit, create a key on your profile and send it as Authorization: Bearer <key>. Keys are bound to your account, so scans made with a key land in your history and honour your default scan visibility.

Rate limits

· Anonymous: 5 requests per minute per IP.
· With an API key: no IP limit; fair use monitored.
· Identical URLs are served from a 5-minute result cache. Pass fresh=1 to force a live scan.
· A limited request returns 429 with a Retry-After header and a problem document.

Errors (RFC 9457)

Every /api/public/v1/* failure returns application/problem+json with a stable type URI you can branch on.

{
  "type": "https://aiscan.site/problems/invalid-url",
  "title": "The supplied url is not scannable",
  "status": 400,
  "detail": "example.com is a reserved documentation domain.",
  "instance": "/api/public/v1/scan"
}

Types: invalid-url, missing-parameter, not-found, rate-limited, method-not-allowed, scan-failed.

Versioning & deprecation policy

· v1 is additive only: fields may be added, never removed or renamed, and enum values are only extended.
· Breaking changes ship under a new prefix (/api/public/v2/…).
· A superseded version keeps serving for at least 180 days, carrying Deprecation and Sunset response headers per RFC 9745/8594.
· Rubric changes never break the API shape; each result reports its rubricVersion so historical scores stay explainable.
· Every change is logged on the changelog.

Agent integrations

Point any MCP client at https://aiscan.site/api/mcp, install the AIScan skill on ClaWHub, drop /CLAUDE.md into a Claude Code project, or talk to the Telegram bot.