POST
/
search
/
qna
cURL
curl --request POST \
  --url https://api.usecortex.ai/search/qna \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: <content-type>' \
  --header 'accept: <accept>' \
  --data '{
  "question": "<string>",
  "user_name": "<string>",
  "user_instructions": "<string>",
  "session_id": "<string>",
  "tenant_id": "<string>",
  "sub_tenant_id": "<string>",
  "stream": true,
  "context_list": [
    "<string>"
  ],
  "search_modes": [
    "<string>"
  ],
  "top_n": 20,
  "ai_generation": true,
  "highlight_chunks": true,
  "search_alpha": 0.8,
  "recency_bias": 0.5,
  "multi_step_reasoning": true,
  "auto_agent_routing": true,
  "metadata": {
    "source_title": "<string>",
    "source_type": "<string>"
  }
}'

​
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>"}
  }'

​
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.

Authorizations

​
Authorization
string
header
required

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

Headers

​
Authorization
string
required

Bearer token (your API key)

​
Content-Type
string
default:application/json
required

Request content type

​
accept
string
default:application/json
required

Response content type

Body

application/json