Skip to main content

Knowledge Base API Guide

The knowledge base provides open API interfaces for integrating with existing business systems, enabling automated operations and complex retrieval requirements.

This document applies only to document search knowledge bases.
Knowledge base features are only available in the China (Beijing) region.

Prerequisites

Sub-accounts (not primary accounts) need the AliyunBailianDataFullAccess policy and must join a business space before they can operate knowledge bases via the Alibaba Cloud API.
Sub-accounts can only operate knowledge bases in business spaces they have joined; primary accounts can operate across all business spaces.
  1. Install the latest Alibaba Cloud Bailian SDK. If the SDK does not meet your needs, you can send signed HTTP requests to the knowledge base API.
  2. Obtain an AccessKey, AccessKey Secret, and business space ID, and configure them as environment variables: 
export ALIBABA_CLOUD_ACCESS_KEY_ID='your-access-key-id'
export ALIBABA_CLOUD_ACCESS_KEY_SECRET='your-access-key-secret'
export WORKSPACE_ID='your-workspace-id'
  1. Prepare a sample document, Alibaba Cloud Bailian phone product introduction.docx.

API Overview

All knowledge base APIs are REST-style, served through the bailian gateway, using AK/SK ACS3-V3 signing.
  • Server: https://bailian.{regionId}.aliyuncs.com
  • Path style: REST resource paths with workspace prefix, e.g. GET /{workspaceId}/promptTemplates
  • Authentication: ACS3-HMAC-SHA256 (V3) signing. Not Bearer token. See Flow Agent API Authentication for details.
  • RAM policies: AliyunBailianFullAccess / AliyunBailianReadOnlyAccess

Resource Summary

ResourceEndpoints
Knowledge BasesCreate, List, Get, Update, Delete
CategoriesCreate, List, Get, Update, Delete
FilesAdd, List, Get, Delete, Get Content
ChunksList, Add, Update, Delete
SessionsCreate, List, Get, Delete

Quick Start: Create a Knowledge Base

curl -X POST 'https://bailian.cn-beijing.aliyuncs.com/{workspaceId}/datacenter/indices' \
  -H 'Authorization: ACS3-HMAC-SHA256 Credential=AK,SignedHeaders=host;x-acs-content-sha256;x-acs-date;x-acs-signature-nonce;x-acs-version,Signature=xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "Name": "my-knowledge-base",
    "Description": "My first knowledge base"
  }'

File Upload Flow

  1. ApplyFileUploadLease — Obtain an upload lease and pre-signed URL.
  2. Upload File — Upload the file to the pre-signed URL.
  3. AddFile — Register the file with the knowledge base and get a FileId.

Error Codes

CodeDescription
DataCenter.FileTooLargeFile exceeds the size limit
PromptTemplate.TemplateNotFoundTemplate not found
InvalidAccessKeyId.NotFoundAccess key not found
NOT AUTHORIZEDNot authorized to the workspace