REST API
API Documentation
The aiready.tools API lets you trigger GEO audits, poll status and retrieve full results programmatically. Perfect for integrating AI-readiness checks into your CI/CD pipeline, CMS or reporting dashboards.
Base URL
https://aiready.tools/api/
Authentication
Pass your API key in the request header:
X-API-Key: your_api_key_here
Retrieve your API key from your dashboard under Settings → API.
POST
/api/audit.php
Trigger a new GEO audit. Returns a job_id for status polling.
REQUEST BODY (JSON)
| Parameter | Type | Required | Description |
|---|---|---|---|
url | string | required | Full URL to audit, including https:// |
modules | array | optional | Subset of modules to run. Default: all 7. |
webhook_url | string | optional | POST callback when audit completes. |
curl -X POST https://aiready.tools/api/audit.php \
-H "X-API-Key: your_key" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'
// Response
{
"job_id": "a3f9b2c1d4e5",
"status": "queued",
"estimated_seconds": 30
}
-H "X-API-Key: your_key" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'
// Response
{
"job_id": "a3f9b2c1d4e5",
"status": "queued",
"estimated_seconds": 30
}
GET
/api/audit_status.php?job_id={id}
Poll audit status. Returns queued, running or complete.
// complete response
{
"job_id": "a3f9b2c1d4e5",
"status": "complete",
"geo_score": 63,
"results_url": "https://aiready.tools/results.php?url=https://example.com"
}
{
"job_id": "a3f9b2c1d4e5",
"status": "complete",
"geo_score": 63,
"results_url": "https://aiready.tools/results.php?url=https://example.com"
}
GET
/api/audit.php?url={url}
Retrieve full audit data as JSON for a previously analyzed URL (within 7-day cache window).
// Abbreviated response structure
{
"geo_score": 63,
"verdict": "Fair",
"modules": {
"citability": { "score": 58, "findings": [...] },
"brand": { "score": 41, "platforms": {...} },
"eeat": { "score": 67, "signals": [...] },
"crawlers": { "score": 100, "blocked": [], "allowed": [...] },
"schema": { "score": 28, "types_found": [...] },
"platforms": { "score": 55, "chatgpt": {...}, "perplexity": {...} },
"llmstxt": { "score": 0, "exists": false, "cta_url": "..." }
},
"action_plan": [...],
"analyzed_at": "2026-03-30T12:00:00Z"
}
{
"geo_score": 63,
"verdict": "Fair",
"modules": {
"citability": { "score": 58, "findings": [...] },
"brand": { "score": 41, "platforms": {...} },
"eeat": { "score": 67, "signals": [...] },
"crawlers": { "score": 100, "blocked": [], "allowed": [...] },
"schema": { "score": 28, "types_found": [...] },
"platforms": { "score": 55, "chatgpt": {...}, "perplexity": {...} },
"llmstxt": { "score": 0, "exists": false, "cta_url": "..." }
},
"action_plan": [...],
"analyzed_at": "2026-03-30T12:00:00Z"
}
Error codes
| Code | Meaning |
|---|---|
| 401 | Missing or invalid API key |
| 403 | Plan does not include API access |
| 422 | Invalid URL or unreachable domain |
| 429 | Rate limit exceeded |
| 500 | Internal error — retry after 60s |
Rate limits
Enterprise plan: 100 API requests per hour. Concurrent audit limit: 5. Rate limit headers are included in every response: X-RateLimit-Remaining and X-RateLimit-Reset.