wix-docs

Wix Docs — Wix API／SDK のドキュメントを検索

Wix API に関する正確な情報（エンドポイント、HTTP メソッド、リクエスト／レスポンス本文、フィールド、列挙値、エラー）を確認できます。Wix のエンドポイント、パス、本文、列挙値を記憶だけで決して作り出さないでください。まずここで確認してください。このスキル内のエンドポイント例も同様です。仕組みを説明するためのものであり、スナップショットと同じく古くなる可能性があります。利用する前に、実際の仕様を確認してください。

検索は短い流れです。適切なページを見つけてから、内容を読みます。 curl（既定。以下を参照）を使うか、利用可能であれば Wix MCP ドキュメントツール（レーン 2）を使います。どちらの場合も、すでに分かっていることに応じて検索方法を選んでください。

• ドキュメント URL が分かっている → そのまま読みます（§2）。すでに特定できているページを再検索する必要はありません。
• 複数ステップのワークフロー（「サービスの設定から決済まで予約を処理する」など） → API のコーパスと併せて、検索にレシピコーパスを含めます。手順が記載されている API コーパスと一緒に document_types: ["SKILLS", …] を指定します（§1A）。レシピには手順の順序、手順間の注意点、全体を処理する一括エンドポイントが記載されています。これらは、単一のメソッドページには記載されていません。関連するレシピが見つからない場合は、同じ検索結果に含まれる、メソッドごとに検証済みの仕様を組み合わせてワークフローを構成してください。
• 特定の操作、フィールド、列挙値 → API コーパス（REST／SDK）を検索し、該当ページを読んで仕様を確認します。

レーン 1 — curl（既定）

ドキュメントは Markdown ページのツリー構造になっています。https://dev.wix.com/docs/… の URL に .md を追加すると、そのページを Markdown 形式で取得できます。SDK も MCP も不要です。

1. ページを探す — 検索、閲覧、またはインデックスの照会

適切なページにたどり着く方法は 3 つあります。目的に合った方法を使ってください。

A. セマンティック検索。 キーワードだけでなく、「顧客が予約を申し込めるようにする」のように、自然な言葉で目的を説明してください。関連度順に検索結果が返されます。どちらの形式でも、POST の本文は同じです。必須の search_term（1～500）、document_type（単一のコーパス）または document_types（複数のコーパスを 1 回の検索で指定する配列）のいずれか一方、maximum_results（1～20、既定値は 15。統合された検索結果全体の件数）、lines_in_each_result（0～200、既定値は 20。0 は検索結果ごとの行数制限なし）を指定します。コーパス：REST（既定）・SDK・SKILLS・WIX_HEADLESS・BUSINESS_SOLUTIONS・VELO・WDS・BUILD_APPS・CLI・OVERVIEW。SKILLS は専用のレシピコーパスです。単一 API の検索では返されない、複数ステップのワークフローページが含まれます。OVERVIEW は、どの開発アプローチや API ファミリーを使うかといった、プラットフォームの全体像を扱います。

質問に関係するコーパスを、1 回の呼び出しで検索してください。 サービスはコーパス全体をまとめて順位付けし、検索結果を混在させて返します。そのため、どのコーパスから試すべきか推測する必要はなく、関連度を基に結果を比較できます。また、複数回のリクエストを 1 回にまとめられます。組み合わせに決まりはありません。質問に応じて選んでください。document_type と document_types の両方を渡すとエラーになります（"Pass either document_type or document_types, not both"）。未知のコーパス名を指定した場合は、有効な一覧とともに拒否されます。

使い方に応じて、次の 2 つの形式から選んでください。

/docs/search/markdown → 検索結果を読む（まずはこちら）。 JSON が返されます。単一の content フィールドには、LLM が読みやすい Markdown 文字列が含まれます（jq -r '.content' で抽出できます）。各検索結果は要約されたメソッドドキュメントで、API のエンドポイント、実際のリクエストコード例、レスポンスの形式、メソッドの説明（注意点を含む）が記載されています。検索結果はプレビューであり、ページ全体ではありません。要約形式ではセクションごとに出力上限が固定されているため、lines_in_each_result を増やしても、すべてのセクションが拡張されるわけではありません。また、0 にすると検索結果ごとの行数制限はなくなりますが、元のページ全体が再現されるわけではありません。検索結果の内容を基に実装する前に、必要な入力、ケースに適用される条件、必要な REST 仕様または SDK シグネチャが揃っているか確認してください。揃っていれば、そのまま進めて問題ありません。追加取得は不要です。足りない場合は、目的を絞って追加取得を 1 回行います。メソッドページを読む（§2）か、スキーマを取得してください（§C）。

curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/search/markdown' \
  -H 'Content-Type: application/json' \
  --data-raw '{"search_term":"create a booking","document_type":"REST","maximum_results":3}' \
  | jq -r '.content'      # no jq? → python3 -c 'import sys,json;print(json.load(sys.stdin)["content"])'

ワークフローと個々の呼び出しにまたがる質問では、両方のコーパスを一度に検索します。レシピとメソッドごとのコントラクトが、1つのランキングリストで返されます。

curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/search/markdown' \
  -H 'Content-Type: application/json' \
  --data-raw '{"search_term":"end to end booking flow","document_types":["SKILLS","REST"],"maximum_results":6}' \
  | jq -r '.content'

/docs/search（JSON）→ 結果に応じて振り分けます。 { results: [ { title, url, content, relevance_score, kb_name, … } ] } を返します。構造化された検索結果です。プログラムから選択・振り分けたい場合に使います。検索結果の url を使ってそのページを読み取る（§2）か、スキーマクエリに渡します（§C）。

kb_name で各検索結果の種類がわかります。すべての検索結果に含まれており、種類によって可能な操作が決まります。スキーマを取得できるのはメソッドページだけです（§C）。記事やレシピは文章として読み取ります（§2）。

リクエストで種類を分けることはできません。1つのコーパスに複数の種類が混在します。API リファレンスを検索すると、メソッドページとその周辺の文章の両方が返されます。また、メソッドページだけを返すコーパスはありません。そのため、document_types でコーパスを選び、返された結果の kb_name で種類を分けます。代わりにしてはいけないことが2つあります。url の有無から種類を推測しないでください（記事やレシピを含め、すべての検索結果に url があります）。また、指定したコーパスから種類を推測しないでください。

多くの値は種類を名前で示します（メソッドページは …_METHODS_…、文章は …_DOCS_…、レシピは SKILLS_KB_ID）。ただし、すべてがそうではありません。SDK のメソッドインデックスは API_REFERENCE_SDK_KB_ID です。そこで、名前のパターンに当てはめたり ID のリストをハードコードしたりするのではなく、検索で実際に返されたラベルを確認し、それに基づいて処理してください。

# see what came back — label, title, url
curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/search' \
  -H 'Content-Type: application/json' \
  --data-raw '{"search_term":"end to end booking flow","document_types":["REST","SKILLS","WIX_HEADLESS"],"maximum_results":10}' \
  | jq -r '.results[] | "\(.kb_name)\t\(.title)\t\(.url)"'
# no jq? → python3 -c 'import sys,json;[print(r.get("kb_name"),r["title"],r.get("url")) for r in json.load(sys.stdin)["results"]]'

# then take the kind you need, by the label you just saw
… | jq -r '.results[] | select(.kb_name == "REST_METHODS_KB_ID") | "\(.title)\t\(.url)"'

B. ドキュメントツリーをメニューとして参照します。 方法は2つあります。対応ポータルでは構造化ブラウズエンドポイント（型付きで件数を確認でき、フィルタリングも可能なため、こちらを推奨）を使い、それ以外のあらゆるサーフェスやページの読み取りには .md メニューツリーを使います。

B1. 構造化ブラウズ — 対応ポータル。 POST /mcp-docs-search/v1/docs/menu/browse はポータルのツリーをたどり、各子要素の種類、メソッドの場合は HTTP 動詞、およびサブツリーの件数（「Catalog V3 — メソッド 121 件、記事 32 件」など）を返します。そのため、形状に基づいて適切な領域を選べます。grep が必要な約 40 KB のメニューページではなく、約 2 KB で済みます。include、name_filter、depth を指定すれば、目的の場所に直接移動できます。

ポータル（document_type）：REST（デフォルト — api-reference ポータル） · FRONTEND_SDK（sdk） · CLI（wix-cli） · BUILD_APPS（build-apps） · WIX_HEADLESS（go-headless）。ブラウズのみで、SDK は REST の別名です（API リファレンスでは各ページに両方のビューが記載されています）。これは FRONTEND_SDK を選択するものではなく、この別名はセマンティック検索には適用されません。ポータルの領域を確認するには、menu_url を省略します。ポータルのルートが返されます。対応ポータルの URL を menu_url に渡した場合も、ポータルが自動的に判別されます。

