Skip to content

Retrieval

The retrieval system provides configurable search strategies for querying the vector store. It also includes a search history feature for the Search Playground.

Base path: /api/notebooks/{notebook_id}/retrieval

Available Strategies

Strategy ID Name Requires LLM
fusion Fusion (RRF) No
semantic-context Semantic Context No
semantic-rerank Semantic Rerank No
hybrid-rerank Hybrid Rerank No
expanded-hybrid Expanded Hybrid Yes
multi-query Multi-Query Expansion Yes
advanced-multipath Advanced Multipath Yes
agentic-sql Agentic SQL Yes
agent-router Agent Router Yes
agent-harness Agent Harness Yes

POST /api/notebooks/{notebook_id}/retrieval/retrieve

Execute a retrieval strategy and return ranked chunks.

Auth: User

Headers:

Header Value
Authorization Bearer <token>
Content-Type application/json

Body:

{
  "query": "What is the refund policy?",
  "strategy_id": "fusion",
  "top_k": 10,
  "full_text_weight": 1.0,
  "semantic_weight": 1.0,
  "rrf_k": 60,
  "rerank_top_k": 5,
  "file_ids": null
}
Field Type Required Default Description
query string Yes -- Search query (min 1 char)
strategy_id string No "fusion" Strategy to execute
top_k integer No 10 Number of results (1-50)
full_text_weight float No 1.0 FTS weight (0.0-2.0)
semantic_weight float No 1.0 Semantic weight (0.0-2.0)
rrf_k integer No 60 RRF constant (1-200)
rerank_top_k integer No 5 Re-rank top K (1-50)
file_ids array No null Restrict to specific files

Status: 200 OK

{
  "success": true,
  "data": {
    "strategy_id": "fusion",
    "query": "What is the refund policy?",
    "chunks": [
      {
        "rank": 1,
        "content": "Our refund policy allows returns within 30 days...",
        "score": 0.92,
        "metadata": {
          "file_name": "handbook.pdf",
          "file_id": "f1a2b3c4-...",
          "chunk_index": 12,
          "source": "handbook.pdf"
        },
        "file_name": "handbook.pdf",
        "file_id": "f1a2b3c4-...",
        "chunk_index": 12
      }
    ],
    "total_results": 5,
    "execution_time_ms": 450
  }
}
Code Cause
400 Unknown strategy ID, missing query, or missing API key
401 Invalid or missing token
500 Retrieval pipeline failure 
curl -X POST http://localhost:8000/api/notebooks/$NOTEBOOK_ID/retrieval/retrieve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the refund policy?",
    "strategy_id": "fusion",
    "top_k": 10
  }'

import httpx

notebook_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = httpx.post(
    f"http://localhost:8000/api/notebooks/{notebook_id}/retrieval/retrieve",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "query": "What is the refund policy?",
        "strategy_id": "fusion",
        "top_k": 10,
    },
)
result = response.json()["data"]
print(f"Found {result['total_results']} chunks in {result['execution_time_ms']}ms")
for chunk in result["chunks"]:
    print(f"  [{chunk['rank']}] {chunk['content'][:80]}... (score: {chunk['score']})")

GET /api/notebooks/{notebook_id}/retrieval/strategies

List all available retrieval strategies with descriptions.

Auth: User

Headers:

Header Value
Authorization Bearer <token>

Status: 200 OK

{
  "success": true,
  "data": [
    {
      "id": "fusion",
      "name": "Fusion (RRF)",
      "description": "Reciprocal Rank Fusion combining FTS and semantic results",
      "requires_reranking": false,
      "requires_llm": false
    },
    {
      "id": "advanced-multipath",
      "name": "Advanced Multipath",
      "description": "Multi-strategy pipeline with LLM-powered query expansion",
      "requires_reranking": true,
      "requires_llm": true
    }
  ]
}
Code Cause
401 Invalid or missing token 
curl http://localhost:8000/api/notebooks/$NOTEBOOK_ID/retrieval/strategies \
  -H "Authorization: Bearer $TOKEN"

import httpx

notebook_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = httpx.get(
    f"http://localhost:8000/api/notebooks/{notebook_id}/retrieval/strategies",
    headers={"Authorization": f"Bearer {token}"},
)
strategies = response.json()["data"]
for s in strategies:
    llm_tag = " [LLM]" if s["requires_llm"] else ""
    print(f"  {s['id']}: {s['name']}{llm_tag}")

