{ "openapi": "3.1.0", "info": { "title": "AIScan Public API", "version": "1.0.0", "summary": "Score any website for AI-agent readiness.", "description": "AIScan audits a URL for the standards AI agents rely on — robots.txt, sitemaps, llms.txt, markdown content negotiation, MCP server cards, agent skills, OAuth discovery and agentic commerce — and returns a 0–100 score, an A–F grade, and per-check remediation.\n\n**Rate limits.** Anonymous callers: 5 requests per minute per IP. Requests carrying a valid API key as `Authorization: Bearer ` are not rate limited by IP.\n\n**Errors.** Every `/api/public/v1/*` error is an RFC 9457 `application/problem+json` document.\n\n**Lifecycle.** `v1` is additive-only: new fields may appear, existing fields are never removed or renamed. A breaking change ships as `v2`; the superseded version is then served for at least 180 days with `Deprecation` and `Sunset` response headers.", "termsOfService": "https://aiscan.site/terms", "contact": { "name": "AIScan support", "url": "https://aiscan.site/contact" }, "license": { "name": "Proprietary — free for non-commercial use", "url": "https://aiscan.site/terms" } }, "servers": [ { "url": "https://aiscan.site", "description": "Production" } ], "externalDocs": { "description": "Developer documentation", "url": "https://aiscan.site/developers" }, "tags": [ { "name": "Scans", "description": "Run an AI-readiness scan." }, { "name": "Reports", "description": "Read a previously shared report." } ], "paths": { "/api/public/v1/scan": { "get": { "tags": [ "Scans" ], "operationId": "scanUrlGet", "summary": "Scan a URL", "description": "Runs a full AI-readiness scan and returns the complete result. Results are cached for 5 minutes per URL; pass `fresh=1` to bypass the cache.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Absolute http(s) URL to scan.", "schema": { "type": "string", "format": "uri", "maxLength": 2048 }, "example": "https://example.com" }, { "name": "fresh", "in": "query", "required": false, "description": "Set to 1 to bypass the 5-minute result cache.", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "isPublic", "in": "query", "required": false, "description": "Override the caller's default scan visibility (API-key calls only).", "schema": { "type": "boolean" } } ], "security": [ {}, { "apiKey": [] } ], "responses": { "200": { "description": "Scan completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanResponse" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "502": { "$ref": "#/components/responses/Problem" } } }, "post": { "tags": [ "Scans" ], "operationId": "scanUrlPost", "summary": "Scan a URL (JSON body)", "description": "Identical to the GET form; accepts the same parameters as a JSON body.", "security": [ {}, { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "fresh": { "type": "boolean", "default": false }, "isPublic": { "type": "boolean" } } }, "example": { "url": "https://example.com" } } } }, "responses": { "200": { "description": "Scan completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanResponse" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "502": { "$ref": "#/components/responses/Problem" } } } }, "/api/public/v1/report/{id}": { "get": { "tags": [ "Reports" ], "operationId": "getReport", "summary": "Fetch a shared report", "description": "Returns the stored result behind a shareable /r/{id} report page.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]{4,24}$" } } ], "responses": { "200": { "description": "Report found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportResponse" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An AIScan API key, created at https://aiscan.site/profile. Lifts the anonymous IP rate limit." } }, "responses": { "Problem": { "description": "RFC 9457 problem details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "Problem": { "type": "object", "required": [ "type", "title", "status" ], "properties": { "type": { "type": "string", "format": "uri", "examples": [ "https://aiscan.site/problems/invalid-url" ] }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" } } }, "CheckResult": { "type": "object", "required": [ "id", "name", "dimension", "status", "weight", "earned" ], "properties": { "id": { "type": "string", "examples": [ "D1" ] }, "name": { "type": "string" }, "dimension": { "type": "string", "enum": [ "discoverability", "content", "bot_access", "capabilities", "commerce" ] }, "tier": { "type": "string", "enum": [ "essential", "recommended", "bonus" ], "description": "Baseline requirement vs. optional upside." }, "status": { "type": "string", "enum": [ "pass", "partial", "fail", "na", "info" ] }, "weight": { "type": "number" }, "earned": { "type": "number" }, "evidence": { "type": "string", "description": "What we actually observed (status code, header, body excerpt)." }, "remediation": { "type": "string" }, "optional": { "type": "boolean" }, "inherited": { "type": "boolean" }, "fixGuide": { "type": "array", "items": { "$ref": "#/components/schemas/FixStep" } } } }, "FixStep": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string" }, "body": { "type": "string" }, "code": { "type": "string" }, "lang": { "type": "string" } } }, "ScanResponse": { "type": "object", "required": [ "url", "overallScore", "level", "checks" ], "properties": { "apiVersion": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "scannedAt": { "type": "string", "format": "date-time" }, "durationMs": { "type": "integer" }, "overallScore": { "type": "integer", "minimum": 0, "maximum": 100 }, "level": { "type": "integer", "minimum": 0, "maximum": 5 }, "levelName": { "type": "string" }, "scope": { "type": "string", "enum": [ "site", "page" ] }, "rubricVersion": { "type": "string" }, "cached": { "type": "boolean" }, "shareId": { "type": "string" }, "shareUrl": { "type": "string", "format": "uri" }, "platform": { "type": "object", "properties": { "platform": { "type": "string" }, "confidence": { "type": "integer" }, "evidence": { "type": "array", "items": { "type": "string" } }, "isEcommerce": { "type": "boolean" }, "isApp": { "type": "boolean" }, "seoPlugin": { "type": [ "string", "null" ] } } }, "dimensions": { "type": "object", "additionalProperties": { "type": "object", "properties": { "earned": { "type": "number" }, "weight": { "type": "number" }, "score": { "type": "integer" }, "applicable": { "type": "boolean" } } } }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/CheckResult" } } } }, "ReportResponse": { "type": "object", "properties": { "apiVersion": { "type": "string" }, "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "score": { "type": "integer" }, "grade": { "type": "string" }, "platform": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "htmlUrl": { "type": "string", "format": "uri" }, "result": { "$ref": "#/components/schemas/ScanResponse" } } } } } }