v1

latestOpenAPI 3.1.0raw.githubusercontent.com2026-06-304917042.1 MB
runtime v2

Poll a v2 conversation for its status and the message tail since a seq

The HITL-04 §6.6 poll primitive — net-new, message+seq shaped.

Distinct from GET /{id}/turns (cursor-paginated over turns): this is the one round-trip a caller loops on while a turn is parked, returning the conversation's current session_status AND every message with seq > since_seq. The SAME primitive serves approval-resume polling (awaiting_approvalactive) and handoff operator-relay polling (waiting_for_humanclosed); the uniform waker generates+persists the resumed/operator message and the caller's next poll picks it up.

The caller watermarks on the returned next_seq (the max seq of the tail, or the request since_seq when the tail is empty so an idle poll never rewinds). Borrows the read-router message-row + worst-of-N delivery- status plumbing; ordered by seq ascending. Org-scoped: cross-org / missing id → 404 before any read.

get/v1/v2/conversations/{conversation_id}/messages

Path parameters

conversation_idstring uuid required

Query parameters

since_seqinteger

Watermark: return only messages with seq > since_seq (exclusive). Message seqs are 0-based, so seed with the default -1 to fetch from the very start (includes seq 0), then pass the response's next_seq back.

Watermark: return only messages with seq > since_seq (exclusive). Message seqs are 0-based, so seed with the default -1 to fetch from the very start (includes seq 0), then pass the response's next_seq back.

include_evidenceboolean

[ENG-670 T3] Attach each message's evidence package (the KB sources shown to the model). Off by default — the poll DEFERS the large citations column; opt in to load and project it.

[ENG-670 T3] Attach each message's evidence package (the KB sources shown to the model). Off by default — the poll DEFERS the large citations column; opt in to load and project it.

evidence_view'display' | 'full'

Serialization view when include_evidence=true. Poll default is 'full' (staff/audit), matching the transcript page; 'display' is the end-user source-card subset.

Serialization view when include_evidence=true. Poll default is 'full' (staff/audit), matching the transcript page; 'display' is the end-user source-card subset.

Response

Successful Response

session_statusstring required
next_seqinteger required