### Set Up Webmole CLI Monitoring

Source: https://github.com/webmoleai/webmole-docs/blob/main/docs/quickstart.md

This section details how to set up continuous monitoring of a website's AI readiness using the Webmole CLI. It includes installation, API key configuration, and initiating a watch command with a specified interval.

```bash
npm install -g @webmole/cli
webmole config set key wbm_your_api_key
webmole watch https://your-site.com --interval 6h
```

--------------------------------

### Apply Fixes with Code Block

Source: https://github.com/webmoleai/webmole-docs/blob/main/docs/quickstart.md

This example shows the structure of a fix suggestion returned by the API. It includes an 'instruction' detailing the necessary action and a 'codeBlock' containing the actual code snippet to be implemented, such as adding schema markup.

```json
{
  "instruction": "Add FAQ schema to your page",
  "codeBlock": "<script type=\"application/ld+json\">
{\"@context\":\"https://schema.org\",\"@type\":\"FAQPage\",...}
</script>"
```

--------------------------------

### Start WebMole MCP Server (Bash)

Source: https://github.com/webmoleai/webmole-docs/blob/main/llms-full.txt

This command uses npx to execute the webmole-mcp package, starting a server that wraps the WebMole API for use in MCP clients. It exposes various tools for auditing and comparison.

```bash
npx -y webmole-mcp
```

--------------------------------

### Bash: WebMole CLI Installation and Usage

Source: https://context7.com/webmoleai/webmole-docs/llms.txt

Commands for installing and using the WebMole CLI. Includes instructions for global installation, API key configuration, running basic audits, setting CI/CD thresholds, and continuous monitoring with watch mode.

```bash
# Install the CLI globally
npm install -g @webmole/cli

# Configure your API key
webmole config set key wbm_your_api_key

# Run a basic audit
webmole audit https://your-site.com

# CI/CD gate — exit code 1 if score below threshold
webmole audit https://your-site.com --threshold 70

# Continuous monitoring with 6-hour intervals
webmole watch https://your-site.com --interval 6h

# Watch mode with JSON output for parsing
webmole watch https://your-site.com --interval 6h --json
```

--------------------------------

### POST /api/v1/audit

Source: https://github.com/webmoleai/webmole-docs/blob/main/docs/quickstart.md

Triggers an AI citation readiness audit for a specified URL and returns a score along with actionable optimization suggestions.

```APIDOC
## POST /api/v1/audit

### Description
Initiates an automated audit of a website to determine its AI citation readiness. The response includes an overall score, detailed factor checks, and specific code-based fix suggestions.

### Method
POST

### Endpoint
https://webmole.ai/api/v1/audit

### Parameters
#### Request Body
- **url** (string) - Required - The fully qualified URL of the website to audit.

### Request Example
{
  "url": "https://your-site.com"
}

### Response
#### Success Response (200)
- **score** (integer) - Overall AI citation readiness score (0-100).
- **factors** (array) - List of 12 individual checks with pass/fail status.
- **fixSuggestions** (array) - List of prioritized fixes containing instructions and code blocks.

#### Response Example
{
  "score": 75,
  "factors": [{"name": "schema_markup", "status": "pass"}],
  "fixSuggestions": [
    {
      "instruction": "Add FAQ schema to your page",
      "codeBlock": "<script type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"FAQPage\"}</script>"
    }
  ]
}
```

--------------------------------

### CI/CD Gate with Webmole CLI

Source: https://github.com/webmoleai/webmole-docs/blob/main/docs/quickstart.md

This snippet illustrates how to integrate Webmole AI audits into a CI/CD pipeline as a gate. It shows a command that performs an audit and exits with a non-zero status code if the website's score falls below a defined threshold, preventing deployment of non-compliant code.

```bash
webmole audit https://your-site.com --threshold 70
# Exits with code 1 if score drops below 70
```

--------------------------------

### Create llms.txt for AI Discoverability

Source: https://github.com/webmoleai/webmole-docs/blob/main/guides/aeo-for-nextjs.md

This markdown snippet shows the content for a `public/llms.txt` file. This file helps AI models discover information about your product, including a one-line description, links to documentation, and guides. Customize the product name, description, and URLs to match your project.

```markdown
# Your Product Name

> One-line description of what you do.

## Docs
- [API Reference](https://yoursite.com/docs)

## Guides
- [Getting Started](https://yoursite.com/docs/quickstart)
```

--------------------------------

### Bash: WebMole API Error Handling Examples

Source: https://context7.com/webmoleai/webmole-docs/llms.txt

Examples of structured error responses from the WebMole API, illustrating common error codes such as unauthorized access, invalid requests, rate limiting, and internal server errors. Also shows rate limit headers.

