---
title: "Plan Chat"
method: POST
path: "/api/plan/chat"
---

# Plan Chat

`POST /api/plan/chat`

## Request

- Base URL: `https://api.kdpcoloringbook.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.kdpcoloringbook.com/api/plan/chat`
- Auth: HTTP bearer

Drive the guided planning conversation. Stateless: the FE replays the full
transcript each turn. Text only — no credits are charged here.

## Request body

- PlanChatRequest
  - `messages` PlannerMessage[], required
    - `role` 'user' | 'assistant', required
    - `content` string, required
  - `language` 'en' | 'es', nullable
  - `chat_language` string, nullable

## Response `200`

Successful Response

- PlannerTurn: One assistant turn. ``kind`` discriminates the shape: - ``question``: render ``message`` + ``options`` (chips) and/or a free-text box. - ``plan``: render ``message`` + ``summary`` bullets + the 3 invented ``style_candidates`` (rendered against one shared ``sample_scene`` so the user can compare looks and pick one), plus Approve / give-feedback CTAs (``config`` is hidden state).
  - `kind` 'question' | 'plan', required
  - `message` string, required
  - `options` PlannerOption[]
    - `label` string, required
    - `value` string, required
    - `emoji` string, nullable
  - `multi_select` boolean
  - `allow_free_text` boolean
  - `collected` object, nullable
  - `summary` string[], nullable
  - `config` BookPlanConfig: The book the agent proposes — a superset compatible with GenerateRequest. On approval the FE forwards this straight to POST /api/generate. ``pages`` is the authoritative page count (the user picks it explicitly); ``length`` is only a coarse label (the nearest LENGTH bucket) and is not used to derive pages.
    - `theme` string, required
    - `length` 'test' | 'short' | 'medium' | 'long'
    - `pages` integer
    - `distribution_type` 'progressive' | 'bold_and_easy' | 'cute_and_cozy'
    - `character_count` integer, nullable
    - `language` 'en' | 'es'
    - `style_id` string, nullable
    - `style_description` string, nullable
    - `allow_text` boolean
  - `style_candidates` StyleCandidate[], nullable
    - `key` string, nullable
    - `name` string, required
    - `description` string, required
    - `name_local` string, nullable
    - `description_local` string, nullable
  - `sample_scene` string, nullable
  - `distribution` DistributionRange[], nullable
    - `start_page` integer, required
    - `end_page` integer, required
    - `theme` string, required
    - `description` string, nullable
  - `handled_requests` string[]
  - `help_topic` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kdpcoloringbook/apis/book-generator-api.md) · [All operations](https://skmtc.dev/kdpcoloringbook/apis/book-generator-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kdpcoloringbook/apis/book-generator-api/revisions/f330c566ffc2?raw)