Free color API

Parse, convert, check contrast, build scales and palettes, simulate color blindness and export design tokens over plain HTTP. No key, no sign-up, JSON in and out.

No API key and no sign-up
GET with query parameters or POST with JSON
CORS enabled, call it from any site
Same math as the site: CSS Color 4

OpenAPI 3.1 spec Using an AI assistant? Connect the MCP server instead

Endpoints

Describe a color
GET, POST /api/v1/parse-color
Read any color and describe it: HEX, RGB, HSL and OKLCH values, the closest human name, the closest Tailwind class, its hue family, whether it fits sRGB and Display P3, and which text color, white or black, reads better on it.
Try it: /api/v1/parse-color?color=oklch%2862%25+0.21+260%29
POST body
```
curl -X POST https://pickshade.com/api/v1/parse-color \
  -H 'Content-Type: application/json' \
  -d '{"color":"oklch(62% 0.21 260)"}'
```
Convert a color
GET, POST /api/v1/convert-color
Convert a color between formats: hex, rgb, hsl, hsv, hwb, cmyk, lab, lch, oklab, oklch, display-p3, rec2020, xyz and platform code (swiftui, uikit, flutter, android). Values follow CSS Color 4.
Try it: /api/v1/convert-color?color=%23ff5733&formats=oklch%2Chsl%2Ccmyk
POST body
```
curl -X POST https://pickshade.com/api/v1/convert-color \
  -H 'Content-Type: application/json' \
  -d '{"color":"#ff5733","formats":["oklch","hsl","cmyk"]}'
```
Check text contrast
GET, POST /api/v1/check-contrast
Check text contrast against a background with both WCAG 2 (ratio, AA and AAA for normal and large text) and APCA (Lc value and the usage level it allows). Also suggests the nearest text color that passes AA and AAA while keeping its hue.
Try it: /api/v1/check-contrast?text=%236b7280&background=%23ffffff
POST body
```
curl -X POST https://pickshade.com/api/v1/check-contrast \
  -H 'Content-Type: application/json' \
  -d '{"text":"#6b7280","background":"#ffffff"}'
```
Check gamut
GET, POST /api/v1/check-gamut
Check whether a color fits the sRGB, Display P3 and Rec. 2020 gamuts, and get the closest sRGB fallback that keeps lightness and hue (CSS Color 4 gamut mapping in OKLCH).
Try it: /api/v1/check-gamut?color=oklch%2870%25+0.3+145%29
POST body
```
curl -X POST https://pickshade.com/api/v1/check-gamut \
  -H 'Content-Type: application/json' \
  -d '{"color":"oklch(70% 0.3 145)"}'
```
Find color names
GET, POST /api/v1/nearest-names
Find the closest named colors, CSS color keywords and Tailwind CSS classes for a color, ranked by perceptual distance (deltaE OK).
Try it: /api/v1/nearest-names?color=%231e3a8a&limit=3
POST body
```
curl -X POST https://pickshade.com/api/v1/nearest-names \
  -H 'Content-Type: application/json' \
  -d '{"color":"#1e3a8a","limit":3}'
```
Compare two colors
GET, POST /api/v1/compare-colors
Compare two colors: CIEDE2000 and deltaE OK difference with a plain verdict (identical, nearly, similar, different, opposite), lightness shift in percent, chroma and hue shift, and the contrast between them.
Try it: /api/v1/compare-colors?first=teal&second=turquoise
POST body
```
curl -X POST https://pickshade.com/api/v1/compare-colors \
  -H 'Content-Type: application/json' \
  -d '{"first":"teal","second":"turquoise"}'
```
Generate a 50–950 scale
GET, POST /api/v1/generate-scale
Build an 11-step tint and shade scale (50, 100 … 900, 950) from one color in OKLCH, the same shape as Tailwind palettes, with even perceived lightness steps.
Try it: /api/v1/generate-scale?color=%233b82f6
POST body
```
curl -X POST https://pickshade.com/api/v1/generate-scale \
  -H 'Content-Type: application/json' \
  -d '{"color":"#3b82f6"}'
```
Color harmonies
GET, POST /api/v1/harmonies
Get color harmonies for a base color, computed in OKLCH so lightness stays even: complementary, split-complementary, analogous, triadic, tetradic, square and monochromatic.
Try it: /api/v1/harmonies?color=%23ff5733&kind=triadic
POST body
```
curl -X POST https://pickshade.com/api/v1/harmonies \
  -H 'Content-Type: application/json' \
  -d '{"color":"#ff5733","kind":"triadic"}'
```
Mix two colors
GET, POST /api/v1/mix-colors
Mix two colors at a ratio in a chosen color space, like CSS color-mix(). OKLab keeps the middle bright, sRGB tends to turn gray. Returns the result and a ready color-mix() expression.
Try it: /api/v1/mix-colors?first=%23ff5733&second=%233b82f6&amount=30&space=oklab
POST body
```
curl -X POST https://pickshade.com/api/v1/mix-colors \
  -H 'Content-Type: application/json' \
  -d '{"first":"#ff5733","second":"#3b82f6","amount":30,"space":"oklab"}'
```
Generate a palette
GET, POST /api/v1/generate-palette
Generate a harmonious palette in OKLCH. Keep colors you already have, pick a style (auto, analogous, complementary, triadic, monochromatic, pastel, vivid, muted, dark) and pass a seed to get the same palette every time.
Try it: /api/v1/generate-palette?keep=%230f172a&mode=analogous&size=5&seed=brand
POST body
```
curl -X POST https://pickshade.com/api/v1/generate-palette \
  -H 'Content-Type: application/json' \
  -d '{"keep":["#0f172a"],"mode":"analogous","size":5,"seed":"brand"}'
```
Simulate color blindness
GET, POST /api/v1/simulate-cvd
Show how colors look with protanopia, deuteranopia, tritanopia and achromatopsia (Machado 2009 at full severity), and list the pairs that become hard to tell apart.
Try it: /api/v1/simulate-cvd?colors=%23e11d48%2C%2316a34a%2C%232563eb
POST body
```
curl -X POST https://pickshade.com/api/v1/simulate-cvd \
  -H 'Content-Type: application/json' \
  -d '{"colors":["#e11d48","#16a34a","#2563eb"]}'
```
Export colors as code
POST /api/v1/export-tokens
Turn a list of colors into ready code: CSS custom properties, a Tailwind v4 @theme block, SCSS variables, JSON, W3C design tokens (DTCG), a JavaScript array or an SVG swatch strip. Unnamed colors get their closest color name.
POST body
```
curl -X POST https://pickshade.com/api/v1/export-tokens \
  -H 'Content-Type: application/json' \
  -d '{"colors":[{"color":"#0f172a","name":"ink"},{"color":"#f97316"}],"format":"tailwind","values":"oklch"}'
```
Build a design system
GET, POST /api/v1/build-system
Build a full color system from a brand color: 50–950 scales for primary, secondary, accent, neutral and status colors, light and dark theme roles, exported as a Tailwind v4 theme, CSS variables, shadcn/ui globals.css or DTCG tokens, with a contrast audit of text and surface pairs.
Try it: /api/v1/build-system?primary=%236d4aff&format=shadcn
POST body
```
curl -X POST https://pickshade.com/api/v1/build-system \
  -H 'Content-Type: application/json' \
  -d '{"primary":"#6d4aff","format":"shadcn"}'
```

Limits

Each IP address can send about 10 requests per second with short bursts. Above that the API answers 429 with a Retry-After header. Results that never change are cached for a day, so repeat calls are instant.

Questions and answers

Do I need an API key?

No. The API is free and open. Just call the endpoints over HTTPS from your server, a script or the browser.

Which color formats does it accept?

Any CSS color: HEX, rgb(), hsl(), hwb(), lab(), lch(), oklab(), oklch() and color(display-p3 …), plus CSS names like navy, common names like royal blue and Tailwind classes like sky-500.

How are errors reported?

Errors use application/problem+json with a title and a detail that says what to fix, for example when a string cannot be read as a color.

Endpoints

Describe a color

POST body

Convert a color

POST body

Check text contrast

POST body

Check gamut

POST body

Find color names

POST body

Compare two colors

POST body

Generate a 50–950 scale

POST body

Color harmonies

POST body

Mix two colors

POST body

Generate a palette

POST body

Simulate color blindness

POST body

Export colors as code

POST body

Build a design system

POST body

Limits

Questions and answers