本文：menu_url?（絶対ドキュメント URL。ポータルのルートには省略）、document_type?、depth?（1、最大 6）、include?（CATEGORY·RESOURCE·METHOD·ARTICLE·WEBHOOK·OBJECT·SKILL）、deprecated?（デフォルトは HIDE·SHOW·ONLY）、name_filter?、max_nodes?、format?（デフォルトの MARKDOWN → content 文字列、STRUCTURED → url/http_method/resource_id/child_counts を含む JSON ツリーに加え、counts_by_type、truncated、deprecated_counts_by_type）。

無視せずに対応するべきレスポンスシグナルが2つあります。

• truncated: true — ノード数の上限により一覧が途中で切られています。読み直すのではなく、範囲を絞ってください。より深い menu_url を指定してブラウズするか、include/name_filter を厳しくするか、depth を小さくします。
• 非推奨項目のフィルタリング — 非推奨の項目はデフォルトで非表示です。deprecated_counts_by_type に、フィルタリングされた件数が表示されます。ブラウズ結果に API がない場合、存在しないのではなく、非推奨になっている可能性があります。deprecated: "SHOW"（または "ONLY"）を指定して再度ブラウズし、代替先への参照が記載されていれば、それに従ってください。

# a vertical's structure, with per-child subtree counts
curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/menu/browse' \
  -H 'Content-Type: application/json' \
  --data-raw '{"menu_url":"https://dev.wix.com/docs/api-reference/business-solutions/stores"}' \
  | jq -r '.content'

# jump straight to a method by name — no multi-level grep
curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/menu/browse' \
  -H 'Content-Type: application/json' \
  --data-raw '{"menu_url":"https://dev.wix.com/docs/api-reference/business-solutions/bookings","include":["METHOD"],"name_filter":"cancel","depth":4}' \
  | jq -r '.content'

# a non-REST portal: the CLI docs, from the portal root
curl -sS -X POST 'https://www.wixapis.com/mcp-docs-search/v1/docs/menu/browse' \
  -H 'Content-Type: application/json' \
  --data-raw '{"document_type":"CLI","depth":2}' | jq -r '.content'

ブラウズのみ：ページのURLが返されます。.md を末尾に付けて読み取り（§2）、正確なスキーマは §C で確認してください。 B2. .md メニューツリー — あらゆるサーフェスとページの読み方。 すべてのドキュメントパスには .md 版があるため、依存関係なしであらゆるサーフェスをたどれます。構造化ブラウズでカバーされないサーフェス（例：Velo）を調べる場合や、末端ページを読む場合に使います。curl https://dev.wix.com/docs/llms.txt はトップレベルのマップです。その下にあるポータルは次のとおりです。

ポータル	ここから始める内容
api-reference.md	すべてのバックエンド／ビジネスソリューション API — メインのポータルです。 各ページには REST と SDK の両方の使い方が記載されています（SDK ビューは .md?apiView=SDK）。
sdk.md	API リファレンスに含まれない SDK 専用サーフェス： クライアントのセットアップ（createClient、OAuthStrategy）、コアモジュール（@wix/sdk、@wix/essentials）、ホストモジュール（dashboard／editor／site）、フロントエンドモジュール（members、pay、seo、storage、pricing-plans、…）。
go-headless.md	ヘッドレスのセットアップ、認証、ホスティング、フレームワークとの統合。
build-apps.md	Wix アプリ／拡張機能の構築。
wix-cli.md · velo.md	Wix CLI コマンド、Velo のサイトコーディング API。

メニューのようにたどる — 任意のパスに .md を付けます（セクションは子リンクのメニュー、末端ページはコンテンツ／メソッドページです）。パスを短くすると上位へ、長くすると下位へ移動します。メソッドページだけでなく、同じ階層にある概要記事や「About …」記事、フロー記事も読んでください。例 — 各メニューで次のリンクを検索しながら、予約作成メソッドまでたどります。

curl -sS https://dev.wix.com/docs/api-reference/business-solutions.md            | grep -i bookings   # → .../bookings.md
curl -sS https://dev.wix.com/docs/api-reference/business-solutions/bookings.md   | grep -iE 'bookings|flow'  # → resource/flow pages
curl -sS https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings.md | grep -i create      # → the create method leaf
curl -sS https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md  # read it

API リファレンスポータルの 2 階層マップ（すべての分野と、その直下の階層）は references/EXTRACTING.md にあります。

