Knowledge、FAQ、学習用 API

この 86 のエンドポイントで、ナレッジ、FAQ ソース、シナリオ、学習対象、顧客対応用の Shop memory を管理できます。以下のパスは Public API のベース URL からの相対パスです。

すべてのリクエストで X-Api-Key を指定し、ボディを送る場合は Content-Type: application/json も指定します。キーによってストアが決まるため、shop ID は送信しません。例：

curl -s 'https://app.chatty.net/v1/knowledge/entries?type=qna&page=1&limit=20' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

各行が 1 つのエンドポイントです。リクエスト列には JSON ボディ、クエリ文字列の例、または「ボディなし」を記載しています。:id などのパスパラメーターは、対応する取得・作成エンドポイントの ID に置き換えてください。12345 などの数値もプレースホルダーです。レスポンス例は構造と主要フィールドを示す抜粋で、実際のレコードには追加のメタデータが含まれる場合があります。空の一覧は結果がない場合の有効な例であり、常に空を返すわけではありません。すべてのルートにページ末尾の共通エラーと、各セクションで説明する固有のエラーが適用されます。

書き込みが成功しても、内容のインデックス作成やジョブが完了したとは限りません。返されたステータスを読み、対応する進捗取得を繰り返してください。タイムアウト後の作成の再試行は重複処理になる可能性があるため、再試行前に保存済みレコードを確認してください。

Knowledge entries

GET /knowledge/entries は Chat API のカーソルではなく、page（デフォルト 1）と limit（デフォルト 20）を使用します。任意のフィルターは search、カンマ区切りの type、source、topic、status、state、issue、および dateFrom/dateTo です。種類は qna、url、shopify_page、file で、url には Shopify ページも含まれます。問題の種類は conflict、index_error、too_short、too_long、stale です。現在、locale を指定すると結果は空になります。一覧は最上位に data、count、total、pagination を返します。

作成時の type のデフォルトは qna です。Q&A には question と answer が必要です。URL エントリーには url、ファイルの内容には content と任意の filename を使い、ページの本文には mdContent を使用できます。内容と併せて title、status、topics（文字列の配列）、scope（support/sales の配列）を任意で指定できます。ステータスは active、draft、inactive です。下書きを指定すると、status: "inactive" と isDraft: true で保存されます。status を省略した場合も下書きになります。スクリーニングで内容が拒否されたり確認対象になったりする場合があるため、公開済みと決めつけず、返されたステータスを確認してください。allowDuplicate: true は同じ内容の独立したコピーを許可しますが、すべての検証を省略するものではありません。

PATCH では answer、question、scope、status、title、topics、url を更新でき、その他のフィールドは無視されます。内容の編集は取り込み処理を通りますが、scope のみの編集では内容のスクリーニングは再実行されません。一括作成・ステータス更新は 1〜100 件のエントリーまたは ID を受け付けます。一括作成は HTTP 201 でも項目ごとの失敗を返します。一括ステータス更新は最初にすべての ID を確認しますが、全件を一体として処理するトランザクションではありません。一括削除には 1〜100 件の ID と confirm: true が必要です。指定した ID だけを削除し、ナレッジ全体は削除しません。

このグループのエラーは VALIDATION_FAILED、NOT_FOUND、CONFIRM_REQUIRED、DUPLICATE_ENTRY、INGESTION_REVIEW、CONFLICT_PENDING、SCREEN_* です。重複エラーには error.existingId が含まれる場合があります。一括処理は全項目の結果を確認してから再試行してください。

インポート、エクスポート、リビジョン

エクスポートは format=json（デフォルト）または format=csv を受け付け、ダウンロード用の knowledge.json または knowledge.csv を返します。data では包みません。JSON には entries が入り、CSV は Q&A のエクスポート形式です。

