Sessions
Durable, resumable dialogues with an agent — messages, generations, forks and expiry.
Overview
A session binds one agent to one thread of conversation. Creating it also creates the conversation underneath, so a single call is enough to start talking; the transcript is then read through that conversation, because naturali stores no message bodies of its own.
On top of a bare conversation, a session adds an agent binding, a lifecycle
(open / closed / expired), optional auto-generation, inactivity expiry,
message debouncing, and forking.
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 → Sessions.
Data Model
Session
| Field | Type | Description |
|---|---|---|
id | string | Session public ID |
agent_id | string | Agent public ID, kept after a shared agent is deleted by its owner. |
conversation_id | string | Underlying conversation public ID |
status | open | closed | expired | |
name | string, nullable | |
actor_id | string, nullable | Public ID of the user actor, or null when the session was created without one |
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. |
auto_generate | boolean | When true, automatically triggers generation after each user message (if no generation is in progress). |
generating_at | string (date-time), nullable | Timestamp when the current generation started, or null if not generating. |
created_at | string (date-time) | |
updated_at | string (date-time) | |
inactivity_ttl_seconds | integer | Number of seconds of inactivity after which the session expires. 0 means the session never expires. |
message_delay_seconds | integer, nullable | Number of seconds to wait after the last user message before sending to the LLM. Acts as a debounce: each new message resets the timer. null or absent means no delay (immediate processing). |
max_context_messages | integer, nullable | Maximum number of recent conversation messages sent to the model on each generation. Takes precedence over the agent's max_context_messages; null defers to it. A fork keeps its parent's value. |
last_activity_at | string (date-time), nullable | Timestamp of the last activity on the session (message added or response generated). |
forked_from_session_id | string, nullable | Public ID of the session this one was forked from, or null when it was not forked. Also null once that parent is deleted — a fork survives its parent and keeps its own history. |
forked_from_position | integer, nullable | The parent conversation position this session branched after, or null when it is not a fork or was forked at the tip. |
usage | object | What the session's generations cost: token counts and cost_usd summed across every metered generation dispatched through it. Present on the single-session read; omitted from session and fork list responses. A fork is a session of its own, so it starts at zero rather than inheriting what the history it copied cost — summing usage across a session and its forks therefore never double-counts. Work the platform does around a session without a generation of its own (a memory extraction pass, for instance) is metered on the project, not here. |
agent_id is required on create.
Key Concepts
Posting a message, with or without auto-generation
POST /v1/projects/{project_id}/sessions/{session_id}/messages
saves a user message. If auto_generate is on and nothing is generating, it also
starts the run and answers like a generate call; otherwise it returns the saved
message and you call
POST …/generate yourself.
Replay a bad answer
posts with it on;
Cap spend per end user adds
the message and generates in two calls.
idempotency_key on the message body, or the Idempotency-Key header,
deduplicates within the session: the same key returns the original message with
200 and starts no second generation — which is what makes a retrying webhook
safe. Reusing a key with a different message, document_id or tool_context
is 409 IDEMPOTENCY_KEY_REUSED; sending both spellings with different values is
400 VALIDATION_FAILED.
Generation is background by default
POST …/generate answers
202 Accepted with the turn's generation_id and trace_id once its
generation record exists, unless you pass wait=true. A refusal before that
record (a closed or expired session, a generation already in progress) is the
same error wait=true answers. Poll the generation for the
result, or pass stream: true to receive the turn's events as Server-Sent
Events until it settles, as on
GET /v1/projects/{project_id}/generations/{generation_id}/events
(stream: true with wait=false is 400). A session with no message to
answer is 400 NO_MESSAGE_TO_ANSWER, and nothing runs. A client-type
tool pauses the run with requires_action and a required_action
payload; resume it with
POST …/tool-outputs, which
takes the generation_id and one output per pending call; the resumed turn runs
under the authority it started with, held to yours
(a resume only narrows). A completed turn is
stored right after the last message it read, so a message sent while it ran or
waited on tool outputs stays after it.
On a managed provider the model the session's 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.
Handing the outputs back with
POST /v1/projects/{project_id}/sessions/{session_id}/tool-outputs
is what makes the next call, so it answers 402 INSUFFICIENT_CREDIT on the same
balance. It needs no price check: the generation it continues cleared one when it
started, on the same model. Adding a message is refused the same way only on a
session with auto_generate on, where the message starts the generation;
otherwise it sits in the session until something generates on it.
Debouncing a chatty user
message_delay_seconds waits that many seconds after the last user message
before calling the model, and each new message resets the timer. Three messages
typed in quick succession become one generation with all three in context,
instead of three runs racing each other.
What a session cost
GET /v1/projects/{project_id}/sessions/{session_id}
carries a usage roll-up: the token counts and cost_usd of every metered
generation dispatched through the session. It answers "what did this
conversation cost" without joining the generations log
against a rate card.
A fork is a session of its own and starts at zero rather than inheriting what
the history it copied cost, so summing usage across a session and its forks
never double-counts. Work the platform does around a session without a
generation of its own is metered on the project, not here — read
GET /v1/projects/{project_id}/usage
for the project-wide view.
usage is one number. For the same spend split by day, model or provider, pass
the session to the project meter as session_id: see
narrowing to one session or one end user;
Cap spend per end user
splits it by end user.
The listing omits usage — reading it per session is a read per session, and a
customer's dashboard is better served by one narrowed rollup.
Tool context is write-only
tool_context set on create, update or fork is a key/value bag forwarded as
X-Naturali-Context-<key> headers on every http and mcp tool
call in the session; on a message or generate call it applies to that generation
only. It may hold credentials, so no read of a session returns it, and closing
or expiring the session clears it.
Expiry
inactivity_ttl_seconds expires a session after a quiet period — status becomes
expired and it stops accepting messages. 0 means it never expires.
Forking
POST …/fork branches a new session from a
point in this one's history: same context, different continuation. The fork gets
its own conversation whose messages reference the same documents as the
parent rather than copying them, so there is one stored copy of the shared
history. Omit fork_at_position to branch at the tip, and pass agent_id to
have a different agent continue. The fork carries over neither actor_id nor
tags, and its response has no tags key; set them on the fork afterwards if
the branch should be driven by the same end user.
GET …/forks lists one level of
lineage: a fork of a fork is listed under its own parent.
Replay a bad answer forks at
a customer's question so a fixed agent answers it again.
Deleting
DELETE removes the session, its
conversation and their messages. The actor is not deleted, and
neither are the generations the session produced — those are
records of what happened, not parts of the session.
Examples
Open a session and send the first message
- CLI
- SDK
- curl
SESSION_ID=$(naturali create-session \
--project-id proj_V1StGXR8Z5jdHi6B \
--agent-id agent_V1StGXR8Z5jdHi6B \
--auto-generate true | jq -r .id)
naturali add-session-message \
--project-id proj_V1StGXR8Z5jdHi6B \
--session-id "$SESSION_ID" \
--message "Where is my order?"
const { data: session } = await naturali.sessions.createSession({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: { agent_id: 'agent_V1StGXR8Z5jdHi6B', auto_generate: true },
});
const { data: reply } = await naturali.sessions.addSessionMessage({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B', session_id: session!.id },
body: { message: 'Where is my order?' },
});
SESSION_ID=$(curl -s -X POST \
https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/sessions \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "agent_id": "agent_V1StGXR8Z5jdHi6B", "auto_generate": true }' | jq -r .id)
curl -X POST \
"https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/sessions/$SESSION_ID/messages" \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "message": "Where is my order?" }'
Read the transcript
The transcript lives on the session's conversation:
- CLI
- SDK
- curl
CONVERSATION_ID=$(naturali get-session \
--project-id proj_V1StGXR8Z5jdHi6B \
--session-id sess_V1StGXR8Z5jdHi6B | jq -r .conversation_id)
naturali list-conversation-messages \
--project-id proj_V1StGXR8Z5jdHi6B \
--conversation-id "$CONVERSATION_ID"
const { data: session } = await naturali.sessions.getSession({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
session_id: 'sess_V1StGXR8Z5jdHi6B',
},
});
const { data: messages } =
await naturali.conversations.listConversationMessages({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
conversation_id: session!.conversation_id,
},
});
CONVERSATION_ID=$(curl -s \
https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/sessions/sess_V1StGXR8Z5jdHi6B \
-H "Authorization: Bearer $NATURALI_TOKEN" | jq -r .conversation_id)
curl "https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/conversations/$CONVERSATION_ID/messages" \
-H "Authorization: Bearer $NATURALI_TOKEN"
Fork a session to try a different continuation
- CLI
- SDK
- curl
naturali fork-session \
--project-id proj_V1StGXR8Z5jdHi6B \
--session-id sess_V1StGXR8Z5jdHi6B \
--fork-at-position 4 \
--name "alternative reply"
const { data: fork } = await naturali.sessions.forkSession({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
session_id: 'sess_V1StGXR8Z5jdHi6B',
},
body: { fork_at_position: 4, name: 'alternative reply' },
});
curl -X POST \
https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/sessions/sess_V1StGXR8Z5jdHi6B/fork \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "fork_at_position": 4, "name": "alternative reply" }'
Close a session
- CLI
- SDK
- curl
naturali update-session \
--project-id proj_V1StGXR8Z5jdHi6B \
--session-id sess_V1StGXR8Z5jdHi6B \
--status closed
await naturali.sessions.updateSession({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
session_id: 'sess_V1StGXR8Z5jdHi6B',
},
body: { status: 'closed' },
});
curl -X PATCH https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/sessions/sess_V1StGXR8Z5jdHi6B \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "status": "closed" }'