> ## Documentation Index
> Fetch the complete documentation index at: https://developer.duplik.cn/llms.txt
> Use this file to discover all available pages before exploring further.

> Semantic retrieval over knowledge bases, with entity_names metadata pre-filtering

# Retrieve Knowledge



## OpenAPI

````yaml post /v1/tools/retrieval_knowledge
openapi: 3.1.0
info:
  title: spectra-server
  description: The API for Spectra Backend.
  version: 0.1.0
servers:
  - url: https://api-spectra.duplik.cn
security: []
paths:
  /v1/tools/retrieval_knowledge:
    post:
      tags:
        - Tools
      summary: Retrieve Knowledge
      description: >-
        Semantic retrieval over one or more knowledge bases. This is the read
        side of the tagging you do at upload time: pass the same `"key:value"`
        values in `entity_names` that you wrote into a document's
        `document_metadata`, and the matching documents are resolved from the
        tag table first and used as a hard filter for the vector and keyword
        search.


        `entity_names` matching is by prefix (`"model:SY5"` hits
        `"model:SY500"`) and multiple values are ANDed, so every value must
        match. At least one value has to contain a colon for the filter to kick
        in — a list of plain words is ignored and you get ordinary semantic
        search. When the filter matches nothing, the result is empty rather than
        falling back to unfiltered search. Note that the tag lookup returns at
        most 100 documents, so tags need to be selective enough: `model:SY500`
        is a good tag, `source:erp` spanning thousands of documents is not.


        `knowledge_ids` are resolved within the API key's organization. If none
        of them resolve — wrong ID, deleted knowledge base, different
        organization — the response body is `null` rather than an empty result,
        so check for that before reading fields.


        `documents` lists the documents the hits came from; their `metadata`
        only ever carries `entity_names`, and is omitted entirely when
        `return_metadata` is false. `document_contents` is the retrieved
        passages serialised as JSON, shortened by a model when it would exceed
        the context budget, so treat it as text to feed a model rather than a
        stable structure to parse.
      operationId: execute_retrieval_knowledge_tool_v1_tools_retrieval_knowledge_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdvancedKnowledgeToolParam'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedKnowledgeToolResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
      security:
        - HTTPBearer: []
components:
  schemas:
    AdvancedKnowledgeToolParam:
      properties:
        query:
          anyOf:
            - type: string
            - type: 'null'
          title: Query
          description: The question to search the knowledge bases with
        entity_names:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Entity Names
          description: >-
            Metadata tags to pre-filter on, written as "key:value" (for example
            ["model:SY500"]). Prefix matched and ANDed
        enable_toc_enhance:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Enable Toc Enhance
          default: false
          description: Enable table-of-contents enhanced retrieval
        knowledge_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Knowledge Ids
          description: >-
            Knowledge bases to search, resolved within the API key's
            organization
        pre_filter_document_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Pre Filter Document Ids
          description: >-
            Restrict the search to these documents; intersected with the
            entity_names filter when both are used
        return_metadata:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Return Metadata
          default: true
          description: Include each document's entity_names in the response
      type: object
      title: AdvancedKnowledgeToolParam
    AdvancedKnowledgeToolResponse:
      properties:
        documents:
          anyOf:
            - items:
                $ref: '#/components/schemas/DocumentInfo'
              type: array
            - type: 'null'
          title: Documents
          description: Documents the retrieved passages came from
        document_contents:
          anyOf:
            - type: string
            - type: 'null'
          title: Document Contents
          description: >-
            Retrieved passages serialised as JSON, shortened by a model when
            over the context budget
      type: object
      title: AdvancedKnowledgeToolResponse
    ErrorResponse:
      properties:
        code:
          type: integer
          title: Code
        message:
          type: string
          title: Message
      type: object
      required:
        - code
        - message
      title: ErrorResponse
    DocumentInfo:
      properties:
        document_id:
          type: string
          title: Document Id
        metadata:
          anyOf:
            - type: object
            - type: 'null'
          title: Metadata
          description: Only carries entity_names, and is null when the document has no tags
      type: object
      required:
        - document_id
      title: DocumentInfo
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````