{
  "openapi": "3.1.1",
  "info": {
    "title": "Minigolf Shot Simulator API",
    "version": "1.0.0",
    "summary": "Simulate one putt on a Puttopia hole: path, bounces, portals, water and whether it drops.",
    "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://puttopiashotsimulator.usefulweb.app"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Simulate one putt on a Puttopia hole: path, bounces, portals, water and whether it drops.",
        "description": "Rolls one putt with Puttopia’s deterministic minigolf physics on a built-in hole (Candy Land, Pirate Cove, Space Station) or your own hole: friction per surface, slopes, conveyor belts, bounces off walls and bumpers, rotating windmills, moving obstacles, portals, loop-de-loops and water. Shows the path from above and where the ball stops — exactly as the game rolls it.\n\nMethodology:\n- One tile is one unit (about a metre on a real course). The ball has a radius of 0.11 tiles, the cup 0.2. The putt starts at 0.35 + power × 5.65 tiles per second in the given direction; 0° points east (+x) and angles grow clockwise in the top view, so 270° points north, away from the tee in most holes.\n- The ball is integrated with a fixed time step of 1/120 s. Each step: forces (slopes 1.3 tiles/s² downhill, conveyor belts push up to 1.7 tiles/s, the cup pulls 4.5 tiles/s² toward its centre), rolling friction per surface (green and bridges 0.9, sand 3.4, ice 0.22 tiles/s²), movement, then collisions.\n- Walls and blocks bounce with a restitution of 0.72 and a little grip along the wall; bumpers kick back with 1.12 and at least 1.2 tiles/s; windmill blades and moving obstacles bounce relative to their own speed. Portals keep the ball’s speed and direction. A loop needs the speed given on the hole (usually 2.6 tiles/s) when the ball enters it; slower balls roll back.\n- The ball drops when it is over the cup slower than 1.35 tiles/s; faster balls lip out. Water and leaving the course cost a penalty stroke and the ball goes back to where the putt started. The putt ends when the ball is still or after 40 seconds.\n- Windmills, moving blocks and rafts follow the obstacle clock; the same hole, ball position, direction, power and clock always give the same path. Sines and cosines are computed with plain arithmetic so every browser and the server agree bit for bit.\n\nA game model for Puttopia, not a physics simulation of a real golf ball, green or course.",
        "tags": [
          "apps"
        ],
        "x-mcp-tool": "puttopia_shot_simulator",
        "x-owner-app": "puttopia",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PuttopiaShotSimulatorInput"
              },
              "examples": {
                "example1": {
                  "summary": "Candy Land hole 1, straight up the middle",
                  "value": {
                    "course": "candy",
                    "hole": 1,
                    "angle": 270,
                    "power": 0.78
                  }
                },
                "example2": {
                  "summary": "Through the loop-de-loop (Candy Land 7)",
                  "value": {
                    "course": "candy",
                    "hole": 7,
                    "angle": 270,
                    "power": 0.65
                  }
                },
                "example3": {
                  "summary": "Bank shot off a bumper on your own hole",
                  "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}]}",
                    "angle": 260,
                    "power": 0.78
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PuttopiaShotSimulatorResult"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      },
      "PuttopiaShotSimulatorInput": {
        "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": ""
          },
          "x": {
            "title": "Ball x (tiles, empty = tee)",
            "type": "number",
            "minimum": 0,
            "maximum": 30
          },
          "y": {
            "title": "Ball y (tiles, empty = tee)",
            "type": "number",
            "minimum": 0,
            "maximum": 30
          },
          "angle": {
            "title": "Direction (degrees: 0 east, 90 south, 180 west, 270 north)",
            "type": "number",
            "minimum": -360,
            "maximum": 720,
            "default": 270,
            "x-unit": "°"
          },
          "power": {
            "title": "Power (0 to 1)",
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "default": 0.6
          },
          "t0": {
            "title": "Obstacle clock at the putt (ticks of 1/120 s)",
            "description": "Windmills, moving blocks and rafts depend on the time of the putt.",
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000,
            "default": 0
          }
        },
        "required": []
      },
      "PuttopiaShotSimulatorResult": {
        "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",
              "putt",
              "holed",
              "water",
              "strokes",
              "end",
              "straightDistance",
              "routeDistance",
              "seconds",
              "ticks",
              "bounces",
              "eventCounts",
              "events",
              "path"
            ],
            "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"
                  }
                }
              },
              "putt": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "x",
                  "y",
                  "angle",
                  "power",
                  "t0",
                  "speed"
                ],
                "properties": {
                  "x": {
                    "type": "number"
                  },
                  "y": {
                    "type": "number"
                  },
                  "angle": {
                    "type": "number"
                  },
                  "power": {
                    "type": "number"
                  },
                  "t0": {
                    "type": "integer"
                  },
                  "speed": {
                    "type": "number"
                  }
                }
              },
              "holed": {
                "type": "boolean"
              },
              "water": {
                "type": "boolean"
              },
              "strokes": {
                "type": "integer"
              },
              "end": {
                "type": "array",
                "items": {
                  "type": "number"
                }
              },
              "straightDistance": {
                "type": "number"
              },
              "routeDistance": {
                "type": "number"
              },
              "seconds": {
                "type": "number"
              },
              "ticks": {
                "type": "integer"
              },
              "bounces": {
                "type": "integer"
              },
              "eventCounts": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                }
              },
              "events": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "second",
                    "type",
                    "x",
                    "y"
                  ],
                  "properties": {
                    "second": {
                      "type": "number"
                    },
                    "type": {
                      "type": "string"
                    },
                    "x": {
                      "type": "number"
                    },
                    "y": {
                      "type": "number"
                    }
                  }
                }
              },
              "path": {
                "type": "array",
                "items": {
                  "type": "array",
                  "items": {
                    "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"
              }
            }
          }
        }
      }
    }
  }
}