The Color API

https://www.thecolorapi.com/docs
Admin
The Color API provides endpoints to identify detailed information about a given color (hex, RGB,...
Tokens:5,329
Snippets:5
Trust Score:8.8
Update:9 months ago
Show doc for...
Tokens:
Raw
### GET /scheme

Source: https://www.thecolorapi.com/docs/index

Generates a color scheme based on a provided seed color and mode. Supports multiple color formats for input and various output formats.

```APIDOC
## GET /scheme

### Description
Generates a color scheme based on a provided seed color and mode. Supports multiple color formats for input and various output formats like JSON, HTML, or SVG.

### Method
GET

### Endpoint
https://www.thecolorapi.com/scheme

### Parameters
#### Query Parameters
- **hex** (string) - Optional - Valid hex code (e.g., `0047AB`).
- **rgb** (string) - Optional - Valid rgb color (e.g., `0,71,171` or `rgb(0,71,171)`).
- **hsl** (string) - Optional - Valid hsl color (e.g., `215,100%,34%` or `hsl(215,100%,34%)`).
- **cmyk** (string) - Optional - Valid cmyk color (e.g., `100,58,0,33` or `cmyk(100,58,0,33)`).
- **format** (string) - Optional - Default: `json` - Return results as JSON, SVG or HTML page of results. Choices: `json`, `html`, `svg`.
- **mode** (string) - Optional - Default: `monochrome` - Define mode by which to generate the scheme from the seed color. Choices: `monochrome`, `monochrome-dark`, `monochrome-light`, `analogic`, `complement`, `analogic-complement`, `triad`, `quad`.
- **count** (integer) - Optional - Default: `5` - Number of colors to return.
- **w** (integer) - Optional - Default: `100` - Height of resulting image, only applicable on SVG format.
- **named** (boolean) - Optional - Default: `true` - Whether to print the color names on resulting image, only applicable on SVG format.

### Request Example
```json
{
  "example": "GET https://www.thecolorapi.com/scheme?hex=0047AB&rgb=0,71,171&hsl=215,100%,34%&cmyk=100,58,0,33&format=html&mode=analogic&count=6"
}
```

### Response
#### Success Response (200)
- **Headers** (object) - Contains response headers.
  - **Content-Type** (string) - Specifies the media type of the resource.

#### Response Example
```json
{
  "example": "Response body will vary based on the requested format (json, html, svg)."
}
```
```

--------------------------------

### Get Color Scheme

Source: https://www.thecolorapi.com/docs/index

Retrieve a color scheme based on a provided color value and mode. Supports various color formats for input and different scheme types.

```APIDOC
## GET /scheme

### Description
Retrieves a color scheme based on a provided color value and mode. Supports various color formats for input and different scheme types.

### Method
GET

### Endpoint
/scheme

### Parameters
#### Query Parameters
- **hex** (string) - Optional - The hexadecimal color value (e.g., "0047AB").
- **rgb** (string) - Optional - The RGB color value (e.g., "rgb(0, 71, 171)").
- **hsl** (string) - Optional - The HSL color value (e.g., "hsl(216, 100%, 33%)").
- **cmyk** (string) - Optional - The CMYK color value (e.g., "cmyk(100, 58, 0, 33)").
- **mode** (string) - Optional - The color scheme mode. Options include: `monochrome`, `monochrome-dark`, `monochrome-light`, `analogic`, `complement`, `analogic-complement`, `triad`, `quad`.
- **count** (integer) - Optional - The number of colors to return in the scheme (default is 5).

### Request Example
```json
{
  "example": "/scheme?hex=0047AB&mode=monochrome&count=2"
}
```

### Response
#### Success Response (200)
- **name** (object) - Information about the color name.
  - **value** (string) - The name of the color.
  - **closest_hex** (string) - The closest hexadecimal representation of the color name.
- **hex** (object) - Information about the hexadecimal representation.
  - **value** (string) - The hexadecimal value.
  - **clean** (string) - The hexadecimal value without the '#'.
- **rgb** (object) - Information about the RGB representation.
  - **value** (string) - The RGB value (e.g., "rgb(0, 71, 171)").
  - **r** (integer) - Red component.
  - **g** (integer) - Green component.
  - **b** (integer) - Blue component.
- **hsl** (object) - Information about the HSL representation.
  - **value** (string) - The HSL value (e.g., "hsl(216, 100%, 33%)").
  - **h** (number) - Hue component.
  - **s** (number) - Saturation component.
  - **l** (number) - Lightness component.
- **cmyk** (object) - Information about the CMYK representation.
  - **value** (string) - The CMYK value (e.g., "CMYK(100, 58, 0, 33)").
  - **c** (number) - Cyan component.
  - **m** (number) - Magenta component.
  - **y** (number) - Yellow component.
  - **k** (number) - Key (black) component.
- **xyz** (object) - Information about the XYZ color space representation.
  - **value** (string) - The XYZ value (e.g., "XYZ(0.17, 0.15, 0.32)").
  - **X** (number) - X component.
  - **Y** (number) - Y component.
  - **Z** (number) - Z component.
- **image** (object) - URLs for the color image.
  - **bare** (string) - URL for the bare image.
  - **named** (string) - URL for the named image.
- **contrast** (object) - Information about the contrast ratio.
  - **value** (string) - The contrast value (hexadecimal).
- **_links** (object) - Links related to the color.
  - **self** (object) - Link to the current color resource.
    - **href** (string) - The URL for the self link.
- **_embedded** (object) - Embedded resources.

#### Response Example
```json
{
  "name": {
    "value": "Cobalt Blue",
    "closest_hex": "#0047AB"
  },
  "hex": {
    "value": "#0047AB",
    "clean": "0047AB"
  },
  "rgb": {
    "value": "rgb(0, 71, 171)",
    "r": 0,
    "g": 71,
    "b": 171
  },
  "hsl": {
    "value": "hsl(216, 100%, 33%)",
    "h": 216,
    "s": 1,
    "l": 0.33
  },
  "cmyk": {
    "value": "CMYK(100, 58, 0, 33)",
    "c": 1,
    "m": 0.58,
    "y": 0,
    "k": 0.33
  },
  "xyz": {
    "value": "XYZ(0.17, 0.15, 0.32)",
    "X": 0.17,
    "Y": 0.15,
    "Z": 0.32
  },
  "image": {
    "bare": "http://placehold.it/300x300.png/0047AB/000000",
    "named": "http://placehold.it/300x300.png/0047AB/000000&text=Cobalt"
  },
  "contrast": {
    "value": "#000000"
  },
  "_links": {
    "self": {
      "href": "/id?hex=0047AB"
    }
  },
  "_embedded": {}
}
```

#### Error Response (400)
- **code** (integer) - The error code.
- **message** (string) - A description of the error.
- **query** (object) - The query parameters received.
- **params** (array) - The parameters processed.
- **path** (string) - The endpoint path.
- **example** (string) - An example of a correct request.

##### Response Example
```json
{
  "code": 400,
  "message": "The Color API doesn't understand what you mean. Please supply a query parameter of `rgb`, `hsl`, `cmyk` or `hex`.",
  "query": {},
  "params": [],
  "path": "/scheme",
  "example": "/scheme?hex=FF0&mode=monochrome&count=5"
}
```
```

--------------------------------

### POST /websites/thecolorapi

Source: https://www.thecolorapi.com/docs/index

This endpoint allows you to generate monochromatic colors. You can specify the mode, the number of colors, and a seed color. The response includes detailed information about each generated color, including its hex, RGB, HSL, HSV, CMYK, XYZ values, a suggested name, and image URLs.

```APIDOC
## POST /websites/thecolorapi

### Description
Generates monochromatic colors based on a seed value and count.

### Method
POST

### Endpoint
/websites/thecolorapi

### Parameters
#### Request Body
- **mode** (string) - Required - The color mode (e.g., "monochrome").
- **count** (string) - Required - The number of colors to generate.
- **colors** (array) - Optional - An array of color objects (used for generating colors based on input colors).
- **seed** (object) - Optional - The seed color object to base the generation on.
  - **hex** (object) - Required if seed is provided - The hex value of the seed color.
    - **value** (string) - Required - The hex color code (e.g., "#0047AB").

### Request Example
```json
{
  "mode": "monochrome",
  "count": "2",
  "seed": {
    "hex": {
      "value": "#0047AB"
    }
  }
}
```

### Response
#### Success Response (200)
- **mode** (string) - The color mode used for generation.
- **count** (string) - The number of colors generated.
- **colors** (array) - An array of color objects, each containing detailed color information (hex, rgb, hsl, hsv, name, cmyk, XYZ, image, contrast).
- **seed** (object) - The seed color object used for generation.

#### Response Example
```json
{
  "mode": "monochrome",
  "count": "2",
  "colors": [
    {
      "hex": {
        "value": "#01122A",
        "clean": "01122A"
      },
      "rgb": {
        "r": 1,
        "g": 18,
        "b": 42,
        "value": "rgb(1, 18, 42)"
      },
      "hsl": {
        "h": 215,
        "s": 95,
        "l": 8,
        "value": "hsl(215, 95%, 8%)"
      },
      "hsv": {
        "h": 215,
        "s": 98,
        "v": 16,
        "value": "hsv(215, 98%, 16%)"
      },
      "name": {
        "value": "Midnight",
        "closest_named_hex": "#011635",
        "exact_match_name": false,
        "distance": 217
      },
      "cmyk": {
        "c": 98,
        "m": 57,
        "y": 0,
        "k": 84,
        "value": "cmyk(98, 57, 0, 84)"
      },
      "XYZ": {
        "X": 6,
        "Y": 6,
        "Z": 17,
        "value": "XYZ(6, 6, 17)"
      },
      "image": {
        "bare": "http://placehold.it/300x300.png/01122A/FFFFFF",
        "named": "http://placehold.it/300x300.png/01122A/FFFFFF&text=Midnight"
      },
      "contrast": {
        "value": "#FFFFFF"
      },
      "_links": {
        "self": {
          "href": "/id?hex=01122A"
        }
      },
      "_embedded": {}
    },
    {
      "hex": {
        "value": "#0247A9",
        "clean": "0247A9"
      },
      "rgb": {
        "r": 2,
        "g": 71,
        "b": 169,
        "value": "rgb(2, 71, 169)"
      },
      "hsl": {
        "h": 215,
        "s": 98,
        "l": 34,
        "value": "hsl(215, 98%, 34%)"
      },
      "hsv": {
        "h": 215,
        "s": 99,
        "v": 66,
        "value": "hsv(215, 99%, 66%)"
      },
      "name": {
        "value": "Cobalt",
        "closest_named_hex": "#0047AB",
        "exact_match_name": false,
        "distance": 80
      },
      "cmyk": {
        "c": 99,
        "m": 58,
        "y": 0,
        "k": 34,
        "value": "cmyk(99, 58, 0, 34)"
      },
      "XYZ": {
        "X": 22,
        "Y": 25,
        "Z": 66,
        "value": "XYZ(22, 25, 66)"
      },
      "image": {
        "bare": "http://placehold.it/300x300.png/0247A9/000000",
        "named": "http://placehold.it/300x300.png/0247A9/000000&text=Cobalt"
      },
      "contrast": {
        "value": "#000000"
      },
      "_links": {
        "self": {
          "href": "/id?hex=0247A9"
        }
      },
      "_embedded": {}
    }
  ],
  "seed": {
    "hex": {
      "value": "#0047AB",
      "clean": "0047AB"
    },
    "rgb": {
      "r": 0,
      "g": 71,
      "b": 171,
      "value": "rgb(0, 71, 171)"
    },
    "hsl": {
      "h": 215,
      "s": 100,
      "l": 34,
      "value": "hsl(215, 100%, 34%)"
    },
    "hsv": {
      "h": 215,
      "s": 100,
      "v": 67,
      "value": "hsv(215, 100%, 67%)"
    },
    "name": {
      "value": "Cobalt",
      "closest_named_hex": "#0047AB",
      "exact_match_name": true,
      "distance": 0
    },
    "cmyk": {
      "c": 100,
      "m": 58,
      "y": 0,
      "k": 33,
      "value": "cmyk(100, 58, 0, 33)"
    },
    "XYZ": {
      "X": 22,
      "Y": 25,
      "Z": 66,
      "value": "XYZ(22, 25, 66)"
    }
  }
}
```
```

--------------------------------

### Generate Scheme API

Source: https://www.thecolorapi.com/docs/index

Generate a color scheme based on a provided seed color and an optional mode and count.

```APIDOC
## GET /scheme

### Description
Return a generated scheme for the provided seed color and optional mode.

### Method
GET

### Endpoint
`/scheme{?hex,rgb,hsl,cmyk,format,mode,count}`

### Parameters
#### Query Parameters
- **hex** (string, optional) - Seed color in hex format. Example: `24B1E0`
- **rgb** (string, optional) - Seed color in RGB format. Example: `rgb(0,71,171)`
- **hsl** (string, optional) - Seed color in HSL format. Example: `hsl(215,100%,34%)`
- **cmyk** (string, optional) - Seed color in CMYK format. Example: `cmyk(100,58,0,33)`
- **format** (string, optional) - Return results as JSON, SVG or HTML page. Choices: `json`, `html`, `svg`. Default: `json`.
- **mode** (string, optional) - The color scheme mode. Example: `triad`
- **count** (integer, optional) - The number of colors in the scheme. Example: `6`

### Request Example
```
/scheme?hex=24B1E0&mode=triad&count=6 || /scheme?rgb=rgb(0,71,171)
```

### Response
*(Response structure for scheme generation is similar to color identification but includes an array of colors for the scheme.)*

### Response Example
*(Example response would vary based on input parameters for scheme generation.)*
```

--------------------------------

### Color Identification API

Source: https://www.thecolorapi.com/docs/index

Retrieve identifying information for a given color using its hex, RGB, HSL, or CMYK values.

```APIDOC
## GET /id

### Description
Return available identifying information on the given color.

### Method
GET

### Endpoint
`/id{?hex,rgb,hsl,cmyk,format,w,named}`

### Parameters
#### Query Parameters
- **hex** (string, optional) - Valid hex code. Example: `0047AB`
- **rgb** (string, optional) - Valid rgb color, also `rgb(0,71,171)`. Example: `0,71,171`
- **hsl** (string, optional) - Valid hsl color, also `hsl(215,100%,34%)`. Example: `215,100%,34%`
- **cmyk** (string, optional) - Valid cmyk color, also `cmyk(100,58,0,33)`. Example: `100,58,0,33`
- **format** (string, optional) - Return results as JSON, SVG or HTML page. Choices: `json`, `html`, `svg`. Default: `json`. Example: `html`
- **w** (integer, optional) - Height of resulting image, only applicable on SVG format. Default: `100`. Example: `350`
- **named** (boolean, optional) - Whether to print the color names on resulting image, only applicable on SVG format. Default: `true`. Example: `false`

### Request Example
```
GET https://www.thecolorapi.com/id?hex=0047AB&rgb=0,71,171&hsl=215,100%,34%&cmyk=100,58,0,33&format=html
```

### Response
#### Success Response (200)
- **hex** (object) - Hexadecimal representation of the color.
- **rgb** (object) - RGB representation of the color.
- **hsl** (object) - HSL representation of the color.
- **hsv** (object) - HSV representation of the color.
- **name** (object) - Information about the closest named color.
- **cmyk** (object) - CMYK representation of the color.
- **XYZ** (object) - XYZ representation of the color.
- **image** (object) - URLs for bare and named image representations.
- **contrast** (object) - Information about color contrast.

#### Response Example
```json
{
  "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
    },
    "h": 215,
    "s": 100,
    "value": "hsv(215, 100%, 67%)",
    "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": "http://placehold.it/300x300.png/0047AB/000000",
    "named": "http://placehold.it/300x300.png/0047AB/000000&text=Cobalt"
  },
  "contrast": {
    "value": "#000000"
  },
  "_links": {
    "self": {
      "href": "/id?hex=0047AB"
    }
  },
  "_embedded": {}
}
```

#### Error Response (400)
- **code** (integer) - Error code.
- **message** (string) - Error message explaining the issue.
- **query** (object) - The query object received.
- **params** (array) - An array of parameters.
- **path** (string) - The endpoint path.
- **example** (string) - An example of a correct request.

#### Error Response Example
```json
{
  "code": 400,
  "message": "The Color API doesn't understand what you mean. Please supply a query parameter of `rgb`, `hsl`, `cmyk` or `hex`.",
  "query": {},
  "params": [],
  "path": "/id",
  "example": "/id?hex=a674D3"
}
```
```
Tokens:
Raw