{
  "openapi":"3.1.0",
  "info":{
    "title":"HTML&HTML Website AI & Search Readiness API",
    "version":"2.5.0",
    "description":"Public contracts for the 18-engine evidence diagnosis, 13 non-scoring Intelligence Audits, seven readiness lenses, paid AI Mention Tracker, the entitlement-gated $99 AI Search Visibility Roadmap, and its automated ZIP delivery pack. Evaluated signals are internal heuristics; NOT_MEASURED and REQUIRES_CONTEXT are preserved instead of fabricated scores."
  },
  "servers":[{"url":"https://htmlandhtml.com"}],
  "paths":{
    "/api/health":{"get":{"summary":"Service health and capability state","operationId":"getHealth","responses":{"200":{"description":"Health state"}}}},
    "/api/scan":{"post":{"summary":"Run the public 18-engine diagnosis plus 13 non-scoring Intelligence analyses","operationId":"scanWebsite","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","examples":["example.com"]}}}}}},"responses":{"200":{"description":"Complete evidence-backed diagnostic result with unchanged 18-engine core scores, all public findings and non-scoring intelligence report. Implementation instructions are not included."},"400":{"description":"Invalid or unscannable target"},"403":{"description":"Target rejected by network safety boundary"}}}},
    "/api/intelligence":{"post":{"summary":"Run the public Search & AI Intelligence Audit","description":"Returns exactly 13 analyses and seven internal readiness lenses. Information Gain is a within-site public differentiation signal, not a Google score. Render parity and source-code governance remain NOT_MEASURED/REQUIRES_CONTEXT without the required evidence.","operationId":"auditIntelligence","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"url":{"type":"string"}},"anyOf":[{"required":["domain"]},{"required":["url"]}]}}}},"responses":{"200":{"description":"Non-scoring intelligence report"},"400":{"description":"Invalid or unscannable target"},"403":{"description":"Target rejected by network safety boundary"}}}},
    "/api/mandate":{"post":{"summary":"Generate the $99 entitlement-gated AI Search Visibility Roadmap","description":"Internal commercial contract name remains FULL_SITE_FIX_MANDATE for backward compatibility. The customer-facing deliverable is the AI Search Visibility Roadmap.","operationId":"generateVisibilityRoadmap","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string"},"baseline_scan":{"type":"object"}}}}}},"responses":{"200":{"description":"Paid Roadmap, 50-page maximum, including P0–P3 issue execution contracts and intelligence priorities"},"402":{"description":"Valid paid entitlement required"},"503":{"description":"Paid implementation entitlement is not configured"}}}},
    "/api/delivery":{"post":{"summary":"Generate and download the paid Roadmap ZIP package","description":"Runs the same domain through the canonical scan and $99 Roadmap contract. Returns a deterministic ZIP with 11 core files plus up to 30 evidence-bound page-level machine-surface manifests. Guest delivery requires a short-lived entitlement bound to both target domain and order_id; admin bearer access remains available for operations. Only one proposed root llms.txt is generated; page-level files are Markdown machine-surface manifests and never fabricated page content.","operationId":"downloadVisibilityRoadmap","security":[{"bearerAuth":[]},{"guestEntitlement":[]}],"parameters":[{"in":"header","name":"x-htmlhtml-entitlement","required":false,"schema":{"type":"string"},"description":"Required for guest delivery; HMAC-signed, short-lived, domain+order-bound entitlement."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string"},"order_id":{"type":"string","minLength":6,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$","description":"Required when x-htmlhtml-entitlement is used."},"locale":{"type":"string","enum":["tr","en"],"default":"en"},"baseline_scan":{"type":"object"}}}}}},"responses":{"200":{"description":"ZIP Roadmap package: 00_READ_ME.md through 10_EVALUATION_REPORT.md plus machine-surfaces/ up to 30 files.","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"402":{"description":"Valid paid entitlement bound to this domain and order_id required"},"503":{"description":"Paid delivery entitlement is not configured"}}}},
    "/api/mentions":{"get":{"summary":"AI Mention Tracker availability","responses":{"200":{"description":"Provider and paid-access configuration status"}}},"post":{"summary":"Run paid neutral-prompt AI mention measurement","description":"Measures provider API/search-grounded surfaces; consumer app results can differ.","parameters":[{"in":"header","name":"x-ai-mention-token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Mention observations and citation evidence"},"400":{"description":"Invalid or biased prompt"},"402":{"description":"Paid access required"},"503":{"description":"Paid module/provider configuration unavailable"}}}}
  },
  "components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"guestEntitlement":{"type":"apiKey","in":"header","name":"x-htmlhtml-entitlement","description":"Short-lived signed guest download entitlement; request body order_id and domain must match the token claims."}}}
}