SEO Audit API Documentation

Make your first API call in seconds. Send a GET request with the target URL:

curl "https://www.auditme.dev/api/v1/audit?url=https://example.com"

No authentication needed. You will receive a JSON response with a full SEO audit of the specified page.

The audit endpoint accepts a target URL as a query parameter and returns a JSON object containing the complete SEO analysis. The response typically completes within 5—15 seconds depending on the target page size.

No API key is required — send the request and you get JSON back. An optional account API key raises your shared limit from 10 to 30 requests per minute via the x-api-key header:

# Anonymous — 10 requests/min per IP (no key needed)
curl "https://www.auditme.dev/api/v1/audit?url=https://example.com"

# With an account API key — 30 requests/min (optional)
curl -H "x-api-key: YOUR_API_KEY" \
  "https://www.auditme.dev/api/v1/audit?url=https://example.com"

All parameters are passed as query string parameters on the GET request.

The API returns a JSON object with the following top-level structure:

{
  "ok": true,
  "api_version": "v1",
  "scanned_at": "2026-08-29T10:00:00.000Z",
  "page": {
    "url": "https://example.com",
    "title": "Example Domain",
    "meta_description": "This domain is for use in illustrative examples",
    "h1": "Example Domain",
    "word_count": 68,
    "images": { "total": 5, "missing_alt": 1 },
    "links": { "internal": 3, "external": 1 },
    "og": {
      "title": "Example Domain",
      "description": "This domain is for use in illustrative examples",
      "image": "https://example.com/og.png"
    },
    "canonical": "https://example.com",
    "robots": "index, follow",
    "schema_markup": true,
    "load_time_ms": 312,
    "status_code": 200
  },
  "score": {
    "current": 85,
    "max": 100,
    "percentage": 85
  },
  "recommendations": [
    {
      "type": "warning",
      "category": "Images",
      "title": "One image is missing alt text",
      "description": "Add descriptive alt text so the image is accessible and indexed.",
      "impact": "medium",
      "effort": "medium",
      "confidence": 90,
      "source": "deterministic",
      "current_value": "Image without alt attribute",
      "suggested_value": "<img src=\"hero.jpg\" alt=\"Descriptive alt text\" />"
    }
  ],
  "ai_insights": "Add alt text to images and keep the meta description within 150 characters."
}

The API enforces a rate limit of 10 requests per minute per IP address. This is generous enough for most monitoring, reporting, and development use cases.

Anonymous requests are limited to 10 per minute per IP address. Account API keys share a higher quota — 30 per minute by default, up to 60 when raised by an operator — counted together across REST and MCP. There is no paid API tier.

Errors return a JSON object with an error message. Check the HTTP status code first, then read the message:

{
  "error": "url parameter is required",
  "usage": "GET /api/v1/audit?url=https://example.com&format=json",
  "docs": "https://www.auditme.dev/api-docs"
}

{
  "error": "Rate limit exceeded. Try again in a minute.",
  "retry_after_ms": 60000
}

Use the API from any language that supports HTTP requests. Here are examples in JavaScript and Python:

JavaScript (fetch)

async function auditUrl(url) {
  const response = await fetch(
    `https://www.auditme.dev/api/v1/audit?url=${encodeURIComponent(url)}`
  );

  if (!response.ok) {
    throw new Error(`Audit failed: ${response.status}`);
  }

  const data = await response.json();
  console.log("Overall Score:", data.score.percentage);
  console.log("Page Title:", data.page.title);
  console.log("Load Time:", data.page.load_time_ms + "ms");

  return data;
}

auditUrl("https://example.com");

Python (requests)

import requests
from urllib.parse import urlencode

def audit_url(url):
    params = {"url": url}
    response = requests.get(
        "https://www.auditme.dev/api/v1/audit",
        params=params
    )
    response.raise_for_status()
    data = response.json()

    print(f"Overall Score: {data['score']['percentage']}")
    print(f"Page Title: {data['page']['title']}")
    print(f"Load Time: {data['page']['load_time_ms']}ms")

    return data

audit_url("https://example.com")

cURL

# Basic GET request
curl "https://www.auditme.dev/api/v1/audit?url=https://example.com"

# Compact format (trimmed summary)
curl "https://www.auditme.dev/api/v1/audit?url=https://example.com&format=compact"

# Pretty-print JSON output
curl -s "https://www.auditme.dev/api/v1/audit?url=https://example.com" | jq .

Embed a live SEO score badge on any website. The badge displays the current score and links directly to the audit report.

Embed Examples

Image

<!-- Simple badge -->
<img loading="lazy" src="https://www.auditme.dev/api/widget?domain=example.com" alt="SEO Score" style="border:0" />

<!-- Custom color and size -->
<img loading="lazy" src="https://www.auditme.dev/api/widget?domain=example.com&color=3b82f6&size=large" alt="SEO Score" style="border:0" />

Iframe

<!-- Clickable badge (opens audit report) -->
<iframe
  src="https://www.auditme.dev/api/widget?domain=example.com&format=iframe"
  width="200" height="56" style="border:0"
  loading="lazy" title="SEO Score"
></iframe>

JavaScript

<!-- Live badge, auto-positioned bottom-right. Domain is auto-detected. -->
<script async src="https://www.auditme.dev/widget.js" data-color="10b981"></script>

<!-- Explicit domain + inline placement -->
<div id="auditme-widget"></div>
<script async src="https://www.auditme.dev/widget.js"
        data-domain="example.com" data-color="3b82f6"
        data-position="inline"></script>

<!-- White-label for agencies -->
<script async src="https://www.auditme.dev/widget.js"
        data-domain="example.com" data-brand="Your Agency"
        data-link="https://youragency.com/audit-offer"></script>