ページ

API ドキュメント

このページは2つの部分に分かれています:公開読み取り可能なアドレス(キー不要、検索エンジンとAI検索クローラーが直接読み取り可能)とAI Agent接続用のskillチャネル(サイトトークンが必要、WorkBuddyなどのAgentが本サイトを読み書きするためのもの)です。

一、公開アドレス:キー不要

アドレス用途パラメータ実測ステータス
/sitemap.xmlサイト全体の公開ページインデックスなし200
/robots.txtクロールルールの説明なし200
/llms.txtAI検索クローラー向けのサイト説明と公開アドレス一覧なし200
/api/geo/v1/capabilities本サイトで読み取り可能なフィールドと公開アドレス一覧を宣言なし200
/capi/geo/list公開コンテンツ(商品 / カテゴリ / ページ / 記事)を一覧表示type、page、pageSize、updated_since200
/capi/geo/product/info単一商品の公開ナレッジビューhandle200
/capi/geo/entity/infoページなどのエンティティナレッジの公開ビューentity_type、entity_id200

統一して { code, message, data } を返し、code が 200 で成功を表します。公開済みのコンテンツのみを返します:公開済みの商品、公開済みのページと記事。

二、AI Agent接続(skillチャネル)

一言で言うと:インターフェースアドレス + サイトトークン、この2つの値をAgentに入力すれば使えます。トークンは本サイトの管理画面権限と同等です。リクエストヘッダーにのみ配置し、URLに書き込まないでください。コードリポジトリにコミットしないでください。

1. 2つの値を取得する

  1. 管理画面にログインし、左側ナビゲーションの「AI接続」ページを開きます。
  2. ページには2行あります:インターフェースアドレス(本サイトでは /api/skill に固定、完全なアドレスは https://あなたのドメイン/api/skill)とアクセストークン(sk_ で始まる)。
  3. 右側のコピーボタンをクリックします。「接続説明をコピー」をクリックすると、アドレス、認証、インターフェース検出方法を一括でAgentに渡せます。

トークンをリセットすると旧トークンは即座に無効になります。使用中のAgentは同期して更新する必要があります。そうしないとすべての呼び出しが401を返します。

2. 認証方法

すべてのskillインターフェースは1つのリクエストヘッダーのみを認識します:X-Site-Token: あなたのトークン。トークンをURLパラメータに含めることはサポートされていません——URLはアクセスログ、Referer、ブラウザ履歴に記録されるため、管理画面権限を公開するのと同じです。

最小呼び出し例(ドメインとトークンを自分のものに置き換えてください):

curl -s https://あなたのドメイン/api/skill/capabilities \
-H "X-Site-Token: sk_あなたのトークン"

3. まず「何ができるか」を問い合わせ、次に具体的なインターフェースを呼び出す

最初からインターフェース名を推測しないでください。2つのセルフサービスインターフェースは常に利用可能で、Agentはこれらを使って自身で機能を検出します:

  • GET /api/skill/capabilities —— 完全な機能一覧:インターフェースパス、メソッド、読み書きタイプ、パラメータ説明、および本サイトの認証方式とバージョン番号。
  • GET /api/skill/base/init —— サイト基本情報:サイトタイプ(B2B / B2C)、現在のテーマ、利用可能なテーマ、言語と通貨。

その他のインターフェースはモジュールごとに分かれています。一般的なものは:/api/skill/product/list(商品)、/api/skill/plugin/list(プラグイン)、/api/skill/i18n/list(多言語エントリ)、/api/skill/analytics/traffic-get(トラフィック)、/api/skill/b2c-order/list(注文、B2Cサイト)。

4. 権限マトリックス:デフォルトは全開、モジュールごとに絞り込み可能

管理画面の「インターフェース権限」には2つのレベルがあります:すべて許可(デフォルト、開通時の動作と同じ)とモジュールごとの制限(モジュールごとに読み取り / 書き込み / 危険の3種類の操作を個別にオン/オフ)。

カテゴリ意味推奨
読み取り専用商品、コンテンツ、トラフィック、プラグイン状態の照会デフォルトで有効
書き込み商品、コンテンツ、装修の追加または変更Agentによる代行運用が必要な場合に有効化
危険削除、サイト全体の上書き、公開系操作明確に必要な場合のみ有効化

「インターフェース一覧(capabilities)」と「サイト初期化(base/init)」の2つの読み取り専用インターフェースは常に許可され、権限テーブルの影響を受けません——そうでなければAgentは「なぜ接続できないか」すら確認できません。保存後すぐに有効になり、Agent側で設定を変更する必要はありません。禁止されたインターフェースは403を返し、理由を説明します。

5. 実測記録(2026-10-19、2つの顧客サイトで各1回ずつテスト)

各サイト自身の実際のトークンで1つずつ呼び出した結果は以下の通りです(飾りなし、当時の戻り値そのまま):

インターフェースB2BサイトB2Cサイト
GET /api/skill/capabilities200 / 46,063 B200 / 45,842 B
GET /api/skill/base/init200 / 644 B200 / 664 B
GET /api/skill/product/list?limit=2200 / 25,534 B200 / 5,417 B
GET /api/skill/analytics/traffic-get200 / 3,424 B200 / 2,913 B
GET /api/skill/plugin/list200 / 15,673 B200 / 14,681 B
GET /api/skill/i18n/list200 / 5,275 B200 / 5,275 B
同上、ただしトークンなし401 / 68 B401 / 68 B

結論:両サイトとも通信経路は正常で、認証も有効、トークンなしは拒否されました(「未認証:X-Site-Token が欠落または不一致」を返却)。サイズの違いはデータ量の差であり、故障ではありません。

6. エラーコードと対処

ステータス意味対処方法
401トークン欠落または不一致リクエストヘッダー名が X-Site-Token か確認;トークンがリセットされていないか確認
403権限マトリックスによりブロック戻り値の reason を確認;管理画面の「インターフェース権限」で該当モジュールを開放
404パスが存在しないまず capabilities でインターフェース名を照合し、記憶で組み立てない
503サーバー側でサイトトークンが未設定管理画面の「AI接続」ページを一度正常に開くと、システムが自動生成

7. 3つのセキュリティ原則

  1. トークンをURLに入れない、チャットウィンドウに貼り付けたりコードリポジトリにコミットしない——管理画面のログイン状態と同等です。
  2. 必要最小限の権限のみ付与:日常運用は読み取り専用 + 書き込みで十分、危険カテゴリは必要に応じて一時的に有効化。
  3. 担当者変更や引き継ぎ時はトークンをリセット、旧トークンは即座に無効になり、個別回収より確実です。

三、WorkBuddy接続の最小手順

  1. 管理画面「AI接続」→ インターフェースアドレスとアクセストークンをコピー(または接続説明全体を直接コピー)。
  2. WorkBuddyのコネクタ / スキル設定にサイトアドレスを入力し、認証に X-Site-Token を使用。
  3. Agentにまず capabilities を呼び出して自己記述させ、次に一覧に従って具体的なインターフェースを呼び出します。