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.

​
Examples

  • API Request
  • TypeScript
  • Python (Sync)
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

Body

application/json
​
question
string
required
Example:
​
session_id
string
required
Example:
​
tenant_id
string
required
Example:
​
context_list
string[] | null
​
search_modes
string[] | null
​
sub_tenant_id
string | null
default:""
Example:
​
highlight_chunks
boolean | null
default:false
​
stream
boolean | null
default:false
​
search_alpha
number | null
default:0.8
​
recency_bias
number | null
default:0.2
​
ai_generation
boolean | null
default:true
​
top_n
integer | null
​
user_name
string | null
default:""
Example:
​
user_instructions
string | null
default:""
​
multi_step_reasoning
boolean | null
default:true
​
auto_agent_routing
boolean | null
default:true
​
metadata
object | null

Response