POST /api/notebooks/{notebook_id}/retrieval/history

Save a search execution to history.

Auth: User

Headers:

Header Value
Authorization Bearer <token>
Content-Type application/json

Body:

{
  "mode": "single",
  "strategy_id": "fusion",
  "strategy_name": "Fusion (RRF)",
  "user_query": "What is the refund policy?",
  "execution_params": {"top_k": 10, "rrf_k": 60},
  "result_chunks": [{"rank": 1, "content": "..."}],
  "total_results": 5,
  "execution_time_ms": 450,
  "comparison_group_id": null
}
Field Type Required Default Description
mode string Yes -- "single" or "compare"
strategy_id string Yes -- Strategy used
strategy_name string Yes -- Human-readable strategy name
user_query string Yes -- Search query
execution_params object No {} Strategy parameters used
result_chunks array No [] Result chunks
total_results integer No 0 Number of results
execution_time_ms integer No null Execution time in ms
comparison_group_id string No null Group ID for compare mode

Status: 200 OK

{
  "success": true,
  "data": {
    "id": "hist-1234-...",
    "mode": "single",
    "strategy_id": "fusion",
    "created_at": "2026-02-25T15:00:00Z"
  }
}
Code Cause
401 Invalid or missing token
500 Failed to save history 
curl -X POST http://localhost:8000/api/notebooks/$NOTEBOOK_ID/retrieval/history \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "single",
    "strategy_id": "fusion",
    "strategy_name": "Fusion (RRF)",
    "user_query": "What is the refund policy?",
    "total_results": 5,
    "execution_time_ms": 450
  }'

import httpx

response = httpx.post(
    f"http://localhost:8000/api/notebooks/{notebook_id}/retrieval/history",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "mode": "single",
        "strategy_id": "fusion",
        "strategy_name": "Fusion (RRF)",
        "user_query": "What is the refund policy?",
        "total_results": 5,
    },
)
print(response.json()["data"])

GET /api/notebooks/{notebook_id}/retrieval/history

List search history, split into single executions and compare groups.

Auth: User

Headers:

Header Value
Authorization Bearer <token>

Status: 200 OK

{
  "success": true,
  "data": {
    "single": [
      {
        "id": "hist-1234-...",
        "mode": "single",
        "strategy_id": "fusion",
        "strategy_name": "Fusion (RRF)",
        "user_query": "What is the refund policy?",
        "total_results": 5,
        "execution_time_ms": 450,
        "created_at": "2026-02-25T15:00:00Z"
      }
    ],
    "compare": [
      {
        "comparison_group_id": "cmp-5678-...",
        "user_query": "What is the refund policy?",
        "created_at": "2026-02-25T15:05:00Z",
        "strategies": [
          {"strategy_id": "fusion", "strategy_name": "Fusion"},
          {"strategy_id": "semantic-context", "strategy_name": "Semantic Context"}
        ]
      }
    ]
  }
}
Code Cause
401 Invalid or missing token
500 Failed to list history 
curl http://localhost:8000/api/notebooks/$NOTEBOOK_ID/retrieval/history \
  -H "Authorization: Bearer $TOKEN"

import httpx

response = httpx.get(
    f"http://localhost:8000/api/notebooks/{notebook_id}/retrieval/history",
    headers={"Authorization": f"Bearer {token}"},
)
history = response.json()["data"]
print(f"Single: {len(history['single'])}, Compare: {len(history['compare'])}")

GET /api/notebooks/{notebook_id}/retrieval/history/compare/{group_id}

Get all entries in a compare group with full chunks.

Auth: User

Headers:

Header Value
Authorization Bearer <token>

Status: 200 OK

{
  "success": true,
  "data": [
    {
      "id": "hist-1234-...",
      "strategy_id": "fusion",
      "result_chunks": [{"rank": 1, "content": "..."}],
      "total_results": 5
    },
    {
      "id": "hist-5678-...",
      "strategy_id": "semantic-context",
      "result_chunks": [{"rank": 1, "content": "..."}],
      "total_results": 3
    }
  ]
}
Code Cause
401 Invalid or missing token
404 Comparison group not found
500 Failed to get comparison group 
curl http://localhost:8000/api/notebooks/$NOTEBOOK_ID/retrieval/history/compare/$GROUP_ID \
  -H "Authorization: Bearer $TOKEN"