C. API インデックスをクエリする — 1 回の呼び出しで構造化された結果を取得。 code-mode の検索エンドポイントは、lightIndex（REST API 仕様全体。すべてのリソースとメソッドに operationId、httpMethod、menuPath、docsUrl、実行可能な publicUrl を含む）に対して JS 関数を実行します。メソッドをプログラムで列挙／フィルタリングしたい場合、たとえば特定の分野をブラウズしたり、すべてのメソッドを検索したりする場合に最適です。メニューをたどらずに、docsUrl と publicUrl を一度に取得できます。

# pinpoint a method by keyword across the whole index → its docsUrl + executable publicUrl
curl -sS -X POST 'https://mcp.wix.com/api/code-mode/search' -H 'Content-Type: application/json' \
  --data-raw '{"code":"async function(){ return lightIndex.flatMap(r=>r.methods).filter(m=>/createBooking$/i.test(m.operationId)).map(m=>({op:m.operationId, httpMethod:m.httpMethod, publicUrl:m.publicUrl, docsUrl:m.docsUrl})); }"}'

絞り込んで必要なフィールドだけを返してください — インデックスは大きいため、フィルタリングせずに出力すると膨大になります。対象範囲はREST サーフェスです。lightIndex がインデックス化するのは REST のメソッドです。REST ポータルの文章コンテンツ（概要、レシピ、フローページ）は、関連する articles インデックスと getArticleContentByUrl(docsUrl)／getArticleContent(resourceId) で参照できます。SDK 専用サーフェスやその他のポータルはここにはありません。それらには A/B を使ってください。また、返されるスキーマは REST の契約であり、SDK のシグネチャではない点に注意してください（同じメソッドの SDK ビューはドキュメントページの §2 にあります）。その他の例（分野のブラウズ、menuPath のたどり方、リソーススキーマ）とスキーマ／記事の読み取り方法については、references/API_SPEC_SEARCH.md を参照してください。

Wix MCP が利用可能な場合、これらと同じ機能をネイティブツールとして提供します（curl／JSON の定型処理は不要です）— Lane 2。

2. 移動先の内容を確認する

URL に .md を追加すると、3 種類のページのいずれかが表示されます。どの種類かを確認し、それに応じて扱ってください。

• メニューページ — セクションのパス（§1B の閲覧で取得）。子リンクの一覧で、数十 KB になることもよくあります。全体を読まず、grep で目的の子ページを探してから、そのページに進んでください。

  curl -sS 'https://dev.wix.com/docs/api-reference/business-solutions/bookings.md' | grep -i 'booking'
  

• 記事／ガイド — 導入、概念、サンプルフローのページです。通常は小さな文章の Markdown なので、全体を読んでください。

  curl -sS 'https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/introduction.md'
  

• メソッドページ — 1 つの API メソッドを扱うページで、最も容量の大きい種類です。REST と JavaScript SDK の両方のセクション、完全なリクエスト／レスポンススキーマ、コード例を含み、多くの場合 100 KB 以上あります。ページ全体を読み込まず、まず構成を把握してから必要な部分を取得してください（呼び出し方を理解するには、通常、コード例で十分です）。

  curl -sS "$URL.md" | grep -nE '^#{1,3} '                                              # 1. map the outline
  curl -sS "$URL.md" | awk '/^## REST API/{r=1} r&&/^### Examples/{f=1} /^## JavaScript SDK/{f=0} f'  # 2. just the REST examples
  curl -sS "$URL.md" | grep -nE 'name: (selectedPaymentOption|totalParticipants)'       # 3. grep specific schema fields
  

  その他のレシピ（REST と SDK を分ける、列挙型を解決する）→ references/EXTRACTING.md。

  正確な構造化スキーマと列挙型の値が必要な場合は、Markdown を手作業で切り出さず、curl の POST で API 仕様を https://mcp.wix.com/api/code-mode/search に問い合わせてください（MCP の SearchWixAPISpec と同等の方法です）。code は、lightIndex と getResourceSchemaByUrl(docsUrl) をスコープ内で利用できる JS 関数です。必要な内容だけを返してください。

  getResourceSchemaByUrl は、指定した URL を対象にします。メソッド URL を指定すると、methods 配列にそのメソッドだけが含まれるスキーマが返されます。methods[0] として読み取り、m.docsUrl と入力値を比較して選択しないでください（リーダーが URL を正規化します）。リソース URL（メソッド URL の最後のセグメントを除いたもの）を指定すると、リソース全体が返されます。関連する操作やリソースで共有されるコンテキストが必要な場合は、こちらを取得してください。

  # find a method by keyword → its docsUrl + executable publicUrl
  curl -sS -X POST 'https://mcp.wix.com/api/code-mode/search' -H 'Content-Type: application/json' \
    --data-raw '{"code":"async function(){ return lightIndex.flatMap(r=>r.methods).filter(m=>/createBooking$/i.test(m.operationId)).map(m=>({op:m.operationId, httpMethod:m.httpMethod, publicUrl:m.publicUrl, docsUrl:m.docsUrl})); }"}'
  
  # a METHOD URL → that one method's contract (resolve $circular refs via s.components.schemas)
  curl -sS -X POST 'https://mcp.wix.com/api/code-mode/search' -H 'Content-Type: application/json' \
    --data-raw '{"code":"async function(){ const s=await getResourceSchemaByUrl(\"https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking\"); const m=s.methods[0]; return { publicUrl:m.publicUrl, requestBody:m.requestBody, responses:m.responses }; }"}'
  

  応答は { "result": … } または { "error": "<message>" } です。どちらの場合も HTTP 200 が返るため、ステータスではなく本文を確認してください。エラーテキストには修正方法が示されます。記事 URL の場合は getArticleContentByUrl に切り替え、未知の URL の場合はキーワードで lightIndex を検索してください。同じ内容で失敗した検索を再送しないでください。エラーに基づいて何かを変更し、見つからない場合は仕様を推測せず、その制約を報告してください。

  使用例一式（リソース一覧、部分 URL の解決、列挙型／ネストされた参照の展開）→ references/API_SPEC_SEARCH.md。

