Knowledge Search

Overview

Permissions: This API requires an Alibaba Cloud Model Studio API Key and a workspace. Obtain them on the API Key page and the Workspace Management page in the console.
Call method: HTTP REST, POST + application/json. The Base URL is https://{workspaceId}.cn-beijing.maas.aliyuncs.com, where {workspaceId} is the workspace ID.
Prerequisites: Create and publish a Knowledge Retrieval service on the Knowledge Search service page in the console to obtain the service ID (agent_id). Search strategies (multi-KB weights, Knowledge Base routing, the re-ranking model and its mode, etc.) are pre-configured into the service instance and published; callers only pass the search intent (query / images) and agent_id, and can specify document/tag filter conditions per Knowledge Base via kb_search_configs. If the service is not published, an Agent-not-published error is returned.
Rate limit: 25 QPS per user by default. If throttled, retry later.

Request Syntax

POST /api/v1/indices/knowledge/search HTTP/1.1
Host: {workspaceId}.cn-beijing.maas.aliyuncs.com
Authorization: Bearer <API-Key>
Content-Type: application/json

Request Parameters

Callers only pass the search intent, agent_id, and the optional kb_search_configs filter conditions; all other search strategies are configured in agent_config and are not exposed in the request.

Name	Type	Required	Description	Example
agent_id	string	Yes	Knowledge Search service (agent) instance ID. The server loads the published `agent_config` (with all search strategies) by this ID. Create and publish it on the Knowledge Search page in the console.	aid-xxxxxxxxxxxxxxxx
query	string	Conditional	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.	Recommend a sports jacket for autumn and winter
images	array<string>	Conditional	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.	[]
agent_version	string	No	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.
kb_search_configs	array<object>	No	Knowledge Base filter configuration array. Each element corresponds to one Knowledge Base and can specify document/tag filter conditions. `id` must be a Knowledge Base already bound to the agent; duplicates are not allowed within the same request.
kb_search_configs[].id	string	Yes	Knowledge Base ID (pipeline_id); must be a Knowledge Base already bound to the agent.	kb_product_001
kb_search_configs[].search_filters	array<object>	No	Array of filter conditions, each a JSON object. Supports filtering by doc_id, tags, and custom meta fields. Online search_filters are appended to the end of the offline configured search_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.

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 end of the offline filters array — both apply simultaneously (AND relationship), not replaced. If you need "online conditions only", do not set search_filters in the offline config.

Response Parameters

The top-level response has a unified structure. data contains three parts: total (matched chunk count), nodes (result list), and cost_time (search latency in milliseconds). Use the success field to tell success from failure, and use request_id to correlate logs when troubleshooting.

Name	Type	Description
code	string	Business status code. `Success` on success; otherwise the error code string.
status_code	integer	Semantic status code; 200 on success.
status	string	Status enum: `SUCCESS` on success, `ERROR` on failure.
success	boolean	Whether the request succeeded. Callers should use this field as the primary verdict.
message	string	Status description.
request_id	string	Unique request identifier. Include this ID when reporting an issue.
data.total	integer	Total number of matched chunks.
data.nodes	array<object>	Search result nodes, ordered by relevance. See the table below for the structure.
data.cost_time	integer	Search latency in milliseconds.

data.nodes[] structure

Name	Type	Description
score	number	Relevance score between the chunk and the query, between 0 and 1 — higher means more relevant.
text	string	The assembled chunk text, joined as `field: value` lines; by default includes the doc name, title, and body.
metadata	object	Chunk metadata. Fields vary by Knowledge Base type; see the table below.

data.nodes[].metadata fields

Field	Type	Description
doc_id	string	Document/row ID.
doc_name	string	Document name.
title	string	Chunk title.
hier_title	string	Hierarchical title, with levels separated by `>`.
content	string	Chunk body.
image_url	array<string>	Image URLs contained in the chunk.
audio_url	array<string>	Audio URLs contained in the chunk.
video_url	array<string>	Video URLs contained in the chunk.
_knowledge_type	string	Knowledge type, e.g. `document`, `image`.
_knowledge_scene	string	Knowledge scene, e.g. `basic_document_qa`, `image_qa`.
pipeline_id	string	ID of the owning Knowledge Base.
workspace_id	string	ID of the owning workspace.
_id	string	Chunk ID.
nid	string	Document parsing layout ID.
page_number	array<integer>	Page numbers the chunk belongs to.
doc_url	string	Original document URL.
_score	number	Relevance score.
_rc_v_score	number	Vector match score.
_rc_t_score	number	Keyword match score.
_score_with_weight	number	Weighted relevance score.
_rank_weight	number	Sort weight.
is_displayed_chunk_content	boolean	Whether the chunk content is used for display.

Fields starting with _ are internal scores and may change between versions — do not build business logic on them. Spreadsheet Knowledge Bases also return business fields from your own table (field names vary by table schema; a product catalog might return product_id, product_name, category, etc.), which are not listed above.

Error Codes

On failure, success is false, status is ERROR, status_code is the corresponding 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 code alone; provide request_id when reporting an issue.

HTTP Status	Error Code	Description
400	InvalidParameter	Invalid request parameter. Many different parameter errors return this code, so the error code alone cannot pinpoint the cause — refer to the `message` field; common scenarios are listed below.
401	InvalidApiKey	Authentication failed; the API Key is invalid or missing.

Common parameter error scenarios

Scenario	Error Code	Message
Missing `agent_id`	`InvalidParameter`	`agent_id is required`
Missing `query`	`InvalidParameter`	`query is required`
kb_id not bound to the agent's Knowledge Bases	`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 total 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 size exceeded	`InvalidParameter`	`search_filters[{i}].tags array size must not exceed 1000`

Examples

The following example queries "Recommend a sports jacket for autumn and winter"; replace agent_id with the ID of a published Knowledge Search service.

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"]}
        ]
      }
    ]
  }'

Python

import os
import requests

resp = requests.post(
    "https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/knowledge/search",
    headers={
        "Authorization": f"Bearer {os.getenv('DASHSCOPE_API_KEY')}",
        "Content-Type": "application/json",
    },
    json={
        "agent_id": "aid-xxxxxxxxxxxxxxxx",
        "query": "Recommend a sports jacket for autumn and winter",
        "kb_search_configs": [
            {
                "id": "kb_product_001",
                "search_filters": [
                    {"tags": ["autumn", "sports"]}
                ],
            }
        ],
    },
)
print(resp.json())

​Overview

​Request Syntax

​Request Parameters

​kb_search_configs

​Response Parameters

​Error Codes

​Examples

​cURL

​Python

Overview

Request Syntax

Request Parameters

kb_search_configs

Response Parameters

Error Codes

Examples

cURL

Python