Developer Documentation

Integrate ColorFYI data into your applications. Access color conversions, contrast ratios, harmonies, 809 named colors, and more through our JSON APIs, packages, and machine-readable endpoints.

Miễn phí Không cần xác thực JSON CORS

API Endpoints

All endpoints return JSON with Content-Type: application/json. No authentication required. CORS enabled for browser requests.

URL cơ sở https://colorfyi.com/api/

Endpoint	Description	Cache
`GET /api/color/{hex}/`	Full color info: RGB, HSL, HSV, CMYK, OKLCH, harmonies, shades	—
`GET /api/contrast/?fg=&bg=`	WCAG contrast ratio with AA/AAA compliance	—
`GET /api/search/?q=`	Search across colors, brands, blog, glossary, collections	—
`GET /api/harmonies/{hex}/`	Color harmonies: complementary, analogous, triadic, tetradic	—
`GET /api/shades/{hex}/`	Tailwind-style shade scale (50-950)	—
`GET /api/blindness/{hex}/`	Color blindness simulation (4 types)	—
`GET /api/compare/?hex1=&hex2=`	Compare two colors: contrast, Delta E, gradient, mix	—
`GET /api/mix/?hex1=&hex2=&ratio=`	Mix two colors in Lab space at a given ratio	—
`GET /api/gradient/?hex1=&hex2=&steps=`	Lab-interpolated gradient between two colors	—
`GET /api/palette/{hex}/?type=&count=`	Generate palette: monochromatic, shades, analogous, triadic, etc.	—
`GET /api/named-colors/?source=&limit=`	List 809 named colors, filterable by source	—
`GET /api/graph/`	Knowledge graph nodes/edges (terms, posts, brands, tools)	—
`GET /api/openapi.json`	OpenAPI 3.1.0 specification (CORS enabled)	—

Thông tin màu sắc

Lấy thông tin màu sắc đầy đủ bao gồm RGB, HSL, HSV, CMYK, OKLCH, hòa âm và sắc độ Tailwind.

GET /api/color/{hex}/

curl https://colorfyi.com/api/color/FF5733/

Show response

{
  "hex": "FF5733",
  "rgb": {"r": 255, "g": 87, "b": 51},
  "hsl": {"h": 11, "s": 100, "l": 60},
  "hsv": {"h": 11, "s": 80, "v": 100},
  "cmyk": {"c": 0, "m": 66, "y": 80, "k": 0},
  "oklch": {"l": 0.67, "c": 0.21, "h": 35},
  "is_light": true,
  "is_warm": true,
  "text_color": "#FFFFFF",
  "harmonies": {
    "complementary": ["33D7FF"],
    "analogous": ["FF3357", "FF8C33"],
    "triadic": ["33FF57", "5733FF"],
    "split_complementary": ["33FFDA", "3357FF"],
    "tetradic": ["33FF57", "33D7FF", "5733FF"]
  },
  "shades": [
    {"level": "50", "hex": "FFF0ED"},
    {"level": "100", "hex": "FFD6CC"},
    {"level": "500", "hex": "FF5733"},
    {"level": "900", "hex": "7A1800"}
  ]
}

Tỷ lệ tương phản

Calculate WCAG contrast ratio between two colors with AA/AAA compliance checks.

GET /api/contrast/?fg={hex}&bg={hex}

curl "https://colorfyi.com/api/contrast/?fg=000000&bg=FFFFFF"

{
  "fg": "000000",
  "bg": "FFFFFF",
  "ratio": 21.0,
  "aa_normal": true,
  "aa_large": true,
  "aaa_normal": true,
  "aaa_large": true
}

Tìm kiếm

Search across named colors, brands, blog posts, glossary terms, and collections. Returns top 15 matches.

GET /api/search/?q={query}

curl "https://colorfyi.com/api/search/?q=coral"

{
  "results": [
    {"name": "Coral", "hex": "FF7F50", "type": "color", "url": "/color/coral/"},
    {"name": "Light Coral", "hex": "F08080", "type": "color", "url": "/color/light-coral/"}
  ]
}

Mô phỏng mù màu

Simulate how a color appears under four types of color vision deficiency.

GET /api/blindness/{hex}/

curl https://colorfyi.com/api/blindness/3B82F6/

{
  "original": "3B82F6",
  "protanopia": "4D6FE8",
  "deuteranopia": "5C6CF0",
  "tritanopia": "2B8EBC",
  "achromatopsia": "808080"
}

Compare Colors

