Skip to main content
POST
/
api
/
r2r
/
v3
/
retrieval
/
search
Search R2R
curl --request POST \
  --url https://api.intelligence.io.solutions/api/r2r/v3/retrieval/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "<string>",
  "search_mode": "basic",
  "search_settings": {
    "use_hybrid_search": false,
    "use_semantic_search": true,
    "use_fulltext_search": false,
    "filters": "<string>",
    "limit": 10,
    "offset": "0",
    "include_metadatas": true,
    "include_scores": true,
    "search_strategy": "vanilla",
    "hybrid_settings": {
      "full_text_weight": 1,
      "semantic_weight": 5,
      "full_text_limit": 200,
      "rrf_k": 50
    },
    "chunk_settings": {
      "index_measure": "l2_distance",
      "probes": 10,
      "ef_search": 40,
      "enabled": true
    },
    "graph_settings": {
      "limits": [
        "<any>"
      ],
      "enabled": true
    },
    "num_sub_queries": 5
  }
}'
{
  "results": {
    "chunk_search_results": [
      {
        "id": "3f3d47f3-8baf-58eb-8bc2-0171fb1c6e09",
        "document_id": "3e157b3a-8469-51db-90d9-52e7d896b49b",
        "collection_ids": [
          "collection_ids"
        ],
        "text": "Example text from the document",
        "metadata": {
          "associated_query": "What is the capital of France?",
          "title": "example_document.pdf"
        },
        "owner_id": "2acb499e-8428-543b-bd85-0d9098718220",
        "score": 0.23943702876567796
      }
    ],
    "graph_search_results": [
      {
        "content": {
          "id": "3f3d47f3-8baf-58eb-8bc2-0171fb1c6e09",
          "name": "Entity Name",
          "description": "Entity Description",
          "metadata": {
            "key": "value"
          }
        },
        "id": "id",
        "result_type": "entity",
        "chunk_ids": [
          "c68dc72e-fc23-5452-8f49-d7bd46088a96"
        ],
        "metadata": {
          "associated_query": "What is the capital of France?"
        }
      }
    ],
    "web_search_results": [
      {
        "position": 1,
        "id": "id",
        "title": "Page Title",
        "link": "https://example.com/page",
        "snippet": "Page snippet",
        "date": "2021-01-01",
        "sitelinks": [
          {
            "link": "https://example.com/sitelink",
            "title": "Sitelink Title"
          }
        ]
      }
    ],
    "document_search_results": [
      {
        "id": "id",
        "collection_ids": [
          "collection_ids"
        ],
        "owner_id": "owner_id",
        "document_type": "mp3",
        "metadata": {
          "key": "value"
        },
        "version": "version"
      }
    ]
  }
}
The Search endpoint provides advanced retrieval capabilities across documents, chunks, and knowledge graphs within R2R. It supports multiple search modes, hybrid vector and keyword retrieval, graph-enhanced search, and metadata-based filtering, enabling powerful and flexible information discovery for semantic, contextual, and RAG-driven applications. This endpoint is designed for both simple semantic lookups and complex, structured search workflows that combine multiple retrieval strategies.

​
Search Modes

The search_mode field determines the level of control and type of retrieval performed.
ModeDescription
basicPerforms a standard semantic search using vector embeddings. Ideal for quick and simple retrievals.
advancedCombines semantic search with full-text search for broader and more comprehensive results.
customGrants full control via a SearchSettings object, allowing fine-tuned configurations for specialized applications.

​
Filters

Filters can be used to restrict search results by document attributes or metadata. Apply filters directly inside search_settings.filters. Supported operators: $eq, $neq, $gt, $gte, $lt, $lte, $like, $ilike, $in, $nin. Example: 
{
	"filters": {
		"document_id": {"$eq": "e43864f5-a36f-548e-aacd-6f8d48b30c7f"}
	}
}
Complex Filters Example: 
{
  "filters": {
    "$and": [
      {"document_type": {"$eq": "report"}},
      {"metadata.topic": {"$ilike": "finance"}}
    ]
  }
}
Hybrid search combines semantic similarity with keyword-based retrieval, improving result relevance by leveraging both vector embeddings and traditional text search. Enable hybrid search by setting use_hybrid_search: true in search_settings and configure with hybrid_settings . Configuration Example: 
{
	"use_hybrid_search": true,
	"hybrid_settings": {
    	"full_text_weight": 1.0,
    	"semantic_weight": 5.0,
    	"full_text_limit": 200,
    	"rrf_k": 50
	}
}
Parameters:
  • full_text_weight: Adjusts the influence of keyword search.
  • semantic_weight: Adjusts the influence of semantic similarity.
  • full_text_limit: Limits keyword results before fusion.
  • rrf_k: Rank fusion parameter controlling hybrid blending strength.
The Search API supports knowledge graph integration, enabling entity- and relationship-aware retrieval. This allows search results to include contextually related information based on graph traversal. Knowledge graph integration is enabled by default. Configure it with graph_search_settings . Configuration Example: 
{
	"graph_search_settings": {
    	"use_graph_search": true,
    	"kg_search_type": "local"
	}
}
Parameters:
  • use_graph_search: Enables or disables graph integration.
  • kg_search_type: Defines scope — "local" (collection-level) or "global" (across all graphs).

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json
​
query
string

The search query text

​
search_mode
enum<string>

Default value of custom allows full control over search settings. Pre-configured search modes: basic: A simple semantic-based search. advanced: A more powerful hybrid search combining semantic and full-text. custom: Full control via search_settings. If filters or limit are provided alongside basic or advanced, they will override the default settings for that mode.ID of the collection to search in

Available options:
basic,
advanced,
custom
​
search_settings
object

The search configuration object. If search_mode is custom, these settings are used as-is. For basic or advanced, these settings will override the default mode configuration. Common overrides include filters to narrow results and limit to control how many results are returned.

Response

200

​
results
object