レーン 2 — Wix MCP のドキュメントツール（エージェントが利用できる場合のみ）

Wix MCP が接続されている場合、これらはレーン 1 と同じバックエンド（ドキュメント検索サービスと API 仕様インデックス）をネイティブツールでラップしたものです。スキーマ検証、レスポンスサイズへの対応があり、curl／JSON の定型記述は不要です。curl を使う方法より便利ですが、データソースが増えるわけではありません。利用できる場合はこれらを使い、利用できない場合はレーン 1 に切り替えてください。このレーンは任意です。ツールがない場合はスキップしてください。

ツール	用途
SearchWixRESTDocumentation	キーワードで REST メソッド／レシピを検索する
SearchWixSDKDocumentation	SDK メソッドを検索する（モジュールメニューに表示されない実行時関数も検索できます）
SearchWixAPISpec → getResourceSchemaByUrl	構造化スキーマを取得する — メソッド URL はそのメソッドの仕様、リソース URL はリソース全体に使用します
ReadFullDocsArticle	レシピ／フロー／記事のページ全体を読む
BrowseWixRESTDocsMenu	メニューツリーをたどってメソッドに進む

• 仕様を確認するにはメソッドを、コンテキストを確認するにはリソースを取得してください。 メソッド URL からは、そのメソッドだけが返されます。要件が別のメソッド（たとえば、単一作成では memberId が必須でも、一括作成のページでは省略されている場合）に含まれている可能性があるときは、代わりにリソース URL を取得してください。リソースビューには、すべてのメソッドと共有オブジェクトスキーマが含まれています。
• このスキルの冒頭にあるレシピ優先のルーティングは、こちらでも適用されます。複数ステップのワークフローでは、メソッドごとの呼び出しを組み立てる前にレシピのコーパスを検索してください（多くの業種で、…/business-solutions/<vertical>/skills ノードの下にレシピが公開されています）。

.md サフィックス

.md を追加するのは、ページに直接 curl を実行する場合だけです。MCP ツールと検索エンドポイントには、.md を付けない通常のドキュメント URL を指定してください。.md 付きの URL を MCP ツールに渡さないでください。

ドキュメントから呼び出しへ

契約を理解するのがこのスキルの役割ですが、実行にはアイデンティティが必要です。メソッドが受け付けるアイデンティティは、読み取る内容の一部です。呼び出す前に、メソッドのページにある権限とアイデンティティに関する注記を確認し、トークンのサイト／アカウントのスコープが一致していることを確認してください。トークンの発行（CLI 管理者トークン、ビジタートークン）、アイデンティティモデル、動的なサイトコンテキストレポートについては → references/CALLING.md を参照してください。

コードを書く前に

記憶に頼らず、ページでエンドポイント、HTTP メソッド、リクエストボディの形式、必須フィールド、列挙値を確認してください。それから呼び出しを記述します。スキルに同梱されたクライアントを拡張する場合は、既存のトランスポート／ヘルパーのスタイルを維持してください。追加するのは呼び出し 1 つであり、アーキテクチャを再設計するのではありません。