Search R2R — The most advanced AI retrieval system. Containerized, Retrieval-Augmented Generation (RAG) with a RESTful API.

Perform a search query against vector and/or graph-based databases.

Search Modes:

basic: Defaults to semantic search. Simple and easy to use.
advanced: Combines semantic search with full-text search for more comprehensive results.
custom: Complete control over how search is performed. Provide a full SearchSettings object.

Filters: Apply filters directly inside search_settings.filters. For example:

1 {
2   "filters": { "document_id": { "$eq": "3e157b3a-..." } }
3 }

Supported operators: $eq, $neq, $gt, $gte, $lt, $lte, $like, $ilike, $in, $nin.

Limit: Control how many results you get by specifying limit inside search_settings. For example:

1 {
2   "limit": 20
3 }

Examples:

Using basic mode and no overrides: Just specify search_mode="basic".
Using advanced mode and applying a filter: Specify search_mode="advanced" and include search_settings={"filters": {...}, "limit": 5} to override defaults.
Using custom mode: Provide the entire search_settings to define your search exactly as you want it.

Request

This endpoint expects an object.

querystringRequired

Search query to find relevant documents

search_modeenumOptional

Allowed values: basicadvancedcustom

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.

search_settingsobjectOptional

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

Successful Response

resultsobject

Errors

1 from r2r import R2RClient 2 3 client = R2RClient("http://localhost:7272") 4 # if using auth, do client.login(...) 5 6 # Basic mode, no overrides 7 response = client.retrieval.search( 8 query="Who is Aristotle?", 9 search_mode="basic" 10 ) 11 12 # Advanced mode with overrides 13 response = client.retrieval.search( 14 query="Who is Aristotle?", 15 search_mode="advanced", 16 search_settings={ 17 "filters": {"document_id": {"$eq": "3e157b3a-..."}}, 18 "limit": 5 19 } 20 ) 21 22 # Custom mode with full control 23 response = client.retrieval.search( 24 query="Who is Aristotle?", 25 search_mode="custom", 26 search_settings={ 27 "use_semantic_search": True, 28 "filters": {"category": {"$like": "%philosophy%"}}, 29 "limit": 20, 30 "chunk_settings": {"limit": 20}, 31 "graph_settings": {"enabled": True} 32 } 33 )

1 { 2 "results": { 3 "chunk_search_results": [ 4 { 5 "id": "3f3d47f3-8baf-58eb-8bc2-0171fb1c6e09", 6 "document_id": "3e157b3a-8469-51db-90d9-52e7d896b49b", 7 "collection_ids": [ 8 "collection_ids" 9 ], 10 "score": 0.23943702876567796, 11 "text": "Example text from the document", 12 "metadata": { 13 "associated_query": "What is the capital of France?", 14 "title": "example_document.pdf" 15 }, 16 "owner_id": "2acb499e-8428-543b-bd85-0d9098718220" 17 } 18 ], 19 "graph_search_results": [ 20 { 21 "content": { 22 "name": "Entity Name", 23 "description": "Entity Description", 24 "metadata": { 25 "key": "value" 26 } 27 }, 28 "result_type": "entity", 29 "chunk_ids": [ 30 "c68dc72e-fc23-5452-8f49-d7bd46088a96" 31 ], 32 "metadata": { 33 "associated_query": "What is the capital of France?" 34 } 35 } 36 ] 37 } 38 }

1	{
2	"filters": { "document_id": { "$eq": "3e157b3a-..." } }
3	}

1	from r2r import R2RClient
2
3	client = R2RClient("http://localhost:7272")
4	# if using auth, do client.login(...)
5
6	# Basic mode, no overrides
7	response = client.retrieval.search(
8	query="Who is Aristotle?",
9	search_mode="basic"
10	)
11
12	# Advanced mode with overrides
13	response = client.retrieval.search(
14	query="Who is Aristotle?",
15	search_mode="advanced",
16	search_settings={
17	"filters": {"document_id": {"$eq": "3e157b3a-..."}},
18	"limit": 5
19	}
20	)
21
22	# Custom mode with full control
23	response = client.retrieval.search(
24	query="Who is Aristotle?",
25	search_mode="custom",
26	search_settings={
27	"use_semantic_search": True,
28	"filters": {"category": {"$like": "%philosophy%"}},
29	"limit": 20,
30	"chunk_settings": {"limit": 20},
31	"graph_settings": {"enabled": True}
32	}
33	)

1	{
2	"results": {
3	"chunk_search_results": [
4	{
5	"id": "3f3d47f3-8baf-58eb-8bc2-0171fb1c6e09",
6	"document_id": "3e157b3a-8469-51db-90d9-52e7d896b49b",
7	"collection_ids": [
8	"collection_ids"
9	],
10	"score": 0.23943702876567796,
11	"text": "Example text from the document",
12	"metadata": {
13	"associated_query": "What is the capital of France?",
14	"title": "example_document.pdf"
15	},
16	"owner_id": "2acb499e-8428-543b-bd85-0d9098718220"
17	}
18	],
19	"graph_search_results": [
20	{
21	"content": {
22	"name": "Entity Name",
23	"description": "Entity Description",
24	"metadata": {
25	"key": "value"
26	}
27	},
28	"result_type": "entity",
29	"chunk_ids": [
30	"c68dc72e-fc23-5452-8f49-d7bd46088a96"
31	],
32	"metadata": {
33	"associated_query": "What is the capital of France?"
34	}
35	}
36	]
37	}
38	}