Convert colors between hex, RGB, and HSL with one API call

Color conversion math is the kind of code you write once, get subtly wrong, and copy between projects forever. Hex to RGB is straightforward; RGB to HSL is where the off-by-a-degree bugs live. This endpoint takes a color in any of the three formats and returns all three at once, so you stop carrying conversion functions around.

The request

curl -X POST https://api.botoi.com/v1/color/convert \
  -H "Content-Type: application/json" \
  -d '{"color": "#3EC997"}'

The response gives you the hex string, an { r, g, b } object, and an { h, s, l } object together:

{
  "data": {
    "hex": "#3EC997",
    "rgb": { "r": 62, "g": 201, "b": 151 },
    "hsl": { "h": 158, "s": 56, "l": 52 }
  }
}

Input format does not matter. Pass rgb(62, 201, 151) or an HSL string and you get the same three representations back. Hex works with or without the #:

# RGB and HSL inputs work too; you always get all three back.
curl -X POST https://api.botoi.com/v1/color/convert \
  -H "Content-Type: application/json" \
  -d '{"color": "rgb(62, 201, 151)"}'

Generate a design-token scale from one brand color

HSL is the format worth building on. Because it separates hue from lightness, you can produce a full tint-and-shade scale by holding hue and saturation steady and stepping the lightness value. Convert your brand hex to HSL once, then walk the lightness to generate the 50-to-900 scale a design system needs:

// Build a design-token file at build time from one brand color.
// Hold hue and saturation, step lightness to make a 50-900 scale.
async function toHsl(color) {
  const res = await fetch("https://api.botoi.com/v1/color/convert", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ color }),
  });
  const { data } = await res.json();
  return data.hsl; // { h, s, l }
}

const brand = await toHsl("#3EC997");
const steps = { 50: 95, 100: 90, 200: 80, 300: 68, 400: 60, 500: 52, 600: 44, 700: 35, 800: 26, 900: 17 };

const scale = {};
for (const [name, l] of Object.entries(steps)) {
  scale[name] = `hsl(${brand.h} ${brand.s}% ${l}%)`;
}
console.log(scale["500"]); // hsl(158 56% 52%)

Run that in a build step and write the output to a CSS variables file. You get a coordinated palette from a single source color, and changing the brand color regenerates the whole scale:

:root {
  /* Generated from one brand hex, expressed as HSL for easy theming */
  --brand-50:  hsl(158 56% 95%);
  --brand-500: hsl(158 56% 52%);
  --brand-900: hsl(158 56% 17%);
}

Normalize colors pasted into a CMS

Content editors paste colors in whatever format their design tool exports: a hex from Figma, an rgb() from a screenshot tool, an HSL from a CSS snippet. Run every pasted value through the endpoint on save and store the normalized hex. Your rendering code then deals with one format, and the editor keeps pasting whatever is convenient.

Where it fits

For interactive UI math in the browser, a local function is fine. The API earns its place in build steps, backends, and any language without a solid color package: a single HTTP call replaces a dependency. Color conversion is one of roughly 200 single-purpose endpoints on botoi, all behind one key with 5 req/min free.

Try the conversion in the interactive playground, browse the full API docs, or connect the MCP server to convert colors straight from Claude or Cursor.