Skip to main content
POST
/
search
/
qna
Qna
curl --request POST \
  --url https://api.usecortex.ai/search/qna \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "question": "What is Cortex AI",
  "session_id": "chat_session_1234",
  "tenant_id": "tenant_1234",
  "context_list": [
    "<string>"
  ],
  "search_modes": [
    "<string>"
  ],
  "sub_tenant_id": "sub_tenant_4567",
  "highlight_chunks": true,
  "stream": true,
  "search_alpha": 123,
  "recency_bias": 123,
  "ai_generation": true,
  "top_n": 123,
  "user_name": "John Doe",
  "user_instructions": "<string>",
  "multi_step_reasoning": true,
  "auto_agent_routing": true,
  "metadata": {}
}'
"<any>"
Hit the Try it button to try this API now in our playground. Itโ€™s the best way to check the full request and response in one place, customize your parameters, and generate ready-to-use code snippets.

Sample Request

curl --request POST \
  --url https://api.usecortex.ai/search/qna \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "question": "What is Cortex AI",
  "session_id": "chat_session_1234",
  "tenant_id": "tenant_1234",
  "sub_tenant_id": "sub_tenant_4567",
  "highlight_chunks": false,
  "stream": false,
  "search_alpha": 0.8,
  "recency_bias": 0.2,
  "ai_generation": true,
  "user_name": "John Doe",
  "user_instructions": "",
  "multi_step_reasoning": true,
  "auto_agent_routing": true
}'
Ask questions and get AI-generated answers based on your tenantโ€™s knowledge base with conversational responses and citations.
Default Sub-Tenant Behavior: If you donโ€™t specify a sub_tenant_id, the QnA will search within the default sub-tenant created when your tenant was set up. This searches across organization-wide documents and knowledge.

QnA Capabilities

The QnA endpoint provides intelligent question-answering with several powerful features:

AI-Generated Responses

  • Natural Language Processing: Understands complex questions and context
  • Citation-Based Answers: Every answer includes source references with exact locations
  • Conversational Context: Maintains conversation history through session management
  • Multi-Step Reasoning: Can break down complex questions into logical steps

Advanced Search Integration

  • Hybrid Search: Combines semantic and keyword search for optimal results
  • Context-Aware Retrieval: Finds relevant information based on question context
  • Source Highlighting: Identifies and highlights the most relevant content chunks

Customization Options

  • User Instructions: Provide custom instructions to guide AI behavior
  • Metadata Filtering: Filter results by source type, title, or other metadata
  • Streaming Support: Get real-time responses for better user experience
  • Auto-Agent Routing: Automatically route queries to specialized agents

Key Parameters

Core Parameters

Question & Session Management

  • question: The question you want answered (required)
  • session_id: Unique identifier for maintaining conversation context
  • user_name: Optional user identifier for personalized responses

Search Configuration

  • search_alpha: Balance between semantic and keyword search (0.0-1.0)
  • top_n: Number of relevant chunks to retrieve for context
  • recency_bias: Prioritize recent content (0.0-1.0)

AI Generation Control

  • ai_generation: Enable/disable AI response generation
  • multi_step_reasoning: Enable complex reasoning for difficult questions
  • user_instructions: Custom instructions to guide AI behavior
  • auto_agent_routing: Automatically route to specialized agents

Response Formatting

  • stream: Enable streaming responses for real-time output
  • highlight_chunks: Include highlighted relevant chunks in response
  • context_list: Provide additional context for the AI

Advanced Features

Metadata Filtering

Use the metadata object to filter results:
{
  "metadata": {
    "source_title": "Specific Document Title",
    "source_type": "file",
    "custom_field": "value"
  }
}

Session Management

  • Persistent Context: Maintain conversation history across multiple questions
  • Context Accumulation: Build understanding over multiple interactions
  • User Personalization: Adapt responses based on user preferences

Multi-Step Reasoning

When enabled, the AI can:
  • Break down complex questions into smaller parts
  • Analyze multiple sources of information
  • Synthesize information from different documents
  • Provide step-by-step explanations

Use Cases

Customer Support

  • FAQ Automation: Answer common customer questions automatically
  • Product Information: Provide detailed product specifications and features
  • Troubleshooting: Guide users through problem-solving steps

Knowledge Management

  • Document Q&A: Ask questions about uploaded documents and manuals
  • Research Assistance: Find and synthesize information from multiple sources
  • Training Support: Answer questions about company policies and procedures

Content Discovery

  • Information Retrieval: Find specific information within large document collections
  • Contextual Search: Get answers that understand the broader context
  • Citation Tracking: See exactly where information comes from

Best Practices

Question Formulation

  • Be Specific: Ask clear, specific questions for better results
  • Provide Context: Include relevant background information when needed
  • Use Natural Language: Ask questions as you would to a human expert

Session Management

  • Maintain Context: Use consistent session IDs for related questions
  • Build Understanding: Ask follow-up questions to deepen the conversation
  • Reset When Needed: Start new sessions for unrelated topics

Response Optimization

  • Enable Highlighting: Use highlight_chunks to see source relevance
  • Adjust Search Alpha: Experiment with different values for your content type
  • Use Metadata Filtering: Narrow results to specific document types when needed

