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 天内仍有调用该端点的密钥拥有者。

相关文档