Runtype APIClient Runtime

Read one of the visitor's own conversations

Return a single conversation with its message transcript. Answers 404 (never 403) for a conversation the caller does not own, so the route cannot be used to probe for other visitors' conversations. Every response carries `X-History-Identity-Status` (`not_provided` | `admitted` | `ignored`) reporting what the server did with a supplied `X-Identity-Proof`, so a widget can tell a verified action from a browser-scoped one. It is exposed via CORS; it grants no authority.

Path parameters

idstringRequired
Conversation id from the list route.

Headers

x-visitor-tokenstringRequired

The browser’s anonymous visitor secret (cvt_…) returned by /client/init. It is what scopes the request to one visitor’s own conversations, so a request without it is refused. Sent as a header so it never lands in access logs or Referer.

x-identity-proofstringOptional1-8192 characters

Optional fresh hosted end-user identity proof. When admitted and already bound to the presented visitor, expands the request from this exact browser to sibling visitors for the same verified person. Without it, even a previously bound visitor remains exact-browser scoped.

Query parameters

sessionIdstringRequired

Client session id from /client/init.

messageCursorstringOptional

Opaque cursor returned as nextMessageCursor by a previous detail response. Omit for the newest message page.

messageLimitstringOptional
Message page size as a decimal string. Defaults to 25 and is clamped to 25 to bound media rehydration and Worker memory.

Response

Conversation
conversationRevisionstring

Opaque change token for this conversation. Compare for equality only — it is unordered and unparseable. It changes on every transcript mutation, including a display-projection finalization that deliberately leaves updatedAt untouched, so a client can tell whether a transcript it cached is still current. The same token is returned by /client/init and by the display-projections route.

createdAtstring

ISO-8601 timestamp of the first turn, i.e. when the conversation was created.

flowIdstring or null

Deprecated alias of targetId, carrying the same value. Retained for clients written before the rename; read targetId instead.

idstring
Conversation id.
messageCountdouble
Number of stored messages. Falls back to the length of the stored transcript when the conversation predates the counter.
messageslist of objects

The stored transcript, oldest first. Renderable fields only: tool invocations and other execution internals are not exposed here.

nextMessageCursorstring or null
Opaque cursor for the next older message page, or null when the beginning is reached.
previewstring or null

Plain-text excerpt of the conversation’s most recent visitor-visible message, bounded to 140 Unicode code points, for a scannable history list. Derived from displayContent when the message has one and never from opaque model-only content, so it cannot become the one place internals leak. Null when the latest visible message has no text — including when its captured projection is deliberately empty.

targetIdstring or null

The flow or agent this conversation ran against, and the exact value to pass as the targetId list/delete filter. Null for a conversation stored without one. Canonical replacement for flowId.

titlestring

Display title. Uses a timestamp fallback unless conversation-title generation is enabled and produces a title from the opening exchange.

updatedAtstring

ISO-8601 timestamp of the most recent write. Sort key for “resume where I left off” in a widget.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error