wix-docs

Wix Docs — look up the Wix API/SDK documentation

Get the exact truth about a Wix API — endpoint, HTTP method, request/response body, a field, an enum, or an error. Never invent a Wix endpoint, path, body, or enum from memory — confirm it here first. That includes the example endpoints in this skill: they illustrate the mechanics and go stale like any snapshot — discover the real contract before you rely on one.

A lookup is a short flow: find the right page, then read it. Do it with curl (default, below) or the Wix MCP doc tools if your agent has them (Lane 2). Either way, route by what you already know:

• You have a docs URL → just read it (§2). Don't re-search for a page you can already name.
• A multi-step workflow ("take a booking from service setup to payment") → include the recipe corpus in the search: document_types: ["SKILLS", …] alongside the API corpus the steps live in (§1A). A recipe carries step ordering, cross-step gotchas, and the one bundled endpoint that does the whole job — things no single method page states. No relevant recipe comes back → assemble the workflow from the verified per-method contracts in the same result set.
• One specific operation, field, or enum → search its API corpus (REST / SDK), then read or schema-check what you land on.

Lane 1 — curl (default)

The docs are one tree of markdown pages: append .md to any https://dev.wix.com/docs/… URL to get that page as markdown. No SDK, no MCP.

1. Find the page — search, browse, or query the index

Three ways to reach the right page — use whichever fits.

A. Semantic search. Describe what you want in natural language ("let a customer book an appointment"), not just keywords; hits come back ranked by relevance. Same POST body for both variants: search_term (required, 1–500), one of document_type (a single corpus) or document_types (an array — several corpora in one ranked call); maximum_results (1–20, def 15, counted across the combined result set), lines_in_each_result (0–200, def 20; 0 = no per-hit line cap). Corpora: REST (default) · SDK · SKILLS · WIX_HEADLESS · BUSINESS_SOLUTIONS · VELO · WDS · BUILD_APPS · CLI · OVERVIEW. SKILLS is the dedicated recipe corpus — multi-step workflow pages a single-API search does not return; OVERVIEW is platform orientation (which development approach, which API family).

Search the corpora a question actually spans, in one call. The service ranks them together and interleaves the hits, so they compete on relevance instead of you guessing which to try first — and one round trip replaces several. There's no fixed combination: pick by the question. Passing both document_type and document_types is an error ("Pass either document_type or document_types, not both"), and an unknown corpus name is rejected with the valid list.

Two variants — pick by what you're doing:

/docs/search/markdown → read it (start here). Returns JSON with a single content field holding one LLM-ready markdown string (extract it with jq -r '.content') where each hit is a condensed method doc: the API endpoint, real request code examples, the response shape, and the method description (with its gotchas). Hits are previews, not full pages: the condensed format has fixed per-section limits, so raising lines_in_each_result does not expand every section, and 0 only removes the per-hit line cap — it never reproduces the whole source page. Before building on a hit, check sufficiency: do you have the required inputs, the conditions that apply to your case, and the REST contract or SDK signature you need? If yes, proceed — no extra fetch. If not, make one targeted follow-up: read the method page (§2) or pull its schema (§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"])'

A question that spans a workflow and its individual calls asks for both corpora at once — the recipe and the per-method contracts arrive in one ranked list:

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) → route on it. Returns { results: [ { title, url, content, relevance_score, kb_name, … } ] } — structured hits. Use it when you want to pick/route programmatically: grab a hit's url to read that page (§2) or feed it to the schema query (§C).

kb_name tells you what each hit is — every hit carries one, and the kind decides what you can do with it: only a method page has a schema to pull (§C); an article or recipe is read as prose (§2).

The request can't make that split for you. A corpus mixes kinds — searching the API reference returns method pages and the prose around them — and no corpus returns method pages alone. So pick corpora with document_types, then separate the kinds on the way out with kb_name. Two things not to do instead: don't infer the kind from the presence of a url (every hit has one, articles and recipes included), and don't infer it from the corpus you asked for.

Most values name their kind (…_METHODS_… for method pages, …_DOCS_… for prose, SKILLS_KB_ID for recipes) but not all do — the SDK's method index is API_REFERENCE_SDK_KB_ID. So list the labels your search actually returned, then act on those, rather than pattern-matching the name or hard-coding a list of ids.

# 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. Browse the docs tree as a menu. Two ways: the structured browse endpoint for the supported portals (preferred there — typed, counted, filterable), and the .md menu tree for any surface and for reading pages.

B1. Structured browse — the supported portals. POST /mcp-docs-search/v1/docs/menu/browse walks a portal's tree and returns each child with its kind, its HTTP verb (for methods), and subtree counts ("Catalog V3 — 121 methods, 32 articles"), so you pick the right area by shape — in ~2 KB, not a ~40 KB menu page you have to grep. include, name_filter, and depth jump straight to what you want.

Portals (document_type): REST (default — the api-reference portal) · FRONTEND_SDK (sdk) · CLI (wix-cli) · BUILD_APPS (build-apps) · WIX_HEADLESS (go-headless). In browse only, SDK is an alias for REST (the API reference documents both views on every page) — it does not select FRONTEND_SDK, and the alias doesn't apply to semantic search. To discover a portal's areas, omit menu_url — you get the portal root; passing a supported portal's URL as menu_url also infers the portal for you.

Body: menu_url? (absolute docs URL; omit for the portal root), document_type?, depth? (1, max 6), include? (CATEGORY·RESOURCE·METHOD·ARTICLE·WEBHOOK·OBJECT·SKILL), deprecated? (HIDE default·SHOW·ONLY), name_filter?, max_nodes?, format? (MARKDOWN default → content string; STRUCTURED → JSON tree with url/http_method/resource_id/child_counts, plus counts_by_type, truncated, deprecated_counts_by_type).

