@wix/agent-skills 1.24.0 → 1.25.0

package/skills/wix-manage/references/cms/cms-references-and-relationships.md

@@ -1,162 +0,0 @@
----
-name: "CMS References And Relationships"
-description: "Add, replace, or remove items from MULTI_REFERENCE fields. Use insert-references, replace-references, remove-references endpoints. Required for managing multi-reference relationships - these CANNOT be set via regular insert/update/patch operations. Also covers single references and querying with expanded references."
----
-# CMS References & Relationships
-
-> **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 linking CMS collections together using reference fields.
-
-## Prerequisites
-
-1. Wix CMS enabled on the site
-2. At least two collections to link together
-3. API access with CMS permissions
-
-## Required APIs
-
-- **Collections API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/introduction)
-- **Data Items API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/introduction)
-
-## Reference Types
-
-| 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 |
-
-## Add a Single Reference Field
-
-**Endpoint**: `POST /wix-data/v2/collections/create-field`
-
-```bash
-curl -X POST \
-'https://www.wixapis.com/wix-data/v2/collections/create-field' \
--H 'Content-Type: application/json' \
--H 'Authorization: <AUTH>' \
--d '{
-  "dataCollectionId": "Products",
-  "field": {
-    "key": "category",
-    "displayName": "Category",
-    "type": "REFERENCE",
-    "typeMetadata": {
-      "reference": {
-        "referencedCollectionId": "Categories"
-      }
-    }
-  }
-}'
-```
-
-## Add a Multi-Reference Field
-
-**Endpoint**: `POST /wix-data/v2/collections/create-field`
-
-```bash
-curl -X POST \
-'https://www.wixapis.com/wix-data/v2/collections/create-field' \
--H 'Content-Type: application/json' \
--H 'Authorization: <AUTH>' \
--d '{
-  "dataCollectionId": "Products",
-  "field": {
-    "key": "tags",
-    "displayName": "Tags",
-    "type": "MULTI_REFERENCE",
-    "typeMetadata": {
-      "multiReference": {
-        "referencedCollectionId": "Tags",
-        "referencingFieldKey": "products",
-        "referencingDisplayName": "Products"
-      }
-    }
-  }
-}'
-```
-
-## Insert Multi-Reference Links
-
-**Endpoint**: `POST /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 /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 /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 /wix-data/v2/items/query`
-
-```json
-{
-  "dataCollectionId": "Products",
-  "query": {
-    "filter": {
-      "inStock": true
-    }
-  },
-  "includeReferencedItems": ["category", "tags"]
-}
-```
-
-## 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"] } }` |
-
-## Related Documentation
-
-- [Data Items API Reference](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/introduction)
-- [Collections API Reference](https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/introduction)
-- [CMS Schema Management Recipe](cms-schema-management.md)