```bash
# Error response format
# HTTP 401 - Missing or invalid API key
# { "error": { "code": "unauthorized", "message": "Invalid or missing API key." } }

# HTTP 400 - Invalid URL
# { "error": { "code": "invalid_url", "message": "\"url\" must be a valid URL (e.g., https://example.com)." } }

# HTTP 429 - Rate limited
# { "error": { "code": "rate_limited", "message": "Daily limit of 100 requests reached. Resets at 2026-03-18T00:00:00.000Z." } }

# HTTP 500 - Internal error
# { "error": { "code": "score_failed", "message": "Failed to analyze the page. Please try again." } }

# Rate limit headers on all responses:
# X-RateLimit-Limit: 100
# X-RateLimit-Remaining: 99
# X-RateLimit-Reset: 2026-03-18T00:00:00.000Z
```

--------------------------------

### Implement Meta Tag Fix

Source: https://github.com/webmoleai/webmole-docs/blob/main/docs/api-reference.md

Example HTML meta tag implementation suggested by the API to resolve missing meta description issues.

```HTML
<meta name="description" content="Your page summary here." />
```

--------------------------------

### Integrate WebMole API with Python

Source: https://context7.com/webmoleai/webmole-docs/llms.txt

This Python example uses the `requests` library to interact with the WebMole API. It demonstrates how to authenticate using an environment variable for the API key, retrieve audit results, print the score, and display prioritized fix suggestions. It also shows how to access the `codeBlock` for suggested fixes.

```python
import os
import requests

API_KEY = os.environ.get("WEBMOLE_API_KEY", "wbm_your_api_key")

def audit_url(url: str) -> dict:
    """Run an AEO audit on a URL. Returns score, factors, and fix suggestions."""
    response = requests.post(
        "https://webmole.ai/api/v1/audit",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={"url": url},
    )
    response.raise_for_status()
    return response.json()

# Basic usage
result = audit_url("https://example.com")
print(f"Score: {result['score']}/100")

# Print fix suggestions
for fix in result["fixSuggestions"]:
    print(f"[{fix['impact']}] {fix['instruction']}")
    if fix.get("codeBlock"):
        print(f"  Code: {fix['codeBlock'][:80]}...")

```

--------------------------------

### TypeScript/React: Next.js JSON-LD Schema Integration

Source: https://context7.com/webmoleai/webmole-docs/llms.txt

Example code for integrating Organization and FAQPage JSON-LD schema markup into a Next.js application. This structured data enhances AI citation readiness by providing machine-readable information.

```tsx
// src/app/layout.tsx — Add Organization schema
const orgSchema = {
  '@context': 'https://schema.org',
  '@type': 'Organization',
  name: 'Your Company',
  url: 'https://yoursite.com',
  logo: 'https://yoursite.com/logo.png',
}

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <script
          type="application/ld+json"
          dangerouslySetInnerHTML={{ __html: JSON.stringify(orgSchema) }}
        />
      </head>
      <body>{children}</body>
    </html>
  )
}

// Content pages — Add FAQ schema for AI answer extraction
const faqSchema = {
  '@context': 'https://schema.org',
  '@type': 'FAQPage',
  mainEntity: [
    {
      '@type': 'Question',
      name: 'What does your product do?',
      acceptedAnswer: {
        '@type': 'Answer',
        text: 'A direct, 25-word answer that AI engines can quote.',
      },
    },
  ],
}
```

--------------------------------

### Integrate WebMole API with JavaScript/TypeScript

Source: https://context7.com/webmoleai/webmole-docs/llms.txt

This TypeScript example shows how to integrate the WebMole API into Node.js or browser applications. It includes type definitions for the API response, handles potential errors, and demonstrates how to check bot accessibility. The `auditUrl` function makes a POST request to the API and returns the audit results.

```typescript
interface AuditResult {
  url: string
  score: number
  categories: {
    answerReadiness: number
    structure: number
    authoritySignals: number
    technicalGEO: number
  }
  factors: Array<{ 
    id: number
    name: string
    score: number
    max: number
    status: 'pass' | 'warn' | 'fail'
    details: string
  }>
  fixSuggestions: Array<{
    factorId: number
    factorName: string
    impact: 'High' | 'Medium' | 'Low'
    instruction: string
    codeBlock?: string
  }>
  botAccessibility: Record<string, {
    status: number
    accessible: boolean
    cdnBlocked: boolean
    cdn?: string
  }>
  scannedAt: string
  rateLimit: { remaining: number; limit: number; resetAt: string }
}

async function auditUrl(url: string, apiKey: string): Promise<AuditResult> {
  const res = await fetch('https://webmole.ai/api/v1/audit', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ url }),
  })

  if (!res.ok) {
    const error = await res.json()
    throw new Error(`WebMole API error: ${error.error?.message || res.statusText}`)
  }

  return res.json()
}

// Usage
const result = await auditUrl('https://example.com', 'wbm_your_api_key')
console.log(`Score: ${result.score}/100`)
console.log(`Top fix: ${result.fixSuggestions[0]?.instruction}`)

// Check if bots can access the page
for (const [bot, status] of Object.entries(result.botAccessibility)) {
  if (status.cdnBlocked) {
    console.warn(`${bot} is blocked by ${status.cdn} CDN — robots.txt alone won't fix this`)
  }
}
```

--------------------------------

### Run AEO Audit with Webmole CLI

Source: https://github.com/webmoleai/webmole-docs/blob/main/guides/ci-cd-integration.md

Installs and runs the Webmole CLI to audit a given URL. The command exits with a non-zero status code if the AEO score drops below the specified threshold, making it suitable for CI/CD environments. Dependencies: Node.js, npm.

```bash
npm install -g @webmole/cli
webmole audit https://your-site.com --threshold 70
```

--------------------------------

### WebMole Agent Tool Definition

Source: https://github.com/webmoleai/webmole-docs/blob/main/llms-full.txt

This JSON object defines the 'webmole_audit' tool for AI agents. It includes a name, description, and input schema to guide the agent on how to use the WebMole audit functionality.

```APIDOC
## Agent Tool Definition: webmole_audit

