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

# Your First API Call

> Make your first call to the NBQ Engine API.

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:

```bash theme={null}
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

```json theme={null}
{
  "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:

<CardGroup cols={2}>
  <Card title="Pattern A — show it directly" icon="eye">
    Render `next_question.text` straight to the user. Simplest integration — NBQ drives the wording entirely.
  </Card>

  <Card title="Pattern B — hand it to your agent" icon="robot">
    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**.
  </Card>
</CardGroup>

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:

<Steps>
  <Step title="Display the question">
    Show `next_question.text` to the user.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Track the answered question">
    Add `next_question.external_id` to your `answered_question_ids` list.
  </Step>

  <Step title="Call the API again">
    Send the updated context to get the next question.
  </Step>

  <Step title="Check for exhausted">
    When `"exhausted": true`, all eligible questions have been asked. End the flow.
  </Step>
</Steps>

<Note>
  When `exhausted` is `true`, `next_question` will be `null`. Your application should handle this to gracefully close or continue the conversation flow.
</Note>