Skip to main content
POST
/
search
/
retrieve
Search
curl --request POST \
  --url https://api.usecortex.ai/search/retrieve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "Which mode does user prefer",
  "tenant_id": "tenant_1234",
  "sub_tenant_id": "sub_tenant_4567",
  "max_chunks": 123,
  "mode": "fast",
  "alpha": 123,
  "recency_bias": 123,
  "personalise_search": true,
  "graph_context": true,
  "extra_context": "<string>"
}'
{
  "chunks": [
    {
      "chunk_uuid": "doc_a1b2c3d4e5f6...",
      "chunk_content": "Sarah Chen founded Acme Corp in 2019 after leaving her role at TechGiant.",
      "source_title": "company-history.md",
      "relevancy_score": 0.85,
      "graph_triplet_ids": [
        "g_0"
      ]
    },
    {
      "chunk_uuid": "doc_x7y8z9a0b1c2...",
      "chunk_content": "Marcus Johnson joined as CTO and leads the Platform team, reporting directly to Sarah.",
      "source_title": "org-structure.md",
      "relevancy_score": 0.72,
      "graph_triplet_ids": [
        "g_1",
        "g_2"
      ]
    }
  ],
  "graph_relations": {
    "entity_paths": [
      {
        "combined_context": "Sarah Chen is the founder and CEO of Acme Corp. | Marcus Johnson serves as CTO at Acme Corp. | Marcus reports directly to Sarah Chen.",
        "triplets": [
          {
            "source": {
              "name": "Sarah Chen",
              "type": "PERSON",
              "namespace": "employees"
            },
            "target": {
              "name": "Acme Corp",
              "type": "ORGANIZATION"
            },
            "relation": {
              "canonical_predicate": "FOUNDER_OF",
              "context": "Sarah Chen founded Acme Corp in 2019."
            }
          },
          {
            "source": {
              "name": "Marcus Johnson",
              "type": "PERSON",
              "namespace": "employees"
            },
            "target": {
              "name": "Acme Corp",
              "type": "ORGANIZATION"
            },
            "relation": {
              "canonical_predicate": "WORKS_AT",
              "context": "Marcus Johnson is the CTO at Acme Corp."
            }
          },
          {
            "source": {
              "name": "Marcus Johnson",
              "type": "PERSON"
            },
            "target": {
              "name": "Sarah Chen",
              "type": "PERSON"
            },
            "relation": {
              "canonical_predicate": "REPORTS_TO",
              "context": "Marcus reports directly to Sarah."
            }
          }
        ],
        "relevancy_score": 0.78
      }
    ],
    "chunk_triplets": {
      "g_0": {
        "source": {
          "name": "Sarah Chen",
          "type": "PERSON"
        },
        "target": {
          "name": "Acme Corp",
          "type": "ORGANIZATION"
        },
        "relation": {
          "canonical_predicate": "FOUNDER_OF",
          "context": "Sarah Chen founded Acme Corp in 2019 after leaving TechGiant."
        },
        "relevancy_score": 0.85
      },
      "g_1": {
        "source": {
          "name": "Marcus Johnson",
          "type": "PERSON"
        },
        "target": {
          "name": "Acme Corp",
          "type": "ORGANIZATION"
        },
        "relation": {
          "canonical_predicate": "WORKS_AT",
          "context": "Marcus Johnson is the CTO at Acme Corp."
        },
        "relevancy_score": 0.72
      },
      "g_2": {
        "source": {
          "name": "Marcus Johnson",
          "type": "PERSON"
        },
        "target": {
          "name": "Sarah Chen",
          "type": "PERSON"
        },
        "relation": {
          "canonical_predicate": "REPORTS_TO",
          "context": "Marcus reports directly to Sarah as CTO."
        },
        "relevancy_score": 0.68
      }
    }
  },
  "metadata": {}
}
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/retrieve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "Which mode does user prefer",
  "tenant_id": "tenant_1234",
  "sub_tenant_id": "sub_tenant_4567",
  "alpha": 0.8,
  "recency_bias": 0,
  "personalise_search": true
}'
Search across your tenant’s knowledge base using both semantic and keyword matching for comprehensive results.
Default Sub-Tenant Behavior: If you don’t specify a sub_tenant_id, the search will be performed within the default sub-tenant created when your tenant was set up. This searches across organization-wide documents.

​
Search Modes

