{
  "openapi": "3.1.1",
  "info": {
    "title": "Perceptual Gradient Generator (OKLCH, OKLab, CSS) API",
    "version": "1.0.0",
    "summary": "Build smooth multi-stop CSS gradients in OKLab or OKLCH, with a fallback for every browser.",
    "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://luminagradientgenerator.usefulweb.app"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Build smooth multi-stop CSS gradients in OKLab or OKLCH, with a fallback for every browser.",
        "description": "Enter 2–16 color stops in any CSS color syntax. Get a modern CSS gradient that interpolates in OKLab, OKLCH, Lab, LCH or linear light, a fallback with dense HEX stops and its measured error, evenly spaced palette steps and an optional bilinear mesh gradient as PNG.\n\nMethodology:\n- Parse each stop with CSS Color 4 syntax and fix positions like CSS Images 3: the first and last stop default to 0 % and 100 %, a position smaller than an earlier one is raised to it, and stops without a position are spaced evenly between their neighbours.\n- Interpolate between neighbouring stops in the chosen space (CSS Color 4 §12). In OKLCH and LCH the hue follows the chosen path; a grey stop has no hue and takes its neighbour's, so grey to blue never passes through red. Colors outside sRGB are brought back with the CSS Color 4 gamut mapping (chroma reduction in OKLCH).\n- The modern rule uses the CSS syntax \"in \u003cspace\u003e\" so the browser interpolates itself. The fallback samples the same gradient at the step count plus every original stop and lets the browser mix those HEX stops in sRGB; its largest deviation from the true gradient is reported as an OKLab distance × 100 over 513 samples (about 2 is barely visible).\n- The mesh gradient puts the grid colors at the corners of equal cells and mixes them bilinearly (first across, then down) in the chosen space; the PNG is 480 × 320 pixels.",
        "tags": [
          "apps"
        ],
        "x-mcp-tool": "lumina_gradient_generator",
        "x-owner-app": "lumina",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LuminaGradientGeneratorInput"
              },
              "examples": {
                "example1": {
                  "summary": "Teal to sand in OKLCH",
                  "value": {
                    "stops": "#164E63\n#EBC17E",
                    "space": "oklch",
                    "hue": "shorter",
                    "kind": "linear",
                    "angle": 90,
                    "steps": 9,
                    "mesh": ""
                  }
                },
                "example2": {
                  "summary": "Three stops with positions, conic, longer hue",
                  "value": {
                    "stops": "oklch(0.7 0.15 30) 0\nrebeccapurple 40\n#2E8B57 100",
                    "space": "oklch",
                    "hue": "longer",
                    "kind": "conic",
                    "angle": 0,
                    "steps": 12,
                    "mesh": ""
                  }
                },
                "example3": {
                  "summary": "A 2 × 3 mesh gradient",
                  "value": {
                    "stops": "#FF6B6B\n#4D96FF",
                    "space": "oklab",
                    "hue": "shorter",
                    "kind": "linear",
                    "angle": 135,
                    "steps": 7,
                    "mesh": "#FF6B6B #FFD93D #6BCB77\n#4D96FF #9B5DE5 #F15BB5"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LuminaGradientGeneratorResult"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      },
      "LuminaGradientGeneratorInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "stops": {
            "title": "Color stops (one per line: color and optional position in %)",
            "type": "string",
            "maxLength": 4000,
            "default": "#164E63\n#EBC17E"
          },
          "space": {
            "title": "Interpolation space",
            "type": "string",
            "enum": [
              "oklch",
              "oklab",
              "lab",
              "lch",
              "srgb-linear",
              "srgb"
            ],
            "default": "oklch"
          },
          "hue": {
            "title": "Hue path (OKLCH and LCH)",
            "type": "string",
            "enum": [
              "shorter",
              "longer",
              "increasing",
              "decreasing"
            ],
            "default": "shorter"
          },
          "kind": {
            "title": "Gradient shape",
            "type": "string",
            "enum": [
              "linear",
              "radial",
              "conic"
            ],
            "default": "linear"
          },
          "angle": {
            "title": "Angle (degrees; linear direction or conic start)",
            "type": "number",
            "minimum": 0,
            "maximum": 360,
            "default": 90
          },
          "steps": {
            "title": "Palette steps and fallback stops",
            "type": "integer",
            "minimum": 2,
            "maximum": 64,
            "default": 9
          },
          "mesh": {
            "title": "Mesh gradient grid (optional; one row of colors per line, 2–6 per side)",
            "type": "string",
            "maxLength": 2000,
            "default": ""
          }
        },
        "required": []
      },
      "LuminaGradientGeneratorResult": {
        "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": [
              "modern",
              "fallback",
              "css",
              "fallbackMaxErrorOK",
              "stops",
              "steps",
              "space",
              "hue",
              "kind",
              "mesh"
            ],
            "properties": {
              "modern": {
                "type": "string"
              },
              "fallback": {
                "type": "string"
              },
              "css": {
                "type": "string"
              },
              "fallbackMaxErrorOK": {
                "type": "number"
              },
              "space": {
                "type": "string"
              },
              "hue": {
                "type": "string"
              },
              "kind": {
                "type": "string"
              },
              "stops": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "hex",
                    "position"
                  ],
                  "properties": {
                    "hex": {
                      "type": "string"
                    },
                    "position": {
                      "type": "number"
                    }
                  }
                }
              },
              "steps": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "mesh": {
                "anyOf": [
                  {
                    "type": "null"
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "rows",
                      "columns",
                      "width",
                      "height",
                      "artifact"
                    ],
                    "properties": {
                      "rows": {
                        "type": "integer"
                      },
                      "columns": {
                        "type": "integer"
                      },
                      "width": {
                        "type": "integer"
                      },
                      "height": {
                        "type": "integer"
                      },
                      "artifact": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                          "artifactId",
                          "filename",
                          "mime",
                          "bytes",
                          "sha256",
                          "path"
                        ],
                        "properties": {
                          "artifactId": {
                            "type": "string"
                          },
                          "filename": {
                            "type": "string"
                          },
                          "mime": {
                            "type": "string"
                          },
                          "bytes": {
                            "type": "integer"
                          },
                          "sha256": {
                            "type": "string"
                          },
                          "path": {
                            "type": "string",
                            "description": "Download path on the same site (valid for about 2 hours)."
                          }
                        }
                      }
                    }
                  }
                ]
              }
            }
          },
          "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"
              }
            }
          }
        }
      }
    }
  }
}