@wix/agent-skills 1.31.1 → 1.32.0

package/skills/wix-manage/references/forms/read-forms-and-submissions.md

@@ -0,0 +1,277 @@
+---
+name: "Read Forms and Submissions"
+description: "Reads a site's Wix forms and the submissions visitors sent to them — what forms do I have, find a form by name, show the latest submissions, who filled in my contact form, how many submissions did I get last week, submissions from one contact, unread submissions. Covers finding the form's namespace instead of guessing it, where that namespace goes on each read, the Form Schemas and Form Submissions endpoints (and the look-alike URLs that 404), forms hidden from a default listing, the closed list of submission fields you can filter and sort by, date ranges, cursor paging, totals per form, and reading answers by field. Read-only; changing a form is Update Form, building one is Create Form."
+---
+# RECIPE: Read Wix Forms and Their Submissions
+
+> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Body-bearing requests also need `Content-Type: application/json`. Send `wix-site-id: <SITE_ID>` when the token is account-scoped.
+
+> These calls need the Wix Forms app on the site (`appDefId` `225dd912-7dea-4738-8688-4b8c6955ffc2`); a `428`, a `400` naming the app, or an empty result on a site that should have content means it is not there. [List Installed Apps](../app-installation/list-installed-apps.md) shows what the site has; [Install Wix Apps](../app-installation/install-wix-apps.md) adds it by that id.
+
+List a site's forms, find one, and read the submissions sent to it. The usual order is **find the form first, then query its submissions by `formId`**. Every call here is a read — nothing on the site changes, so no confirmation is needed.
+
+---
+
+## STEP 1 · Know the namespace — never guess it
+
+Every form and every submission belongs to one **namespace**: the app that owns the form. Every read except Get Form and Get Submission needs it.
+
+| App that owns the form | Namespace |
+|---|---|
+| Wix Forms (the forms on the site's **Forms** dashboard) | `wix.form_app.form` |
+| Wix Bookings | `wix.bookings.v2.bookings` |
+| Wix Pricing Plans | `wix.pricing_plans.v1.custom_form` |
+| Wix eCom checkout | `wix.ecom.v1.checkout` |
+| Wix Quizzes | `wix.achievements.quizzes.v1.quiz` |
+| Wix Contacts | `wix.contacts.v4.contact` |
+
+The source is [Namespaces of apps made by Wix](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/introduction#namespaces-of-apps-made-by-wix).
+
+- **"My forms", "my contact form", "form submissions"** with no app named → `wix.form_app.form`.
+- **You already hold a form** → use its `namespace` field.
+- **`Permissions for given namespace not found: <namespace>`** → that app is not installed on the site. **Stop.** Check the site's apps with [List Installed Apps](../app-installation/list-installed-apps.md) and tell the user the app is missing. Do not try other namespaces (`wix.old_form_app.form`, `wix.forms`, …): none of them exist, and each one only costs another failed call.
+- **List Forms returns `"forms": []`** for a namespace → it means *no forms there*, or *the wrong namespace*. It does not error on a namespace the site lacks.
+
+---
+
+## STEP 2 · Pick the call
+
+| Task | Request | Where the namespace goes |
+|---|---|---|
+| List forms | `GET https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form` | query parameter `namespace` (required) |
+| Query forms (by name, date) | `POST https://www.wixapis.com/form-schema-service/v4/forms/query` | inside the filter: `"namespace": {"$eq": "wix.form_app.form"}` |
+| Get one form | `GET https://www.wixapis.com/form-schema-service/v4/forms/{formId}` | not needed |
+| Query submissions | `POST https://www.wixapis.com/form-submission-service/v4/submissions/namespace/query` | inside the filter: `"namespace": "wix.form_app.form"` |
+| Get one submission | `GET https://www.wixapis.com/form-submission-service/v4/submissions/{submissionId}` | not needed |
+| Count submissions per form | `POST https://www.wixapis.com/form-submission-service/v4/submissions/count` | body field `namespace` |
+
+**⚠️ These look-alike URLs do not exist and return a bare `404`:**
+
+- `/forms/v4/forms`, `/forms/v4/forms/query`, `/forms/v4/forms/{formId}` — forms live under **`/form-schema-service/v4/`**.
+- `/form-schema-service/v4/submissions/...` and `/form-submission-service/v4/forms` — submissions live under **`/form-submission-service/v4/submissions/`**, forms don't.
+
+**Use `.../submissions/namespace/query` for every submissions query.** It is the only submissions query the docs list. Don't drop `namespace` from the path.
+
+`https://www.wixapis.com/forms/v4/submissions/...` (the `publicUrl` the API spec gives for the submission methods) is the same API under another path, and works too. The `/forms/v4/` alias exists for submissions only: `/forms/v4/forms` still 404s.
+
+---
+
+## STEP 3 · List or find the forms
+
+### List every form
+
+```bash
+# enabled forms (the default)
+curl -X GET \
+  'https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form&fieldsets=METADATA&paging.limit=100' \
+  -H 'Authorization: <AUTH>'
+
+# disabled forms — a second call, always
+curl -X GET \
+  'https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form&enabled=false&fieldsets=METADATA&paging.limit=100' \
+  -H 'Authorization: <AUTH>'
+```
+
+- **⚠️ `enabled` defaults to `true`, and no value returns both.** One call hides every disabled form. With List Forms, make both calls and report both lists, marking the disabled ones. Or use Query Forms with only the namespace filter (below): it returns enabled and disabled forms in one call.
+- **`fieldsets=METADATA`** returns only the top-level properties (`id`, `name`, `enabled`, dates, `namespace`) and leaves out fields, steps and rules. Use it whenever you only need names and IDs. Omit it when you need the fields (to read submission answers, see STEP 5).
+- Response: `forms[]` and **`pagingMetadata`**. When `pagingMetadata.hasNext` is `true`, call again with `paging.cursor=<pagingMetadata.cursors.next>`.
+- To read specific forms, add `formIds=<id>` (repeat the parameter for each ID).
+
+### Find a form by name or date
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/form-schema-service/v4/forms/query' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  -d '{
+    "query": {
+      "filter": {
+        "namespace": { "$eq": "wix.form_app.form" },
+        "name": { "$startsWith": "Contact" }
+      },
+      "sort": [{ "fieldName": "createdDate", "order": "DESC" }],
+      "cursorPaging": { "limit": 50 }
+    }
+  }'
+```
+
+- Filter and sort fields: `id`, `namespace` (`$eq` only), `name` (`$eq`, `$ne`, `$in`, `$nin`, `$startsWith`), `enabled` (`$eq`, `$ne`), `createdDate` and `updatedDate` (`$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`). Date operators are `$gte` / `$lte`. **`$ge` / `$le` are rejected.** A range needs one condition per operator under `$and`, exactly as for submissions in STEP 4.
+- Query Forms returns enabled and disabled forms together, unless you filter on `enabled`.
+- Response: `forms[]` and **`metadata`** (not `pagingMetadata`). For the next page, see [Paging](#paging).
+
+### Read one form
+
+```bash
+curl -X GET \
+  'https://www.wixapis.com/form-schema-service/v4/forms/{formId}' \
+  -H 'Authorization: <AUTH>'
+```
+
+Returns `form`, with `formFields` (each input field's `inputOptions.target` is the key its answers are stored under) and `namespace`.
+
+---
+
+## STEP 4 · Query the submissions
+
+### The latest submissions to one form
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/form-submission-service/v4/submissions/namespace/query' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  -d '{
+    "query": {
+      "filter": {
+        "namespace": "wix.form_app.form",
+        "formId": "<formId>"
+      },
+      "sort": [{ "fieldName": "createdDate", "order": "DESC" }],
+      "cursorPaging": { "limit": 20 }
+    }
+  }'
+```
+
+- **⚠️ `namespace` goes inside `query.filter`.** A top-level `"namespace"` beside `query` doesn't count: the call fails with `namespace filter is required`.
+- Leave out `formId` to read submissions across every form in the namespace.
+- Response: `submissions[]` and **`metadata`** (`count`, `hasNext`, `cursors.next`). Each submission has `id`, `formId`, `status`, `seen`, `contactId` (when linked to a contact), `submitter`, `createdDate`, and `submissions` (the answers, see STEP 5).
+
+### Read one submission
+
+When you already hold a submission ID, read it directly. No namespace is needed:
+
+```bash
+curl -X GET \
+  'https://www.wixapis.com/form-submission-service/v4/submissions/{submissionId}' \
+  -H 'Authorization: <AUTH>'
+```
+
+Returns `submission`, with the same fields as a query result, including `formId` (the form it belongs to) and the answers in `submissions`.
+
+### When it was submitted = `createdDate`
+
+**The submission time is `createdDate`.** Filter and sort on it. These fields **do not exist**, and each one fails with `Filter contains unsupported condition` or `Sort contains unsupported condition`: `submittedDate`, `submittedAt`, `submissionTime`, `submissionDate`, `dateCreated`, `_createdDate`.
+
+### A date range — one condition per operator, joined with `$and`
+
+A field takes **one** operator. Two operators in one object, such as `"createdDate": {"$gte": …, "$lt": …}`, fail with `Field '$lt' is not supported for filter with operator '$eq'`. Put each bound in its own condition under `$and`:
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/form-submission-service/v4/submissions/namespace/query' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  -d '{
+    "query": {
+      "filter": {
+        "$and": [
+          { "namespace": "wix.form_app.form" },
+          { "createdDate": { "$gte": "2026-10-05T00:00:00Z" } },
+          { "createdDate": { "$lt": "2026-10-12T00:00:00Z" } }
+        ]
+      },
+      "sort": [{ "fieldName": "createdDate", "order": "DESC" }],
+      "cursorPaging": { "limit": 100 }
+    }
+  }'
+```
+
+- Write dates as ISO 8601 UTC. For "last week", work out the week's start and end from today's date, and say which dates you used.
+- **"How many…" in a date range**: follow every page and add up `metadata.count`. There is no total in the response, and Count Submissions takes no date filter.
+- **"How many…" in total, per form**: Count Submissions.
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/form-submission-service/v4/submissions/count' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  -d '{ "formIds": ["<formId>"], "namespace": "wix.form_app.form" }'
+```
+
+Returns `formsSubmissionsCount[]`, with `formId`, `totalCount` and `unseenCount` for each form.
+
+### The fields you can filter and sort by — a closed list
+
+| Field | Filter operators | Sortable |
+|---|---|---|
+| `namespace` | `$eq` — **required in every filter** | no |
+| `id`, `formId`, `contactId`, `status` | `$eq`, `$ne`, `$in`, `$nin` | yes |
+| `seen` | `$eq`, `$ne` | yes |
+| `createdDate`, `updatedDate` | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin` | yes |
+| `submitter.memberId`, `submitter.visitorId`, `submitter.applicationId`, `submitter.userId` | `$eq`, `$ne`, `$in`, `$nin` | yes |
+| `orderDetails.checkoutId` | `$eq`, `$ne`, `$in`, `$nin` | yes |
+
+Any other field is rejected. The common wrong ones:
+
+| You want | Use | Not |
+|---|---|---|
+| Submissions from one contact | `"contactId": "<contactId>"` (top level) | `submitter.contactId`, `submitterContactId` |
+| Submissions to one form | `"formId": "<formId>"` | `submission.formId` |
+| Unread submissions | `"seen": false` | — |
+| Recorded submissions only | `"status": "CONFIRMED"` | — |
+| Submissions with a given answer (an email typed in, a choice picked) | Not filterable. Filter by `formId`, then match the answer in code (STEP 5). | `submissions.email`, `submissions.<target>`, `contact.email` |
+
+To find a person's submissions by their email, look up the contact first, then filter submissions by `"contactId": "<contacts[0].id>"`:
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/contacts/v4/contacts/query' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  -d '{ "query": { "filter": { "info.emails.email": "jane@example.com" }, "fieldsets": ["BASIC"] } }'
+```
+
+No contact found means no submissions linked to that email. See [Query Contacts](https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts/contact-v4/query-contacts).
+
+### Paging
+
+Each page holds at most **100** submissions or forms. When `metadata.hasNext` is `true`, send the same URL with **only** the cursor. The cursor carries the filter and sort, including the namespace:
+
+```json
+{ "query": { "cursorPaging": { "limit": 100, "cursor": "<metadata.cursors.next>" } } }
+```
+
+---
+
+## STEP 5 · Read the answers
+
+A submission's answers are in its `submissions` object, keyed by each field's **`target`**:
+
+```json
+"submissions": { "email_1923": "jane@example.com", "short_answer_7b5c": "Hello" }
+```
+
+The targets are not labels. To show the user readable answers, read the form once (Get Form) and match each `formFields[].inputOptions.target` to the label inside that field's `inputOptions`, for example `stringOptions.textInputOptions.label`.
+
+**Return only what the user asked for.** A submission page can be large. Before you answer or pass results on, keep only the fields you need, such as `id`, `createdDate`, `contactId` and the few answers that matter. Use `fieldsets=METADATA` on List Forms for the same reason.
+
+To give the user a link to a form's submissions table, see [Forms Dashboard Navigation](./forms-dashboard-navigation.md).
+
+---
+
+## Troubleshooting
+
+| Error / symptom | Cause | Fix |
+|---|---|---|
+| `namespace must not be empty` / `namespace has size 0, expected 10 or more` on List Forms | The `namespace` query parameter is missing | Add `?namespace=wix.form_app.form` |
+| `namespace filter is required` on a submissions query | `namespace` is missing from `query.filter`, or sent at the top level | Put `"namespace": "wix.form_app.form"` inside `query.filter` |
+| `Permissions for given namespace not found: …` | The site doesn't have that app | Stop. Check [installed apps](../app-installation/list-installed-apps.md) and tell the user. Don't try other namespaces |
+| A bare `404` with no message | An invented URL such as `/forms/v4/forms` or `/form-schema-service/v4/submissions/...` | Use the URLs in STEP 2 exactly |
+| `Sort contains unsupported condition` / `Filter contains unsupported condition` | A field outside the closed list, such as `submittedDate`, `_createdDate`, `submitter.contactId` or an answer key | Use `createdDate`, `contactId`, or the table in STEP 4 |
+| `Field '$lt' is not supported for filter with operator '$eq'` | Two operators in one field object | One condition per operator under `$and` |
+| `Filter contains unsupported operator` on Query Forms | Two operators in one field object | One condition per operator under `$and` |
+| `Field 'createdDate' is using non allowed operator '$ge'` | `$ge` / `$le` | Use `$gte` / `$lte` |
+| The user says a form is missing from the list | List Forms defaults to `enabled=true` | Call again with `enabled=false` |
+| `"forms": []` | Wrong namespace, no forms there, or (on List Forms) every form is disabled | Check the namespace (STEP 1) and call again with `enabled=false` before reporting "no forms" |
+
+---
+
+## Related Documentation
+
+- [Update Form](./update-form.md) and [Create Form](./create-form.md) — changing or building a form
+- [Forms Dashboard Navigation](./forms-dashboard-navigation.md) — links to a form and its submissions table
+- [List Forms](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/list-forms) · [Query Forms](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/query-forms) · [Get Form](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/get-form)
+- [Query Submissions By Namespace](https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/query-submissions-by-namespace) · [Count Submissions](https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/count-submissions)
+- [About Submission Values](https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/about-submission-values) — what each field type stores
+- [About the Wix API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language) — `$and`, `$or`, paging

package/skills/wix-manage/references/forms/update-form.md

@@ -4,6 +4,9 @@ description: "Changes a Wix form that already exists, with Form Schemas v4 `PATC
 ---
 # RECIPE: Update a Wix Form
 
+> These calls need the Wix Forms app on the site (`appDefId` `225dd912-7dea-4738-8688-4b8c6955ffc2`); a `428`, a `400` naming the app, or an empty result on a site that should have content means it is not there. [List Installed Apps](../app-installation/list-installed-apps.md) shows what the site has; [Install Wix Apps](../app-installation/install-wix-apps.md) adds it by that id.
+
+
 > **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Body-bearing requests also need `Content-Type: application/json`. Send `wix-site-id: <SITE_ID>` when the token is account-scoped.
 
 Change what a form collects — **add a field, relabel one, tighten a rule, reorder, retire one** — on a form that already exists. **Composing the field itself is not here**: [About Form Fields](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields) owns the `identifier` / `inputType` / `componentType` table and the options/enum shapes, and [Create Form](./create-form.md) § Silent breakers apply to an added field exactly as to a created one.
@@ -14,6 +17,8 @@ Change what a form collects — **add a field, relabel one, tighten a rule, reor
 
 ## The call
 
+**No `formId` yet** ("my contact form")? List the forms and pick it by `name`: `GET https://www.wixapis.com/form-schema-service/v4/forms?namespace=wix.form_app.form&fieldsets=METADATA` returns only names and IDs. That call skips disabled forms; if the form isn't there, call again with `&enabled=false`.
+
 ```bash
 # 1 · read the form back: you need its current revision, and every field you intend to keep
 curl -X GET \
@@ -37,6 +42,7 @@ curl -X PATCH \
 
 - **⚠️ `namespace` is a REQUIRED query parameter on the read, and this is what a revise run trips over.** Without it the read returns `400 namespace has size 0, expected 10 or more, namespace must not be empty` — a violation naming a *field*, so it reads like a body problem. Fix the call, don't reshape the payload. (The filter on `POST .../v4/forms/query` needs it too.)
 - **The read-back is the body.** Apply your change to what the `GET` returned and send that as `form`. `namespace` is **immutable** and travels along; **there is no `fieldMask`**, and no `revision` outside `form` — inventing either is a silent partial write.
+- **⚠️ Delete the legacy `fields` array before you send.** The read-back carries `fields` (the old field list) next to `formFields`. Send both and the old list wins: the `PATCH` returns `200` and bumps `revision`, but a field you added only to `formFields` is dropped, and only its layout item is kept. Spreading the whole form (`{ ...form, formFields }`) does exactly this. Remove `fields` and `deletedFields` first: `const { fields, deletedFields, ...body } = form`.
 - **⚠️ Append to `formFields`; never rebuild the entries you read.** `[...form.formFields, newField]` works. Mapping the array to "clean up" each field — dropping `fieldType`, re-shaping an options block — fails with `fieldType cannot be provided with any these fields: input_options, display_options` on **every** field at once. The read-back's field objects are already a valid write shape: pass them through untouched and touch only the one field you are changing.
 - **`formFields` is replaced wholesale.** Wix: *"Any field that's missing from the array you send is moved to `deletedFormFields`, so resend every field you want to keep."* Same for `steps[].layout` — miss an item and that field goes unplaced, which renders empty. Drops are recoverable from `deletedFormFields`, but nothing announces them.
 - **A stale `revision` is rejected** — re-`GET` and re-apply; never guess or increment it.
@@ -105,6 +111,7 @@ Then hand back the dashboard links ([Forms Dashboard Navigation](./forms-dashboa
 | `fieldType cannot be provided with any these fields: input_options, display_options` — on every field | The read-back's `formFields` were re-mapped or "cleaned" before sending | Send the fields exactly as read and append the new one: `[...form.formFields, newField]` |
 | `inputType enum must be in [UNKNOWN_INPUT_TYPE, STRING, NUMBER, …]` | An invented `inputType` such as `ENUM` (with an `enumOptions` block) for a choice field | A dropdown or radio is `inputType: "STRING"` with `stringOptions.componentType`; multi choice is `ARRAY` |
 | The `PATCH` is rejected for a `revision` mismatch | Someone (or an earlier call) updated the form since your read | Re-`GET` and re-apply the change; never increment the revision yourself |
+| The `PATCH` returns `200` and bumps `revision`, but the new field is missing from the read-back (its layout item is there) | The body still carried the legacy `fields` array from the read-back, and the server applied that old list | Remove `fields` and `deletedFields` from the body, re-`GET`, and send again. Don't retry the same body |
 | Fields that were on the form are gone after the update | `formFields` was sent partial — the omitted fields moved to `deletedFormFields` | Re-send them in a further `PATCH`, from `deletedFormFields` in the read-back; always send the whole array |
 | Surviving fields render empty for the owner | `steps[].layout` was sent without their items | Re-send every layout item, including `SUBMIT_BUTTON`'s; re-verify with `/summary` |
 | The added dropdown/radio reads back as a text input with `textInputOptions` | `identifier` was `TEXT_INPUT` rather than the choice kind — `componentType` alone doesn't route the renderer | Set `identifier` to the choice kind and re-send. Deleting and re-adding the field with the same `identifier` reproduces it ([Create Form](./create-form.md) § Choice fields) |
@@ -115,6 +122,7 @@ Then hand back the dashboard links ([Forms Dashboard Navigation](./forms-dashboa
 
 ## Related Documentation
 
+- [Read Forms and Submissions](./read-forms-and-submissions.md) — finding the form to update when you have no `formId` yet
 - [Create Form](./create-form.md) — composing fields, the identifier table, choice fields, the layout rules, plan caps
 - [Forms Dashboard Navigation](./forms-dashboard-navigation.md) — the builder and submissions links to hand back
 - [Update Form](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/update-form) — the `PATCH` contract and its replace semantics

package/skills/wix-manage/references/pricing-plans/create-and-update-pricing-plans.md

@@ -4,6 +4,9 @@ description: Creates subscription and one-time payment plans using Plans API. Co
 ---
 # Technical Step-by-Step Instructions: Creating or Updating a Wix Pricing Plans (Real-World, API-First)
 
+> These calls need the Wix Pricing Plans app on the site (`appDefId` `1522827f-c56c-a5c9-2ac9-00f9e6ae12d3`); a `428`, a `400` naming the app, or an empty result on a site that should have content means it is not there. [List Installed Apps](../app-installation/list-installed-apps.md) shows what the site has; [Install Wix Apps](../app-installation/install-wix-apps.md) adds it by that id.
+
+
 ## Description
 Below are the recommended steps to successfully create or update a Wix Pricing Plans (or several at once) on Wix and attach a booking session to a pricing plan, with real-world troubleshooting and fixes for common API issues.
 

package/skills/wix-manage/references/restaurants/wix-restaurants-setup.md

@@ -4,6 +4,9 @@ description: Configures restaurant menus, sections, and items using Menus API. C
 ---
 # Wix Restaurants Setup API Reference
 
+> These calls need the Wix Restaurants Menus app on the site (`appDefId` `b278a256-2757-4f19-9313-c05c783bec92`; online ordering is Wix Restaurants Orders `9a5d83fd-8570-482e-81ab-cfa88942ee60`, reservations Wix Table Reservations `f9c07de2-5341-40c6-b096-8eb39de391fb`); a `428`, a `400` naming the app, or an empty result on a site that should have content means it is not there. [List Installed Apps](../app-installation/list-installed-apps.md) shows what the site has; [Install Wix Apps](../app-installation/install-wix-apps.md) adds one by that id.
+
+
 This recipe covers setting up and configuring Wix Restaurants using the REST API, including menus, items, and ordering configuration.
 
 ## Prerequisites

package/skills/wix-manage/references/seo/manage-url-redirects.md

@@ -1,6 +1,6 @@
 ---
 name: "Manage URL Redirects on a Wix Site"
-description: "Retrieve, create, and delete URL redirects on a Wix site using the public SEO Redirects API. Covers exact and group redirects, language-scoped redirects for multilingual sites, batches of up to 500, and the change flow for a redirect that already exists. This API has no query, search, or update method: List Redirects is the only read-many. Redirects do not chain, so creating one that points at a path another redirect starts from permanently deletes that other redirect; list and check before every write."
+description: "Retrieve, create, and delete URL redirects on a Wix site using the public SEO Redirects API. Covers exact and group redirects, language-scoped redirects for multilingual sites, bulk creates of up to 100 and bulk deletes of up to 500, and the change flow for a redirect that already exists. This API has no query, search, or update method: List Redirects is the only read-many. Redirects do not chain, so creating one that points at a path another redirect starts from permanently deletes that other redirect; list and check before every write."
 ---
 
 # Manage URL Redirects on a Wix Site
@@ -72,6 +72,12 @@ directly - do not go looking for the shapes in the docs first.
 | Bulk Create Redirects | `POST /bulk/redirects/create` |
 | Bulk Delete Redirects | `POST /bulk/redirects/delete` |
 
+**`POST /redirects` is not Create Redirect.** It looks like the standard create
+path, but it is not part of this API and rejects a `{ "redirect": ... }` body
+with a 400. Create one redirect with `POST /create-redirect` and many with
+`POST /bulk/redirects/create`. Do not build any other path from the method
+names: `/list-redirects` and `/redirects/query` return 404.
+
 Create Redirect takes the redirect nested under `redirect`. `options` and
 `language` are optional, `id` only when preserving an existing redirect's
 identity:
@@ -185,7 +191,7 @@ count as the same path.
 
 **There is no query endpoint and no search endpoint.** Most Wix APIs have one, so
 this is the second place an agent goes wrong. Do not call, construct, or go
-looking for `POST /v1/redirects/query`, a `/search` path, or any filtered variant:
+looking for `POST /v1/redirects/query`, `/list-redirects`, a `/search` path, or any filtered variant:
 they do not exist, and trying one wastes a turn and returns nothing useful.
 
 - **List Redirects** returns every redirect on the site in one response. It takes
@@ -213,8 +219,9 @@ redirect is not in effect, and if the create fails the old redirect is gone.
 
 ## Batches
 
-**Bulk Create Redirects** and **Bulk Delete Redirects** take 1 to 500 items and
-report each one separately **inside a successful response**:
+**Bulk Create Redirects** takes 1 to 100 redirects and **Bulk Delete Redirects**
+takes 1 to 500 IDs. A larger list is rejected as a whole with a 400, so split it
+first. Both report each item separately **inside a successful response**:
 
 - Read every outcome from `results[].itemMetadata`, matched to your request by
   `originalIndex`. A failed item carries `error.code`, such as `FROM_URL_EXISTS`
@@ -225,6 +232,28 @@ report each one separately **inside a successful response**:
 - A malformed request, such as an empty list, is rejected as a whole with a 400
   and returns no per-item results.
 
+There is no import endpoint. To migrate a list of old URLs, such as a CSV from
+another platform, follow this path and nothing else:
+
+1. Parse the whole list before any call. Skip the header row, trim whitespace,
+   and drop exact duplicate rows. Each row is one exact redirect unless the user
+   asked for a whole section.
+2. Call **List Redirects** once and run the checks above against every row. If
+   either check matches any row, the same rule applies as for a single create:
+   name every row and every existing redirect at stake, end your turn without
+   writing, and continue only after the user answers. A row whose `to` equals an
+   existing redirect's `from` is the dangerous one - Bulk Create deletes that
+   redirect with no error to catch afterwards. If nothing matched, continue in
+   the same turn.
+3. Split the rows into chunks of 100 and call **Bulk Create Redirects** once per
+   chunk, in order. 250 rows is three calls: 100, 100, then 50.
+4. Read each chunk's `results[].itemMetadata` and keep a running count. Never
+   delete a redirect that reported success in order to create it again, and
+   never resend a chunk that succeeded. A success with no `id` means the same
+   redirect was already on the site, not that the write was lost.
+5. Report the total from those results. Call List Redirects again only if
+   `bulkActionMetadata.undetailedFailures` was not `0`.
+
 Two more sharp edges to report truthfully:
 
 - A successful **Bulk Delete** item means the deletion was found and sent, not

package/skills/wix-manage/references/sites/create-headless-site.md

@@ -1,55 +1,21 @@
 ---
 name: "Create Headless Site"
-description: Creates a Wix Headless site (headless business) with one account-level API call — site, Wix Business Solution apps, and a configured OAuth client.
+description: Creates a Wix Headless website: a site in the user's Wix account whose frontend is files uploaded to Wix hosting, with the Wix business backend behind it through APIs. The site is created and its pages put live by Upload a Website or HTML Files; a Wix Business Solution (a store, blog, bookings and more) is then integrated into it by the Wix Headless kit, from its cold start.
 ---
 # Create Headless Site
 
-Headless sites are not created from templates. One account-level call creates the site, installs the requested Wix Business Solution apps, and creates and configures the site's OAuth client.
-
-> Do NOT use the [Create Site from Template](create-site-from-template.md) API for headless sites — it only tags the site's namespace and skips the headless setup entirely.
-
-## Prerequisites
-
-- Wix account with site creation permissions
-- Account-level API access
-
-## Provision a Headless Business
-
-**Endpoint**: `POST https://www.wixapis.com/headless-business-setup/v1/headless-business/provision`
-
-**Request Body**:
-```json
-{
-  "origin": "agent-<your-agent-id>",
-  "newMetasite": {
-    "namingStrategy": { "metaSiteName": "My Headless Business" },
-    "seedOptions": [
-      { "businessSolution": "STORES", "clearTemplateContent": true, "seedDemoContent": false }
-    ]
-  },
-  "synchronousSteps": ["SET_METASITE_NAME", "CONFIGURE_HEADLESS_APP"]
-}
-```
-
-- `origin` — `agent-` followed by your own identifier: a short, stable, lowercase-hyphenated slug for the coding agent or tool you are (e.g. `claude-code`, `cursor`, `codex-cli`, `windsurf`, `github-copilot`, or your product's name; `unknown-agent` if you can't name yourself). It records which agent created the site
-- `namingStrategy` — exactly one of: `metaSiteName` (exact display name), `llmPromptBasedName: {}` (name derived from the top-level `prompt` field), or `defaultName: {}`
-- `seedOptions` — Wix Business Solution apps to install at creation: `STORES`, `BLOG`, `BOOKINGS`, `EVENTS`, `PORTFOLIO`, `PRICING_PLANS`. Each entry takes `clearTemplateContent` (remove sample content) and `seedDemoContent` (seed demo content). Empty installs none
-- `synchronousSteps` — steps to complete before the call returns: `SET_METASITE_NAME`, `CONFIGURE_HEADLESS_APP`, `SEED_CONTENT`. Omitted steps run asynchronously. Include `CONFIGURE_HEADLESS_APP` when the OAuth client must be usable immediately
-
-**Response**:
-```json
-{ "metaSiteId": "<SITE_ID>", "appId": "<OAUTH_CLIENT_ID>" }
-```
-
-`appId` is the site's OAuth client ID — do NOT create a separate OAuth app.
-
-## Existing Sites
-
-To provision headless onto an existing site, pass `"existingMetasite": {}` instead of `newMetasite`. This is a site-level call in the context of that site.
-
-## Next Steps
-
-After creating the site:
-- Install additional apps using [Install Wix Apps](../app-installation/install-wix-apps.md)
-- Add content (products, services, blog posts, etc.)
-- Use the `appId` as the `client_id` to mint visitor tokens and make buyer-facing API calls — see [Manage OAuth Apps](manage-oauth-apps.md)
+A Wix Headless site is a site in the user's Wix account whose frontend is files
+uploaded to Wix hosting and served at a `*.wix-site-host.com` URL, with the Wix
+business backend (stores, bookings, forms, a CMS) behind it through APIs. It comes
+to be in two steps:
+
+1. **Create the site and put its pages live**: [Upload a Website or HTML Files](upload-static-site.md),
+   online at https://dev.wix.com/docs/api-reference/account-level/sites/skills/upload-a-website-or-html-files.md.
+   It holds the call that creates the site, then uploads the pages, the user's or
+   ones you write, and changes them later on the same site and URL.
+2. **Integrate Wix Headless into it**: a Wix Business Solution built on shipped code (a
+   store, a blog, bookings, events, a CMS, forms, members and more, with its pages,
+   data layer and seed) comes from the Wix Headless kit, starting at its cold start,
+   https://www.wix.com/skills/headless-cold-start/headless-kit.md. It takes a machine
+   from nothing (the skills, the Wix CLI sign-in) to a built, seeded, released site on
+   the same site and URL; the upload recipe says how to run it with no shell of your own.

package/skills/wix-manage/references/sites/manage-oauth-apps.md

@@ -147,8 +147,8 @@ Use the `access_token` as the `Authorization` header on subsequent API calls.
 
 ## API Reference
 
-- [OAuth Apps — Create](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/create-o-auth-app)
-- [OAuth Apps — Get](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/get-o-auth-app)
-- [OAuth Apps — Query](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/query-o-auth-apps)
-- [OAuth Apps — Update](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/update-o-auth-app)
+- [OAuth Apps — Create](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/create-oauth-app)
+- [OAuth Apps — Get](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/get-oauth-app)
+- [OAuth Apps — Query](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/query-oauth-apps)
+- [OAuth Apps — Update](https://dev.wix.com/docs/api-reference/business-management/headless/oauth-apps/update-oauth-app)
 - [Retrieve Tokens — `/oauth2/token` contract, all grant types](https://dev.wix.com/docs/api-reference/business-management/headless/authentication/retrieve-tokens)

package/skills/wix-manage/references/sites/read-site-context.md

@@ -51,6 +51,10 @@ Response:
 - **Wix Blog** (ID: `14bcded7-0066-7c35-14d7-466cb3f09103`)
 ```
 
+The app list reflects installs after a delay: an app installed a few minutes ago can be missing here
+while its own API already answers. To check an install you just made, read the site's instances with
+[List Installed Apps](../app-installation/list-installed-apps.md), which is immediate.
+
 ### Without siteId
 
 ```bash