REST API

Kanorio Management REST API 讓您的後端程式直接透過 HTTPS 讀寫網站：建立與設定網站、讀寫頁面模組與網誌帖文、管理資料集合與數碼交付物、上傳媒體庫圖片、查詢訂單與聯絡人，以及發佈網站與管理自訂網域。

它底層的能力與連接 AI 助理（MCP）完全相同，差別在於呼叫方式：

• 連接 AI 助理（MCP）：由 ChatGPT、Claude、Cursor 等 AI 依對話脈絡自主選擇工具替您操作。
• Management REST API（本篇）：由您的排程腳本、自家後台、CI/CD 流程或自動化節點，以明確的程式碼主動呼叫指定端點。
• Content Delivery API 與 Customer API：掛在網站自己網址下的前端公開讀取與買家登入 API（見 Content Delivery API 與在自建前端接入會員登入與數碼交付）。

Base URL：https://app.kanorio.com/api/v1

完整端點、參數與錯誤碼參考（SSOT）：所有端點的路徑、查詢參數、Request／Response 範例、速率限制與錯誤代碼表，皆由程式碼契約即時產生於公開的 Management API 參考頁（機器可讀規格：https://app.kanorio.com/api/v1/openapi.json）。本文專注說明認證、並行安全與淘汰政策。

認證與權限規則

REST API 僅接受以 knr_pat_ 開頭的。請在每個請求加上 Authorization Header：

Authorization: Bearer knr_pat_您的金鑰

• 如何建立金鑰：前往「帳戶設定 › API 存取」點選「建立金鑰」，工具選擇「其他工具」，勾選可操作的網站與權限範圍。
• 實際權限計算：$\text{實際權限} = \text{金鑰勾選的權限} \cap \text{您在該網站的成員角色}$。
• 不接受 OAuth 憑證：透過 ChatGPT、Claude 點選「允許」取得的連線憑證僅限用於 /api/mcp，無法用來呼叫 REST API。

資安提醒：knr_pat_ 金鑰等同您的個人管理身分。請務必存放在伺服器端的環境變數或密鑰保管服務中，絕對不要將金鑰寫進瀏覽器前端程式碼、流動裝置 App 或公開的 Git 儲存庫。

核心寫入機制：草稿邊界與樂觀鎖

1. 如何取得網站 ID（:id）

所有網站層級的端點路徑都以 /sites/:id/... 開頭。您可以進入後台「網站設定 › 一般」滑到底部複製 websiteId，或先呼叫 GET /api/v1/sites 列出金鑰可存取的網站清單。

2. 草稿與立即生效的邊界

• 先寫入草稿（需呼叫 POST /sites/:id/publish 才會更新託管網站）：頁面模組（PUT .../sections）、頁首與頁尾（PUT .../globals/header|footer）、全站共用按鈕與社群連結、網站外觀設定。網誌帖文的新增與修改同樣只更新工作副本，需呼叫 POST .../posts/:postId/publish 才會公開。
• 預設直接發佈：資料集合項目（items.* 預設 publish: true，傳 publish: false 則存草稿）、商店商品與交付物。

3. 防覆蓋機制（樂觀鎖 ifUnmodifiedSince）

為了防止您的腳本與正在使用後台編輯器的團隊成員（或另一支 AI 助理）互相覆蓋改動，寫入頁面模組與全站導覽時採用樂觀並行控制（Optimistic Concurrency Control）：

• 改寫頁面模組（PUT /sites/:id/pages/:pageId/sections）：必須先讀取頁面取得 updatedAt，並在寫入時帶入 ifUnmodifiedSince: "<updatedAt>"。
• 改寫頁首、頁尾與全站設定：必須先呼叫 GET /sites/:id/globals 取得 contentUpdatedAt，並在寫入時帶入 ifUnmodifiedSince: "<contentUpdatedAt>"。
• 若在您讀取之後該資源已被他人修改，伺服器會拒絕寫入並回傳 409 CONFLICT（附帶最新時間戳），請重新讀取並合併後再重送。

快速開始：從讀取到發佈的四個請求

先將金鑰設為環境變數：

export KANORIO_TOKEN="knr_pat_您的金鑰"

1. 列出網站並取得網站 ID

curl -s https://app.kanorio.com/api/v1/sites \
  -H "Authorization: Bearer $KANORIO_TOKEN"

2. 讀取頁面列表，取得首頁 id 與 updatedAt

curl -s https://app.kanorio.com/api/v1/sites/ws_example123/pages \
  -H "Authorization: Bearer $KANORIO_TOKEN"

3. 帶上 ifUnmodifiedSince 改寫頁面模組草稿

curl -s -X PUT https://app.kanorio.com/api/v1/sites/ws_example123/pages/pg_example456/sections \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ifUnmodifiedSince": "2026-10-15T08:00:00.000Z",
    "sections": [
      {
        "id": "sec_hero_1",
        "type": "page-main-visual",
        "title": "拾光手作烘焙",
        "description": "每天清晨出爐的手作酸種麵包與法式常溫甜點。"
      }
    ]
  }'

4. 發佈網站上線

curl -s -X POST https://app.kanorio.com/api/v1/sites/ws_example123/publish \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

速率限制與版本淘汰政策（Deprecation & Sunset）

• 速率限制：每把金鑰獨立計算——一般端點每分鐘 120 次、發佈與下架端點每小時 30 次。超過時回傳 429 RATE_LIMITED 並附 Retry-After 秒數。
• 版本與變更紀錄：所有新增與調整皆記載於公開的 API 變更紀錄（Changelog）。
• 淘汰保護期：當某個端點需要移除或做不相容變更時，在正式版（Stable）遵循至少 6 個月淘汰期，回應會自動附帶標準 Deprecation、Sunset 與 Link Header，並主動寄信通知近 30 天內仍有呼叫該端點的金鑰擁有者。

相關文件