Skip to main content
GET
List conversation messages (delta read by version cursor)

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id
string<uuid>
required

The conversation's UUID. UUID identifying a conversation. Returned from POST /agents/conversations and used in every other agent endpoint that operates on this conversation.

Example:

"bc2505b7-068d-44ed-8055-a6f6ffe54ab1"

Query Parameters

since
integer
default:0

Return messages with sequence_no > since. Use the previous response's current_version as the next request's since for gap-free incremental reads.

Default 0 returns the entire conversation from the beginning.

Required range: x >= 0

Response

A page of messages with sequence_no > since, plus the current head version.

Returned by GET /agents/conversations/{id}/messages?since=N. Carries the conversation's current head version (current_version) plus the requested page of messages.

Polling pattern:

The current_version is the conversation's head at the moment the response was generated — using it as the next request's since gives gap-free incremental reads.

current_version
integer
required

Monotonic per-conversation counter, bumped by 1 (or more) every time a successful run appends messages. Two roles:

  1. Delta cursor for GET .../messages?since=N — fetch only messages with sequence_no > N.
  2. Compare-and-swap token for POST .../runs — set expected_version to the conversation's current head; if it doesn't match at run-creation time, you get a Version Conflict (HTTP 409).

Always start a new run cycle by reading the current version from GET /agents/conversations/{id} rather than caching a value from earlier.

Required range: x >= 0
Example:

4

messages
object[]
required

Messages with sequence_no > since. Empty array means no new messages — the conversation is at version current_version but you've already seen everything.