> ## 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. # Get Next Question > Returns the next best question to ask in the current conversation. You must provide at least one of `conversation_history` or `context`. The last message in `conversation_history` must have `role: "user"`. ## OpenAPI ````yaml /openapi.yaml post /v1/next-questions openapi: 3.1.0 info: title: NBQ Engine API description: >- The NBQ Engine REST API returns the next best question to ask during a conversation. version: 1.0.0 servers: - url: https://api.zelinqa.ai description: Production security: - bearerAuth: [] tags: - name: Health description: API health check - name: Questions description: Next-question selection - name: Sessions description: Conversation outcome recording paths: /v1/next-questions: post: tags: - Questions summary: Get Next Question description: > Returns the next best question to ask in the current conversation. You must provide at least one of `conversation_history` or `context`. The last message in `conversation_history` must have `role: "user"`. operationId: getNextQuestion requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NextQuestionRequest' examples: with_history: summary: Using conversation history value: session_id: conv-7f3a1c conversation_history: - role: assistant content: Hi! Tell me about the space you are furnishing. - role: user content: I am looking for an outdoor dining table for my terrace. answered_question_ids: [] with_context: summary: Using a context summary value: session_id: conv-7f3a1c context: >- Visitor wants an outdoor dining table for a south-facing terrace. Prefers contemporary metal design. Budget not yet discussed. answered_question_ids: [] responses: '200': description: Next question returned content: application/json: schema: $ref: '#/components/schemas/NextQuestionResponse' examples: with_question: summary: Question returned value: next_question: external_id: q_budget_range text: What budget range did you have in mind for the table? exhausted: false nbq_version: 0.9.0-beta.1 request_id: req_3b9f0a1c2d4e6f80 exhausted: summary: No more questions value: next_question: null exhausted: true nbq_version: 0.9.0-beta.1 request_id: req_91a2b3c4d5e6f708 '403': description: Unauthorized — missing, malformed, or revoked API key content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' example: type: https://api.zelinqa.ai/errors/missing_tenant_id title: Missing or invalid API key status: 403 request_id: req_2c4e6a8b0d1f3508 '422': description: Validation error — request body failed validation content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' example: type: https://api.zelinqa.ai/errors/validation_failed title: Request body or parameters failed validation. status: 422 request_id: req_2c4e6a8b0d1f3508 detail: >- Value error, invalid_request: provide conversation_history or context errors: - loc: - body msg: >- Value error, invalid_request: provide conversation_history or context type: value_error '429': description: Too many requests — rate limit or quota reached content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' example: type: https://api.zelinqa.ai/errors/internal_error title: An unexpected server error occurred. status: 500 request_id: req_2c4e6a8b0d1f3508 components: schemas: NextQuestionRequest: type: object required: - session_id properties: session_id: type: string minLength: 1 maxLength: 128 description: > A stable identifier for the conversation. Reuse the same value for every call within one conversation — this is how usage is counted. example: conv-7f3a1c conversation_history: type: array maxItems: 50 description: > The full conversation so far, as an ordered list of messages. Required if `context` is not provided. The last message must have `role: "user"`. items: type: object required: - role - content properties: role: type: string enum: - user - assistant description: '`user` for the end user, `assistant` for your application' content: type: string minLength: 1 maxLength: 2000 description: The text of the message context: type: string maxLength: 8000 description: > A free-text summary of the conversation so far. Required if `conversation_history` is not provided. Include facts gathered, user segment, and latest intent. Maximum 8000 characters. example: >- Visitor wants an outdoor dining table for a south-facing terrace. Prefers contemporary metal. Budget not yet discussed. answered_question_ids: type: array maxItems: 200 description: > The `external_id` values of questions already asked and answered. NBQ excludes these so it never repeats a question. items: type: string example: - q_budget_range - q_seating_capacity NextQuestionResponse: type: object properties: next_question: description: The recommended next question, or `null` when `exhausted` is `true`. oneOf: - type: object required: - external_id - text properties: external_id: type: string description: The question ID as defined in the NBQ Studio Questions area. example: q_budget_range text: type: string description: The question text to display to the user. example: What budget range did you have in mind for the table? - type: 'null' exhausted: type: boolean description: >- `true` when all eligible questions have been asked. Treat this as the signal to end the question flow. example: false nbq_version: type: string description: >- Version identifier of the active NBQ Studio configuration. Include in logs and support requests. example: 0.9.0-beta.1 request_id: type: string description: Unique ID for this API call. Include in any support request. example: req_3b9f0a1c2d4e6f80 ErrorResponse: type: object description: >- RFC 7807 problem-details format. Returned with Content-Type: application/problem+json. properties: type: type: string description: Stable URI identifying the error class. example: https://api.zelinqa.ai/errors/validation_failed title: type: string description: Short, human-readable summary of the problem. example: Request body or parameters failed validation. status: type: integer description: HTTP status code, mirrored in the body. example: 422 request_id: type: string description: Include in any support request to trace the exact call. example: req_2c4e6a8b0d1f3508 detail: type: string description: Human-readable explanation specific to this occurrence. example: >- Value error, invalid_request: provide conversation_history or context errors: type: array description: Per-field validation problems. Present on 422 validation failures. items: type: object properties: loc: type: array items: type: string msg: type: string type: type: string securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: 'Pass your NBQ API key in the Authorization header: `Bearer nbq_live_xxx`' ````