{
  "openapi": "3.1.1",
  "info": {
    "title": "Path Boolean Operations (SVG) API",
    "version": "1.0.0",
    "summary": "Union, intersect, subtract or exclude two SVG paths, or remove the overlaps of one path.",
    "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://threadsmithpathboolean.usefulweb.app"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Union, intersect, subtract or exclude two SVG paths, or remove the overlaps of one path.",
        "description": "Paste two SVG paths (the d attribute) and combine them like a vector editor's Path menu: union, intersection, difference or exclusion. With an empty second path, union removes overlaps and self-intersections. Curves are flattened within your tolerance, combined exactly as polygons and refitted to Bézier curves; the result is checked against both inputs on a grid of test points. Threadsmith uses the same engine for Object → Combine shapes.\n\nMethodology:\n- Both paths are parsed with the full SVG path grammar (arcs become cubic Béziers, about 2.7e-4 × radius off) and every curve is flattened adaptively so that the polygon stays within the curve tolerance. Open sub-paths are closed, as SVG filling does.\n- Vertices are snapped to a grid of 1e-9 × the drawing size; all segments are split at their crossings, T-junctions and collinear overlaps (sweep over x-sorted bounding boxes), and identical edges are merged with a signed count per path.\n- For every edge, an axis-parallel ray from its midpoint across all other edges gives the winding numbers of A and B on both sides. With each path's fill rule this decides whether each side is inside the result; edges with the result on one side only are kept, oriented and chained into rings (tightest turn first), and collinear points are removed. The result has winding ±1 inside, so it fills the same with nonzero and evenodd.\n- Curve refit: runs between corners (turns sharper than 35°) are fitted with least-squares cubic Béziers (chord-length parameters, Newton reparameterisation, split at the worst point). A curve is accepted only when every polygon point lies within the refit tolerance of the curve and 16 samples of the curve lie within it of the polygon; otherwise straight segments stay.\n- Check: on a 48 × 48 grid over the drawing, every point farther than twice the tolerances from any outline must be inside the re-read result exactly when the operation says so for its position in A and B.\n\nThe result is within the curve tolerance of the exact Boolean (plus the refit tolerance when curves are refitted) and rounded to the chosen decimals. Strokes, transforms, clip paths and text are not part of path data; convert them to paths first. Up to 200,000 characters per path and 40,000 segments after flattening.",
        "tags": [
          "apps"
        ],
        "x-mcp-tool": "threadsmith_path_boolean",
        "x-owner-app": "threadsmith",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThreadsmithPathBooleanInput"
              },
              "examples": {
                "example1": {
                  "summary": "Union of two overlapping circles",
                  "value": {
                    "pathA": "M-10 0A10 10 0 1 0 10 0A10 10 0 1 0 -10 0Z",
                    "pathB": "M0 0A10 10 0 1 0 20 0A10 10 0 1 0 0 0Z",
                    "op": "union",
                    "fillA": "nonzero",
                    "fillB": "nonzero",
                    "tolerance": 0.01,
                    "refit": true,
                    "fitTolerance": 0.01,
                    "precision": 3
                  }
                },
                "example2": {
                  "summary": "Square minus a circle: a window with a round hole",
                  "value": {
                    "pathA": "M0 0H40V40H0Z",
                    "pathB": "M8 20A12 12 0 1 0 32 20A12 12 0 1 0 8 20Z",
                    "op": "difference",
                    "fillA": "nonzero",
                    "fillB": "nonzero",
                    "tolerance": 0.02,
                    "refit": true,
                    "fitTolerance": 0.02,
                    "precision": 3
                  }
                },
                "example3": {
                  "summary": "Remove the overlaps of a self-intersecting star",
                  "value": {
                    "pathA": "M50 0L79 91L2 35L98 35L21 91Z",
                    "pathB": "",
                    "op": "union",
                    "fillA": "nonzero",
                    "fillB": "nonzero",
                    "tolerance": 0.05,
                    "refit": false,
                    "fitTolerance": 0.05,
                    "precision": 3
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadsmithPathBooleanResult"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      },
      "ThreadsmithPathBooleanInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "pathA": {
            "title": "Path A (SVG path data)",
            "type": "string",
            "maxLength": 200000,
            "default": "M-10 0A10 10 0 1 0 10 0A10 10 0 1 0 -10 0Z"
          },
          "pathB": {
            "title": "Path B (SVG path data; empty = remove the overlaps of path A)",
            "type": "string",
            "maxLength": 200000,
            "default": ""
          },
          "op": {
            "title": "Operation",
            "type": "string",
            "enum": [
              "union",
              "intersect",
              "difference",
              "xor"
            ],
            "default": "union"
          },
          "fillA": {
            "title": "Fill rule of path A",
            "type": "string",
            "enum": [
              "nonzero",
              "evenodd"
            ],
            "default": "nonzero"
          },
          "fillB": {
            "title": "Fill rule of path B",
            "type": "string",
            "enum": [
              "nonzero",
              "evenodd"
            ],
            "default": "nonzero"
          },
          "tolerance": {
            "title": "Curve tolerance (path units)",
            "type": "number",
            "minimum": 0.0001,
            "maximum": 100,
            "default": 0.05
          },
          "refit": {
            "title": "Refit Bézier curves to the result",
            "type": "boolean",
            "default": true
          },
          "fitTolerance": {
            "title": "Refit tolerance (path units)",
            "type": "number",
            "minimum": 0.0001,
            "maximum": 100,
            "default": 0.05
          },
          "precision": {
            "title": "Decimals in the result",
            "type": "integer",
            "minimum": 0,
            "maximum": 6,
            "default": 3
          }
        },
        "required": [
          "pathA"
        ]
      },
      "ThreadsmithPathBooleanResult": {
        "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": [
              "op",
              "d",
              "areaA",
              "areaB",
              "area",
              "outerRings",
              "holes",
              "nodes",
              "curves",
              "segments",
              "intersections",
              "fitFallbacks",
              "check",
              "warnings",
              "svgSha256",
              "artifactUrl"
            ],
            "properties": {
              "op": {
                "enum": [
                  "union",
                  "intersect",
                  "difference",
                  "xor"
                ]
              },
              "d": {
                "type": "string"
              },
              "areaA": {
                "type": "number"
              },
              "areaB": {
                "type": "number"
              },
              "area": {
                "type": "number"
              },
              "outerRings": {
                "type": "integer"
              },
              "holes": {
                "type": "integer"
              },
              "nodes": {
                "type": "integer"
              },
              "curves": {
                "type": "integer"
              },
              "segments": {
                "type": "integer"
              },
              "intersections": {
                "type": "integer"
              },
              "fitFallbacks": {
                "type": "integer"
              },
              "check": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "samples",
                  "agree",
                  "skipped",
                  "passed"
                ],
                "properties": {
                  "samples": {
                    "type": "integer"
                  },
                  "agree": {
                    "type": "integer"
                  },
                  "skipped": {
                    "type": "integer"
                  },
                  "passed": {
                    "type": "boolean"
                  }
                }
              },
              "warnings": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "svgSha256": {
                "type": "string"
              },
              "artifactUrl": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "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"
              }
            }
          }
        }
      }
    }
  }
}