### Description
This definition describes the 'webmole_audit' tool, which can be used by AI agents to perform an AEO audit on a URL. It provides a score, factor analysis, and prioritized fix suggestions.

### Tool Definition
```json
{
  "name": "webmole_audit",
  "description": "Run an AEO (Answer Engine Optimization) audit on a URL. Returns a score from 0-100 measuring how likely AI systems (ChatGPT, Perplexity, Gemini) are to cite this page, plus per-factor analysis and prioritized fix suggestions with copy-paste code snippets. Use this when a user asks to optimize a page for AI search, improve AEO/GEO scores, check AI citation readiness, or fix schema markup.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "url": {
        "type": "string",
        "description": "Fully qualified URL to audit (must include https://)"
      }
    },
    "required": ["url"]
  }
}
```
```

--------------------------------

### CLI Tool Commands

Source: https://github.com/webmoleai/webmole-docs/blob/main/llms-full.txt

Common CLI commands for auditing, monitoring, and configuring the WebMole tool.

```bash
npm install -g @webmole/cli
webmole config set key wbm_your_api_key
webmole audit https://example.com --json
webmole audit https://example.com --threshold 70
webmole watch https://example.com --interval 6h
```

--------------------------------

### Audit Website for AI Optimization using CLI

Source: https://github.com/webmoleai/webmole-docs/blob/main/guides/aeo-for-nextjs.md

This bash command uses the `@webmole/cli` package to audit a website for AI search optimization. It takes the website URL as an argument and provides a score based on various optimization factors. This is a quick way to check your site's readiness for AI search engines.

```bash
npx @webmole/cli audit https://yoursite.com
```

--------------------------------

### WebMole MCP Server Tools

Source: https://github.com/webmoleai/webmole-docs/blob/main/llms-full.txt

This section lists the tools exposed by the WebMole MCP server, which wraps the WebMole API for use in various MCP clients. These tools offer different levels of detail for audits.

```APIDOC
## WebMole MCP Server Tools

### Description
The WebMole MCP server provides several tools for interacting with the WebMole API through MCP clients. These tools offer varying functionalities from full audits to specific data points.

### Tools
- **webmole_audit**: Performs a full audit, including score, factors, and fix suggestions.
- **webmole_fixes**: Returns only the fix suggestions, suitable for lightweight use.
- **webmole_score**: Provides only the score and categories, without factors or fixes.
- **webmole_compare**: Compares multiple URLs side-by-side (available on paid plans).
```

--------------------------------

### Audit URL via CLI

Source: https://github.com/webmoleai/webmole-docs/blob/main/AGENTS.md

Use the WebMole CLI to perform audits directly from the terminal. Supports standard audits, JSON output, threshold filtering, and automated monitoring intervals.

```bash
npm install -g @webmole/cli
webmole audit https://example.com
webmole audit https://example.com --json --threshold 70
webmole watch https://example.com --interval 6h
```

--------------------------------

### Perform API Audit using JavaScript Fetch

Source: https://github.com/webmoleai/webmole-docs/blob/main/llms-full.txt

This JavaScript code snippet shows how to use the `fetch` API to interact with the WebMole API. It handles sending the request, checking for errors, and processing the JSON response, including accessing the overall score and fix suggestions.

```javascript
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)          // 74
console.log(data.fixSuggestions) // [{factorId, instruction, codeBlock}]
```

--------------------------------

### Add FAQ JSON-LD Schema to Next.js Content Pages

Source: https://github.com/webmoleai/webmole-docs/blob/main/guides/aeo-for-nextjs.md

This code snippet shows how to implement an 'FAQPage' schema using JSON-LD in Next.js. It's designed to be added to content pages to highlight frequently asked questions and their direct answers, which AI engines can potentially use for answer capsules. Customize the `name` and `text` within `mainEntity` for each question and answer pair.

```tsx
const faqSchema = {
  '@context': 'https://schema.org',
  '@type': 'FAQPage',
  mainEntity: [
    {
      '@type': 'Question',
      name: 'What does your product do?',
      acceptedAnswer: {
        '@type': 'Answer',
        text: 'A direct, 25-word answer that AI engines can quote.',
      },
    },
  ],
}
```

--------------------------------

### Python: Check Bot Accessibility and CI/CD Gate

Source: https://context7.com/webmoleai/webmole-docs/llms.txt

Python code snippets to check bot accessibility by iterating through results and to implement a CI/CD gate that fails the build if the AEO score is below a threshold.

```python
for bot, status in result.get("botAccessibility", {}).items():
    if status.get("cdnBlocked"):
        print(f"WARNING: {bot} blocked by {status.get('cdn', 'CDN')} — fix in CDN settings")

