Skip to main content
GET
Get an agent conversation

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"

Response

The conversation row.

The conversation row as the API returns it. The same shape comes back from POST /agents/conversations (201 Created) and GET /agents/conversations/{id} (200 OK).

id
string<uuid>
required

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"

company_id
integer
required

Company ID derived from the bearer token. Pinned for the conversation's lifetime.

Example:

1

user_id
integer
required

User ID derived from the bearer token. Pinned for the conversation's lifetime and gates every subsequent read endpoint — only the originating user can fetch the conversation, its messages, or its runs. Peers in the same company see 404.

Example:

407

defaults
object
required

The configuration applied to every run on this conversation by default. Each field can be overridden per-run via config_override on the POST .../runs body, except system_prompt which is fixed at conversation creation time.

For mcp_servers and tools, overrides replace the whole list, not individual entries. There is no per-server or per-tool merge — set the complete catalog you want for that run.

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

created_at
string<date-time>
required
Example:

"2026-05-18T13:21:30.355180Z"

updated_at
string<date-time>
required
Example:

"2026-05-18T13:21:51.983952Z"

name
string | null
system_prompt
string | null