API & MCP
Everything a person can do on Minigolf Hole Checker, a program or AI agent can do with the same inputs and get the identical result.
HTTP API
POST https://puttopiaholecheck.usefulweb.app/api/v1/calculate– run Minigolf Hole CheckerGET https://puttopiaholecheck.usefulweb.app/api/v1/tool– inputs, output schema, examples- OpenAPI 3.1: /openapi.json · /openapi.yaml
- Errors:
application/problem+json;422includes per-fielderrors.
Minigolf Hole Checker
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.
| Field | Type | Default | Description |
|---|---|---|---|
course | select (candy, pirate, space, custom) | "candy" | Course |
hole | integer | 1 | Hole number (1–9) |
customHole | textarea | "{\"name\":\"Bumper alley\",\"par\":3,\"theme\":\"candy\",\"tiles\":[\"ggggg\",\ | 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. |
caddie | boolean | true | Let the caddie play the hole |
Example request
Your own hole: bumper alley
curl -X POST https://puttopiaholecheck.usefulweb.app/api/v1/calculate -H 'content-type: application/json' -d '{"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}'
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://puttopiaholecheck.usefulweb.app/mcp– protocol revisions 2026-07-28 (stateless) and 2025-11-25 / 2025-06-18 / 2025-03-26 (initialize handshake). - Tools:
puttopia_hole_check - Local stdio connector:
node src/mcp-stdio.ts --tool=puttopia-hole-check
{
"mcpServers": {
"puttopia-hole-check": { "type": "http", "url": "https://puttopiaholecheck.usefulweb.app/mcp" }
}
}