REST API

Kanorio管理REST APIを使用すると、バックエンドプログラムからHTTPS経由で直接サイトの読み書きが可能になります。サイトの作成や設定、ページセクションやブログ記事の読み書き、コレクションやデジタル製品の管理、メディアライブラリへの画像アップロード、注文や連絡先の照会、さらにサイトの公開やカスタムドメインの管理まで行えます。

その基盤となる機能はAIアシスタント（MCP）の接続と同一ですが、呼び出し方法が異なります。

• AIアシスタント（MCP）の接続: ChatGPT、Claude、CursorなどのAIが、会話の文脈に基づいて自律的に操作します。
• 管理REST API（本ガイド）: スケジュールされたスクリプト、カスタムバックエンド、CI/CDパイプライン、または自動化ノードから、明示的なコードを使用して特定のエンドポイントを呼び出します。
• コンテンツ配信APIおよび顧客API: サイト独自のドメインでホストされる、公開読み取りおよびメンバーログイン用のAPIです（コンテンツ配信APIおよびカスタムフロントエンドでのメンバーログインとデジタル配信の統合を参照）。

ベースURL: https://app.kanorio.com/api/v1

エンドポイント、パラメータ、エラーコードの完全版（SSOT）: すべてのエンドポイントパス、クエリパラメータ、リクエスト/レスポンスの例、レート制限、エラーコード表は、公開されている管理APIリファレンスページ上のコードコントラクトからリアルタイムで生成されます（機械可読仕様: https://app.kanorio.com/api/v1/openapi.json）。本ガイドでは、認証、並行処理の安全性、廃止ポリシーに焦点を当てます。

認証と権限ルール

REST APIは、knr_pat_で始まるのみを受け付けます。すべてのリクエストにAuthorizationヘッダーを含めてください。

Authorization: Bearer knr_pat_your_key

• キーの作成方法: 「アカウント設定 › APIアクセス」に移動し、「キーを作成」をクリックして「その他のツール」を選択し、有効にするサイトと権限スコープにチェックを入れます。
• 実際の権限計算: $\text{実際の権限} = \text{キーの権限} \cap \text{サイトにおけるメンバーの役割}$
• OAuthトークンは利用不可: ChatGPTやClaude経由で「許可」をクリックして取得した接続トークンは/api/mcpに限定されており、REST APIの呼び出しには使用できません。

セキュリティ警告: knr_pat_キーは、あなたの個人管理IDと同等です。必ずサーバー側の環境変数またはシークレット管理サービスに保存してください。ブラウザ側のフロントエンドコード、モバイルアプリ、または公開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アシスタント）がダッシュボードエディタで行った変更をスクリプトが上書きしないように、ページセクションやサイト全体のナビゲーションを書き込む際には楽観的同時実行制御を使用します。

• ページセクションの更新（PUT /sites/:id/pages/:pageId/sections）: まずページを読み取ってupdatedAtタイムスタンプを取得し、リクエストにifUnmodifiedSince: "<updatedAt>"を含める必要があります。
• ヘッダー、フッター、サイト設定の更新: まずGET /sites/:id/globalsを呼び出してcontentUpdatedAtタイムスタンプを取得し、リクエストにifUnmodifiedSince: "<contentUpdatedAt>"を含める必要があります。
• 最後に読み取った後にリソースが他の誰かによって変更されていた場合、サーバーは書き込みを拒否し、409 CONFLICT（最新のタイムスタンプ付き）を返します。再読み込み、マージ、再送信を行ってください。

クイックスタート：読み取りから公開までの4つのリクエスト

キーを環境変数として設定します：

export KANORIO_TOKEN="knr_pat_your_key"

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": "Artisan Bakery",
        "description": "Handcrafted sourdough bread and French pastries, baked fresh every morning."
      }
    ]
  }'

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 '{}'

レート制限と廃止ポリシー

• レート制限: キーごとに個別に計算されます。一般的なエンドポイントは1分間に120リクエスト、公開/非公開エンドポイントは1時間に30リクエストです。これを超えると、Retry-Afterヘッダーと共に429 RATE_LIMITEDが返されます。
• バージョンと変更履歴: すべての追加や変更は、公開されているAPI変更履歴に記録されます。
• 廃止期間: エンドポイントの削除や破壊的変更が必要な場合、安定版に対して最低6ヶ月の廃止期間を設けます。レスポンスには標準のDeprecation、Sunset、Linkヘッダーが自動的に含まれ、過去30日間にそのエンドポイントを呼び出したキーの所有者には事前に通知を行います。

関連ドキュメント