文章

文章是知識庫的基本組成單位。建立、列出、更新與刪除 AI Agent 回答問題所用的內容。

文章是 AI Agent 知識庫的基本組成單位。每篇文章代表一項知識，例如說明頁面、常見問答、產品說明，或任何 AI 應知道的內容。

文章有三種類型：文章（含標題與本文的完整文件）、段落（簡短獨立文字）與 URL 文章（匯入網頁內容時自動建立）。您可以透過 API 手動建立文章、使用匯入外部內容從網站匯入、透過上傳檔案上傳，或從 Intercom 同步。

不需要重新訓練。每篇新增、更新或刪除的文章都會在背景自動處理，完成即生效，通常只需幾秒。可透過下方的 embed_state 欄位，或取得知識庫設定中的 pending_embed_count 追蹤。

選用範例檢查

預覽 API Action 請求。以合成範例值呈現提供的請求範本，但不傳送。請省略憑證標頭。
預覽 JSONPath 比對結果。對提供的 JSON 檢查根節點、欄位、陣列索引與萬用字元路徑。不會執行 Action 或儲存對話記憶。

建立文章

權限範圍：write_all

POST https://app.quickchat.ai/v1/api/knowledge_base/articles/

請求本文

參數	說明
`content` 字串，必填	文章內容
`type` 字串	`"Article"`（預設）或 `"Paragraph"`
`title` 字串	文章標題

"Article"：含標題與內容的完整知識庫文件。適合常見問答、說明文章與產品描述。
"Paragraph"：沒有標題的簡短獨立文字。適合簡短事實、一行答案與快速參考資料。
"URL"（唯讀）：從網站匯入內容時自動建立，包含擷取的頁面內容與來源 URL。建立時不能指定此類型。

Shell
Python

curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/articles/ \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "content": "Our return policy allows returns within 30 days.",
  "title": "Return Policy"
}'

import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "content": "Our return policy allows returns within 30 days.",
        "title": "Return Policy",
    },
)
data = response.json()

回應 201 Created

{
  "id": 1234,
  "article_id": "abc-123",
  "type": "Article",
  "title": "Return Policy",
  "description": "",
  "content": "Our return policy allows returns within 30 days.",
  "state": "draft",
  "deploy_state": "draft",
  "embed_state": "pending",
  "refresh_failure_reason": "",
  "version": null,
  "max_available_version": null,
  "url": null,
  "tags": [],
  "created_timestamp": "2026-01-15",
  "last_modified_timestamp": "2026-01-15",
  "downloaded_timestamp": "2026-01-15",
  "last_updated_timestamp": "2026-01-15",
  "last_updated_from_external_source_timestamp": null
}

欄位	說明
`id` 整數	文章數字 ID，所有 URL 路徑使用的正式識別碼
`article_id` 字串	舊版字串識別碼，可能為空，請改用 `id`
`type` 字串	`"Article"`、`"Paragraph"` 或 `"URL"`
`title` 字串	文章標題
`description` 字串	文章說明
`content` 字串	文章內容
`deploy_state` 字串	`"draft"` 或 `"published"`，僅為標籤（見下方說明）
`embed_state` 字串或 null	文章是否已上線：`"pending"`、`"embedding"`、`"embedded"` 或 `"failed"`（見下方說明）
`state` 字串	內部處理狀態（見下方說明）
`refresh_failure_reason` 字串	最近一次 URL 更新失敗的原因。沒有儲存已分類的更新失敗時為空
`version` 整數或 null	目前版本號碼
`max_available_version` 整數或 null	最高可用版本
`url` 字串或 null	來源 URL（URL 類型文章）
`tags` 字串陣列	關聯標籤
`created_timestamp` 字串	建立日期
`last_modified_timestamp` 字串	最後修改日期
`downloaded_timestamp` 字串	下載日期
`last_updated_timestamp` 字串	最後更新日期
`last_updated_from_external_source_timestamp` 字串或 null	最後一次從外部來源更新的時間

文章有三個狀態欄位，只有其中一個能告訴您 AI Agent 是否正在使用該文章：

embed_state：最重要的欄位。"pending" 與 "embedding" 表示文章仍在處理；"embedded" 表示已上線且 AI Agent 正在使用；"failed" 表示處理未完成，文章未被使用。寫入後應輪詢此欄位。
deploy_state："draft" 或 "published"。僅供您整理內容的標籤，不會影響 AI 是否使用文章。
state：內部內容擷取狀態。大多數 API 使用者可忽略。對 URL 文章而言，"refresh_failed" 表示最近一次更新未取代已儲存內容。
refresh_failure_reason：已分類 URL 更新失敗的穩定類別："http_error"、"soft_404"、"off_domain_redirect"、"auth_wall"、"error_page"、"empty_content" 或 "thin_content"。若在 Quickchat 能分類頁面前擷取就失敗，可能為空。除非 embed_state 也失敗，否則最後儲存的內容仍保持上線。

列出文章

權限範圍：read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/articles/

查詢參數

參數	說明
`limit` 整數	每頁項目數
`offset` 整數	要略過的項目數
`types` 字串	依類型篩選：`Article`、`Paragraph`、`URL`
`tags` 字串	依標籤篩選
`url` 字串	依 URL 篩選
`title` 字串	依標題篩選
`query` 字串	依內容搜尋

