---
title: "Revise Paragraph"
method: POST
path: "/api/mcp/revise_paragraph"
tags: ["mcp"]
---

# Revise Paragraph

`POST /api/mcp/revise_paragraph`

## 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_paragraph`
- Auth: none declared

Revise a single paragraph in-place. The user selects a paragraph by
index (0-based, split on double-newline) and provides a note describing
the desired change. Only the target paragraph is rewritten; the rest of
the chapter is preserved byte-for-byte. Use this for one paragraph that
needs reflow, voice, localized logic, or characterization. If adjacent
paragraphs or a beat/scene range also need to change, use the selected
paragraph chat/finalize/apply flow instead. Costs 1 credit.

## Request body

- ReviseParagraphInput
  - `job_id` string, required: The story job ID.
  - `chapter` integer, required: Chapter number to revise a paragraph in.
  - `paragraph_index` integer, required: 0-based index of the paragraph (split on double-newline) the user selected.
  - `note` string, required: User's revision note for this paragraph.
  - `model` string, nullable: Model override (e.g. 'grok-4').
  - `base_revision` integer, nullable: Which revision number to revise from. None = latest.
  - `authoring_mode` 'server' | 'client', nullable: Set to 'client' to use the caller's own model. Without revised_paragraph, returns a no-LLM paragraph rewrite brief; with revised_paragraph and base_text_hash, commits the client-authored paragraph without a server LLM call.
  - `server_llm` boolean, nullable: Set false as an alias for authoring_mode='client'. Do not send model in this mode.
  - `base_text_hash` string, nullable: Full chapter text hash returned by the client paragraph brief; required when committing revised_paragraph.
  - `revised_paragraph` string, nullable: Client-authored replacement for exactly the selected paragraph. Must not contain a double-newline paragraph break.
  - `dry_run` boolean: Validate revised_paragraph without committing.
  - `commit` boolean, nullable: Set false as an alias for dry_run=true; only true/default commits.
  - `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 paragraph artifacts.
  - `beat_map_update` BeatMapUpdateInput: Optional as-written map patch for in-place prose mutations.
    - `semantic_impact` 'none' | 'same_beat' | 'changed_beats': none/same_beat = mechanical range shift when wholly inside one entry; changed_beats = require replacement_entries or the map becomes stale.
    - `replacement_entries` object[]: Validated as-written entries covering the resulting edited range when semantic_impact is changed_beats.

## 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)