API 參考

分頁

所有 Kanorio API 的列表端點皆採用 limit 與 cursor 參數，並回傳 data、hasMore 與 nextCursor。

Management API、Content Delivery API 以及 Customer API 的所有列表端點皆採用相同的分頁方式。

請求

參數	類型	預設值	備註
`limit`	整數	20	範圍由 1 至 100。部分端點會註明較低的上限。
`cursor`	字串	無	來自上一頁的 `nextCursor`。第一頁請省略此參數。

回應

{
  "data": [{ "id": "post_example01" }, { "id": "post_example02" }],
  "hasMore": true,
  "nextCursor": "eyJvIjoyMCwicyI6ImFiYzEyMyJ9"
}

欄位	類型	備註
`data`	陣列	此頁面的項目，按端點的順序排列。
`hasMore`	布林值	當仍有下一頁時為 `true`。
`nextCursor`	字串或 null	將其作為 `cursor` 傳入以獲取下一頁。最後一頁時為 `null`。

部分端點會在這些欄位之外新增其他欄位。例如，集合項目（collection items）會新增 assets，這是一個包含該頁面所參照之所有圖片與檔案的對應表（map）。

規則

游標（Cursors）是不透明的。 請勿解析、建構或長時間儲存它們。其格式可能會在未經通知的情況下變更。
保留其他參數。 游標僅適用於發出該游標時所使用的篩選條件、排序與限制。若在發送游標時使用不同的篩選條件，將會回傳 400 INVALID_CURSOR。當篩選條件變更時，請重新開始，不要使用游標。
不支援頁碼或偏移量。 API 不接受 page、pageSize 或 offset。
預設不提供總數。 計算每一筆符合的項目成本高昂，因此列表不會回傳總數。Content Delivery API 有兩個端點在您傳入 total=true 時會回傳 total：集合項目，以及搜尋（總數與結果在同一次查詢中算出）。
短列表仍使用封裝格式。 具有小型固定上限的列表（例如 Webhook 端點或重新導向）會將所有內容回傳在單一頁面中，並將 hasMore 設為 false。相關參考頁面會對此進行說明。

讀取每一頁

curl "https://app.kanorio.com/api/v1/sites/ws_example123/posts?limit=50" \
  -H "Authorization: Bearer $KANORIO_TOKEN"

# then, while hasMore is true
curl "https://app.kanorio.com/api/v1/sites/ws_example123/posts?limit=50&cursor=eyJvIjo1MH0" \
  -H "Authorization: Bearer $KANORIO_TOKEN"

SDK 的 paginate 會為您追蹤 nextCursor，並適用於任何列表端點：

import { createManagementClient, paginate } from "@kanorio/sdk";

const client = createManagementClient({ token: process.env.KANORIO_TOKEN! });

for await (const post of paginate((cursor) =>
  client.get("/sites/{id}/posts", { params: { id: "ws_example123" }, query: { limit: 50, cursor } })
)) {
  console.log(post.slug);
}

當您需要將整個列表作為陣列取得時，請使用 listAll 取代 paginate。