Create Knowledge Base and Import

Create a Knowledge Base and import files in a single call (merges CreateIndex and SubmitIndexJob). On success, the response returns the Knowledge Base ID (pipelineId) and the import job ID (ingestionId).

Prerequisites

Get an API key and a workspace ID, and configure authentication first. See API overview and Authentication.

Endpoint

POST /api/v1/indices/rag/index/create_v2

Create a Knowledge Base and import files in a single call (merges CreateIndex and SubmitIndexJob).

Request body

Field	Required	Type	Description
name	Yes	string	Knowledge Base name, 1-20 characters.
description	Yes	string	Knowledge Base description, 1-200 characters.
structureType	Yes	string	Structure type: unstructured or structured.
knowledgeType	No	string	Knowledge Base type, corresponding to the console Knowledge Base type: document (Document Search), table (Data Query), image (Image Q&A), multimedia (Audio and Video Search). The value must match structureType: document, image, and multimedia pair with unstructured, while table pairs with structured. Must be supplied together with knowledgeScene or omitted together. When both are omitted, the system applies defaults based on structureType.
knowledgeScene	No	string	Usage scenario, corresponding to the console usage scenario. The value depends on knowledgeType: document supports basic_document_qa (basic document Q&A), visual_perception_qa (visual understanding, rich text documents), and lite_document_qa (express Q&A); table is fixed to basic_table_qa; image is fixed to image_qa; multimedia is fixed to basic_multimedia_qa. The console only offers scenario options for the Document Search type; other types are filled with fixed values automatically, but you must still pass them explicitly when creating through the API. Must be supplied together with knowledgeType or omitted together. Note: lite_document_qa requires sinkType to be BUILT_IN; visual_perception_qa and image_qa require a multimodal embedding model through multimodalEmbeddingModelName. document also accepts visual_document_qa (rich media answers), but the console no longer exposes this option.
sinkType	Yes	string	Storage type. Default: DEFAULT. BUILT_IN uses the built-in vector storage of the platform. It must be BUILT_IN when knowledgeScene is lite_document_qa (express Q&A).
sourceType	Yes	string	Data source type, for example DATA_CENTER_FILE.
embeddingModelName	No	string	Embedding model name, for example text-embedding-v4.
multimodalEmbeddingModelName	No	string	Multimodal embedding model name, for example qwen3-vl-embedding. Required when knowledgeScene is image_qa (Image Q&A) or visual_perception_qa (visual understanding). If missing or invalid, the request returns invalid multi embedding model.
chunkSize	No	integer	Document chunk size in characters. Recommended: 300-800.
docIds	Yes	array<string>	List of file IDs to import when creating the Knowledge Base. Values come from the fileId returned after registering a file with addFile, or query existing files through listFile. We recommend importing no more than 10,000. The parameter name is docIds — not file_ids or fileIds. However, validation error messages use the name file_ids.
categoryIds	No	array<string>	Files can also be imported by category when creating the Knowledge Base. Specifying category IDs imports all files under the corresponding categories. We recommend importing no more than 10,000.
dataSources	Yes	array<object>	Data source configuration list. Sub-field: sourceType (string, data source type, for example DATA_CENTER_FILE).

Knowledge Base type and usage scenario

knowledgeType and knowledgeScene correspond to Knowledge Base Type and Usage Scenario in step 1 of the console creation wizard. They must be supplied together or omitted together — sending only one returns knowledgeType and knowledgeScene cannot be empty. When both are omitted, the system applies defaults based on structureType.

The console only offers a Usage Scenario choice for Document Search. The other three types have a fixed scenario that the console fills in automatically, but you must still send the pair explicitly when creating a Knowledge Base through the API.

knowledgeType	Console label	structureType	Available knowledgeScene
document	Document Search	unstructured	basic_document_qa (basic document Q&A) visual_perception_qa (visual understanding, rich text documents) lite_document_qa (express Q&A)
table	Data Query	structured	basic_table_qa (fixed)
image	Image Q&A	unstructured	image_qa (fixed)
multimedia	Audio and Video Search	unstructured	basic_multimedia_qa (fixed)

Example request body for Image Q&A:

{
  "name": "image-kb",
  "description": "Image Q&A Knowledge Base",
  "structureType": "unstructured",
  "knowledgeType": "image",
  "knowledgeScene": "image_qa",
  "sinkType": "BUILT_IN",
  "sourceType": "DATA_CENTER_FILE",
  "multimodalEmbeddingModelName": "qwen3-vl-embedding",
  "docIds": ["your-file-id"],
  "dataSources": [{ "sourceType": "DATA_CENTER_FILE" }]
}

Request example

curl -X POST "$BASE_URL/api/v1/indices/rag/index/create_v2" \
  -H "Authorization: Bearer $BAILIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "your-kb-name",
    "description": "your-kb-description",
    "structureType": "unstructured",
    "sinkType": "DEFAULT",
    "sourceType": "DATA_CENTER_FILE",
    "embeddingModelName": "text-embedding-v4",
    "chunkSize": 600,
    "docIds": ["your-file-id-1", "your-file-id-2"],
    "dataSources": [{"sourceType": "DATA_CENTER_FILE"}]
  }'

BASE_URL is https://{workspace_id}.cn-beijing.maas.aliyuncs.com ({workspace_id} is the workspace ID), and BAILIAN_API_KEY is your Alibaba Cloud Model Studio API key.

Response example

Returns 200 on success.

{
  "code": "Success",
  "status_code": 200,
  "success": true,
  "message": "success",
  "data": {
    "pipelineId": "your-kb-id",
    "ingestionId": "your-ingestion-id",
    "status": "PENDING",
    "created_at": 1783657930436,
    "updated_at": 1783657930436
  },
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "SUCCESS"
}

Response fields

Field	Type	Description
code	string	Response code. Success when successful.
status_code	integer	HTTP status code.
success	boolean	Whether the request succeeded. true when successful.
message	string	Response message. success when successful.
request_id	string	Unique request identifier. Provide this ID when troubleshooting.
status	string	Request status. SUCCESS when successful.
data	object	Response data. Sub-fields: pipelineId (string, Knowledge Base ID), ingestionId (string, import job ID), status (string, job status; PENDING after creation), created_at (integer, Knowledge Base creation time as a Unix timestamp in milliseconds), updated_at (integer, last update time as a Unix timestamp in milliseconds).

Error codes

HTTP status code	Error code (code)	Description
400	Index.InvalidParameter	description missing or too long: Required parameter(description length range[1-200]) missing or invalid, please check the request parameters.
400	Index.InvalidParameter	docIds missing or an empty array: Required parameter(file_ids) missing or invalid, please check the request parameters.
400	Index.FileEmptyError	A file ID in docIds does not exist: fetch empty file list from data center.
401	InvalidApiKey	Invalid or missing API key: Invalid API-key provided.