{"openapi":"3.1.0","info":{"title":"WriteForYou MCP API","version":"0.1.0"},"paths":{"/api/mcp/list_models":{"post":{"tags":["mcp"],"summary":"List Models","description":"List LLM models the caller can pass via the `model` parameter\non `generate_story`, `revise_chapter`, `plan_revision`, etc.\n\nReturns `{models: [{id, label, ...}]}`. Omit `model` (or pass an\nempty string) to use the server default. No auth required.","operationId":"list_models","requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/EmptyInput"},{"type":"null"}],"title":"Input"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListModelsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/get_credits":{"post":{"tags":["mcp"],"summary":"Get Credits","description":"Report the authenticated user's billing and subscription state.\n\nFree, read-only probe. Use before a chargeable call to avoid a 402\nmid-flow and to surface whether WriteForYou Pro access is active.\n\nReturns entitlement plus credit_accounting. In subscription mode,\ncredit_accounting is legacy/free-trial bookkeeping and does not gate\naccess; use entitlement.allows_access and subscription.allows_access.","operationId":"get_credits","requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/EmptyInput"},{"type":"null"}],"title":"Input"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCreditsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/get_job_status":{"post":{"tags":["mcp"],"summary":"Get Job Status","description":"Lean status probe for a story, revision, asset, article, or chat op.\n\n`is_terminal` is the only terminal signal clients should use.\nPrefer wait_for_status over a client poll loop.","operationId":"get_job_status","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatusInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/wait_for_status":{"post":{"tags":["mcp"],"summary":"Wait For Status","description":"Block until the job reaches `target`/`until` (or timeout).\n\nCovers story writes, revisions, assets, articles, and chat\noperations via `kind`. On timeout returns current status with\ntimed_out=true — not an error.","operationId":"wait_for_status","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WaitForStatusInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/get_activity":{"post":{"tags":["mcp"],"summary":"Get Activity","description":"Agent-activity feed for one story or article job.","operationId":"get_activity","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetActivityInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivityResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/start_checkout":{"post":{"tags":["mcp"],"summary":"Start Checkout","operationId":"start_checkout","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartCheckoutInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/get_billing_portal":{"post":{"tags":["mcp"],"summary":"Get Billing Portal","operationId":"get_billing_portal","requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/EmptyInput"},{"type":"null"}],"title":"Input"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingPortalResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/sync_subscription":{"post":{"tags":["mcp"],"summary":"Sync Subscription","operationId":"sync_subscription","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncSubscriptionInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncSubscriptionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/start_article_job":{"post":{"tags":["mcp"],"summary":"Start Article Job","description":"Create an article job from a Codex MCP request and return its URL.\n\nThis is only the Created phase. The article writer's tone and style\nare server-side defaults, so callers provide the article request but\ndo not pass a tone field.","operationId":"start_article_job","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartArticleJobInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/attach_article_research":{"post":{"tags":["mcp"],"summary":"Attach Article Research","description":"Attach Codex/Claude research to an article job.\n\nDefault server mode stores the handoff, writes the first draft with\nthe server article writer, and returns the review URL. Client mode\n(`authoring_mode=\"client\"` or `server_llm=false`) stores the handoff\nand returns a no-server-LLM drafting brief; call this same tool again\nwith `base_text_hash` and `text` to commit the client-authored draft.","operationId":"attach_article_research","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachArticleResearchInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/upsert_article_note":{"post":{"tags":["mcp"],"summary":"Upsert Article Note","description":"Add or update a review note on an article draft.\n\nNotes can come from Codex or the website review UI. They stay visible\non the article page and are consumed by revise_article_from_notes.","operationId":"upsert_article_note","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertArticleNoteInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/resolve_article_note":{"post":{"tags":["mcp"],"summary":"Resolve Article Note","description":"Mark one article review note resolved without running a revision.","operationId":"resolve_article_note","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleNoteInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/delete_article_note":{"post":{"tags":["mcp"],"summary":"Delete Article Note","description":"Delete one article review note from an article job.","operationId":"delete_article_note","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArticleNoteInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/revise_article_from_notes":{"post":{"tags":["mcp"],"summary":"Revise Article From Notes","description":"Apply open article notes and produce the next draft revision.\n\nOpen review notes are the highest-priority edit contract and override\nstale original request constraints. If a note says to replace\ntitle/deck/body exactly and supplies Title:, Deck:, and Body: sections,\nthe replacement is applied deterministically without a server LLM call.\n\nDefault server mode uses the server article revision writer. Client\nmode (`authoring_mode=\"client\"` or `server_llm=false`) returns a\nno-server-LLM revision brief; call this same tool again with\n`base_text_hash` and revised Markdown `text` to commit.","operationId":"revise_article_from_notes","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviseArticleFromNotesInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/prepare_publish_draft":{"post":{"tags":["mcp"],"summary":"Prepare Publish Draft","description":"Prepare a draft-only publishing package.\n\nThis does not publish externally. It packages the final article so a\nhuman can approve and copy it into the configured destination.","operationId":"prepare_publish_draft","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreparePublishDraftInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/publish_article_draft":{"post":{"tags":["mcp"],"summary":"Publish Article Draft","description":"Create a draft article on Dev.to from the prepared publish package.\n\nThe Dev.to payload always uses published=false. This endpoint is\nidempotent: if the article already has a Dev.to draft id, it returns\nthe stored draft metadata instead of creating another draft.","operationId":"publish_article_draft","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishArticleDraftInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/list_articles":{"post":{"tags":["mcp"],"summary":"List Articles","description":"List article jobs owned by the caller.","operationId":"list_articles","requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/EmptyInput"},{"type":"null"}],"title":"Input"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListArticlesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/delete_article":{"post":{"tags":["mcp"],"summary":"Delete Article","description":"Delete one article job owned by the caller.","operationId":"delete_article","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/generate_asset":{"post":{"tags":["mcp"],"summary":"Generate Asset","description":"Start an async Writer visual-asset generation through DesignForYou.\n\nNormalizes a structured `asset-generation/v1` brief, then kicks off a\nbackground job that asks DesignForYou to recommend a template and\ncalls its `/api/mcp/generate` tool. Returns immediately with\n`{job_id, status: \"running\"}` — poll `get_asset_status` until the job\nis terminal. The expert image-edit path can take well over two\nminutes, so this never blocks the HTTP request. Pass\n`generation.session_id` to refine a previous result, and\n`generation.context_ids` to use prior DesignForYou designs as visual\nreferences.","operationId":"generate_asset","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateAssetInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/list_location_references":{"post":{"tags":["mcp"],"summary":"List Location References","description":"List durable reusable Writer location references saved on a story.","operationId":"list_location_references","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListLocationReferencesInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationReferencesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/set_location_reference":{"post":{"tags":["mcp"],"summary":"Set Location Reference","description":"Persist or update a reusable Writer location reference from a D4U asset.","operationId":"set_location_reference","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetLocationReferenceInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/delete_location_reference":{"post":{"tags":["mcp"],"summary":"Delete Location Reference","description":"Delete a saved Writer location reference from a story.","operationId":"delete_location_reference","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteLocationReferenceInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/generate_writer_scene_still":{"post":{"tags":["mcp"],"summary":"Generate Writer Scene Still","description":"Generate one full-bleed 16:9 scene still via hosted DesignForYou or local Grok CLI.","operationId":"generate_writer_scene_still","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateWriterSceneStillInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/set_scene_stills":{"post":{"tags":["mcp"],"summary":"Set Scene Stills","description":"Persist a generated selected-paragraph scene-stills grid on a chapter.","operationId":"set_scene_stills","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetSceneStillsInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/generate_cover":{"post":{"tags":["mcp"],"summary":"Generate Chapter Cover","description":"Generate a non-spoiler cover image for a chapter.\n\nReads the chapter, plans an establishing scene that sets the chapter up\nwithout revealing its climax or twist, grounds it on the featured cast's\nreference art (gpt-image-2 multi-reference edit — pose sheet preferred\nper character), and renders it through DesignForYou.\nReturns `{cover_job_id, status: \"running\"}` — poll\n`get_chapter_cover_status` until terminal. The generated cover is saved\non the chapter (`output_artifacts.chapters[n].cover`).","operationId":"generate_cover","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateChapterCoverInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/suggest_cover_scenes":{"post":{"tags":["mcp"],"summary":"Suggest Cover Scenes Route","description":"Suggest distinct one-line, non-spoiler establishing cover-scene ideas.\n\nCall on open for the first 3 ideas. Call again for MORE options — pass the\nalready-shown lines in `exclude` and any steer in `message` (and the running\n`messages`). Returns `{chapter, scenes: [str], editorial_summary}`.","operationId":"suggest_cover_scenes","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuggestCoverScenesInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/set_cover":{"post":{"tags":["mcp"],"summary":"Set Chapter Cover","description":"Persist a chosen generated image as the chapter's cover.\n\n`image` is an object returned by get_cover_image_status (`result.image`).\nReturns `{chapter, cover}`. Overwrites any existing cover for the chapter.","operationId":"set_cover","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetChapterCoverInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/list_stories":{"post":{"tags":["mcp"],"summary":"List Stories","description":"List every story in the caller's library.\n\nReturns a lightweight summary per story — no plan / cast / prose —\nsuitable for picking which `job_id` to drill into with `get_story`.\nEach entry includes status, title, synopsis, chapter count, model,\ntimestamps, and (when available) `story_url` for a click-through.\nCheap; safe to call frequently.","operationId":"list_stories","requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/EmptyInput"},{"type":"null"}],"title":"Input"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListStoriesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/upsert_chapter_note":{"post":{"tags":["mcp"],"summary":"Upsert Chapter Note","description":"Add or update a review note on a generated story chapter.\n\nNotes can come from Codex or the website reader UI. They stay visible\non the chapter and can be consumed by revise_chapter_from_notes.","operationId":"upsert_chapter_note","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertChapterNoteInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/delete_chapter_note":{"post":{"tags":["mcp"],"summary":"Delete Chapter Note","description":"Delete an open review note from a generated story chapter.","operationId":"delete_chapter_note","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteChapterNoteInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/generate_story":{"post":{"tags":["mcp"],"summary":"Generate Story","description":"Kick off a new story — planner + characterizer run in the background.\n\nStatus state machine:\n pending → in_progress → reviewing → in_progress → completed\n\nBy default the job settles at 'reviewing' so the caller can edit\nthe outline/cast via update_outline / update_characters and then\ncall start_writing. Pass auto_approve=true to skip review and go\nstraight to 'completed'.\n\nTerminal statuses: completed, failed, cancelled. Use\nwait_for_status to block until one is reached instead of polling\nget_job_status manually.","operationId":"generate_story","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateStoryInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoryMutationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/plan_story":{"post":{"tags":["mcp"],"summary":"Plan Story","description":"Granular alternative to generate_story — runs the PLANNER ONLY.\n\nCreates a fresh job and kicks off the planner in the background.\nSettles at status='outlining' with the plan committed; does NOT\nauto-chain into characterizer or setting research. Use this when\nyou want explicit control over each phase (call generate_cast and\nregenerate_setting separately afterwards).\n\nFor one-shot \"give me a complete story foundation\" use generate_story.\n\nReturns immediately with `{job_id, status: \"pending\", story_url?}`;\npoll get_job_status / wait_for_status for progress.","operationId":"plan_story","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanStoryInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/start_story_foundation":{"post":{"tags":["mcp"],"summary":"Start Story Foundation","description":"Create a premise-only story shell for the guided creation wizard.\n\nThis call deliberately performs no LLM work and creates no outline.\nThe intended sequence is research_world -> generate_cast ->\ngenerate_outline -> start_writing, allowing each artifact to be\nreviewed before it becomes context for the next one.","operationId":"start_story_foundation","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartStoryFoundationInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoryMutationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/generate_cast":{"post":{"tags":["mcp"],"summary":"Generate Cast","description":"Granular alternative to generate_story — runs the CHARACTERIZER ONLY.\n\nRequires either an approved world or an existing outline.\nKicks off cast generation in the background; settles at\nstatus='reviewing' with the cast committed. Does NOT auto-research\nthe world — call regenerate_setting if you need that.\n\nReturns immediately with `{job_id, status: \"starting\", story_url?}`.","operationId":"generate_cast","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/generate_outline":{"post":{"tags":["mcp"],"summary":"Generate Outline","description":"Generate the first and only outline from the approved world and cast.","operationId":"generate_outline","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoryMutationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/resume_writing":{"post":{"tags":["mcp"],"summary":"Resume Writing","description":"Resume chapter generation for a story with unwritten outlines.\n\nDetects the gap between `plan.chapter_outlines` and written\nchapters (those with non-empty text). Kicks off a background\nworker that writes only the missing chapters in outline order,\nseeding ledger context from chapters already on disk.\n\nUse when:\n - A prior generation failed or was cancelled mid-write.\n - The user grew the outline post-generation through the Outline\n chat (refine_outline → Apply) and wants the new chapter(s) written.\n\nNo-op if every outline already has a written chapter — settles the\nstory back at status='completed'. Refused (409) while a write or\nrevision is already in flight.","operationId":"resume_writing","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoryMutationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/write_chapter":{"post":{"tags":["mcp"],"summary":"Write Chapter","description":"Write one unwritten chapter by number, possibly out of order.\n\nDiffers from resume_writing in that the caller picks which chapter\ninstead of always starting from the lowest unwritten one. Useful\nwhen the user wants to attempt a later chapter after an earlier one\nfailed (e.g. an LLM safety rejection) and they don't want to\nre-trigger the failing chapter first.\n\nRefused (409) when the chapter has no outline, is already written,\nor another writing/revision job is in flight.","operationId":"write_chapter","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WriteChapterInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoryMutationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/get_chapter_text":{"post":{"tags":["mcp"],"summary":"Get Chapter Text","description":"Fetch text for a specific chapter revision — used when switching versions.","operationId":"get_chapter_text","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatHistoryInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetChapterTextResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/refresh_chapter_context":{"post":{"tags":["mcp"],"summary":"Refresh Chapter Context","description":"Regenerate continuity context for an existing chapter/revision.\n\nRe-runs the same continuity extractor used after chapter writes and\nfull chapter revisions. If the refreshed revision is the latest one,\nthe chapter-level metadata is refreshed too so future context ledgers\nsee the new facts.","operationId":"refresh_chapter_context","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshChapterContextInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/update_chapter_memory":{"post":{"tags":["mcp"],"summary":"Update Chapter Memory","description":"Edit saved continuity memory for a chapter/revision.\n\nThis is a manual correction path for bad extracted memory. It replaces\n`carry_forward_facts` on the selected revision (latest by default). If\nthe edited revision is the latest revision, the chapter-level memory is\nupdated too so future prior-context ledgers stop carrying stale facts.","operationId":"update_chapter_memory","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateChapterMemoryInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/get_story":{"post":{"tags":["mcp"],"summary":"Get Story","description":"Fetch the full story artifact — plan, cast, chapter prose, revisions.\n\nSafe to call in any state, but the heavy payload only becomes\nuseful once status is 'reviewing' (outline + cast populated) or\n'completed' (all chapters written). During 'pending' / 'in_progress'\nmost fields are empty — prefer get_job_status for cheap polling.","operationId":"get_story","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetStoryInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetStoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/cancel_job":{"post":{"tags":["mcp"],"summary":"Cancel Job","description":"Cancel an in-flight story job (`pending` or `in_progress`).\n\nFlips both the persisted story status and the in-process job queue\nso unstarted work short-circuits immediately. Already-running\nchapter writes finish their current LLM call before stopping.\nSafe to call on terminal jobs — no-op.","operationId":"cancel_job","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoryMutationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/delete_story":{"post":{"tags":["mcp"],"summary":"Delete Story","description":"Permanently delete a story from the caller's library.\n\nRemoves the story document, all chapters, all revisions, and any\nsaved chat threads. Irreversible — there is no soft-delete or\nrestore. Caller should confirm with the user before invoking.","operationId":"delete_story","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/update_story_title":{"post":{"tags":["mcp"],"summary":"Update Story Title","description":"Rename the story in the caller's library through an audited mutation.","operationId":"update_story_title","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStoryTitleInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStoryTitleResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/get_revision_beats":{"post":{"tags":["mcp"],"summary":"Get Revision Beats","description":"Return historical beat artifacts and any fresh rewrite plan.\n\nRead-only. Computes text_hash and paragraph_count on the server.\nNever fabricates an exact map from unmapped legacy plan beats.\n``authoring_plan`` remains historical; ``active_revision_plan`` is the\nhash-bound client plan to use for a pending rewrite. Does not return\nchapter prose.","operationId":"get_revision_beats","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetRevisionBeatsInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetRevisionBeatsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/chapter_chat":{"post":{"tags":["mcp"],"summary":"Chapter Chat","description":"Conversational reply for back-and-forth in the revise panel.\n\nUse this on every user-typed message. Returns a short free-text\neditor response — questions answered, ideas brainstormed, critique\ngiven, suggested changes described — WITHOUT generating a\nstructured plan. The UI shows a \"Ready for plan?\" button after\neach reply; clicking that calls plan_revision with the full\nconversation to synthesize the plan.\n\nReturns: {chapter: int, editorial_summary: str}","operationId":"chapter_chat","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChapterChatInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/paragraph_chat":{"post":{"tags":["mcp"],"summary":"Selected Paragraph Chat","description":"Multi-purpose chat about one selected paragraph.\n\nThis is the chat-first replacement for the inline note apply flow. It\ncan explain, critique, retrieve prior context through story-query tools,\ndiscuss revision options, or prepare for a later rewrite plan. It does\nnot change story text.","operationId":"paragraph_chat","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SelectedParagraphChatInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/outline_chat":{"post":{"tags":["mcp"],"summary":"Outline Chat","description":"Discuss the outline with the user. No changes are committed — call\nthis repeatedly across turns to explore direction, ask the user what\nthey want changed, react to their answers. Pass the running\nconversation back in `messages` each turn so the editor has context.\n\nReturns {editorial_summary} — free-text editor reply, usually ending\nwith a question to keep the conversation moving. When the user is\nsatisfied with a direction, call refine_outline(apply=true) to\ngenerate and commit the updated plan in one shot.\n\nValid while story.status == 'reviewing'. Free to call (no credit cost).","operationId":"outline_chat","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutlineChatInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/character_chat":{"post":{"tags":["mcp"],"summary":"Character Chat","description":"Discuss the cast with the user. No changes are committed — call\nthis repeatedly across turns to explore who the characters are,\nwhat needs changing, etc. Pass the running `messages` back each turn.\n\nReturns {editorial_summary}. When the user is satisfied, call\nrefine_characters(apply=true) to commit a refined cast in one shot.\n\nValid while status == 'reviewing'. Free to call.","operationId":"character_chat","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharacterChatInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/world_chat":{"post":{"tags":["mcp"],"summary":"World Chat","description":"Discuss the world document (location, time period, culture) with the user.\nNo changes are committed — conversational only. Returns {editorial_summary}.","operationId":"world_chat","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorldChatInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/get_chat":{"post":{"tags":["mcp"],"summary":"Get Chat","description":"Load a saved chat thread for a chapter+revision.\n\nReturns `{job_id, chapter, revision, messages}`. `messages` is a\nlist of `{role, content, plan?}` entries in chronological order.\nEmpty list if nothing was ever saved for this slot. Use\n`revision=0` (or omit) for the pre-revision draft thread.","operationId":"get_chat","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatHistoryInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetChatResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/save_chat":{"post":{"tags":["mcp"],"summary":"Save Chat","description":"Persist a chat thread to a chapter+revision slot.\n\nReplaces any prior thread at that slot — pass the FULL message\nhistory each time, not a delta. `chapter_chat(auto_save=true)`\ndoes this automatically; this endpoint is for callers that build\nthe thread themselves.","operationId":"save_chat","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveChatInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/clear_chat":{"post":{"tags":["mcp"],"summary":"Clear Chat","description":"Delete the saved chat thread for a chapter+revision.\n\nIrreversible. Subsequent `get_chat` calls return an empty list.\nDoes not affect the chapter prose, only the conversation history.","operationId":"clear_chat","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatHistoryInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/query_story":{"post":{"tags":["mcp"],"summary":"Query Story","description":"Semantic search over a story's text (whole story, latest revision).\n\nReturns `{job_id, question, passages}` where each passage is\n`{chapter, para, text, score}` — the most relevant excerpts for the\nquestion, with citations. Use to pull a specific fact, check continuity,\nor find where something happened. Pass `chapter` to scope to one chapter.\n`score` is the final hybrid relevance score; `semantic_score` is the\nraw embedding similarity before lexical/phrase reranking. Lexical\nfallback expands common rewrite-check concepts, so\n`matched_query_expansions` may include synonym or morphology hits.\nquery_story is a locator, not proof. For rewrite claims, inspect `retrieval_mode`, `confidence`, and\n`needs_read_story_verification`; use `read_story` on `recommended_read`\nwhen confidence is not high or fallback retrieval was used.","operationId":"query_story","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryStoryInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryStoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/read_story":{"post":{"tags":["mcp"],"summary":"Read Story","description":"Read exact text by address: a chapter + 0-based paragraph range\n(latest revision). Omit `para_end` for the rest of the chapter. Returns\n`{job_id, chapter, para_start, para_end, text, total_paras}`.","operationId":"read_story","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadStoryInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadStoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/plan_chapter":{"post":{"tags":["mcp"],"summary":"Plan Chapter","description":"Create or register a versioned initial beat plan for an unwritten chapter.","operationId":"plan_chapter","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanChapterInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/refine_outline":{"post":{"tags":["mcp"],"summary":"Refine Outline Endpoint","description":"Generate a refined outline from the conversation so far. Pass the\nfull running `messages` plus a synthesis instruction in `message`\n(e.g. \"based on our discussion, update the outline\").\n\n apply=false (default): returns reply.updated_plan for inspection.\n Use when you want to preview the rewrite before committing.\n apply=true: atomically commits the refined plan. Use when the\n user has said \"go ahead\" — saves a round-trip vs refine ->\n serialize -> update_outline and eliminates re-serialization drift.\n\nReturns {editorial_summary, reply.{short_reply, long_reply,\nupdated_plan}, applied, title}. Valid while status == 'reviewing'.","operationId":"refine_outline","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefineOutlineInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/update_outline":{"post":{"tags":["mcp"],"summary":"Update Outline","description":"Low-level direct replacement of the plan. Caller sends the full\nplan dict; this endpoint does not merge or diff — it replaces.\n\nPrefer refine_outline(apply=true) for conversational edits: it\nbuilds the new plan from the running chat and commits atomically.\nReach for update_outline only when you already have a fully-formed\nplan dict (e.g. programmatic transforms, reapplying a saved plan).\n\nValid after planning has produced a plan, including post-write and\ncancelled stories. Written chapter rows remain frozen unless an\noutline-review client explicitly sets allow_written_outline_edits.","operationId":"update_outline","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOutlineInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/refine_characters":{"post":{"tags":["mcp"],"summary":"Refine Characters Endpoint","description":"Generate a refined character list from the conversation so far.\nPass `messages` plus a synthesis instruction (e.g. \"based on our\ndiscussion, update the cast\").\n\n apply=false: returns reply.updated_cast for preview.\n apply=true: atomically commits. Use when the user says \"go ahead\".\n\nReturns {editorial_summary, reply.{short_reply, long_reply,\nupdated_cast}, applied, character_count}.","operationId":"refine_characters","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefineCharactersInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/update_characters":{"post":{"tags":["mcp"],"summary":"Update Characters","description":"Low-level direct replacement of the character list. Prefer\nrefine_characters(apply=true) for conversational edits —\nupdate_characters is for programmatic / fully-formed cast dicts.\n\nValid in any state. Edits made after writing has started apply to\nfuture revisions only — already-written chapter text is not retouched.","operationId":"update_characters","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCharactersInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/update_character_asset":{"post":{"tags":["mcp"],"summary":"Update Character Asset","description":"Patch generated image metadata for one cast member.\n\nUse this for concept art and character sheets. It avoids resending the\nwhole cast through update_characters when only one generated asset\nchanged.","operationId":"update_character_asset","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCharacterAssetInput"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericToolResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/mcp/create_character_reference":{"post":{"tags":["mcp"],"summary":"Create Character Reference","description":"Make one cast member's reference image with your own image tools, then attach it.\n\nReturns a brief built from the story: a prompt in the house reference\nformat (one square image: front full body, face close-up, back full\nbody; fitted tank top and compression shorts, barefoot; neutral pose\nand expression), any existing images of the character to use as\nidentity references, generator settings (local Codex CLI first, fal\ngpt-image-2.5 flare as backup), acceptance checks, and a 60-minute\nupload URL. Generate the image locally, check it against brief.checks,\nthen PUT the file to upload.url (curl given; add ?model=