Cleanor Research Labs Tools API

openapi: 3.2.0
info:
  title: Cleanor Tools 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
tags:
- name: Tools
paths:
  /v1/tools:
    get:
      operationId: listTools
      summary: List tools with input schemas
      responses:
        '200':
          description: Tool list.
      tags:
      - Tools
  /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).
      tags:
      - Tools
  /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).
      tags:
      - Tools
  /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).
      tags:
      - Tools
  /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).
      tags:
      - Tools
  /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).
      tags:
      - Tools
  /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).
      tags:
      - Tools
  /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).
      tags:
      - Tools
  /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).
      tags:
      - Tools
  /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).
      tags:
      - Tools
  /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).
      tags:
      - Tools
  /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).
      tags:
      - Tools
  /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).
      tags:
      - Tools
  /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).
      tags:
      - Tools
  /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).
      tags:
      - Tools
  /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).
      tags:
      - Tools
  /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).
      tags:
      - Tools
  /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).
      tags:
      - Tools
  /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).
      tags:
      - Tools
  /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).
      tags:
      - Tools
  /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).
      tags:
      - Tools
  /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).
      tags:
      - Tools
components:
  schemas:
    ToolResult:
      type: object
      properties:
        ok:
          type: boolean
        tool:
          type: string
        data:
          type:
          - object
          - 'null'
        text:
          type: string
        attribution:
          type: string