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

# Présentation de l'API

> Comment fonctionne l'API REST du NBQ Engine.

Le NBQ Engine expose une API REST. Votre application l'appelle chaque fois qu'elle doit décider quelle question poser ensuite.

## URL de base

```
https://api.zelinqa.ai
```

## Authentification

Incluez votre clé API dans l'en-tête `Authorization` de chaque requête :

```
Authorization: Bearer nbq_live_xxx
```

Générez et gérez vos clés API dans le [NBQ Studio](https://client.zelinqa.ai).

## Points de terminaison

| Méthode | Chemin                                 | Description                                      |
| ------- | -------------------------------------- | ------------------------------------------------ |
| `GET`   | `/v1/health`                           | Vérifier la disponibilité de l'API               |
| `POST`  | `/v1/next-questions`                   | Retourne la prochaine meilleure question à poser |
| `POST`  | `/v1/sessions/{session_id}/conversion` | Enregistre le résultat d'une conversation        |

URL complète :

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

## Propriétés clés

<CardGroup cols={2}>
  <Card title="Sans état" icon="arrows-rotate">
    L'API ne stocke aucun état de session. Chaque requête doit inclure le contexte complet de la conversation.
  </Card>

  <Card title="Une question par appel" icon="circle-1">
    Chaque réponse contient exactement une question suivante — la plus pertinente pour ce moment.
  </Card>

  <Card title="Scores privés" icon="lock">
    Les scores de classement internes ne sont jamais retournés. Seule la question sélectionnée est exposée.
  </Card>

  <Card title="Rejouabilité sûre" icon="rotate-right">
    Le point de terminaison de conversion accepte un en-tête `Idempotency-Key`, de sorte que les tentatives sont toujours sûres.
  </Card>
</CardGroup>

## Architecture sans état

L'API étant sans état, votre application doit envoyer le contexte complet à chaque appel :

| Champ                   | Obligatoire                                            | Description                                |
| ----------------------- | ------------------------------------------------------ | ------------------------------------------ |
| `session_id`            | Oui                                                    | Identifie la conversation en cours         |
| `conversation_history`  | L'un de `conversation_history` ou `context` est requis | Tous les messages échangés jusqu'à présent |
| `context`               | L'un de `conversation_history` ou `context` est requis | Résumé en texte libre de la conversation   |
| `answered_question_ids` | Non                                                    | Identifiants des questions déjà répondues  |

Cela rend l'API prévisible, facile à tester et simple à déboguer.