インポートでは format（json または csv）、内容を指定する text、content、entries（この優先順位）、および fileIds を使用できます。文字列以外の内容は JSON 化され、文字列の前後の空白は除去されます。内容またはファイル ID のどちらかが必要です。これは非同期のナレッジ取り込みであり、FAQ ソースのインポートではありません。返された jobId で進捗を確認します。ステータスは queued、importing、applied、partial、failed です。report.applied、report.failed、report.items で結果を確認してください。HTTP 202 だけでは内容が利用可能になったとはいえません。ストアの最新のインポートジョブのみが公開されるため、古いジョブ ID は 404 になる場合があります。

リビジョンの取得は保留中の内容を返します。公開操作は既存のエントリーに反映し、削除操作は保留中のリビジョンだけを破棄します。これらのルートではリビジョンを作成しません。存在しないリビジョンは NOT_FOUND、インポートやエクスポートの入力エラーは VALIDATION_FAILED です。公開時には、上記の取り込みエラーも発生する場合があります。

状態確認と運用操作

このセクションの GET にボディは不要です。Summary はステータス別の件数と、ソース種別ごとの有効な件数をまとめます。Coverage は競合、インデックス失敗、長い内容、短い内容、古い内容の件数を返します。unresolvedQuestionsPath は管理画面用のパスです。API では /knowledge/unresolved を使用してください。

一括処理の進捗は、最新のキュー登録済み処理を表します。キャンセルは、対応するジョブが待機中または処理中の場合にだけ要求フラグを設定します。完了済みの書き込みは戻しません。FAQ audit はスキャンを開始します。state が done になるまで再取得し、その後でレポートを使用してください。開始成功は監査完了を意味しません。

重複解決には candidateId、decision（create、merge、replace）、entry が必要です。create は独立したエントリーを保持し、merge は回答とトピックを候補に結合し、replace は候補の ID に新しい内容を適用します。HTTP 200 だけで保存されたと判断せず、saved、skipped、pendingReview、report を確認してください。判断値やボディが不正な場合は VALIDATION_FAILED、重複候補が存在しない場合は現在 500 INTERNAL_ERROR になります。

存在しないエントリーの再同期は NOT_FOUND を返します。ストアページの再同期は、キューに登録した jobId を返します。ページ同期は /sync/status で確認できますが、そのページ用カウンターだけでは完了を証明できません。

提案と未回答の質問

提案の一覧には任意の status（pending、accepted、skipped）を指定できます。HTTP レスポンスの data 内にさらに一覧オブジェクトが入ります。項目は data.data、件数は data.summary、生成状況は data.generationStatus を参照してください。生成は HTTP 202 と queued または in_progress を返します。結果は一覧を再取得して確認してください。キュー登録に失敗すると 500 GENERATION_FAILED になります。

承認では編集済みの answer を任意で指定できます。省略すると提案された回答を使います。スキップにボディは不要です。存在しない項目、承認済みの項目の再承認、承認済み項目のスキップは 404 NOT_FOUND になります。一括操作は /knowledge/suggestions/bulk-accept と /knowledge/suggestions/bulk-skip で、空ではない ids 配列が必要です。一括スキップのレスポンス例は {"data":{"success":true,"skipped":1}} です。返される処理件数は要求件数より少ない場合があります。ID の入力形式が不正なら VALIDATION_FAILED、未知の一括操作なら NOT_FOUND です。

未回答一覧は open 状態の質問のみを返します。任意のクエリは reason、limit（デフォルト 20）、after/before（レコード ID）、hasCount=true です。data.data と data.pagination を使用し、Knowledge 一覧のページ番号は使いません。解決には answer が必要で、status は任意です。保存済みの質問から Knowledge の Q&A を作成した後、質問を解決済みにします。エントリー作成と同じ検証、スクリーニング、重複エラーが適用されます。削除は質問を deleted 状態にして一覧から除外する操作で、Knowledge エントリーは削除しません。

FAQ ソースのカテゴリ、質問、ブロック

これらはストアフロントに表示する FAQ のソースレコードで、Knowledge エントリーとは別です。一覧はページ分割せず全件を返します。GET と DELETE にボディは不要です。カテゴリの表示タイトルは question で、name ではありません。作成時に必須です。published、featured、icon、position は任意で、位置を省略すると末尾に追加します。カテゴリを削除すると、その質問はデフォルトカテゴリに移動し、関連する FAQ ブロックも更新されます。デフォルトカテゴリは削除できません。