Response

Returns a JSON object containing the AI-generated answer and supporting source chunks with layout information for creating bounding boxes around cited sources.
{
  "answer": "Based on the uploaded knowledge, here is the answer to your question...",
  "session_id": "session_123",
  "sources": [
    {
      "id": "source_123",
      "url": "https://example.com/document.pdf",
      "title": "Document Title",
      "timestamp": "2024-01-15T10:30:00Z",
      "context": "This is the relevant text chunk from the document...",
      "source": "document",
      "layout": {
        "page": 1,
        "coordinates": {
          "x": 100,
          "y": 200,
          "width": 200,
          "height": 50
        }
      },
      "hybrid_score": 0.85
    }
  ],
  "highlight_chunks": [
    {
      "source_id": "CortexDoc1234",
      "subject": "Document Title",
      "timestamp": "1750697263.2323804",
      "context": "Highlighted text chunk...",
      "source": "document",
      "hybrid_score": 0.85,
      "layout": {
        "page": 1,
        "coordinates": {
          "x": 100,
          "y": 200,
          "width": 200,
          "height": 50
        }
      }
    }
  ],
  "source_id_map": {
    "s0": {
      "chunk_uuid": "05631d4e-4d24-4a9c-9e7a-e61a3100cafb",
      "source_id": "CortexDoc8156c6834c304451ab569d264da5f38a1750697087"
    },
    "s1": {
      "chunk_uuid": "f7c98cae-566b-4bf1-8d66-9bb556c090b0",
      "source_id": "CortexDoc8156c6834c304451ab569d264da5f38a1750697087"
    },
    "s2": {
      "chunk_uuid": "47a30767-0a79-4960-bb16-e817833f42e8",
      "source_id": "CortexDoc1c8e2cdc1b924cd0951b940ae8f511c91750697218"
    },
    "s3": {
      "chunk_uuid": "419b52e2-65c7-43d1-a4ed-109662c0d130",
      "source_id": "CortexDoc1c8e2cdc1b924cd0951b940ae8f511c91750697218"
    },
    "s4": {
      "chunk_uuid": "7af5563f-04c0-4c3a-b633-815945f5cc2e",
      "source_id": "CortexDocc77864b3aba34e40afcced8b0257f26b1750697112"
    }
  }
}

๐Ÿ“ Layout Field

The layout field provides coordinates for creating bounding boxes around cited sources:
Note: For PowerPoint (PPT) and Excel (XLSX) files, the page field will be returned as an empty string since these file formats donโ€™t use traditional page numbering.
  • page (number): The page number where the content appears
  • coordinates (object): Alternative coordinate format with:
    • x (number): Left position
    • y (number): Top position
    • width (number): Width of the bounding box
    • height (number): Height of the bounding box
This layout information enables you to highlight or create visual indicators around the exact location of cited content within documents.
Important Note: Cortex internally uses Cortex Metadata Agent which is an expert at performing metadata-specific search. Using the metadata field as a filter should only be reserved when you want to deterministically fetch results from specific documents based on their metadata.

Error Responses

All endpoints return consistent error responses following the standard format. For detailed error information, see our Error Responses documentation.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
question
string
required

The question to be answered

Example:

"What is Cortex AI"

session_id
string
required

Unique identifier for the conversation session. Keep it same when the current question refers to a previous answer or question

Example:

"chat_session_1234"

tenant_id
string
required

Identifier for the tenant/organization

Example:

"tenant_1234"

context_list
string[] | null

List of context strings to provide additional information

search_modes
string[] | null

List of search modes to use for finding relevant information

sub_tenant_id
string | null
default:""

Identifier for sub-tenant within the tenant

Example:

"sub_tenant_4567"

highlight_chunks
boolean | null
default:false

Whether to return text chunks in the response along with final LLM generated answer

stream
boolean | null
default:false

Whether to stream the response

search_alpha
number | null
default:0.8

Closer to 0.0 means a exact keyword search will be performed, closer to 1.0 means semantics of the search will be considered. In most cases, you wont have to toggle it yourself.

recency_bias
number | null
default:0.2

Bias towards more recent information (0.0 to 1.0)

ai_generation
boolean | null
default:true

Whether to use AI for generating responses

top_n
integer | null

Number of top results to return

user_name
string | null
default:""

Name of the user making the request. This helps LLM to know the user's name if semantics around the username are involved in query. Its generally a good practice to include it possible.

Example:

"John Doe"

user_instructions
string | null
default:""

Custom instructions for the AI response to add to our proprietary prompt. This can be used to provide additional context or instructions for the LLM to follow so that the answers are tailored towards your application style

multi_step_reasoning
boolean | null
default:true

Enable advanced multi-step reasoning for complex queries. When enabled, the AI will automatically break down complex questions into multiple research steps to provide more comprehensive and accurate answers.

auto_agent_routing
boolean | null
default:true

Enable intelligent agent routing to automatically select the most suitable AI agent for your specific query type. Different agents are optimized for various use cases like social media, code, conversations, general knowledge, etc.

metadata
object | null

Additional metadata for the request

Response

Successful Response

The response is of type any.

โŒ˜I