Home/API Documentation

API Documentation

REST API for SEO audits, AI visibility checks, and AI agent integration via MCP.

Last updated: August 31, 2026

Quick Start

Run an SEO audit

curl "https://www.auditme.dev/api/v1/audit?url=https%3A%2F%2Fwww.auditme.dev&format=json"

JavaScript (fetch)

const res = await fetch("https://www.auditme.dev/api/v1/audit?url=https%3A%2F%2Fwww.auditme.dev&format=json");
const data = await res.json();
console.log("Score:", data.score);

Python (requests)

import requests
r = requests.get("https://www.auditme.dev/api/v1/audit", params={"url": "https://example.com"})
data = r.json()
print(f"Score: {data['score']}")

Endpoints

GET/api/v1/audit

Analyze a URL for SEO issues. Returns a comprehensive audit with score, issues, and recommendations. Rate limit: 10 requests/minute anonymous, 30 free, 60 pro — shared with MCP for the same API key.

Parameters

Name	Type	Required	Description
url	string	Yes	The URL to audit
format	string	No	Response format: full JSON or compact summary

Request

curl "https://www.auditme.dev/api/v1/audit?url=https%3A%2F%2Fwww.auditme.dev&format=json"

Response

{
  "ok": true,
  "api_version": "v1",
  "scanned_at": "2026-10-14T12:00:00.000Z",
  "page": {
    "url": "https://example.com",
    "title": "Example Domain",
    "meta_description": null,
    "h1": "Example Domain",
    "word_count": 120,
    "canonical": "https://example.com",
    "load_time_ms": 400,
    "status_code": 200
  },
  "score": {
    "current": 82,
    "max": 100,
    "percentage": 82,
    "passed": 130,
    "total": 159,
    "engine_version": "1.0.0",
    "ruleset_version": "1.0.0",
    "ruleset_fingerprint": "abc123"
  },
  "recommendations": [
    {
      "type": "critical",
      "category": "SEO Technical",
      "title": "Missing meta description",
      "description": "Add a meta description of 150-160 characters",
      "impact": "high",
      "effort": "low",
      "confidence": 90,
      "current_value": null,
      "suggested_value": "Add a compelling meta description…"
    }
  ],
  "target_type": "public",
  "target": null,
  "meta": {
    "engine_version": "1.0.0",
    "ruleset_version": "1.0.0",
    "ruleset_fingerprint": "abc123",
    "checks_executed": 159
  }
}

200400429500

POST/api/v1/audit/batch

Run up to 10 SEO audits in one request with bounded concurrency (3). Rate limit: 1 unit per URL from the same shared audit quota (10/min anon, 30 free, 60 pro). SUPERFINAL Phase C.

Request

{
  "urls": [
    "https://example.com",
    "https://example.org"
  ],
  "format": "compact"
}

200400429

POST/api/ai-visibility-scan

Deterministic check of a website's AI-readiness: LLMs.txt, AI bot access, content structure, entity clarity.

Request

{
  "url": "https://example.com"
}

Response

{
  "ok": true,
  "score": 75,
  "pillars": {
    "llmsTxt": 80,
    "aiBotAccess": 90,
    "answerStructure": 65,
    "entityClarity": 70
  },
  "recommendations": [
    "Add /llms.txt with site description and key pages",
    "Add FAQ schema for better AI citation potential"
  ]
}

200429

POST/api/ai-readiness

Check if a website is ready for AI search engines: LLMs.txt presence, robots.txt AI bot rules, semantic HTML analysis.

Request

{
  "url": "https://example.com"
}

200

POST/api/mcp

