REST API
CrawlScope API
One endpoint. POST a URL. Get a complete structured audit report back as JSON. No key required for self-hosted instances.
Endpoint
POST/api/scan
Accepts a JSON body, launches a real Chromium browser, runs a full Lighthouse audit, parses the HTML with Cheerio, captures screenshots, and returns a structured AuditReport object.
Request
Headers
Content-Type: application/json
Body
{
"url": "https://example.com"
}
"url": "https://example.com"
}
Example — fetch
const res = await fetch("/api/scan", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ url: "https://example.com" }),
});
const { success, report, error } = await res.json();
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ url: "https://example.com" }),
});
const { success, report, error } = await res.json();
Response
Success (200)
{
"success": true,
"report": {
"url": "https://example.com",
"domain": "example.com",
"overall": 84,
"lighthouse": { performance, seo, accessibility, bestPractices },
"vitals": { lcp, cls, inp, ttfb, fcp },
"stats": { critical, warnings, passed, total },
"priorityFixes": [...],
"seoChecks": [...],
"screenshots": { desktop, mobile },
"meta": { title, description, h1, wordCount, ... }
}
}
"success": true,
"report": {
"url": "https://example.com",
"domain": "example.com",
"overall": 84,
"lighthouse": { performance, seo, accessibility, bestPractices },
"vitals": { lcp, cls, inp, ttfb, fcp },
"stats": { critical, warnings, passed, total },
"priorityFixes": [...],
"seoChecks": [...],
"screenshots": { desktop, mobile },
"meta": { title, description, h1, wordCount, ... }
}
}
Error (400 / 500)
{
"success": false,
"error": "Invalid URL"
}
"success": false,
"error": "Invalid URL"
}
Notes
- ·Scans take 30–90 seconds depending on the target site's performance.
- ·Screenshots are returned as base64-encoded JPEG data URIs.
- ·The endpoint runs server-side only — Puppeteer and Lighthouse require Node.js with a Chromium binary.
- ·For self-hosted deployments, no API key is required. The endpoint is open by default.
- ·Set a request timeout of at least 120 seconds in your HTTP client to account for slow target sites.
- ·Screenshots add ~200–400 KB to the response payload. Parse JSON server-side if possible.