Updated on 2025-08-13 GMT+08:00

Searching Knowledge Bases

Function

Search for top-N most relevant document chunks in a specified knowledge base based on user query.

URI

POST /v1/{project_id}/applications/{application_id}/uni-search/experience/searchtext

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition:

Project ID. For details about how to obtain the project ID, see Obtaining a Project ID.

Constraints:

N/A

Value range:

The value can contain 1 to 64 characters. Only digits, letters, hyphens (-), and underscores (_) are allowed. The value must start with a letter.

Default value:

N/A

application_id

Yes

String

Definition:

Application ID. For details about how to obtain the application ID, see Obtaining an Application ID.

Constraints:

Character string

Value range:

The value can contain 1 to 64 characters. Only digits, letters, hyphens (-), and underscores (_) are allowed. The value must start with a letter.

Default value:

N/A

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

Definition:

Token used for API authentication. For details about how to obtain the token, see Obtaining an IAM User Token.

Constraints:

N/A

Value range:

N/A

Default value:

N/A

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

repo_id

Yes

String

Definition:

Knowledge base ID.

Constraints:

The value can contain only 1 to 64 characters. Only digits, letters, hyphens (-), and underscores (_) are allowed.

Value range:

N/A

Default value:

N/A

extra_repo_ids

No

Array of strings

Definition:

Multi-knowledge base search.

Constraints:

N/A

Value range:

The list cannot exceed 9, and each ID must be unique.

Default value:

N/A

content

Yes

String

Definition:

Search content.

Constraints:

N/A

Value range:

A maximum of 1,000 characters are allowed.

Default value:

N/A

scope

No

String

Definition:

Search scope, which defines the data subsets in the target index. The default value is document library.

Constraints:

N/A

Value range:

  • doc: document knowledge, using the query2doc model.

  • faq: FAQ, using the query2query model.

  • web: web source, from the web search engine.

  • keyword: keyword. When reranking is enabled, the maximum number of pages is the value of top-K in the recall configuration.

  • mix: hybrid search (document search and keyword search, including FAQ. The number of FAQs is the value of FAQ topK in the recall configuration, and the FAQ threshold is the value of FAQ similarity threshold in the recall configuration.)

  • graph: graph chunk. After graph aggregation, the result can be retrieved.

  • graph_keyword: keyword-based graph search

Default value:

doc

filter_string

No

String

Definition:

A query string with syntax. A parser with strict syntax is used to return documents based on the provided query string.

Example: tags: (Shanghai OR capital) AND category:"city"

Example: If segments need to be filtered based on the document ID, use '"fileId": "f6a050ffef5512e80a6dea57e386f194"'.

Constraints:

  1. Boolean operators AND, OR, and NOT (also written as &&, ||, and !) are supported, but note that they do not follow the usual precedence rules. Parentheses should be used as long as multiple operators are used together.

  2. If you use reserved characters in your query string, you will need to escape them using "\". These characters include: + - = && || > <! ( ) { } [ ] ^ " ~ * ? : \ /. For example, \!.

  3. For the query string syntax, see the link.

Value range:

N/A

Default value:

N/A

page_num

Yes

Integer

Definition:

Page number.

Constraints:

N/A

Value range:

The value ranges from 1 to 9999. Note that the sum of page_num and page_size cannot exceed 10000.

Default value:

N/A

page_size

Yes

Integer

Definition:

Page size.

Constraints:

N/A

Value range:

The value ranges from 1 to 9999. Note that the sum of page_num and page_size cannot exceed 10000.

Default value:

N/A

search_threshold

No

Float

Definition:

Search threshold (only for vector search). The value ranges from 0 to 200.

Constraints:

N/A

Value range:

0-200

Default value:

N/A

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

doc_list

Array of ChatReferenceInfo objects

Definition:

Documents.

Value range:

N/A

total

Integer

Definition:

Total number.

Value range:

N/A

Table 5 ChatReferenceInfo

Parameter

Type

Description

file_id

String

Definition:

File ID (or FAQ ID).

Value range:

N/A

chunk_id

String

Definition:

Block ID.

Value range:

N/A

title

String

Definition:

Title.

Value range:

N/A

subtitle

String

Definition:

Document subheading.

Value range:

N/A

content

String

Definition:

Text content.

Value range:

N/A

big_content

String

Definition:

Content context, for example, the original table that is not segmented.

Note:

(1) The search API may have a value.

(2) The Q&A API replaces big_content with content, and this field is cleared.

Value range:

N/A

doc_type

String

Definition:

Document type. The value can be doc or faq.

Value range:

N/A

file_path

String

Definition:

Document archive path.

Value range:

N/A

category

String

Definition:

Document directory, which corresponds to the leaf nodes in the directory tree. This parameter has only one value.

Value range:

N/A

tags

Array of strings

Definition:

Document tag list.

Value range:

N/A

update_date_time

String

Definition:

Update time.

Value range:

N/A

repo_id

String

Definition:

Knowledge base ID.

Value range:

N/A

page_num

Long

Definition:

Page number.

Value range:

N/A

component_num

Long

Definition:

Chunk sequence number.

Value range:

N/A

score

Float

Definition:

ES score.

Value range:

N/A

additional_fields

Map<String,Object>

Definition:

Used to store unknown fields.

Value range:

N/A

elements

Array of strings

Definition:

Data element in HTML.

Value range:

N/A

Constraints:

This parameter is supported only in clusters 25.7.T1 or later.

pdf_coordinate

Object

Definition:

Metadata used for PDF parsing and text locating. Example value:

[

[

202,

687

],

[

1031,

687

]

]

Value range:

N/A

Constraints:

This parameter is supported only in clusters 25.7.T1 or later.

Example Requests

Search for top-N most relevant document chunks in a specified knowledge base based on user query.

/v1/123456/applications/123456/uni-search/experience/searchtext

{
  "repo_id" : "1234abdc",
  "content" : "Write a story that the leading role is sent to the Song Dynasty.",
  "page_num" : 1,
  "page_size" : 10
}

Example Responses

Status code: 200

Search result response body.

{
  "doc_list" : [ {
    "file_id" : "123abc",
    "title" : "AI.doc",
    "content" : "AI",
    "update_date_time" : "134554",
    "doc_type" : "doc",
    "file_path" : "uni-search/v1/AI.doc",
    "score" : 0.9999
  } ],
  "total" : 12
}

Status Codes

Status Code

Description

200

Search result response body.

Error Codes

See Error Codes.