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
Submit a question with dynamic filters to narrow search results
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: Submit a Question with Dynamic Filter

When to Use Dynamic Filters

Use dynamicFilter when you need to narrow search results at query time based on metadata or document properties. Dynamic filters are applied at runtime, allowing different filter criteria for each question without modifying the agent configuration.

Use dynamic filters for:

Filtering by date ranges (e.g., documents from the last quarter)
Restricting to specific categories or document types
Applying user-specific context (e.g., department, project)
Combining multiple metadata criteria

Dynamic vs. Static Filters:

Static filters are configured in the agent and apply to all queries automatically
Dynamic filters are provided with each question and allow per-query customization
Both can be used together - static filters for permanent restrictions, dynamic filters for runtime flexibility

Dynamic Filter Example

Here's a practical example filtering documents by date and category:

HTTP
curl

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

{
  "question": "What are the latest product updates?",
  "dynamicFilter": {
    "logicalOperator": "And",
    "conditions": [
      {
        "field": "Category",
        "type": "Text",
        "operator": "Equals",
        "value": "Product Updates"
      },
      {
        "field": "PublishedDate",
        "type": "Date",
        "operator": "GreaterThan",
        "value": "2025-01-01"
      }
    ]
  }
}

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 are the latest product updates?",
    "dynamicFilter": {
      "logicalOperator": "And",
      "conditions": [
        {
          "field": "Category",
          "type": "Text",
          "operator": "Equals",
          "value": "Product Updates"
        },
        {
          "field": "PublishedDate",
          "type": "Date",
          "operator": "GreaterThan",
          "value": "2025-01-01"
        }
      ]
    }
  }'

Filter Structure

The filter uses:

logicalOperator: "And", "Or", or "Not" to combine conditions
field: The metadata field name to filter on
type: Field data type - "Text", "Number", "Date", or "Boolean"
operator: Comparison operator (e.g., "Equals", "GreaterThan", "Contains", "Any")
value or values: The value(s) to compare against

For more filter operators and complex examples, see the Managing Agents Tutorial.

Part 3: 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 4: 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 5: 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: Submit a Question with Dynamic Filter​

When to Use Dynamic Filters​

Dynamic Filter Example​

Part 3: Retrieve the Answer​

Answer Response Structure​

Response Completeness Values​

Part 4: Provide Feedback​

Feedback Values​

Part 5: Retrieve Question History​

Query Parameters​

Response Structure​

Understanding the Response​

Summary​