mcp

Revise Chapter

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.

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

Request body

job_idstring required

The story job ID.

chapterinteger nullable

Chapter number to revise. If omitted, the legacy instruction parser is used.

instructionstring required
base_versioninteger

DEPRECATED — stories no longer have a version axis. Use base_revision. Ignored; accepted for back-compat.

base_revisioninteger nullable

Which revision number to revise from. None = latest.

target_wordsinteger nullable

Target word count for the revised chapter.

modelstring nullable

Model override (e.g. 'grok-4').

editorial_planstring 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_planobject nullable

Structured plan {short_plan, long_plan, beats[]} from the new planner. Writer consumes beats as the primary directive.

plan_idstring 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_reasonstring nullable

Required for large/full rewrites when the caller deliberately skips the planned-revision path.

writer_thinkingobject 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_idsstring[]

Open chapter review note ids gathered by revise_chapter_from_notes.

chapter_notesobject[]

Open chapter review notes gathered by revise_chapter_from_notes.

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_llmboolean nullable

Set false as an alias for authoring_mode='client'. Do not send model in this mode.

dry_runboolean

Validate client-authored revised text without creating a chapter revision.

commitboolean 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_indexinteger nullable

0-based segment index for stage='upsert_segment'.

beat_rangeinteger[] nullable

Optional inclusive [start, end] beat range covered by a staged segment.

word_count_policyobject nullable

Optional guard such as {min: 9500, max: 11500, hard: true}. Hard failures reject before commit.

validation_anchorsstring[]

Exact anchors expected in the revised text during dry-run/preflight.

stale_termsstring[]

Terms that should not appear in the revised text; returned as warnings when found.

base_text_hashstring nullable

Hash returned by the no-LLM revise_chapter brief; required when committing client-authored text.

scope'chapter' | 'paragraph' | 'range'

Client revision scope.

paragraph_indexinteger nullable

0-based paragraph index for client paragraph-scope revisions.

paragraph_rangeinteger[] nullable

0-based inclusive [start, end] paragraph range for client range-scope revisions.

textstring nullable

Full client-authored revised chapter prose to commit in client mode.

summarystring nullable

Updated chapter summary written by the client.

handoffstring nullable

Updated end-of-chapter continuity handoff written by the client.

titlestring nullable

Optional chapter title override.

beatsobject[]

Optional beat plan that drove this client-authored revision.

carry_forward_factsstring[]

Continuity facts after this revision.

facts_removedstring[]

Continuity facts removed by this revision.

fact_updatesobject[]

Structured continuity updates.

open_loops_startedstring[]

Open loops introduced by this revision.

open_loops_resolvedstring[]

Open loops resolved by this revision.

open_loop_resolutionsobject[]

Structured open-loop resolutions.

open_loops_updatedobject[]

Structured open-loop updates.

writer_approach_idstring nullable

Approach id previously returned by a client writer-approach step.

client_namestring

Client identity for no-LLM provenance.

client_modelstring nullable

Client-side model name for no-LLM provenance. Never used for server API calls.

artifact_versionstring

Version label for submitted client revision artifacts.

Response

Successful Response

story_urlstring nullable
article_urlstring nullable
job_idstring nullable
statusstring nullable
is_terminalboolean nullable

Changes

No recorded changes to this operation across all 1 revision of this API.