{"openapi":"3.1.0","info":{"title":"Murder API","version":"0.1.0","description":"A fully local, hand-curated murder-mystery PARTY GAME design reference (the lighthearted fictional whodunit party genre, not true crime): common hosting formats, clue design principles, character/role assignment tips, red herring design, a computed reveal-timeline/pacing tool, a term glossary, format matching by group size and experience level, and beginner-host tips. Keyless; fully local; zero upstream calls.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://murder.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/murder/docs"},"termsOfService":"https://connectorbay.com/murder/terms"},"servers":[{"url":"https://murder.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/murder/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/format_info":{"post":{"operationId":"format_info","summary":"Full detail for one murder-mystery-party hosting format: how it works, best group size and","description":"Full detail for one murder-mystery-party hosting format: how it works, best group size and\n    experience level, typical duration, host effort, and pros/cons. Use for \"what's a pre-scripted\n    kit\", \"how does a self-run packet format work\", \"explain the escape-room hybrid format\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A hosting format's name or alias.","examples":["pre-scripted kit","gamemaster-improvised","escape-room hybrid","virtual party"],"minLength":1,"title":"Name","type":"string"}},"required":["name"],"title":"format_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/clue_design_tip":{"post":{"operationId":"clue_design_tip","summary":"One practical clue-design principle for a murder mystery party, keyed by topic — or, with no","description":"One practical clue-design principle for a murder mystery party, keyed by topic — or, with no\n    topic, the full list of tip topics. Use for \"how many clues should point to each suspect\", \"how\n    do I avoid the table solving the case too early\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A clue-design topic to look up; omit to list every tip topic.","examples":["means motive and opportunity","clue distribution","corroboration","chekhov's gun"],"title":"Topic"}},"title":"clue_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/character_role_tip":{"post":{"operationId":"character_role_tip","summary":"One practical tip for casting, writing or assigning characters in a murder mystery party, keyed","description":"One practical tip for casting, writing or assigning characters in a murder mystery party, keyed\n    by topic — or, with no topic, the full list of tip topics. Use for \"how do I pick who plays the\n    killer\", \"how do I write a good alibi\", \"should the host also play a character\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A character/role topic to look up; omit to list every tip topic.","examples":["writing a convincing motive","choosing who plays the killer","designing alibis","wildcard role"],"title":"Topic"}},"title":"character_role_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/red_herring_design_tip":{"post":{"operationId":"red_herring_design_tip","summary":"Every red-herring design principle at once: giving misdirection real motive, pairing it with a","description":"Every red-herring design principle at once: giving misdirection real motive, pairing it with a\n    real non-murder secret, limiting how many you use, physical vs. behavioral misdirection, and\n    keeping the mystery fair-play. Use for \"how do I design a good red herring\", \"how many red\n    herrings is too many\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"red_herring_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/pacing_structure":{"post":{"operationId":"pacing_structure","summary":"Computes a genuine reveal-timeline for a stated party size and total duration — real","description":"Computes a genuine reveal-timeline for a stated party size and total duration — real\n    arithmetic, not a lookup. Returns how many investigation rounds fit, a minute-by-minute phase\n    breakdown (welcome/briefing, each investigation round, final deliberation, the reveal), a\n    suggested mid-party break for longer sessions, and recommended clue/red-herring/named-character\n    counts scaled to the group size. Use for \"plan a timeline for a 3-hour party with 10 guests\",\n    \"how many investigation rounds should a 2-hour mystery have\", \"how many clues do I need for 8 players\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"party_size":{"description":"Number of players attending.","examples":[6,10,16],"maximum":40,"minimum":3,"title":"Party Size","type":"integer"},"duration_minutes":{"description":"Total planned length of the party, in minutes.","examples":[90,150,240],"maximum":480,"minimum":30,"title":"Duration Minutes","type":"integer"}},"required":["party_size","duration_minutes"],"title":"pacing_structureArguments","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 common murder-mystery-party vocabulary — whodunit, gamemaster, dossier, red","description":"Definitions of common murder-mystery-party vocabulary — whodunit, gamemaster, dossier, red\n    herring, means/motive/opportunity, alibi, floater role, wildcard, cold open, fair-play mystery,\n    and more. Use for \"what does 'red herring' mean here\", \"what's a floater role\".","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_format_for_group":{"post":{"operationId":"find_format_for_group","summary":"Scores every hosting format by how well its designed player-count range fits `group_size` (a","description":"Scores every hosting format by how well its designed player-count range fits `group_size` (a\n    size outside the format's range loses points with distance), plus a bonus if `experience_level`\n    matches, and returns the best-fitting formats. Use for \"what format works best for 6 beginners\",\n    \"best murder mystery format for a 20-person office party\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"group_size":{"description":"How many players will be playing.","examples":[4,8,20],"maximum":60,"minimum":1,"title":"Group Size","type":"integer"},"experience_level":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The group's experience with murder mystery parties, if known.","examples":["beginner","intermediate","experienced"],"title":"Experience Level"}},"required":["group_size"],"title":"find_format_for_groupArguments","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 ranked shortlist of general tips for someone hosting their first murder mystery party —","description":"A ranked shortlist of general tips for someone hosting their first murder mystery party —\n    picking an easy format, briefing the killer, handling a no-show, and more. Use for \"tips for\n    hosting my first mystery night\", \"what should a first-time host know\".","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}}}}