HEX to Closest Color Name API¶

Overview¶

This API converts a given HEX color code into its closest named CSS color.
It accepts a JSON body containing a HEX value and returns the nearest color name based on Euclidean distance in RGB space.

Base URL:
https://api.apidatatools.com/hex-to-color-name-api

Endpoint (POST)¶

POST https://api.apidatatools.com/hex-to-color-name-api

Headers¶

Header	Type	Required	Description
`Content-Type`	`application/json`	Yes	Must be `application/json`
`x-api-key`	`string`	Yes	Your API key for authentication
`x-source-type`	`string`	Optional	Must be `body` (default). Only body mode supported.

Accepted File Extensions¶

This tool only supports body mode.
No file or URL input is accepted.

Input Example (Body Mode)¶

{
  "hex": "#FF5733"
}

Input Example (URL Mode)¶

Not applicable.

Input Example (File Mode)¶

Not applicable.

Example Request¶

Synchronous (Body Input)¶

Request

curl -X POST "https://api.apidatatools.com/hex-to-color-name-api" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"hex": "#FF5733"}'

Asynchronous (Remote File URL)¶

Not applicable.

Asynchronous (Input File)¶

Not applicable.

Example Response¶

Successful (Body Mode)¶

Response (200 OK)

{
  "status": "success",
  "request_id": "b2c3a1f0-1234-4e56-9a78-abcdef123456",
  "preview": "{\n  \"name\": \"tomato\"\n}"
}

Async Job Accepted¶

Not applicable.

Error Handling¶

Possible Errors¶

Error Code	HTTP Status	Message	Example Details
`INVALID_JSON`	400	Input must be valid JSON.	`{ "message": "Expecting value: line 1 column 1 (char 0)" }`
`MISSING_HEX_KEY`	400	JSON must contain 'hex' key.	`{ "input_keys": [] }`
`INVALID_HEX_FORMAT`	400	HEX must be 3 or 6 hex characters (with or without '#').	`{ "hex_input": "ZZZZZZ" }`
`HEX_TO_RGB_FAILED`	400	Failed to convert HEX to RGB.	`{ "message": "invalid literal for int() with base 16: ..." }`
`NO_COLOR_MATCH`	400	Could not determine closest color name.	`{}`
`EMPTY_BODY`	400	Request body is empty.	`{}`
`PAYLOAD_TOO_LARGE`	413	Request body exceeds plan limit.	`{}`
`UNKNOWN_FUNCTION`	404	Unsupported API endpoint.	`{}`
`INTERNAL_ERROR`	500	Failed to process your request.	`{}`

Example Error Response

{
  "status": "error",
  "error": "INVALID_HEX_FORMAT",
  "request_id": "b2c3a1f0-1234-4e56-9a78-abcdef123456",
  "details": {
    "message": "HEX must be 3 or 6 hex characters (with or without '#').",
    "hex_input": "ZZZZZZ"
  }
}

Async Job Status¶

Not applicable (no async mode supported).

Notes for Developers¶

This API only supports synchronous body mode.
Input must be a valid JSON object containing a "hex" key.
HEX values can include or omit the # prefix and must be 3 or 6 hexadecimal digits.
The response includes a request_id for traceability.
The returned color name is derived from the internal CSS color database.
Ensure the Content-Type header is set to application/json.
No file or URL-based asynchronous processing is available for this endpoint.