{ "openapi": "3.1.1", "info": { "title": "Plinko Name Picker API", "version": "1.0.0", "summary": "Drop a ball through pegs to pick a name — fair, replayable and provable.", "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://fielddayplinkopicker.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Drop a ball through pegs to pick a name — fair, replayable and provable.", "description": "Pick one or more names with a physics plinko board. The organiser publishes a SHA-256 fingerprint of a secret before the drop, the audience adds a word, and afterwards anyone can replay the exact drop here and check that every name had the same chance.\n\nMethodology:\n- Fairness proof (commit-reveal): fingerprint = SHA-256 of “fieldday-party-v1|plinko|\u003centries and settings as sorted JSON\u003e|\u003csecret\u003e”. It is shown before the drop, so the secret and the list cannot change unnoticed. The random numbers come from SHA-256 of the secret plus the audience word, which is chosen after the fingerprint is public.\n- Physics: a ball (radius 9.6) falls under gravity (900 units/s², step 1/240 s) through rows of pegs 40 units apart, bouncing off pegs and walls with restitution 0.45 and a small random spin on every peg hit. It starts above the centre with a random offset. Only +, −, ×, ÷ and square roots are used, so every JavaScript engine replays the identical path.\n- Why names are equally likely: before each drop the names are shuffled onto the slots (Fisher–Yates; one slot per name, small lists repeat to at least 8 slots so each name holds equally many). Real boards favour some slots, but because every name is equally likely to sit on every slot, each name wins with probability exactly 1 / number of names (up to the 32-bit resolution of the generator).\n- Several picks: the winner leaves, a new board is laid out for the remaining names and a new ball drops. The optional fairness check repeats the drop with test seeds and reports slot counts, name counts and a chi-square statistic against equal chances.\n\nFor games, chores and small prizes. Without a secret the draw is predictable. For legally regulated lotteries follow the rules that apply to you.", "tags": [ "apps" ], "x-mcp-tool": "fieldday_plinko_picker", "x-owner-app": "fieldday", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FielddayPlinkoPickerInput" }, "examples": { "example1": { "summary": "Who picks the film tonight? (secret + audience word)", "value": { "names": [ "Ana", "Ben", "Cleo", "Dev", "Eli", "Fay" ], "picks": 1, "rows": 12, "secret": "7f3a9c2e51d84b06", "audienceWord": "pineapple" } }, "example2": { "summary": "Three prize winners with a fairness check", "value": { "names": [ "Mia", "Noah", "Lena", "Omar", "Sofia", "Jonas", "Aylin", "Paul", "Emma", "Yusuf" ], "picks": 3, "rows": 10, "secret": "raffle-2026-secret-41b7", "audienceWord": "confetti", "checkDrops": 500 } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FielddayPlinkoPickerResult" } } } }, "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" } } } } } }, "FielddayPlinkoPickerInput": { "type": "object", "additionalProperties": false, "properties": { "names": { "title": "Names (one per line)", "type": "array", "items": { "type": "string" }, "maxItems": 40 }, "picks": { "title": "How many to pick (one ball each, winners leave the board)", "type": "integer", "minimum": 1, "maximum": 10, "default": 1 }, "rows": { "title": "Peg rows", "type": "integer", "minimum": 6, "maximum": 16, "default": 12 }, "secret": { "title": "Secret (revealed after the draw)", "description": "The organiser’s random secret. Its fingerprint is shown before the draw; empty = derived from the entries (predictable, only for demos).", "type": "string", "maxLength": 128 }, "audienceWord": { "title": "Audience word (optional)", "description": "A word someone calls out after the fingerprint is shown. It changes the draw, so the organiser cannot steer it.", "type": "string", "maxLength": 60 }, "checkDrops": { "title": "Fairness check: extra test drops (0 = off)", "description": "Counts where test balls land and which names they pick, to show the board’s bias and that names are still equally likely.", "type": "integer", "minimum": 0, "maximum": 1000, "default": 0 } }, "required": [ "names" ] }, "FielddayPlinkoPickerResult": { "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": [ "names", "picks", "rows", "fingerprint", "proof", "secret", "audienceWord", "secretDerived", "probability", "winners", "drops", "check" ], "properties": { "names": { "type": "array", "items": { "type": "string" } }, "picks": { "type": "integer" }, "rows": { "type": "integer" }, "fingerprint": { "type": "string" }, "proof": { "type": "string" }, "secret": { "type": "string" }, "audienceWord": { "type": "string" }, "secretDerived": { "type": "boolean" }, "probability": { "type": "number" }, "winners": { "type": "array", "items": { "type": "string" } }, "drops": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "pick", "slots", "labels", "slot", "winner", "bounces", "seconds", "path" ], "properties": { "pick": { "type": "integer" }, "slots": { "type": "integer" }, "labels": { "type": "array", "items": { "type": "string" } }, "slot": { "type": "integer" }, "winner": { "type": "string" }, "bounces": { "type": "integer" }, "seconds": { "type": "number" }, "path": { "type": "array", "items": { "type": "array", "items": { "type": "number" } } } } } }, "check": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "drops", "slotCounts", "nameCounts", "expectedPerName", "chiSquare", "degreesOfFreedom", "slotSpread" ], "properties": { "drops": { "type": "integer" }, "slotCounts": { "type": "array", "items": { "type": "integer" } }, "nameCounts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "count" ], "properties": { "name": { "type": "string" }, "count": { "type": "integer" } } } }, "expectedPerName": { "type": "number" }, "chiSquare": { "type": "number" }, "degreesOfFreedom": { "type": "integer" }, "slotSpread": { "type": "integer" } } } } }, "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" } } } } } } } }