# CI/CD gate
if result["score"] < 70:
    print(f"FAIL: AEO score {result['score']} is below threshold 70")
    exit(1)
print(f"PASS: AEO score {result['score']}")
```

--------------------------------

### Run AEO Audit with cURL

Source: https://context7.com/webmoleai/webmole-docs/llms.txt

This snippet demonstrates how to use cURL to call the WebMole API's core audit endpoint. It sends a POST request with the URL to be analyzed and includes the API key for authentication. The response contains the AI citation readiness score, detailed factor analysis, category breakdowns, bot accessibility status, and suggested fixes with code.

```bash
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"}'

# Response:
# {
#   "url": "https://example.com",
#   "score": 74,
#   "categories": {
#     "answerReadiness": 80,
#     "structure": 70,
#     "authoritySignals": 65,
#     "technicalGEO": 80
#   },
#   "factors": [
#     { "id": 7, "name": "Schema Markup (JSON-LD)", "score": 10, "max": 10, "status": "pass" },
#     { "id": 8, "name": "Meta Tags", "score": 0, "max": 8, "status": "fail" }
#   ],
#   "fixSuggestions": [
#     {
#       "factorId": 8,
#       "factorName": "Meta Tags",
#       "impact": "High",
#       "instruction": "Add a concise meta description (120-160 chars).",
#       "codeBlock": "<meta name=\"description\" content=\"Your page summary here.\" />"
#     }
#   ],
#   "botAccessibility": {
#     "GPTBot": { "status": 200, "accessible": true, "cdnBlocked": false },
#     "ClaudeBot": { "status": 403, "accessible": false, "cdnBlocked": true, "cdn": "cloudflare" }
#   },
#   "scannedAt": "2026-03-17T12:00:00.000Z",
#   "rateLimit": { "remaining": 99, "limit": 100, "resetAt": "2026-03-18T00:00:00.000Z" }
# }
```

--------------------------------

### GitHub Actions: CI/CD Gate for AEO Audits

Source: https://context7.com/webmoleai/webmole-docs/llms.txt

A GitHub Actions workflow that automates AEO audits on pull requests. It fails the build if the AEO score drops below 70, preventing regressions from reaching production. It uses `curl` to post to the WebMole API and `jq` to parse the JSON response.

```yaml
name: AEO Audit
on:
  pull_request:
    branches: [main]

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

          SCORE=$(echo $RESULT | jq '.score')
          echo "AEO Score: $SCORE/100"

          if [ "$SCORE" -lt 70 ]; then
            echo "::error::AEO score $SCORE is below threshold 70"
            echo "$RESULT" | jq '.fixSuggestions[] | "\(.impact): \(.instruction)"'
            exit 1
          fi
          echo "AEO check passed with score $SCORE"
```

--------------------------------

### Process and Filter Fix Suggestions

Source: https://github.com/webmoleai/webmole-docs/blob/main/llms-full.txt

Extract high-impact fix suggestions from the audit response to provide actionable optimization steps.

```javascript
const { score, fixSuggestions } = await auditUrl('https://example.com', apiKey)

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}`)
  }
}
```

--------------------------------

### WebMole Agent Tool Definition (JSON)

Source: https://github.com/webmoleai/webmole-docs/blob/main/llms-full.txt

This JSON object defines a tool for AI agents to interact with the WebMole API for AEO audits. It includes a name, description, and input schema specifying the required URL parameter.

```json
{
  "name": "webmole_audit",
  "description": "Run an AEO (Answer Engine Optimization) audit on a URL. Returns a score from 0-100 measuring how likely AI systems (ChatGPT, Perplexity, Gemini) are to cite this page, plus per-factor analysis and prioritized fix suggestions with copy-paste code snippets. Use this when a user asks to optimize a page for AI search, improve AEO/GEO scores, check AI citation readiness, or fix schema markup.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "url": {
        "type": "string",
        "description": "Fully qualified URL to audit (must include https://)"
      }
    },
    "required": ["url"]
  }
}
```

--------------------------------

### TypeScript: Next.js Robots.txt Configuration

Source: https://context7.com/webmoleai/webmole-docs/llms.txt

Configuration for a Next.js `robots.ts` file to manage crawler access. It explicitly allows specific AI bots like GPTBot and ClaudeBot while disallowing access to private routes.