Two response signals to act on, not ignore:

• truncated: true — the node cap cut the listing. Narrow instead of re-reading: browse a deeper menu_url, tighten include/name_filter, or lower depth.
• Deprecation filtering — deprecated entries are hidden by default; deprecated_counts_by_type reports how many were filtered out. An API missing from a browse may be deprecated, not nonexistent — re-browse with deprecated: "SHOW" (or "ONLY") to inspect it, and follow its replacement pointer where one is documented.

# 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'

Browse-only: it hands you the page URL — read it by appending .md (§2), and get the exact schema from §C.

B2. .md menu tree — any surface, and how you read pages. Every docs path has a .md twin, so you can navigate any surface with zero dependencies; use it for surfaces structured browse doesn't cover (e.g. Velo) and to read leaves. curl https://dev.wix.com/docs/llms.txt is the top-level map; the portals under it:

Drill like a menu — append .md to any path (a section → a menu of child links, a leaf → the content/method page); truncate to go up, extend to go down. Read the sibling intro / "About …" / flow articles too, not just the method page. Example — drill to the create-booking method, grepping each menu for the next link:

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

A 2-level map of the API-reference portal (all verticals, one level down) is in references/EXTRACTING.md.

C. Query the API index — one call, structured. The code-mode search endpoint runs a JS function over lightIndex (the whole REST API spec: every resource + method with operationId, httpMethod, menuPath, docsUrl, and executable publicUrl). Best when you want to enumerate/filter methods programmatically — browse a vertical, or grep across all methods — and get the docsUrl + publicUrl back in one shot, no menu-drilling:

# 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})); }"}'

Filter narrowly and return only the fields you need — the index is large, so an unfiltered dump is huge. Scope: the REST surface. lightIndex indexes REST methods; a sibling articles index plus getArticleContentByUrl(docsUrl) / getArticleContent(resourceId) cover the REST portal's prose (introductions, recipes, flow pages). SDK-only surfaces and the other portals aren't here — use A/B for those, and note the schemas returned are REST contracts, not SDK signatures (the SDK view of the same method lives on its docs page, §2). More examples (browse a vertical, menuPath walk, resource schema) and the schema/article readers → references/API_SPEC_SEARCH.md.

If the Wix MCP is present, it exposes these same capabilities as native tools (no curl/JSON boilerplate) — Lane 2.

2. Read what you land on

Appending .md to a URL gives one of three kinds of page. Know which you're looking at, and handle it accordingly:

• Menu page — a section path (from browsing, §1B). A list of child links, often tens of KB — don't read it whole; grep it for the child you want, then drill into that page:

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

• Article / guide — introductions, concepts, sample-flow pages. Prose markdown, usually small — read it whole:

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

• Method page — one API method, and the heavy one: it carries both a REST and a JavaScript SDK section, the full request/response schema, and code examples — often 100 KB+. Don't swallow the whole page — map it, then pull the part you need (the examples are usually enough to model a call):

  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
  

  More recipes (split REST vs SDK, resolve an enum) → references/EXTRACTING.md.

  For the exact structured schema and enum values, don't hand-slice the markdown — query the API spec with a curl POST to https://mcp.wix.com/api/code-mode/search (the no-MCP equivalent of the MCP SearchWixAPISpec). The code is a JS function with lightIndex and getResourceSchemaByUrl(docsUrl) in scope; return only what you need.

  getResourceSchemaByUrl scopes to the URL you pass: a method URL returns a schema whose methods array holds just that method — read it as methods[0], and don't select it by comparing m.docsUrl to your input (the reader normalizes URLs). A resource URL (the method URL minus its last segment) returns the whole resource — fetch that when you need sibling operations or shared resource context.

  # 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 }; }"}'
  

  The envelope is { "result": … } or { "error": "<message>" } — both arrive as HTTP 200, so check the body, not the status. The error text names the fix: an article URL → switch to getArticleContentByUrl; an unknown URL → search lightIndex by keyword. Don't re-send an identical failed lookup — change something based on the error, and if discovery still fails, report the limitation instead of guessing the contract.

  Full example set (resource listing, partial-URL resolution, enum/nested-ref expansion) → references/API_SPEC_SEARCH.md.

Lane 2 — Wix MCP doc tools (only if your agent has them)

If the Wix MCP is connected, these are the same backends as Lane 1 (the doc-search service and the API-spec index) wrapped as native tools — schema-validated, response-size handled, no curl/JSON boilerplate. A convenience over the curl lane, not a richer data source; use them when present, fall back to Lane 1 when not. Optional — skip this lane if the tools aren't present.

• Fetch the method for its contract; fetch the resource for context. A method URL gives exactly that method. When a requirement may live on a sibling method (e.g. a memberId required on single-create but omitted from the bulk-create page), fetch the resource URL instead — the resource view carries every method plus the shared object schema.
• The recipe-first routing at the top of this skill applies here too: for a multi-step workflow, search the recipe corpus (many verticals publish recipes under a …/business-solutions/<vertical>/skills node) before assembling per-method calls.

The .md suffix

Append .md only when curl-ing a page directly. The MCP tools and the search endpoint take the plain docs URL without .md — never feed a .md URL to an MCP tool.

From docs to calls

Understanding the contract is this skill's job; executing it needs an identity. Which identities a method accepts is part of what you read — check the method page's permissions and identity notes before calling, and confirm your token's site/account scope matches. Token minting (CLI admin tokens, visitor tokens), the identity model, and the dynamic site-context report → references/CALLING.md.

Before you write the code

Confirm on the page — not from memory — the endpoint, the HTTP verb, the request body shape, required fields, and any enum values. Then write the call. If you're extending a skill's shipped client, keep the skill's existing transport/helper style; you're adding one call, not re-architecting.