---
title: "Revise Chapter"
method: POST
path: "/api/mcp/revise_chapter"
tags: ["mcp"]
---

# Revise Chapter

`POST /api/mcp/revise_chapter`

## Request

- Base URL: `https://writer.swapp1990.org` (the document declares no server; this is the origin it was published from)
- URL: `https://writer.swapp1990.org/api/mcp/revise_chapter`
- Auth: none declared

Apply a chapter-scope revision plan and produce a new chapter revision.

Use this when the requested change affects chapter structure: beat
order, scene sequence, chapter goal, ending, whole-scene rebuilds, or
continuity handoff. For major rewrites, call start_plan_revision or
plan_revision first, inspect/refine the accepted plan, then pass the
structured_plan or plan_id here.

Returns immediately with `{job_id, status: "starting", chapter,
base_revision, new_revision}`; the actual planner+writer+evaluator
chain runs in the background. Poll progress via `get_revision_status`.
Pass `structured_plan` (from `plan_revision`) for best results;
`editorial_plan` is the legacy free-text path. `base_revision`
defaults to the latest committed revision.

## Request body

- ReviseChapterInput
  - `job_id` string, required: The story job ID.
  - `chapter` integer, nullable: Chapter number to revise. If omitted, the legacy instruction parser is used.
  - `instruction` string, required
  - `base_version` integer: DEPRECATED — stories no longer have a version axis. Use base_revision. Ignored; accepted for back-compat.
  - `base_revision` integer, nullable: Which revision number to revise from. None = latest.
  - `target_words` integer, nullable: Target word count for the revised chapter.
  - `model` string, nullable: Model override (e.g. 'grok-4').
  - `editorial_plan` string, nullable: Legacy editorial plan from chat (free-text). If structured_plan is also supplied, structured_plan wins and this is used only as a fallback summary.
  - `structured_plan` object, nullable: Structured plan {short_plan, long_plan, beats[]} from the new planner. Writer consumes beats as the primary directive.
  - `plan_id` string, nullable: Optional accepted revision-plan id. In authoring_mode='client' staged revisions, set plan_id on stage='start' only when intentionally linking that plan; omit it or send an empty string to keep the staged commit unlinked. Do not auto-fill this from a prior plan_revision response.
  - `revision_mode` 'surgical' | 'scene_rewrite' | 'full_rewrite', nullable: Caller-declared revision scope. full_rewrite and large targets require an accepted plan or bypass reason.
  - `bypass_plan_reason` string, nullable: Required for large/full rewrites when the caller deliberately skips the planned-revision path.
  - `writer_thinking` object, nullable: Previewed writer-thinking dict from the writer_thinking operation ('Show writer plan'). Reused at write time instead of rebuilding, IF its beats and target_words still match structured_plan — otherwise the writer rebuilds it fresh.
  - `chapter_note_ids` string[]: Open chapter review note ids gathered by revise_chapter_from_notes.
  - `chapter_notes` object[]: Open chapter review notes gathered by revise_chapter_from_notes.
  - `conversation` PlanMessage[], nullable: Full chat conversation for context.
    - `role` string, required
    - `content` string
    - `plan` object, nullable
    - `cover` object, nullable
    - `writer_thinking` string, nullable
    - `writer_thinking_data` object, nullable
    - `metadata` object, nullable
    - `type` string, nullable
    - `applied_at` string, nullable
    - `applied_revision` integer, nullable
    - `applied_status` string, nullable
  - `authoring_mode` 'server' | 'client', nullable: Set to 'client' to have revise_chapter return a no-LLM revision brief or commit client-authored revised text.
  - `server_llm` boolean, nullable: Set false as an alias for authoring_mode='client'. Do not send model in this mode.
  - `dry_run` boolean: Validate client-authored revised text without creating a chapter revision.
  - `commit` boolean, nullable: Set false as an alias for dry_run=true; only true/default commits.
  - `stage` 'start' | 'upsert_segment' | 'validate' | 'commit', nullable: Client revision staging step. Only stage='commit' creates a chapter revision.
  - `segment_index` integer, nullable: 0-based segment index for stage='upsert_segment'.
  - `beat_range` integer[], nullable: Optional inclusive [start, end] beat range covered by a staged segment.
  - `word_count_policy` object, nullable: Optional guard such as {min: 9500, max: 11500, hard: true}. Hard failures reject before commit.
  - `validation_anchors` string[]: Exact anchors expected in the revised text during dry-run/preflight.
  - `stale_terms` string[]: Terms that should not appear in the revised text; returned as warnings when found.
  - `base_text_hash` string, nullable: Hash returned by the no-LLM revise_chapter brief; required when committing client-authored text.
  - `scope` 'chapter' | 'paragraph' | 'range': Client revision scope.
  - `paragraph_index` integer, nullable: 0-based paragraph index for client paragraph-scope revisions.
  - `paragraph_range` integer[], nullable: 0-based inclusive [start, end] paragraph range for client range-scope revisions.
  - `text` string, nullable: Full client-authored revised chapter prose to commit in client mode.
  - `summary` string, nullable: Updated chapter summary written by the client.
  - `handoff` string, nullable: Updated end-of-chapter continuity handoff written by the client.
  - `title` string, nullable: Optional chapter title override.
  - `beats` object[]: Optional beat plan that drove this client-authored revision.
  - `carry_forward_facts` string[]: Continuity facts after this revision.
  - `facts_removed` string[]: Continuity facts removed by this revision.
  - `fact_updates` object[]: Structured continuity updates.
  - `open_loops_started` string[]: Open loops introduced by this revision.
  - `open_loops_resolved` string[]: Open loops resolved by this revision.
  - `open_loop_resolutions` object[]: Structured open-loop resolutions.
  - `open_loops_updated` object[]: Structured open-loop updates.
  - `writer_approach_id` string, nullable: Approach id previously returned by a client writer-approach step.
  - `client_name` string: Client identity for no-LLM provenance.
  - `client_model` string, nullable: Client-side model name for no-LLM provenance. Never used for server API calls.
  - `artifact_version` string: Version label for submitted client revision artifacts.

## Response `200`

Successful Response

- GenericToolResponse: Fallback for tools whose payload is still being tightened.
  - `story_url` string, nullable
  - `article_url` string, nullable
  - `job_id` string, nullable
  - `status` string, nullable
  - `is_terminal` boolean, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/swapp1990/apis/writeforyou-mcp-api.md) · [All operations](https://skmtc.dev/swapp1990/apis/writeforyou-mcp-api/llms.txt) · [OpenAPI document](https://skmtc.dev/swapp1990/apis/writeforyou-mcp-api/revisions/ce5e2a89ab4d?raw)