---
title: "Refine Outline Endpoint"
method: POST
path: "/api/mcp/refine_outline"
tags: ["mcp"]
---

# Refine Outline Endpoint

`POST /api/mcp/refine_outline`

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

Generate a refined outline from the conversation so far. Pass the
full running `messages` plus a synthesis instruction in `message`
(e.g. "based on our discussion, update the outline").

  apply=false (default): returns reply.updated_plan for inspection.
    Use when you want to preview the rewrite before committing.
  apply=true: atomically commits the refined plan. Use when the
    user has said "go ahead" — saves a round-trip vs refine ->
    serialize -> update_outline and eliminates re-serialization drift.

Returns {editorial_summary, reply.{short_reply, long_reply,
updated_plan}, applied, title}. Valid while status == 'reviewing'.

## Request body

- RefineOutlineInput
  - `job_id` string, required: The story job ID.
  - `message` string, required: Synthesis instruction (often 'Based on our conversation, update the outline').
  - `messages` PlanMessage[]: Full outline-level 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
  - `model` string, nullable
  - `apply` boolean: If true, atomically commit the refined plan (like calling update_outline with the returned plan in one step). Avoids the refine→serialize→update round-trip that risks plan drift from re-serialization.
  - `target_words_per_chapter` integer, nullable: Optional length override applied when apply=true. Updates the writer's per-chapter target so subsequent chapter generation sizes accordingly. Omit to leave unchanged — there is no other way to edit target length mid-review.

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