A free color API
for every developer.

Convert any CSS color into every supported format (HEX, RGB, HSL, LCH, OKLCH, LAB).

Parameters

Example

Response

{
  "input": "#7c5cff",
  "oklch": { "l": 0.5901, "c": 0.2376, "h": 282.47 },
  "css": "oklch(59.01% 0.2376 282.47)"
}

Compute the WCAG 2.1 contrast ratio between two colors plus AA / AAA pass-fail flags.

Parameters

Example

Response

{
  "fg": "#ffffff",
  "bg": "#7c5cff",
  "ratio": 4.78,
  "wcag": {
    "aa":  { "normalText": true,  "largeText": true,  "graphics": true },
    "aaa": { "normalText": false, "largeText": true }
  },
  "grade": "AA"
}

Generate a palette from a free-text prompt (AI mode), a harmony rule, or randomly.

Parameters

Example

Response

{
  "source": "ai",
  "prompt": "Cyberpunk gaming UI",
  "colors": ["#0b0b1a", "#7c5cff", "#ff2bd6", "#06f5ff", "#fbbf24"],
  "intent": { "key": "gaming", "label": "Gaming / Esports", "rationale": "..." },
  "narratives": [/* per-color explanations */],
  "shareUrl": "https://colorui.io/p/0b0b1a7c5cffff2bd606f5fffbbf24"
}

Rate limits & headers

60 requests per IP per 60 seconds. Every response includes:

• X-RateLimit-Limit - your bucket size (always 60).
• X-RateLimit-Remaining - calls left in the current window.
• X-RateLimit-Reset - UNIX epoch (seconds) when the bucket refills.

Need higher throughput? Get in touch - we can issue a key for batch use.

Versioning & stability

Endpoints live under /api/v1/*. Breaking changes will only ship under /api/v2/* - v1 will continue to work. New optional parameters or response fields may be added at any time.

Quick example - fetch from JS

const r = await fetch(
  'https://colorui.io/api/v1/contrast?fg=%23ffffff&bg=%237c5cff'
);
const { ratio, grade } = await r.json();
console.log(ratio, grade); // 4.78 'AA'

OpenAPI 3.1 specification

The full machine-readable spec is served at /api/v1/openapi.json. Import it into your tool of choice:

• Postman / Bruno / Insomnia: File → Import →https://colorui.io/api/v1/openapi.json
• SDK generation:npx @openapitools/openapi-generator-cli generate -i https://colorui.io/api/v1/openapi.json -g typescript-fetch -o ./colorui-sdk
• Microsoft Kiota:kiota generate -d https://colorui.io/api/v1/openapi.json -l typescript -o ./colorui-sdk
• Type-safe Zod client:npx openapi-zod-client https://colorui.io/api/v1/openapi.json -o colorui-client.ts

Ready-made collections

Skip the SDK step and call the API straight from your favourite workbench. Each collection ships with the four endpoints, the right query encodings, and a `baseUrl` variable so you can point at a self-hosted deployment.

• Postman / Hoppscotch: File → Import → Link →https://colorui.io/api/v1/postman.json
• Bruno: File → Open Collection → openapi/bruno/from the repo.
• Insomnia: Preferences → Data → Import →openapi/colorui.insomnia_collection.json
• CI smoke test:npx newman run https://colorui.io/api/v1/postman.json