Search and inspect the Wix REST API documentation/spec by writing JavaScript code that runs in a sandboxed read-only environment.
This tool overlaps with `SearchWixRESTDocumentation`, `BrowseWixRESTDocsMenu`, `ReadFullDocsArticle`, and `ReadFullDocsMethodSchema`: use any of them to discover Wix REST endpoints, schemas, examples, and related docs. Prefer `SearchWixAPISpec` over `ReadFullDocsMethodSchema` for REST method schemas when it is available, especially after you already have a docs URL from semantic search, menu browsing, or conversation context.
Prefer URL-first results:
- If you have a docs URL or partial docs URL, search `resource.docsUrl` and `method.docsUrl` first.
- If you have a method docs URL and need the request/response shape, call `getResourceSchemaByUrl(methodDocsUrl)` in this tool and return the selected method schema directly.
- For API execution, return and use `method.publicUrl` when available. It is the preferred executable `https://www.wixapis.com/...` URL.
- Return `docsUrl` for relevant resources/methods when the next step needs an article or API call source URL; do not hand off to `ReadFullDocsMethodSchema` just to inspect a REST method schema.
- Use `resourceId` only as the internal handle for low-level loaders; prefer URL helpers when you have a docs URL.
- `getResourceSchemaByUrl` resolves only **API resource/method** docs (e.g. `.../bookings/services/services-v2/create-service`). It does NOT work on **skill** pages (`.../skills/...`) or **article** pages — those have no schema. For an article, use `getArticleContentByUrl(docsUrl)`. Never pass a `.../skills/...` URL (skill recipes often cross-link sibling skill pages) — search `lightIndex` by keyword/operationId for the real API method instead. If a lookup misses, don't retry the same URL; search by keyword.
Your code has access to these globals:
**lightIndex** — Current lightweight REST API resource array:
```typescript
interface LightIndex extends Array<LightResource> {
updatedAt?: string; // ISO timestamp for when spec sync generated this index
}
interface LightResource {
name: string; // e.g. "Products V3", "Contact V4"
resourceId: string; // internal handle for getResourceSchema()
docsUrl: string; // e.g. "https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3"
menuPath: string[]; // e.g. ["business-solutions", "stores", "catalog-v3", "products-v3"]
methods: Array<{
operationId: string; // e.g. "wix.stores.catalog.v3.CatalogApi.CreateProduct"
summary: string; // e.g. "Create Product"
httpMethod: string; // "get" | "post" | "patch" | "delete"
path: string; // e.g. "/v3/products"
docsUrl?: string; // e.g. "https://dev.wix.com/docs/api-reference/.../query-products"
publicUrl?: string; // preferred executable URL for ExecuteWixAPI, when available after spec sync
publicBaseUrl?: string;
description: string; // truncated to 200 chars
}>;
}
```
**getResourceSchemaByUrl(docsUrl)** and **getResourceSchema(resourceId)** return the full schema for a resource:
```typescript
interface FullSchema {
title: string;
description: string;
fqdn: string;
docsUrl?: string;
methods: Array<{
summary: string;
description: string;
operationId: string;
httpMethod: string;
path: string;
docsUrl?: string;
publicUrl?: string; // Preferred executable URL for ExecuteWixAPI, e.g. "https://www.wixapis.com/..."
publicBaseUrl?: string; // Public Wix APIs base URL used to derive publicUrl
servers: Array<{ url: string }>; // Base URLs (e.g. "https://www.wixapis.com/...")
requestBody: object | null;
responses: object;
parameters: Array<object>;
permissions: string[];
legacyExamples: Array<{ // Curl examples
content: { title: string; request: string; response: string };
}>;
}>;
components: { schemas: object };
}
```
**articles** — Array of all Wix documentation articles (~1000 guides, tutorials, concepts):
```typescript
interface LightArticle {
name: string; // e.g. "About the Wix API Query Language"
resourceId: string;
docsUrl: string; // e.g. "https://dev.wix.com/docs/api-reference/articles/..."
menuPath: string[]; // e.g. ["work-with-wix-apis", "data-retrieval", "about-the-wix-api-query-language"]
description: string; // first ~200 chars of the article content
}
```
**getResourceSchemaByUrl(docsUrl)** — Async function returning the full schema for the resource or method docs URL.
**getResourceSchema(resourceId)** — Lower-level async function returning the full schema for a resource ID. Prefer `getResourceSchemaByUrl(docsUrl)` when you have a docs URL.
**getArticleContentByUrl(docsUrl)** — Async function returning the full markdown content of an article docs URL (string).
**getArticleContent(resourceId)** — Lower-level async function returning the full markdown content of an article resource ID. Prefer `getArticleContentByUrl(docsUrl)` when you have a docs URL.
Articles and API resources share the same menuPath hierarchy. Use menuPath to find related articles and APIs within the same domain.
Your code MUST be an `async function()` expression that returns a value.
app-management [14 resources]: app-billing, oauth-2, app-instance, app-permissions, bi-event, embedded-scripts, site-plugins, market-listing, app-installations, app-extensions
business-solutions [157 resources]: e-commerce, stores, bookings, meetings, cms, events, restaurants, blog, forum, pricing-plans, portfolio, benefit-programs, donations, suppliers-hub, gift-cards, coupons
assets [4 resources]: media, rich-content, pro-gallery
crm [58 resources]: members-contacts, forms, community, communication, loyalty-program, crm
business-management [112 resources]: ai-site-chat, analytics, app-installation, async-job, automations, calendar, captcha, cookie-consent-policy, custom-embeds, branches, faq-app, dashboard, functions, data-extension-schema, get-paid, headless, locations, marketing, multilingual, notifications, payments, online-programs, site-search, secrets, site-urls, site-properties, tags
account-level [21 resources]: sites, domains, b2b-site-management, resellers, studio-workspace, user-management, ai-credits
tools [1 resources]: semantic-search
site [2 resources]: viewer
Important schema guidance:
- For ExecuteWixAPI, ALWAYS use `method.publicUrl`. It is the complete, executable `https://www.wixapis.com/...` URL for that method. When `publicUrl` is present, never build the execution URL by hand and never expose any other field as "the endpoint".
- Do not use `method.servers[0]` to build execution URLs. `method.servers` includes internal Wix hosts such as `www.wix.com`, `manage.wix.com`, and editor hosts.
- `method.path` is a PARTIAL, relative path (e.g. `/v2/coupons/query`). It OMITS the gateway prefix that the real URL requires: many APIs are served under a prefix such as `/stores` or `/ecom` (for example, `path` `/v2/coupons/query` is actually served at `https://www.wixapis.com/stores/v2/coupons/query`). Prepending `https://www.wixapis.com` to `method.path` will 404 for these APIs. Treat `method.path` as a matching/debugging key only — never as an execution URL, and never surface it as the endpoint of a method.
- If — and only if — `publicUrl` is absent and you must construct the URL: recover the gateway prefix from `method.publicBaseUrl` (it is the segment(s) before the API version, e.g. `https://www.wixapis.com/stores/v2/coupons` → prefix `/stores`) and build `https://www.wixapis.com` + prefix + `method.path`. Do NOT simply concatenate `publicBaseUrl` + `path`; they overlap on the version/resource segments and would duplicate them.
- Do not exact-match full Wix API URLs against `method.path`.
- Search docs URLs first when you have them. Search broadly across `resource.name`, `resource.docsUrl`, `resource.menuPath.join("/")`, `method.summary`, `method.operationId`, `method.description`, `method.path`, and `method.docsUrl` only when you still need discovery.
- Schemas use `{ "$circular": "TypeName" }` to reference a type defined in `schema.components.schemas`. The marker appears both in method bodies and *inside dictionary entries themselves*, so a looked-up type's nested fields may contain further `$circular` refs. The dictionary is complete — every `$circular` name resolves — so expand **as much or as little as you need**, not the whole schema:
- Partial / targeted: look up only the specific types on the path you care about, e.g. `schema.components.schemas["…SeoSchema"]` then its `settings` type `schema.components.schemas["…SeoSchema.Settings"]` (see the "Expand selected nested schema refs" example).
- Subsequent: it's fine to resolve a `$circular` type in a follow-up `SearchWixAPISpec` call rather than all at once.
- Recursive: expand an entire subtree when you really need it (see the `expandRefs` example), but keep depth small and avoid dumping huge fully-expanded schemas.
- When inspecting a specific method schema (i.e. you have found a single method and are returning its details), always include `responses: method.responses` alongside `requestBody`. Knowing the response shape up front prevents speculative re-runs of mutations just to see what the API returned.
- For query/search methods, `method.queryMethodData.queryFieldsCapabilitiesMap` lists exactly which fields are filterable (their allowed `operators`) and sortable (`sort`). Only filter or sort by fields present in that map; a field that is absent (e.g. `name` on Catalog V3 products) is rejected with `is not declared as filterable` — filter those client-side after fetching a bounded page.
Examples:
Inspect one method schema by exact docs URL:
```javascript
async function() {
const methodUrl = "https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/query-products";
const schema = await getResourceSchemaByUrl(methodUrl);
const method = schema.methods.find(method => method.docsUrl === methodUrl);
if (!method) {
return {
message: "Found the resource, but no exact method URL match. Returning available methods.",
resourceDocsUrl: schema.docsUrl,
methods: schema.methods.map(method => ({
title: method.summary,
docsUrl: method.docsUrl,
httpMethod: method.httpMethod.toUpperCase(),
publicUrl: method.publicUrl
}))
};
}
return {
title: method.summary,
docsUrl: method.docsUrl,
resourceDocsUrl: schema.docsUrl,
publicUrl: method.publicUrl,
publicBaseUrl: method.publicBaseUrl,
httpMethod: method.httpMethod.toUpperCase(),
operationId: method.operationId,
permissions: method.permissions,
parameters: method.parameters,
requestBody: method.requestBody,
responses: method.responses,
// For query/search methods: which fields are filterable (allowed operators) and sortable.
queryFieldsCapabilities: method.queryMethodData?.queryFieldsCapabilitiesMap,
curlExamples: method.legacyExamples?.map(example => example.content)
};
}
```
Inspect one resource by resource docs URL:
```javascript
async function() {
const resourceUrl = "https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3";
const schema = await getResourceSchemaByUrl(resourceUrl);
return {
resource: schema.title,
docsUrl: schema.docsUrl,
description: schema.description,
methods: schema.methods.map(method => ({
title: method.summary,
docsUrl: method.docsUrl,
httpMethod: method.httpMethod.toUpperCase(),
publicUrl: method.publicUrl,
operationId: method.operationId
}))
};
}
```
Inspect one method from a partial docs URL:
```javascript
async function() {
const partialUrl = "stores/catalog-v3/products-v3/query-products";
const resource = lightIndex.find(resource =>
resource.docsUrl.includes(partialUrl) ||
resource.methods.some(method => method.docsUrl?.includes(partialUrl))
);
if (!resource) return "No API resource found for this partial docs URL";
const schema = await getResourceSchemaByUrl(
resource.methods.find(method => method.docsUrl?.includes(partialUrl))?.docsUrl ??
resource.docsUrl
);
const method = schema.methods.find(method =>
method.docsUrl?.includes(partialUrl)
);
if (!method) {
return {
message: "Found the resource, but no exact method match.",
resource: resource.name,
resourceDocsUrl: resource.docsUrl,
methods: schema.methods.map(method => ({
title: method.summary,
docsUrl: method.docsUrl,
httpMethod: method.httpMethod.toUpperCase(),
publicUrl: method.publicUrl
}))
};
}
return {
title: method.summary,
docsUrl: method.docsUrl,
resource: resource.name,
resourceDocsUrl: resource.docsUrl,
httpMethod: method.httpMethod.toUpperCase(),
publicUrl: method.publicUrl,
publicBaseUrl: method.publicBaseUrl,
requestBody: method.requestBody,
responses: method.responses,
curlExamples: method.legacyExamples?.map(example => example.content)
};
}
```
Expand selected nested schema refs:
```javascript
async function() {
const methodUrl = "https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/query-products";
const schema = await getResourceSchemaByUrl(methodUrl);
const method = schema.methods.find(method => method.docsUrl === methodUrl);
return {
title: method.summary,
docsUrl: method.docsUrl,
requestBody: method.requestBody,
selectedNestedTypes: {
product: schema.components.schemas["com.wix.stores.catalog.product.api.v3.Product"],
cursorPaging: schema.components.schemas["wix.stores.catalog.v3.upstream.wix.common.CursorPaging"],
sorting: schema.components.schemas["wix.stores.catalog.v3.upstream.wix.common.Sorting"]
}
};
}
```
Advanced: bounded recursive expansion for one method. Use only when top-level schema and selected nested refs are not enough; keep depth small because schemas can become very large.
```javascript
async function() {
const methodUrl = "https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/query-products";
const schema = await getResourceSchemaByUrl(methodUrl);
const method = schema.methods.find(method => method.docsUrl === methodUrl);
function expandRefs(value, depth = 0, seen = []) {
if (depth > 3) return value;
if (Array.isArray(value)) return value.map(item => expandRefs(item, depth, seen));
if (!value || typeof value !== "object") return value;
if (value.$circular) {
const refName = value.$circular;
if (seen.includes(refName)) return { $ref: refName, circular: true };
const target = schema.components?.schemas?.[refName];
if (!target) return { $ref: refName, missing: true };
return {
$ref: refName,
schema: expandRefs(target, depth + 1, seen.concat(refName))
};
}
return Object.fromEntries(
Object.entries(value).map(([key, nested]) => [
key,
expandRefs(nested, depth, seen)
])
);
}
return {
title: method.summary,
docsUrl: method.docsUrl,
httpMethod: method.httpMethod.toUpperCase(),
publicUrl: method.publicUrl,
requestBody: expandRefs(method.requestBody),
responses: expandRefs(method.responses)
};
}
```
Find APIs by broad keywords when you do not have a docs URL:
```javascript
async function() {
const words = ["stores", "query", "products"];
return lightIndex.flatMap(resource =>
resource.methods
.filter(method => {
const haystack = [
resource.name,
resource.docsUrl,
resource.menuPath.join("/"),
method.summary,
method.operationId,
method.description,
method.path,
method.docsUrl
].join(" ").toLowerCase();
return words.every(word => haystack.includes(word));
})
.map(method => ({
title: method.summary,
docsUrl: method.docsUrl,
resource: resource.name,
resourceDocsUrl: resource.docsUrl,
resourceId: resource.resourceId,
operationId: method.operationId,
httpMethod: method.httpMethod.toUpperCase(),
publicUrl: method.publicUrl
}))
);
}
```
