{"openapi":"3.1.0","info":{"title":"AuditMe API","version":"1.0.0","description":"REST API for AuditMe SEO audit platform. Analyze websites for technical SEO, performance, schema, content quality, and AI visibility.","contact":{"name":"AuditMe Support","url":"https://www.auditme.dev/support","email":"support@auditme.dev"},"license":{"name":"MIT","url":"https://github.com/Edo911/AISeoAudit/blob/main/LICENSE"}},"servers":[{"url":"https://www.auditme.dev","description":"Production"}],"paths":{"/api/v1/audit":{"get":{"operationId":"runAudit","summary":"Run SEO Audit","description":"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.","tags":["Audit"],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"},"description":"The URL to audit","example":"https://www.auditme.dev"},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","compact"],"default":"json"},"description":"Response format: full JSON or compact summary"}],"responses":{"200":{"description":"Audit results","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed in the current window"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window"},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix timestamp when the window resets"}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"api_version":{"type":"string","example":"v1"},"scanned_at":{"type":"string","format":"date-time"},"page":{"type":"object","description":"Parsed page metadata","properties":{"url":{"type":"string"},"title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"h1":{"type":"string","nullable":true},"word_count":{"type":"integer"},"canonical":{"type":"string","nullable":true},"load_time_ms":{"type":"integer","nullable":true},"status_code":{"type":"integer"}}},"score":{"type":"object","description":"Audit score with provenance metadata","properties":{"current":{"type":"number","description":"Canonical display score 0-100 (W1b-capped; same number the UI and PDF show)"},"max":{"type":"number","example":100},"percentage":{"type":"number","description":"Alias of current (canonical display score)"},"raw_percentage":{"type":"number","description":"Uncapped weighted engine score before display caps (provenance)"},"caps_applied":{"type":"array","items":{"type":"string"},"description":"Display-cap reasons applied (empty when none)"},"passed":{"type":"integer"},"total":{"type":"integer"},"engine_version":{"type":"string"},"ruleset_version":{"type":"string"},"ruleset_fingerprint":{"type":"string"}},"required":["current","percentage","passed","total"]},"recommendations":{"type":"array","description":"Top prioritized issues (max 7)","items":{"type":"object","properties":{"type":{"type":"string","enum":["critical","warning","info"]},"category":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"impact":{"type":"string","enum":["high","medium","low"]},"effort":{"type":"string"},"confidence":{"type":"number"},"current_value":{"type":"string","nullable":true},"suggested_value":{"type":"string","nullable":true}}}},"target_type":{"type":"string","nullable":true,"enum":["public","application","authenticated","redirect-only","error","non-indexable","unknown",null],"description":"Context-aware surface classification of the audited page (S10 additive; null when unclassified)."},"target":{"type":"object","nullable":true,"description":"Full target classification snapshot: surface type, page type, indexability, intent, confidence and classifier/policy versions (S10 additive; null on legacy audits)."},"meta":{"type":"object","properties":{"engine_version":{"type":"string"},"ruleset_version":{"type":"string"},"ruleset_fingerprint":{"type":"string"},"checks_executed":{"type":"integer"}}}}},"example":{"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}}}}},"400":{"description":"Invalid URL or missing url parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}},"example":{"error":"url parameter is required"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"retry_after_ms":{"type":"integer"}}},"example":{"error":"Rate limit exceeded. Try again in a minute.","retry_after_ms":45000}}}},"500":{"description":"Scan failed","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"}}}}}}}}},"/api/v1/audit/batch":{"post":{"operationId":"runAuditBatch","summary":"Run Batch SEO Audit","description":"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.","tags":["Audit"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["urls"],"properties":{"urls":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1,"maxItems":10,"description":"URLs to audit (max 10)"},"format":{"type":"string","enum":["json","compact"],"default":"json","description":"Response format per URL"}}},"example":{"urls":["https://example.com","https://example.org"],"format":"compact"}}}},"responses":{"200":{"description":"Batch audit results","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"api_version":{"type":"string"},"batch":{"type":"object","properties":{"total":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"}}},"results":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"ok":{"type":"boolean"},"score":{"type":"number"},"error":{"type":"string"}}}},"rejected":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"error":{"type":"string"}}}}}}}}},"400":{"description":"Invalid request (bad JSON, >10 URLs, unsafe URL)"},"429":{"description":"Rate limit exceeded (1 unit per URL)","headers":{"Retry-After":{"schema":{"type":"integer"}}}}}}},"/api/ai-visibility-scan":{"post":{"operationId":"scanAiVisibility","summary":"AI Visibility Scan","description":"Deterministic check of a website's AI-readiness: LLMs.txt, AI bot access, content structure, entity clarity.","tags":["AI Visibility"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"URL to scan"}}},"example":{"url":"https://example.com"}}}},"responses":{"200":{"description":"AI visibility results","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"score":{"type":"number","description":"AI visibility score (0-100)"},"pillars":{"type":"object","properties":{"llmsTxt":{"type":"number"},"aiBotAccess":{"type":"number"},"answerStructure":{"type":"number"},"entityClarity":{"type":"number"}}},"recommendations":{"type":"array","items":{"type":"string"}}}},"example":{"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"]}}}},"429":{"description":"Rate limit exceeded"}}}},"/api/ai-readiness":{"post":{"operationId":"checkAiReadiness","summary":"AI Readiness Check","description":"Check if a website is ready for AI search engines: LLMs.txt presence, robots.txt AI bot rules, semantic HTML analysis.","tags":["AI Visibility"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"URL to check"}}},"example":{"url":"https://example.com"}}}},"responses":{"200":{"description":"AI readiness results","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"score":{"type":"number"},"checks":{"type":"object","properties":{"llmsTxt":{"type":"boolean"},"aiBotsAllowed":{"type":"boolean"},"semanticHtml":{"type":"boolean"}}}}}}}}}}},"/api/mcp":{"post":{"operationId":"mcpToolCall","summary":"MCP Tool Call","description":"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.","tags":["MCP"],"parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for write tools and higher rate limits. Absent = anonymous (public tools only, IP rate limit)."},{"name":"MCP-Protocol-Version","in":"header","required":false,"schema":{"type":"string","enum":["2026-07-28"]},"description":"Protocol version for the modern path. When present it must equal params._meta['io.modelcontextprotocol/protocolVersion'] (else HTTP 400)."},{"name":"Mcp-Method","in":"header","required":false,"schema":{"type":"string"},"description":"Mirrors the JSON-RPC method in the body; required whenever MCP-Protocol-Version is sent (else HTTP 400)."},{"name":"Mcp-Name","in":"header","required":false,"schema":{"type":"string"},"description":"Mirrors params.name (tools/call) or params.uri (resources/read); required for those methods on the modern path (else HTTP 400)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","id","method","params"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"oneOf":[{"type":"string"},{"type":"number"}]},"method":{"type":"string","enum":["tools/list","tools/call","prompts/list","resources/list","initialize"],"description":"MCP JSON-RPC method"},"params":{"type":"object","description":"Method parameters (e.g. name + arguments for tools/call)","required":["_meta"],"properties":{"_meta":{"type":"object","description":"Required envelope on the modern path (MCP 2026-07-28)","required":["io.modelcontextprotocol/protocolVersion","io.modelcontextprotocol/clientCapabilities"],"properties":{"io.modelcontextprotocol/protocolVersion":{"type":"string","enum":["2026-07-28"]},"io.modelcontextprotocol/clientCapabilities":{"type":"object"}}}}}}},"example":{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}}}},"responses":{"200":{"description":"MCP JSON-RPC response","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","example":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"}]},"result":{"type":"object","description":"Method result. For tools/call: { content: [{ type: \"text\", text: string }], structuredContent?: object, isError?: boolean }"}}}}}},"429":{"description":"Rate limit exceeded (shared audit quota)","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"limit":{"type":"integer"},"retry_after_ms":{"type":"integer"}}}}}}},"x-mcp-tools":[{"name":"get_site_info","summary":"Site info: title, tech stack, crawl status","category":"public"},{"name":"get_audit_methodology","summary":"Scoring methodology and check categories","category":"public"},{"name":"get_seo_concept","summary":"Plain-language SEO concept explanations","category":"public"},{"name":"seo_audit","summary":"Full unified audit returning score and issues","category":"write"},{"name":"get_opportunities","summary":"Prioritized issue list ranked by impact","category":"write"},{"name":"generate_fixes","summary":"Deterministic fix suggestions (template-based, no LLM)","category":"write"},{"name":"workflow_execute","summary":"Multi-step SEO workflow with approval gates","category":"write"},{"name":"workflow_status","summary":"Status of a running or completed workflow","category":"write"},{"name":"approve_fixes","summary":"Approve or reject workflow-generated fixes","category":"write"},{"name":"detect_regressions","summary":"Compare two audit snapshots for regressions","category":"write"},{"name":"compare_competitors","summary":"Compare SEO metrics against competitors","category":"write"},{"name":"monitor_site","summary":"Monitoring overview: alerts, rules, severity","category":"write"},{"name":"track_keywords","summary":"Add, remove, or list tracked keywords","category":"write"},{"name":"run_experiment","summary":"Create or list SEO experiments with metrics","category":"write"}]}},"/api/v1/usage":{"get":{"operationId":"getUsage","summary":"Get API Usage","description":"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.","tags":["Usage"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your API key","example":"am_"}],"responses":{"200":{"description":"Usage snapshot","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"example":{"error":"Valid x-api-key required"}}}}}}},"/api/status":{"get":{"operationId":"getStatus","summary":"Platform Health","description":"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.","tags":["Status"],"parameters":[],"responses":{"200":{"description":"Healthy","content":{"application/json":{"example":{"status":"ok","db":"up","engine_version":"1.0.0","timestamp":"2026-10-15T12:00:00Z","uptime_s":12345,"latency_ms":42}}}},"503":{"description":"Degraded (database unreachable)","content":{"application/json":{"example":{"status":"degraded","db":"down"}}}}}}}},"tags":[{"name":"Audit","description":"SEO audit operations"},{"name":"AI Visibility","description":"AI search engine readiness checks"},{"name":"MCP","description":"Model Context Protocol for AI agents"},{"name":"Usage","description":"API usage and quota introspection"},{"name":"Status","description":"Platform health and uptime"}]}