Color Contrast Checker — verify WCAG contrast

Check WCAG Color Contrast API

What it does

Color Contrast Checker compares a foreground and background color and returns the WCAG 2.1 contrast result for that pair. Send a foreground color in fg and a background color in bg; each can be provided as a hex value, rgb() value, or CSS color name.

The response includes the original fg and bg values, contrast_ratio, contrast_ratio_display, overall_level, and a passes object with AA/AAA results for normal and large text. You also get fg_luminance, bg_luminance, and a recommendation string to help you adjust a color combination that fails.

Use Color Contrast Checker when you need to validate design tokens, review brand palettes, or check text colors before shipping a UI. It gives you a quick accessibility signal for buttons, labels, alerts, and any other foreground/background pairing where readability matters.

curl -X POST "http://localhost:8080/creightonnick0/color-contrast-checker" \ -H "apy-token: $APY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "fg": "#767676", "bg": "#ffffff" }'

What you'll get back

Returns a JSON object with contrast details for the two colors, including the top-level bg, fg, passes, bg_luminance, fg_luminance, overall_level, contrast_ratio, recommendation, and contrast_ratio_display fields. passes is itself an object with boolean checks for AA_large_text, AAA_large_text, AA_normal_text, and AAA_normal_text.

{
  "bg": "#ffffff",
  "fg": "#767676",
  "passes": {
    "AA_large_text": true,
    "AAA_large_text": true,
    "AA_normal_text": false,
    "AAA_normal_text": false
  },
  "bg_luminance": 1,
  "fg_luminance": 0.18,
  "overall_level": "AA",
  "contrast_ratio": 4.48,
  "recommendation": "Use a darker foreground color for normal text.",
  "contrast_ratio_display": "4.48:1"
}

About this endpoint

What it does

Checks the contrast between a foreground color and a background color, using the two input color values you provide. It returns the normalized colors, luminance values, contrast ratio, WCAG pass/fail flags, an overall level, and a recommendation string.

Request Body

Parameter	Type	Mandatory	Description
fg	String	Yes	Foreground / text color. Accepts hex, `rgb()`, or a CSS color name.
bg	String	Yes	Background color. Accepts hex, `rgb()`, or a CSS color name.

Response

Returns a JSON object with bg and fg string fields, a passes object, bg_luminance and fg_luminance number fields, overall_level and recommendation string fields, and a contrast_ratio number plus contrast_ratio_display string. The response is the computed color-contrast result for the submitted foreground/background pair.

Parameter	Type	Mandatory	Description
bg	String	No	Background color returned by the service.
fg	String	No	Foreground color returned by the service.
passes	Object	No	WCAG pass/fail results for text sizes and levels.
passes.AA_large_text	Boolean	No	`true` if the pair passes AA for large text, otherwise `false`.
passes.AAA_large_text	Boolean	No	`true` if the pair passes AAA for large text, otherwise `false`.
passes.AA_normal_text	Boolean	No	`true` if the pair passes AA for normal text, otherwise `false`.
passes.AAA_normal_text	Boolean	No	`true` if the pair passes AAA for normal text, otherwise `false`.
bg_luminance	Number	No	Luminance value for the background color.
fg_luminance	Number	No	Luminance value for the foreground color.
overall_level	String	No	Overall contrast level returned by the service.
contrast_ratio	Number	No	Calculated contrast ratio for the color pair.
recommendation	String	No	Recommendation returned by the service.
contrast_ratio_display	String	No	Display-formatted contrast ratio.

Body

Name

Type

Description

bodyREQUIRED

object

—

Check WCAG Color Contrast API

What it does

Quickstart

What you'll get back

About this endpoint

What it does

Request Body

Response

Body

Errors any endpoint can return