> ## 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.

# REST API

> Integrate NBQ V1 directly from any server-side language.

The REST API is the V1 integration available today. Your backend keeps the identifiers returned by NBQ and calls the engine whenever your experience needs a new question.

## Responsibilities

| Your application                           | NBQ Engine                                   |
| ------------------------------------------ | -------------------------------------------- |
| Display or rephrase the question           | Select the best candidates                   |
| Keep `session_id` and `state_version`      | Maintain canonical session state             |
| Send the answer that was actually observed | Understand the answer and update progress    |
| Decide when to end the experience          | Report warnings and the absence of questions |
| Protect the API key on the server          | Enforce isolation, scopes, and idempotency   |

## Recommended loop

1. Create a session once with `POST /v1/sessions`.
2. Call `/next` with the latest `state_version`.
3. Use `candidates[0]`, or select another candidate if your product requires it.
4. After the answer, call `/next` again with `previous_turn`.
5. Send external information through `/events` without triggering a new selection.
6. Submit the final outcome through `/feedback`.

<Note>
  If your backend restarts, read the session with `GET /v1/sessions/{session_id}`. Do not rebuild state from a stale local copy.
</Note>

## Choice answers

When your interface displays choices provided by NBQ, return their `choice_id` values in `structured_answer.choice_ids`. This avoids unnecessary semantic interpretation and preserves deterministic mapping.

## Prefer structured answers

When your application already knows what an answer means, send that interpretation directly:

* `previous_turn.outcome` reports whether the question was answered, left unanswered, or explicitly refused;
* `structured_answer.choice_ids` sends selections from a closed or semi-open question;
* `client_updates.data` sends business data already validated by your system.

```json theme={null}
{
  "state_version": 3,
  "previous_turn": {
    "decision_id": "dec_7f2a",
    "question_id": "q_budget",
    "outcome": "asked_answered"
  },
  "client_updates": {
    "data": [
      { "id": "info_budget", "operation": "set", "value": 3000 }
    ]
  }
}
```

This path is deterministic: NBQ validates and applies structured information without asking a language model to reinterpret the text. It is therefore faster and more reproducible. Do not manufacture an uncertain value: when your application only knows the verbatim answer, send `user_text` and let NBQ analyze it.

<Note>
  `outcome` describes the result of the question, but does not create business data by itself. Also send `structured_answer` or `client_updates` when your system knows the information obtained.
</Note>

<CardGroup cols={2}>
  <Card title="First API call" icon="terminal" href="/en/quickstart/first-api-call">
    Follow the complete curl example.
  </Card>

  <Card title="API reference" icon="book" href="/en/api-reference/overview">
    Explore routes, schemas, and response codes.
  </Card>
</CardGroup>

<Warning>
  Call NBQ from your backend. Never expose a key in browser JavaScript or a mobile bundle.
</Warning>