Overview

The RAG API lets you manage Knowledge Bases, import documents, run retrievals, and call the Knowledge Q&A service programmatically. Every endpoint is served through the DashScope gateway.

Before calling the API, create an API key.

Endpoint

{workspace_id} is the Workspace ID (e.g., llm-xxxxxxxxxxxx). View or create workspaces on the Workspace Management page. All endpoints share the same base URL:

https://{workspace_id}.cn-beijing.maas.aliyuncs.com

The RAG API has three endpoint groups with different path prefixes:

Group	Path prefix	Purpose
Knowledge Base management	`/api/v1/indices/`	CRUD on Knowledge Bases, document and chunk management, retrieval
Data import	`/api/v1/connector/dash/`	Categories, file upload, connector configuration
Knowledge Q&A	`/api/v2/apps/knowledge/`	Knowledge Q&A service (SSE streaming)

For example, the full URL for the retrieve endpoint is:

https://llm-xxxxxxxxxxxx.cn-beijing.maas.aliyuncs.com/api/v1/indices/rag/index/retrieve

Protocol

All endpoints use HTTPS. HTTP is not supported.
Request and response bodies are JSON encoded as UTF-8.
Knowledge Base management, document/chunk management, retrieval, and data-import endpoints all use POST. A few query endpoints use GET and pass parameters via query string: List Knowledge Bases, List Documents, and Get Import Job Status. Refer to each endpoint page for its actual method and parameter location.

Common request headers

Header	Required	Description
`Authorization`	Yes	`Bearer <API-Key>` — create one on the console API Key page. See Authentication.
`Content-Type`	Yes	`application/json` for POST requests.

Common response format

Every endpoint returns the same JSON envelope. Success:

{
  "code": "Success",
  "status_code": 200,
  "data": { },
  "success": true,
  "message": "success",
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Failure:

{
  "code": "Index.InvalidParameter",
  "status_code": 400,
  "message": "Required parameter(xxx) missing or invalid, please check the request parameters.",
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

When you report a problem, include the request_id so support can find the request quickly. The full error catalog is in Errors.

Pagination

List endpoints support pagination. The HTTP method, parameter names, and where parameters live differ across endpoints — check carefully:

Endpoint	Method	Page parameter	Page size	Where
List Knowledge Bases	GET	`page_number` (starts at 1)	`page_size`	Query string
List Documents	GET	`page_num`	`page_size`	Query string
List Chunks	POST	`page_num`	`page_size`	Request body
List Document Details	POST	`pageNumber` (starts at 1)	`pageSize`	Request body

List Knowledge Bases takes pagination via query string (page_number, page_size — note page_number, not page_num). Sent in the request body, the server ignores them and returns the default page size.

Endpoint catalog

Knowledge Base

Endpoint	Description
Create Knowledge Base and Import	Create a Knowledge Base and import files in a single call.
List Knowledge Bases	Paginate through every Knowledge Base in the current workspace.
Update Knowledge Base	Update the description of a Knowledge Base.
Delete Knowledge Base	Permanently delete a Knowledge Base along with all of its documents and chunks.
Get Knowledge Base Monitoring	Get storage usage and QPS metrics for a Knowledge Base.

Document Management

Endpoint	Description
List Documents	List the documents in a Knowledge Base.
List Document Details	Get detailed document information, including chunk count and parsing status.
Delete Document	Delete a document and all of its chunks from a Knowledge Base.

Chunk Management

Endpoint	Description
Add Chunk	Add a chunk to a specified knowledge base.
List Chunks	Paginate through the chunks in a Knowledge Base.
Update Chunk	Update the content of a single chunk.
Delete Chunks	Delete chunks in batch — up to 10 per call.

Sync Jobs

Endpoint	Description
Submit Import Job	Append documents to an existing Knowledge Base.
Get Job Status	Check the status of a Knowledge Base import job.

Data Import

Endpoint	Description
List Categories	List categories under the current workspace. Filter by type or name.
Create Category	Create a new category under the current workspace.
Delete Category	Delete a category.
List Files	List files under the current workspace. Filter by category, file name, or file ID.
Describe File	Get a file's metadata, including size, MD5, tags, and timestamps.
Delete File	Permanently delete a file.
Batch Update File Tags	Update tags on multiple files in one call. Supports overwrite and append modes.
Request Upload Lease	First step in uploading a file to the data center. Returns an OSS presigned URL and a lease ID.
Register File	Final step of the upload flow — register an OSS-uploaded file with the data center.
Import from OSS	Batch-import files from an authorized Alibaba Cloud OSS bucket into the data center.
Create Connector	Create a new Data Connector that manages where imported files come from.
Get Connector	Get the details of a connector.

Knowledge Retrieval & QA

Endpoint	Description
Knowledge Search	Run a joined semantic search across multiple Knowledge Bases.
Knowledge Chat	SSE-based Streaming Q&A grounded in your Knowledge Bases.

Agent Management

Endpoint	Description
Agent Management Overview	Full lifecycle management APIs for RAG Agent instances.
Create Agent	Create a new RAG Agent with initial status draft.
Update Agent	Update the Agent name, description, or draft config.
Deploy Agent	Publish the beta draft as a new version.
Delete Agent	Soft delete an Agent, marking status as deleted.
List Agents	Paginated query of Agents under the current tenant.
Get Agent	Get full Agent details, supports specifying a version.
Copy Agent	Copy an existing Agent to generate a new draft.

Rate limits

Each endpoint has a request rate limit. Going over returns HTTP 429. See Rate Limits for the full table.

​Endpoint

​Protocol

​Common request headers

​Common response format

​Pagination

​Endpoint catalog

​Knowledge Base

​Document Management

​Chunk Management

​Sync Jobs

​Data Import

​Knowledge Retrieval & QA

​Agent Management

​Rate limits

Endpoint

Protocol

Common request headers

Common response format

Pagination

Endpoint catalog

Knowledge Base

Document Management

Chunk Management

Sync Jobs

Data Import

Knowledge Retrieval & QA

Agent Management

Rate limits