{
  "openapi": "3.1.1",
  "info": {
    "title": "Contrast Fixer: Nearest Accessible Color API",
    "version": "1.0.0",
    "summary": "Find the closest color that reaches WCAG 3:1, 4.5:1 or 7:1 contrast — and repair a palette.",
    "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp."
  },
  "servers": [
    {
      "url": "https://luminacontrastfixer.usefulweb.app"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Find the closest color that reaches WCAG 3:1, 4.5:1 or 7:1 contrast — and repair a palette.",
        "description": "Enter a text and a background color. If the pair fails the WCAG contrast target, get the nearest darker and lighter versions of the color you want to change (same OKLCH hue, measured by CIEDE2000). Optionally check a whole palette: every background gets its readable text colors and a repaired one where none passes.\n\nMethodology:\n- Contrast is the WCAG 2.x ratio (L1 + 0.05)/(L2 + 0.05) of relative luminances from 8-bit sRGB. Thresholds compare unrounded ratios; every suggestion is checked again on its rounded HEX value.\n- Only the chosen color changes. Its OKLCH hue and chroma are kept and its lightness is moved towards black (darker) and towards white (lighter) by bisection until the target is just reached; chroma is reduced by the CSS Color 4 gamut mapping if the color would leave sRGB.\n- The suggestion is the option with the smaller CIEDE2000 difference to the original. Black or white is offered only when neither direction can reach the target.\n- Palette check: for each color as background, the other palette colors that pass are listed (best ratio first). If none passes, the palette color with the highest ratio is adjusted as above. APCA is not used.",
        "tags": [
          "apps"
        ],
        "x-mcp-tool": "lumina_contrast_fixer",
        "x-owner-app": "lumina",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LuminaContrastFixerInput"
              },
              "examples": {
                "example1": {
                  "summary": "Sea green text on foam",
                  "value": {
                    "foreground": "#72A5A0",
                    "background": "#ECF0DE",
                    "target": "4.5",
                    "adjust": "foreground",
                    "palette": ""
                  }
                },
                "example2": {
                  "summary": "Grey #777 on white for AAA",
                  "value": {
                    "foreground": "#777777",
                    "background": "#FFFFFF",
                    "target": "7",
                    "adjust": "foreground",
                    "palette": ""
                  }
                },
                "example3": {
                  "summary": "Repair a four-color palette",
                  "value": {
                    "foreground": "#FFFFFF",
                    "background": "#E07A5F",
                    "target": "4.5",
                    "adjust": "background",
                    "palette": "#3D405B #E07A5F #F2CC8F #81B29A"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LuminaContrastFixerResult"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON body.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Invalid input (see errors[]).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (see Retry-After).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tool": {
      "get": {
        "operationId": "getToolDefinition",
        "summary": "Inputs, output schema and examples for this tool",
        "responses": {
          "200": {
            "description": "Tool definition.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details. 422 responses include per-field `errors`.",
        "required": [
          "type",
          "title",
          "status",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "field",
                "message"
              ],
              "properties": {
                "field": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "LuminaContrastFixerInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "foreground": {
            "title": "Text color (CSS color)",
            "type": "string",
            "maxLength": 200,
            "default": "#72A5A0"
          },
          "background": {
            "title": "Background color (CSS color)",
            "type": "string",
            "maxLength": 200,
            "default": "#ECF0DE"
          },
          "target": {
            "title": "Contrast target",
            "type": "string",
            "enum": [
              "3",
              "4.5",
              "7"
            ],
            "default": "4.5"
          },
          "adjust": {
            "title": "Color to change",
            "type": "string",
            "enum": [
              "foreground",
              "background"
            ],
            "default": "foreground"
          },
          "palette": {
            "title": "Palette to check (optional, 2–24 colors)",
            "type": "string",
            "maxLength": 16384,
            "default": ""
          }
        },
        "required": []
      },
      "LuminaContrastFixerResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schemaVersion",
          "tool",
          "computedAt",
          "inputs",
          "summary",
          "result",
          "units",
          "assumptions",
          "sources",
          "warnings",
          "presentation",
          "links"
        ],
        "properties": {
          "schemaVersion": {
            "type": "string",
            "const": "1.0"
          },
          "tool": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "name",
              "version"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "version": {
                "type": "string"
              }
            }
          },
          "computedAt": {
            "type": "string",
            "format": "date-time"
          },
          "inputs": {
            "type": "object",
            "description": "Normalised inputs actually used, including applied defaults."
          },
          "summary": {
            "type": "string"
          },
          "result": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "foreground",
              "background",
              "adjust",
              "target",
              "ratio",
              "passes",
              "suggestion",
              "options",
              "palette"
            ],
            "properties": {
              "foreground": {
                "type": "string"
              },
              "background": {
                "type": "string"
              },
              "adjust": {
                "type": "string"
              },
              "target": {
                "type": "number"
              },
              "ratio": {
                "type": "number"
              },
              "passes": {
                "type": "boolean"
              },
              "suggestion": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "hex",
                  "ratio",
                  "deltaE2000",
                  "direction"
                ],
                "properties": {
                  "hex": {
                    "type": "string"
                  },
                  "ratio": {
                    "type": "number"
                  },
                  "deltaE2000": {
                    "type": "number"
                  },
                  "direction": {
                    "type": "string"
                  }
                }
              },
              "options": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "hex",
                    "ratio",
                    "deltaE2000",
                    "direction"
                  ],
                  "properties": {
                    "hex": {
                      "type": "string"
                    },
                    "ratio": {
                      "type": "number"
                    },
                    "deltaE2000": {
                      "type": "number"
                    },
                    "direction": {
                      "type": "string"
                    }
                  }
                }
              },
              "palette": {
                "anyOf": [
                  {
                    "type": "null"
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "target",
                      "rows",
                      "passingPairs",
                      "totalPairs"
                    ],
                    "properties": {
                      "target": {
                        "type": "number"
                      },
                      "passingPairs": {
                        "type": "integer"
                      },
                      "totalPairs": {
                        "type": "integer"
                      },
                      "rows": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "additionalProperties": false,
                          "required": [
                            "background",
                            "readable",
                            "bestText"
                          ],
                          "properties": {
                            "background": {
                              "type": "string"
                            },
                            "readable": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "additionalProperties": false,
                                "required": [
                                  "index",
                                  "hex",
                                  "ratio"
                                ],
                                "properties": {
                                  "index": {
                                    "type": "integer"
                                  },
                                  "hex": {
                                    "type": "string"
                                  },
                                  "ratio": {
                                    "type": "number"
                                  }
                                }
                              }
                            },
                            "bestText": {
                              "type": "object",
                              "additionalProperties": false,
                              "required": [
                                "hex",
                                "ratio",
                                "source"
                              ],
                              "properties": {
                                "hex": {
                                  "type": "string"
                                },
                                "ratio": {
                                  "type": "number"
                                },
                                "source": {
                                  "type": "string"
                                },
                                "fromIndex": {
                                  "type": "integer"
                                },
                                "deltaE2000": {
                                  "type": "number"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                ]
              }
            }
          },
          "units": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "assumptions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "title"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "publisher": {
                  "type": "string"
                },
                "retrievedAt": {
                  "type": "string"
                },
                "note": {
                  "type": "string"
                }
              }
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "presentation": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Display blocks used by the human page (same data)."
          },
          "links": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "human",
              "api",
              "openapi",
              "methodology"
            ],
            "properties": {
              "human": {
                "type": "string",
                "format": "uri"
              },
              "api": {
                "type": "string",
                "format": "uri"
              },
              "openapi": {
                "type": "string",
                "format": "uri"
              },
              "methodology": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      }
    }
  }
}