{
  "openapi": "3.1.1",
  "info": {
    "title": "PrintPlan — True-scale tiled print API",
    "version": "1.0.0",
    "summary": "Print a measured outline across A4 or Letter sheets with alignment marks.",
    "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://paperwellprintplan.usefulweb.app"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Print a measured outline across A4 or Letter sheets with alignment marks.",
        "description": "Prepare SVG geometry at a measured physical size, inspect the assembly grid and export tiled PDFs with alignment marks and a 100 mm calibration square.\n\nMethodology:\n- Reuses the Threadsmith vector path, flattening and tiled-PDF engines. Bézier curves, elliptical arcs, rounded rectangles and affine group transforms are supported; curves are flattened at 0.15 mm tolerance.\n- The browser can trace a selected PDF page or PNG/JPEG image locally into bounded black-and-white contours, with threshold, inversion and sampling controls. This is contour extraction, not full-color reproduction. Direct SVG input rejects external references, scripts, text, clipping, masks and filters. Unsupported content is rejected rather than silently omitted. The target width and height define the printable canvas.\n- Auto orientation selects the smaller sheet count. Print at 100%, check printer margins and measure the 100 mm calibration square before using a template.",
        "tags": [
          "apps"
        ],
        "x-mcp-tool": "paperwell_printplan",
        "x-owner-app": "paperwell",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaperwellPrintplanInput"
              },
              "examples": {
                "example1": {
                  "summary": "Try an example",
                  "value": {}
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaperwellPrintplanResult"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      },
      "PaperwellPrintplanInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "width": {
            "title": "Target width (mm)",
            "type": "number",
            "minimum": 10,
            "maximum": 5000,
            "default": 400
          },
          "height": {
            "title": "Target height (mm)",
            "type": "number",
            "minimum": 10,
            "maximum": 5000,
            "default": 300
          },
          "source": {
            "title": "SVG geometry (optional)",
            "type": "string",
            "maxLength": 200000,
            "default": ""
          },
          "paper": {
            "title": "Paper",
            "type": "string",
            "enum": [
              "a4",
              "letter"
            ],
            "default": "a4"
          },
          "orientation": {
            "title": "Orientation",
            "type": "string",
            "enum": [
              "auto",
              "portrait",
              "landscape"
            ],
            "default": "auto"
          },
          "aspect": {
            "title": "Scale artwork",
            "type": "string",
            "enum": [
              "stretch",
              "contain"
            ],
            "default": "stretch"
          },
          "overlap": {
            "title": "Overlap (mm)",
            "type": "number",
            "minimum": 0,
            "maximum": 40,
            "default": 15
          },
          "margin": {
            "title": "Printer margin (mm)",
            "type": "number",
            "minimum": 5,
            "maximum": 40,
            "default": 10
          },
          "title": {
            "title": "Project title",
            "type": "string",
            "maxLength": 100,
            "default": "PrintPlan"
          }
        },
        "required": []
      },
      "PaperwellPrintplanResult": {
        "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": [
              "rows",
              "columns",
              "sheets",
              "widthMm",
              "heightMm",
              "orientation",
              "margin",
              "overlap",
              "geometryCount",
              "printPages",
              "printableWidthMm",
              "printableHeightMm",
              "layouts",
              "pages",
              "svg"
            ],
            "properties": {
              "rows": {
                "type": "number"
              },
              "columns": {
                "type": "number"
              },
              "sheets": {
                "type": "number"
              },
              "widthMm": {
                "type": "number"
              },
              "heightMm": {
                "type": "number"
              },
              "orientation": {
                "type": "string"
              },
              "margin": {
                "type": "number"
              },
              "overlap": {
                "type": "number"
              },
              "geometryCount": {
                "type": "number"
              },
              "printPages": {
                "type": "number"
              },
              "printableWidthMm": {
                "type": "number"
              },
              "printableHeightMm": {
                "type": "number"
              },
              "layouts": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "paper",
                    "orientation",
                    "rows",
                    "columns",
                    "printPages",
                    "sheets",
                    "available",
                    "pageWidthMm",
                    "pageHeightMm",
                    "printableWidthMm",
                    "printableHeightMm",
                    "stepX",
                    "stepY"
                  ],
                  "properties": {
                    "paper": {
                      "type": "string"
                    },
                    "orientation": {
                      "type": "string"
                    },
                    "rows": {
                      "type": "number"
                    },
                    "columns": {
                      "type": "number"
                    },
                    "printPages": {
                      "type": "number"
                    },
                    "sheets": {
                      "type": "number"
                    },
                    "available": {
                      "type": "boolean"
                    },
                    "pageWidthMm": {
                      "type": "number"
                    },
                    "pageHeightMm": {
                      "type": "number"
                    },
                    "printableWidthMm": {
                      "type": "number"
                    },
                    "printableHeightMm": {
                      "type": "number"
                    },
                    "stepX": {
                      "type": "number"
                    },
                    "stepY": {
                      "type": "number"
                    }
                  }
                }
              },
              "pages": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "label",
                    "pdfPage",
                    "row",
                    "column",
                    "xMm",
                    "yMm"
                  ],
                  "properties": {
                    "label": {
                      "type": "string"
                    },
                    "pdfPage": {
                      "type": "number"
                    },
                    "row": {
                      "type": "number"
                    },
                    "column": {
                      "type": "number"
                    },
                    "xMm": {
                      "type": "number"
                    },
                    "yMm": {
                      "type": "number"
                    }
                  }
                }
              },
              "svg": {
                "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"
              }
            }
          }
        }
      }
    }
  }
}