Skip to main content

Conversations

Durable message threads — the transcript a session records into, readable and writable on its own.

Overview​

A conversation is an ordered list of messages scoped to a project. Every session has one underneath it (conversation_id on the session), which is why the transcript of a session is read through this module rather than off the session itself. A conversation can also be used directly: create one, append messages, and generate the next reply through an actor's linked agent.

This module is a verbatim mirror of the runtime: every field, method, status code and error shape is the runtime's own, re-rooted under the project in the path.

See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Conversations.

Data Model​

Conversation​

FieldTypeDescription
idstringConversation ID
project_idstringProject ID
namestring, nullableOptional human-readable name for the conversation.
statusopen | closedConversation status
created_atstring (date-time)Creation timestamp
updated_atstring (date-time)Last update timestamp
actor_idstring, nullableActor ID associated with this conversation
tagsobjectKey-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with 400 VALIDATION_FAILED, never coerced. Keys are opaque and stored verbatim, so cost_center and costCenter are two different tags. Matched by JSONB containment wherever tags are read: the ?tags= filter, knowledge search, and the IAM iam:ResourceTag/<key> condition. Keys beginning system. are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with 400 RESERVED_TAG_KEY. They are read and filtered like any other tag. The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is 400 VALIDATION_FAILED with meta.limit naming the bound it crossed. system.* keys are the platform's and do not count against the 50.
retrievalembed | none, nullableWhether this conversation's turns are embedded for vector retrieval. Turns are stored and chunked either way, so none leaves them readable and reachable by full-text search without paying for an embedding. null (the default) inherits the project's default_conversation_retrieval.

ConversationMessage​

FieldTypeDescription
document_idstringDocument ID
roleuser | assistant | systemRole of the message sender
actor_idstring, nullableOptional actor ID associated with this message
agent_idstring, nullableOptional agent ID that generated this message (set for assistant messages produced by generate)
positionintegerZero-based position in the conversation
metadataobjectOptional structured metadata attached to the message
contentstring, nullableFull text content of the message
idempotency_keystring, nullableThe idempotency key the message was posted with, null when none was sent. A channel that posts each inbound message under its provider's message id finds the transcript row for that message by this key.

Each message is stored as a document, so its ID is document_id.

Key Concepts​

Position is the ordering​

GET /v1/projects/{project_id}/conversations/{conversation_id}/messages returns messages ordered by position — order=desc reads from the end — and paginates with limit/cursor over that order. POST …/messages takes message and role, and appends at the end unless you name a position — so inserting into history is possible, but deliberate. Replay a bad answer reads a session's thread this way to pick the position a fork branches after.

Generating the next message​

POST /v1/projects/{project_id}/conversations/{conversation_id}/generate takes the agent_id that should answer and generates the next message into the thread. Like every generate call it is background by default: it answers 202 Accepted with the turn's generation_id and trace_id once its generation record exists, and the reply lands as a new message when the run finishes. Poll the generation for status, or pass wait=true to block and get the reply in the response. stream: true implies waiting and answers Server-Sent Events: an event: accepted frame with the 202 body, then one event: progress frame per step and tool call, as on GET /v1/projects/{project_id}/generations/{generation_id}/events, ending with data: [DONE]. stream: true with wait=false is 400. A conversation with no message to answer is 400 NO_MESSAGE_TO_ANSWER, and nothing runs.

On a managed provider the model the named agent would run must carry a price, or the call answers 409 MODEL_NOT_PRICED and generates nothing; a project that owes for usage already served answers 402 INSUFFICIENT_CREDIT until it is topped up. See A managed model must carry a price and A negative balance stops managed generation.

A Free account that has used its plan's monthly runs answers 403 PLAN_LIMIT_REACHED with resource: "runs" here as well, on its own credential too. See A plan's run allowance can stop generation.

This holds however the call arrives: a call to this API or an agent's tool call.

Sessions versus conversations​

A session adds agent binding, lifecycle (open/closed/ expired), inactivity expiry, message debouncing and forking on top of one conversation. Reach for a session when you want that machinery, and for a bare conversation when you only need a thread you control.

Tags​

GET / PUT / PATCH …/tags read, replace and merge a conversation's tag map. PUT replaces the whole map; PATCH merges keys into it.

Examples​

Create a conversation and append a message​

CONVERSATION_ID=$(naturali create-conversation \
--project-id proj_V1StGXR8Z5jdHi6B \
--name "support thread" | jq -r .id)

naturali add-conversation-message \
--project-id proj_V1StGXR8Z5jdHi6B \
--conversation-id "$CONVERSATION_ID" \
--role user \
--message "My order never arrived."

Read a session's transcript​

naturali list-conversation-messages \
--project-id proj_V1StGXR8Z5jdHi6B \
--conversation-id conv_V1StGXR8Z5jdHi6B \
--limit 50

Generate the next reply and wait for it​

naturali generate-conversation-message \
--project-id proj_V1StGXR8Z5jdHi6B \
--conversation-id conv_V1StGXR8Z5jdHi6B \
--agent-id agent_V1StGXR8Z5jdHi6B \
--wait true