Conversation loop

A conversation belongs to a user and a card. Open it with POST /conversation/start, stream turns over the WebSocket (see Streaming), and manage saves with the archive endpoints.

Opening

POST /open/v1/conversation/start
{ "roleId": "…", "greetingIndex": 0 }

greetingIndex picks the character’s first message: 0 is roleWelcome, 1..n index into welcomeAlternates from the card detail. Calling start again for the same card resumes the current conversation.

Character greetings and player opening lines

welcomeAlternates are alternate first messages from the character — let the player pick one, then send greetingIndex. prologue are suggested first lines for the player to say — show them as a “choose an opening” block; picking one fills the input box and the player sends it. Never pass a prologue line to start.

Turns

The stream carries conversation operations: send, rewrite, continue, backward, stop from the client; streamMeta, thinking, answer, messageMeta, operationStatus, done, error from the server. GET /conversation/operations is the authoritative status of recent operations after the stream disconnects; GET /conversation/replay returns the latest reply.

POST /conversation/suggest-reply drafts the player’s next line for a flat cost, charged only on success. The draft for the current turn is kept: calling again without regenerate returns the same line with cost: 0, cached: true.

Rewind

POST /conversation/backward rewinds the story to an earlier message and drops everything after it. Ask once before doing it; it cannot be undone.

Saves

A card keeps up to 20 saves per user. The current conversation counts as one.

Endpoint	What it does
save-and-start-new	archive the current conversation and open a fresh one
archives?roleId=	list saves for one card, newest first, current included
title	name a save (≤ 100 chars; empty clears)
switch	make a save current; nothing is deleted — reload messages afterwards
fork	branch from the latest message; the source stays as a save, summaries and memory start fresh
delete	delete a conversation

At 20 saves, save-and-start-new and fork return 409 conversation_limit_reached with { limit, count }. Existing saves are retained. The user must delete a save before creating another.

Directives, notepad, memory

• Directives are standing instructions for a conversation (/conversation/directives, add / update / delete), capped by maxCount and maxLength.
• Notepad is free text per conversation (/conversation/notepad, save), with reusable templates the player can share by code.
• Memory atoms are the durable facts the AI keeps (/conversation/memory/:id/atoms). Deleting one cannot be undone; the AI may re-learn it later.

Diagnostics

GET /conversation/prompt-diagnostics?conversationId=…&breakdownVersion=2 shows how the last completed reply’s context was composed: estimated token buckets, cache hit rate and this turn’s cost. supported: false for models without accounting; status: notReady until one reply has completed.