Full Recall

Full recall for knowledge base

import requests

url = "https://api.hydradb.com/recall/full_recall"

payload = {
    "tenant_id": "tenant_1234",
    "query": "Which mode does user prefer",
    "sub_tenant_id": "sub_tenant_4567",
    "max_results": 123,
    "mode": "fast",
    "alpha": 0.8,
    "recency_bias": 1,
    "graph_context": True,
    "search_forceful_relations": True,
    "additional_context": "<string>",
    "metadata_filters": {
        "category": "engineering",
        "department": "R&D"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tenant_id: 'tenant_1234',
    query: 'Which mode does user prefer',
    sub_tenant_id: 'sub_tenant_4567',
    max_results: 123,
    mode: 'fast',
    alpha: 0.8,
    recency_bias: 1,
    graph_context: true,
    search_forceful_relations: true,
    additional_context: '<string>',
    metadata_filters: {category: 'engineering', department: 'R&D'}
  })
};

fetch('https://api.hydradb.com/recall/full_recall', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://api.hydradb.com/recall/full_recall \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tenant_id": "tenant_1234",
  "query": "Which mode does user prefer",
  "sub_tenant_id": "sub_tenant_4567",
  "max_results": 123,
  "mode": "fast",
  "alpha": 0.8,
  "recency_bias": 1,
  "graph_context": true,
  "search_forceful_relations": true,
  "additional_context": "<string>",
  "metadata_filters": {
    "category": "engineering",
    "department": "R&D"
  }
}
'

{
  "chunks": [],
  "sources": [
    {
      "id": "HydraDoc1234",
      "title": "<title>",
      "type": "<type>",
      "description": "<description>",
      "url": "<url>",
      "timestamp": "<timestamp>",
      "tenant_metadata": {},
      "document_metadata": {}
    }
  ],
  "graph_context": {
    "query_paths": [],
    "chunk_relations": [],
    "chunk_id_to_group_ids": {}
  },
  "additional_context": {}
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

POST

recall

full_recall

Full recall for knowledge base

import requests

url = "https://api.hydradb.com/recall/full_recall"

payload = {
    "tenant_id": "tenant_1234",
    "query": "Which mode does user prefer",
    "sub_tenant_id": "sub_tenant_4567",
    "max_results": 123,
    "mode": "fast",
    "alpha": 0.8,
    "recency_bias": 1,
    "graph_context": True,
    "search_forceful_relations": True,
    "additional_context": "<string>",
    "metadata_filters": {
        "category": "engineering",
        "department": "R&D"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tenant_id: 'tenant_1234',
    query: 'Which mode does user prefer',
    sub_tenant_id: 'sub_tenant_4567',
    max_results: 123,
    mode: 'fast',
    alpha: 0.8,
    recency_bias: 1,
    graph_context: true,
    search_forceful_relations: true,
    additional_context: '<string>',
    metadata_filters: {category: 'engineering', department: 'R&D'}
  })
};

fetch('https://api.hydradb.com/recall/full_recall', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://api.hydradb.com/recall/full_recall \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tenant_id": "tenant_1234",
  "query": "Which mode does user prefer",
  "sub_tenant_id": "sub_tenant_4567",
  "max_results": 123,
  "mode": "fast",
  "alpha": 0.8,
  "recency_bias": 1,
  "graph_context": true,
  "search_forceful_relations": true,
  "additional_context": "<string>",
  "metadata_filters": {
    "category": "engineering",
    "department": "R&D"
  }
}
'

{
  "chunks": [],
  "sources": [
    {
      "id": "HydraDoc1234",
      "title": "<title>",
      "type": "<type>",
      "description": "<description>",
      "url": "<url>",
      "timestamp": "<timestamp>",
      "tenant_metadata": {},
      "document_metadata": {}
    }
  ],
  "graph_context": {
    "query_paths": [],
    "chunk_relations": [],
    "chunk_id_to_group_ids": {}
  },
  "additional_context": {}
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

When to use it

/recall/full_recall is the primary endpoint for retrieving knowledge (documents, app sources). It runs a multi-stage pipeline that combines:

Metadata filtering (deterministic scoping)
Hybrid retrieval (semantic + keyword)
Graph traversal (entity relationships)
Personalized ranking (user, agent, task)

Use this for document-grounded queries: “What’s in our Q4 contract?”, “Find pricing decisions from the last sprint.” For user-specific memories (preferences, conversation history), use POST /recall/recall_preferences instead.

Endpoint

Auth: Bearer token
Idempotency: Read-only
Async: No

Example

curl -X POST 'https://api.hydradb.com/recall/full_recall' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "my_first_tenant",
    "query": "What are the pricing tiers?",
    "max_results": 5,
    "mode": "thinking",
    "graph_context": true,
    "metadata_filters": { "category": "pricing" }
  }'

