{"openapi":"3.1.0","info":{"title":"Cleanor API","version":"1.0.0","description":"Free, no-key HTTP API for Cleanor developer and image tools. The same tools are available over MCP at /mcp. Rate limited per IP.","contact":{"name":"Cleanor Labs","url":"https://cleanor.app/api","email":"support@cleanor.app"},"license":{"name":"Free to use with attribution"}},"servers":[{"url":"https://mcp.cleanor.app"}],"paths":{"/v1/optimize":{"post":{"operationId":"optimize","summary":"Optimize or convert an image (WebP, AVIF, JPEG)","description":"Send multipart `file`, JSON `{ image_url }`, or raw bytes. Optional `format`, `quality` (1-100), `width` (16-4096). Returns the image bytes; add `?json=1` for JSON with base64.","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"format":{"type":"string","enum":["webp","avif","jpeg"]},"quality":{"type":"integer","minimum":1,"maximum":100},"width":{"type":"integer","minimum":16,"maximum":4096}},"required":["file"]}},"application/json":{"schema":{"type":"object","properties":{"image_url":{"type":"string","format":"uri"},"format":{"type":"string","enum":["webp","avif","jpeg"]},"quality":{"type":"integer"},"width":{"type":"integer"}},"required":["image_url"]}}}},"responses":{"200":{"description":"The optimized image."},"429":{"description":"Rate limited."}}}},"/v1/qr.svg":{"get":{"operationId":"qrSvg","summary":"Embeddable QR code","parameters":[{"name":"text","in":"query","required":true,"schema":{"type":"string","maxLength":2000}},{"name":"ecc","in":"query","schema":{"type":"string","enum":["L","M","Q","H"]}},{"name":"size","in":"query","schema":{"type":"integer","minimum":64,"maximum":1024}}],"responses":{"200":{"description":"SVG image.","content":{"image/svg+xml":{}}}}}},"/v1/placeholder/{width}x{height}.svg":{"get":{"operationId":"placeholderSvg","summary":"Embeddable placeholder image","parameters":[{"name":"width","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":4000}},{"name":"height","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":4000}},{"name":"text","in":"query","schema":{"type":"string"}},{"name":"bg","in":"query","schema":{"type":"string"}},{"name":"color","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"SVG image.","content":{"image/svg+xml":{}}}}}},"/v1/tools":{"get":{"operationId":"listTools","summary":"List tools with input schemas","responses":{"200":{"description":"Tool list."}}}},"/v1/tools/storage_capacity":{"post":{"operationId":"storage_capacity","summary":"How much fits in a phone storage tier","description":"How many photos or minutes of video actually fit in a given storage size, corrected for real OS/filesystem overhead. Backed by Cleanor Labs measured per-item sizes. Use for realistic sample copy, dashboards, or \"how many photos fit in 128 GB\" answers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"storage_gb":{"type":"number","minimum":1,"maximum":4096,"description":"Advertised storage size in GB (e.g. 64, 128, 256, 512)."},"content":{"type":"string","enum":["photos","video"],"default":"photos","description":"What to count."}},"required":["storage_gb"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool result: `data` (structured) and `text` (human-readable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments."},"429":{"description":"Rate limited (120 requests per minute per IP)."}}}},"/v1/tools/image_format_savings":{"post":{"operationId":"image_format_savings","summary":"Real storage savings of next-gen image formats","description":"How much smaller WebP, AVIF or JPEG XL are than JPEG at matched perceptual quality, from Cleanor Labs’ controlled benchmark. Also reports the \"HEIC conversion tax\" (converting an iPhone HEIC to JPG/PNG makes it bigger). Use to justify a format choice when building a site or app.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"format":{"type":"string","enum":["webp","avif","jxl"],"default":"avif","description":"Target format to compare against JPEG."},"quality":{"type":"string","enum":["web","high"],"default":"web","description":"web = typical web quality (SSIM 0.95); high = near-lossless (SSIM 0.98)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Tool result: `data` (structured) and `text` (human-readable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments."},"429":{"description":"Rate limited (120 requests per minute per IP)."}}}},"/v1/tools/qr_code":{"post":{"operationId":"qr_code","summary":"Generate a QR code (SVG)","description":"Encode text or a URL as a QR code and return a crisp, dependency-free SVG you can paste straight into a page, deck or doc.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":2000,"description":"Text or URL to encode."},"ecc":{"type":"string","enum":["L","M","Q","H"],"default":"M","description":"Error-correction level: L=7%, M=15%, Q=25%, H=30% recoverable."},"size":{"type":"integer","minimum":64,"maximum":1024,"default":320,"description":"SVG pixel size."}},"required":["text"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool result: `data` (structured) and `text` (human-readable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments."},"429":{"description":"Rate limited (120 requests per minute per IP)."}}}},"/v1/tools/hash":{"post":{"operationId":"hash","summary":"Hash text (SHA family)","description":"Compute a cryptographic hash of text (SHA-1, SHA-256, SHA-384 or SHA-512) and return the hex digest. Use for checksums, cache keys, or verifying content. MD5 is intentionally not offered (broken, and unavailable in Web Crypto). LLMs cannot compute these reliably by hand, so always use this tool instead of guessing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"string","minLength":1,"maxLength":100000,"description":"Text to hash (UTF-8)."},"algorithm":{"type":"string","enum":["sha-256","sha-1","sha-384","sha-512"],"default":"sha-256","description":"Hash algorithm. Default sha-256."}},"required":["input"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool result: `data` (structured) and `text` (human-readable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments."},"429":{"description":"Rate limited (120 requests per minute per IP)."}}}},"/v1/tools/uuid":{"post":{"operationId":"uuid","summary":"Generate UUIDs","description":"Generate one or more UUIDs. v4 is fully random; v7 is time-sortable (recommended for database keys). LLMs cannot produce cryptographically random or correctly-formatted UUIDs, so always use this tool.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","enum":["v4","v7"],"default":"v4","description":"UUID version. v7 = time-ordered."},"count":{"type":"integer","minimum":1,"maximum":100,"default":1,"description":"How many to generate."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Tool result: `data` (structured) and `text` (human-readable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments."},"429":{"description":"Rate limited (120 requests per minute per IP)."}}}},"/v1/tools/base64":{"post":{"operationId":"base64","summary":"Base64 encode / decode","description":"Encode text to Base64 or decode Base64 back to text (UTF-8 safe). Supports URL-safe alphabet. Use whenever you need to encode/decode data URIs, tokens, or config values instead of guessing the bytes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"string","minLength":1,"maxLength":100000,"description":"Text to encode, or Base64 to decode."},"mode":{"type":"string","enum":["encode","decode"],"default":"encode","description":"Direction."},"url_safe":{"type":"boolean","default":false,"description":"Use URL-safe alphabet (-_ instead of +/, no padding)."}},"required":["input"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool result: `data` (structured) and `text` (human-readable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments."},"429":{"description":"Rate limited (120 requests per minute per IP)."}}}},"/v1/tools/json_format":{"post":{"operationId":"json_format","summary":"Format / validate JSON","description":"Validate JSON and pretty-print or minify it, optionally sorting object keys. Returns a precise parse error (with position) if invalid. Use to check and clean JSON instead of eyeballing it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"string","minLength":1,"maxLength":100000,"description":"JSON text."},"mode":{"type":"string","enum":["pretty","minify"],"default":"pretty","description":"pretty = 2-space indent; minify = single line."},"sort_keys":{"type":"boolean","default":false,"description":"Sort object keys alphabetically (deep)."}},"required":["input"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool result: `data` (structured) and `text` (human-readable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments."},"429":{"description":"Rate limited (120 requests per minute per IP)."}}}},"/v1/tools/jwt_decode":{"post":{"operationId":"jwt_decode","summary":"Decode a JWT (no verification)","description":"Decode a JSON Web Token into its header and payload so you can inspect claims (iss, exp, sub, scopes). The signature is NOT verified and no secret is required or stored. Use to read a token during debugging.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","minLength":1,"maxLength":100000,"description":"The JWT (three dot-separated segments)."}},"required":["token"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool result: `data` (structured) and `text` (human-readable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments."},"429":{"description":"Rate limited (120 requests per minute per IP)."}}}},"/v1/tools/color":{"post":{"operationId":"color","summary":"Convert a color between formats","description":"Convert a color (hex, rgb() or hsl()) and return hex, RGB and HSL representations at once. Use when picking or translating colors for CSS, design tokens or themes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":64,"description":"A color: \"#3b82f6\", \"rgb(59,130,246)\" or \"hsl(217,91%,60%)\"."}},"required":["value"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool result: `data` (structured) and `text` (human-readable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments."},"429":{"description":"Rate limited (120 requests per minute per IP)."}}}},"/v1/tools/slugify":{"post":{"operationId":"slugify","summary":"Slugify text for URLs","description":"Turn a title or phrase into a clean, URL-safe slug (lowercase, hyphenated, accents stripped). Use when generating page paths, filenames or anchor IDs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"string","minLength":1,"maxLength":2000,"description":"Text to slugify."},"separator":{"type":"string","enum":["-","_"],"default":"-","description":"Word separator."}},"required":["input"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool result: `data` (structured) and `text` (human-readable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments."},"429":{"description":"Rate limited (120 requests per minute per IP)."}}}},"/v1/tools/count":{"post":{"operationId":"count","summary":"Count characters, words, lines, bytes","description":"Accurately count characters (Unicode code points), UTF-16 units, words, lines and UTF-8 bytes in text. LLMs are notoriously bad at counting, so always use this tool for \"how many characters/words\" questions.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"string","minLength":0,"maxLength":100000,"description":"Text to measure."}},"required":["input"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool result: `data` (structured) and `text` (human-readable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments."},"429":{"description":"Rate limited (120 requests per minute per IP)."}}}},"/v1/tools/regex_test":{"post":{"operationId":"regex_test","summary":"Test a regular expression","description":"Test a JavaScript regular expression against sample text and return whether it matches, plus every match with its captured groups and index. Use to verify a pattern instead of reasoning about it in your head. Input and pattern are length-capped to keep it fast and safe.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pattern":{"type":"string","minLength":1,"maxLength":1000,"description":"The regex pattern (without slashes)."},"input":{"type":"string","minLength":0,"maxLength":20000,"description":"Text to test against."},"flags":{"type":"string","maxLength":8,"default":"g","description":"Regex flags, e.g. \"gi\". Allowed: g i m s u y d."}},"required":["pattern","input"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool result: `data` (structured) and `text` (human-readable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments."},"429":{"description":"Rate limited (120 requests per minute per IP)."}}}},"/v1/tools/cron_describe":{"post":{"operationId":"cron_describe","summary":"Explain a cron expression","description":"Parse a standard 5-field cron expression (minute hour day-of-month month day-of-week) into a plain-English breakdown and the next few run times in UTC. Use to sanity-check a schedule instead of guessing what the fields mean.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expression":{"type":"string","minLength":1,"maxLength":200,"description":"A 5-field cron expression, e.g. \"30 2 * * 1-5\"."}},"required":["expression"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool result: `data` (structured) and `text` (human-readable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments."},"429":{"description":"Rate limited (120 requests per minute per IP)."}}}},"/v1/tools/unit_convert":{"post":{"operationId":"unit_convert","summary":"Convert between units","description":"Convert a value between units of length, mass, data size, time, speed or temperature. Supported units: mm, cm, m, km, in, ft, yd, mi, nmi, mg, g, kg, t, oz, lb, st, bit, byte, kb, kib, mb, mib, gb, gib, tb, tib, ms, s, min, h, day, week, mps, kph, mph, fps, knot, c, f, k. Use for exact conversions instead of approximating.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"number","description":"The numeric value to convert."},"from":{"type":"string","minLength":1,"maxLength":8,"description":"Source unit (e.g. \"km\", \"lb\", \"mib\", \"c\")."},"to":{"type":"string","minLength":1,"maxLength":8,"description":"Target unit (must be the same category as \"from\")."}},"required":["value","from","to"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool result: `data` (structured) and `text` (human-readable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments."},"429":{"description":"Rate limited (120 requests per minute per IP)."}}}},"/v1/tools/datetime":{"post":{"operationId":"datetime","summary":"Current or parsed date/time","description":"Get the current date/time, or convert a given timestamp, into a target IANA timezone with ISO, Unix and human-readable forms. Pass a Unix timestamp (seconds or ms) or an ISO string as input; omit it for \"now\". LLMs cannot know the real current time, so use this instead of guessing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"string","maxLength":64,"description":"Optional: a Unix timestamp (s or ms) or ISO date string. Omit for the current time."},"timezone":{"type":"string","maxLength":64,"default":"UTC","description":"IANA timezone, e.g. \"America/New_York\" or \"UTC\"."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Tool result: `data` (structured) and `text` (human-readable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments."},"429":{"description":"Rate limited (120 requests per minute per IP)."}}}},"/v1/tools/url_parse":{"post":{"operationId":"url_parse","summary":"Parse a URL into parts","description":"Break a URL into its components: scheme, host, port, path, decoded query parameters and fragment. Use to inspect or debug a URL instead of parsing it by eye.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":4000,"description":"The URL to parse (absolute, with scheme)."}},"required":["url"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool result: `data` (structured) and `text` (human-readable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments."},"429":{"description":"Rate limited (120 requests per minute per IP)."}}}},"/v1/tools/base_convert":{"post":{"operationId":"base_convert","summary":"Convert a number between bases","description":"Convert an integer between number bases 2–36 (e.g. hex to binary, decimal to base-36). Arbitrary precision via BigInt, so large values stay exact. Use for radix conversions instead of doing them by hand.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":2000,"description":"The number, in from_base (e.g. \"ff\", \"1010\", \"255\")."},"from_base":{"type":"integer","minimum":2,"maximum":36,"default":10,"description":"Base of the input (2–36)."},"to_base":{"type":"integer","minimum":2,"maximum":36,"default":16,"description":"Base to convert to (2–36)."}},"required":["value"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool result: `data` (structured) and `text` (human-readable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments."},"429":{"description":"Rate limited (120 requests per minute per IP)."}}}},"/v1/tools/diff":{"post":{"operationId":"diff","summary":"Line diff between two texts","description":"Compute a line-by-line diff between two texts, marking removed lines with \"-\", added with \"+\" and unchanged with two spaces, plus a change count. Use to see exactly what changed instead of comparing by eye. Capped at 1000 lines per side.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"a":{"type":"string","minLength":0,"maxLength":100000,"description":"The original (\"before\") text."},"b":{"type":"string","minLength":0,"maxLength":100000,"description":"The updated (\"after\") text."}},"required":["a","b"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool result: `data` (structured) and `text` (human-readable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments."},"429":{"description":"Rate limited (120 requests per minute per IP)."}}}},"/v1/tools/hmac":{"post":{"operationId":"hmac","summary":"HMAC signature of a message","description":"Compute an HMAC (keyed hash) of a message with a secret, using SHA-1/256/384/512, returned as hex or Base64. Use to sign webhook payloads or verify a signature instead of guessing. LLMs cannot compute this by hand.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","minLength":0,"maxLength":100000,"description":"The message to sign (UTF-8)."},"secret":{"type":"string","minLength":1,"maxLength":4096,"description":"The shared secret key (UTF-8)."},"algorithm":{"type":"string","enum":["sha-256","sha-1","sha-384","sha-512"],"default":"sha-256","description":"Hash algorithm."},"encoding":{"type":"string","enum":["hex","base64"],"default":"hex","description":"Output encoding."}},"required":["message","secret"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool result: `data` (structured) and `text` (human-readable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments."},"429":{"description":"Rate limited (120 requests per minute per IP)."}}}},"/v1/tools/placeholder_image":{"post":{"operationId":"placeholder_image","summary":"Generate a placeholder image (SVG)","description":"Generate a lightweight SVG placeholder image at any size, with an optional label and custom background/text colors. Dependency-free, pastes straight into a page or mockup. Use for wireframes and design stubs instead of hotlinking a placeholder service.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"width":{"type":"integer","minimum":1,"maximum":4000,"default":600,"description":"Width in pixels."},"height":{"type":"integer","minimum":1,"maximum":4000,"default":400,"description":"Height in pixels."},"bg":{"type":"string","maxLength":32,"default":"#e5e7eb","description":"Background color (hex, rgb() or hsl())."},"color":{"type":"string","maxLength":32,"default":"#6b7280","description":"Text color."},"text":{"type":"string","maxLength":120,"description":"Label text. Defaults to the dimensions, e.g. \"600×400\"."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Tool result: `data` (structured) and `text` (human-readable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments."},"429":{"description":"Rate limited (120 requests per minute per IP)."}}}},"/v1/tools/color_palette":{"post":{"operationId":"color_palette","summary":"Generate a color palette","description":"Build a harmonious color palette from a base color using color-theory rules (complementary, analogous, triadic, tetradic, or monochromatic). Returns each color as hex and HSL. Use to derive a theme or design tokens from one brand color.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"color":{"type":"string","minLength":1,"maxLength":64,"description":"Base color: \"#3b82f6\", \"rgb(...)\" or \"hsl(...)\"."},"harmony":{"type":"string","enum":["complementary","analogous","triadic","tetradic","monochromatic"],"default":"analogous","description":"Color-harmony rule."}},"required":["color"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool result: `data` (structured) and `text` (human-readable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"Invalid arguments."},"429":{"description":"Rate limited (120 requests per minute per IP)."}}}}},"components":{"schemas":{"ToolResult":{"type":"object","properties":{"ok":{"type":"boolean"},"tool":{"type":"string"},"data":{"type":["object","null"]},"text":{"type":"string"},"attribution":{"type":"string"}}}}}}