Knowledge Base and Products

Bulk-sync FAQs, documents, and products via API, with incremental updates keyed by external ID.

4.1 Knowledge Base

Method	Path	Description
POST	`/v1/knowledge/faqs/batch`	Batch write Q&A pairs, `{"items": [{"question", "answer", "external_id"}]}`, up to 500 items. Updated incrementally by `external_id`; unchanged content won't be reprocessed
POST	`/v1/knowledge/documents`	Add a document: `{"title", "content"}` to provide the text directly, or `{"url"}` and we'll crawl the page for you. When `external_id` is included, the old document with the same ID is replaced
POST	`/v1/knowledge/documents/upload`	Upload a file (multipart, field `file`); supports txt, md, html, pdf, docx, max 20MB
GET	`/v1/knowledge/documents`	Document list, `?page=&limit=&source_type=`
GET	`/v1/knowledge/documents/{id}`	Document details; `status` is `pending` / `processing` / `ready` / `failed`
DELETE	`/v1/knowledge/documents/{id}`	Delete

Documents are processed asynchronously after being written, and usually become ready within a few seconds. If a webhook is configured, you'll receive document.ready or document.failed.

4.2 Products

Method	Path	Description
POST	`/v1/products/batch`	Batch write, up to 500 items, updated incrementally by `external_id`
GET	`/v1/products`	Product list
DELETE	`/v1/products/{external_id}`	Delete

Product fields:

{
  "external_id": "w-1001",
  "name": "潜水自动机械表",
  "description": "200 米防水，蓝宝石表镜",
  "category": "手表",
  "price": "399.00",
  "currency": "USD",
  "stock": 12,
  "url": "https://shop.example.com/p/w-1001",
  "image_url": "https://shop.example.com/img/w-1001.jpg",
  "attributes": {"材质": "316L 钢", "表径": "39 mm"},
  "variants": [{"sku": "w-1001-blk", "name": "黑色", "price": "399.00", "stock": 5}],
  "status": "active"
}

A stock of null means inventory isn't tracked; products with a status of inactive won't be recommended. AI answers about price and stock use only the values here.

Was this page helpful?

Last updated: October 31, 2026