Ask a question based on uploaded documents or sessions.

​

Sample Request

curl --location 'https://api.usecortex.ai/search/qna' \
  --header 'Authorization: Bearer {API_KEY}' \
  --header 'accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "question": "{QUESTION}",
    "session_id": "{SESSION_ID}",
    "tenant_id": "{TENANT_ID}",
    "sub_tenant_id": "{SUB_TENANT_ID}",
    "stream": {STREAM},
    "context_list": {CONTEXT_LIST},
    "search_modes": {SEARCH_MODES},
    "top_n": {TOP_N},
    "ai_generation": {AI_GENERATION},
    "highlight_chunks": {HIGHLIGHT_CHUNKS},
    "search_alpha": {SEARCH_ALPHA},
    "recency_bias": {RECENCY_BIAS},
    "multi_step_reasoning": {MULTI_STEP_REASONING},
    "user_name": "{USER_NAME}",
    "user_instructions": "{USER_INSTRUCTIONS}",
    "auto_agent_routing": {AUTO_AGENT_ROUTING},
    "metadata": {"source_title": "<optional title>", "source_type": "<optional type>"}
  }'

​

🔐 Headers

• Authorization: Bearer token
• accept: application/json
• Content-Type: application/json

​

🧾 Body Parameters

• question (string, required): The user query
• user_name (string, optional): User name
• user_instructions (string, optional): Accept custom, specific instructions from the user
• session_id (string, required): Chat session ID
• tenant_id (string, required): Tenant identifier
• sub_tenant_id (string, optional): Sub-tenant identifier
• stream (boolean, optional): Enable streaming
• context_list (list of strings, optional): List of document IDs
• search_modes (list of strings, optional): e.g., ‘creative’, ‘web’
• top_n (number, optional): Number of results to return
• ai_generation (boolean, optional): Enable AI answer generation
• highlight_chunks (boolean, optional): Return source chunks
• search_alpha (float, optional): Weight for semantic match
• recency_bias (float, optional): Recency preference
• multi_step_reasoning (boolean, optional, default: true): If enabled, the system will automatically activate multi-step search for complex queries. If set to false, auto-enabling of multi-step search is disabled, and only single-step search will be used regardless of query complexity.
• auto_agent_routing (boolean, optional, default: true): If true, enables routing for choosing the best suitable agent automatically; if false, the answer is generated from the default model
• metadata (object, optional): Filter context to only sources matching the provided metadata. Allowed keys: source_title, source_type. For example, { "source_title": "contract.pdf", "source_type": "document" } will restrict the context to sources with that title and/or type.

Important Note: Cortex internally relies on the metadata field for source matching. You should use this field when you want to deterministically fetch specific documents based on their metadata.

​

📤 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 documents, 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,
        "bbox": [100, 200, 300, 250],
        "coordinates": {
          "x": 100,
          "y": 200,
          "width": 200,
          "height": 50
        }
      },
      "hybrid_score": 0.85,
      "cohere_score": 0.92,
      "bm25_score": 0.78
    }
  ],
  "highlight_chunks": [
    {
      "source_id": "CortexDoc1234",
      "subject": "Document Title",
      "timestamp": "1750697263.2323804"
      "context": "Highlighted text chunk...",
      "source": "document",
      "hybrid_score": 0.85,
      "layout": {
        "page": 1,
        "bbox": [100, 200, 300, 250],
        "coordinates": {
          "x": 100,
          "y": 200,
          "width": 200,
          "height": 50
        }
      },
    }
  ]
}

​

📍 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
• bbox (array): Bounding box coordinates as [x1, y1, x2, y2]
• 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 PDF documents.

​

🚨 Error Responses

• 400: Missing required parameters (question, session_id, tenant_id)
• 401: Invalid or missing API key
• 500: Internal server error during processing