Execute JavaScript code against the Wix REST API.
CRITICAL CODE SHAPE:
- The `code` parameter MUST be the function expression itself: `async function() { ... }` or `async () => { ... }`.
- Do NOT send a script body like `const result = await ...; return result;`.
- Do NOT call the function yourself. The tool calls it for you.
- Put all `const`, `await`, and `return` statements inside the function body.
MULTI-SITE (read this first):
- If the task spans several sites — "all my sites", "each of my sites", "every site", or a given list of sites — you MUST handle them in ONE `ExecuteWixAPI` call. Inside that single function, loop over the site IDs and fan out with `Promise.allSettled`, passing a per-request `siteId` to each `wix.request({ scope: "site", siteId, method, url, body })`.
- Do NOT make a separate `ExecuteWixAPI` call per site. One call handles all of them; the runtime obtains the correct token for each `siteId` automatically.
- You already have the site IDs from `ListWixSites`; pass that array into the function, or list the sites with a single account-scope Sites API call inside the function. See the "multi-site" example below.
Do not rely on memory for Wix API endpoints, methods, schemas, or request bodies. Before writing code, use SearchWixAPISpec or the search, browse, read-docs, and schema tools to confirm the exact API URL, HTTP method, request body structure, schema field names, required fields, enum values, and auth context. Before accessing fields on a response object, know the exact shape — don't guess paths like `result.id` when the actual path might be `result.results[0].item.id`. When you fetch the method schema for the request body, include `responses: method.responses` at the same time — it costs nothing and tells you exactly what fields come back. When SearchWixAPISpec returns a method schema, use `method.publicUrl` for ExecuteWixAPI when available; do not use `method.servers[0]`, which may be an internal Wix host. Pass the docs article, recipe, or schema URLs you used in the `sourceDocUrls` parameter. Then write code using wix.request(). Auth is handled automatically — do NOT set Authorization, wix-site-id, or wix-account-id headers.
This tool overlaps with `CallWixSiteAPI` and `ManageWixSite`: all can call Wix REST APIs. Use `ExecuteWixAPI` when code helps express the task: repeating one API call in a loop, paginating through results, transforming data between calls, branching on API responses, or chaining several related API calls in one operation.
Probing is useful when it is read-only: use GET/query/list/search calls to inspect existing state, resolve real IDs, confirm response shapes, or verify a previous write. For create/update/delete calls, search docs, read docs, and inspect schemas first; call the mutation only with real resolved inputs, and avoid using placeholder IDs or speculative mutation calls just to discover validation behavior or response shape. If a mutation succeeds but you need more details, use the returned data or follow up with a read-only GET/query; do not repeat the mutation only to get a different response shape.
Use `wix.request({ method, url, body })` for API calls. Scope defaults to `"site"` when the ExecuteWixAPI `siteId` parameter is passed, otherwise `"account"`. Set `scope: "site"` explicitly for site-level APIs, which is the common case for business domains such as Stores, Bookings, CRM, Forms, CMS, Events, and Blog. Set `scope: "account"` explicitly for account-level APIs such as Sites, Site Folders, Domains, and User Management, or when the docs/schema indicate account-level auth.
For MULTIPLE sites, do everything in a single `ExecuteWixAPI` call — never one call per site. Map over the site IDs and fan out with `Promise.allSettled`, passing a per-request `siteId` to each `wix.request({ scope: "site", siteId, method, url, body })`; the runtime resolves the correct token for each site automatically (do not set auth headers). For a SINGLE site you may instead pass the site ID in the tool-level `siteId` parameter, which becomes the default for any site-level `wix.request()` that omits its own `siteId`. Typical multi-site flow: take the site IDs you already have from `ListWixSites` (or list them with one account-scope Sites API call inside the function), then map over them. Since a mutation fans out to every site you target, be deliberate about which sites you include and return exactly which succeeded and which failed.
Error handling: `wix.request()` throws when the Wix API returns an error. If calls depend on each other, let the error throw so the tool reports a clear failure. For independent read-only probes, you may wrap each call in `try/catch` and return structured partial results such as `{ ok: false, error }`. When running independent calls in parallel, use `Promise.allSettled` rather than `Promise.all` so that a single failure does not discard the other results. For mutations, avoid swallowing errors unless you also return exactly which writes succeeded and which failed.
Available in your code:
```typescript
interface WixRequestOptions {
scope?: "site" | "account"; // Defaults to "site" when a siteId is available, otherwise "account"
siteId?: string; // Per-request target site for multi-site calls; defaults to the tool-level siteId
method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
url: string; // Prefer method.publicUrl from SearchWixAPISpec, e.g. "https://www.wixapis.com/stores/v1/products/query"; paths like "/stores/v1/products/query" are resolved against https://www.wixapis.com
body?: unknown;
headers?: Record<string, string>; // Do NOT set Authorization, wix-site-id, or wix-account-id
}
interface WixResponse<T = unknown> {
status: number;
data: T;
json(): Promise<T>; // Fetch-compatible alias for data
}
declare const wix: {
request<T = unknown>(options: WixRequestOptions): Promise<WixResponse<T>>;
};
declare const siteId: string | undefined; // Tool-level siteId passed to ExecuteWixAPI, if any.
```
Your code MUST be an async function expression that returns the result:
```javascript
async () => {
const response = await wix.request({
method: "GET",
url: "https://www.wixapis.com/<account-level-endpoint>"
});
return response.data;
}
```
The response is available as `response.data`. For compatibility with fetch-style code, `await response.json()` returns the same data. Return compact, task-focused data instead of raw API responses. For list/query/search endpoints, especially "list all" tasks or APIs that may return many items, paginate in code and map each item to the fields needed for the task. Include IDs, metadata, nested fields, or raw response fragments when they are needed to complete the task, disambiguate entities, verify mutations, or answer the user. If the user asks for names and types, return only names and types. For hundreds of items, avoid verbose JSON objects because repeated keys waste tokens; return compact strings such as `"Name - TYPE"` joined with newlines, or small tuples such as `["Name", "TYPE"]`. If the user asks for a specific output value, include that value explicitly in the returned object so the final answer can report it. If you need to filter by a field, verify the endpoint supports that filter in the method docs/schema or related "Supported Filters and Sorting" docs; otherwise retrieve a bounded page and filter in JavaScript. When looking up an item by user-provided name, paginate/search until you find an exact name match; never update or delete the first result unless it exactly matches.
Example — MULTIPLE sites in ONE call: same query across every site, in parallel, compact per-site output. This is the required shape for "all my sites" / "each site" tasks — do NOT call ExecuteWixAPI once per site:
```javascript
async function() {
// 1) List the account's sites (account scope) — or pass in IDs you already have from ListWixSites.
const sitesRes = await wix.request({
scope: "account",
method: "POST",
url: "https://www.wixapis.com/site-list/v2/sites/query",
body: { query: { cursorPaging: { limit: 100 } } }
});
const sites = sitesRes.data.sites ?? [];
// 2) Fan out one site-scoped request per site with a per-request siteId — all in this single call.
const results = await Promise.allSettled(
sites.map(site =>
wix.request({
scope: "site",
siteId: site.id,
method: "POST",
url: "https://www.wixapis.com/<site-analytics-endpoint>",
body: { /* ... */ }
}).then(r => ({ siteId: site.id, name: site.displayName, data: r.data }))
)
);
// 3) Return a compact per-site summary — not raw payloads (avoid truncation).
return results.map((r, i) =>
r.status === "fulfilled"
? { site: r.value.name, ok: true, value: r.value.data }
: { site: sites[i].displayName, ok: false, error: String(r.reason) }
);
}
```
Example — site-level request with compact output:
```javascript
async function() {
const response = await wix.request({
method: "POST",
url: "https://www.wixapis.com/<site-level-endpoint>",
body: {
query: {
cursorPaging: { limit: 100 }
}
}
});
const items = response.data.items ?? response.data.results ?? [];
return {
count: items.length,
items: items.map(item => item.name + " - " + item.type).join("\
")
};
}
```
Example — account-level request:
```javascript
async function() {
const response = await wix.request({
scope: "account",
method: "POST",
url: "https://www.wixapis.com/<account-level-endpoint>",
body: {
query: {
cursorPaging: { limit: 50 }
}
}
});
return response.data;
}
```
Example — parallel independent read-only probes with partial results:
```javascript
async function() {
const [productsResult, collectionsResult] = await Promise.allSettled([
wix.request({
scope: "site",
method: "POST",
url: "https://www.wixapis.com/<products-query-endpoint>",
body: { query: { cursorPaging: { limit: 10 } } }
}),
wix.request({
scope: "site",
method: "POST",
url: "https://www.wixapis.com/<collections-query-endpoint>",
body: { query: { cursorPaging: { limit: 10 } } }
})
]);
return {
products: productsResult.status === "fulfilled"
? { ok: true, count: (productsResult.value.data.items ?? productsResult.value.data.products ?? []).length }
: { ok: false, error: String(productsResult.reason) },
collections: collectionsResult.status === "fulfilled"
? { ok: true, count: (collectionsResult.value.data.items ?? collectionsResult.value.data.collections ?? []).length }
: { ok: false, error: String(collectionsResult.reason) }
};
}
```
Example — chain related mutation calls and fail fast on API errors:
```javascript
async function() {
const list = await wix.request({
scope: "site",
method: "POST",
url: "https://www.wixapis.com/<query-endpoint>",
body: { query: { cursorPaging: { limit: 20 } } }
});
const items = list.data.items ?? [];
const match = items.find(item => item.name === "Target name");
if (!match) {
return { error: "NOT_FOUND", available: items.map(item => ({ id: item.id, name: item.name })) };
}
const updated = await wix.request({
scope: "site",
method: "PATCH",
url: `https://www.wixapis.com/<update-endpoint>/${match.id}`,
body: {
item: {
id: match.id,
revision: match.revision,
name: "Updated name"
}
}
});
return {
id: updated.data.item?.id,
name: updated.data.item?.name,
revision: updated.data.item?.revision
};
}
```