{
  "openapi": "3.1.1",
  "info": {
    "title": "Bézier Curve Fitter for SVG Paths API",
    "version": "1.0.0",
    "summary": "Turn jagged traced outlines or freehand polylines into a few smooth Bézier curves.",
    "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://luminacurvefit.usefulweb.app"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Turn jagged traced outlines or freehand polylines into a few smooth Bézier curves.",
        "description": "Paste SVG path data from a tracer, a drawing tablet or a plotter export. The fitter replaces runs of short segments with cubic Bézier curves and straight lines, keeps sharp corners, and proves that the new path stays within your tolerance of the original in both directions. Pixel mode treats the path as pixel steps (as traced by Lumina Vector Lab) and smooths the stairs; freehand mode follows every point. Lumina Vector Lab uses the same engine for curve smoothing.\n\nMethodology:\n- Path data is read with the full SVG grammar; curves and arcs in the input are flattened to within a tenth of the tolerance first. Every sub-path is fitted separately: closed ones as loops, open ones with both end points kept.\n- Corners are vertices whose direction changes by more than the corner angle, measured over a short window (3 × tolerance, 2 units for pixel outlines); they stay sharp and split the path into runs.\n- Each run is fitted with least-squares cubic Béziers (chord-length parameters, Newton reparameterisation, split at the worst point with a shared tangent). Pixel mode first samples the stairs every half unit and filters the samples (twelve [1 2 1] passes) so the fit follows the smooth shape behind the steps.\n- A curve or line is accepted only with a proven two-sided distance bound to the input run: the curve is flattened with a convex-hull error bound, both polylines are sampled every tolerance / 10, and the bound adds both errors and half the sampling step. Runs that cannot be fitted keep their original segments. Rounding to the chosen decimals is reserved inside the tolerance.\n\nThe fitted path stays within the tolerance of the input (after any input curves were flattened to a tenth of it). Fitting does not check whether different sub-paths now touch each other; Lumina Vector Lab adds that check for traced artwork. Up to 200,000 characters, 2,000 sub-paths and 20,000 points.",
        "tags": [
          "apps"
        ],
        "x-mcp-tool": "lumina_curve_fit",
        "x-owner-app": "lumina",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LuminaCurveFitInput"
              },
              "examples": {
                "example1": {
                  "summary": "Smooth a hand-drawn wave",
                  "value": {
                    "path": "M0 49.2 L5 58.2 L10 64.8 L15 70.4 L20 74.8 L25 77.7 L30 80.7 L35 79.9 L40 77.3 L45 72.9 L50 67.2 L55 62.2 L60 54.6 L65 46.8 L70 39.1 L75 32.1 L80 28.1 L85 23.6 L90 20.7 L95 19.6 L100 20.4 L105 25 L110 29.2 L115 34.8 L120 41.2 L125 48.2 L130 57.3 L135 63.9 L140 69.7 L145 74.3 L150 77.3 L155 80.6 L160 80.1 L165 77.7 L170 73.6 L175 67.9 L180 63.2 L185 55.6 L190 47.7 L195 40 L200 32.9",
                    "mode": "freehand",
                    "tolerance": 1,
                    "cornerAngle": 50,
                    "precision": 2
                  }
                },
                "example2": {
                  "summary": "Smooth a traced pixel circle",
                  "value": {
                    "path": "M8 2L16 2L16 3L18 3L18 4L19 4L19 5L20 5L20 6L21 6L21 8L22 8L22 16L21 16L21 18L20 18L20 19L19 19L19 20L18 20L18 21L16 21L16 22L8 22L8 21L6 21L6 20L5 20L5 19L4 19L4 18L3 18L3 16L2 16L2 8L3 8L3 6L4 6L4 5L5 5L5 4L6 4L6 3L8 3Z",
                    "mode": "pixel",
                    "tolerance": 1,
                    "cornerAngle": 50,
                    "precision": 3
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LuminaCurveFitResult"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      },
      "LuminaCurveFitInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "path": {
            "title": "SVG path data (d attribute)",
            "type": "string",
            "maxLength": 200000,
            "default": "M0 49.2 L5 58.2 L10 64.8 L15 70.4 L20 74.8 L25 77.7 L30 80.7 L35 79.9 L40 77.3 L45 72.9 L50 67.2 L55 62.2 L60 54.6 L65 46.8 L70 39.1 L75 32.1 L80 28.1 L85 23.6 L90 20.7 L95 19.6 L100 20.4 L105 25 L110 29.2 L115 34.8 L120 41.2 L125 48.2 L130 57.3 L135 63.9 L140 69.7 L145 74.3 L150 77.3 L155 80.6 L160 80.1 L165 77.7 L170 73.6 L175 67.9 L180 63.2 L185 55.6 L190 47.7 L195 40 L200 32.9"
          },
          "mode": {
            "title": "Input kind",
            "type": "string",
            "enum": [
              "freehand",
              "pixel"
            ],
            "default": "freehand"
          },
          "tolerance": {
            "title": "Maximum distance from the input (path units)",
            "type": "number",
            "minimum": 0.01,
            "maximum": 100,
            "default": 1
          },
          "cornerAngle": {
            "title": "Keep corners sharper than (degrees)",
            "type": "number",
            "minimum": 5,
            "maximum": 175,
            "default": 50
          },
          "precision": {
            "title": "Decimals in the result",
            "type": "integer",
            "minimum": 0,
            "maximum": 6,
            "default": 3
          }
        },
        "required": [
          "path"
        ]
      },
      "LuminaCurveFitResult": {
        "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": [
              "d",
              "subpaths",
              "closed",
              "open",
              "nodesIn",
              "nodesOut",
              "curves",
              "lines",
              "maxDeviation",
              "exactRuns",
              "reduction",
              "svgSha256"
            ],
            "properties": {
              "d": {
                "type": "string"
              },
              "subpaths": {
                "type": "integer"
              },
              "closed": {
                "type": "integer"
              },
              "open": {
                "type": "integer"
              },
              "nodesIn": {
                "type": "integer"
              },
              "nodesOut": {
                "type": "integer"
              },
              "curves": {
                "type": "integer"
              },
              "lines": {
                "type": "integer"
              },
              "maxDeviation": {
                "type": "number"
              },
              "exactRuns": {
                "type": "integer"
              },
              "reduction": {
                "type": "number"
              },
              "svgSha256": {
                "type": "string"
              }
            }
          },
          "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"
              }
            }
          }
        }
      }
    }
  }
}