```typescript
// src/app/robots.ts
import type { MetadataRoute } from 'next'

export default function robots(): MetadataRoute.Robots {
  return {
    rules: [
      { userAgent: '*', allow: '/', disallow: ['/dashboard', '/api/', '/auth/'] },
      { userAgent: 'GPTBot', allow: '/' },
      { userAgent: 'ClaudeBot', allow: '/' },
      { userAgent: 'PerplexityBot', allow: '/' },
      { userAgent: 'OAI-SearchBot', allow: '/' },
    ],
    sitemap: 'https://yoursite.com/sitemap.xml',
  }
}
```

--------------------------------

### Batch Audit URLs with ThreadPoolExecutor

Source: https://github.com/webmoleai/webmole-docs/blob/main/llms-full.txt

Process multiple URLs concurrently using Python's ThreadPoolExecutor to improve performance when auditing large lists of domains.

```python
import os
import requests
from concurrent.futures import ThreadPoolExecutor

API_KEY = os.environ['WBM_API_KEY']

def audit(url):
    r = requests.post(
        'https://webmole.ai/api/v1/audit',
        headers={'Authorization': f'Bearer {API_KEY}'},
        json={'url': url},
        timeout=30,
    )
    r.raise_for_status()
    return r.json()

urls = ['https://example.com', 'https://competitor.com', 'https://another.com']

with ThreadPoolExecutor(max_workers=5) as pool:
    results = list(pool.map(audit, urls))
```

--------------------------------

### Configure robots.txt for AI Bots in Next.js

Source: https://github.com/webmoleai/webmole-docs/blob/main/guides/aeo-for-nextjs.md

This TypeScript code defines the `robots.txt` rules for a Next.js application, specifying which user agents can access which parts of the site. It explicitly allows common AI bots like GPTBot, ClaudeBot, PerplexityBot, and OAI-SearchBot while disallowing access to sensitive paths like `/dashboard` and `/api/`. Ensure the `sitemap` URL is correct.

```ts
import type { MetadataRoute } from 'next'

export default function robots(): MetadataRoute.Robots {
  return {
    rules: [
      { userAgent: '*', allow: '/', disallow: ['/dashboard', '/api/', '/auth/'] },
      { userAgent: 'GPTBot', allow: '/' },
      { userAgent: 'ClaudeBot', allow: '/' },
      { userAgent: 'PerplexityBot', allow: '/' },
      { userAgent: 'OAI-SearchBot', allow: '/' },
    ],
    sitemap: 'https://yoursite.com/sitemap.xml',
  }
}
```

--------------------------------

### Integrate Audit in CI/CD

Source: https://github.com/webmoleai/webmole-docs/blob/main/AGENTS.md

Automate AEO audits within GitHub Actions workflows. This action allows you to set a quality threshold and requires an API key stored in repository secrets.

```yaml
- uses: webmole/aeo-audit-action@v1
  with:
    url: https://yoursite.com
    threshold: 70
    api-key: ${{ secrets.WEBMOLE_API_KEY }}
```

--------------------------------

### Authentication

Source: https://github.com/webmoleai/webmole-docs/blob/main/llms-full.txt

All API requests require a Bearer token in the Authorization header. API keys are generated from the user's dashboard and are unique to their account. Free tier accounts do not have access to API keys.

```APIDOC
## Authentication

All API requests require a Bearer token in the `Authorization` header.

```
Authorization: Bearer wbm_your_api_key_here
```

**Getting an API key:**
1. Sign up at webmole.ai/signup
2. Go to Dashboard → Settings → API Keys
3. Click "Generate API Key"
4. Your key starts with `wbm_`

**Key rules:**
- API keys start with `wbm_` (e.g., `wbm_sk_live_a1b2c3d4e5f6g7h8i9j0`)
- Keys are scoped to your account — do not share or commit to source control
- Rotate a compromised key instantly from Dashboard → Settings
- Free tier accounts cannot generate API keys — upgrade to Starter or above
```

--------------------------------

### POST /api/v1/audit

Source: https://context7.com/webmoleai/webmole-docs/llms.txt

Analyzes a public URL to determine its AI citation readiness, providing a detailed breakdown of scores, bot accessibility, and actionable fix suggestions.

```APIDOC
## POST /api/v1/audit

### Description
Audits a specific URL to calculate its AI citation readiness score. Returns category scores, factor analysis, bot accessibility status, and prioritized fix suggestions.

### Method
POST

### Endpoint
https://webmole.ai/api/v1/audit

### Parameters
#### Request Body
- **url** (string) - Required - The public URL to be audited.

### Request Example
{
  "url": "https://example.com"
}

### Response
#### Success Response (200)
- **url** (string) - The audited URL.
- **score** (number) - Overall AI readiness score (0-100).
- **categories** (object) - Breakdown of scores for answerReadiness, structure, authoritySignals, and technicalGEO.
- **factors** (array) - Detailed list of 12 factors including status and scores.
- **fixSuggestions** (array) - List of actionable improvements with impact levels and code snippets.
- **botAccessibility** (object) - Status of various AI bots (GPTBot, ClaudeBot, etc.) and CDN blocking status.
- **rateLimit** (object) - Current usage statistics.

#### Response Example
{
  "url": "https://example.com",
  "score": 74,
  "categories": {
    "answerReadiness": 80,
    "structure": 70,
    "authoritySignals": 65,
    "technicalGEO": 80
  },
  "factors": [
    { "id": 7, "name": "Schema Markup (JSON-LD)", "score": 10, "max": 10, "status": "pass" }
  ],
  "fixSuggestions": [
    {
      "factorId": 8,
      "factorName": "Meta Tags",
      "impact": "High",
      "instruction": "Add a concise meta description.",
      "codeBlock": "<meta name=\"description\" content=\"Your page summary here.\" />"
    }
  ],
  "botAccessibility": {
    "GPTBot": { "status": 200, "accessible": true, "cdnBlocked": false }
  }
}
```