Shell
Python

curl 'https://app.quickchat.ai/v1/api/knowledge_base/articles/?limit=10&offset=0' \
  -H 'Authorization: Bearer <API_TOKEN>'

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"limit": 10, "offset": 0},
)
data = response.json()

回應 200 OK

{
  "items": [
    {
      "id": 1234,
      "article_id": "abc-123",
      "type": "Article",
      "title": "Return Policy",
      "description": "",
      "state": "published",
      "deploy_state": "published",
      "embed_state": "embedded",
      "refresh_failure_reason": "",
      "version": 1,
      "max_available_version": 1,
      "url": null,
      "tags": ["policies"],
      "created_timestamp": "2026-01-15",
      "last_modified_timestamp": "2026-01-15",
      "downloaded_timestamp": "2026-01-15",
      "last_updated_timestamp": "2026-01-15",
      "last_updated_from_external_source_timestamp": null
    }
  ],
  "offset": 0,
  "limit": 10,
  "count": 1
}

清單回應不包含 content 欄位。請使用取得文章讀取特定文章的完整內容。

取得文章

權限範圍：read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/articles/{article_id}

Shell
Python

curl https://app.quickchat.ai/v1/api/knowledge_base/articles/1234 \
  -H 'Authorization: Bearer <API_TOKEN>'

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/1234",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

回應 200 OK：傳回完整文章物件，結構與建立文章回應相同，包含 content 欄位。

更新文章

權限範圍：write_all

PATCH https://app.quickchat.ai/v1/api/knowledge_base/articles/{article_id}

請求本文

參數	說明
`content` 字串	更新後的文章內容
`title` 字串	更新後的標題
`tags` 字串陣列	更新後的標籤
`save_mode` 字串	`"draft"`（預設）或 `"publish"`

save_mode: "draft" 選項僅設定 deploy_state 旗標，不會阻止 AI 使用內容。草稿文章會與已發布文章一樣被處理及使用。請勿用它暫存尚未上線的內容；只有準備好上線時才寫入文章。

Shell
Python

curl -X PATCH https://app.quickchat.ai/v1/api/knowledge_base/articles/1234 \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "Updated Return Policy",
  "content": "Returns accepted within 60 days.",
  "save_mode": "publish"
}'

import requests

response = requests.patch(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/1234",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "title": "Updated Return Policy",
        "content": "Returns accepted within 60 days.",
        "save_mode": "publish",
    },
)
data = response.json()

回應 200 OK：傳回更新後的文章物件。

刪除文章

依 ID 刪除一篇或多篇文章。

權限範圍：write_all

DELETE https://app.quickchat.ai/v1/api/knowledge_base/articles/

請求本文：文章 ID 的 JSON 陣列。

Shell
Python

curl -X DELETE https://app.quickchat.ai/v1/api/knowledge_base/articles/ \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '[1234, 5678]'

import requests

response = requests.delete(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json=[1234, 5678],
)

回應 200 OK

搜尋文章

以文字比對搜尋文章內容。

權限範圍：read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/articles/search

查詢參數

參數	說明
`query` 字串，必填	搜尋查詢
`is_case_insensitive` 布林值	搜尋不區分大小寫（預設：`true`）
`with_title_url_and_tags` 布林值	搜尋包含標題、URL 與標籤（預設：`true`）
`strict_search` 布林值	要求完全符合（預設：`false`）
`num_of_display_articles` 整數	顯示文章數（預設：`5`）
`num_of_data_articles` 整數	搜尋文章數（預設：`15`）

Shell
Python

curl 'https://app.quickchat.ai/v1/api/knowledge_base/articles/search?query=return%20policy' \
  -H 'Authorization: Bearer <API_TOKEN>'

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/search",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"query": "return policy"},
)
data = response.json()

回應 200 OK

{
  "article_snippets": [
    {
      "article_id": 1234,
      "expository_sentence": "Our return policy allows returns within 30 days.",
      "query_words_ids": [
        {"start_char": 4, "end_char": 10, "text": "return"}
      ]
    }
  ],
  "article_snapshots": {
    "items": [],
    "offset": 0,
    "count": 1
  }
}

列出段落

列出所有段落類型文章。段落是沒有標題的簡短獨立文字，而完整文章同時具有標題與內容本文。

權限範圍：read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/articles/paragraphs

查詢參數

參數	說明
`limit` 整數	每頁項目數
`offset` 整數	要略過的項目數
`query` 字串	依內容篩選

Shell
Python

curl 'https://app.quickchat.ai/v1/api/knowledge_base/articles/paragraphs?limit=10' \
  -H 'Authorization: Bearer <API_TOKEN>'

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/paragraphs",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"limit": 10},
)
data = response.json()

回應 200 OK

{
  "items": [
    {
      "id": 1,
      "content": "Our return policy allows returns within 30 days."
    }
  ],
  "offset": 0,
  "count": 1
}

文章

選用範例檢查

建立文章

列出文章

取得文章

更新文章

刪除文章

搜尋文章

列出段落

開始使用

AI Agent

Actions

對話

Channels

您的網站

Helpdesk 與 CRM

通訊應用程式

帳戶與帳務

開始使用

設定

Knowledge Base

對話