TheColorAPI

Free colour API with no key: convert between hex, RGB, HSL, CMYK and XYZ, get human colour names, contrast values and generate colour schemes. Tested.

No API key requiredCORS enabledHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-20

What is the TheColorAPI?

TheColorAPI is a free, key-free API that converts colours between hex, RGB, HSL, HSV, CMYK and XYZ, returns a human-readable colour name, computes contrast text colour, and generates colour schemes from a base colour.

Colour conversion is easy to get subtly wrong, and naming is genuinely hard — mapping an arbitrary hex value to 'Cobalt' requires a reference set and a nearest-match algorithm. This API does both plus scheme generation.

The `contrast` field is quietly the most useful for real interface work: it returns whether black or white text will be readable on that colour, which saves implementing WCAG luminance calculations yourself.

Quick facts

Base URL: https://www.thecolorapi.com
Authentication: No API key required.
Rate limit: No published limit; fair use expected.
Pricing: Free.
CORS: Enabled — callable directly from browser JavaScript
Official docs: Read the docs

How to use the TheColorAPI

Every request below was executed against the live API on 2026-08-20, and the response shown is the real body it returned — not an illustration.

1. Convert and name a colour

GET https://www.thecolorapi.com/id?hex=0047AB

curl

curl 'https://www.thecolorapi.com/id?hex=0047AB'

JavaScript (fetch)

const res = await fetch("https://www.thecolorapi.com/id?hex=0047AB");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);

Python (requests)

import requests

res = requests.get("https://www.thecolorapi.com/id?hex=0047AB", timeout=20)
res.raise_for_status()
print(res.json())

Response — HTTP 200

{
  "hex": {
    "value": "#0047AB",
    "clean": "0047AB"
  },
  "rgb": {
    "fraction": {
      "r": 0,
      "g": 0.2784313725490196,
      "b": 0.6705882352941176
    },
    "r": 0,
    "g": 71,
    "b": 171,
    "value": "rgb(0, 71, 171)"
  },
  "hsl": {
    "fraction": {
      "h": 0.5974658869395711,
      "s": 1,
      "l": 0.3352941176470588
    },
    "h": 215,
    "s": 100,
    "l": 34,
    "value": "hsl(215, 100%, 34%)"
  },
  "hsv": {
    "fraction": {
      "h": 0.5974658869395711,
      "s": 1,
      "v": 0.6705882352941176
    },
    "value": "hsv(215, 100%, 67%)",
    "h": 215,
    "s": 100,
    "v": 67
  },
  "name": {
    "value": "Cobalt",
    "closest_named_hex": "#0047AB",
    "exact_match_name": true,
    "distance": 0
  },
  "cmyk": {
    "fraction": {
      "c": 1,
      "m": 0.5847953216374269,
      "y": 0,
      "k": 0.3294117647058824
    },
    "value": "cmyk(100, 58, 0, 33)",
    "c": 100,
    "m": 58,
    "y": 0,
    "k": 33
  },
  "XYZ": {
    "fraction": {
      "X": 0.22060823529411763,
      "Y": 0.2475505882352941,
      "Z": 0.6705831372549019
    },
    "value": "XYZ(22, 25, 67)",
    "X": 22,
    "Y": 25,
    "Z": 67
  },
  "image": {
    "bare": "https://www.thecolorapi.com/id?format=svg&named=false&hex=0047AB",
    "named": "https://www.thecolorapi.com/id?format=svg&hex=0047AB"
  },
  "contrast": {
    "value": "#ffffff"
  },
  "_links": {
    "self": {
      "href": "/id?hex=0047AB"
    }
  },
  "_embedded": {}
}

Parameters

Parameter	Type	Required	Description
`id`	path	Optional	Identify and convert a single colour. `id?hex=0047AB`
`hex / rgb / hsl / cmyk`	string	Optional	Input colour in any supported format. `hex=0047AB`
`scheme`	path	Optional	Generate a colour scheme from a base colour. `scheme?hex=0047AB&mode=triad`
`mode`	string	Optional	monochrome, analogic, complement, triad, quad. `triad`
`count`	integer	Optional	How many colours in the scheme. `5`
`format`	string	Optional	json, html or svg. `json`

Response fields

hex.value / hex.cleanstring: Hex with and without the leading hash.
rgb / hsl / hsv / cmyk / XYZobject: The same colour in every supported model.
name.valuestring: Closest human-readable colour name.
name.exact_match_nameboolean: Whether the name is exact or nearest.
contrast.valuestring: #000000 or #ffffff — which text colour is readable on it.
image.bare / image.namedstring: Swatch image URLs.

What you can build with the TheColorAPI

Convert colours between formats in a design tool
Show human-readable colour names in a palette picker
Pick readable text colour automatically for any background
Generate harmonious colour schemes from a brand colour

Common errors and how to fix them

Unexpected colour name

Names are nearest-match from a reference set.

Fix: Check name.exact_match_name — a false value means it is an approximation.

Hash in the hex parameter

Pass hex without the leading #.

Fix: Use hex=0047AB rather than hex=%230047AB.

Scheme count ignored

Some modes have a natural fixed size.

Fix: monochrome respects count; triad and quad are inherently 3 and 4.

TheColorAPI — frequently asked questions

Is TheColorAPI free?

Yes, completely free with no API key or registration.

What formats can it convert between?

Hex, RGB, HSL, HSV, CMYK and XYZ, all returned together in a single response so you do not need to request each.

What is the contrast field for?

It tells you whether black or white text will be readable on that colour, based on luminance — which saves implementing WCAG contrast calculations yourself.

Are the colour names accurate?

They are nearest matches from a reference set. Check name.exact_match_name to know whether the name is exact or approximate.

Tools that pair with this API

Color Picker

Pick any color and get its HEX, RGB and HSL values instantly. Free online color picker with shades, tints and one-click copy for designers and developers.

HEX to RGB Converter

Convert HEX color codes to RGB and RGBA instantly. Supports 3, 6 and 8-digit HEX with a live color swatch, batch list conversion and one-click copy.

RGB to HEX Converter

Convert RGB or RGBA values to HEX color codes instantly. Enter channels manually or paste an rgb() string, preview the swatch and copy the HEX result.

TheColorAPI is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-20; always check the official documentation before relying on this API in production, as terms and limits can change.