{
  "openapi": "3.1.0",
  "info": {
    "title": "Colors API",
    "version": "1.0.0",
    "description": "Name, convert and check contrast for any color, with 31,919 curated names and WCAG math.\n\nEverything a product does with color, in one API. 31,919 human-curated color names (the MIT color-names project, with its quality flag — nearest-name defaults to the 4,962 curated best names so #ff5733 comes back 'Orange Soda', not something unpronounceable) plus all CSS named colors with their spec keywords. Convert anything to everything: feed it hex (#ff5733, short #f53), rgb(255,87,51), bare '255,87,51' or hsl(11,100%,60%) and get hex, RGB, HSL, HSV, CMYK, WCAG relative luminance, a dark/light flag, the nearest curated name AND the nearest CSS keyword (tomato, 23.3 away). Generate named palettes — complementary, analogous, triadic, tetradic, split-complementary, monochromatic, shades, tints — with the base color preserved exactly (no HSL round-trip drift). Check WCAG accessibility: contrast ratio with AA/AAA pass-fail for normal and large text (black on white = 21). Search 32k names ('sunset' → 74 colors), filter to curated or CSS sets, or grab a random one. Design tools, theme builders, accessibility linters, data-viz libraries, e-commerce swatch naming — one token per call.",
    "contact": {
      "name": "Data and APIs",
      "url": "https://dataandapis.com/contact"
    },
    "termsOfService": "https://dataandapis.com/terms-of-service",
    "license": {
      "name": "Data and APIs Terms of Service",
      "url": "https://dataandapis.com/terms-of-service"
    },
    "x-logo": {
      "url": "https://dataandapis.com/images/colors.webp"
    }
  },
  "externalDocs": {
    "description": "Documentation, live tester and pricing",
    "url": "https://dataandapis.com/apis/colors"
  },
  "servers": [
    {
      "url": "https://api-colors.dataandapis.com"
    }
  ],
  "tags": [
    {
      "name": "Tools",
      "description": "Colors API belongs to the Tools category of the Data and APIs catalog."
    }
  ],
  "paths": {
    "/v1/colors/convert": {
      "get": {
        "operationId": "convertColor",
        "summary": "Convert Color",
        "description": "Convert Color endpoint of the Colors API. Costs 1 token per call.",
        "externalDocs": {
          "url": "https://dataandapis.com/apis/colors/convert-color"
        },
        "parameters": [
          {
            "name": "value",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "#FF5733"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "ok": true,
                  "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": 65.88,
                    "y": 80,
                    "k": 0
                  },
                  "luminance": 0.283,
                  "is_dark": false,
                  "name": {
                    "hex": "#fa5b3d",
                    "name": "Orange Soda",
                    "is_bestof": true,
                    "is_css": false,
                    "distance": 11.87,
                    "exact": false
                  },
                  "nearest_css": {
                    "hex": "#ff6347",
                    "name": "tomato",
                    "distance": 23.32
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "402": {
            "description": "Subscription past due; the response carries a payment_url"
          },
          "429": {
            "description": "Monthly token allowance exhausted"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/v1/sources": {
      "get": {
        "operationId": "dataSources",
        "summary": "Data Sources",
        "description": "Data Sources endpoint of the Colors API. Costs 1 token per call.",
        "externalDocs": {
          "url": "https://dataandapis.com/apis/colors/data-sources"
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "ok": true,
                  "sources": [
                    {
                      "slug": "color-names",
                      "name": "meodai color-names",
                      "publisher": "meodai and contributors",
                      "licence": "MIT",
                      "source_url": "https://github.com/meodai/color-names",
                      "file_url": "https://raw.githubusercontent.com/meodai/color-names/main/src/colornames.csv",
                      "cadence": "community-updated; occasional re-scrape",
                      "record_count": 31916,
                      "retrieved_at": "2026-09-06"
                    },
                    {
                      "slug": "css-colors",
                      "name": "CSS named colors",
                      "publisher": "W3C CSS Color Module",
                      "licence": "W3C spec constants",
                      "source_url": "https://www.w3.org/TR/css-color-4/#named-colors",
                      "file_url": null,
                      "cadence": "static",
                      "record_count": 139,
                      "retrieved_at": "2026-09-06"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "402": {
            "description": "Subscription past due; the response carries a payment_url"
          },
          "429": {
            "description": "Monthly token allowance exhausted"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/v1/colors/palette": {
      "get": {
        "operationId": "generatePalette",
        "summary": "Generate Palette",
        "description": "Generate Palette endpoint of the Colors API. Costs 1 token per call.",
        "externalDocs": {
          "url": "https://dataandapis.com/apis/colors/generate-palette"
        },
        "parameters": [
          {
            "name": "count",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "5"
          },
          {
            "name": "mode",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "triadic"
          },
          {
            "name": "value",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1e90ff"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "ok": true,
                  "base": "#1e90ff",
                  "mode": "triadic",
                  "palette": [
                    {
                      "hex": "#1e90ff",
                      "hsl": {
                        "h": 210,
                        "s": 100,
                        "l": 55.88
                      },
                      "name": "Pool Water"
                    },
                    {
                      "hex": "#ff1e8e",
                      "hsl": {
                        "h": 330,
                        "s": 100,
                        "l": 55.88
                      },
                      "name": "Fluorescent Pink"
                    },
                    {
                      "hex": "#8eff1e",
                      "hsl": {
                        "h": 90,
                        "s": 100,
                        "l": 55.88
                      },
                      "name": "Loud Lime"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "402": {
            "description": "Subscription past due; the response carries a payment_url"
          },
          "429": {
            "description": "Monthly token allowance exhausted"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/v1/colors/name": {
      "get": {
        "operationId": "nameAColor",
        "summary": "Name a Color",
        "description": "Name a Color endpoint of the Colors API. Costs 1 token per call.",
        "externalDocs": {
          "url": "https://dataandapis.com/apis/colors/name-a-color"
        },
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "true"
          },
          {
            "name": "count",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "3"
          },
          {
            "name": "value",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "40e0d0"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "ok": true,
                  "query": "#40e0d0",
                  "pool": "all 31,919 names",
                  "matches": [
                    {
                      "hex": "#40e0d0",
                      "name": "Fresh Turquoise",
                      "is_bestof": false,
                      "is_css": true,
                      "distance": 0,
                      "exact": true
                    },
                    {
                      "hex": "#48d1cc",
                      "name": "Medium Turquoise",
                      "is_bestof": false,
                      "is_css": true,
                      "distance": 17.46,
                      "exact": false
                    },
                    {
                      "hex": "#45e9c1",
                      "name": "Aphrodite Aqua",
                      "is_bestof": true,
                      "is_css": false,
                      "distance": 18.19,
                      "exact": false
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "402": {
            "description": "Subscription past due; the response carries a payment_url"
          },
          "429": {
            "description": "Monthly token allowance exhausted"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/v1/colors/random": {
      "get": {
        "operationId": "randomColor",
        "summary": "Random Color",
        "description": "Random Color endpoint of the Colors API. Costs 1 token per call.",
        "externalDocs": {
          "url": "https://dataandapis.com/apis/colors/random-color"
        },
        "parameters": [
          {
            "name": "bestof",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "true"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "ok": true,
                  "color": {
                    "hex": "#c27f38",
                    "name": "Ginger Beer",
                    "is_bestof": true,
                    "is_css": false,
                    "rgb": {
                      "r": 194,
                      "g": 127,
                      "b": 56
                    },
                    "hsl": {
                      "h": 31,
                      "s": 55.2,
                      "l": 49.02
                    },
                    "hsv": {
                      "h": 31,
                      "s": 71.13,
                      "v": 76.08
                    },
                    "cmyk": {
                      "c": 0,
                      "m": 34.54,
                      "y": 71.13,
                      "k": 23.92
                    },
                    "luminance": 0.269,
                    "is_dark": false
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "402": {
            "description": "Subscription past due; the response carries a payment_url"
          },
          "429": {
            "description": "Monthly token allowance exhausted"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/v1/colors": {
      "get": {
        "operationId": "searchColors",
        "summary": "Search Colors",
        "description": "Search Colors endpoint of the Colors API. Costs 1 token per call.",
        "externalDocs": {
          "url": "https://dataandapis.com/apis/colors/search-colors"
        },
        "parameters": [
          {
            "name": "bestof",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "true"
          },
          {
            "name": "css",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "sunset"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "ok": true,
                  "page": 1,
                  "limit": 25,
                  "total": 8,
                  "total_pages": 1,
                  "colors": [
                    {
                      "hex": "#dd8869",
                      "name": "Canyon Sunset",
                      "is_bestof": true,
                      "is_css": false
                    },
                    {
                      "hex": "#eb9f9f",
                      "name": "Cosy Summer Sunset",
                      "is_bestof": true,
                      "is_css": false
                    },
                    {
                      "hex": "#b52604",
                      "name": "Crimson Velvet Sunset",
                      "is_bestof": true,
                      "is_css": false
                    },
                    {
                      "hex": "#f88517",
                      "name": "Glorious Sunset",
                      "is_bestof": true,
                      "is_css": false
                    },
                    {
                      "hex": "#c38d87",
                      "name": "Grand Sunset",
                      "is_bestof": true,
                      "is_css": false
                    },
                    {
                      "hex": "#e95e2a",
                      "name": "Sunset Blaze",
                      "is_bestof": true,
                      "is_css": false
                    },
                    {
                      "hex": "#f6c362",
                      "name": "Sunset Gold",
                      "is_bestof": true,
                      "is_css": false
                    },
                    {
                      "hex": "#fd5e53",
                      "name": "Sunset Orange",
                      "is_bestof": true,
                      "is_css": false
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "402": {
            "description": "Subscription past due; the response carries a payment_url"
          },
          "429": {
            "description": "Monthly token allowance exhausted"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/v1/colors/contrast": {
      "get": {
        "operationId": "wcagContrast",
        "summary": "WCAG Contrast",
        "description": "WCAG Contrast endpoint of the Colors API. Costs 1 token per call.",
        "externalDocs": {
          "url": "https://dataandapis.com/apis/colors/wcag-contrast"
        },
        "parameters": [
          {
            "name": "bg",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "ffffff"
          },
          {
            "name": "fg",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "000000"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "ok": true,
                  "fg": "#000000",
                  "bg": "#ffffff",
                  "contrast_ratio": 21,
                  "wcag": {
                    "aa_normal_text": true,
                    "aa_large_text": true,
                    "aaa_normal_text": true,
                    "aaa_large_text": true
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "402": {
            "description": "Subscription past due; the response carries a payment_url"
          },
          "429": {
            "description": "Monthly token allowance exhausted"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key",
        "description": "Create a free key at https://dataandapis.com/sign-up. 500 tokens a month on the Free plan; this API costs 1 token per call."
      }
    }
  },
  "security": [
    {
      "ApiKey": []
    }
  ]
}