Scan API
TL;DR
The Scan API lets you programmatically submit any public URL for AI readiness analysis. You receive an overall score, eight sub-scores, active floors and bonuses, and a prioritized list of issues with fix recommendations.
Last updated: 2026-03-09
Endpoint Overview#
The Scan API accepts a URL and returns a comprehensive AI readiness analysis. It is the same engine that powers the AgentReady™ web interface. Use it to integrate AI readiness scanning into your own tools, dashboards, or CI/CD pipelines.
The endpoint is rate-limited based on your plan tier. Free-tier users can make a limited number of requests per day. Paid plans offer higher limits and priority queue processing.
Scan Endpoint
POST /api/scan
Content-Type: application/json
{
"url": "https://example.com"
}http
Request Parameters#
The scan endpoint accepts a JSON body with the following fields. Only
url is required. All other parameters are optional and control the scope of the analysis.url(string, required) — The publicly accessible URL to scan. Must include the protocol (https://).industry(string, optional) — Override auto-detected industry for benchmark comparisons. Values: saas, ecommerce, media, finance, healthcare, education, etc.depth(string, optional) — Controls how many pages are crawled. Values:shallow(homepage only),standard(up to 25 pages),deep(up to 100 pages). Default:standard.callback_url(string, optional) — A webhook URL to receive results when the scan completes. Useful for async integrations.
Response Format#
A successful scan returns a JSON object containing the overall score, grade, all eight sub-scores, any active floors or bonuses, and the full issues list. The response also includes metadata like the detected CMS, industry, and page count.
Scans typically complete in 15 to 45 seconds. If you use a callback URL, you will receive a POST request when the scan finishes. Otherwise, poll the status endpoint with the returned scan ID.
Response Example (abbreviated)
{
"id": "scan_abc123",
"url": "https://example.com",
"status": "COMPLETE",
"overallScore": 72,
"grade": "B+",
"subScores": {
"schemaMarkup": 65,
"contentQuality": 80,
"botAccess": 90,
"topicClarity": 55,
"aiProtocols": 40,
"speedPerformance": 85,
"authorityTrust": 60,
"crawlHealth": 75
},
"floors": [],
"bonuses": ["schemaContentFoundation"],
"issueCount": 12,
"industry": "saas",
"cmsDetected": "WordPress"
}json
Error Handling#
The API returns standard HTTP status codes. A
200 response indicates success. A 400 response means invalid input — usually a malformed URL or missing required field. A 429 response means you have hit your rate limit. A 500 response indicates a server-side error.
All error responses include a JSON body with an error field describing the problem. If a scan fails mid-process (for example, the target site is unreachable), the scan status will be FAILED with a failureReason field explaining what went wrong.Error Response
{
"error": "Invalid URL format",
"code": "INVALID_URL",
"status": 400
}json
Related Pages
Frequently Asked Questions
Is there a rate limit on the Scan API?
Yes. Rate limits depend on your plan tier. Free-tier users are limited to a small number of scans per day. Paid plans offer significantly higher limits. Check your dashboard for your current usage and limits.
Can I scan pages behind a login?
No. The Scan API only analyzes publicly accessible pages. Pages that require authentication cannot be crawled. Make sure the URL you submit is reachable without a login.
Was this page helpful?