Skip to main content
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

  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.
If your backend restarts, read the session with GET /v1/sessions/{session_id}. Do not rebuild state from a stale local copy.

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

First API call

Follow the complete curl example.

API reference

Explore routes, schemas, and response codes.
Call NBQ from your backend. Never expose a key in browser JavaScript or a mobile bundle.