Preparing your report…
Audit any URL for Traditional SEO, AI Answer Engine Optimisation, and Agent Discovery in a single API call.
All API requests require a Bearer token in the Authorization header. You can create API keys from your dashboard.
Authorization: Bearer hs_live_...
API keys are prefixed with hs_live_ and shown only once at creation. Store them securely.
Run a full SEO, AEO, and Agent Discovery audit on a URL. Returns scores, individual check results, prioritised gaps, and a link to the visual report.
Audits typically take 10-30 seconds depending on the site (PageSpeed API + sitemap crawl). Each audit consumes 1 credit.
{
"url": "https://stripe.com"
}curl -X POST https://holysignal.xyz/api/v1/audit \
-H "Authorization: Bearer hs_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://stripe.com"}'{
"data": {
"auditId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"url": "https://stripe.com",
"domain": "stripe.com",
"scores": {
"overall": 61,
"traditional": { "score": 74, "band": "good", "passed": 14, "total": 23 },
"aeo": { "score": 33, "band": "critical", "passed": 4, "total": 13 },
"agentDiscovery": { "score": 90, "band": "strong", "passed": 17, "total": 19 }
},
"checks": [
{
"id": "canonical",
"passed": true,
"score": 100,
"weight": "high",
"system": "traditional",
"title": "Canonical URL",
"details": "Canonical URL found: https://stripe.com",
"recommendation": "Your canonical URL is set correctly..."
}
],
"gaps": [
{
"id": "faq-jsonld",
"title": "Let AI engines pull your FAQ answers directly",
"system": "aeo",
"impact": 200,
"isQuickWin": true,
"recommendation": "Add FAQPage JSON-LD with real Q&A pairs..."
}
],
"quickWins": [ ... ],
"reportUrl": "https://holysignal.xyz/report/X-_ZDQJKM0BP",
"pageCount": 1,
"auditedAt": "2026-03-28T03:15:00.000Z"
},
"meta": {
"credits": { "used": 3, "remaining": 47, "total": 50, "plan": "free" },
"responseTimeMs": 4523,
"version": "v1"
}
}Key fields:
scores.overall — Weighted composite (40% traditional + 40% AEO + 20% agent discovery)scores.*.band — One of strong, good, needs-work, criticalchecks — Full array of all individual check results with scores, recommendations, and fix snippetsgaps — Checks that failed, sorted by impact. isQuickWin: true marks low-effort, high-impact fixesreportUrl — Shareable link to the visual report pagemeta.credits — Your remaining credit balance after this requestCheck your current credit balance and billing cycle dates.
curl https://holysignal.xyz/api/v1/usage \ -H "Authorization: Bearer hs_live_YOUR_KEY"
{
"plan": "free",
"credits": {
"used": 3,
"total": 50,
"remaining": 47
},
"cycle": {
"start": "2026-03-01T00:00:00.000Z",
"end": "2026-04-01T00:00:00.000Z"
}
}All errors return a consistent JSON envelope:
{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
}| Code | Status | Description |
|---|---|---|
| UNAUTHORIZED | 401 | Missing or invalid API key |
| CREDITS_EXCEEDED | 429 | Monthly credit limit reached |
| RATE_LIMITED | 429 | Too many requests per second. Check Retry-After header. |
| INVALID_PARAMS | 400 | Bad request body (missing or malformed url field) |
| INVALID_URL | 422 | URL not reachable or returned an error |
| AUDIT_TIMEOUT | 504 | Audit exceeded the 60-second time limit |
| INTERNAL_ERROR | 500 | Unexpected server error |
Each API call consumes 1 credit. Credits reset at the start of each billing cycle (1st of the month).
| Plan | Credits / month | Rate limit |
|---|---|---|
| Free | 50 | 1 req/sec (burst 3) |
| Pro | 2,000 | 5 req/sec (burst 15) |
| Scale | 10,000 | 10 req/sec (burst 30) |
Each audit runs 55 checks across three scoring systems. The overall score is a weighted composite.
23 checks
Meta tags, canonical URL, Open Graph, heading hierarchy, image alt text, structured data (Organization, Product, Article, FAQ, Breadcrumb), Core Web Vitals, HTTPS, viewport, sitemap.
13 checks
Answer-first content, question headings, external citations, structured lists, FAQ schema quality, author attribution, publication dates, testimonials, content depth, paragraph structure, entity consistency, content freshness.
19 checks
llms.txt (presence, description, links), llms-full.txt, agents.txt, robots.txt permissions for 13 AI crawlers (GPTBot, ClaudeBot, PerplexityBot, CCBot, ChatGPT-User, OAI-SearchBot, GoogleOther, Google-Extended, Bytespider, Applebot-Extended, cohere-ai, Meta-ExternalAgent, anthropic-ai), sitemap in robots.txt.
Coming soon: