> ## Documentation Index > Fetch the complete documentation index at: https://docs.evermind.ai/llms.txt > Use this file to discover all available pages before exploring further. # Search a knowledge base > Search within one knowledge base, by keyword, vector or hybrid retrieval. The unit of retrieval is the topic, not the document: each hit carries its parent document's title and summary, so rendering a result needs no second call. Topic bodies are omitted by default — ask for `content` in `include` to inline them, or drill down with GET .../documents/{doc_id}/topics/{topic_id}. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v2/knowledge_bases/{kb_id}/search openapi: 3.1.0 info: title: EverOS Cloud Memory API version: 2.0.0 license: name: Apache-2.0 identifier: Apache-2.0 contact: name: EverMind AI email: service@evermind.ai url: https://github.com/EverMind-AI/everos-cloud-sdk-python description: >- Official Python client for the EverOS Cloud Memory API. Add, search, retrieve, and manage long-term memory for your AI applications over a typed interface (pydantic v2, with full type hints). Install and usage guides: https://github.com/EverMind-AI/everos-cloud-sdk-python servers: - url: https://api.evermind.ai description: Production security: - BearerAuth: [] paths: /api/v2/knowledge_bases/{kb_id}/search: post: tags: - Knowledge summary: Search a knowledge base description: >- Search within one knowledge base, by keyword, vector or hybrid retrieval. The unit of retrieval is the topic, not the document: each hit carries its parent document's title and summary, so rendering a result needs no second call. Topic bodies are omitted by default — ask for `content` in `include` to inline them, or drill down with GET .../documents/{doc_id}/topics/{topic_id}. operationId: searchKnowledge parameters: - name: kb_id in: path required: true schema: type: string title: Kb Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchBody' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SuccessEnvelope_KbSearchData_' '401': description: Missing or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/GatewayError' '403': description: >- Authenticated but not permitted — either rejected by the auth service, or the account's memory API version does not match the interface version implied by the path (a v1 account calling an /api/v2 route). content: application/json: schema: $ref: '#/components/schemas/GatewayError' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit or quota exceeded. content: application/json: schema: $ref: '#/components/schemas/GatewayError' '503': description: >- The gateway could not reach the authentication service. Transient — retry with backoff. content: application/json: schema: $ref: '#/components/schemas/GatewayError' components: schemas: SearchBody: properties: query: anyOf: - type: string maxLength: 2000 - type: 'null' title: Query description: >- What to retrieve against within this knowledge base, up to 2000 characters. Optional: omit it and pass `filters.tag_ids` to page through tagged topics instead, which skips retrieval entirely — every hit then scores 0.0. method: type: string enum: - keyword - vector - hybrid title: Method default: hybrid description: >- Retrieval strategy: "keyword" (lexical), "vector" (embedding similarity) or "hybrid" (default, both). page: type: integer minimum: 1 title: Page description: Filter-only page number; query search supports page 1 only default: 1 top_k: type: integer maximum: 100 minimum: 1 title: Top K default: 10 description: >- Maximum number of topics to return, 1 to 100 (default 10). On a query search the server also bounds the result by its rerank pool — 50 candidates by default — so asking for more than that returns what the pool held. On a filter-only request (tags without a query) it is the page size instead, and `page` walks the rest. score_threshold: anyOf: - type: number - type: 'null' title: Score Threshold description: >- Drop hits whose final score is below this. Mind what that score is: it is normalized within each response (see `score` on a hit), so this cuts a RELATIVE position in one result set, not an absolute relevance bar — a response whose hits are all poor still has a top hit near the top of the range. Two traps follow from the edge values: a filter-only request scores every hit 0.0, so any positive threshold empties it, and a failed rerank batch scores -100.0, which every positive threshold silently removes. Tune it against real results rather than from a BM25 or cosine intuition. include: items: type: string type: array title: Include description: e.g. ['content'] default: [] boost_tag_ids: items: type: string maxLength: 128 minLength: 1 description: Opaque semantic tag id type: array maxItems: 100 title: Boost Tag Ids description: >- Reweight, do not filter: topics carrying these tags are pushed up, and topics without them still come back. Use `filters.tag_ids` when the intent is to exclude everything else. default: [] filters: $ref: '#/components/schemas/SearchFilters' description: Optional filters narrowing what is searched. additionalProperties: false type: object title: SearchBody description: POST body (kb_id rides the path, not the body). SuccessEnvelope_KbSearchData_: properties: request_id: type: string title: Request Id description: Request trace id (peer to data) data: $ref: '#/components/schemas/KbSearchData' description: Endpoint-defined business result type: object required: - request_id - data title: SuccessEnvelope[KbSearchData] GatewayError: type: object additionalProperties: true description: >- Gateway error body. NOTE: shape is not yet uniform across auth/quota/ rate-limit paths — treat fields as best-effort. Commonly includes a `code`/`message` (flat) or an `error` object/string with a `message`. title: GatewayError HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail description: One entry per field that failed validation. type: object title: HTTPValidationError SearchFilters: properties: category_id: anyOf: - type: string - type: 'null' title: Category Id description: >- Bias retrieval toward one category. This is a soft filter on recall, not a hard restriction — hits from other categories can still surface. tag_ids: items: type: string maxLength: 128 minLength: 1 description: Opaque semantic tag id type: array maxItems: 100 title: Tag Ids description: >- Hard filter that does not affect scoring: only topics carrying EVERY one of these tag ids are eligible. Use `boost_tag_ids` when the intent is to reweight rather than exclude. default: [] additionalProperties: false type: object title: SearchFilters description: >- Optional hard filters. ``category_id`` is a soft filter on recall (design 01 §3.9). KbSearchData: properties: hits: items: $ref: '#/components/schemas/SearchHit' type: array title: Hits description: Matching topics, most relevant first. total: type: integer title: Total description: How many topics matched. took_ms: type: number title: Took Ms description: How long the search took, in milliseconds. type: object required: - hits - total - took_ms title: KbSearchData description: >- Knowledge search response payload. Prefixed ``Kb`` to stay distinct from ``memory_api.SearchData`` — two same-named models under ``SuccessEnvelope[...]`` collide to a non-deterministic OpenAPI component name (see openapi-sync / check-openapi). ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location description: Path to the offending field, from the body root. msg: type: string title: Message description: What is wrong with it. type: type: string title: Error Type description: Machine-readable validation-error kind. type: object required: - loc - msg - type title: ValidationError SearchHit: properties: object: type: string enum: - topic - document title: Object description: >- What this hit is. Always "topic" today — the unit of knowledge retrieval. id: type: string title: Id description: The topic's id; fetch its full body with GET .../topics/{topic_id}. doc_id: type: string title: Doc Id description: The document the topic belongs to. kb_id: type: string title: Kb Id description: The knowledge base searched. category_id: type: string title: Category Id default: '' description: The category that document is filed under; empty when uncategorized. category_name: anyOf: - type: string - type: 'null' title: Category Name description: That category's display name, resolved for you. name: type: string title: Name description: The topic's title. depth: type: integer title: Depth default: 0 description: The topic's depth in the document tree. summary: anyOf: - type: string - type: 'null' title: Summary description: >- Retrieval-oriented summary of the topic — enough to render a result row. content: anyOf: - type: string - type: 'null' title: Content description: >- The topic's full body, present only when `content` was asked for in `include`. score: type: number title: Score description: >- Relevance of this topic to the query, and NOT a raw keyword or vector score: candidates from every method are reranked by a cross-encoder, min-max normalized WITHIN THIS RESPONSE, then given a category boost (up to 0.1) and, when `boost_tag_ids` was passed, a tag-coverage boost (up to 0.3). So it lands in roughly 0.0–1.4, the best hit of any response sits near the top of that range by construction, and scores compare inside one response but not across responses or queries. Three edge values to expect: every hit comes back at 0.5 when the reranker cannot separate the pool, every hit is 0.0 on a filter-only request (tags without a query, which never runs relevance at all), and a hit carries a synthetic -100.0 when its rerank batch failed — that is a fail-soft marker, not a relevance judgement. retrieval_method: type: string enum: - keyword - vector - hybrid - filter title: Retrieval Method description: >- The retrieval strategy this search ran with, so every hit in one response carries the same value and a stored or traced response is self-describing. It echoes the request's `method`, except on a filter-only request (tags without a query), which reports "filter" because no retrieval ran. It is deliberately NOT per-hit provenance: in a hybrid search the two lanes are fused, and hits recalled by only one of them still report "hybrid". source: anyOf: - type: string - type: 'null' title: Source description: The parent document's source name. document: anyOf: - $ref: '#/components/schemas/DocumentContext' - type: 'null' description: >- The parent document's context, rolled up so a result needs no second call. tags: items: $ref: '#/components/schemas/TagRef' type: array title: Tags description: The semantic tags materialized on this topic. updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At description: When the topic last changed. type: object required: - object - id - doc_id - kb_id - name - score - retrieval_method - tags title: SearchHit description: A topic hit from recall or a document hit from filter-only search. DocumentContext: properties: doc_id: type: string title: Doc Id description: The parent document's id. title: type: string title: Title default: '' description: Its title. summary: anyOf: - type: string - type: 'null' title: Summary description: Its document-level summary. type: object required: - doc_id title: DocumentContext description: The parent document a hit belongs to (rolled up for display). TagRef: properties: id: type: string title: Id description: Opaque semantic tag id. name: anyOf: - type: string - type: 'null' title: Name description: >- The tag's display name when one is resolved; null when only the id is known. additionalProperties: false type: object required: - id title: TagRef description: Opaque semantic tag reference; its containing topic conveys ownership. securitySchemes: BearerAuth: type: http scheme: bearer description: 'API key issued by EverOS, sent as `Authorization: Bearer `.' ````