Conversations overview

Conversations give your application a configured assistant that can answer an end user, read platform data through tools, hand work to your own code, and pause for approval before anything changes. You configure the assistant once as a Conversation instance, release it as a numbered version, and then run conversations on it: one thread per end user, each made of turns that stream back over Server-Sent Events (SSE). The platform keeps the transcript, enforces the guardrails you declared, records every tool call, and runs your regression tests before a new version goes live. Your application owns the user interface and any tools that act inside your own systems.

How it works

You create an instance and edit its draft config: system prompt, tools, data access, guardrails, limits, retention, attachments. See Instance configuration.
You publish the draft. The platform replays your gate eval scenarios against it first. A regression refuses the release only when the config sets evals.on_regression to block and no waiver is recorded; under warn the version releases and the failed run is recorded. Each release is an immutable integer version. See Versions and publish.
Your server creates a conversation for one end user.
Your server posts a turn. The platform runs the model loop on the latest published version and streams frames back. See Turns and streaming.
When the model calls one of your client tools, the turn pauses and hands the call to you. When a call has a write, outbound or destructive effect, or the tool is marked requires_confirmation, the turn pauses for a confirmation first. See Client tools and confirmations.
You read the conversation back, rate turns, and export it for review. See Evaluation and Export and retention.

Conversation instance (slug, draft config)
  └── Version 1, 2, 3 ... (immutable, eval-gated)
        └── Conversation (one end user, one environment)
              └── Turn (one user message plus a bounded model loop)
                    └── Messages (user, assistant), each stamped with the config hash it ran under

The objects

Object	What it is	Identified by
Conversation instance	A configured assistant. Holds a mutable draft config and a list of released versions.	`slug`, unique in your org
Version	One immutable release of the draft config. Integers, dense, starting at 1.	`version` plus `config_hash`
Conversation	One thread between the assistant and one end user.	`id` (UUID) plus `end_user`
Turn	One user message, or one resume after a pause, plus the model loop it starts. A turn can span several requests.	`turn_id` (UUID)
Message	One stored user or assistant message made of typed content blocks.	`id` (UUID)

One model, platform owned

Every configured assistant runs the same platform-owned model, gpt-6-sol. Instance configs and turn requests have no model field. A config that sets the retired model_policy.default_model or model_policy.deep_model fails validation with invalid_instance_config, and a turn request that sends the retired depth field returns 400 invalid_request. The only model setting you control is model_policy.max_tokens. Engines and the stateless converse endpoint can use other models; every external model provider is listed on Data use. The stateless converse endpoint is separate: it takes an optional model and stores no conversation.

Turns run released config only

A new message turn resolves the latest published version of the instance. An instance with no published version refuses turns with 409 instance_not_published, and file uploads follow the same rule. Editing the draft never changes what live conversations run until you publish.

Conversations are partitioned by end user

A conversation belongs to one organization, one key environment, one instance, and one end_user. The end_user value is an identifier your server asserts for the person using your application, at most 256 bytes (UTF-8). Every request that reads or writes a conversation must send it. A conversation that exists under a different end user, a different environment, or another org returns 404 conversation_not_found, never 403, so a caller cannot learn that it exists. The platform does not verify end_user. Your server is responsible for sending the right value, which is one reason these routes must be called server to server. The API sends no CORS headers.

Instance status and ownership

Field	Values	Meaning
`status`	`active`, `archived`	Archived instances refuse every conversation route, and the version list, eval, and annotation promotion routes, with `403 instance_archived`. `GET` and `PATCH` on the instance still work, so `PATCH` with `status: active` reactivates one.
`managed_by`	`org`, `platform`	`platform` means Nexio maintains the instance.
`follows_canonical`	`true`, `false`	`true` marks a follower: its config comes from the published versions of a platform-managed instance it follows. A follower returns no local config and refuses config edits, publishes, and scenario authoring with `409 instance_follows_canonical`.

The portal’s built-in assistant is a follower of a platform-managed instance. It appears in the API instance list and does not appear in the portal’s Instances tab.

Credentials

Every public conversation route is under /api/v1/ and takes Authorization: Bearer <key>. Two credential families exist; see Authentication and access.

Action	Organization API key (`nx_<environment>_...`, issued in the portal)	Scoped key (`nxsk_v1_...`, issued by Nexio)
Read instances, versions, eval scenarios, eval runs	Allowed	Needs `conversations:use`
Create, read, update conversations; take turns; branch; attachments; annotations	Allowed	Needs `conversations:use`
Stateless `POST /api/v1/converse`	Allowed	Needs `conversations:use`
Export a conversation	Allowed	Needs `conversations:export`
Create or patch an instance, publish, author or retire eval scenarios, promote an annotation, start an eval run	Allowed	Refused with `403 insufficient_capability` for every scoped key

Authoring is a portal task for most teams. If you hold only a scoped key, create and publish instances in the portal and use the API for conversations.

What you configure (portal)

Conversations, then New instance: create an instance.
The instance’s Config tab: edit the draft, including the Data access checkboxes, publish it, and waive a blocked release.
The Evals tab: write scenarios and start on-demand runs.
The Versions tab: read each released version and its eval result.
The Chat, Conversations, Metrics, and Feedback tabs: try the assistant, read transcripts, watch usage, and read ratings. Nexio staff triage the ratings.

What you call (API)

List instances and read one.
Create a conversation, then take a turn.
Read the conversation, annotate turns, and export it.

Limits

Limit	Value
Turn requests per org	300 per minute, or the default org limit when that is higher (own bucket)
Other conversation routes	Default org bucket, 60 per minute by default
One turn segment, server side	10 minutes
Publish with eval gate	50 minutes end to end
`message` length	32,000 characters
`page_context` size	16 KiB
`end_user` length	256 bytes (UTF-8)
Messages returned by conversation detail	Most recent 500 on the served branch
Request body (`POST`, `PUT` and `PATCH` JSON routes)	1 MiB

Attachment limits are on the Attachments page. All platform limits are on Limits.

Your first conversation

Create a conversation, stream a turn, and read it back.

Turns and streaming

Every frame, stop reason, and error.

Instance configuration

Every config field, bound, and default.

Versions and publish

How the eval gate decides a release.

Start here

Engines

Conversations

Connections and data

Records

Events and webhooks

Platform

Reference

Conversations overview

How it works

The objects

One model, platform owned

Turns run released config only

Conversations are partitioned by end user

Instance status and ownership

Credentials

What you configure (portal)

What you call (API)

Limits

Your first conversation

Turns and streaming

Instance configuration

Versions and publish

​How it works

​The objects

​One model, platform owned

​Turns run released config only

​Conversations are partitioned by end user

​Instance status and ownership

​Credentials

​What you configure (portal)

​What you call (API)

​Limits

Your first conversation

Turns and streaming

Instance configuration

Versions and publish

How it works

The objects

One model, platform owned

Turns run released config only

Conversations are partitioned by end user

Instance status and ownership

Credentials

What you configure (portal)

What you call (API)

Limits