Description

Performs semantic RAG (Retrieval-Augmented Generation) search over the knowledge base and returns matched knowledge entry or Q&A-pair content chunks, suitable for AI scenarios such as intelligent Q&A and customer-service assistance.

Request Specification

HTTP Method: POST + application/json

Request Path: https://${Cloud Domain}/cgi/crm/v2/knowledge/rag/search?thirdTraceId=${Random String}

Request Headers: Refer to Common Parameters

Request Parameters

Parameter	Type	Required	Description
data	Map	Yes	Data
content	String	Yes	Query text
scenes	List[String]	No	List of search scene identifiers; values must be scenes configured in the tenant knowledge base; pass all (case-insensitive) for all scenes
folders	List[String]	No	List of knowledge folder codes to limit the search scope

Request Example

{
  "data": {
    "content": "how to install the device",
    "scenes": ["wechat"],
    "folders": ["16", "17"]
  }
}

Response Parameters

Parameter	Type	Description
traceId	string	Unique request ID
errorDescription	string	Error description
errorMessage	string	Error message
errorCode	Int	Error Codes
data	object	Response data
knowledgeList	Array	Matched results; may be an empty array, and may be absent entirely in degraded scenarios
knowledgeList[].id	String	Knowledge entry or Q&A pair ID
knowledgeList[].objectApiName	String	Matched object type: ServiceKnowledgeObj (knowledge entry) or QuestionAnswerPairObj (Q&A pair)
knowledgeList[].title	String	Title
knowledgeList[].content	String	Matched content chunk; for Q&A pair hits, the first item carries the answer text
knowledgeList[].url	String	In-app link of the matched content; may be null
knowledgeList[].score	Float	Relevance score, may be null, for reference only
knowledgeList[].chunkId	String	Content chunk ID; may be null
knowledgeList[].type	String	Result type; currently always url
knowledgeList[].index	Int	Sequence number; may be null

Response Example

{
  "traceId": "E-O.fktest4234.1000-20260914111000-xxxxxx",
  "errorDescription": "success",
  "errorMessage": "success",
  "errorCode": 0,
  "data": {
    "knowledgeList": [
      {
        "id": "68c1a0f0abcd0001",
        "objectApiName": "ServiceKnowledgeObj",
        "title": "Device Installation Guide",
        "type": "url",
        "content": "Installation steps",
        "score": 0.92,
        "chunkId": "chunk-001",
        "index": 0
      }
    ]
  }
}

Notes

• When both scenes and folders are provided, their scopes are unioned; when neither is provided, the search defaults to all scenes (equivalent to scenes=["all"]).
• When folders is provided, sub-folders are expanded automatically and intersected with the current user's authorized visible scope; content beyond the user's permission is never returned.
• If no valid folder remains after expansion and intersection, the call still succeeds with an empty result (knowledgeList absent or an empty array) instead of falling back to a full-library search.
• If the tenant has not initialized the knowledge base or the current user has no visible scope, the call still succeeds with an empty hit list (knowledgeList is an empty array or absent); no error is returned.
• Fields such as url, score, chunkId and index in the hit items may be null or absent; tolerate missing fields when consuming the response.
• This API performs semantic retrieval and may take longer; it is recommended to set the call timeout to 60 seconds.
• The returned url is an in-app link and is not guaranteed to be accessible from external networks.
• Do not use the message field in the response for logical judgment, as errorMessage may change.