{"openapi":"3.1.0","info":{"title":"Hermes by inlevel9 Scan API","version":"0.1.0","description":"Start a public website search-readiness scan and poll its progress. Hermes evaluates Google, Naver, and AI-search readiness signals for public websites.","contact":{"name":"INLEVEL9","url":"https://inlevel9.com/","email":"contact@inlevel9.com"}},"servers":[{"url":"https://hermes.inlevel9.com","description":"Hermes production"}],"externalDocs":{"description":"Hermes developer resources","url":"https://hermes.inlevel9.com/developers"},"tags":[{"name":"Scans","description":"Public website search-readiness scans"}],"paths":{"/api/scans":{"post":{"operationId":"createScan","summary":"Start a website search-readiness scan","description":"Validates a public website URL, applies the public rate limit, and queues a scan. Poll the returned scanId until the status is terminal.","tags":["Scans"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateScanRequest"},"examples":{"website":{"value":{"url":"https://example.com"}}}}}},"responses":{"202":{"description":"Scan accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateScanResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/InvalidTarget"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/scans/{scanId}":{"get":{"operationId":"getScanProgress","summary":"Get scan progress","description":"Returns the current lifecycle state, the remaining anonymous result wait, and the result URL after completion.","tags":["Scans"],"parameters":[{"name":"scanId","in":"path","required":true,"description":"The identifier returned by createScan.","schema":{"type":"string","pattern":"^scn_[A-Za-z0-9_]+$"}}],"responses":{"200":{"description":"Current scan state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanProgress"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}},"components":{"schemas":{"CreateScanRequest":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"mode":{"type":"string","enum":["reuse","refresh"],"default":"reuse","description":"refresh requests the scan stream without immediately returning the stored report; upstream caching can still apply."},"url":{"type":"string","format":"uri","maxLength":2048,"description":"Public HTTP(S) website URL to scan."}}},"CreateScanResponse":{"type":"object","additionalProperties":false,"required":["scanId","status"],"properties":{"scanId":{"type":"string","pattern":"^scn_[A-Za-z0-9_]+$"},"status":{"type":"string","const":"queued"}}},"ScanProgress":{"type":"object","required":["scanId","domain","status","progress","stage","message","explorationEvents","anonymousResultWaitMs"],"properties":{"scanId":{"type":"string"},"domain":{"type":"string"},"status":{"type":"string","enum":["QUEUED","VALIDATING","SCANNING","NORMALIZING","SCORING","SUMMARIZING","COMPLETED","COMPLETED_PARTIAL","FAILED"]},"progress":{"type":"integer","minimum":0,"maximum":100},"stage":{"type":"string"},"message":{"type":"string"},"completedChecks":{"type":"integer","minimum":0},"totalChecks":{"type":"integer","minimum":0},"explorationEvents":{"type":"array","description":"Observed scan actions in execution order. Each item records why the action was selected.","items":{"$ref":"#/components/schemas/ScanExplorationEvent"}},"anonymousResultWaitMs":{"type":"integer","minimum":0,"maximum":60000,"description":"Milliseconds remaining before an anonymous visitor may see the completed result."},"resultUrl":{"type":"string","pattern":"^/scan/"},"error":{"type":"string"}}},"ScanExplorationEvent":{"type":"object","additionalProperties":false,"required":["id","sequence","kind","status","label","description","origin","startedAt","contributesToResult","evidenceRuleIds"],"properties":{"id":{"type":"string"},"sequence":{"type":"integer","minimum":0},"kind":{"type":"string","enum":["target","lookup","scan","check","transform","evidence","outcome"]},"status":{"type":"string","enum":["queued","active","succeeded","attention","failed"]},"label":{"type":"string"},"description":{"type":"string"},"target":{"type":"string"},"parentId":{"type":"string"},"origin":{"type":"object","required":["kind","label"],"properties":{"kind":{"type":"string","enum":["direct_target","upstream_roster","previous_event","result_evidence"]},"label":{"type":"string"},"refEventId":{"type":"string"}}},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"},"durationMs":{"type":"integer","minimum":0},"contributesToResult":{"type":"boolean"},"evidenceRuleIds":{"type":"array","items":{"type":"string"}}}},"Error":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Malformed JSON request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PayloadTooLarge":{"description":"Request body exceeds 8 KB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InvalidTarget":{"description":"URL is missing, malformed, private, or otherwise unsafe to scan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Public scan limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Scan not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"The scan request could not be created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"x-mcp-endpoints":["https://hermes.inlevel9.com/.well-known/mcp","https://hermes.inlevel9.com/mcp"]}