The Hybrid Search endpoint combines multiple search strategies to provide the most relevant results:
  • Purpose: Finds content based on meaning and context, not just exact keywords
  • Best for: Conceptual queries, finding related content, understanding intent
  • Example: Searching for “machine learning” will also find content about “AI”, “neural networks”, “deep learning”
  • Purpose: Finds content containing specific terms or phrases
  • Best for: Exact term matching, technical specifications, proper nouns
  • Example: Searching for “TensorFlow 2.0” will find documents mentioning this specific version

​
Hybrid Approach

  • Purpose: Combines semantic understanding with keyword precision
  • Best for: Most use cases where you want both relevance and accuracy
  • Example: “Python data analysis libraries” finds both semantic matches (pandas, numpy) and exact keyword matches

​
Search Parameters

​
Alpha Parameter

Controls the balance between semantic and keyword search:
  • 0.0 - Pure keyword search only
    • Best for: Exact term matching, technical specifications
    • Use when: You need precise keyword matches
  • 1.0 - Pure semantic search only
    • Best for: Conceptual queries, finding related content
    • Use when: You want to discover related concepts
  • 0.8 - Default balanced approach (recommended)
    • Best for: Most general use cases
    • Provides optimal balance of precision and recall
  • "auto" - Intelligent auto-selection
    • Cortex analyzes your query and chooses the optimal alpha
    • Best for: When you’re unsure which approach to use

​
Recency Bias

Controls how much recent content is prioritized:
  • 0.0 - No recency bias (default)
  • 0.1-0.5 - Light to moderate recency preference
  • 0.6-1.0 - Strong recency preference
  • Best for: News, documentation updates, time-sensitive information

​
Max Chunks

Controls the number of results returned:
  • Range: 1-1001 chunks
  • Default: System limit
  • Recommendation: Start with 10-20 for most use cases
Enables personalized search results based on user memories from the corresponding tenant and sub-tenant combination:
  • true - Enable personalized search results
    • Leverages user memories stored in the tenant/sub-tenant combination
    • Provides more relevant and tailored search results
    • Considers user’s historical interactions and preferences
  • false - Standard search without personalization (default)
    • Returns results based purely on content relevance
    • No user-specific context applied
Best Practice: Enable personalise_search for applications where user context significantly impacts result relevance, such as personalized dashboards, recommendation systems, or user-specific knowledge bases.

​
Knowledge Graph Context

Search results are automatically enriched with knowledge graph context, providing entity relationships extracted from your content. What’s included in responses:
  • extra_context.chunk_relations — Entities and relationships found within each chunk
  • extra_graph_context — Additional entity relationships extracted from your query
This helps your AI understand not just what is mentioned, but how things relate—like knowing that “Sarah Chen” leads “Project Phoenix” which depends on the “Authentication Service”. network

Learn More: Knowledge Graphs

See how to leverage entity relationships, build context for your LLM, and create intelligent features with graph data.

​
Search Optimization Tips

​
For Better Precision

  • Use lower alpha values (0.2-0.4) for exact term matching
  • Include specific terminology in your queries
  • Set higher max_chunks to get more comprehensive results

​
For Better Recall

  • Use higher alpha values (0.6-0.8) for broader semantic matching
  • Try synonyms and related terms in your queries
  • Use conceptual language rather than specific terms
  • Enable recency bias for time-sensitive content

​
For Complex Queries

  • Use “auto” alpha to let Cortex optimize automatically
  • Combine specific terms with conceptual language
  • Adjust recency bias based on content type
  • Experiment with different alpha values to find optimal results
  • Enable personalise_search for user-specific contexts and preferences

​
Alpha Parameter

The alpha parameter controls the balance between semantic and keyword search:
  • 0.0 = keyword search only
  • 1.0 = semantic search only
  • 0.8 = default balanced approach
  • "auto" = Cortex intelligently decides the optimal alpha value based on the query

​
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
​
query
string
required
Example:
​
tenant_id
string
required
Example:
​
sub_tenant_id
string | null
default:""
Example:
​
max_chunks
integer | null
​
mode
enum<string>
Available options:
fast,
accurate
​
alpha
default:0.8
​
recency_bias
number | null
default:0
​
personalise_search
boolean | null
default:false
​
graph_context
boolean | null
default:false
​
extra_context
string | null

Response

​
chunks
SearchChunk · object[]
Example:
​
graph_relations
object | null
​
metadata
object