Knowledge Search

POST

/api/v1/indices/knowledge/search

cURL

curl -X POST "https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/knowledge/search" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "aid-xxxxxxxxxxxxxxxx",
    "query": "Recommend a sports jacket for autumn and winter",
    "images": [],
    "kb_search_configs": [
      {
        "id": "kb_product_001",
        "search_filters": [
          {"tags": ["autumn", "sports"]}
        ]
      }
    ]
  }'

{
  "code": "Success",
  "status_code": 200,
  "data": {
    "total": 5,
    "nodes": [
      {
        "score": 0.9201360940933228,
        "metadata": {
          "_rc_v_score": 0.9662528038024902,
          "image_url": [
            "https://example.com/image.jpeg"
          ],
          "_score": 0.9201360940933228,
          "doc_id": "table_xxxxxxxxxxxx_10034682_5780",
          "_score_with_weight": 0.9201360940933228,
          "_rank_weight": 1,
          "doc_name": "Product catalog",
          "pipeline_id": "your_kb_id",
          "_id": "llm-xxxxxxxxxxxx_your_kb_id_table_xxxxxxxxxxxx_10034682_5780",
          "media_url": "https://example.com/image.jpeg",
          "update_date": "2023-11-4 0:03",
          "product_id": "SKU-001",
          "product_name": "Sports jacket (sample)",
          "category": "Apparel",
          "_knowledge_type": "image",
          "_knowledge_scene": "image_qa"
        },
        "text": "media_url: https://example.com/image.jpeg\nupdate_date: 2023-11-4 0:03\nproduct_id: SKU-001\nproduct_name: Sports jacket (sample)\ncategory: Apparel"
      }
    ],
    "cost_time": 2629
  },
  "success": true,
  "message": "success",
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "SUCCESS"
}

Run a unified semantic search across multiple Knowledge Bases and return chunks ordered by relevance. Search strategies are pre-configured into the agent instance and published from the console; callers pass the search intent (query / images) and agent_id, and can specify document/tag filters per Knowledge Base via kb_search_configs.

Publish the Knowledge Search service (agent) in the console first — otherwise the API returns an Agent-not-published error.

Parameter classification

The request surface stays minimal. Parameters fall into two classes by role:

Class	Meaning	Owner	In request?
A · agent strategy	Search strategies that belong to the agent	Locked in `agent_config`, configured and published from the console	No
B · call intent	Inputs known only at call time	Request body	Yes

A-class examples: dense_similarity_top_k, sparse_similarity_top_k, rerank, rerank_top_n, rerank_min_score, hybrid_rerank, enable_kb_router, kb_search_configs[].weight, enable_rewrite, enable_nl2sql — all managed in agent_config and not overridable from the request. B-class examples: query, images, kb_search_configs[].id, kb_search_configs[].search_filters.

kb_search_configs

Use kb_search_configs to specify document/tag filter conditions per Knowledge Base at request time, enabling runtime dynamic filtering. This field is an array; each element corresponds to one Knowledge Base.

kb_search_configs[].id must be a Knowledge Base ID already bound in the agent's offline config — you cannot query unbound Knowledge Bases.
Duplicate id values are not allowed within the same request.
Each kb_search_configs element must include an id field.
Total search_filters byte size must not exceed 80,000 bytes. Unstructured Knowledge Bases only allow tags and meta keys, with array length up to 1,000.
Filterable fields must be declared in index_config.fields when the Knowledge Base is indexed, or filtering has no effect.

Show search_filters syntax details

search_filters is a JSON array where each element is an independent filter object. Three filtering dimensions are supported, each passed as a separate JSON object:

"search_filters": [
  // Filter by document ID (supports multi-value IN)
  { "doc_id": "file_abc_123" },
  { "doc_id": ["file_abc_123", "file_def_456"] },

  // Filter by tags
  { "tags": ["contract", "2024"] },

  // Filter by custom meta field
  { "custom_field": "value" },

  // Advanced: operators (gte / lte / like, etc.)
  { "price": { "gte": 100, "lte": 500 } },
  { "name": { "like": "Zhang%" } },

  // Advanced: nested OR group
  {
    "_operator": "OR",
    "_conditions": [
      { "status": "active" },
      { "priority": { "gte": 5 } }
    ]
  }
]

Merge strategy: When the agent's offline config already has search_filters, the online filters are appended to the offline array — both apply simultaneously (AND relationship), not replaced. If you need "online conditions only", don't set search_filters in the offline config.

Response

Response data contains total (matched chunk count), nodes (result list), and cost_time (latency in ms). Each node has score, text, and metadata; see the parameter table above for field details.

Metadata fields starting with _ are internal scores and may change between versions — don't build business logic on them. Spreadsheet Knowledge Bases also return business fields from your own table (field names vary by table schema).

