Submit Import Job

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/job/create Append documents to an existing Knowledge Base.

Request body

Field	Required	Type	Description
`indexId`	Yes	string	Knowledge Base ID.
`sourceType`	No	string	Data source type. `DATA_CENTER_CATEGORY` imports by category (requires categoryIds); `DATA_CENTER_FILE` imports by file (requires docIds). When this parameter is omitted, all files in the entire data center are imported by default — use with caution.
`categoryIds`	No	`array<string>`	Category ID list. Required when sourceType is `DATA_CENTER_CATEGORY`.
`docIds`	No	`array<string>`	File ID list. Required when sourceType is `DATA_CENTER_FILE`. The parameter name is `docIds` — not `documentIds` or `fileIds`. With a wrong name, the server ignores the parameter and returns `Index.InvalidParameter` (Required parameter(dataSource.fileIds) missing).
`chunkMode`	No	string	Chunk mode, which sets a segmentation strategy only for the files in this import (independent of the global configuration made when the Knowledge Base was created). `h1` to `h5` split by the corresponding heading level (`h1` is the level-1 heading, and so on, down to `h5`); `length` splits by fixed length; `page` splits by page; `regex` splits by a custom regular expression.
`chunkSize`	No	integer	Chunk size in characters. Valid range: 1-6000. Required when chunkMode is `length`. When chunkMode is `h1` to `h5`, a specified value is also taken into account (default 500 when not passed).
`overlapSize`	No	integer	Chunk overlap size in characters. Valid range: 0-1024. Only takes effect when chunkMode is `length`; has no effect when splitting by headings (`h1` to `h5`).
`separator`	No	string	Chunk separator, which only takes effect when chunkMode is `regex`. Required when chunkMode is `regex`, otherwise the request returns `Index.InvalidParameter` (Separator can't be null).
`enableHeaders`	No	boolean	Whether to enable heading extraction. Default: false.

Request example

curl -X POST "$BASE_URL/api/v1/indices/rag/index/job/create" \
  -H "Authorization: Bearer $BAILIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "indexId": "your-kb-id",
    "categoryIds": ["your-category-id"]
  }'

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,
  "data": {
    "updated_at": 1782191904527,
    "created_at": 1782191904527,
    "ingestionId": "your-ingestion-id",
    "pipelineId": "your-kb-id",
    "status": "PENDING"
  },
  "success": true,
  "message": "success",
  "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.
`request_id`	string	Unique request identifier. Provide this ID when troubleshooting.
`success`	boolean	Whether the request succeeded.
`message`	string	Response message. `success` when successful.
`status`	string	Request status: `SUCCESS` or `FAILED`.
`data`	object	Response data. Sub-fields: `pipelineId` (string, Knowledge Base ID), `ingestionId` (string, import job ID), `status` (string, job status; `PENDING` after submission).

Error codes

HTTP status code	Error code (`code`)	Description
400	`Index.InvalidParameter`	Invalid request parameters: `Required parameter missing or invalid.`
401	`InvalidApiKey`	Invalid or missing API key: `Invalid API-key provided.`

​Prerequisites

​Endpoint

​Request body

​Request example

​Response example

​Response fields

​Error codes