Knowledge
One semantic query across a project's ingested documents — the read side of retrieval.
Overview
Knowledge search is a single call:
POST /v1/projects/{project_id}/knowledge/search
takes a query and returns the chunks that match, ranked, each carrying enough
provenance to cite it — the document, the chunk, the page, the source file's
path.
It is the same retrieval an agent performs internally when its knowledge configuration is set, exposed so you can see what the agent will see. Debugging a bad answer usually starts here: run the user's question through search and look at what came back before touching the prompt.
This module is a verbatim mirror of the runtime: every field, method, status code and error shape is the runtime's own, re-rooted under the project in the path.
See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Knowledge.
Data Model
Request
Every field is optional on its own, but at least one of query,
similar_to_document_id, similar_to_memory_id, document_paths,
document_ids, memory_store_ids or tags must be present — a request with
none of them is a 400. A query names no store, so it reaches
documents and memories alike; the store-specific filters narrow within a store
rather than choosing between them, and include_documents / include_memories
are the switches that choose.
| Field | Type | Description |
|---|---|---|
query | string | Search query text. Runs a vector query and a full-text query over each store and fuses the rankings; the full-text channel matches exact tokens and phrases, the vector channel everything else. |
similar_to_document_id | string | Ranks by this document's stored embedding (the mean of its chunk embeddings) instead of a query: the vector channel alone, no embedding call, and none of the document's own chunks in the results. Not combinable with query or similar_to_memory_id. |
similar_to_memory_id | string | Ranks by this memory's stored embedding instead of a query: the vector channel alone, no embedding call, and the memory itself left out of the results. Not combinable with query or similar_to_document_id. |
min_similarity | number | Minimum raw cosine similarity_score a vector candidate must reach to take part in ranking, applied before fusion. Only applies when query or a similar_to_* source is provided. Lexical candidates are deliberately exempt: a result that literally contains the searched token is the evidence, and dropping it for a low cosine is the failure hybrid search exists to prevent. Not a floor on score, whose fused value encodes rank position rather than similarity. |
rrf_k | integer | The k in the reciprocal rank fusion term 1 / (k + rank), which sets how steeply a result's contribution decays with its position in each ranked list. A smaller value weights the very top of each list more heavily. Defaults to 60. Only applies when query is provided; ignored with a similar_to_* source, which ranks by one channel. |
recency_half_life_days | number | Half-life, in days, of a recency decay applied to memory store results after fusion: a result's score is multiplied by 2 ^ (-age_in_days / recency_half_life_days), where age is measured from its updated_at. Document results are never decayed. 0, the default, disables the blend entirely. Accepts fractions (0.5 is twelve hours). How many ranks a given half-life costs depends on rrf_k. Only applies when query is provided. No value is known to be safe in general: every half-life measured against the reference corpus that lifted recency-sensitive queries also cost relevance-sensitive ones, which is why this ships disabled. Measure against your own corpus before setting it. |
limit | integer | Maximum number of results to return (default 10). A value above 100 is clamped to 100 — the ceiling bounds the vector scan this one request performs, so a larger limit returns everything there is up to that many rows rather than being refused. |
include_documents | boolean | Set false to leave the document store out of this search. A query names no store, so it reaches both; the store-specific filters narrow within a store rather than choosing between them. This is the switch, and a filter naming the other store never overrides it. false for both stores is 400. |
include_memories | boolean | Set false to leave the memory store out of this search. The mirror of include_documents, for a caller that wants documents alone. |
memory_store_ids | string[] | Search memories within these specific memory stores |
actor_id | string | Searches only the memories that belong to this actor; documents are not narrowed. Pin it in a tool's preset_parameters as {{context:actor_id}} so an agent searches the memories of the end user it serves only. |
document_paths | string[] | Filter results to documents whose file path starts with one of these prefixes |
document_ids | string[] | Filter results to specific document IDs |
tags | object | Filter results to documents and memories whose tags contain every one of these key-value pairs (exact, case-sensitive match). Scopes both stores, so passing it alone searches both — as query does. For memories it matches at memory granularity: a memory is returned when its parent memory store's tags match or its own do. |
metadata | object | Filter document results by their metadata bag. A document-store filter: a memory carries no such bag, so passing it alone searches documents, as document_paths does. |
DocumentKnowledgeResult
A result from a document; source_type is document.
| Field | Type | Description |
|---|---|---|
source_type | document | The type of knowledge source this result comes from |
document_id | string | Public ID of the document |
document_version | integer | The document version the chunk belongs to. Cite it to record which text was read; the document's versions keep that text after it changes. |
chunk_id | string | Public ID of the document chunk that matched the query |
page | integer, nullable | Page number within the source PDF (1-indexed). Null for plain-text documents. |
file_id | string | Public ID of the underlying file |
project_id | string | Public ID of the project the document belongs to |
path | string | Logical path of the file within the project |
filename | string | Filename of the underlying file |
size | integer | File size in bytes |
title | string | Document title |
metadata | object | Arbitrary metadata attached to the document, returned verbatim in the casing it was written with at create/update time (e.g. a key written as strapiDocumentId is returned as strapiDocumentId, not strapi_document_id) — it is not converted between snake_case and camelCase like other response fields. |
tags | object | Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with 400 VALIDATION_FAILED, never coerced. Keys are opaque and stored verbatim, so cost_center and costCenter are two different tags. Matched by JSONB containment wherever tags are read: the ?tags= filter, knowledge search, and the IAM iam:ResourceTag/<key> condition. Keys beginning system. are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with 400 RESERVED_TAG_KEY. They are read and filtered like any other tag. The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is 400 VALIDATION_FAILED with meta.limit naming the bound it crossed. system.* keys are the platform's and do not count against the 50. |
content | string, nullable | Full text content of the document |
score | number | Reciprocal-rank-fusion relevance ranking — higher is better. The ordering it produces is the contract; the absolute value is not, is deliberately not rescaled into 0–1, and the formula behind it may change. Results are sorted by it. Nothing filters on it: min_similarity filters similarity_score. Only present when query was provided. Use similarity_score when you need the raw cosine value. |
signals | object | Which retrieval channels ranked this result before fusion, and its 1-based position in that channel's own ordering. A channel that did not return the result is absent, so presence reads as "this channel found it". score says where the result landed; this says how it got there — { "lexical": 1 } is a pure token hit, { "vector": 2, "lexical": 1 } a result both channels found and fusion promoted. Only present when query was provided; a channel that degraded is absent from every result. Diagnostic: nothing filters or sorts on it. |
similarity_score | number | Raw cosine similarity (0–1) between the query and this result. Pinned to that meaning — unlike score, it is never redefined — and populated on every result of a query search, a lexical-only hit included. Absent only when the embedding provider was unreachable and the search answered from the lexical channel alone, where there is no query vector to measure against. |
created_at | string (date-time) | Creation timestamp |
updated_at | string (date-time) | Last updated timestamp |
MemoryKnowledgeResult
A result from a memory; source_type is memory.
| Field | Type | Description |
|---|---|---|
source_type | memory | The type of knowledge source this result comes from |
memory_id | string | Public ID of the memory |
memory_store_id | string | Public ID of the parent memory store |
memory_store_name | string | Human-readable name of the parent memory store |
content | string | Text content of the memory |
tags | object | The memory's tags; absent when it has none |
score | number | Reciprocal-rank-fusion relevance ranking — higher is better. The ordering it produces is the contract; the absolute value is not, is deliberately not rescaled into 0–1, and the formula behind it may change. Results are sorted by it. Nothing filters on it: min_similarity filters similarity_score. Only present when query was provided. Use similarity_score when you need the raw cosine value. |
signals | object | Which retrieval channels ranked this result before fusion, and its 1-based position in that channel's own ordering. A channel that did not return the result is absent, so presence reads as "this channel found it". score says where the result landed; this says how it got there — { "lexical": 1 } is a pure token hit, { "vector": 2, "lexical": 1 } a result both channels found and fusion promoted. Only present when query was provided; a channel that degraded is absent from every result. Diagnostic: nothing filters or sorts on it. |
similarity_score | number | Raw cosine similarity (0–1) between the query and this result. Pinned to that meaning — unlike score, it is never redefined — and populated on every result of a query search, a lexical-only hit included. Absent only when the embedding provider was unreachable and the search answered from the lexical channel alone, where there is no query vector to measure against. |
created_at | string (date-time) | Creation timestamp |
updated_at | string (date-time) | Last updated timestamp |
Read source_type first: the two result shapes share content, score and
similarity_score and agree on nothing else, so it is the discriminator a client
switches on.
Key Concepts
Search, filter, or both
With query, results are ranked semantically. With only document_paths or
document_ids, there is nothing to rank — the call is a fetch, and
similarity_score is absent. Combining them is the useful case: rank
semantically within a subset, which is how a corpus shared by several teams
serves one team's question.
similar_to_document_id or similar_to_memory_id ranks by that record's stored
embedding instead of a query: no embedding call, and the record itself is left
out of the results. It takes neither query nor the other source (400), an
unknown or unsearchable source is 404, and one not yet embedded is
409 SIMILARITY_SOURCE_NOT_EMBEDDED.
document_paths matches on prefix, so /handbook/ reaches everything filed
under it. That is why the path you choose at ingest time is worth choosing
deliberately; Answer from your documents
files its handbook under /handbook/ for exactly this.
Two scores, one contract
score is what the ordering is built on, and it is deliberately not pinned: the
formula behind it may change, so the ranking is the contract, the number is
not. similarity_score is raw cosine similarity and always means exactly
that.
min_similarity filters on similarity_score, not on score: it drops weak
vector candidates before ranking, and leaves lexical ones alone — a result that
literally contains the searched token is the evidence. Start without one, look at
the similarities you actually get back, and set it from those.
Answer from your documents does
that before giving an agent the same corpus.
An agent's knowledge_config spells the
same floor min_score. One filter, two names.
Who may do what
Searching needs any project member. It is a read: nothing is written, and the query is not stored.
Examples
Search the whole corpus
- CLI
- SDK
- curl
naturali search-knowledge \
--project-id proj_V1StGXR8Z5jdHi6B \
--query "how long do refunds take" \
--limit 5
const { data } = await naturali.knowledge.searchKnowledge({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: { query: 'how long do refunds take', limit: 5 },
});
for (const hit of data?.results ?? []) {
console.log(hit.score, hit.path, hit.content?.slice(0, 80));
}
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/knowledge/search \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "query": "how long do refunds take", "limit": 5 }'
Search inside one part of the corpus
- CLI
- SDK
- curl
naturali search-knowledge \
--project-id proj_V1StGXR8Z5jdHi6B \
--query "escalation path" \
--document-paths /handbook/support/ \
--min-similarity 0.5
const { data } = await naturali.knowledge.searchKnowledge({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
query: 'escalation path',
document_paths: ['/handbook/support/'],
min_similarity: 0.5,
},
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/knowledge/search \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"query": "escalation path",
"document_paths": ["/handbook/support/"],
"min_similarity": 0.5
}'
Fetch specific documents without ranking
- CLI
- SDK
- curl
naturali search-knowledge \
--project-id proj_V1StGXR8Z5jdHi6B \
--document-ids doc_V1StGXR8Z5jdHi6B
const { data } = await naturali.knowledge.searchKnowledge({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: { document_ids: ['doc_V1StGXR8Z5jdHi6B'] },
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/knowledge/search \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "document_ids": ["doc_V1StGXR8Z5jdHi6B"] }'