> ## Documentation Index > Fetch the complete documentation index at: https://docs.usenexio.com/llms.txt > Use this file to discover all available pages before exploring further. # Conversations overview > Understand instances, versions, conversations, and turns, and which credential can do what. 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 1. You create an instance and edit its draft config: system prompt, tools, data access, guardrails, limits, retention, attachments. See [Instance configuration](/conversations/configuration). 2. 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](/conversations/versions-and-publish). 3. Your server creates a conversation for one end user. 4. Your server posts a turn. The platform runs the model loop on the latest published version and streams frames back. See [Turns and streaming](/conversations/turns-and-streaming). 5. 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](/conversations/client-tools). 6. You read the conversation back, rate turns, and export it for review. See [Evaluation](/conversations/evaluation) and [Export and retention](/conversations/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](/reference/data-use). The [stateless converse endpoint](/conversations/stateless-converse) 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 `. Two credential families exist; see [Authentication and access](/authentication). | Action | Organization API key (`nx__...`, 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](/api-reference/conversations/instances/list-instances) and [read one](/api-reference/conversations/instances/get-instance). * [Create a conversation](/api-reference/conversations/conversations/create-conversation), then [take a turn](/api-reference/conversations/turns/take-turn). * [Read the conversation](/api-reference/conversations/conversations/get-conversation), [annotate turns](/api-reference/conversations/annotations/create-annotation), and [export it](/api-reference/conversations/export/export-conversation). ## 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](/conversations/attachments) page. All platform limits are on [Limits](/reference/limits). Create a conversation, stream a turn, and read it back. Every frame, stop reason, and error. Every config field, bound, and default. How the eval gate decides a release.