Compare two colors: contrast ratio, Delta E perceptual difference, gradient steps, and mixed result.

GET /api/compare/?hex1={hex}&hex2={hex}

curl "https://colorfyi.com/api/compare/?hex1=FF5733&hex2=3B82F6"

Show response

{
  "color1": {
    "hex": "FF5733", "rgb": {"r": 255, "g": 87, "b": 51},
    "hsl": {"h": 11, "s": 100, "l": 60}, "is_light": true, "is_warm": true
  },
  "color2": {
    "hex": "3B82F6", "rgb": {"r": 59, "g": 130, "b": 246},
    "hsl": {"h": 217, "s": 91, "l": 60}, "is_light": false, "is_warm": false
  },
  "contrast": {
    "ratio": 2.14, "aa_normal": false, "aa_large": false,
    "aaa_normal": false, "aaa_large": false
  },
  "delta_e": 72.3,
  "delta_e_category": "Very different",
  "gradient": ["FF5733", "D0604B", "A16863", "72707B", "437993", "3B82F6"],
  "mixed": "9D6D95"
}

Gradient

Generate a Lab-interpolated gradient between two colors with configurable steps (2-20).

GET /api/gradient/?hex1={hex}&hex2={hex}&steps={n}

curl "https://colorfyi.com/api/gradient/?hex1=FF0000&hex2=0000FF&steps=5"

{
  "hex1": "FF0000",
  "hex2": "0000FF",
  "steps": ["FF0000", "CC2266", "8844AA", "4422CC", "0000FF"]
}

Màu sắc có tên

List 809 named colors from CSS, X11, Crayola, Pantone, RAL, and NCS. Filter by source.

GET /api/named-colors/?source={source}&limit={n}

curl "https://colorfyi.com/api/named-colors/?source=css&limit=3"

Show response

{
  "colors": [
    {"name": "AliceBlue", "hex": "F0F8FF", "slug": "aliceblue", "source": "css", "url": "/color/aliceblue/"},
    {"name": "AntiqueWhite", "hex": "FAEBD7", "slug": "antiquewhite", "source": "css", "url": "/color/antiquewhite/"},
    {"name": "Aqua", "hex": "00FFFF", "slug": "aqua", "source": "css", "url": "/color/aqua/"}
  ],
  "sources": [
    {"value": "css", "label": "CSS", "count": 148},
    {"value": "x11", "label": "X11", "count": 140},
    {"value": "crayola", "label": "Crayola", "count": 120}
  ],
  "total": 148
}

AI / LLM Integration

ColorFYI provides machine-readable content summaries following the llms.txt standard, plus Markdown endpoints for every page.

/llms.txt text/plain

A concise summary of ColorFYI's content structure and key pages. Designed for AI models to quickly understand what the site offers and how it is organized.

# ColorFYI.com

> Color knowledge platform — 16.7M hex colors, 809 named colors,
  544 brands, and color tools in 15 languages.

