Guides/AEO API QuickstartPublished March 2026 · Updated March 2026

WebMole API Quickstart: Your First AEO Audit in 60 Seconds

From zero to structured AI citation data in three commands.

Quick answer

The WebMole API lets you run AEO audits via REST. Send a POST to /api/v1/audit with a URL in the JSON body. Get back a JSON report with a 0–100 score, per-factor analysis across 12 AEO signals, and code-level fix suggestions. Auth via Bearer token (keys start with wbm_). Starter plan gives you 100 requests/day at $29/month.

Get your API key

Sign up at webmole.ai/signup
Go to /dashboard/settings
Click Generate API Key
Copy the key — it starts with wbm_

Your key looks like this

wbm_sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5

Keep your key out of source control. Set it as an environment variable or CI secret.

Run your first audit

Three ways to call the API — pick the language you already use.

curl (bash)

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 / TypeScript

typescript

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

if (!res.ok) {
  const err = await res.json()
  throw new Error(err.error.message)
}

const data = await res.json()
console.log(data.score)          // 73
console.log(data.fixSuggestions) // [{factorId, instruction, codeBlock}]

Python

python

import os
import requests

response = requests.post(
    'https://webmole.ai/api/v1/audit',
    headers={
        'Authorization': f'Bearer {os.environ["WBM_API_KEY"]}',
        'Content-Type': 'application/json',
    },
    json={'url': 'https://example.com'},
)
response.raise_for_status()

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

Read the response

The response is a flat JSON object. Here is what each section tells you:

Response structure (annotated)

{
  "url": "https://example.com",
  "score": 73,              // ← overall AEO score, 0-100
  "categories": {           // ← four sub-scores
    "answerReadiness": 80,  //   content clarity and Q&A structure
    "structure": 65,        //   headings, lists, semantic markup
    "authoritySignals": 70, //   author schema, citations, links
    "technicalGEO": 75      //   robots.txt, crawlability, canonicals
  },
  "factors": [              // ← 12 individual checks
    {
      "id": 1,
      "name": "Structured Data (JSON-LD)",
      "score": 15,
      "max": 15,
      "status": "pass",     // "pass" | "fail" | "warn"
      "details": "Valid JSON-LD found with @type Organization"
    }
  ],
  "fixSuggestions": [       // ← only failing/warning factors
    {
      "factorId": 2,
      "factorName": "Meta Description",
      "impact": "High",
      "instruction": "Add a concise meta description.",
      "codeBlock": "<meta name=\"description\" content=\"...\" />"
    }
  ],
  "rateLimit": {
    "remaining": 99,        // ← requests left today
    "limit": 100,
    "resetAt": "2026-03-18T00:00:00.000Z"
  }
}

Apply the fixes in your code

Each fix in fixSuggestions has a codeBlock field. Extract and apply them:

javascript

const { score, fixSuggestions } = await audit('https://example.com')

// Filter to high-impact fixes
const highImpact = fixSuggestions.filter(f => f.impact === 'High')

for (const fix of highImpact) {
  console.log(`Fix: ${fix.factorName}`)
  console.log(`Instruction: ${fix.instruction}`)
  if (fix.codeBlock) {
    console.log(`Code to add:\n${fix.codeBlock}`)
  }
}

Set up monitoring with the CLI

Install the CLI once. Configure your key. Run audits and watch commands without writing curl each time.

shell

# Install
npm install -g @webmole/cli

# Set your API key (saved to ~/.webmole/config)
webmole config set key wbm_your_api_key

# Run a one-off audit
webmole audit https://yoursite.com

# Fail if score is below threshold
webmole audit https://yoursite.com --threshold 70

# Watch a URL — alerts when score drops
webmole watch https://yoursite.com --interval 6h

Ready to automate your AEO audits?

Get your API key and run your first audit in 60 seconds.

Get your API key

Advanced: CI/CD integration

Gate deploys on AEO score. If a content change drops your score below 60, the pipeline fails before it goes live. Add this to your GitHub Actions workflow:

.github/workflows/aeo-check.ymlGitHub Actions

name: AEO Score Check

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  aeo-check:
    runs-on: ubuntu-latest
    steps:
      - name: Run AEO audit
        env:
          WBM_API_KEY: ${{ secrets.WBM_API_KEY }}
          DEPLOY_URL: https://yoursite.com
        run: |
          RESPONSE=$(curl -s -X POST https://webmole.ai/api/v1/audit \
            -H "Authorization: Bearer $WBM_API_KEY" \
            -H "Content-Type: application/json" \
            -d "{\"url\": \"$DEPLOY_URL\"}")

          SCORE=$(echo "$RESPONSE" | jq '.score')
          echo "AEO score: $SCORE"

          if [ "$SCORE" -lt 60 ]; then
            echo "AEO score $SCORE is below threshold (60). Failing."
            exit 1
          fi

Add WBM_API_KEY as a repository secret in Settings → Secrets and variables → Actions. The job returns exit code 1 if score is below threshold, which fails the workflow.

Common questions

How many API requests do I get?

Starter plan: 100 requests/day. Pro: 500/day. Agency: 2,000/day. All limits reset at midnight UTC. Your remaining count is returned in every response under rateLimit.remaining. Free accounts cannot access the API.

Can I audit competitor sites?

Yes. The API accepts any publicly accessible URL. You can audit competitor pages, benchmark your score against theirs, and track changes over time. Private URLs, localhost, and IP addresses are rejected.

Does it work with any URL?

Any publicly reachable HTTPS URL works. The page must be accessible to our crawler — pages behind a login, Cloudflare CAPTCHA, or geo-block may return an error. The URL must be fully qualified (https://…) and under 2048 characters.

How often should I run audits?

For CI/CD pipelines, run on every deploy. For monitoring, weekly is enough for most sites. If you publish new content frequently, run daily. Use the CLI with --interval 6h to automate monitoring without writing cron jobs.

Run your first audit now

API key ready in 60 seconds. 100 audits/day on Starter ($29/mo). No integration required.

Get your API key API reference