@wix/agent-skills 1.23.0 → 1.25.0

package/skills/wix-manage/references/cms/cms-data-items-crud.md

@@ -1,12 +1,12 @@
 ---
 name: "CMS Data Items CRUD"
-description: "Add, query, update, and delete items in CMS collections. Use this to insert content, bulk insert/update/patch/delete items, query with filters, and manage collection data. Key endpoints: /wix-data/v2/items, /wix-data/v2/bulk/items/*."
+description: "Add, query, update, and delete items in CMS collections, one at a time or in bulk. Also covers counting items, upserting with bulk save, truncating a collection, aggregating data with a pipeline, linking items through single- and multi-reference fields, and reading items with their referenced items expanded."
 ---
 # CMS Data Items CRUD
 
 > **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`.
 
-This recipe covers basic Create, Read, Update, Delete (CRUD) operations for Wix CMS data items.
+This recipe covers Create, Read, Update, Delete (CRUD) operations for Wix CMS data items, plus count, upsert, truncate, aggregate, and reference-field links.
 
 ## Prerequisites
 
@@ -25,8 +25,8 @@ This recipe covers basic Create, Read, Update, Delete (CRUD) operations for Wix
 Before inserting or updating items, you need to know the collection's field names and types. If you don't already know the schema:
 
 1. **Query existing items** - Fetch a few items to infer field names from the data
-2. **Get collection schema** - Use `GET /collections/{dataCollectionId}` for full field definitions, **including `plugins`** — don't omit the `plugins` field when fetching or listing schemas
-3. **List collections** - Use `GET /collections?fields=displayName,plugins` to see what collections exist (see [Schema Management](cms-schema-management.md))
+2. **Get collection schema** - Use `GET https://www.wixapis.com/wix-data/v2/collections/{dataCollectionId}` for full field definitions, **including `plugins`** — don't omit the `plugins` field when fetching or listing schemas
+3. **List collections** - Use `GET https://www.wixapis.com/wix-data/v2/collections?fields=displayName,plugins` to see what collections exist (see [Schema Management](cms-schema-management.md))
 
 It may be, that user refers to schema by its `displayName` rather than `id`, if collection is not found list all collections to find the right `id` (`dataCollectionId`) to use.
 
@@ -36,7 +36,7 @@ It may be, that user refers to schema by its `displayName` rather than `id`, if
 
 ## Insert Data Item
 
-**Endpoint**: `POST /wix-data/v2/items`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items`
 
 **Request Body**:
 ```json
@@ -73,7 +73,7 @@ It may be, that user refers to schema by its `displayName` rather than `id`, if
 
 ## Bulk Insert Items
 
-**Endpoint**: `POST /wix-data/v2/bulk/items/insert`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/bulk/items/insert`
 
 **Request Body**:
 ```json
@@ -108,7 +108,7 @@ It may be, that user refers to schema by its `displayName` rather than `id`, if
 
 ## Query Data Items
 
-**Endpoint**: `POST /wix-data/v2/items/query`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items/query`
 
 **Basic Query**:
 ```json
@@ -163,7 +163,7 @@ It may be, that user refers to schema by its `displayName` rather than `id`, if
 
 ## Get Single Item
 
-**Endpoint**: `GET /wix-data/v2/items/{itemId}?dataCollectionId={collectionId}`
+**Endpoint**: `GET https://www.wixapis.com/wix-data/v2/items/{itemId}?dataCollectionId={collectionId}`
 
 ```bash
 curl -X GET \
@@ -173,7 +173,7 @@ curl -X GET \
 
 ## Update Data Item
 
-**Endpoint**: `PUT /wix-data/v2/items/{itemId}`
+**Endpoint**: `PUT https://www.wixapis.com/wix-data/v2/items/{itemId}`
 
 **Request Body**:
 ```json
@@ -192,7 +192,7 @@ curl -X GET \
 
 ## Patch Data Item (Partial Update - Single Item)
 
-**Endpoint**: `PATCH /wix-data/v2/items/{dataItemId}`
+**Endpoint**: `PATCH https://www.wixapis.com/wix-data/v2/items/{dataItemId}`
 
 Unlike Update, this only modifies the specified fields — all other fields remain unchanged.
 
