{"openapi":"3.1.0","info":{"title":"Gamification API","version":"0.1.0","description":"A fully local, hand-curated reference on applying game-like mechanics to non-game contexts: 20 mechanics (points, badges, leaderboards, streaks, levels, quests, and more), 12 common pitfalls grounded in real behavioral-design research, 10 real-world application areas, a design glossary, practical design tips, and a beginner shortlist.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://gamification.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/gamification/docs"},"termsOfService":"https://connectorbay.com/gamification/terms"},"servers":[{"url":"https://gamification.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/gamification/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/mechanic_info":{"post":{"operationId":"mechanic_info","summary":"Full detail for one game mechanic applied outside of games: how it works, its psychological basis,","description":"Full detail for one game mechanic applied outside of games: how it works, its psychological basis,\n    what it's best used for, linked common pitfalls, and example application areas. Use for \"how do\n    streaks work\", \"what's the psychology behind badges\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A gamification mechanic's name or alias.","examples":["points","streaks","leaderboards","progress bars"],"minLength":1,"title":"Name","type":"string"}},"required":["name"],"title":"mechanic_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/pitfall_info":{"post":{"operationId":"pitfall_info","summary":"Full detail for one common gamification pitfall, grounded in real behavioral-design research:","description":"Full detail for one common gamification pitfall, grounded in real behavioral-design research:\n    description, research basis, how it typically shows up, and how to mitigate it. Use for \"what's the\n    overjustification effect\", \"why do leaderboards demotivate people\", \"what's Goodhart's law\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A gamification pitfall's name or alias.","examples":["overjustification effect","Goodhart's law","leaderboard demotivation","badge fatigue"],"minLength":1,"title":"Name","type":"string"}},"required":["name"],"title":"pitfall_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/application_area_info":{"post":{"operationId":"application_area_info","summary":"Full detail for one real-world area where gamification is commonly applied: a summary, its commonly","description":"Full detail for one real-world area where gamification is commonly applied: a summary, its commonly\n    used mechanics (linked by name), and domain-specific considerations or cautions. Use for \"how should I\n    gamify a fitness app\", \"what mechanics work for workplace training\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A real-world application area's name or alias.","examples":["fitness apps","education","workplace training","customer loyalty programs"],"minLength":1,"title":"Name","type":"string"}},"required":["name"],"title":"application_area_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/design_tip":{"post":{"operationId":"design_tip","summary":"A practical, actionable design tip for a specific gamification topic, with why it matters and a","description":"A practical, actionable design tip for a specific gamification topic, with why it matters and a\n    short example. Use for \"how should I design a streak\", \"what should I watch for with leaderboards\",\n    \"how do I avoid manipulative gamification\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"topic":{"description":"A design topic.","examples":["onboarding","streak design","leaderboard design","avoiding manipulative design","measurement"],"minLength":1,"title":"Topic","type":"string"}},"required":["topic"],"title":"design_tipArguments","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":"Definitions of gamification and behavioral-design terms — extrinsic/intrinsic motivation,","description":"Definitions of gamification and behavioral-design terms — extrinsic/intrinsic motivation,\n    self-determination theory, variable reward schedule, flow state, loss aversion, Goodhart's law,\n    streak, leaderboard, PBL triad, and more. Use for \"what's intrinsic motivation\", \"what's a variable\n    reward schedule\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific term to look up; omit to list all.","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/find_mechanic_for_goal":{"post":{"operationId":"find_mechanic_for_goal","summary":"Suggests 1-4 suitable mechanics for a stated goal, keyword-matched against each mechanic's summary,","description":"Suggests 1-4 suitable mechanics for a stated goal, keyword-matched against each mechanic's summary,\n    how it works, and best-used-for tags. Use for \"what mechanic should I use to increase daily use\",\n    \"how do I reward finishing a long process\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"goal_description":{"description":"A goal to accomplish, in plain language.","examples":["get people to open the app every day","reward completing a long multi-step process","encourage friendly competition among coworkers","make onboarding feel rewarding"],"minLength":1,"title":"Goal Description","type":"string"}},"required":["goal_description"],"title":"find_mechanic_for_goalArguments","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/category_list":{"post":{"operationId":"category_list","summary":"Every category in this reference (mechanics, pitfalls, application areas, glossary terms, design","description":"Every category in this reference (mechanics, pitfalls, application areas, glossary terms, design\n    tips, beginner tips) with how many entries each has. Use for \"what do you cover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"category_listArguments","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, ranked shortlist of the most essential gamification design principles to learn first,","description":"A curated, ranked shortlist of the most essential gamification design principles to learn first,\n    from most to least essential. Use for \"what should I know before I start gamifying something\".","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}}}}