## Browse
- [Colors](https://colorfyi.com/) — 16.7M colors computed on-the-fly
- [Named Colors](https://colorfyi.com/color/named/) — 809 named colors
  ...

/llms-full.txt text/plain

Extended version with complete URL patterns, i18n language codes, and page-level structure. Use this for deeper indexing and cross-referencing.

*.md endpoints text/markdown

Every page has a Markdown equivalent. Append .md to any URL for a machine-readable version optimized for AI consumption.

# Examples
curl https://colorfyi.com/index.md              # Homepage
curl https://colorfyi.com/color/coral.md        # Named color detail
curl https://colorfyi.com/brands.md             # All brands
curl https://colorfyi.com/glossary.md           # Glossary index
curl https://colorfyi.com/blog.md               # Blog list
curl https://colorfyi.com/tools.md              # Tools index

AI Crawler Policy: Our robots.txt explicitly allows GPTBot, ClaudeBot, and Google-Extended crawlers.

SEO & Standards

Standard endpoints for search engines, crawlers, and security researchers.

Endpoint	Standard	Description
/sitemap.xml	Sitemaps 0.9	Sitemap index with 15 per-section sitemaps covering all content types
/robots.txt	REP	Crawler directives with explicit AI bot permissions
/.well-known/security.txt	RFC 9116	Security vulnerability reporting contact information
/llms.txt	llms.txt	AI-optimized site summary for language models

Structured Data

Every page includes JSON-LD structured data for rich search results:

WebSite — with SearchAction for sitelinks search box
BreadcrumbList — navigation breadcrumbs on all pages
Article — blog posts with author, dates, and word count
DefinedTerm — glossary terms with definitions
WebApplication — interactive tools with free pricing
CollectionPage — index/browse pages

Internationalization

All content pages include hreflang alternate links for 15 languages: English (default), Korean, Japanese, Chinese (Simplified), Spanish, French, German, Portuguese, Russian, Arabic, Hindi, Thai, Vietnamese, Indonesian, and Turkish.

OpenAPI Specification

A machine-readable OpenAPI 3.1 specification is available for all JSON API endpoints. Use it with Swagger UI, Postman, or code generators.

Download openapi.json

Fetch via command line

# Download the OpenAPI spec
curl "https://colorfyi.com/api/openapi.json" -o openapi.json

# Pretty-print
curl -s "https://colorfyi.com/api/openapi.json" | python -m json.tool

Rate Limits & Usage

Our APIs are free to use with no authentication required. To ensure fair access for everyone, please follow these guidelines:

Keep requests under 60 requests per minute per IP address
Include a descriptive User-Agent header identifying your application
Cache responses locally when possible
For bulk data access, use the named-colors API or the sitemap to discover all URLs

If you need higher-volume access or have integration questions, reach out via the contact in our security.txt.

Python Package

Pure Python color engine with zero dependencies. Available on PyPI.

Install

pip install colorfyi                # Core engine (zero deps)
pip install "colorfyi[cli]"         # + CLI
pip install "colorfyi[mcp]"         # + MCP server
pip install "colorfyi[all]"         # Everything

Ví dụ

from colorfyi import color_info, contrast_ratio, harmonies

c = color_info("3B82F6")
print(c.rgb)        # (59, 130, 246)
print(c.hsl)        # (217.2, 91.2, 59.8)
print(c.wcag_white) # 3.44

ratio = contrast_ratio("000000", "FFFFFF")  # 21.0
h = harmonies("FF6B35")                     # complementary, triadic, ...

PyPI · GitHub

npm Package

Color engine for JavaScript and TypeScript. Zero dependencies, tree-shakeable ESM. Available on npm.

Install

npm install @fyipedia/colorfyi

Ví dụ

import { getColorInfo, contrastRatio, harmonies } from "@fyipedia/colorfyi";

const info = getColorInfo("3B82F6");          // Full color info
const cr = contrastRatio("000000", "FFFFFF"); // 21.0
const h = harmonies("FF6B35");               // complementary, triadic, ...

@fyipedia/colorfyi npm demo — Node.js REPL with color conversion and WCAG contrast

npm · GitHub

Command-Line Interface

Color tools in your terminal. Rich tables and formatted output.

Install & Use

pip install "colorfyi[cli]"

colorfyi info FF6B35          # Full color info
colorfyi contrast 000000 FFFFFF  # WCAG contrast check
colorfyi harmonies FF6B35     # Color harmonies
colorfyi shades 3B82F6        # Tailwind-style shades

ColorFYI CLI demo showing color info, contrast check, and harmonies output

MCP Server

Add color tools to AI assistants via Model Context Protocol.

Install

pip install "colorfyi[mcp]"

claude_desktop_config.json

{
  "mcpServers": {
    "colorfyi": {
      "command": "python",
      "args": ["-m", "colorfyi.mcp_server"]
    }
  }
}

Available tools

color_info contrast_check color_harmonies color_shades simulate_color_blindness mix_colors compare_colors gradient text_color_for_background

VSCode Extension

Inline color swatches, hover info, WCAG contrast checks, Tailwind palettes, and color blindness simulation right in your editor.

Install

# Via VS Code Marketplace
ext install fyipedia.colorfyi

# Or via command line
code --install-extension fyipedia.colorfyi

VS Code Marketplace · GitHub

Quick Reference

Thông tin màu sắc /api/color/{hex}/

Tỷ lệ tương phản /api/contrast/?fg=&bg=

Tìm kiếm /api/search/?q=...

Harmonies /api/harmonies/{hex}/

Shades /api/shades/{hex}/

Color Blindness /api/blindness/{hex}/

So sánh /api/compare/?hex1=&hex2=

Mix /api/mix/?hex1=&hex2=

Gradient /api/gradient/?hex1=&hex2=

Palette /api/palette/{hex}/

Màu sắc có tên /api/named-colors/

Đồ thị kiến thức /api/graph/

OpenAPI Spec /api/openapi.json

llms.txt /llms.txt

Python pip install colorfyi

npm npm i @fyipedia/colorfyi