import httpx

response = httpx.get(
    f"http://localhost:8000/api/notebooks/{notebook_id}/retrieval/history/compare/{group_id}",
    headers={"Authorization": f"Bearer {token}"},
)
entries = response.json()["data"]
for entry in entries:
    print(f"  {entry['strategy_id']}: {entry['total_results']} results")

GET /api/notebooks/{notebook_id}/retrieval/history/{entry_id}

Get full detail of a single history entry, including result chunks.

Auth: User

Headers:

Header Value
Authorization Bearer <token>

Status: 200 OK

{
  "success": true,
  "data": {
    "id": "hist-1234-...",
    "notebook_id": "a1b2c3d4-...",
    "mode": "single",
    "strategy_id": "fusion",
    "strategy_name": "Fusion (RRF)",
    "user_query": "What is the refund policy?",
    "execution_params": {"top_k": 10},
    "result_chunks": [{"rank": 1, "content": "..."}],
    "total_results": 5,
    "execution_time_ms": 450,
    "created_at": "2026-02-25T15:00:00Z"
  }
}
Code Cause
401 Invalid or missing token
404 History entry not found
500 Failed to get history detail 
curl http://localhost:8000/api/notebooks/$NOTEBOOK_ID/retrieval/history/$ENTRY_ID \
  -H "Authorization: Bearer $TOKEN"

import httpx

response = httpx.get(
    f"http://localhost:8000/api/notebooks/{notebook_id}/retrieval/history/{entry_id}",
    headers={"Authorization": f"Bearer {token}"},
)
print(response.json()["data"])

DELETE /api/notebooks/{notebook_id}/retrieval/history/compare/{group_id}

Delete all entries in a compare group.

Auth: User

Headers:

Header Value
Authorization Bearer <token>

Status: 200 OK

{
  "success": true,
  "data": {
    "deleted": 3
  }
}
Code Cause
401 Invalid or missing token
500 Failed to delete comparison group 
curl -X DELETE http://localhost:8000/api/notebooks/$NOTEBOOK_ID/retrieval/history/compare/$GROUP_ID \
  -H "Authorization: Bearer $TOKEN"

import httpx

response = httpx.delete(
    f"http://localhost:8000/api/notebooks/{notebook_id}/retrieval/history/compare/{group_id}",
    headers={"Authorization": f"Bearer {token}"},
)
print(f"Deleted: {response.json()['data']['deleted']}")

DELETE /api/notebooks/{notebook_id}/retrieval/history/{entry_id}

Delete a single history entry.

Auth: User

Headers:

Header Value
Authorization Bearer <token>

Status: 200 OK

{
  "success": true,
  "data": {
    "deleted": true
  }
}
Code Cause
401 Invalid or missing token
404 History entry not found
500 Failed to delete history entry 
curl -X DELETE http://localhost:8000/api/notebooks/$NOTEBOOK_ID/retrieval/history/$ENTRY_ID \
  -H "Authorization: Bearer $TOKEN"

import httpx

response = httpx.delete(
    f"http://localhost:8000/api/notebooks/{notebook_id}/retrieval/history/{entry_id}",
    headers={"Authorization": f"Bearer {token}"},
)
print(response.json()["data"])

DELETE /api/notebooks/{notebook_id}/retrieval/history

Clear all search history for a notebook.

Auth: User

Headers:

Header Value
Authorization Bearer <token>

Status: 200 OK

{
  "success": true,
  "data": {
    "deleted": 15
  }
}
Code Cause
401 Invalid or missing token
500 Failed to clear history 
curl -X DELETE http://localhost:8000/api/notebooks/$NOTEBOOK_ID/retrieval/history \
  -H "Authorization: Bearer $TOKEN"

import httpx

response = httpx.delete(
    f"http://localhost:8000/api/notebooks/{notebook_id}/retrieval/history",
    headers={"Authorization": f"Bearer {token}"},
)
print(f"Deleted: {response.json()['data']['deleted']} entries")