/wix-manage

CMS Schema Management

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 managing the structure (schema) of Wix CMS collections using the REST API.

Prerequisites

1. Wix CMS application installed on the site (appDefId: e593b0bd-b783-45b8-97c2-873d42aacaf4)
2. API access with CMS permissions (Manage Data Collections scope)

Required APIs

• Collections API: REST

List All Collections

Lightweight listing (recommended for existence checks):

curl -X GET \
'https://www.wixapis.com/wix-data/v2/collections?fields=displayName' \
-H 'Authorization: <AUTH>'

Full listing (includes all field schemas):

curl -X GET \
'https://www.wixapis.com/wix-data/v2/collections' \
-H 'Authorization: <AUTH>'

Collection Types: NATIVE (user-created), WIX_APP (Wix app collections), BLOCKS_APP, EXTERNAL

Get Collection Schema

Endpoint: GET https://www.wixapis.com/wix-data/v2/collections/{collectionId}

curl -X GET \
'https://www.wixapis.com/wix-data/v2/collections/Products' \
-H 'Authorization: <AUTH>'

Create a New Collection

Endpoint: POST https://www.wixapis.com/wix-data/v2/collections

{
  "collection": {
    "id": "Products",
    "displayName": "Products",
    "fields": [
      {"key": "title", "displayName": "Title", "type": "TEXT", "required": true},
      {"key": "price", "displayName": "Price", "type": "NUMBER"},
      {"key": "description", "displayName": "Description", "type": "TEXT"},
      {"key": "inStock", "displayName": "In Stock", "type": "BOOLEAN"}
    ],
    "permissions": {
      "insert": "ADMIN",
      "update": "ADMIN",
      "remove": "ADMIN",
      "read": "ANYONE"
    }
  }
}

Add a Field to Existing Collection

Endpoint: POST https://www.wixapis.com/wix-data/v2/collections/create-field

{
  "dataCollectionId": "Products",
  "field": {
    "key": "sku",
    "displayName": "SKU",
    "type": "TEXT",
    "description": "Product SKU code"
  }
}

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).

Single reference — typeMetadata.reference names the referenced collection:

{
  "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:

{
  "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 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 https://www.wixapis.com/wix-data/v2/collections/delete-field

{
  "dataCollectionId": "Products",
  "fieldKey": "sku"
}

Update Collection Settings

Endpoint: PATCH https://www.wixapis.com/wix-data/v2/collections/{collectionId}

{
  "dataCollection": {
    "id": "Products",
    "displayName": "Product Catalog"
  }
}

This works for displayName/displayField. Permission updates currently fail with WDE0075: Not recognized role provided in permissions. Use the full-replace endpoint below to update a collection's permissions.

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 https://www.wixapis.com/wix-data/v2/collections

{
  "collection": {
    "id": "Products",
    "revision": "3",
    "displayName": "Product Catalog",
    "fields": [ /* the collection's full current non-system fields, from GET */ ],
    "permissions": {
      "insert": "ADMIN",
      "update": "ADMIN",
      "remove": "ADMIN",
      "read": "SITE_MEMBER"
    }
  }
}

Don't delete and recreate a collection just to change its permissions — this full-replace call is the working path.

Field Types Reference

Permission Levels

Error Handling

Related Documentation

• Data Collections API Reference
• Data Types in Wix Data
• CMS Data Items CRUD Recipe