Error handling

On failure, success is false, status is ERROR, status_code is the semantic code, code is the error code string, message is the description, and request_id is always returned. Always check success rather than relying on the HTTP status alone; provide request_id when reporting an issue.

Scenario	Error code	Message
Missing `agent_id`	`InvalidParameter`	`agent_id is required`
Missing `query`	`InvalidParameter`	`query is required`
kb_id not bound to agent	`InvalidParameter`	`kb not bound to agent: {id}`
Duplicate kb_id	`InvalidParameter`	`duplicate kb id in kb_search_configs: {id}`
Empty kb_id	`InvalidParameter`	`kb_search_configs[{i}].id is required`
search_filters byte size exceeded	`InvalidParameter`	`search_filters total bytes must less than 80000`
Invalid key in unstructured filter	`InvalidParameter`	`search_filters[{i}] contains invalid key '{key}'. Only 'tags' and 'meta' are allowed for unstructured data`
Unstructured tags/meta array exceeded	`InvalidParameter`	`search_filters[{i}].tags array size must not exceed 1000`

Many different parameter errors return the same code — InvalidParameter. The error code alone is not enough to pinpoint the cause; refer to the message field.

Authorizations

string

header

required

DashScope API Key, obtained from the API Key page in the console.

Body

application/json

string

required

Knowledge Search service (agent) instance ID. The server loads the published agent_config (with all A-class search strategies) by this ID. Create and publish it on the Knowledge Search page in the console.

string

default""

Text search intent. At least one of query and images must be provided; pass an empty string for image-only search; required when images is absent, otherwise InvalidParameter is returned.

string[]

default[]

Image search intent. Each element is a publicly accessible image URL. At least one of query and images must be provided; pass both for multimodal search.

string

Agent version. The standard interface exposes only agent_id / agent_version / query / images / kb_search_configs; all other search strategies go through agent_config and are not exposed in the request.

object[]

Knowledge Base filter configuration array. Each element corresponds to one Knowledge Base and can specify document/tag filters. id must be a Knowledge Base already bound to the agent; duplicates are not allowed within the same request.

Show child attributes

string

required

Knowledge Base ID (pipeline_id); must be a Knowledge Base already bound to the agent.

object[]

Array of filter conditions, each a JSON object. Supports filtering by doc_id, tags, and custom meta fields. Online search_filters are appended to offline config filters (AND relationship), not replaced. Total byte size must not exceed 80,000. Unstructured Knowledge Bases only allow tags and meta keys, with array length up to 1,000.

Response

200-application/json

string

Business status code. Success on success; otherwise the error code string.

integer

Semantic status code. 200 on success.

string

Status enum. SUCCESS on success, ERROR on failure.

boolean

Whether the request succeeded. Callers should use this field as the primary verdict.

string

Status description.

string

Unique request identifier. Include this ID when reporting an issue.

object

Show child attributes

integer

Total number of matched chunks.

object[]

Search result nodes, ordered by relevance.

Show child attributes

number

Relevance score between 0 and 1 — higher means more relevant.

string

The chunk text, assembled as field: value lines; by default includes the doc name, title, and body.

object

Chunk metadata. Fields aren't fixed — they vary by Knowledge Base type — and fall into groups: business content (doc_id / doc_name / title / hier_title / content / image_url / audio_url / video_url), Knowledge Base info (_knowledge_type / _knowledge_scene / pipeline_id / workspace_id), chunk info (_id / nid / page_number / doc_url), internal scores (_-prefixed, may change between versions — don't rely on them), and structured business fields (only in spreadsheet Knowledge Bases; field names follow your table schema, e.g. product_id / product_name / category / update_date).

Show child attributes

string

Unique document/row ID, e.g. table_..._10034682_5780.

string

Document name.

string

Chunk title.

string

Hierarchical title — a title path separated by >.

string

Raw chunk body content.

string[]

Image URLs contained in the chunk.

string[]

Audio URLs contained in the chunk.

string[]

Video URLs contained in the chunk.

string

Knowledge type, e.g. document, image.

string

Knowledge scene, e.g. basic_document_qa, image_qa.

string

Knowledge Base ID.

string

Workspace ID.

string

Chunk ID.

string

Document parsing layout ID.

integer[]

Page numbers the chunk belongs to.

string

Original document URL.

number

Relevance score between 0 and 1 (internal, unstable).

number

Vector match score (internal, unstable).

number

Keyword match score (internal, unstable).

number

Weighted relevance score (internal, unstable).

number

Weighted sort weight (internal, unstable).

boolean

Whether this chunk content is used for display.

integer

Search latency in milliseconds.

​Parameter classification

​kb_search_configs

​Response

​Error handling

Authorizations

Body

Response

Parameter classification

kb_search_configs

Response

Error handling