質問の作成には question、answer、同じストアに存在する categoryId が必要です。published のデフォルトは true で、featured は任意です。PATCH は既存の値にマージし、移動先カテゴリを検証するため、質問を移動するには有効な categoryId が必要です。画像にはインライン base64 ではなく URL を使用してください。ブロックのボディには blockName、heading、subHeading、display、categorizeFaqs と、ソースの質問を参照する faqs 配列（questionId、categoryId、question、answer、published）を使います。表示場所には showOnProductPages、productPagesMode（all、specific、collections、tags）、products、collections、tags、showOnHomepage、showOnCollectionPages、showOnCartPage、showOnBlogPages、showOnSpecificPages、showCustomUrls、customUrls（ストアフロントのパスを 1 行に 1 つ）を指定できます。レイアウトを変更する前に既存のブロックを読み取ってください。PATCH は配列全体を含め、指定したフィールドを置き換えます。ブロック作成は id、質問作成は questionId、カテゴリ作成は categoryId と position を返します。

利用可能な FAQ を Knowledge に同期する前に FAQ audit を実行してください。POST /faq/sync-to-knowledge にボディは不要で、準備ができた項目をキューに登録します。同じパスを GET し、state、phase、processed、total、progress とエラーを確認してください。HTTP 202 は受け付けたことだけを示します。このグループのエラーは 400 VALIDATION_FAILED、404 NOT_FOUND、その他の失敗の 500 INTERNAL_ERROR です。FAQ のインポート、エクスポート、全件削除は以下にあります。

FAQ のインポート、エクスポート、全件削除

エクスポート。 format は csv（デフォルト）または json です。status は all（デフォルト）または published で、published は公開済みカテゴリーの公開済みの質問だけを残します。すべての行が 1 つのレスポンスで返ります。CSV は BOM（byte order mark）で始まり、列は Question、Answer、Category、Published question、Featured question、Published category、Featured category です。JSON は質問のフラグのみを返します。複数のカテゴリーに属する質問は、カテゴリーごとに 1 回ずつ表示されます。

インポート。 Content-Type: text/csv の CSV、または JSON（行の配列、あるいは {"rows":[...],"overwrite":false,"publish":false}）のどちらかを送信します。どちらも 1～500 行を受け付けます。

• JSON の行には question（10,000 文字まで）、answer（100,000 文字まで）、category（1,000 文字まで）、published、featured が必要です。無効な行が 1 つでもあると、リクエスト全体が 400 VALIDATION_FAILED で拒否されます。
• CSV にはヘッダー Question、Answer、Category、Published question、Featured question が必要です。エクスポートに含まれるカテゴリー列など、余分な列は無視されます。CSV ファイルは 5 MB までで、超えると 413 PAYLOAD_TOO_LARGE を返します。CSV では、値が空の行、true / false 以外のフラグがある行、インライン base64 画像を含む行は fail に数えられてスキップされ、他の行は引き続きインポートされます。fail.detail には、問題ごとに 1 から始まる行番号が一覧されます。
• カテゴリーは名前の完全一致で照合されます。存在しないカテゴリーは作成され、publish が true の場合のみ公開されます。
• 同じカテゴリー内で同じ文面の質問は duplicate として数えられスキップされますが、overwrite が true の場合は既存の質問が更新されます。overwrite と publish のデフォルトは false で、クエリパラメータとしても送信できます。
• success はインポートまたは更新した行数、countQuestionNew は新しい質問の数、categories は使用したカテゴリーの数です。Chatty は結果をストアのメールアドレスにもメールで送信します。

全件削除。 すべての FAQ の質問とカテゴリーを完全に削除し、FAQ ブロックと翻訳からも消去します。ボディは {"confirm":"DELETE ALL FAQS"} と完全に一致する必要があります。ジョブはバックグラウンドで実行され、1 秒あたり約 100 件の質問を処理します。state が done または error になるまで GET /faq/delete-all をポーリングしてください。削除がまだ一度も実行されていない場合は {"data":null} を返します。削除が queued または running の間に再度開始すると 409 ALREADY_RUNNING を返します。30 分間進捗がないジョブは停止したものとして扱われ、新しいジョブを開始できます。

