API & MCP

Everything a person can do on Minigolf Shot Simulator, a program or AI agent can do with the same inputs and get the identical result.

HTTP API

Minigolf Shot Simulator

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.

Inputs of Minigolf Shot Simulator
FieldTypeDefaultDescription
courseselect (candy, pirate, space, custom)"candy"Course
holeinteger1Hole number (1–9)
customHoletextarea—Custom hole (JSON, only for “Custom hole”). Tiles as text rows (. void, # block, g green, s sand, i ice, w water, B bridge, > < ^ 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.
xnumber—Ball x (tiles, empty = tee)
ynumber—Ball y (tiles, empty = tee)
anglenumber270Direction (degrees: 0 east, 90 south, 180 west, 270 north)
powernumber0.6Power (0 to 1)
t0integer0Obstacle clock at the putt (ticks of 1/120 s). Windmills, moving blocks and rafts depend on the time of the putt.

Example request

Candy Land hole 1, straight up the middle

curl -X POST https://puttopiashotsimulator.usefulweb.app/api/v1/calculate -H 'content-type: application/json' -d '{"course":"candy","hole":1,"angle":270,"power":0.78}'

Every result contains

inputs (normalised, defaults applied), summary, result (validated against the published schema), units, assumptions, sources, warnings, computedAt and links.

MCP (Model Context Protocol)

{
  "mcpServers": {
    "puttopia-shot-simulator": { "type": "http", "url": "https://puttopiashotsimulator.usefulweb.app/mcp" }
  }
}