{"openapi":"3.1.0","info":{"title":"Story Prompt API","version":"0.1.0","description":"A real, stateless, playable collaborative-story game session engine with a 100+ original story-starter bank across genres, running word/contribution tracking, a genuine trigger-based plot-twist mechanic backed by a 40+ original twist bank, and a real length-threshold wrap-up nudge. Every tool call takes the full session state and returns the new state; nothing is stored server-side.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://storyprompt.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/storyprompt/docs"},"termsOfService":"https://connectorbay.com/storyprompt/terms"},"servers":[{"url":"https://storyprompt.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/storyprompt/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/list_genres":{"post":{"operationId":"list_genres","summary":"Lists the story-starter genres available. Use for \"what genres do you have\".","description":"Lists the story-starter genres available. Use for \"what genres do you have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_genresArguments","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/new_story":{"post":{"operationId":"new_story","summary":"Starts a fresh collaborative story with an original opening line. Use for \"let's write a","description":"Starts a fresh collaborative story with an original opening line. Use for \"let's write a\n    story together\", \"give me a story starter\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"genre":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Optional genre to pick the opener from. See list_genres. Omit for a random genre.","title":"Genre"}},"title":"new_storyArguments","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/continue_story":{"post":{"operationId":"continue_story","summary":"Appends a contribution to the story and returns the updated word/contribution counts plus","description":"Appends a contribution to the story and returns the updated word/contribution counts plus\n    the full story so far. Use for \"add my part\", \"here's what happens next\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current session state, exactly as returned by new_story/continue_story/plot_twist_prompt.","examples":[{"contributions_count":0,"contributions_since_last_twist":0,"genre":"fantasy","opener_id":"sp_001","story":[{"author":"opener","text":"..."}],"used_twist_ids":[],"word_count":18}],"title":"State","type":"object"},"contribution":{"description":"The player's next piece of the story, appended verbatim.","title":"Contribution","type":"string"},"author":{"default":"player","description":"Label for who contributed this part, e.g. a player's name. Purely descriptive.","title":"Author","type":"string"}},"required":["state","contribution"],"title":"continue_storyArguments","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/plot_twist_prompt":{"post":{"operationId":"plot_twist_prompt","summary":"Checks whether a plot twist is due (a real trigger: TWIST_EVERY_N contributions — currently 4","description":"Checks whether a plot twist is due (a real trigger: TWIST_EVERY_N contributions — currently 4\n    — since the last twist, not random) and, if so, injects a fresh original twist into the story\n    and resets the counter. If not due yet, reports triggered:false and how many contributions\n    remain. Use to periodically check \"is it twist time\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current session state, exactly as returned by new_story/continue_story/plot_twist_prompt.","examples":[{"contributions_count":0,"contributions_since_last_twist":0,"genre":"fantasy","opener_id":"sp_001","story":[{"author":"opener","text":"..."}],"used_twist_ids":[],"word_count":18}],"title":"State","type":"object"}},"required":["state"],"title":"plot_twist_promptArguments","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/wrap_up_prompt":{"post":{"operationId":"wrap_up_prompt","summary":"Checks whether the story has crossed a real length threshold (currently 120 words OR 10","description":"Checks whether the story has crossed a real length threshold (currently 120 words OR 10\n    contributions, whichever comes first) and, if so, suggests nudging toward an ending. Use for\n    \"should we start wrapping this up\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current session state, exactly as returned by new_story/continue_story/plot_twist_prompt.","examples":[{"contributions_count":0,"contributions_since_last_twist":0,"genre":"fantasy","opener_id":"sp_001","story":[{"author":"opener","text":"..."}],"used_twist_ids":[],"word_count":18}],"title":"State","type":"object"}},"required":["state"],"title":"wrap_up_promptArguments","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/render":{"post":{"operationId":"render","summary":"A human-readable rendering of the full story so far, with each part labeled (opener, a","description":"A human-readable rendering of the full story so far, with each part labeled (opener, a\n    contributor, or TWIST). Use for \"read back the story\", \"show me what we have so far\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current session state, exactly as returned by new_story/continue_story/plot_twist_prompt.","examples":[{"contributions_count":0,"contributions_since_last_twist":0,"genre":"fantasy","opener_id":"sp_001","story":[{"author":"opener","text":"..."}],"used_twist_ids":[],"word_count":18}],"title":"State","type":"object"}},"required":["state"],"title":"renderArguments","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}}}}