const result = await client.recall.fullRecall({
  tenant_id: "my_first_tenant",
  query: "What are the pricing tiers?",
  max_results: 5,
  mode: "thinking",
  graph_context: true,
  metadata_filters: { category: "pricing" }
});

result = client.recall.full_recall(
    tenant_id="my_first_tenant",
    query="What are the pricing tiers?",
    max_results=5,
    mode="thinking",
    graph_context=True,
    metadata_filters={"category": "pricing"},
)

Request parameters

Name	Type	Required	Default	Description
`tenant_id`	string	Yes	–	The tenant to search.
`query`	string	Yes	–	Search terms or natural-language question.
`sub_tenant_id`	string	No	default	Sub-tenant scope.
`max_results`	integer	No	–	Maximum number of chunks to return.
`mode`	enum	No	`fast`	`fast` (single query, lower latency) or `thinking` (multi-query with reranking, higher quality).
`alpha`	number\|string	No	`0.8`	Hybrid weight: `0.0` = keyword, `1.0` = semantic, `"auto"` lets the system pick.
`recency_bias`	number	No	`0.0`	Preference for newer content (`0.0`–`1.0`).
`graph_context`	boolean	No	`false`	If `true`, include entity relationships in the response.
`search_apps`	boolean	No	`false`	If `true`, run the app-aware retrieval lane for app sources. See App Sources.
`search_forceful_relations`	boolean	No	`true`	In `thinking` mode, augment context with forcefully-related sources. See, Forceful Relations
`additional_context`	string	No	–	Extra context to guide retrieval.
`metadata_filters`	object	No	–	Filter by metadata. See Metadata filters.

Metadata filters

This field matches OpenAPI schema RecallSearchRequest.metadata_filters (see api-reference/openapi.json).

Optional object for exact-match metadata scoping; all conditions are ANDed.
Tenant-level: top-level keys (except the reserved nested object below) must match tenant metadata field names declared with enable_match in tenant_metadata_schema. Values use plain equality to stored tenant metadata. These are pre-filtered in the vector store, so they are fast.
Document-level: nest an object under the key additional_metadata (matches the ingestion field name). Keys and values use plain equality to the per-source data you sent as additional_metadata at ingestion. Applied post-retrieval — the engine over-fetches (~3x) to compensate. document_metadata is also accepted as a legacy alias for the nested key.
Not supported in this contract: range operators, regular-expression operators, or Mongo-style operators such as $gte, $lt, $in, or $regex.

{ "metadata_filters": { "category": "engineering", "department": "R&D" } }

{ "metadata_filters": { "additional_metadata": { "source": "account_plan" } } }

// Legacy alias - still accepted, but prefer `additional_metadata`.
{ "metadata_filters": { "document_metadata": { "source": "account_plan" } } }

Modes

Mode	Latency	Quality	When to use
`fast` (default)	Lower	Standard	Real-time chat, autocomplete, simple lookups
`thinking`	Higher	Higher	Complex queries, multi-step reasoning, anything customer-facing where quality matters more than ms

In thinking mode, HydraDB runs multiple sub-queries against the index and reranks results before returning.

Response

{
  "chunks": [
    {
      "chunk_uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "source_id": "doc_12345",
      "chunk_content": "Pricing tiers: $29/month Starter, $79/month Pro, $199/month Enterprise...",
      "source_title": "Q4 Pricing Strategy",
      "source_type": "file",
      "source_upload_time": "2025-09-15T10:00:00Z",
      "relevancy_score": 0.92,
      "additional_metadata": { "author": "Product Team" },
      "metadata": { "category": "pricing" }
    }
  ],
  "sources": [
    {
      "id": "doc_12345",
      "title": "Q4 Pricing Strategy",
      "type": "file",
      "url": "https://...",
      "timestamp": "2025-09-15T10:00:00Z",
      "metadata": { "category": "pricing" },
      "additional_metadata": { "author": "Product Team" }
    }
  ],
  "graph_context": {
    "query_paths": [
      {
        "triplets": [
          {
            "source": { "name": "Pricing Strategy", "type": "PROJECT" },
            "relation": { "canonical_predicate": "OWNED_BY" },
            "target": { "name": "Product Team", "type": "ORGANIZATION" }
          }
        ],
        "relevancy_score": 0.85
      }
    ],
    "chunk_relations": [],
    "chunk_id_to_group_ids": {}
  },
  "additional_context": {}
}

