Writing prose safely

This is the one part of the API that can touch your body text, and it’s the one part worth reading slowly. The rule from the overview holds: the API is your own programmatic hand — an import round-trip, a deterministic transform — not an agent authoring your book. There is no prose generation endpoint; the API only persists text your script gives it.

Why prose writes cost something

In Calliope your chapter isn’t a flat string — it’s a rich document. Two things are woven into it that a plain block of text doesn’t carry:

• Mentions — the anchors that link spans of prose to Map facts.
• Marginalia — snippets anchored to specific paragraphs.

When you overwrite prose as plain text or Markdown, those anchors can’t all survive the trip:

• editing a paragraph’s text drops its mention anchors (the Map links on that paragraph);
• rewriting or removing a paragraph drops the marginalia anchored to it.

Calliope never does this silently. It preserves what it can, and it tells you exactly what it couldn’t.

The two prose endpoints

There are two ways to write prose, and choosing the right one is most of using this safely.

Prefer: PATCH …/paragraphs/{blockId} — surgical, anchor-safe

Updating a single paragraph by its block id keeps that paragraph’s identity, so its marginalia survive by construction. This is the right tool for targeted edits — fix one line, normalise one paragraph — and it’s the one to reach for first.

Get block ids by reading the chapter as a document:

# Read the chapter with paragraph ids
curl "https://app.writecalliope.ink/api/v1/chapters/CHAPTER_ID?format=doc" \
  -H "Authorization: Bearer cal_your_key"

# Edit exactly one paragraph, keeping its id (marginalia stay put)
curl -X PATCH https://app.writecalliope.ink/api/v1/chapters/CHAPTER_ID/paragraphs/BLOCK_ID \
  -H "Authorization: Bearer cal_your_key" \
  -H "Content-Type: text/markdown" \
  --data 'The rewritten paragraph text.'

Whole chapter: PUT …/chapters/{id}/prose

To replace an entire chapter — a full round-trip back from another editor — use the prose endpoint. It accepts text/markdown (the default), or JSON with {markdown}, or {doc} for a native Calliope document.

Calliope reconciles block ids across the write: paragraphs it can match are kept, so their marginalia are preserved; genuinely rewritten or removed paragraphs lose their anchors. Passing a native {doc} with block ids intact preserves the most.

curl -X PUT https://app.writecalliope.ink/api/v1/chapters/CHAPTER_ID/prose \
  -H "Authorization: Bearer cal_your_key" \
  -H "Content-Type: text/markdown" \
  --data-binary @chapter.md

Every prose write reports mentionsDropped

You never have to guess what a write cost. Every prose response reports mentionsDropped — the map anchors that couldn’t survive the edit — alongside the new wordCount and block info. It’s never silent.

To put the Map anchors back after a prose write, re-run detection on the chapter:

# Re-anchor the map (this is an AI call — it spends credits)
curl -X POST https://app.writecalliope.ink/api/v1/chapters/CHAPTER_ID/detect \
  -H "Authorization: Bearer cal_your_key"

Rules of thumb

• Editing part of a chapter? Use PATCH …/paragraphs/{blockId}. Marginalia survive.
• Replacing a whole chapter? Use PUT …/prose, and prefer a native {doc} with block ids if you have one.
• After any prose write, check mentionsDropped, and re-run POST …/detect if you need the Map re-anchored (it spends credits).
• Remember what this is for — your own scripts and transforms. If what you want is an AI writing your book, Calliope isn’t that product, on purpose.

Prose writes are a write-tier operation, so they need an active subscription. The exact request and response shapes are in the endpoint reference.