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

# API Overview

> How the NBQ Engine REST API works.

The NBQ Engine exposes a REST API. Your application calls it each time it needs to decide which question to present to the user next.

## Base URL

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

## Authentication

Every request must include your API key in the `Authorization` header:

```
Authorization: Bearer nbq_live_xxx
```

Generate and manage your API keys in the [NBQ Studio](https://client.zelinqa.ai).

## Endpoints

| Method | Path                                   | Description                           |
| ------ | -------------------------------------- | ------------------------------------- |
| `GET`  | `/v1/health`                           | Check API availability                |
| `POST` | `/v1/next-questions`                   | Returns the next best question to ask |
| `POST` | `/v1/sessions/{session_id}/conversion` | Records the outcome of a conversation |

### POST /v1/next-questions

This is the main endpoint. Call it each time your application needs to decide which question to ask next. The engine analyses the conversation so far and returns the single most relevant question.

You must send either `conversation_history` (the full message list) or `context` (a plain-text summary) with every request, along with a `session_id` that stays the same throughout the conversation.

### POST /v1/sessions/{session_id}/conversion

Call this once per conversation when a meaningful result is reached — a purchase, a lead capture, or an abandonment. This powers the conversion analytics in the NBQ Studio Dashboard.

## Key properties

<CardGroup cols={2}>
  <Card title="Stateless" icon="arrows-rotate">
    The API stores no session state. Every request must include the full conversation context.
  </Card>

  <Card title="One question per call" icon="circle-1">
    Each response contains exactly one next question — the most relevant one for that moment.
  </Card>

  <Card title="Scores are private" icon="lock">
    Internal ranking scores are never returned. Only the selected question is exposed.
  </Card>

  <Card title="Safe retries" icon="rotate-right">
    The conversion endpoint accepts an `Idempotency-Key` header so retries are always safe.
  </Card>
</CardGroup>