Model Context Protocol endpoint for AI agents (MCP 2026-07-28, Streamable HTTP). Execute SEO audit tools via JSON-RPC. Public tools (get_site_info, get_audit_methodology, get_seo_concept) work without auth; write tools require the x-api-key header. Modern requests must send Content-Type: application/json, the MCP-Protocol-Version header (2026-07-28), an Mcp-Method header mirroring params.method, a params._meta envelope carrying io.modelcontextprotocol/protocolVersion + io.modelcontextprotocol/clientCapabilities, and for tools/call/prompts/get/resources/read an Mcp-Name header mirroring params.name (or params.uri); missing or mismatched values are rejected with HTTP 400. Responses are a single application/json JSON-RPC message. Rate limit is SHARED with REST for the same key: 10/min anonymous (IP, public tools only), 30/min free, 60/min pro. Responses include content[].text (string) and structuredContent (object) where an output schema is defined.

Parameters

Name	Type	Required	Description
x-api-key	string	No	API key for write tools and higher rate limits. Absent = anonymous (public tools only, IP rate limit).
MCP-Protocol-Version	string	No	Protocol version for the modern path. When present it must equal params._meta['io.modelcontextprotocol/protocolVersion'] (else HTTP 400).
Mcp-Method	string	No	Mirrors the JSON-RPC method in the body; required whenever MCP-Protocol-Version is sent (else HTTP 400).
Mcp-Name	string	No	Mirrors params.name (tools/call) or params.uri (resources/read); required for those methods on the modern path (else HTTP 400).

Available Tools

• get_site_info — Site info: title, tech stack, crawl statuspublic
• get_audit_methodology — Scoring methodology and check categoriespublic
• get_seo_concept — Plain-language SEO concept explanationspublic
• seo_audit — Full unified audit returning score and issueswrite
• get_opportunities — Prioritized issue list ranked by impactwrite
• generate_fixes — Deterministic fix suggestions (template-based, no LLM)write
• workflow_execute — Multi-step SEO workflow with approval gateswrite
• workflow_status — Status of a running or completed workflowwrite
• approve_fixes — Approve or reject workflow-generated fixeswrite
• detect_regressions — Compare two audit snapshots for regressionswrite
• compare_competitors — Compare SEO metrics against competitorswrite
• monitor_site — Monitoring overview: alerts, rules, severitywrite
• track_keywords — Add, remove, or list tracked keywordswrite
• run_experiment — Create or list SEO experiments with metricswrite

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

200429

GET/api/v1/usage

Per-user API usage snapshot: tier, requests this minute (live counter), requests last 24h, API keys with last_used_at, and enabled webhook subscription count. Requires x-api-key. Read-only — does not consume the shared audit quota.

Parameters

Name	Type	Required	Description
x-api-key	string	Yes	Your API key

Request

curl "https://www.auditme.dev/api/v1/usage?x-api-key=am_"

Response

{
  "ok": true,
  "api_version": "v1",
  "user_id": "uuid",
  "tier": "free",
  "rate_limit_per_minute": 30,
  "requests_this_minute": 3,
  "requests_last_24h": 47,
  "api_keys": [
    {
      "id": "uuid",
      "name": "Default",
      "key_prefix": "am_ab12",
      "scopes": [
        "audit"
      ],
      "rate_limit": 10,
      "enabled": true,
      "last_used_at": "2026-10-15T12:00:00Z",
      "expires_at": null,
      "created_at": "2026-10-01T00:00:00Z"
    }
  ],
  "webhook_subscriptions": 1
}

200401

GET/api/status

Lightweight platform health check. Returns status (ok|degraded), db reachability, engine version, uptime, and latency. No auth required; does not consume the audit quota. Suitable for external uptime monitors.

Request

curl "https://www.auditme.dev/api/status"

Response

{
  "status": "ok",
  "db": "up",
  "engine_version": "1.0.0",
  "timestamp": "2026-10-15T12:00:00Z",
  "uptime_s": 12345,
  "latency_ms": 42
}

200503

Rate Limits

Tier	Requests/min	Pages/crawl
Anonymous	5	30
Free Account	10	100
Pro	30	500

Additional Resources

OpenAPI Spec

Machine-readable API specification

MCP Documentation

Model Context Protocol integration

Methodology

How audits work

Legacy API Docs

Additional API documentation