# Calliope Writer API

> A plain HTTP/JSON API over a writer's own Calliope manuscript. You (an LLM) are being asked
> to build an integration for a non-developer writer. Read the OpenAPI contract, then write
> them the smallest script that does what they asked.

## Start here
- OpenAPI 3.1 contract: https://localhost:8080/api/v1/openapi.json  (every endpoint, params, and bodies)
- Auth: the writer creates a key at https://localhost:8080/account/api and gives it to you. Send it as
  `Authorization: Bearer cal_...` on every request. Never print or commit the key.
- Base URL: https://localhost:8080/api/v1

## The cost model — tell the writer before running anything that costs
- read  = free (outline, chapters, search, map, snippets)
- ai    = spends the writer's credits (detect, check, generate synopsis) — no subscription needed
- write = needs an active subscription (snippets, structure, map, and chapter PROSE)

## Prose write — the important caveats (surface these to the writer)
- This API CAN overwrite chapter prose. It is for the writer's OWN scripts (import/export
  round-trips, deterministic transforms) — not for you to author their book for them.
- PUT /chapters/{id}/prose replaces a whole chapter (Markdown or a native doc). Editing a
  paragraph's text DROPS its map "mention" anchors, and rewriting/removing a paragraph drops the
  marginalia anchored to it. The response reports `mentionsDropped`.
- Prefer PATCH /chapters/{id}/paragraphs/{blockId} for targeted edits — it keeps the paragraph's
  id, so marginalia survives. Get blockIds from GET /chapters/{id}?format=doc.
- After a prose write, you can re-anchor the map by calling POST /chapters/{id}/detect (spends credits).

## Errors (stable JSON shape: { "error": code, "message": ... })
- 401 unauthorized · 402 insufficient_credits · 403 subscription_required / category_disabled
- 404 not_found · 400 bad_request

## A good first task to offer
"Read my book's outline and print each chapter's title, status, and word count." Then ask the
writer what they actually want to automate.