Search

Use existing resource IDs in paths. Set the environment variables shown in each example.

Search knowledge base

POST /knowledge/v1/vector_stores/{vector_store_id}/search

Search ingested text to answer a question or find supporting passages. Native results contain one chunk each, so file_id can repeat; max_num_results counts chunks (1–50, default 10), while the compatible URL groups results by file. Unlike OpenAI vector stores, next_page is always null even when has_more is true. Only completed attachments are searchable. For keyword-only retrieval set ranking_options.hybrid_search to {"embedding_weight":0,"text_weight":1}; omit rewrite_query or set it to false to avoid query rewriting. Unlike OpenAI, ranker auto does not rerank; only default-2024-11-15 requests reranking. Set praxis.explain=true to inspect scores and use returned content[].chunk_id to retrieve a segment.

Parameters

Name	Location and type	Description
vector_store_id	path: string	Required; Knowledge-base ID returned by create or list; use the ID rather than its display name. min characters: 1

Request body

Field	Type	Description
query	string / string[]	required; Nonblank text. Multiple queries are joined with newlines for one search.
filters	object / object / object	optional; Type-strict file attribute filters. At most 20 nested levels below the root.
filters (1).type	"eq" / "ne" / "gt" / "gte" / "lt" / "lte"	required; eq means equal, ne not equal, gt greater, gte greater or equal, lt less, and lte less or equal. The attribute must exist and have the same value type.
filters (1).key	string	required; Literal file-attribute key to compare, including any punctuation in the key.; min characters: 1
filters (1).value	string / number / boolean	required; Scalar value compared without type coercion.
filters (2).type	"in" / "nin"	required; in matches an attribute equal to an array member; nin matches an attribute unequal to every member. Missing attributes never match.
filters (2).key	string	required; Literal file-attribute key to compare, including any punctuation in the key.; min characters: 1
filters (2).value	string / number[]	required; String or number values tested for membership without type coercion.
filters (3).type	"and" / "or"	required; and requires every child filter to match; or requires at least one child filter to match.
filters (3).filters	object / object / object[]	required; Nonempty child-filter list combined using the selected and/or operator.; min items: 1
filters (3).filters[]	object / object / object	Repeat the same filter structure; nesting limit is 20.
max_num_results	integer	optional; Maximum chunks, not distinct files.; min: 1; max: 50; default: 10
rewrite_query	boolean	optional; supported: When true, the store's query_rewrite model first rewrites each query into a concise search query; retrieval uses the rewrite and search_query returns it. Each rewrite is one small model call billed by model usage. If a rewrite fails, times out (5 s) or is empty, that query falls back to the original text and the search still succeeds. Omitted or false makes no model call.
next_page	string	optional; ignored: Unlike OpenAI vector stores, search has no next page; supplying this cursor has no effect. Narrow the query or filters to inspect other matches.
ranking_options	object	optional; Controls result ranking and the minimum score required for inclusion.
ranking_options.ranker	"none" / "auto" / "default-2024-11-15"	optional; Unlike OpenAI, auto does not select a reranker. Only default-2024-11-15 requests reranking; none, auto and omission use the initial ranking. Reranking effect has not been measured separately.
ranking_options.score_threshold	number	optional; Minimum score. Scores are not relevance probabilities; threshold effect has not been measured separately.; min: 0; max: 1; default: 0
ranking_options.hybrid_search	object	optional; Praxis extension. Supply both nonnegative weights with a positive sum. Defaults when omitted: 0.7 / 0.3.; Praxis extension
ranking_options.hybrid_search.embedding_weight	number	required; Relative weight of semantic retrieval; zero disables semantic retrieval.; min: 0; default: 0.7
ranking_options.hybrid_search.text_weight	number	required; Relative weight of keyword retrieval; zero disables keyword retrieval.; min: 0; default: 0.3
praxis	object	optional; Set explain=true to include score and term explanations.; Praxis extension
praxis.explain	boolean	optional; Requests per-result score, rank and term explanations when true.; default: false

Request example

curl -X POST "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}/search" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"query\":\"When will I receive my refund?\",\"max_num_results\":5,\"praxis\":{\"explain\":true}}"

Response

HTTP 200

Field	Type	Description
object	"vector_store.search_results.page"	required; Object discriminator; vector_store.search_results.page identifies a search result page.
search_query	string[]	required; The queries used for retrieval, one per input query; rewritten when rewrite_query is true, otherwise the input as sent.
data	object[]	required; One result per matched chunk; the same file_id can occur more than once.
data[].file_id	string	required; Resource ID.; min characters: 1
data[].filename	string	required; Original source filename for the matched file.
data[].score	number	required; Relevance ranking score for this chunk, clamped to the range 0 to 1; not a probability.; min: 0; max: 1
data[].attributes	object / null	required; Current file attributes used for filtering; null when unset.
data[].content	object[]	required; Matched chunk text and its source coordinates; one chunk per native result.
data[].content[].type	"text"	required; text identifies an extracted text chunk.
data[].content[].text	string	required; Extracted text of the matched chunk, which may overlap neighboring chunks.
data[].content[].chunk_id	string	optional; Resource ID.; min characters: 1
data[].content[].page	integer / null	optional; One-based source page containing the start of this chunk; null when no page mapping is available.
data[].content[].span	integer[]	optional; Start and end offsets in UTF-16 code units.; min items: 2; max items: 2
data[].praxis	object	optional; Native search explanation, included only when praxis.explain is requested.
data[].praxis.explain	object	required; Per-chunk retrieval scores, ranks and matched query terms.
data[].praxis.explain.semantic_score	number / null	required; Semantic retrieval score for this chunk; null when absent from semantic candidates.
data[].praxis.explain.keyword_score	number / null	required; Keyword retrieval score for this chunk; null when absent from keyword candidates.
data[].praxis.explain.rerank_score	number / null	required; Score from the reranking model; null when reranking was not applied.
data[].praxis.explain.semantic_rank	integer / null	required; One-based position in semantic candidates; null when not recalled by that route.
data[].praxis.explain.keyword_rank	integer / null	required; One-based position in keyword candidates; null when not recalled by that route.
data[].praxis.explain.rank_before_rerank	integer	required; One-based fused rank before reranking; without reranking, the position among returned filtered results.; min: 1
data[].praxis.explain.query_terms	string[]	required; Normalized query terms used in the explanation, including adjacent Han-character pairs.
data[].praxis.explain.matched_terms	string[]	required; Query terms found in the normalized chunk text.
has_more	boolean	required; True when filtered chunks exceed max_num_results; next_page remains null.; supported:
next_page	null	required; ignored: Always null; no next search page.

Error codes and objects