商品別 FAQ

productId には Shopify 商品 ID（数値 ID または URL エンコード済みの Shopify GID）を使用します。PUT には空ではない faqs 配列が必要で、各項目の question と answer は必須です。id を指定すると、その FAQ を更新します。レスポンスは FAQ レコードではなく保存済み ID の配列です。GET は商品とストアで絞り込みます。DELETE の対象 FAQ は、その商品とストアに属している必要があります。入力が不正な場合は VALIDATION_FAILED、対象が存在しない場合は NOT_FOUND、同じ商品質問がある場合は DUPLICATE_ENTRY です。

Scenarios

カスタムシナリオの作成には name と instruction が必要です。任意の intents と exampleMessages は空配列がデフォルトで、exampleMessages の要素は文字列である必要があります。任意の scope は support/sales の配列で、検索対象の範囲を指定します。status は active、draft、inactive を受け付け、デフォルトは draft です。対応する intent は product_search、cart、order_tracking、discount、after_sale、human_transfer、loyalty、sizing、general、other、ask_related_product、ask_complementary、shipping_delivery、payment、store_info、product_compare、availability、gift、subscription、order_change です。

PATCH ではカスタムシナリオの内容と、関連する学習データ（linkedItems の type/id、または linkedDocumentIds）を編集できます。識別情報などの変更不可フィールドと keyword は無視されます。デフォルトのシナリオで更新できるのは status と、そのシナリオ固有の設定だけです。非対応のフィールドは FIELD_NOT_PERMITTED になります。デフォルトのシナリオは削除できません。作成時にはプランのカスタムシナリオ上限も確認されます。現在、LIMIT_REACHED は 403 ではなく HTTP 500 で返ります。ステータスだけを変更する場合は専用エンドポイントを使用してください。

関連付け可能な学習データの取得では type が必須で、url、shopify_page、file、qna、in-app、product、collection、discount を使用できます。search、status、page（デフォルト 1）、limit（デフォルト 50、最大 100）、sort（デフォルト updatedAt_desc）は任意ですが、適用されるフィルターはソースによって異なります。結果は id、type、label、任意の subtitle/updatedAt と、最上位の pagination.hasNext を返します。非対応の type は HTTP 400 になり、通常のコード付きオブジェクトではなく文字列の error を返します。

リビジョン用ルートは、既存の保留中リビジョンを確認するためのものです。公開時は同じシナリオ ID の内容を更新し、リビジョンの削除ではシナリオ自体を削除しません。シナリオやリビジョンが存在しなければ NOT_FOUND、入力が不正なら VALIDATION_FAILED です。一覧には品質と利用状況も含まれます。observability.available: false は測定済みの利用状況がないことを示し、マッチ件数がゼロという意味ではありません。

Size guides

作成には name と、読み取り可能なサイズ表の markdown が必要です。任意の measurementFields で解析された項目を上書きできます。matchType のデフォルトは automatic、matchLogic は {"collectionIds":[],"collections":[]}、status は draft です（active/draft/inactive に対応）。PUT は指定したフィールドを更新します。markdown を含めると表を再解析し、明示された measurementFields は保持します。読み取り時には解析しません。

一覧のフィルターは status、sort（デフォルト updatedAt_desc）、limit（デフォルト 20）、レコード ID の after/before、hasCount=true です。未回答一覧と同様に、ページ情報は data 内に入ります。書き込みでは現在の Pro 以上のサイズガイド利用権も確認し、403 PLAN_REQUIRED を返す場合があります。その他のエラーは VALIDATION_FAILED、NOT_FOUND、chart_unreadable、not_a_size_chart、chart_service_unavailable です。最後のエラーは HTTP 503、サイズ表の入力に関する 2 つのエラーは HTTP 400 です。

学習用カタログ