--------------------------------

### API Rate Limit Headers

Source: https://github.com/webmoleai/webmole-docs/blob/main/llms-full.txt

These headers are included in every response from the WebMole API to indicate the current status of your rate limit. The 'X-RateLimit-Reset' header specifies when the limit will be refreshed.

```http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 2026-03-18T00:00:00.000Z
```

--------------------------------

### GitHub Actions CI/CD Integration

Source: https://github.com/webmoleai/webmole-docs/blob/main/llms-full.txt

Automate AEO score checks in CI/CD pipelines to prevent deployments that fall below a specific quality threshold.

```yaml
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')
          if [ "$SCORE" -lt 60 ]; then
            exit 1
          fi
```

--------------------------------

### API Rate Limits

Source: https://github.com/webmoleai/webmole-docs/blob/main/llms-full.txt

API rate limits vary by subscription plan. Exceeding the limit results in an HTTP 429 response with `Retry-After` and `X-RateLimit-Reset` headers. Remaining requests can be monitored via the `rateLimit.remaining` field in responses.

```APIDOC
## API Rate Limits

API rate limits are determined by your subscription plan. Exceeding these limits will result in a `429 Too Many Requests` HTTP status code.

### Rate Limit Handling
When the rate limit is exceeded, the API will return:
- HTTP `429` status code.
- `Retry-After` header: Indicates the number of seconds until the limit resets.
- `X-RateLimit-Reset` header: Provides the exact timestamp when the limit will reset.

It is recommended to proactively monitor your usage using the `rateLimit.remaining` field present in every API response.

### Rate Limits by Plan

| Plan    | Requests/day |
|---------|--------------|
| Free    | No API access|
| Starter | 100 / day    |
| Pro     | 500 / day    |
| Agency  | 2,000 / day  |

*Note: Limits reset at midnight UTC.*
```

--------------------------------

### Authenticate WebMole API Requests

Source: https://github.com/webmoleai/webmole-docs/blob/main/llms-full.txt

All API requests must include an Authorization header with a Bearer token. This token is generated via the user dashboard and must be kept secure.

```HTTP
Authorization: Bearer wbm_your_api_key_here
```

--------------------------------

### POST /api/v1/audit

Source: https://github.com/webmoleai/webmole-docs/blob/main/llms-full.txt

This endpoint allows you to run an AEO audit on any public URL programmatically. It returns a comprehensive analysis including a 0-100 score, 12-factor breakdown, category scores, and actionable fix suggestions.

```APIDOC
## POST /api/v1/audit

Run an AEO audit on any public URL. Returns a 0–100 score, 12-factor analysis, category breakdown, and prioritized fix suggestions.

**Use this endpoint when:** a user or agent wants to check a URL's AI citation readiness, get AEO/GEO score data, retrieve fix suggestions for a page, or audit a competitor URL.

### Method
POST

### Endpoint
`https://webmole.ai/api/v1/audit`

