> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hydradb.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Full Recall
> Hybrid semantic + graph + metadata recall over knowledge sources.
## 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:
1. Metadata filtering (deterministic scoping)
2. Hybrid retrieval (semantic + keyword)
3. Graph traversal (entity relationships)
4. 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`](/api-reference/endpoint/recall-preferences) instead.
## Endpoint
* **Auth:** Bearer token
* **Idempotency:** Read-only
* **Async:** No
## Example
```bash cURL theme={"dark"}
curl -X POST 'https://api.hydradb.com/recall/full_recall' \
-H "Authorization: Bearer " \
-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" }
}'
```
```typescript TypeScript SDK theme={"dark"}
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" }
});
```
```python Python SDK theme={"dark"}
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](/essentials/app-sources). |
| `search_forceful_relations` | boolean | No | `true` | In `thinking` mode, augment context with forcefully-related sources. See, [Forceful Relations](/essentials/knowledge#7-forceful-relations) |
| `additional_context` | string | No | – | Extra context to guide retrieval. |
| `metadata_filters` | object | No | – | Filter by metadata. See [Metadata filters](#metadata-filters). |
## Metadata filters
This field matches OpenAPI schema **`RecallSearchRequest.metadata_filters`** (see [`api-reference/openapi.json`](/api-reference/openapi.json)).
* Optional object for **exact-match** metadata scoping; all conditions are **AND**ed.
* **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`.
```json theme={"dark"}
{ "metadata_filters": { "category": "engineering", "department": "R&D" } }
```
```json theme={"dark"}
{ "metadata_filters": { "additional_metadata": { "source": "account_plan" } } }
```
```json theme={"dark"}
// 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
```json theme={"dark"}
{
"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](/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`.
## Related endpoints
* **For user memories instead:** [Recall preferences](/api-reference/endpoint/recall-preferences) – same parameters, targets the memory collection
* **For exact-match search:** [Boolean recall](/api-reference/endpoint/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](/api-reference/error-responses) for the full list.
Read more: [Essentials → Recall](/essentials/recall) · [Essentials → Context Graphs](/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](/essentials/api-results).
## OpenAPI
````yaml POST /recall/full_recall
openapi: 3.1.0
info:
title: HydraDB API
description: REST APIs for the HydraDB retrieval engine
version: 0.0.1
servers:
- url: https://api.hydradb.com
description: Production
x-fern-server-name: hydradb-prod
security: []
paths:
/recall/full_recall:
post:
tags:
- Search
summary: Full recall for knowledge base
operationId: full_recall_recall_full_recall_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RecallSearchRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RetrievalResult'
'400':
description: Bad Request - Invalid input parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ActualErrorResponse'
'401':
description: Unauthorized - Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ActualErrorResponse'
'403':
description: Forbidden - Access denied
content:
application/json:
schema:
$ref: '#/components/schemas/ActualErrorResponse'
'404':
description: Not Found - Resource does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/ActualErrorResponse'
'422':
description: Unprocessable Entity - Validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/ActualErrorResponse'
'429':
description: Too Many Requests - Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ActualErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ActualErrorResponse'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ActualErrorResponse'
security:
- HTTPBearer: []
components:
schemas:
RecallSearchRequest:
properties:
tenant_id:
type: string
title: Tenant Id
description: Unique identifier for the tenant/organization
example: tenant_1234
sub_tenant_id:
anyOf:
- type: string
- type: 'null'
title: Sub Tenant Id
description: >-
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
query:
type: string
title: Query
description: Search terms to find relevant content
example: Which mode does user prefer
max_results:
anyOf:
- type: integer
- type: 'null'
title: Max Results
description: Maximum number of results to return
mode:
$ref: '#/components/schemas/RetrieveMode'
description: Retrieval mode to use ('fast' or 'thinking')
default: fast
alpha:
anyOf:
- type: string
- type: number
title: Alpha
description: Search ranking algorithm parameter (0.0-1.0 or 'auto')
default: 0.8
recency_bias:
type: number
title: Recency Bias
description: >-
Preference for newer content (0.0 = no bias, 1.0 =
strong recency preference)
default: 0
example: 1
graph_context:
type: boolean
title: Graph Context
description: Enable graph context for search results
default: false
example: true
search_forceful_relations:
type: boolean
title: Search Forceful Relations
description: >-
Whether to search for forceful relations in thinking mode to augment
context
default: true
example: true
additional_context:
anyOf:
- type: string
- type: 'null'
title: Additional Context
description: Additional context provided by the user to guide retrieval
metadata_filters:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Metadata Filters
description: >-
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.
examples:
- category: engineering
department: R&D
- additional_metadata:
source: account_plan
type: object
required:
- tenant_id
- query
title: RecallSearchRequest
description: >-
Request body for full recall (sources) and recall preferences
(memories).
RetrievalResult:
properties:
chunks:
items:
$ref: '#/components/schemas/VectorStoreChunk'
type: array
title: Chunks
example: []
sources:
items:
$ref: '#/components/schemas/SourceInfo'
type: array
title: Sources
description: Deduplicated source documents corresponding to the returned chunks
graph_context:
$ref: '#/components/schemas/GraphContext'
additional_context:
additionalProperties:
$ref: '#/components/schemas/VectorStoreChunk'
type: object
title: Additional Context
description: >-
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.
type: object
title: RetrievalResult
description: Result of a hybrid search retrieval operation.
ActualErrorResponse:
properties:
detail:
$ref: '#/components/schemas/ErrorResponse'
type: object
required:
- detail
title: ActualErrorResponse
RetrieveMode:
type: string
enum:
- fast
- thinking
title: RetrieveMode
VectorStoreChunk:
properties:
chunk_uuid:
type: string
title: Chunk Uuid
description: Unique identifier for this content chunk
examples:
- a1b2c3d4-e5f6-7890-1234-567890abcdef
example:
source_id:
type: string
title: Source Id
description: Unique identifier for the source document
examples:
- doc_12345
example:
chunk_content:
type: string
title: Chunk Content
description: The actual text content of this chunk
examples:
- This is a chunk of text from the source document.
example:
source_type:
type: string
title: Source Type
description: Type of the source document (file, webpage, etc.)
default: ''
examples:
- file
example:
source_upload_time:
type: string
title: Source Upload Time
description: When the source document was originally uploaded
default: ''
examples:
- '2023-10-27T10:00:00Z'
example:
source_title:
type: string
title: Source Title
description: Title or name of the source document
default: ''
examples:
- Project Phoenix Overview
example:
source_last_updated_time:
type: string
title: Source Last Updated Time
description: When the source document was last modified
default: ''
examples:
- '2023-10-27T12:30:00Z'
example:
layout:
anyOf:
- type: string
- type: 'null'
title: Layout
description: >-
Layout of the chunk in original document. You will generally
receive a stringified dict with 2 keys, `offsets` and
`page`(optional). Offsets will have
`document_level_start_index` and `page_level_start_index`(optional)
examples:
- '{"offsets": {"document_level_start_index": 1024}, "page": 2}'
relevancy_score:
anyOf:
- type: number
- type: 'null'
title: Relevancy Score
description: >-
Score indicating how relevant this chunk is to your search
query, with higher values indicating better matches
document_metadata:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Document Metadata
description: Metadata extracted from the source document
examples:
- author: John Doe
category: Internal
tenant_metadata:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Tenant Metadata
description: Custom metadata associated with your tenant
examples:
- department: R&D
extra_context_ids:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Extra Context Ids
description: >-
IDs of related chunks providing extra context (from forceful
relations). Only present in thinking mode when sources have forceful
relations.
type: object
required:
- chunk_uuid
- source_id
- chunk_content
title: VectorStoreChunk
SourceInfo:
properties:
id:
type: string
title: Id
description: Unique identifier for the source
example: HydraDoc1234
title:
type: string
title: Title
description: Short human-readable title for the source
default: ''
example:
type:
type: string
title: Type
description: Category of the source (e.g., document, email, ticket)
default: ''
example: <type>
description:
type: string
title: Description
description: Long-form description providing additional context
default: ''
example: <description>
url:
type: string
title: Url
description: Canonical URL or reference link associated with the source
default: ''
example: <url>
timestamp:
type: string
title: Timestamp
description: Creation or last-updated timestamp in ISO-8601 format
default: ''
example: <timestamp>
tenant_metadata:
additionalProperties: true
type: object
title: Tenant Metadata
description: Custom metadata associated with your tenant
document_metadata:
additionalProperties: true
type: object
title: Document Metadata
description: Metadata extracted from the source document
type: object
required:
- id
title: SourceInfo
GraphContext:
properties:
query_paths:
items:
$ref: '#/components/schemas/ScoredPathResponse'
type: array
title: Query Paths
example: []
chunk_relations:
items:
$ref: '#/components/schemas/ScoredPathResponse'
type: array
title: Chunk Relations
example: []
chunk_id_to_group_ids:
additionalProperties:
items:
type: string
type: array
type: object
title: Chunk Id To Group Ids
type: object
title: GraphContext
description: >-
Graph context containing query-based paths and chunk-based relation
paths.
ErrorResponse:
properties:
success:
type: boolean
title: Success
default: false
message:
type: string
minLength: 1
title: Message
default: Error occurred
error_code:
anyOf:
- type: string
- type: 'null'
title: Error Code
type: object
title: ErrorResponse
ScoredPathResponse:
properties:
triplets:
items:
$ref: '#/components/schemas/PathTriplet'
type: array
title: Triplets
example: []
relevancy_score:
type: number
title: Relevancy Score
example: 1
combined_context:
anyOf:
- type: string
- type: 'null'
title: Combined Context
group_id:
anyOf:
- type: string
- type: 'null'
title: Group Id
description: Path group identifier (e.g., 'p_0') for chunk mapping
source_chunk_ids:
anyOf:
- items:
type: string
type: array
uniqueItems: true
- type: 'null'
title: Source Chunk Ids
description: Input chunk IDs whose graph traversal produced this path
type: object
required:
- triplets
- relevancy_score
title: ScoredPathResponse
PathTriplet:
properties:
source:
$ref: '#/components/schemas/Entity'
relation:
$ref: '#/components/schemas/RelationEvidence'
target:
$ref: '#/components/schemas/Entity'
type: object
required:
- source
- relation
- target
title: PathTriplet
Entity:
properties:
name:
type: string
title: Name
description: Normalized entity name
example: <name>
type:
type: string
title: Type
description: PERSON, ORGANIZATION, PROJECT, PRODUCT, ERROR_CODE, etc.
example: <type>
namespace:
type: string
title: Namespace
description: Context category like 'employees', 'projects'
default: default
example: <namespace>
entity_id:
type: string
title: Entity Id
description: Internal unique entity ID from graph database
example: <entity_id>
identifier:
anyOf:
- type: string
- type: 'null'
title: Identifier
description: Unique ID like email, employee_id, URL
type: object
required:
- name
- type
- entity_id
title: Entity
RelationEvidence:
properties:
canonical_predicate:
type: string
title: Canonical Predicate
description: Relationship phrase like 'works for', 'reports to'
example: <canonical_predicate>
raw_predicate:
type: string
title: Raw Predicate
description: Original predicate from text
example: <raw_predicate>
context:
type: string
title: Context
description: >-
Rich contextual description of the relationship with surrounding
information, details about how/why/when, and any relevant
background. Should be comprehensive enough to understand the
relationship without referring back to source.
example: <context>
confidence:
type: number
maximum: 1
minimum: 0
title: Confidence
description: Confidence score
default: 0.8
example: 1
temporal_details:
anyOf:
- type: string
- type: 'null'
title: Temporal Details
description: >-
Temporal timing information extracted from text (e.g., 'last week',
'in 2023', 'yesterday')
timestamp:
type: string
format: date-time
title: Timestamp
description: Timestamp when this relation was introduced
example: <timestamp>
relationship_id:
type: string
title: Relationship Id
description: Unique ID for this relationship from graph database
example: <relationship_id>
chunk_id:
anyOf:
- type: string
- type: 'null'
title: Chunk Id
description: ID of the chunk this relation was extracted from
source_entity_id:
anyOf:
- type: string
- type: 'null'
title: Source Entity Id
description: The entity ID of source node
target_entity_id:
anyOf:
- type: string
- type: 'null'
title: Target Entity Id
description: The entity ID of target node
type: object
required:
- canonical_predicate
- raw_predicate
- context
- relationship_id
title: RelationEvidence
description: Single piece of evidence for a relationship between two entities
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````