これらの一覧は data.data と data.pagination を返します。解析時に外側の data を省略しないでください。商品一覧では search、page（デフォルト 1）、limit（デフォルト 10、最大 50）、sort（デフォルト title_asc）、status（active、inactive、not-added、all。デフォルト active）を指定できます。任意の絞り込みには vendors、tags、metaTags、productIds、collectionIds（または collectionId）、collections（タイトル）、restrictProductIds があります。複数値は同じクエリキーを繰り返して指定します。商品やコレクションの条件なしで isSmartRecommendation を指定すると、エラーメッセージ付きの空の結果を返します。

割引一覧では search、status（active、inactive、expiring）、page（デフォルト 1）、limit（デフォルト 20）、sort を指定できます。sort は updatedAt、createdAt、title に _asc/_desc を付けます。expiring は 7 日以内に終了する有効な割引を選択します。コレクション一覧は search、status、sort（デフォルト updatedAt_desc）、page（デフォルト 1）、limit（デフォルト 20、最大 100）、hasCount=true に対応します。

ステータス変更には、対応する ID 配列と boolean の enabled が必要です。商品は Shopify ID、コレクションは同期済み一覧の ID を使用します。商品を有効にする際、上限に達していても HTTP 200 を返す場合があります。要求した全商品が学習済みと判断する前に、limitReached、toEnableIds、toDisableIds と成功フラグを確認してください。未同期のコレクションを更新すると、400 INVALID_VALUE と不足する collectionIds を返すため、先に商品同期を実行してください。その他の入力エラーは VALIDATION_FAILED、存在しないショップは NOT_FOUND です。不正な割引 sort は現在 500 INTERNAL_ERROR になります。

Shop memory と同期

Shop memory は顧客対応エージェント向けのナレッジであり、マーチャント向けアシスタントの記憶ではありません。プロフィールとスキルの取得には audience: "customer-facing-agent" が付きます。プロフィールは null、スキルは空配列の場合があります。スキル ID は数値の文字列です。存在しないスキルや他ストアのスキルの削除は 404 NOT_FOUND になります。

学習には任意の boolean の force、family（deepseek または anthropic）、quality（quality-pair、cheap-only、agentic）を指定できます。未対応の family/quality はサービスのデフォルト値になります。HTTP 202 と jobId を返すため、Public API の /shop-memory/jobs/:id で確認してください。レスポンスの statusUrl は旧 /agent-api/ 配下なので、そのまま使用しないでください。ジョブは queued から running に進み、applied、failed、skipped のいずれかで終わります。別のジョブが実行中の場合は現在 500 JOB_IN_FLIGHT になります。繰り返し登録せず、そのジョブを待ってください。存在しないジョブや他ストアのジョブは 404 NOT_FOUND または 404 SHOP_SCOPE_MISMATCH です。

消去には confirm: true が必要で、ショップのプロフィールとスキルの両方を削除します。確認がなければ 400 VALIDATION_FAILED です。顧客の記憶や通常の Knowledge エントリーは削除しません。

同期できるリソースは products、discounts、pages のみです。POST にボディは不要で、202 と jobId を返します。ただし、この ID は受け付けたことを示すもので、個別ジョブの永続的な進捗参照には使えません。ストアの現在の進捗は /sync/status で取得します。商品・割引の done には、同期済み件数と総件数の数値カウンターがあり、エラーがないことが必要です。カウンターがないことは完了を意味しません。ページ側には対応するカウンターの組がないため、pages.done は false のままです。未知のリソースは 404 NOT_FOUND を返します。

エラー

上記の関連付け可能な学習データの type エラーを除き、失敗時は {"error":{"code":"…","message":"…"}} を返します。details、reason、existingId が付く場合もあります。一括処理は HTTP ステータスだけで成功と判断しないでください。

作成が拒否された場合の例：

{"error":{"code":"DUPLICATE_ENTRY","message":"DEDUPE_CONTENT_HASH","existingId":"entry_123"}}

キー、バージョン、レート制限の共通ルールは Authentication と Errors and rate limits をご覧ください。MCP tools reference では、これらのルートを呼び出すグループ化されたツールを説明しています。利用できるツールは認証方式とスコープによって異なります。