• 简体中文

      • 知识库 API

      知识库 API 用来管理当前店铺的知识条目。调用前需要先完成开放平台鉴权。

      基础路径：

      /open/v1/knowledge

      目前可以列出知识条目、获取单条、删除单条，以及创建一条手动输入的知识。

      条目字段

      字段类型说明
      idstring条目 ID。
      typestring条目类型，例如 input-text、pdf、link、text-file、QA、correction、page、shopify-policy。
      titlestring条目标题。
      contentstring条目内容。只在获取单条时返回。
      statusstringsuccess 或 failed。
      expiredAtstring 或 null过期时间，UTC。条目不过期时为 null。
      createdAtstring 或 null创建时间，UTC。

      列表响应不包含 content。

      列出条目

      GET /open/v1/knowledge/entries

      查询参数：

      参数必填默认值说明
      title否无按标题过滤，不区分大小写。
      type否无按条目类型精确匹配。
      page否1页码，从 1 开始。
      pageSize否20每页数量，最大 50。
      onlyExpired否false为 true 时，只返回设置了过期时间的条目。

      page 必须大于等于 1。pageSize 必须在 1 到 50 之间。超出范围会返回 400。

      200 响应：

      {
  "items": [
    {
      "id": "665f0c2e0f1a2b3c4d5e6f70",
      "type": "input-text",
      "title": "shipping policy",
      "status": "success",
      "expiredAt": null,
      "createdAt": "2026-09-04T00:00:00Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 1
}

      没有匹配结果时仍然返回 200，此时 items 为 []，total 为 0。

      获取单条

      GET /open/v1/knowledge/entries/{id}

      路径参数：

      参数说明
      id条目 ID。

      200 响应：

      {
  "id": "665f0c2e0f1a2b3c4d5e6f70",
  "type": "input-text",
  "title": "shipping policy",
  "content": "We ship in 3 days.",
  "status": "success",
  "expiredAt": null,
  "createdAt": "2026-09-04T00:00:00Z"
}

      如果这个 ID 在当前已鉴权店铺中不存在，返回 404。

      删除单条

      DELETE /open/v1/knowledge/entries/{id}

      路径参数：

      参数说明
      id条目 ID。

      删除成功返回 204，没有响应体。

      对同一条已经存在的条目重复删除也是安全的，仍然返回 204。如果这个 ID 从未对当前店铺可见，则返回 404。

      创建手动输入条目

      POST /open/v1/knowledge/entries/user-input
Content-Type: application/json

      请求体：

      字段必填说明
      title是条目标题。空白文本会被拒绝。
      content是条目内容。空白文本会被拒绝。
      {
  "title": "shipping policy",
  "content": "We ship in 3 days."
}

      201 响应：

      {
  "id": "665f0c2e0f1a2b3c4d5e6f70"
}

      标题或内容为空白时返回 400。如果店铺已达到知识条目配额，返回 409。

      这个请求不是幂等的。超时后重试可能会再创建一条知识。成功后请保存返回的 id。

      示例

      curl "{baseUrl}/open/v1/knowledge/entries?page=1&pageSize=20" \
  -H "X-Platform-Access: pk_..." \
  -H "X-Platform-Secret: sk_..."