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
POST https://puttopiashotsimulator.usefulweb.app/api/v1/calculate– run Minigolf Shot SimulatorGET https://puttopiashotsimulator.usefulweb.app/api/v1/tool– inputs, output schema, examples- OpenAPI 3.1: /openapi.json · /openapi.yaml
- Errors:
application/problem+json;422includes per-fielderrors.
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.
| Field | Type | Default | Description |
|---|---|---|---|
course | select (candy, pirate, space, custom) | "candy" | Course |
hole | integer | 1 | Hole number (1–9) |
customHole | textarea | — | 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. |
x | number | — | Ball x (tiles, empty = tee) |
y | number | — | Ball y (tiles, empty = tee) |
angle | number | 270 | Direction (degrees: 0 east, 90 south, 180 west, 270 north) |
power | number | 0.6 | Power (0 to 1) |
t0 | integer | 0 | Obstacle 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)
- Streamable HTTP endpoint:
https://puttopiashotsimulator.usefulweb.app/mcp– protocol revisions 2026-07-28 (stateless) and 2025-11-25 / 2025-06-18 / 2025-03-26 (initialize handshake). - Tools:
puttopia_shot_simulator - Local stdio connector:
node src/mcp-stdio.ts --tool=puttopia-shot-simulator
{
"mcpServers": {
"puttopia-shot-simulator": { "type": "http", "url": "https://puttopiashotsimulator.usefulweb.app/mcp" }
}
}