Conversation loop

HarperHarbor runs conversations using an agent configuration, the user’s settings and the selected model. Requests require chat.play. Authors can test their own private configurations; other users can access configurations that are public and approved.

Start or resume

POST /open/v1/conversation/start
Authorization: Bearer <access token>
Content-Type: application/json

{ "roleId": "<agent configuration ID>", "language": "en", "greetingIndex": 0 }

The response includes conversationId and the opening message. Calling this endpoint again for the same account and configuration resumes the current conversation. greetingIndex: 0 selects the default opening; positive indices select alternate openings. Suggested user prompts are input choices, not agent openings.

When you resume, add "firstPageSize": 30 (1–100) to receive the newest history page in the same response as firstPage. It has the same shape as a conversation/messages page, so you can render it without a second request. A new conversation returns no firstPage; its opening message is in the response already.

Send a message

Request a connection ticket and follow the streaming protocol. Give every new message a stable clientOperationId. Reuse it only when retrying the same message in the same conversation; this prevents duplicate generation and charges.

The model receives the agent’s instructions, examples, conversation history, user settings and matching Lorebook entries. Lorebook retrieval combines keywords, constant entries and semantic retrieval. Agent preparation can inspect additional entries and compatible history when needed.

Read progress and history

• GET /open/v1/conversation/messages?conversationId=…&pageNum=1&pageSize=30 returns saved messages, newest first. Increase pageNum to load older pages.
• GET /open/v1/conversation/operations?conversationId=… returns operation states.
• GET /open/v1/conversation/operations/{operationId} returns one operation, including settled and chargeCredits.

A disconnected stream can keep generating. Check its operation before sending another message. See Streaming for replay and Quotas and pricing for settlement.

Stop

Send POST /open/v1/conversation/stop with { "conversationId": "…" }, or send { "action": "stop" } on the active WebSocket. Read the final operation state to confirm the outcome.

This API also supports regenerate/rewrite, archives and forks, message editing/deletion, user and AI notebooks, persistent memory, reply suggestions and Agent mode. Continue-response is a separate unsupported capability; it is not the same as resuming saved Agent preparation.

Agent preparation

Read or save multiPassEnabled through /open/v1/player/agent-mode for the roleId. Check runtimeEnabled, modelSupported and costWarning before offering the mode. The model catalog’s supportsMultiPass describes tool capability. A WebSocket turn may override the saved preference with agentMode: true or false.

During preparation the model can inspect Lorebook entries and conversation history, maintain its own notes and versioned state, establish random or sealed facts, read permitted public web pages, and create and revise a draft before delivering it. The user’s notebook remains read-only to the model. The same configuration, persona, response preferences and instructions apply throughout.

Show prepStep as progress rather than reply text, and keep Stop available. If an incomplete operation reports reasonCode: "agent_progress_preserved", offer Continue. Send the same message with a new clientOperationId, operationKind: "retry_generation", and resumeFromOperationId set to the saved operation. This preserves the original user message and charges only newly performed work. The model may differ from the interrupted one: the saved progress continues on the model you send, and the remaining work is charged at that model’s rate.

Continuation requires the same caller and conversation, unchanged history, the latest user turn, no existing continuation and saved preparation no older than 30 days. Invalid sources fail rather than silently starting over. Reconnecting to the same operation is replay, not continuation, and must not start another paid generation.

Agent preparation can make multiple model calls. Review usage and billing before enabling it; the catalog’s per-turn estimate is not a total Agent execution price cap.