{"openapi":"3.1.1","info":{"title":"Themelior public API","version":"1.1.0+1001b28","summary":"Scan a website the way an agent reads it.","description":"Themelior measures how well AI agents can use a website. The full picture, with every MCP server and the limits: https://themelior.com/llms.txt\n\nVersioning: the paths carry no version and no request needs a version header. One version is live, the one described here, and no older one is kept. A change, a breaking one included, is published in this description and in llms.txt with the deploy that makes it; the part of info.version after + names that deploy's commit. No notice period is promised yet.\n\nErrors: every JSON error of the REST paths is {\"error\", \"message\"}, error a stable code (schema Error) and message one sentence for a person; GET /api/health's 503 is its Health body instead. The scan stream answers 200 and ends with an error line instead, with its own code. On /api/mcp, the API key's 401 and 429 are {\"error\", \"message\"} too; the MCP endpoint's other errors are JSON-RPC errors.\n\nLimits: each 429 these paths' handlers send carries Retry-After in seconds. A 429 from an API key's own limit (60 requests per API key, counted until the key goes 60 seconds without a served request) also carries the IETF draft RateLimit and RateLimit-Policy fields; the policy names the quota (q) and no window (w), since the count restarts only after that pause. Served requests carry no rate-limit header.","contact":{"url":"https://themelior.com/contact"}},"externalDocs":{"description":"llms.txt","url":"https://themelior.com/llms.txt"},"servers":[{"url":"https://themelior.com"}],"paths":{"/api/scan":{"post":{"operationId":"startScan","security":[],"summary":"Scan a public website, streamed as it runs","description":"No account. The scan reads the page the way an agent does and scores Find, Act and Safe from static checks. The answer is NDJSON, one ScanStreamEvent per line: a `step` for each of page, robots, sitemap, llms, mcp, openapi, https, score as it completes, then `done` with the report's `id` and its static `score`, or `error` with a `code` (refused, failed, internal) and a message for the person. Every outcome answers 200, a refusal included (an empty or invalid body, a URL the scan refuses, an address that does not resolve or whose DNS lookup does not answer included, a site that opted out, a limit reached): a refusal is one `error` line with code refused, and past a limit its message says when to retry. The status and headers are sent before the limits are counted, so no rate-limit header is sent here. A complete scan of the same URL from the last hour is reused: one `done` line with `\"reused\": true` and no steps. The report is at https://themelior.com/scan/{id}, its badge at https://themelior.com/scan/{id}/badge.svg. Limits: https://themelior.com/llms.txt (Limits).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartScanInput"},"example":{"site":"example.com"}}}},"responses":{"200":{"description":"The scan's events, one JSON object per line (NDJSON), each a ScanStreamEvent; never cached. A whole stream:\n\n```\n{\"type\":\"step\",\"step\":\"page\",\"found\":true,\"detail\":\"200 · 42 KB\"}\n{\"type\":\"step\",\"step\":\"robots\",\"found\":true}\n{\"type\":\"step\",\"step\":\"openapi\",\"found\":false}\n{\"type\":\"step\",\"step\":\"score\",\"found\":null,\"detail\":\"72\"}\n{\"type\":\"done\",\"id\":\"7b1e0a8e-1f3a-4f2e-9d2a-0a0a0a0a0a0a\",\"score\":72,\"reused\":false}\n```","headers":{"Cache-Control":{"schema":{"type":"string","const":"no-store"}}},"content":{"application/x-ndjson":{"schema":{"$ref":"#/components/schemas/ScanStreamEvent"},"examples":{"step_page":{"value":{"type":"step","step":"page","found":true,"detail":"200 · 42 KB"}},"step_robots":{"value":{"type":"step","step":"robots","found":true}},"step_openapi":{"value":{"type":"step","step":"openapi","found":false}},"step_score":{"value":{"type":"step","step":"score","found":null,"detail":"72"}},"done":{"value":{"type":"done","id":"7b1e0a8e-1f3a-4f2e-9d2a-0a0a0a0a0a0a","score":72,"reused":false}},"error":{"value":{"type":"error","code":"refused","message":"You have run 10 scans in the last hour. Try again in 12 minutes."}}}}}}}},"get":{"operationId":"scanUsage","security":[],"summary":"How to call the scan (not a scan)","responses":{"405":{"description":"The scan takes POST only; the body says how to call it.","headers":{"Allow":{"schema":{"type":"string","const":"POST"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"method_not_allowed","message":"POST a JSON body {\"site\":\"example.com\"}; the scan streams back as NDJSON, one step per line."}}}}}}},"/api/sites/{siteId}/scans":{"post":{"operationId":"startDeployScan","summary":"Scan one of your own watched sites after a deploy","description":"For a customer's CI step. Scans the URL stored for the site (never one from the caller), as the daily re-scan does: the scan is stored with the site, compared with the one before it (Stays correct) and shown in /app; the answer is JSON, not a stream. The key's user must own the site and have it marked as theirs; any other id answers 404. A complete scan of the same `deployLabel` is never stored twice: a retry answers the first scan with `duplicate: true` and counts toward no scan limit. No label, no dedupe. A scan seconds after a deploy can read a build the CDN has not replaced yet: wait until the deployment answers. Uses no model. Limits: the key's own (60 requests per API key, counted until the key goes 60 seconds without a served request; checked first), the scan limits of https://themelior.com/llms.txt (Limits) counted per API key and its account together, and at most 48 deploy scans a day (UTC) per site, each answered 429 with Retry-After.","security":[{"apiKey":[]}],"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site's id, from /app or the MCP tool list_my_sites. An id that is not a UUID answers 404, like any other unknown id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"description":"Optional; at most 1024 bytes. No body is no label.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeployScanInput"},"example":{"deployLabel":"3f9c2d1"}}}},"responses":{"200":{"description":"The scan, new or the first one for this deployLabel.","headers":{"Cache-Control":{"schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeployScanResult"},"example":{"duplicate":false,"scanId":"7b1e0a8e-1f3a-4f2e-9d2a-0a0a0a0a0a0a","report":"https://themelior.com/scan/7b1e0a8e-1f3a-4f2e-9d2a-0a0a0a0a0a0a","host":"example.com","deployLabel":"3f9c2d1","staticScore":72,"previousStaticScore":80,"drop":8,"regressions":[{"title":"llms.txt","from":"pass","to":"fail","fix":"Serve /llms.txt again."}]}}}},"400":{"description":"The body is not valid.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"invalid_request"}}}]},"examples":{"too_long":{"value":{"error":"invalid_request","message":"The body is unreadable or over 1024 bytes."}},"not_json":{"value":{"error":"invalid_request","message":"The body is not JSON."}},"bad_label":{"value":{"error":"invalid_request","message":"deployLabel is 1 to 64 characters: letters, digits and . _ - /"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No such site on the key's account (the same answer for every other id).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"not_found"}}}]},"examples":{"not_found":{"value":{"error":"not_found","message":"No such site on this account."}}}}}},"422":{"description":"The site's host asked us to stop and is not proved yours.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"not_scannable"}}}]},"examples":{"opted_out":{"value":{"error":"not_scannable","message":"The owner of example.com asked Themelior to stop. Prove it is yours to scan it."}}}}}},"429":{"description":"Over the key's request limit, a scan limit or the site's deploy scans for the day (UTC). Each of these three sends Retry-After; RateLimit and RateLimit-Policy only the key's limit.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"rate_limited"}}}]},"examples":{"key_limit":{"value":{"error":"rate_limited","message":"Too many requests for this API key. Retry in 42s."}},"scan_limit":{"value":{"error":"rate_limited","message":"You have run 10 scans in the last hour. Try again in 12 minutes."}},"deploy_day":{"value":{"error":"rate_limited","message":"This site has stored 48 deploy scans today (UTC). Try again in 300 minutes."}}}}}},"500":{"description":"Our side failed; the cause is never sent.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"internal"}}}]},"examples":{"internal":{"value":{"error":"internal","message":"The scan failed on our side. Try again in a minute."}}}}}},"502":{"description":"The site could not be fetched, or its stored URL is refused.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"scan_failed"}}}]},"examples":{"unreachable":{"value":{"error":"scan_failed","message":"example.com did not answer."}},"private":{"value":{"error":"scan_failed","message":"example.com points to a private network."}}}}}}}}},"/scan/{id}/badge.svg":{"get":{"operationId":"reportBadge","security":[],"summary":"A report's badge","description":"The report's static score as an embeddable SVG (light and dark by the reader's setting). An unlisted report's badge shows no score. Cached for an hour.","parameters":[{"name":"id","in":"path","required":true,"description":"The report's id, from POST /api/scan or the MCP tools.","schema":{"type":"string"}}],"responses":{"200":{"description":"The badge.","headers":{"Cache-Control":{"schema":{"type":"string","const":"public, max-age=3600, s-maxage=3600"}}},"content":{"image/svg+xml":{"schema":{"type":"string"}}}},"404":{"description":"No report with this id.","content":{"text/plain":{"schema":{"type":"string","const":"Not found"}}}}}}},"/api/health":{"get":{"operationId":"health","security":[],"summary":"Uptime check","description":"Whether the service and its database answer. Never cached.","responses":{"200":{"description":"Up.","headers":{"Cache-Control":{"schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"},"example":{"status":"ok"}}}},"503":{"description":"The database does not answer.","headers":{"Cache-Control":{"schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"},"example":{"status":"degraded"}}}}}}},"/api/mcp":{"post":{"operationId":"mcp","summary":"Themelior's MCP endpoint (Streamable HTTP)","description":"An MCP server, not a REST resource: POST MCP JSON-RPC messages over Streamable HTTP, stateless (no session id), with Accept: application/json, text/event-stream. Its tools and their inputs are listed, readable without a key, in https://themelior.com/llms.txt (MCP servers), and described at https://themelior.com/.well-known/mcp.json. The key is checked first: 401 and 429 come before the message is read.","externalDocs":{"description":"The tools and their inputs","url":"https://themelior.com/llms.txt"},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"jsonrpc":"2.0","id":1,"method":"tools/list"}}}},"responses":{"200":{"description":"The JSON-RPC response to a request, as one server-sent event.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"202":{"description":"A notification, accepted; no body."},"400":{"description":"The body could not be read, is not JSON or not a JSON-RPC message, or names a protocol version the server does not support.","content":{"application/json":{"schema":{"type":"object"},"example":{"jsonrpc":"2.0","error":{"code":-32700,"message":"Parse error: Invalid JSON-RPC message"},"id":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"406":{"description":"The Accept header does not list both application/json and text/event-stream.","content":{"application/json":{"schema":{"type":"object"},"example":{"jsonrpc":"2.0","error":{"code":-32000,"message":"Not Acceptable: Client must accept both application/json and text/event-stream"},"id":null}}}},"413":{"description":"The body is over 4194304 bytes.","content":{"application/json":{"schema":{"type":"object"},"example":{"jsonrpc":"2.0","error":{"code":-32000,"message":"Payload Too Large: Request body must not exceed 4194304 bytes"},"id":null}}}},"415":{"description":"The Content-Type is not application/json.","content":{"application/json":{"schema":{"type":"object"},"example":{"jsonrpc":"2.0","error":{"code":-32000,"message":"Unsupported Media Type: Content-Type must be application/json"},"id":null}}}},"429":{"$ref":"#/components/responses/KeyRateLimited"},"500":{"description":"The MCP server failed on our side; the cause is never sent.","content":{"application/json":{"schema":{"type":"object"},"example":{"jsonrpc":"2.0","error":{"code":-32603,"message":"Internal server error"},"id":null}}}}}},"get":{"operationId":"mcpStream","summary":"No server-sent stream (stateless endpoint)","description":"The endpoint keeps no session, so GET opens no stream: a valid key gets 405 with Allow: POST.","externalDocs":{"description":"The tools and their inputs","url":"https://themelior.com/llms.txt"},"security":[{"apiKey":[]}],"responses":{"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"description":"POST only, for a valid key.","content":{"application/json":{"schema":{"type":"object"},"example":{"jsonrpc":"2.0","error":{"code":-32000,"message":"Method not allowed."},"id":null}}},"headers":{"Allow":{"schema":{"type":"string","const":"POST"}}}},"429":{"$ref":"#/components/responses/KeyRateLimited"}}}}},"components":{"schemas":{"StartScanInput":{"type":"object","properties":{"site":{"type":"string","minLength":1,"maxLength":2048}},"required":["site"]},"ScanStreamEvent":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"step"},"step":{"type":"string","enum":["page","robots","sitemap","llms","mcp","openapi","https","score"]},"found":{"type":["boolean","null"]},"detail":{"type":"string","maxLength":120}},"required":["type","step","found"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"done"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"score":{"type":"integer","minimum":0,"maximum":100},"reused":{"type":"boolean"}},"required":["type","id","score","reused"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"error"},"code":{"description":"refused: the body, the URL (an address that does not resolve, or whose DNS lookup does not answer, included), the site's opt-out or a limit refused the scan (the message says which, and when to retry); failed: the site could not be read; internal: our side failed.","type":"string","enum":["refused","failed","internal"]},"message":{"type":"string","description":"One sentence for the person."}},"required":["type","message"],"additionalProperties":false}]},"DeployScanInput":{"type":"object","properties":{"deployLabel":{"description":"The commit SHA or deployment id this scan is for. Sent twice, the second call answers the first scan with duplicate: true and stores nothing.","type":"string","pattern":"^[A-Za-z0-9._/-]{1,64}$"}}},"DeployScanResult":{"type":"object","properties":{"duplicate":{"type":"boolean","description":"True when this deployLabel was scanned before: that scan."},"scanId":{"type":"string"},"report":{"type":"string","format":"uri","description":"The report, for the site's owner."},"host":{"type":"string"},"deployLabel":{"type":["string","null"]},"staticScore":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Find, Act and Safe, 0 to 100."},"previousStaticScore":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The site's scan before this one; null for its first."},"drop":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Points lost since that scan (negative when the score rose); null for a first scan."},"regressions":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"from":{"type":"string","description":"The sub-check's status before: pass or warn."},"to":{"type":"string","description":"Its status now: warn or fail."},"fix":{"type":"string"}},"required":["title","from","to","fix"],"additionalProperties":false},"description":"Each sub-check that got worse since the scan before."}},"required":["duplicate","scanId","report","host","deployLabel","staticScore","previousStaticScore","drop","regressions"],"additionalProperties":false},"Health":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"]}},"required":["status"],"additionalProperties":false},"Error":{"type":"object","description":"Every JSON error of the REST paths (the health check's 503 aside, a Health body), and the API key's 401 and 429 on the MCP endpoint (its other errors are JSON-RPC): a stable code for programs and one sentence for people. method_not_allowed: The path takes another method (GET /api/scan). invalid_request: The body is unreadable, too long, not JSON or not valid. unauthorized: No API key, or a wrong, revoked or expired one. not_found: Nothing with that id on the key's account. not_scannable: The site's owner asked Themelior to stop, and it is not proved yours. rate_limited: A limit was reached; Retry-After says when to try again. scan_failed: The site could not be read. internal: Our side failed; never the cause. Try again in a minute.","properties":{"error":{"type":"string","enum":["method_not_allowed","invalid_request","unauthorized","not_found","not_scannable","rate_limited","scan_failed","internal"]},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":false}},"responses":{"Unauthorized":{"description":"No key, or a wrong, revoked or expired one; the message says where to make one. Answered before the body is read.","headers":{"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"unauthorized"}}}]},"examples":{"no_key":{"value":{"error":"unauthorized","message":"Send Authorization: Bearer thm_... with an API key made in https://themelior.com/app (free account). Themelior uses static API keys, not OAuth."}},"refused_key":{"value":{"error":"unauthorized","message":"This API key is wrong, revoked or expired. Make a new one in https://themelior.com/app (free account)."}}}}}},"KeyRateLimited":{"description":"Over the key's limit: 60 requests per API key, counted until the key goes 60 seconds without a served request. Answered before the body is read.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"error":{"const":"rate_limited"}}}]},"examples":{"key_limit":{"value":{"error":"rate_limited","message":"Too many requests for this API key. Retry in 42s."}}}}}}},"headers":{"RetryAfter":{"description":"Seconds to wait before the next request.","schema":{"type":"integer","minimum":1}},"RateLimit":{"description":"Only on a 429 from the API key's own limit: the IETF draft field (draft-ietf-httpapi-ratelimit-headers), 0 requests left (r) and seconds until the next one is served (t), the same wait as Retry-After.","schema":{"type":"string","example":"\"key\";r=0;t=42"}},"RateLimitPolicy":{"description":"Only with RateLimit: the key's quota, 60 requests (q). No window (w): the count restarts only once the key has gone 60 seconds without a served request, so steady traffic under 60 a minute can still reach it.","schema":{"type":"string","const":"\"key\";q=60"}},"WWWAuthenticate":{"description":"An RFC 6750 Bearer challenge; with error=\"invalid_token\" when a key was sent and refused.","schema":{"type":"string","example":"Bearer realm=\"themelior\""}}},"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"thm_...","description":"A static API key made in https://themelior.com/app (free account, up to 5 keys), sent as Authorization: Bearer thm_...; not OAuth. Scopes: none. A key acts as its account on every operation that takes one (the deploy scan, and every tool of the MCP endpoint: scan_site, get_report, list_my_sites, get_site_fixes); revoke it in /app. 60 requests per API key, counted until the key goes 60 seconds without a served request, then 429 with Retry-After."}}}}