Field	Description
`chunks`	Retrieved content ranked by relevance.
`chunks[].chunk_uuid`	Unique identifier for the chunk.
`chunks[].source_id`	The document this chunk came from.
`chunks[].chunk_content`	The actual text content.
`chunks[].relevancy_score`	Higher means more relevant.
`sources`	Deduplicated source documents corresponding to the returned chunks.
`graph_context`	Entity relationships extracted from your data. Populated only when `graph_context: true` in the request.
`graph_context.query_paths`	Relationship paths relevant to the query.
`graph_context.chunk_relations`	Relationships between returned chunks.
`additional_context`	Map of related chunks from forcefully-connected sources (only in `thinking` mode).

graph_context populates only when:

You set graph_context: true in the request, and
Your ingested content has linked relationships in the graph.

If either condition is missing, the fields return as empty arrays. See Essentials → Context Graphs.

Behavior notes

thinking mode is the personalized path. The default fast mode uses a single retrieval pass. thinking mode adds query expansion, reranking, and forceful-relation context. For B2C apps where personalized recall matters, prefer thinking.

For user memories instead: Recall preferences – same parameters, targets the memory collection
For exact-match search: Boolean recall – full-text search with AND/OR/PHRASE operators

Errors

Common codes: 400 INVALID_PARAMETERS, 404 TENANT_NOT_FOUND, 422 VALIDATION_ERROR, 429 RATE_LIMITED. See Error Responses for the full list. Read more: Essentials → Recall · Essentials → Context Graphs

How to use API Results

Recall responses are chunks of data from knoledge, memory and graph relations in structured JSON. To extract context, we parse the data out of the response strucutre and feed it in prose to an LLM. For further details, explore Essentials → How to Use API Results.

Authorizations

Authorization

string

header

required

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

Body

application/json

Request body for full recall (sources) and recall preferences (memories).

tenant_id

string

required

Unique identifier for the tenant/organization

Example:

"tenant_1234"

query

string

required

Search terms to find relevant content

Example:

"Which mode does user prefer"

sub_tenant_id

string | null

Optional sub-tenant identifier used to organize data within a tenant. If omitted, the default sub-tenant created during tenant setup will be used.

Example:

"sub_tenant_4567"

max_results

integer | null

Maximum number of results to return

mode

enum<string>

default:fast

Retrieval mode to use ('fast' or 'thinking')

Available options:

fast,

thinking

alpha

default:0.8

Search ranking algorithm parameter (0.0-1.0 or 'auto')

recency_bias

number

default:0

Preference for newer content (0.0 = no bias, 1.0 = strong recency preference)

Example:

1

graph_context

boolean

default:false

Enable graph context for search results

Example:

true

search_forceful_relations

boolean

default:true

Whether to search for forceful relations in thinking mode to augment context

Example:

true

additional_context

string | null

Additional context provided by the user to guide retrieval

metadata_filters

Metadata Filters · object | null

Optional object for exact-match metadata scoping. All provided conditions are combined with AND. Top-level keys (except the reserved nested object described below) must match tenant-level metadata field names declared with enable_match in tenant_metadata_schema; each value is compared with plain equality to the stored tenant metadata value for that field. For document-level metadata, supply a nested object under the key "additional_metadata" whose keys and values are compared with plain equality to per-source document metadata. Only equality on scalar-compatible values is part of this contract—do not send range operators, regular-expression operators, or Mongo-style operators such as $gte, $lt, $in, or $regex.

Example:

{
  "category": "engineering",
  "department": "R&D"
}

Response

Successful Response

Result of a hybrid search retrieval operation.

chunks

VectorStoreChunk · object[]

Show child attributes

Example:

[]

sources

SourceInfo · object[]

Deduplicated source documents corresponding to the returned chunks

Show child attributes

graph_context

GraphContext · object

Graph context containing query-based paths and chunk-based relation paths.

Show child attributes

additional_context

Additional Context · object

Map of chunk_uuid to VectorStoreChunk for extra context from forcefully related sources. Use chunk.extra_context_ids to look up chunks: extra_context[id] for id in chunk.extra_context_ids.

Show child attributes

API Documentation

Tenants

Knowledge & Memories

Recall

Managing Data

When to use it

Endpoint

Example

Request parameters

Metadata filters

Modes

Response

Behavior notes

Errors

How to use API Results

Authorizations

Body

Response

​When to use it

​Endpoint

​Example

​Request parameters

​Metadata filters

​Modes

​Response

​Behavior notes

​Related endpoints

​Errors

​How to use API Results

Authorizations

Body

Response

When to use it

Endpoint

Example

Request parameters

Metadata filters

Modes

Response

Behavior notes

Related endpoints

Errors

How to use API Results