AddDocuments Import documents - Tablestore - Alibaba Cloud Documentation Center

Use the AddDocuments API to import documents into a knowledge base. The system automatically performs parsing, chunking, vectorization, and index building. Uploading the same `ossKey` again overwrites the original document.

Prerequisites

An AgentStorage instance has been created and its status is normal, and you have obtained the instance endpoint and instance name.
An API Key has been created.
Before importing, prepare an OSS Bucket in the same region and grant read access. The AddDocuments API supports API Key authentication; when using the SDK to upload local files, you must also provide a RAM AccessKey or temporary credentials for accessing OSS.

Request parameters

Parameter	Type	Description
`knowledgeBaseName`	string	The name of the knowledge base (required).
`subspace`	string	The name of the subspace, up to 128 UTF-8 bytes. Required when subspace is enabled.
`documents`	list<object>	The list of documents (required). Maximum 10 per request.
`documents[].filePath`	string	Used only by the SDK's upload_documents local upload method, not an AddDocuments HTTP request parameter. Local files must first be uploaded to OSS, then imported via ossKey.
`documents[].ossKey`	string	The OSS file or directory path, length 1--256. Required when calling AddDocuments.
`documents[].metadata`	object	The document metadata, which must be consistent with the metadata schema defined by the knowledge base.
`documents[].inclusionFilters`	list<string>	Inclusion filters, support leading/trailing `` wildcards (e.g., `.pdf`), used for OSS directory scanning.
`documents[].exclusionFilters`	list<string>	Exclusion filters, support leading/trailing `` wildcards (e.g., `draft*`).

Request examples

When using API Key authentication, pass the instance name and API Key through the x-ots-instancename and x-ots-apikey request headers.

### Import a single file from OSS

curl -X POST https://<endpoint>/AddDocuments \
  -H "x-ots-instancename: <instance-name>" \
  -H "x-ots-apikey: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "knowledgeBaseName": "product_docs_kb",
  "subspace": "default",
  "documents": [
    {
      "ossKey": "oss://example-bucket/docs/manual.pdf",
      "metadata": {"author": "张三", "date": "2026-01-22 10:00:59", "score": 80}
    }
  ]
}'

### Batch import from an OSS directory

ossKey specifies a directory path (ending with /); the system recursively scans all files under the directory and filters by file name pattern through inclusionFilters and exclusionFilters.

curl -X POST https://<endpoint>/AddDocuments \
  -H "x-ots-instancename: <instance-name>" \
  -H "x-ots-apikey: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "knowledgeBaseName": "product_docs_kb",
  "subspace": "default",
  "documents": [
    {
      "ossKey": "oss://example-bucket/docs/",
      "inclusionFilters": ["*.pdf", "*.docx"],
      "exclusionFilters": ["*draft*"]
    }
  ]
}'

Response

Field	Type	Description
`documentDetails`	list<object>	The acceptance result of each document. An HTTP 200 with code SUCCESS does not mean all documents succeeded; you must check the status of each item. succeed only indicates the task was accepted, not that indexing is complete; when failed, check the failureReason of that item. For successfully accepted documents, use the returned docId to call GetDocument to query the status (pass the same subspace when subspace is enabled), and wait for completed before retrieving. When failed is returned, handle the failure reason; the polling should set a total timeout.
`documentDetails[].docId`	string	The document ID.
`documentDetails[].ossKey`	string	The OSS path of the document.
`documentDetails[].status`	string	succeed` or `failed
`documentDetails[].failureReason`	string	The failure reason (only when failed).

{
  "code": "SUCCESS",
  "data": {
    "documentDetails": [
      {"docId": "fc6ed97f-28ad-4dc0-9b73-bf4a7d67ab65", "status": "succeed", "ossKey": "oss://example-bucket/docs/manual.pdf"}
    ]
  },
  "message": "succeed"
}