Learn about the Knowledge Studio API's service endpoints, protocol conventions, request formats, and rate limiting rules.
The Knowledge Studio API enables programmatic management of knowledge bases, document ingestion, retrieval operations, and knowledge-based question-answering services. All APIs are served through the DashScope gateway.
The Knowledge Studio API comprises three groups of endpoints, each with a distinct path prefix:
For example, the full URL for the retrieval API is:
All APIs return responses in a consistent JSON structure.
Successful Response:
Failed Response:
When troubleshooting, provide the
List APIs support pagination. However, pagination parameters vary across endpoints in terms of HTTP method, naming, and location. Pay close attention when calling:
Each API enforces request rate limits. Exceeding these limits returns HTTP status
Before calling the API, obtain your API Key.
Service Endpoint
{workspaceId} is the business workspace ID (e.g., llm-xxxxxxxxxxxx). You can view or create it on the console’s Workspace Management page.
All APIs use the same base endpoint:
| API Group | Path Prefix | Description |
|---|---|---|
| Knowledge Base Management | /api/v1/indices/ | CRUD operations for knowledge bases, document management, chunk management, and retrieval |
| Data Ingestion | /api/v1/connector/dash/ | Category management, file uploads, and connector configuration |
| Knowledge Q&A | /api/v2/apps/knowledge/ | Knowledge-based question-answering service (SSE streaming) |
Protocol Conventions
- All APIs are accessible only via HTTPS; HTTP is not supported.
- Request and response bodies are in JSON format, using UTF-8 encoding.
- Most APIs—including knowledge base management, document management, chunk management, retrieval, and data ingestion—use the
POSTmethod. A few read-only query APIs useGET, passing parameters via the query string. These include: listing knowledge bases, listing documents, and checking ingestion task status. Always refer to individual API documentation for the exact HTTP method and parameter location.
Common Request Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <API-Key>. Obtain your key from the console API Key page. See Authentication for details. |
Content-Type | Yes | For POST requests: application/json. |
Common Response Format
All APIs return responses in a consistent JSON structure.
Successful Response:
request_id to help technical support quickly identify the issue. Full error codes are listed in the Error Code Reference.
Pagination
List APIs support pagination. However, pagination parameters vary across endpoints in terms of HTTP method, naming, and location. Pay close attention when calling:
| Applicable API | Method | Page Number Parameter | Items Per Page | Parameter Location |
|---|---|---|---|---|
| List Knowledge Bases | GET | page_number (1-indexed) | page_size | Query String |
| List Documents | GET | page_num | page_size | Query String |
| List Chunks | POST | page_num | page_size | Request Body |
| List File Details | POST | pageNumber (1-indexed) | pageSize | Request Body |
For listing knowledge bases, pagination parameters must be passed in the query string (
page_number, page_size) — note it's page_number, not page_num. If included in the request body, the server will ignore them and return results using default values.Rate Limiting
Each API enforces request rate limits. Exceeding these limits returns HTTP status 429. Full rate-limiting rules are documented in the Rate Limits Guide.