@@ -229,7 +229,9 @@ Unlike Update, this only modifies the specified fields — all other fields rema
 
 ## Bulk Update Items
 
-**Endpoint**: `POST /wix-data/v2/bulk/items/update`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/bulk/items/update`
+
+> There is no update-by-filter endpoint. To update the items matching a filter, query them first (see [Query Data Items](#query-data-items)), then send their ids to bulk update or bulk patch.
 
 > **Important**: Use `id` (not `_id`) at the element level. The `data` object should NOT contain `_id`.
 
@@ -259,7 +261,7 @@ Unlike Update, this only modifies the specified fields — all other fields rema
 
 ## Bulk Patch Items (Partial Update)
 
-**Endpoint**: `POST /wix-data/v2/bulk/items/patch`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/bulk/items/patch`
 
 Unlike bulk update, this only modifies the specified fields - other fields remain unchanged. **Use this for partial updates.**
 
@@ -297,7 +299,7 @@ Unlike bulk update, this only modifies the specified fields - other fields remai
 }
 ```
 
-**Setting a reference field** (single REFERENCE only):
+**Setting a single `REFERENCE` field** (the value is one item ID; for `MULTI_REFERENCE` the value shape differs, see the next example):
 ```json
 {
   "dataCollectionId": "events",
@@ -318,27 +320,40 @@ Unlike bulk update, this only modifies the specified fields - other fields remai
 }
 ```
 
+**Setting a `MULTI_REFERENCE` field** (verified live): the value is an **array of item IDs**, and `SET_FIELD` **replaces the whole link set**. To add links without dropping the existing ones, use [Insert Multi-Reference Links](#insert-multi-reference-links) instead. A plain string, or `APPEND_TO_ARRAY`, fails per item with `WDE0303` inside a 200 bulk response — check `results[].itemMetadata`.
+```json
+{
+  "dataCollectionId": "Projects",
+  "patches": [
+    {
+      "dataItemId": "project-item-id",
+      "fieldModifications": [
+        {
+          "fieldPath": "team",
+          "action": "SET_FIELD",
+          "setFieldOptions": {
+            "value": ["alice-item-id", "bob-item-id"]
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
 **Available actions**: `SET_FIELD`, `REMOVE_FIELD`, `INCREMENT_FIELD`, `APPEND_TO_ARRAY`, `REMOVE_FROM_ARRAY`
 
 > **Common error**: If you get `WDE0080: patches must not be empty`, you sent `dataItems` instead of `patches`. Use the format above.
 
 > **Recommended**: Use bulk patch instead of bulk update when you only need to change specific fields.
 
-> **Reference Fields**:
-> - **Single REFERENCE**: CAN be set during insert/update by providing the referenced item's ID as the field value (e.g., `"venue": "venue-item-id"`)
-> - **MULTI_REFERENCE**: **STOP** - You cannot use this recipe for multi-reference fields. They cannot be set via insert/update/patch.
->
-> **For MULTI_REFERENCE operations (add speakers, assign tags, link categories, etc.):**
-> **READ [CMS References & Relationships](cms-references-and-relationships.md)** for the exact endpoints and request bodies:
-> - `POST /wix-data/v2/bulk/items/insert-references` - add references
-> - `POST /wix-data/v2/items/replace-references` - replace all references
-> - `POST /wix-data/v2/bulk/items/remove-references` - remove references
->
-> Error `WDE0303` occurs when attempting to set multi-reference fields via data operations.
+> **Reference fields**: a single `REFERENCE` field is set like any other value (`"venue": "venue-item-id"`, as above). `MULTI_REFERENCE` links are written only by a `SET_FIELD` patch (single or bulk) or by the reference endpoints in [Reference Fields](#reference-fields) below; insert, bulk insert, bulk save, PUT and bulk update all return 200 but silently drop multi-reference values (verified live) — read the item back after any of them.
 
 ## Delete Data Item
 
-**Endpoint**: `DELETE /wix-data/v2/items/{itemId}?dataCollectionId={collectionId}`
+> Deletes are irreversible. Confirm with the user before calling either delete endpoint unless the request already names the items to remove.
+
+**Endpoint**: `DELETE https://www.wixapis.com/wix-data/v2/items/{itemId}?dataCollectionId={collectionId}`
 
 ```bash
 curl -X DELETE \
@@ -348,7 +363,7 @@ curl -X DELETE \
 
 ## Bulk Delete Items
 
-**Endpoint**: `POST /wix-data/v2/bulk/items/remove`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/bulk/items/remove`
 
 ```json
 {
@@ -357,6 +372,225 @@ curl -X DELETE \
 }
 ```
 
+## Count Data Items
+
+Count items in a collection, optionally with filters.
+
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items/count`
+
+**Count All Items**:
+```json
+{
+  "dataCollectionId": "Products"
+}
+```
+
+**Response**:
+```json
+{
+  "totalCount": 42
+}
+```
+
+**Count with Filter**:
+```json
+{
+  "dataCollectionId": "Products",
+  "filter": {
+    "$and": [
+      { "inStock": true },
+      { "price": { "$gte": 50 } }
+    ]
+  }
+}
+```
+
+Count returns only `totalCount`. When the user needs to know *which* items match, run Query Data Items with the same filter instead of, or after, counting.
+
+## Bulk Save (Upsert)
+
+Insert new items or update existing items in a single operation. This is useful for syncing data.
+
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/bulk/items/save`
+
+```json
+{
+  "dataCollectionId": "Products",
+  "dataItems": [
+    {
+      "id": "existing-item-id",
+      "data": {
+        "title": "Updated Product",
+        "price": 199.99,
+        "inStock": true
+      }
+    },
+    {
+      "data": {
+        "title": "New Product",
+        "price": 79.99,
+        "inStock": true
+      }
+    }
+  ],
+  "returnEntity": true
+}
+```
+
+| Scenario | Action |
+|----------|--------|
+| No `id` provided | INSERT - Creates new item with generated ID |
+| `id` provided, doesn't exist | INSERT - Creates new item with provided ID |
+| `id` provided, exists | UPDATE - Replaces existing item |
+
+> **Warning**: When updating, the entire item is replaced. Include all fields you want to keep. Confirm with the user before saving over existing items.
+
+## Truncate Collection
+
+Remove all items from a collection.
+
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items/truncate`
+
+```json
+{
+  "dataCollectionId": "TestCollection"
+}
+```
+
+> **Warning**: This permanently deletes ALL items in the collection and cannot be undone. Ask the user to confirm before calling it.
+
+## Aggregate Data
+
+Perform calculations on collection data using a pipeline of sequential stages. The example shows one `group` stage; the full set of stages (`filter`, `group`, `sort`, `projection`, `unwindArray`, `skip`, `limit`) and accumulators is in the [Aggregate Pipeline Data Items reference](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/aggregate-pipeline-data-items).
+
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items/aggregate-pipeline`
+
+**Count by Category**:
+```json
+{
+  "dataCollectionId": "Products",
+  "pipeline": {
+    "stages": [
+      {
+        "group": {
+          "groupIds": [
+            {"key": "category", "expression": {"fieldPath": "category"}}
+          ],
+          "accumulators": [
+            {
+              "resultFieldName": "count",
+              "sum": {"expression": {"numeric": 1}}
+            }
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+## Operation Comparison
+
+| Operation | Use Case | Behavior |
+|-----------|----------|----------|
+| **Bulk Insert** | Add new items only | Fails if ID exists |
+| **Bulk Update** | Update existing items | Fails if ID doesn't exist, replaces entire item |
+| **Bulk Save** | Upsert (insert or update) | Creates or updates based on ID |
+| **Bulk Patch** | Partial update | Only modifies specified fields |
+
+## Reference Fields
+
+Reference fields link items across collections. A single `REFERENCE` field holds one item ID and is set like any other value in insert, update, or patch. A `MULTI_REFERENCE` field holds many links, and only two kinds of write create them: a `SET_FIELD` patch on the field (single or bulk), or the reference endpoints below, which add, replace, or remove links without touching the rest of the item. To add a reference field to a collection, see [Add a Reference Field](cms-schema-management.md#add-a-reference-field).
+
+> **Warning (verified live)**: writing IDs into a `MULTI_REFERENCE` field through insert, bulk insert, bulk save, or PUT update returns **200 and silently drops that field's value** — no error is raised. Bulk update is a full-item replace like PUT and does the same: `success: true`, value dropped (verified live, bulk save on both its insert and update paths). Never trust the write response for reference links: read the item back with `includeReferencedItems` and confirm the linked items are there.
+
+Linking flow, every time:
+
+1. Resolve the referring item ID and the referenced item IDs (query by a field value; never guess IDs).
+2. Write the links with the reference endpoints below, or with a `SET_FIELD` patch on the reference field. If the field already has links, `insert-references` adds without dropping them; `replace-references` and `SET_FIELD` discard the rest — confirm with the user before replacing unless the request says to.
+3. **Read the referring item back** with Query Data Items and `includeReferencedItems: ["<field>"]` (or `includeReferences: [{ "field": "<field>" }]`), and confirm the linked items are present. The write's 200 is not proof; only the read-back is.
+
+### Insert Multi-Reference Links
+
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/bulk/items/insert-references`
+
+```json
+{
+  "dataCollectionId": "Products",
+  "dataItemReferences": [
+    {
+      "referringItemId": "product-item-id",
+      "referringItemFieldName": "tags",
+      "referencedItemId": "tag-1-item-id"
+    },
+    {
+      "referringItemId": "product-item-id",
+      "referringItemFieldName": "tags",
+      "referencedItemId": "tag-2-item-id"
+    }
+  ],
+  "returnEntity": true
+}
+```
+
+### Replace All References
+
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items/replace-references`
+
+```json
+{
+  "dataCollectionId": "Products",
+  "referringItemId": "product-item-id",
+  "referringItemFieldName": "tags",
+  "newReferencedItemIds": ["new-tag-1-id", "new-tag-2-id", "new-tag-3-id"]
+}
+```
+
+> **Note**: To remove all references, pass an empty array for `newReferencedItemIds`.
+
+### Remove References (Bulk)
+
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/bulk/items/remove-references`
+
+```json
+{
+  "dataCollectionId": "Products",
+  "dataItemReferences": [
+    {
+      "referringItemId": "product-id-1",
+      "referringItemFieldName": "tags",
+      "referencedItemId": "tag-to-remove-id"
+    }
+  ]
+}
+```
+
+### Query with Referenced Items Expanded
+
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items/query`
+
+```json
+{
+  "dataCollectionId": "Products",
+  "query": {
+    "filter": {
+      "inStock": true
+    }
+  },
+  "includeReferencedItems": ["category", "tags"]
+}
+```
+
+The method article documents the same expansion as `"includeReferences": [{ "field": "category" }, { "field": "tags", "limit": 50 }]`; both forms work (verified live). Either way the expanded value is an **array of item objects** (with `_id`, `name`, …), not an array of IDs. Without one of these properties a `MULTI_REFERENCE` field is absent from the returned item, and a single `REFERENCE` field is returned as the item ID string (it is stored on the item; verified live).
+
+### Reference Query Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `$eq` | Exact match (single reference) | `{ "category": "id" }` |
+| `$hasSome` | Has at least one of | `{ "tags": { "$hasSome": ["id1", "id2"] } }` |
+| `$hasAll` | Has all of | `{ "tags": { "$hasAll": ["id1", "id2"] } }` |
+
 ## Field Types Reference
 
 | Type | Description | Example Value |
@@ -379,7 +613,7 @@ curl -X DELETE \
 | `ARRAY_STRING` | Array of strings | `["tag1", "tag2"]` |
 | `OBJECT` | JSON object | `{"key": "value"}` |
 | `REFERENCE` | Single reference | Item ID string |
-| `MULTI_REFERENCE` | Multiple references, use separate *reference* endpoints to manipulate, `include` to include in queries | Array of IDs |
+| `MULTI_REFERENCE` | Multiple references. Write with a `SET_FIELD` patch (array of item IDs, replaces the set) or the *reference* endpoints (add / replace / remove); expand in queries with `includeReferencedItems` or `includeReferences` | Write: array of item IDs (`SET_FIELD`). Read: absent unless expanded with `includeReferencedItems` / `includeReferences`, then an array of item objects |
 
 ---
 
@@ -452,7 +686,7 @@ POST https://www.wixapis.com/apps-installer-service/v1/app-instance/install
 }
 ```
 
-After the installation succeeds, retry the original `POST /wix-data/v2/items` request. If the
+After the installation succeeds, retry the original `POST https://www.wixapis.com/wix-data/v2/items` request. If the
 user only asks what the error means or how to fix it, explain this installation step and ask for
 confirmation before performing the install.
 
@@ -465,7 +699,7 @@ confirmation before performing the install.
 | `PERMISSION_DENIED` | Insufficient access | Check API permissions |
 | `WDE0007` | Bulk update: wrong ID field name | Use `id` not `_id` at element level |
 | `WDE0080` | Validation failed (multiple causes) | Bulk update: don't include `_id` in `data`; Bulk patch: use `patches` array not `dataItems` |
-| `WDE0303` | Can't set multi-reference field via data operations | Use reference endpoints: `insert-references`, `replace-references` |
+| `WDE0303` | Multi-reference field value is not an array of item IDs (a single ID string, or `APPEND_TO_ARRAY`); reported per item inside a 200 bulk response | Send `"value": ["id1", "id2"]` with `SET_FIELD`, or use the reference endpoints |
 | `WDE0110` | Wix CMS (Wix Data) application is not installed | Install application with appDefId: `e593b0bd-b783-45b8-97c2-873d42aacaf4` |
 
 ---
@@ -474,6 +708,4 @@ confirmation before performing the install.
 
 - [Data Items API Reference](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/introduction)
 - [CMS Schema Management](cms-schema-management.md) - Creating and modifying collections
-- [CMS References & Relationships](cms-references-and-relationships.md) - Linking collections
-- [CMS Data Operations Extended](cms-data-operations-extended.md) - Count, upsert, aggregate
 - [CMS Draft & Publish Workflow](cms-publishing-flow.md) - Collections gated behind a draft/publish (Draft Items plugin) workflow

package/skills/wix-manage/references/cms/cms-publishing-flow.md

@@ -68,7 +68,7 @@ Reads target a specific surface — there is no merged view:
 - **Published items**: query the published collection (`articles`).
 - **Drafts**: query the drafts collection resolved from `draftItemsPluginOptions.draftsCollectionId` (e.g. `articles__drafts`).
 
-**Endpoint**: `POST /wix-data/v2/items/query`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items/query`
 
 ```json
 {
@@ -92,7 +92,7 @@ Reads target a specific surface — there is no merged view:
 
 Insert into the **drafts** collection. The item starts as **DRAFT**.
 
-**Endpoint**: `POST /wix-data/v2/items`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items`
 
 ```json
 {
@@ -117,7 +117,7 @@ Editing a live item does **not** overwrite the live copy — it stages a **pendi
 
 Replaces the published item's data with the draft's content; the draft is then deleted. Pass the **published** collection id.
 
-**Endpoint**: `POST /wix-data/v2/items/publish-draft`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items/publish-draft`
 
 ```bash
 curl -X POST \
@@ -147,7 +147,7 @@ curl -X POST \
 
 Retracts a published item back to draft state. Pass the **published** collection id.
 
-**Endpoint**: `POST /wix-data/v2/items/unpublish`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/items/unpublish`
 
 ```bash
 curl -X POST \
@@ -198,7 +198,7 @@ curl -X DELETE 'https://www.wixapis.com/wix-data/v2/items/<id>?dataCollectionId=
 
 **Enable** — add the Draft Items plugin (requires collection-management permission). Use the dedicated endpoint; the Draft Items plugin cannot be added through the generic add-plugin call.
 
-**Endpoint**: `POST /wix-data/v2/collections/add-draft-items-plugin`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/collections/add-draft-items-plugin`
 
 ```bash
 curl -X POST 'https://www.wixapis.com/wix-data/v2/collections/add-draft-items-plugin' \
@@ -219,7 +219,7 @@ curl -X POST 'https://www.wixapis.com/wix-data/v2/collections/add-draft-items-pl
 
 **Disable** — remove the plugin:
 
-**Endpoint**: `POST /wix-data/v2/collections/delete-draft-items-plugin`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/collections/delete-draft-items-plugin`
 
 ```bash
 curl -X POST 'https://www.wixapis.com/wix-data/v2/collections/delete-draft-items-plugin' \
@@ -252,17 +252,17 @@ At the REST level, every read/author/publish/unpublish call here goes through th
 | Collection state | Desired action | API call | Permission needed |
 |------------------|----------------|----------|-------------------|
 | Draft Items plugin absent | Any write | Normal insert/update — writes go live immediately | Write Data Items |
-| Draft Items enabled | Detect workflow | `GET /collections/{id}` → inspect plugins for the Draft Items plugin; read `draftItemsPluginOptions.draftsCollectionId` | (read) |
-| Draft Items enabled | Read published items | `POST /items/query` on the published id | read |
-| Draft Items enabled | Read drafts | `POST /items/query` on the drafts collection id | read |
+| Draft Items enabled | Detect workflow | `GET https://www.wixapis.com/wix-data/v2/collections/{id}` → inspect plugins for the Draft Items plugin; read `draftItemsPluginOptions.draftsCollectionId` | (read) |
+| Draft Items enabled | Read published items | `POST https://www.wixapis.com/wix-data/v2/items/query` on the published id | read |
+| Draft Items enabled | Read drafts | `POST https://www.wixapis.com/wix-data/v2/items/query` on the drafts collection id | read |
 | PUBLISHED | Edit into a pending draft (→ CHANGED) | Create the draft (`createDataItemDraft`), then edit it on the drafts collection | Write Data Items |
-| — | Create new draft (→ DRAFT) | `POST /items` on the drafts collection | Write Data Items |
-| DRAFT / CHANGED | Publish (→ PUBLISHED) | `POST /items/publish-draft` (published id) | Write Data Items |
-| PUBLISHED / CHANGED | Unpublish, keep as draft (→ DRAFT) | `POST /items/unpublish` `copyToDraft:true` | Write Data Items |
-| PUBLISHED / CHANGED | Unpublish, discard | `POST /items/unpublish` `copyToDraft:false` | Write Data Items |
-| CHANGED | Revert to live version (discard edit) | `DELETE /items/{id}?dataCollectionId=<drafts id>` | Write Data Items |
+| — | Create new draft (→ DRAFT) | `POST https://www.wixapis.com/wix-data/v2/items` on the drafts collection | Write Data Items |
+| DRAFT / CHANGED | Publish (→ PUBLISHED) | `POST https://www.wixapis.com/wix-data/v2/items/publish-draft` (published id) | Write Data Items |
+| PUBLISHED / CHANGED | Unpublish, keep as draft (→ DRAFT) | `POST https://www.wixapis.com/wix-data/v2/items/unpublish` `copyToDraft:true` | Write Data Items |
+| PUBLISHED / CHANGED | Unpublish, discard | `POST https://www.wixapis.com/wix-data/v2/items/unpublish` `copyToDraft:false` | Write Data Items |
+| CHANGED | Revert to live version (discard edit) | `DELETE https://www.wixapis.com/wix-data/v2/items/{id}?dataCollectionId=<drafts id>` | Write Data Items |
 | any | Delete entirely (both versions) | Delete on the published id (+ drafts id if a draft exists) | Write Data Items |
-| plain, no plugin | Enable workflow | `POST /collections/add-draft-items-plugin` | Manage Data Collections |
+| plain, no plugin | Enable workflow | `POST https://www.wixapis.com/wix-data/v2/collections/add-draft-items-plugin` | Manage Data Collections |
 
 ---
 

package/skills/wix-manage/references/cms/cms-schema-management.md

@@ -1,6 +1,6 @@
 ---
 name: "CMS Schema Management"
-description: Create and modify CMS collection structures. Covers listing collections, creating collections with fields, adding/removing fields, and updating collection settings.
+description: Create and modify CMS collection structures. Covers listing collections, creating collections with fields, adding/removing fields (including single- and multi-reference fields that link two collections), and updating collection settings.
 ---
 # CMS Schema Management
 
@@ -37,7 +37,7 @@ curl -X GET \
 
 ## Get Collection Schema
 
-**Endpoint**: `GET /wix-data/v2/collections/{collectionId}`
+**Endpoint**: `GET https://www.wixapis.com/wix-data/v2/collections/{collectionId}`
 
 ```bash
 curl -X GET \
@@ -47,7 +47,7 @@ curl -X GET \
 
 ## Create a New Collection
 
-**Endpoint**: `POST /wix-data/v2/collections`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/collections`
 
 ```json
 {
@@ -72,7 +72,7 @@ curl -X GET \
 
 ## Add a Field to Existing Collection
 
-**Endpoint**: `POST /wix-data/v2/collections/create-field`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/collections/create-field`
 
 ```json
 {
@@ -86,11 +86,60 @@ curl -X GET \
 }
 ```
 
+### Add a Reference Field
+
+Same endpoint as above: `POST https://www.wixapis.com/wix-data/v2/collections/create-field`. The two bodies below differ only in `type` and `typeMetadata`; omitting `typeMetadata` fails with `WDE0075` (see Error Handling).
+
+| Type | Field Type | Relationship | Example |
+|------|------------|--------------|---------|
+| Single Reference | `REFERENCE` | One-to-one, Many-to-one | Product → Category |
+| Multi-Reference | `MULTI_REFERENCE` | One-to-many, Many-to-many | Product → Tags |
+
+**Single reference** — `typeMetadata.reference` names the referenced collection:
+
+```json
+{
+  "dataCollectionId": "Products",
+  "field": {
+    "key": "category",
+    "displayName": "Category",
+    "type": "REFERENCE",
+    "typeMetadata": {
+      "reference": {
+        "referencedCollectionId": "Categories"
+      }
+    }
+  }
+}
+```
+
+**Multi-reference** — `typeMetadata.multiReference` also names the field created on the other collection:
+
+```json
+{
+  "dataCollectionId": "Products",
+  "field": {
+    "key": "tags",
+    "displayName": "Tags",
+    "type": "MULTI_REFERENCE",
+    "typeMetadata": {
+      "multiReference": {
+        "referencedCollectionId": "Tags",
+        "referencingFieldKey": "products",
+        "referencingDisplayName": "Products"
+      }
+    }
+  }
+}
+```
+
+To link items through these fields, see [Reference Fields](cms-data-items-crud.md#reference-fields) in the CMS Data Items CRUD recipe.
+
 ## Delete a Field from Collection
 
 > **Warning**: This permanently deletes all data stored in this field across all items.
 
-**Endpoint**: `POST /wix-data/v2/collections/delete-field`
+**Endpoint**: `POST https://www.wixapis.com/wix-data/v2/collections/delete-field`
 
 ```json
 {
@@ -101,7 +150,7 @@ curl -X GET \
 
 ## Update Collection Settings
 
-**Endpoint**: `PATCH /wix-data/v2/collections/{collectionId}`
+**Endpoint**: `PATCH https://www.wixapis.com/wix-data/v2/collections/{collectionId}`
 
 ```json
 {
@@ -116,7 +165,7 @@ This works for `displayName`/`displayField`. **Permission updates currently fail
 
 **To change permissions on an existing collection, use the full-replace endpoint instead** (`UpdateDataCollection`, not `PatchDataCollection`) — it requires the collection's current `revision` and full `fields` array (get both from a `GET` first), but it does work:
 
-**Endpoint**: `PUT /wix-data/v2/collections`
+**Endpoint**: `PUT https://www.wixapis.com/wix-data/v2/collections`
 
 ```json
 {
@@ -170,6 +219,8 @@ Don't delete and recreate a collection just to change its permissions — this f
 
 | Error | Cause | Solution |
 |-------|-------|----------|
+| `WDE0075` (`Metadata for Reference type field not provided`) | `create-field` with `type` REFERENCE or MULTI_REFERENCE but no `typeMetadata` | Send `typeMetadata.reference.referencedCollectionId` (or `typeMetadata.multiReference…`), see Add a Reference Field |
+| `WDE0075` (`Not recognized role provided in permissions`) | `PATCH /collections/{id}` with a `permissions` change | Use the full-replace `PUT /collections` (see Update Collection Settings) or the Data Permissions API |
 | `WDE0110` | Wix CMS (Wix Data) app is not installed on the site | Install it: `POST https://www.wixapis.com/apps-installer-service/v1/app-instance/install` with body `{"tenant":{"tenantType":"SITE","id":"<SITE_ID>"},"appInstance":{"appDefId":"e593b0bd-b783-45b8-97c2-873d42aacaf4"}}`, then retry. See the [Install Wix Apps recipe](../app-installation/install-wix-apps.md). |
 
 ## Related Documentation

package/skills/wix-manage/references/sites/query-sites.md

@@ -6,7 +6,7 @@ description: List, count, and find the sites in a Wix account. Covers the namesp
 
 List, count, and find the sites in a Wix account.
 
-- **Auth**: account-level (a Wix user token, or an account-level API key). `wix token` prints one.
+- **Auth**: account-level (a Wix user token, or an account-level API key).
 - **Permission**: `SITE_LIST.READ` (scope `SCOPE.ACC-DC-OS.READ-SITE`).
 - **Endpoints**: list `POST https://www.wixapis.com/site-list/v2/sites/query` · count
   `POST https://www.wixapis.com/site-list/v2/sites/count`.
@@ -99,10 +99,3 @@ interface Site {
   parentChildRole: string;    // e.g. NONE
 }
 ```
-
-## Next Steps
-
-Use a site's `id` for site-level API calls — derive a site token from the account token
-(`wix token --site <id>`, or the `oauth2/token` refresh-grant in wix-auth `device-flow`), then read
-its context via [Read Site Context](read-site-context.md) or create sites with
-[Create Site from Template](create-site-from-template.md).

package/skills/wix-auth/SKILL.md

@@ -1,12 +0,0 @@
----
-name: wix-auth
-description: "Authenticate with Wix to obtain an access token for calling Wix APIs. Use when an agent needs a valid Wix access token and has none, or when the stored token is expired."
----
-
-# Wix Auth
-
-Wix supports multiple authentication flows. This skill currently covers:
-
-- [Device Flow](references/device-flow.md) — interactive login via browser, no client secret required. Use when the agent is acting on behalf of a logged-in Wix user.
-
-Other flows (OAuth authorization code, API key) are documented at [https://www.wix.com/skills/docs](https://www.wix.com/skills/docs).