{"openapi":"3.1.0","info":{"title":"Flipper API","version":"0.1.0","description":"A fully local, hand-curated original pinball reference: machine eras from bagatelle games through electromechanical, solid-state, dot-matrix and modern digital pinball; scoring concepts (multiball, skill shots, wizard modes, jackpots, combos); playing terminology; generic playing techniques (nudging, live catch, post pass); playfield anatomy; and competitive/high-score pinball culture.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://flipper.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/flipper/docs"},"termsOfService":"https://connectorbay.com/flipper/terms"},"servers":[{"url":"https://flipper.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/flipper/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/era_info":{"post":{"operationId":"era_info","summary":"Full detail on one pinball machine era — year range, characteristics, and how it transitioned in and","description":"Full detail on one pinball machine era — year range, characteristics, and how it transitioned in and\n    out — or, with no name given, a list of every era. Use for \"what was the electromechanical era\",\n    \"when did solid-state pinball start\", \"what changed in the dot-matrix era\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A pinball machine era's name or alias; omit to list every era.","examples":["electromechanical","solid-state","dot-matrix","modern digital"],"title":"Name"}},"title":"era_infoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/find_era_by_year":{"post":{"operationId":"find_era_by_year","summary":"Returns which pinball machine era a given calendar year falls into. Use for \"what era is a 1972","description":"Returns which pinball machine era a given calendar year falls into. Use for \"what era is a 1972\n    pinball machine from\", \"what year did modern pinball start\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"year":{"description":"A calendar year.","examples":[1955,1985,1995,2020],"maximum":2100,"minimum":1850,"title":"Year","type":"integer"}},"required":["year"],"title":"find_era_by_yearArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/scoring_concept":{"post":{"operationId":"scoring_concept","summary":"Explains a pinball scoring concept or mechanic — multiball, skill shot, wizard mode, jackpot, combo,","description":"Explains a pinball scoring concept or mechanic — multiball, skill shot, wizard mode, jackpot, combo,\n    mode stacking, extra ball, replay, match, video mode, add-a-ball, bonus multiplier, hurry-up, mystery\n    award, ball save, progressive award — described generically, or with no name given, a list of all of\n    them. Use for \"what is a wizard mode in pinball\", \"explain multiball jackpots\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A scoring concept's name; omit to list all.","examples":["multiball","skill shot","wizard mode","jackpot","combo"],"title":"Name"}},"title":"scoring_conceptArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/term_glossary":{"post":{"operationId":"term_glossary","summary":"Defines common pinball vocabulary and slang — tilt, nudge, drain, SDTM, outlane, inlane, kickback,","description":"Defines common pinball vocabulary and slang — tilt, nudge, drain, SDTM, outlane, inlane, kickback,\n    trough, brick, airball, swish, rattle, and more — or, with no term given, the full glossary. Use for\n    \"what does SDTM mean in pinball\", \"what's an outlane\", \"what's the difference between an inlane and\n    outlane\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific pinball term to look up; omit to list all.","examples":["tilt","SDTM","outlane","drain","brick"],"title":"Term"}},"title":"term_glossaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/technique_info":{"post":{"operationId":"technique_info","summary":"Explains a generic pinball playing technique — nudging, live catch, cradle separation, post pass, tap","description":"Explains a generic pinball playing technique — nudging, live catch, cradle separation, post pass, tap\n    pass, drop catch, slap save, stall, bang-back, dead bounce — described in general terms as it applies\n    across machines, not tied to any single trademarked title; or, with no name given, a list of all\n    techniques. Use for \"how do you nudge a pinball machine without tilting\", \"what is a live catch\", \"what's\n    a post pass\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A playing technique's name; omit to list all.","examples":["nudging","live catch","post pass","cradle separation","bang-back"],"title":"Name"}},"title":"technique_infoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/anatomy_info":{"post":{"operationId":"anatomy_info","summary":"Explains a physical pinball machine part — flipper, pop bumper, slingshot, ramp, drop target, standup","description":"Explains a physical pinball machine part — flipper, pop bumper, slingshot, ramp, drop target, standup\n    target, plunger, ball trough, kicker/VUK, backglass, playfield glass, cabinet, magnet, and more — or, with\n    no part name given, a list of every part. Use for \"what is a slingshot on a pinball table\", \"what's a\n    VUK\", \"what does the apron do\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"part_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A playfield or cabinet part's name; omit to list all.","examples":["flipper","pop bumper","slingshot","drop target","backglass"],"title":"Part Name"}},"title":"anatomy_infoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/competitive_culture_note":{"post":{"operationId":"competitive_culture_note","summary":"Covers a topic in competitive or high-score pinball culture — IFPA world rankings, PAPA and its world","description":"Covers a topic in competitive or high-score pinball culture — IFPA world rankings, PAPA and its world\n    championship, match-play tournament format, head-to-head format, on-machine high score culture, local\n    leagues, on-location play vs. home collecting, the restoration/preservation hobby, streaming, and\n    grassroots inclusion groups — or, with no topic given, a list of all of them. Use for \"how does\n    competitive pinball ranking work\", \"what's match play in pinball tournaments\", \"what is IFPA\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A competitive/high-score pinball culture topic; omit to list all.","examples":["IFPA","match play","high score culture","leagues","restoration"],"title":"Topic"}},"title":"competitive_culture_noteArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/beginner_tips":{"post":{"operationId":"beginner_tips","summary":"A curated list of tips for a pinball beginner, ordered from most to least essential. Use for \"give me","description":"A curated list of tips for a pinball beginner, ordered from most to least essential. Use for \"give me\n    some pinball tips\", \"how do I get better at pinball as a beginner\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"count":{"default":5,"description":"How many tips to return.","maximum":10,"minimum":1,"title":"Count","type":"integer"}},"title":"beginner_tipsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}