API Overview

The RAG Knowledge Base 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

{workspaceId} 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://{workspaceId}.cn-beijing.maas.aliyuncs.com

The RAG Knowledge Base 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 in 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.

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

​Rate limits

Endpoint

Protocol

Common request headers

Common response format

Pagination

Rate limits