---
title: "Use this when checking whether a text/background color pair meets WCAG 2.x accessibility contrast."
method: POST
path: "/v1/color_contrast"
tags: ["color"]
---

# Use this when checking whether a text/background color pair meets WCAG 2.x accessibility contrast.

`POST /v1/color_contrast`

## Request

- Base URL: `https://api.clean.tools`
- URL: `https://api.clean.tools/v1/color_contrast`
- Auth: none declared

Use this when checking whether a text/background color pair meets WCAG 2.x accessibility contrast. Computes the relative-luminance contrast ratio (1-21, rounded to 2 decimals) and returns pass/fail booleans for normal and large text at AA and AAA levels (thresholds 4.5 / 7 / 3 / 4.5), plus a suggested passing foreground hex when normal-text AA fails (null when it already passes or none is found). Accepts 3- or 6-digit hex, with or without a leading '#'; echoed colors are normalized to 6-digit hex. Deterministic: same input, same output. Example: {foreground:'777', background:'fff'} -> ratio 4.48, normalAA false, largeAA true, suggestedForeground '#767676'.

## Request body

- object
  - `foreground` string, required: Foreground (text) color as a 3 or 6 digit HEX string, with or without a leading #, e.g. "#1a1a1a" or "777".
  - `background` string, required: Background color as a 3 or 6 digit HEX string, with or without a leading #, e.g. "#ffffff" or "fff".

## Response `200`

Structured tool result.

- object
  - `tool` string
  - `result` object
    - `foreground` string, required: Normalized foreground color as a 6-digit hex string.
    - `background` string, required: Normalized background color as a 6-digit hex string.
    - `ratio` number, required: WCAG 2.x contrast ratio, 1 to 21, rounded to 2 decimals.
    - `normalAA` boolean, required: Unrounded ratio >= 4.5 (normal text, AA).
    - `normalAAA` boolean, required: Unrounded ratio >= 7 (normal text, AAA).
    - `largeAA` boolean, required: Unrounded ratio >= 3 (large text >=18pt / 14pt bold, AA).
    - `largeAAA` boolean, required: Unrounded ratio >= 4.5 (large text, AAA).
    - `suggestedForeground` string, nullable, required: A passing foreground hex (>=4.5 vs the background) when normal-text AA fails; null when the pair already passes or no passing value is found.

## Other responses

- `400`: Invalid input or the tool reported an error.
- `413`: Request body exceeds the 128 KB limit.
- `429`: Rate limit exceeded; the response carries Retry-After and RateLimit-* headers — honor them and add jitter.

---

[API](https://skmtc.dev/clean/apis/clean-tools-api.md) · [All operations](https://skmtc.dev/clean/apis/clean-tools-api/llms.txt) · [OpenAPI document](https://skmtc.dev/clean/apis/clean-tools-api/revisions/a24a01d2833c?raw)