> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zelinqa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Session lifecycle

> Create, advance, resume, and complete an NBQ V1 conversation.

A V1 session is durable server-side state. Create it once, then advance it with mutations protected against duplicate requests and concurrent writes.

<Steps>
  <Step title="Create the session">
    `POST /v1/sessions` creates a `session_id` and returns `versions.state_version: 0`. The session is pinned to the active published configuration.
  </Step>

  <Step title="Request the first question">
    `POST /v1/sessions/{session_id}/next` with `state_version: 0` returns a decision and ranked candidates.
  </Step>

  <Step title="Send the next turn">
    Send the new `state_version` and, when available, the `decision_id`, `question_id`, actual text asked, and visitor answer.
  </Step>

  <Step title="Apply external information">
    `/events` adds a summary, missed messages, or known CRM data without immediately selecting a question.
  </Step>

  <Step title="Read or resume">
    `GET /v1/sessions/{session_id}` returns the public state. Resume after an interruption with the latest `state_version`.
  </Step>

  <Step title="Report the outcome">
    `/feedback` records success, failure, or another business outcome. It replaces the limited 0.9 beta “conversion” concept.
  </Step>
</Steps>

## Two values to keep

| Value                    | Purpose                                                                                            |
| ------------------------ | -------------------------------------------------------------------------------------------------- |
| `session_id`             | Identifies the entire conversation.                                                                |
| `versions.state_version` | Prevents concurrent updates from overwriting the same state. Always use the latest received value. |

`decision_id` and `question_id` improve turn correlation but remain optional: NBQ can recover the pending decision from observed messages.

## Soft stopping rules

`max_turns` is a soft limit. Once reached, NBQ may still return the best available question with a warning. Your application decides whether to continue or stop. `action: stop` means no identifiable question is available.

<Warning>
  Never reuse an old `state_version`. After a conflict, read the session again before rebuilding your mutation.
</Warning>