---
title: "Upsert Chapter Note"
method: POST
path: "/api/mcp/upsert_chapter_note"
tags: ["mcp"]
---

# Upsert Chapter Note

`POST /api/mcp/upsert_chapter_note`

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

Add or update a review note on a generated story chapter.

Notes can come from Codex or the website reader UI. They stay visible
on the chapter and can be consumed by revise_chapter_from_notes.

## Request body

- UpsertChapterNoteInput
  - `job_id` string, required: The story job ID.
  - `chapter` integer, required: Chapter number the review note belongs to.
  - `initial_plan_id` string, nullable: Optional initial chapter plan id when the note targets an unwritten chapter plan.
  - `note_id` string, nullable: Existing note id to update. Omit to create a new note.
  - `text` string, required: Review note to apply to this story chapter. Notes stay visible on the chapter and can be consumed by revise_chapter_from_notes.
  - `paragraph_index` integer, nullable: 0-based displayed paragraph index the note refers to.
  - `selected_text` string, nullable: Optional text span the note is anchored to.
  - `revision` integer, nullable: Chapter revision number this note belongs to. Omit to attach the note to the latest revision.
  - `scope` string: Note scope: paragraph, beat, or chapter. Beat notes may include beat_index/range metadata.
  - `beat_index` integer, nullable: 0-based beat index when scope is beat.
  - `beat_num` integer, nullable: 1-based beat number when scope is beat.
  - `beat_summary` string, nullable: Beat summary shown to the writer when applying beat-level notes.
  - `range_start` integer, nullable: 0-based first paragraph covered by the beat note.
  - `range_end` integer, nullable: 0-based last paragraph covered by the beat note.
  - `origin` string: Where the note came from, such as Codex session or website 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)