Skip to main content
Once you have configured NBQ and generated an API key, you are ready to call the API.

​
The endpoint

POST https://api.zelinqa.ai/v1/next-questions

​
Minimal test with curl

Start with an empty conversation — no history, no answered questions yet: 
curl -X POST https://api.zelinqa.ai/v1/next-questions \
  -H "Authorization: Bearer nbq_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_lead_42",
    "conversation_history": [
      { "role": "user", "content": "Hi, I'd like to learn more about your solution." }
    ],
    "answered_question_ids": []
  }'

​
Example response

{
  "next_question": {
    "external_id": "q_volume",
    "text": "Combien de conversations par mois ?"
  },
  "exhausted": false,
  "nbq_version": "0.9.0-beta.1",
  "request_id": "req_a1b2c3"
}

​
Using the returned question — two patterns

NBQ returns exactly one question: { external_id, text }. You have two ways to use it:

Pattern A — show it directly

Render next_question.text straight to the user. Simplest integration — NBQ drives the wording entirely.

Pattern B — hand it to your agent

Pass next_question.text to your own LLM as “the next question to ask” and let your agent phrase it naturally. NBQ decides what to ask; your agent decides how.
In both patterns, once a question is asked, add its external_id to answered_question_ids on the next call so it is never repeated.

​
The conversation loop

After the first call, repeat this cycle for each turn:
1

Display the question

Show next_question.text to the user.
2

Record the answer

Update your conversation state — either append the reply to conversation_history, or update your context summary. Send at least one of the two on every call.
3

Track the answered question

Add next_question.external_id to your answered_question_ids list.
4

Call the API again

Send the updated context to get the next question.
5

Check for exhausted

When "exhausted": true, all eligible questions have been asked. End the flow.
When exhausted is true, next_question will be null. Your application should handle this to gracefully close or continue the conversation flow.