### Parameters
#### Request Body
- **url** (string) - Required - Fully qualified URL to audit (https://…). Max 2048 chars. Private/internal IPs rejected.

### Request Example
```json
{
  "url": "https://example.com/your-page"
}
```

### Response
#### Success Response (200)
- **score** (integer) - The overall AEO score from 0 to 100.
- **analysis** (object) - Detailed breakdown of the 12 factors.
- **categories** (object) - Score breakdown by category.
- **suggestions** (array) - Prioritized list of fix suggestions with code examples.

#### Response Example
```json
{
  "score": 85,
  "analysis": {
    "factor1": {"score": 10, "description": "..."},
    "factor2": {"score": 8, "description": "..."}
  },
  "categories": {
    "citations": {"score": 90},
    "content": {"score": 80}
  },
  "suggestions": [
    {
      "title": "Improve title tag",
      "description": "Ensure your title tag is descriptive and includes relevant keywords.",
      "code": "<title>Your Optimized Title Here</title>"
    }
  ]
}
```
```

--------------------------------

### POST /api/v1/audit

Source: https://github.com/webmoleai/webmole-docs/blob/main/README.md

Audits a given URL for AI citation readiness and provides a score along with detailed category breakdowns and fix suggestions.

```APIDOC
## POST /api/v1/audit

### Description
Audits a given URL for AI citation readiness and provides a score along with detailed category breakdowns and fix suggestions.

### Method
POST

### Endpoint
/api/v1/audit

### Parameters
#### Query Parameters
None

#### Request Body
- **url** (string) - Required - The URL to be audited.

### Request Example
```json
{
  "url": "https://example.com"
}
```

### Response
#### Success Response (200)
- **score** (integer) - The overall AI citation readiness score.
- **categories** (object) - An object containing scores for different AI readiness categories.
  - **answerReadiness** (integer) - Score for answer readiness.
  - **structure** (integer) - Score for structural optimization.
  - **authoritySignals** (integer) - Score for authority signals.
  - **technicalGEO** (integer) - Score for technical GEO aspects.
- **factors** (array) - A list of optimization factors with their scores and status.
  - **id** (integer) - The ID of the factor.
  - **name** (string) - The name of the factor.
  - **score** (integer) - The score achieved for this factor.
  - **max** (integer) - The maximum possible score for this factor.
  - **status** (string) - The status of the factor (e.g., 'pass', 'fail').
- **fixSuggestions** (array) - A list of suggested fixes for optimization.
  - **factorId** (integer) - The ID of the factor this suggestion relates to.
  - **factorName** (string) - The name of the factor.
  - **impact** (string) - The impact level of the suggestion (e.g., 'High').
  - **instruction** (string) - The instruction on how to implement the fix.
  - **codeBlock** (string) - A code snippet demonstrating the fix.

#### Response Example
```json
{
  "score": 74,
  "categories": {
    "answerReadiness": 80,
    "structure": 70,
    "authoritySignals": 65,
    "technicalGEO": 80
  },
  "factors": [
    { "id": 7, "name": "Schema Markup (JSON-LD)", "score": 10, "max": 10, "status": "pass" },
    { "id": 8, "name": "Meta Tags", "score": 0, "max": 8, "status": "fail" }
  ],
  "fixSuggestions": [
    {
      "factorId": 8,
      "factorName": "Meta Tags",
      "impact": "High",
      "instruction": "Add a concise meta description (120-160 chars).",
      "codeBlock": "<meta name=\"description\" content=\"Your page summary here.\" />"
    }
  ]
}
```
```

--------------------------------

### AEO Factors Data Structure (JSON)

Source: https://context7.com/webmoleai/webmole-docs/llms.txt

This JSON object outlines the 12 AEO (AI Engine Optimization) factors used by WebMole. It includes the ID, name, maximum score, and a brief description for each factor, detailing criteria like header hierarchy, answer capsules, and schema markup.

```json
{
  "factors": [
    { "id": 1, "name": "Header Hierarchy", "max": 10, "description": "H1→H2→H3 nesting, no skipped levels" },
    { "id": 2, "name": "Answer Capsules", "max": 10, "description": "40-60 word direct answers after H2 headings" },
    { "id": 3, "name": "Section Lengths", "max": 8, "description": "Paragraphs sized for AI extraction (100-180 words)" },
    { "id": 4, "name": "FAQ Sections", "max": 8, "description": "FAQPage schema or Q&A structured headings" },
    { "id": 5, "name": "Statistics Density", "max": 8, "description": "Data points, percentages, specific numbers" },
    { "id": 6, "name": "Source Citations", "max": 8, "description": "Outbound links to authoritative sources" },
    { "id": 7, "name": "Schema Markup (JSON-LD)", "max": 10, "description": "Structured data for AI comprehension" },
    { "id": 8, "name": "Meta Tags", "max": 8, "description": "Title, description, Open Graph, canonical" },
    { "id": 9, "name": "Content Front-Loading", "max": 8, "description": "Key information in first 30% of page" },
    { "id": 10, "name": "AI Bot Access", "max": 8, "description": "robots.txt allows GPTBot, ClaudeBot, PerplexityBot" },
    { "id": 11, "name": "Readability", "max": 7, "description": "Sentence length averaging 15-20 words" },
    { "id": 12, "name": "Lists and Tables", "max": 5, "description": "Structured content elements AI can parse" }
  ]
}
```

--------------------------------

### Audit and Alert Endpoint

Source: https://github.com/webmoleai/webmole-docs/blob/main/llms-full.txt

This endpoint allows you to perform an audit on a given URL and trigger an alert if the score drops below a specified threshold. It's designed for programmatic use, such as in Python scripts.

```APIDOC
## POST /api/v1/audit

### Description
Performs an Answer Engine Optimization (AEO) audit on a provided URL. It returns a score indicating the likelihood of AI systems citing the page, along with factor analysis and prioritized fix suggestions.

### Method
POST

### Endpoint
/api/v1/audit

### Parameters
#### Query Parameters
- **url** (string) - Required - The fully qualified URL to audit (must include https://).
- **threshold** (integer) - Optional - The score threshold below which an alert should be triggered. Defaults to 65.

#### Request Body
```json
{
  "url": "string"
}
```

### Request Example
```json
{
  "url": "https://example.com"
}
```

### Response
#### Success Response (200)
- **score** (integer) - The AEO score for the URL (0-100).
- **factors** (object) - Analysis of different factors contributing to the score.
- **suggestions** (array) - Prioritized list of suggested fixes with code snippets.

#### Response Example
```json
{
  "score": 75,
  "factors": {
    "schema_markup": {
      "score": 80,
      "analysis": "Schema markup is well-implemented."
    }
  },
  "suggestions": [
    {
      "description": "Improve meta description length.",
      "code": "<meta name=\"description\" content=\"Your updated meta description here...\">
"
    }
  ]
}
```
```

--------------------------------

### Common API Error Responses

Source: https://github.com/webmoleai/webmole-docs/blob/main/llms-full.txt

This table outlines common HTTP status codes, their corresponding error codes, and a brief explanation for API errors. These errors cover issues like authentication, invalid requests, and server-side problems.

```table
| HTTP Status | Code |
|-------------|------|
| 401 | `unauthorized` |
| 400 | `invalid_body` |
| 400 | `invalid_url` |
| 400 | `fetch_failed` |
| 400 | `fetch_timeout` |
| 429 | `rate_limited` |
| 500 | `score_failed` |
```

--------------------------------

### Perform AEO Audit via WebMole API

Source: https://github.com/webmoleai/webmole-docs/blob/main/guides/what-is-aeo.md

This snippet demonstrates how to perform an Answer Engine Optimization (AEO) audit using the WebMole API. It requires an API key for authorization and sends a JSON payload containing the URL to be audited. The API returns an audit score based on 12 factors relevant to AI citation.

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

--------------------------------

### POST /api/v1/audit

Source: https://github.com/webmoleai/webmole-docs/blob/main/docs/api-reference.md

Performs an automated audit on a provided URL to evaluate its AI search readiness and accessibility.

```APIDOC
## POST https://webmole.ai/api/v1/audit

### Description
Submits a URL for analysis against 12 AEO (AI Engine Optimization) factors. Requires a valid Bearer token for authentication.

### Method
POST

### Endpoint
https://webmole.ai/api/v1/audit

### Parameters
#### Request Body
- **url** (string) - Required - Fully qualified URL to audit (https://...). Max 2048 chars. Private/internal IPs are rejected.

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

### Response
#### Success Response (200)
- **url** (string) - The audited URL.
- **score** (integer) - Overall audit score.
- **categories** (object) - Breakdown of scores by category.
- **factors** (array) - Detailed list of the 12 AEO factors evaluated.
- **fixSuggestions** (array) - Actionable advice to improve scores.
- **botAccessibility** (object) - Status of access for various AI bots.
- **scannedAt** (string) - ISO timestamp of the audit.
- **rateLimit** (object) - Current usage statistics.

#### Response Example
{
  "url": "https://example.com",
  "score": 74,
  "categories": {
    "answerReadiness": 80,
    "structure": 70,
    "authoritySignals": 65,
    "technicalGEO": 80
  },
  "factors": [
    {
      "id": 7,
      "name": "Schema Markup (JSON-LD)",
      "score": 10,
      "max": 10,
      "status": "pass",
      "details": "Valid JSON-LD found with @type Organization"
    }
  ],
  "scannedAt": "2026-03-17T12:00:00.000Z"
}
```

--------------------------------

### Add Organization JSON-LD Schema to Next.js Layout

Source: https://github.com/webmoleai/webmole-docs/blob/main/guides/aeo-for-nextjs.md

This snippet demonstrates how to add an 'Organization' schema to the `layout.tsx` file in a Next.js application. It uses JSON-LD to provide structured data about the organization, which can help search engines understand your site better. Ensure the `name`, `url`, and `logo` properties are updated with your specific details.

```tsx
// src/app/layout.tsx
const orgSchema = {
  '@context': 'https://schema.org',
  '@type': 'Organization',
  name: 'Your Company',
  url: 'https://yoursite.com',
  logo: 'https://yoursite.com/logo.png',
}

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <script
          type="application/ld+json"
          dangerouslySetInnerHTML={{ __html: JSON.stringify(orgSchema) }}
        />
      </head>
      <body>{children}</body>
    </html>
  )
}
```

--------------------------------

### GitHub Actions: Audit AEO Score via API

Source: https://github.com/webmoleai/webmole-docs/blob/main/guides/ci-cd-integration.md

A GitHub Actions workflow that performs an AEO audit using the Webmole API. It sends a POST request with the site URL and an API key, then uses `jq` to extract the score and exits with an error if the score is below 70. Dependencies: `curl`, `jq`, GitHub secrets for API key and site URL.

```yaml
name: AEO Audit
on: [pull_request]
jobs:
  aeo-check:
    runs-on: ubuntu-latest
    steps:
      - name: Run AEO Audit
        run: |
          SCORE=$(curl -s -X POST https://webmole.ai/api/v1/audit \
            -H "Authorization: Bearer ${{ secrets.WEBMOLE_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"url": "${{ secrets.SITE_URL }}"}') | jq '.score'
          echo "AEO Score: $SCORE"
          [ "$SCORE" -ge 70 ] || exit 1
```