REST API · v1

WebMole API: Run AEO Audits Programmatically

Integrate AI citation readiness scoring into your own tools. Send a URL, get back a structured score, factor-by-factor analysis, and fix suggestions as JSON.

Get your API key Jump to endpoint

Quick start

curl -X POST https://webmole.ai/api/v1/audit \
  -H "Authorization: Bearer wbm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# → { "score": 74, "factors": [...], "fixSuggestions": [...] }

See a live API response →Try in terminal →API overview →Quickstart tutorial →

WebMole API JSON response showing a score of 74 with factor-by-factor analysis and fix suggestions

A live API response: score, per-factor breakdown, and prioritised fix suggestions — all in one JSON payload.

What is Answer Engine Optimisation (AEO)?

Answer Engine Optimisation (AEO) is the practice of structuring your web content so that AI systems — ChatGPT, Perplexity, Google AI Overviews, Claude, Gemini — are more likely to cite your pages when users ask questions in your topic area. Unlike traditional SEO, which targets position in a ranked list, AEO targets the citation decision made by a large language model or retrieval-augmented generation (RAG) pipeline.

AI search engines decide what to cite based on signals like structured data (JSON-LD schema markup), crawlability (robots.txt permissions for AI bots), content clarity (explicit answers, defined entities, factual tone), authority signals (author markup, organization schema, external citations), and freshness (publication dates, last-modified headers). A page that ranks #1 on Google may score poorly on these signals and receive zero AI citations.

The WebMole API measures these signals programmatically across 12 weighted factors, returning a single 0–100 score plus per-factor pass/fail results and prioritised fix suggestions. This lets you audit pages at scale, integrate AEO scoring into your CMS or CI pipeline, and track changes over time without manual UI work.

AEO is not a speculative future concern — AI search now accounts for a measurable and growing share of referral traffic for content-heavy sites. Pages optimised for AI citation tend to get cited across multiple AI engines simultaneously, compounding the benefit. The WebMole API gives you the data layer to make that optimisation systematic.

Authentication

All API requests require a Bearer token in the Authorization header. Generate your key from Dashboard → Settings → API Keys.

Request header

Authorization: Bearer wbm_your_api_key_here

API keys begin with wbm_
Keys are scoped to your account — do not share or commit them to source control
Rotate a compromised key instantly from Dashboard → Settings
Free tier accounts cannot generate API keys — upgrade to Starter or above

Terminal showing a curl request to the WebMole API with a JSON response containing a score of 74

A curl request to /api/v1/audit with a Bearer token — returns structured JSON in under a second.

Endpoint

POST/api/v1/audit

Request body

application/json

{
  "url": "https://example.com/your-page"
}

Field	Type	Required	Description
url	string	Yes	Fully qualified URL to audit (https://…). Max 2048 chars. Private/internal IPs rejected.

Response

200 OK · application/jsonSuccess

{
  "url": "https://example.com",
  "score": 74,
  "categories": {
    "answerReadiness": 80,
    "structure": 70,
    "authoritySignals": 65,
    "technicalGEO": 80
  },
  "factors": [
    {
      "id": 1,
      "name": "Structured Data (JSON-LD)",
      "score": 15,
      "max": 15,
      "status": "pass",
      "details": "Valid JSON-LD found with @type Organization"
    },
    {
      "id": 2,
      "name": "Meta Description",
      "score": 0,
      "max": 8,
      "status": "fail",
      "details": "No meta description found"
    }
  ],
  "fixSuggestions": [
    {
      "factorId": 2,
      "factorName": "Meta Description",
      "impact": "High",
      "instruction": "Add a concise meta description (120-160 chars) summarising the page.",
      "codeBlock": "<meta name=\"description\" content=\"Your page summary here.\" />"
    }
  ],
  "scannedAt": "2026-03-06T12:00:00.000Z",
  "rateLimit": {
    "remaining": 99,
    "limit": 100,
    "resetAt": "2026-03-07T00:00:00.000Z"
  }
}

Code examples

curl

shell

curl -X POST https://webmole.ai/api/v1/audit \
  -H "Authorization: Bearer wbm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

JavaScript (fetch)

javascript

const res = await fetch('https://webmole.ai/api/v1/audit', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wbm_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ url: 'https://example.com' }),
})

const data = await res.json()
console.log(data.score)          // 74
console.log(data.fixSuggestions) // array of fixes

Python (requests)

python

import requests

response = requests.post(
    'https://webmole.ai/api/v1/audit',
    headers={
        'Authorization': 'Bearer wbm_your_api_key',
        'Content-Type': 'application/json',
    },
    json={'url': 'https://example.com'},
)

data = response.json()
print(data['score'])           # 74
print(data['fixSuggestions'])  # list of fixes

Chrome Extension

Audit any page in one click

No curl required. Install the WebMole browser extension and get an instant AEO score for any page you are browsing — with per-factor breakdown and fixes shown directly in the popup.

Score, categories, and top fixes — visible in your browser without leaving the page.

Works on any URLNavigate to any public page, click the WebMole icon, and get results in seconds.

Live fix suggestionsSee exactly what to fix and copy the code snippet directly from the popup.

Syncs with your accountScans count against your plan quota and appear in your dashboard history.

Get the extension

Rate limits

Limits are per API key per calendar day (UTC). Response headers include your current usage:

X-RateLimit-Limit: 100X-RateLimit-Remaining: 99X-RateLimit-Reset: 2026-03-07T00:00:00.000Z

Plan	Requests	Notes
Free	No API access	Dashboard only
Starter	100 / day	Resets at midnight UTC
Pro	500 / day	Resets at midnight UTC
Agency	2,000 / day	Resets at midnight UTC

Need higher limits? Upgrade your plan or contact us for custom volume.

Error codes

All errors return JSON with an error object containing a code and message:

Error response shape

{
  "error": {
    "code": "rate_limited",
    "message": "Daily limit of 100 requests reached. Resets at 2026-03-07T00:00:00.000Z."
  }
}

HTTP status	Code	Meaning
401	unauthorized	Missing or invalid API key. Check your Authorization header.
400	invalid_body / invalid_url	Request body is malformed or the URL is not valid/reachable.
429	rate_limited	Daily request limit reached. Check the Retry-After response header for reset time.
500	score_failed	Internal error scoring the page. Retry once — if it persists, contact support.

Common questions

What is the WebMole API?

The WebMole API lets you run AEO (Answer Engine Optimisation) audits programmatically. Send a URL, get back a structured JSON report with an AI citation readiness score, per-factor analysis, and actionable fix suggestions.

Which plans include API access?

API access is available on Starter ($29/mo), Pro ($49/mo), and Agency ($99/mo) plans. Free tier users cannot access the API. Starter gets 100 requests/day, Pro gets 500, Agency gets 2,000.

How do I authenticate with the WebMole API?

Use a Bearer token in the Authorization header: Authorization: Bearer wbm_your_api_key. Generate your API key from the WebMole dashboard at /dashboard/settings.

What does the AEO audit API return?

The API returns a JSON object with a numeric score (0-100), category scores (answerReadiness, structure, authoritySignals, technicalGEO), per-factor results with numeric score/max/status, and fix suggestions with instruction and optional codeBlock.

What is Answer Engine Optimisation (AEO)?

Answer Engine Optimisation (AEO) is the practice of structuring web content so that AI systems like ChatGPT, Perplexity, and Google AI Overviews are more likely to cite your pages when users ask relevant questions. Unlike SEO, which targets search rankings, AEO targets AI citation decisions.

Ready to start building?

Get your API key from the dashboard. Starter plan includes 100 audits/day from $29/month.

Get API key View pricing