API ドキュメント
このページは2つの部分に分かれています:公開読み取り可能なアドレス(キー不要、検索エンジンとAI検索クローラーが直接読み取り可能)とAI Agent接続用のskillチャネル(サイトトークンが必要、WorkBuddyなどのAgentが本サイトを読み書きするためのもの)です。
一、公開アドレス:キー不要
| アドレス | 用途 | パラメータ | 実測ステータス |
|---|---|---|---|
| /sitemap.xml | サイト全体の公開ページインデックス | なし | 200 |
| /robots.txt | クロールルールの説明 | なし | 200 |
| /llms.txt | AI検索クローラー向けのサイト説明と公開アドレス一覧 | なし | 200 |
| /api/geo/v1/capabilities | 本サイトで読み取り可能なフィールドと公開アドレス一覧を宣言 | なし | 200 |
| /capi/geo/list | 公開コンテンツ(商品 / カテゴリ / ページ / 記事)を一覧表示 | type、page、pageSize、updated_since | 200 |
| /capi/geo/product/info | 単一商品の公開ナレッジビュー | handle | 200 |
| /capi/geo/entity/info | ページなどのエンティティナレッジの公開ビュー | entity_type、entity_id | 200 |
統一して { code, message, data } を返し、code が 200 で成功を表します。公開済みのコンテンツのみを返します:公開済みの商品、公開済みのページと記事。
二、AI Agent接続(skillチャネル)
一言で言うと:インターフェースアドレス + サイトトークン、この2つの値をAgentに入力すれば使えます。トークンは本サイトの管理画面権限と同等です。リクエストヘッダーにのみ配置し、URLに書き込まないでください。コードリポジトリにコミットしないでください。
1. 2つの値を取得する
- 管理画面にログインし、左側ナビゲーションの「AI接続」ページを開きます。
- ページには2行あります:インターフェースアドレス(本サイトでは /api/skill に固定、完全なアドレスは https://あなたのドメイン/api/skill)とアクセストークン(sk_ で始まる)。
- 右側のコピーボタンをクリックします。「接続説明をコピー」をクリックすると、アドレス、認証、インターフェース検出方法を一括で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/capabilities | 200 / 46,063 B | 200 / 45,842 B |
| GET /api/skill/base/init | 200 / 644 B | 200 / 664 B |
| GET /api/skill/product/list?limit=2 | 200 / 25,534 B | 200 / 5,417 B |
| GET /api/skill/analytics/traffic-get | 200 / 3,424 B | 200 / 2,913 B |
| GET /api/skill/plugin/list | 200 / 15,673 B | 200 / 14,681 B |
| GET /api/skill/i18n/list | 200 / 5,275 B | 200 / 5,275 B |
| 同上、ただしトークンなし | 401 / 68 B | 401 / 68 B |
結論:両サイトとも通信経路は正常で、認証も有効、トークンなしは拒否されました(「未認証:X-Site-Token が欠落または不一致」を返却)。サイズの違いはデータ量の差であり、故障ではありません。
6. エラーコードと対処
| ステータス | 意味 | 対処方法 |
|---|---|---|
| 401 | トークン欠落または不一致 | リクエストヘッダー名が X-Site-Token か確認;トークンがリセットされていないか確認 |
| 403 | 権限マトリックスによりブロック | 戻り値の reason を確認;管理画面の「インターフェース権限」で該当モジュールを開放 |
| 404 | パスが存在しない | まず capabilities でインターフェース名を照合し、記憶で組み立てない |
| 503 | サーバー側でサイトトークンが未設定 | 管理画面の「AI接続」ページを一度正常に開くと、システムが自動生成 |
7. 3つのセキュリティ原則
- トークンをURLに入れない、チャットウィンドウに貼り付けたりコードリポジトリにコミットしない——管理画面のログイン状態と同等です。
- 必要最小限の権限のみ付与:日常運用は読み取り専用 + 書き込みで十分、危険カテゴリは必要に応じて一時的に有効化。
- 担当者変更や引き継ぎ時はトークンをリセット、旧トークンは即座に無効になり、個別回収より確実です。
三、WorkBuddy接続の最小手順
- 管理画面「AI接続」→ インターフェースアドレスとアクセストークンをコピー(または接続説明全体を直接コピー)。
- WorkBuddyのコネクタ / スキル設定にサイトアドレスを入力し、認証に X-Site-Token を使用。
- Agentにまず capabilities を呼び出して自己記述させ、次に一覧に従って具体的なインターフェースを呼び出します。