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

# Votre premier appel API

> Effectuez votre premier appel à l'API NBQ Engine.

Une fois que vous avez configuré NBQ et généré une clé API, vous êtes prêt à appeler l'API.

## Le point de terminaison

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

## Test minimal avec curl

Commencez avec une conversation vide — sans historique, sans questions répondues :

```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": "Bonjour, je souhaite en savoir plus sur votre solution." }
    ],
    "answered_question_ids": []
  }'
```

## Exemple de réponse

```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"
}
```

## Utiliser la question retournée — deux approches

NBQ retourne exactement une question : `{ external_id, text }`. Deux façons de l'utiliser :

<CardGroup cols={2}>
  <Card title="Approche A — afficher directement" icon="eye">
    Affichez `next_question.text` directement à l'utilisateur. Intégration la plus simple — NBQ gère entièrement la formulation.
  </Card>

  <Card title="Approche B — passer à votre agent" icon="robot">
    Transmettez `next_question.text` à votre propre LLM comme *"la prochaine question à poser"* et laissez votre agent la formuler naturellement. NBQ décide **quoi** demander ; votre agent décide **comment**.
  </Card>
</CardGroup>

Dans les deux approches, une fois la question posée, ajoutez son `external_id` dans `answered_question_ids` au prochain appel pour qu'elle ne soit jamais répétée.

## La boucle de conversation

Après le premier appel, répétez ce cycle à chaque tour :

<Steps>
  <Step title="Afficher la question">
    Montrez `next_question.text` à l'utilisateur.
  </Step>

  <Step title="Enregistrer la réponse">
    Mettez à jour l'état de la conversation — soit en ajoutant la réponse à `conversation_history`, soit en mettant à jour votre résumé `context`. Envoyez au moins l'un des deux à chaque appel.
  </Step>

  <Step title="Suivre la question répondue">
    Ajoutez `next_question.external_id` à votre liste `answered_question_ids`.
  </Step>

  <Step title="Rappeler l'API">
    Envoyez le contexte mis à jour pour obtenir la prochaine question.
  </Step>

  <Step title="Vérifier exhausted">
    Quand `"exhausted": true`, toutes les questions éligibles ont été posées. Terminez le flux.
  </Step>
</Steps>

<Note>
  Quand `exhausted` est `true`, `next_question` sera `null`. Votre application doit gérer ce cas pour clore ou poursuivre le flux de conversation de manière appropriée.
</Note>