Kanorio
Kanorio 開發者

開始使用

快速入門

建立權杖、進行第一次 Management API 呼叫、發佈文章並從 Content Delivery API 讀取，全程約十分鐘。

本快速入門將引導您從零開始，透過程式碼建立一篇網誌文章，並從您網站的公開 API 讀取該內容。

開始之前

  • 一個擁有至少一個網站的 Kanorio 帳戶。空白網站即可。
  • curl，若您想使用 SDK，則需 Node.js 20 或更高版本。

1. 建立個人存取權杖

個人存取權杖以 knr_pat_ 開頭，代表您的身分，並受限於您選擇的網站與權限。

  1. 開啟 帳戶設定 › API 存取 並選擇 建立金鑰。
  2. 選擇 其他工具，選取您要使用的網站，並挑選 編輯內容 權限預設集。發佈功能需要 完整存取 或發佈權限。
  3. 複製權杖。它只會顯示一次。
export KANORIO_TOKEN="knr_pat_..."

請將權杖存放在伺服器端。切勿將其放入瀏覽器程式碼或公開儲存庫中。請參閱 驗證 以了解其他權杖類型。

2. 列出您的網站

每個 Management API 請求都會發送到 https://app.kanorio.com/api/v1，並將權杖作為 Bearer 憑證。

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

列表會以統一的封裝格式回傳。請記下網站的 id 及其 publicUrl。

{
  "data": [
    {
      "id": "ws_example123",
      "name": "Sourdough Studio",
      "role": "OWNER",
      "isPublished": true,
      "publicUrl": "https://sourdough.kanorio.com"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

3. 建立草稿文章

寫入操作會建立草稿。在您發佈之前，網上網站不會有任何變更。

curl -X POST https://app.kanorio.com/api/v1/sites/ws_example123/posts \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How we feed our sourdough starter",
    "excerpt": "The first thing we do every morning.",
    "contentMarkdown": "## Flour and water\n\nEqual weights, twice a day."
  }'

回應內容即為該文章本身，包含 "status": "DRAFT" 以及如 post_example01 的 id。

4. 發佈文章

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

若回應為錯誤代碼 SITE_NOT_PUBLISHED，請使用 POST /sites/{id}/publish 發佈網站一次後再試。錯誤格式皆相同，詳見 錯誤。

5. 從 Content Delivery API 讀取文章

已發佈的內容無需權杖即可從您網站的自有網址讀取。請使用步驟 2 中的 publicUrl，或在 網站設定 › 開發者 下顯示的永久系統網址。

curl "https://sourdough.kanorio.com/api/v1/collections/blog/items?limit=1&fields=title,excerpt"

{
  "data": [
    {
      "id": "post_example01",
      "slug": "how-we-feed-our-starter",
      "publishedAt": "2026-11-02T08:00:00.000Z",
      "fieldData": {
        "title": "How we feed our sourdough starter",
        "excerpt": "The first thing we do every morning."
      }
    }
  ],
  "hasMore": false,
  "nextCursor": null,
  "assets": {}
}

使用 SDK 執行相同操作

npm install @kanorio/sdk

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

const management = createManagementClient({ token: process.env.KANORIO_TOKEN! });
const sites = await management.get("/sites");
const site = sites.data[0]!;

const post = await management.post("/sites/{id}/posts", {
  params: { id: site.id },
  body: { title: "How we feed our sourdough starter", contentMarkdown: "## Flour and water" },
});
await management.post("/sites/{id}/posts/{postId}/publish", { params: { id: site.id, postId: post.id }, body: {} });

const delivery = createDeliveryClient({ siteUrl: site.publicUrl! });
const latest = await delivery.get("/collections/{key}/items", { params: { key: "blog" }, query: { limit: 1 } });
console.log(latest.data[0]?.slug);

後續步驟