Single-Shot Questions Tutorial

This tutorial demonstrates how to submit single-shot questions to Knowledge Discovery agents and retrieve answers.

Prerequisites

Valid access token (see Authentication)
At least one configured agent with data sources
Discovery User role or higher

Tutorial Overview

In this tutorial, you'll learn to:

Submit a question to an agent
Retrieve answers with source references
Provide feedback on answers
Retrieve question history

Part 1: Submit a Simple Question

Basic Question Submission

Let's start by submitting a simple question to an agent.

HTTP
curl

POST {{baseUrl}}/agent/agents/{{agentId}}/questions
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}
Content-Type: application/json

{
  "question": "What is the company's vacation policy for new employees?",
  "dynamicFilter": null
}

AGENT_ID="hr-agent-id"

curl -X POST "${DISCOVERY_API_BASE_URL}/agent/agents/${AGENT_ID}/questions" \
  -H "Authorization: Bearer ${DISCOVERY_ACCESS_TOKEN}" \
  -H "Hxp-Environment: ${ENVIRONMENT_KEY}" \
  -H "Hxp-App: ${APP_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is the company'\''s vacation policy for new employees?",
    "dynamicFilter": null
  }'

Understanding Question Parameters

Parameter	Required	Description
`question`	Yes	The natural language question text
`dynamicFilter`	No	Runtime filter expression to apply to the search

Asynchronous Processing

The POST /agents/{agentId}/questions endpoint returns 202 Accepted immediately. The question is processed asynchronously. Poll the GET endpoint to retrieve the answer once ready.

Part 2: Retrieve the Answer

After submitting a question, retrieve the answer using the question ID.

HTTP
curl

GET {{baseUrl}}/qna/questions/{{questionId}}/answer
Authorization: Bearer {{accessToken}}

# Wait for processing
sleep 3

curl -X GET "${DISCOVERY_API_BASE_URL}/qna/questions/${QUESTION_ID}/answer" \
  -H "Authorization: Bearer ${DISCOVERY_ACCESS_TOKEN}"

Answer Response Structure

{
  "answer": "New employees are eligible for 15 days of paid vacation per year...",
  "agentId": "hr-agent-id",
  "agentVersion": 1,
  "responseCompleteness": "Complete",
  "objectReferences": [
    {
      "objectId": "doc-123",
      "references": [
        {
          "referenceId": "chunk-456",
          "rankScore": 0.95,
          "rank": 1
        }
      ]
    }
  ],
  "question": "What is the company's vacation policy for new employees?",
  "feedback": null,
  "staticFilter": null,
  "dynamicFilter": null
}

Response Completeness Values

Value	Meaning
`Submitted`	Question has been submitted and is being processed
`Complete`	Answer has been generated and is ready
`Error`	An error occurred during processing

Part 3: Provide Feedback

Users can provide feedback on answers to help improve the system.

HTTP
curl

POST {{baseUrl}}/qna/questions/{{questionId}}/answer/feedback
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}
Content-Type: application/json

{
  "feedback": "Good"
}

curl -X POST "${DISCOVERY_API_BASE_URL}/qna/questions/${QUESTION_ID}/answer/feedback" \
  -H "Authorization: Bearer ${DISCOVERY_ACCESS_TOKEN}" \
  -H "Hxp-Environment: ${ENVIRONMENT_KEY}" \
  -H "Hxp-App: ${APP_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"feedback": "Good"}'

Feedback Values

Supported feedback types:

"Good" - Answer was helpful and accurate
"Bad" - Answer was not helpful or contained errors
"Retry" - Request to regenerate the answer

Part 4: Retrieve Question History

Retrieve the history of questions asked to a specific agent.

HTTP
curl

GET {{baseUrl}}/qna/agents/{{agentId}}/questions/history?pageNumber=1&pageSize=50
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}

AGENT_ID="agent-id"

curl -X GET "${DISCOVERY_API_BASE_URL}/qna/agents/${AGENT_ID}/questions/history?pageNumber=1&pageSize=50" \
  -H "Authorization: Bearer ${DISCOVERY_ACCESS_TOKEN}" \
  -H "Hxp-Environment: ${ENVIRONMENT_KEY}" \
  -H "Hxp-App: ${APP_KEY}"

Query Parameters

Parameter	Required	Default	Description
`pageNumber`	No	1	Page number for pagination
`pageSize`	No	100	Number of items per page (max: 100)
`maxContentLength`	No	null	Maximum length of question/answer content (10-1000)

Response Structure

{
  "data": [
    {
      "id": "c9d6f822-e88c-48a7-bfb9-1f91e7214b40",
      "question": "What is the company's vacation policy for new employees?",
      "answer": "New employees are eligible for 15 days of paid vacation per year...",
      "dateCreated": "2025-11-12T10:30:00Z",
      "dateAnswered": "2025-11-12T10:30:15Z",
      "agentVersion": 1,
      "responseCompleteness": "Complete",
      "feedback": "Good",
      "staticFilter": null,
      "dynamicFilter": null
    },
    {
      "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
      "question": "What are the office hours?",
      "answer": "Office hours are Monday to Friday, 9 AM to 5 PM.",
      "dateCreated": "2025-11-12T09:15:00Z",
      "dateAnswered": "2025-11-12T09:15:10Z",
      "agentVersion": 1,
      "responseCompleteness": "Complete",
      "feedback": null,
      "staticFilter": null,
      "dynamicFilter": null
    }
  ],
  "pagination": {
    "pageSize": 50,
    "pageNumber": 1,
    "totalItems": 125,
    "totalPages": 3
  }
}

Understanding the Response

Field	Type	Description
`data`	array	Array of question history items
`data[].id`	UUID	Question identifier
`data[].question`	string	The question text
`data[].answer`	string (nullable)	The answer text (null if error or still processing)
`data[].dateCreated`	datetime	When the question was submitted
`data[].dateAnswered`	datetime (nullable)	When the answer was generated
`data[].agentVersion`	integer	Version of the agent used
`data[].responseCompleteness`	enum	Status: `Submitted`, `Complete`, `Error`
`data[].feedback`	enum (nullable)	User feedback: `Good`, `Bad`, `Retry`
`data[].staticFilter`	object (nullable)	Static filters applied
`data[].dynamicFilter`	object (nullable)	Dynamic filters applied
`pagination.pageSize`	integer	Items per page
`pagination.pageNumber`	integer	Current page number
`pagination.totalItems`	integer	Total number of questions
`pagination.totalPages`	integer	Total number of pages

Summary

In this tutorial, you learned how to:

✅ Submit questions to agents
✅ Retrieve answers with source references
✅ Provide feedback on answer quality
✅ Retrieve question history for an agent

Prerequisites​

Tutorial Overview​

Part 1: Submit a Simple Question​

Basic Question Submission​

Understanding Question Parameters​

Part 2: Retrieve the Answer​

Answer Response Structure​

Response Completeness Values​

Part 3: Provide Feedback​

Feedback Values​

Part 4: Retrieve Question History​

Query Parameters​

Response Structure​

Understanding the Response​

Summary​