Skip to main content

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.

FieldTypeDescription
querystringSearch 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_idstringRanks 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_idstringRanks 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_similaritynumberMinimum 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_kintegerThe 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_daysnumberHalf-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.
limitintegerMaximum 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_documentsbooleanSet 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_memoriesbooleanSet false to leave the memory store out of this search. The mirror of include_documents, for a caller that wants documents alone.
memory_store_idsstring[]Search memories within these specific memory stores
actor_idstringSearches 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_pathsstring[]Filter results to documents whose file path starts with one of these prefixes
document_idsstring[]Filter results to specific document IDs
tagsobjectFilter 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.
metadataobjectFilter 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.

FieldTypeDescription
source_typedocumentThe type of knowledge source this result comes from
document_idstringPublic ID of the document
document_versionintegerThe 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_idstringPublic ID of the document chunk that matched the query
pageinteger, nullablePage number within the source PDF (1-indexed). Null for plain-text documents.
file_idstringPublic ID of the underlying file
project_idstringPublic ID of the project the document belongs to
pathstringLogical path of the file within the project
filenamestringFilename of the underlying file
sizeintegerFile size in bytes
titlestringDocument title
metadataobjectArbitrary 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.
tagsobjectKey-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.
contentstring, nullableFull text content of the document
scorenumberReciprocal-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.
signalsobjectWhich 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_scorenumberRaw 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_atstring (date-time)Creation timestamp
updated_atstring (date-time)Last updated timestamp

MemoryKnowledgeResult​

A result from a memory; source_type is memory.

FieldTypeDescription
source_typememoryThe type of knowledge source this result comes from
memory_idstringPublic ID of the memory
memory_store_idstringPublic ID of the parent memory store
memory_store_namestringHuman-readable name of the parent memory store
contentstringText content of the memory
tagsobjectThe memory's tags; absent when it has none
scorenumberReciprocal-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.
signalsobjectWhich 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_scorenumberRaw 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_atstring (date-time)Creation timestamp
updated_atstring (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.

Two kinds of source, one query

A query alone searches memories and documents together, memory_store_ids and tags scope which of them take part, and a result says which it came from in source_type. Memories are what an agent learned while working; documents are reference material you supplied. Both rank in the same call.

Examples​

Search the whole corpus​

naturali search-knowledge \
--project-id proj_V1StGXR8Z5jdHi6B \
--query "how long do refunds take" \
--limit 5

Search inside one part of the corpus​

naturali search-knowledge \
--project-id proj_V1StGXR8Z5jdHi6B \
--query "escalation path" \
--document-paths /handbook/support/ \
--min-similarity 0.5

Fetch specific documents without ranking​

naturali search-knowledge \
--project-id proj_V1StGXR8Z5jdHi6B \
--document-ids doc_V1StGXR8Z5jdHi6B