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
| Field | Type | Description |
|---|---|---|
id | string | Conversation ID |
project_id | string | Project ID |
name | string, nullable | Optional human-readable name for the conversation. |
status | open | closed | Conversation status |
created_at | string (date-time) | Creation timestamp |
updated_at | string (date-time) | Last update timestamp |
actor_id | string, nullable | Actor ID associated with this conversation |
tags | object | Key-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. |
retrieval | embed | none, nullable | Whether 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
| Field | Type | Description |
|---|---|---|
document_id | string | Document ID |
role | user | assistant | system | Role of the message sender |
actor_id | string, nullable | Optional actor ID associated with this message |
agent_id | string, nullable | Optional agent ID that generated this message (set for assistant messages produced by generate) |
position | integer | Zero-based position in the conversation |
metadata | object | Optional structured metadata attached to the message |
content | string, nullable | Full text content of the message |
idempotency_key | string, nullable | The 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
- CLI
- SDK
- curl
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."
const { data: conversation } =
await naturali.conversations.createConversation({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: { name: 'support thread' },
});
await naturali.conversations.addConversationMessage({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
conversation_id: conversation!.id,
},
body: { role: 'user', message: 'My order never arrived.' },
});
CONVERSATION_ID=$(curl -s -X POST \
https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/conversations \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "support thread" }' | jq -r .id)
curl -X POST \
"https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/conversations/$CONVERSATION_ID/messages" \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "role": "user", "message": "My order never arrived." }'
Read a session's transcript
- CLI
- SDK
- curl
naturali list-conversation-messages \
--project-id proj_V1StGXR8Z5jdHi6B \
--conversation-id conv_V1StGXR8Z5jdHi6B \
--limit 50
// `conversation_id` comes from the session record.
const { data: messages } =
await naturali.conversations.listConversationMessages({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
conversation_id: 'conv_V1StGXR8Z5jdHi6B',
},
query: { limit: 50 },
});
curl "https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/conversations/conv_V1StGXR8Z5jdHi6B/messages?limit=50" \
-H "Authorization: Bearer $NATURALI_TOKEN"
Generate the next reply and wait for it
- CLI
- SDK
- curl
naturali generate-conversation-message \
--project-id proj_V1StGXR8Z5jdHi6B \
--conversation-id conv_V1StGXR8Z5jdHi6B \
--agent-id agent_V1StGXR8Z5jdHi6B \
--wait true
const { data: reply } =
await naturali.conversations.generateConversationMessage({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
conversation_id: 'conv_V1StGXR8Z5jdHi6B',
},
query: { wait: true },
body: { agent_id: 'agent_V1StGXR8Z5jdHi6B' },
});
curl -X POST \
"https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/conversations/conv_V1StGXR8Z5jdHi6B/generate?wait=true" \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "agent_id": "agent_V1StGXR8Z5jdHi6B" }'