{
  "openapi": "3.1.1",
  "info": {
    "title": "Minigolf Hole Checker API",
    "version": "1.0.0",
    "summary": "Check a minigolf hole: playable, estimated par and how many putts a perfect caddie needs.",
    "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://puttopiaholecheck.usefulweb.app"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Check a minigolf hole: playable, estimated par and how many putts a perfect caddie needs.",
        "description": "Checks a Puttopia hole — built-in or made in the hole editor — for problems (start or cup off the course, cup unreachable, portal exits in the water), estimates its par from the route length and the hazards on it, counts surfaces and obstacles, and lets the caddie play it with the real physics to prove it can be holed.\n\nMethodology:\n- Errors: the start or the cup is not on playable floor, they are closer than 1.5 tiles, a portal exit is not on playable floor, or no route leads from the start to the cup. The route search walks through floor tiles (8 directions, no corner cutting), over bridges and the water a raft covers, and takes portals and loops as short cuts.\n- Estimated par = 2, plus 1 for every 8 tiles of route beyond the first 6, plus 1 when the hole has two or more hazards (windmills, moving blocks, loops, rafts, gates, water, sand), between 2 and 6.\n- The caddie tries 72 directions × 10 power levels with the real physics for each putt and plays the one that ends nearest the cup along the route (holed first, water last). It knows the physics exactly, so it is better than any person — treat its strokes as the best case.\n\nPar is an estimate for fun play, not an official minigolf rating.",
        "tags": [
          "apps"
        ],
        "x-mcp-tool": "puttopia_hole_check",
        "x-owner-app": "puttopia",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PuttopiaHoleCheckInput"
              },
              "examples": {
                "example1": {
                  "summary": "Your own hole: bumper alley",
                  "value": {
                    "course": "custom",
                    "customHole": "{\"name\":\"Bumper alley\",\"par\":3,\"theme\":\"candy\",\"tiles\":[\"ggggg\",\"ggggg\",\"ggggg\",\"ggggg\",\"ggggg\",\"ggggg\",\"ggggg\",\"ggggg\"],\"start\":[2.5,6.5],\"cup\":[2.5,1.2],\"objects\":[{\"type\":\"bumper\",\"x\":2.5,\"y\":4,\"r\":0.35}]}",
                    "caddie": true
                  }
                },
                "example2": {
                  "summary": "Pirate Cove hole 9: Whirlpool",
                  "value": {
                    "course": "pirate",
                    "hole": 9,
                    "customHole": "",
                    "caddie": true
                  }
                },
                "example3": {
                  "summary": "A broken hole: the cup sits in the water",
                  "value": {
                    "course": "custom",
                    "customHole": "{\"name\":\"Soggy\",\"tiles\":[\"ggg\",\"gwg\",\"ggg\",\"ggg\"],\"start\":[1.5,3.5],\"cup\":[1.5,1.5]}",
                    "caddie": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PuttopiaHoleCheckResult"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      },
      "PuttopiaHoleCheckInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "course": {
            "title": "Course",
            "type": "string",
            "enum": [
              "candy",
              "pirate",
              "space",
              "custom"
            ],
            "default": "candy"
          },
          "hole": {
            "title": "Hole number (1–9)",
            "type": "integer",
            "minimum": 1,
            "maximum": 9,
            "default": 1
          },
          "customHole": {
            "title": "Custom hole (JSON, only for “Custom hole”)",
            "description": "Tiles as text rows (. void, # block, g green, s sand, i ice, w water, B bridge, \u003e \u003c ^ v conveyor belts, E W N S slopes down toward east/west/north/south), start and cup as [x, y] in tiles, objects such as bumpers, windmills, portals and loops.",
            "type": "string",
            "maxLength": 20000,
            "default": "{\"name\":\"Bumper alley\",\"par\":3,\"theme\":\"candy\",\"tiles\":[\"ggggg\",\"ggggg\",\"ggggg\",\"ggggg\",\"ggggg\",\"ggggg\",\"ggggg\",\"ggggg\"],\"start\":[2.5,6.5],\"cup\":[2.5,1.2],\"objects\":[{\"type\":\"bumper\",\"x\":2.5,\"y\":4,\"r\":0.35}]}"
          },
          "caddie": {
            "title": "Let the caddie play the hole",
            "type": "boolean",
            "default": true
          }
        },
        "required": []
      },
      "PuttopiaHoleCheckResult": {
        "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": [
              "hole",
              "playable",
              "issues",
              "estimatedPar",
              "routeLength",
              "hazards",
              "tiles",
              "objects",
              "caddie"
            ],
            "properties": {
              "hole": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "id",
                  "name",
                  "par",
                  "theme",
                  "width",
                  "length"
                ],
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "par": {
                    "type": "integer"
                  },
                  "theme": {
                    "type": "string"
                  },
                  "width": {
                    "type": "integer"
                  },
                  "length": {
                    "type": "integer"
                  }
                }
              },
              "playable": {
                "type": "boolean"
              },
              "issues": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "level",
                    "code",
                    "message"
                  ],
                  "properties": {
                    "level": {
                      "enum": [
                        "error",
                        "warning"
                      ]
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              },
              "estimatedPar": {
                "type": "integer"
              },
              "routeLength": {
                "type": "number"
              },
              "hazards": {
                "type": "integer"
              },
              "tiles": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                }
              },
              "objects": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                }
              },
              "caddie": {
                "type": [
                  "object",
                  "null"
                ],
                "additionalProperties": false,
                "required": [
                  "strokes",
                  "holed",
                  "putts"
                ],
                "properties": {
                  "strokes": {
                    "type": "integer"
                  },
                  "holed": {
                    "type": "boolean"
                  },
                  "putts": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "angle",
                        "power"
                      ],
                      "properties": {
                        "angle": {
                          "type": "number"
                        },
                        "power": {
                          "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"
              }
            }
          }
        }
      }
    }
  }
}