Streaming

Use protocol version 2 to stream HarperHarbor conversations. HTTP requests and the WebSocket must use the same API host.

Request a ticket

POST /open/v1/conversation/ws-ticket
Authorization: Bearer <access token>

The token needs chat.play. The response contains ticket and expiresIn: 30. Tickets are single-use; request a fresh one for each connection. Keep bearer tokens and tickets out of URL parameters and logs.

Connect

Open wss://api.harperharbor.com/open/v1/conversation/ws?protocolVersion=2. Send this as the first frame:

{ "type": "auth", "ticket": "<ticket>" }

The server confirms authentication using an SSE-formatted WebSocket text frame:

event: ready
data: {"accountBound":true,"supportsInputQueue":false}

Then send one message:

{
  "conversationId": "<ID returned by conversation/start>",
  "clientOperationId": "<unique ID for this message>",
  "operationKind": "send",
  "message": "How do I configure this service?",
  "language": "en",
  "model": "deepseek-v4-flash"
}

The connection is bound to the authenticated account. Do not include an account ID. Reusing clientOperationId with changed input is a conflict.

Read events

Events include streamMeta, accepted, thinking, answer, prepStep, messageMeta, operationStatus, done and error. Each persisted answer, thinking or preparation chunk carries a sequence id; save the last one applied. streamMeta.streamId identifies the operation. Ignore unknown event types for forward compatibility.

To stop the active generation, send { "action": "stop" }. Agent mode uses the existing turn frame with agentMode and, when continuing saved preparation, resumeFromOperationId. See Agent preparation for continuation requirements. Regenerate/rewrite are supported; continue-response is a separate unsupported command.

Reconnect

Request a new ticket, then connect with resumeStreamId=<streamId>&lastEventId=<last sequence> alongside protocolVersion=2. After authentication the server replays later persisted chunks and follows the operation until it ends. Deduplicate chunks by sequence ID.

After a page reload, use mode=tryResume&conversationId=<ID> to attach to an active operation. noActiveStream means none is running. Reload saved messages and operation states through the HTTP API; do not start a replacement generation merely because the socket closed.

Tickets are short-lived and held by the API process. If a ticket expires or the service restarts before the handshake, obtain another ticket. Conversation history and operation results remain in the database.

Memory preparation and capacity

Long conversations may enter memory preparation before the reply begins. Handle compacting, compactDone and compactFailed; use the operation’s terminal state, rather than a preparation event, to decide whether sending succeeded. Keep Stop available during preparation. Original messages remain in history.

operationStatus includes phase, compacting and reasonCode. If reasonCode is context_capacity_exceeded, preserve the draft and explain that the input or model capacity must change. Do not automatically resend the same input. insufficient_credits also needs user action. A disconnected socket does not authorize a new generation: reconnect or read the existing operation first.

Completed memory preparation is billed independently of the reply. Unpublished or canceled preparation does not consume credits. A failed optional preparation step can be skipped when the original request still fits and its reservation has been released.

Lorebook entries retain their initial context position across ordinary turns. Full memory checkpoints may release older retrieval; the source asset remains available for future recall. Arbitrary insertion depth, probability and timed removal from other systems are not applied. See matchOptions in the Worldbook API for supported matching and fragment metadata.

Agent progress and stop acknowledgement

An Agent operation carries agentTurn: true. Persisted prepStep events and history agentPrepTraces describe preparation; they are not answer text. A saved incomplete preparation exposes state: "failed_retryable" and reasonCode: "agent_progress_preserved". Offer Continue only from this durable result.

For Agent execution, the HTTP Stop response waits for the terminal state and settlement to become durable, so a following history reload can recover Continue. A WebSocket Stop requests cancellation asynchronously; continue reading operation state. Completed model calls before a stop can still consume credits.