The Data Collections API enables you to create, delete, and modify the structure of data collections in a Wix site.
Wix sites store data in collections. A collection determines the structure of the data to be stored, defining the fields each item contains, and the data type of each field. Wix users can create and modify collections for their site using the Content Management System (CMS).
With the Data Collections API, you can use code to create, modify, and delete collections in a Wix site. You can then store and retrieve data in these collections using the Data Items API.
Note: The structure you define for a data collection isn't enforced. This means that if you add or update an item containing a field or data type that doesn't match the collection's structure, your data is stored anyway.
Access to a data collection is controlled by its permissions. These permissions are defined in the collection object and they specify which types of user can perform actions on the data contained in the collection.
Wix Data recognizes 4 roles:
ADMIN
: The site owner.SITE_MEMBER_AUTHOR
: A signed-in user who has added content to the collection.SITE MEMBER
: Any signed-in user.ANYONE
: Any site visitor.For each of the 4 basic actions (inserting, updating, removing, and reading content) the minimal role required must be set. For example, if you want to allow only site members to view data, and only the site owner to insert, update, and remove data, declare your permissions as follows:
insert
: ADMIN
update
: ADMIN
remove
: ADMIN
read
: SITE_MEMBER
A data collection determines the structure of data to be stored in a database.
Collection ID. For example, my-first-collection
. May include a namespace.
Collection type. Indicates how the collection was created and how it is stored.
ID of the app that defined this collection. For collections defined by Wix users, this value is null.
Maximum number of items returned in a single query, based on the underlying storage. Native collections have a maximum page size of 1000 for offset-based queries or 100 for cursor-based queries. External collections' maximum page size defaults to 50, but an external provider can set any maximum value up to 1000.
Collection's display name as shown in the CMS. For example, My First Collection
.
Default item sorting order when a query doesn't specify one.
UI-friendly namespace of the Wix app with which the data collection is associated, such as Stores or Bookings. Empty for all data collections not owned by Wix apps.
Field whose value the CMS displays to represent the collection item when referenced in a different collection.
Capabilities the collection supports.
Collection's field structure.
Levels of permission for accessing and modifying data, defined by lowest role needed to perform each action.
Collection's current revision number, which increments each time the collection is updated. For an update operation to succeed, you must specify the latest revision number.
Plugins the collection uses. Plugins apply additional capabilities to the collection or extend its functionality.
Paging modes the collection supports. In native collections, offset-based paging is supported by default.
Date the collection was created.
Date the collection was last updated.
Updates a data collection.
A collection ID, revision number, permissions, and at least 1 field must be provided within the collection
body parameter.
If a collection with that ID exists, and if its current revision
number matches the one provided, it is updated.
Otherwise, the request fails.
When a collection is updated, its updatedDate
property is changed to the current date and its revision
property is incremented.
Note: After a collection is updated, it only contains the properties included in the Update Data Collection request. If the existing collection has properties with values and those properties aren't included in the updated collection details, their values are lost.
You can only call this method when authenticated as a Wix app or Wix user identity.
Updated collection details. The existing collection is replaced with this version.
Updated collection details.
curl -X PUT \
'https://www.wixapis.com/wix-data/v2/collections' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
--data-raw '{
{
"id": "my-first-collection",
"revision": "1",
"displayName": "Author Collection",
"fields": [
{"key": "first_name", "displayName": "First Name", "type": "TEXT"},
{"key": "last_name", "displayName": "Last Name", "type": "TEXT"}
],
"permissions": {
"insert": "ADMIN",
"update": "ADMIN",
"remove": "ADMIN",
"read": "ANYONE"
}
}'
{
"collection": {
"id": "my-first-collection",
"collectionType": "NATIVE",
"displayName": "Author Collection",
"displayField": "first_name",
"capabilities": {
"dataOperations": [
"AGGREGATE",
"BULK_INSERT",
"BULK_REMOVE",
"BULK_SAVE",
"BULK_UPDATE",
"COUNT",
"DISTINCT",
"FIND",
"GET",
"INSERT",
"INSERT_REFERENCE",
"IS_REFERENCED",
"QUERY_REFERENCED",
"REMOVE",
"REMOVE_REFERENCE",
"REPLACE_REFERENCES",
"SAVE",
"TRUNCATE",
"UPDATE"
],
"collectionOperations": ["UPDATE", "REMOVE"]
},
"fields": [
{
"key": "first_name",
"displayName": "First Name",
"type": "TEXT",
"systemField": false,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
},
{
"key": "last_name",
"displayName": "Last Name",
"type": "TEXT",
"systemField": false,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
},
{
"key": "_id",
"displayName": "ID",
"type": "TEXT",
"systemField": true,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
},
{
"key": "_owner",
"displayName": "Owner",
"type": "TEXT",
"systemField": true,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
},
{
"key": "_createdDate",
"displayName": "Created Date",
"type": "DATETIME",
"systemField": true,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
},
{
"key": "_updatedDate",
"displayName": "Updated Date",
"type": "DATETIME",
"systemField": true,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
}
],
"permissions": {
"insert": "ADMIN",
"update": "ADMIN",
"remove": "ADMIN",
"read": "ANYONE"
},
"revision": "2",
"plugins": [],
"pagingModes": ["OFFSET"],
"createdDate": "2022-09-19T15:10:56.603Z",
"updatedDate": "2022-09-22T11:29:41.822Z"
}
}
Retrieves a list of all data collections associated with the site or project.
By default, the list is ordered by ID in ascending order.
You can only call this method when authenticated as a Wix app or Wix user identity.
Name of the field to sort by.
Sort order.
Number of items to load.
Number of items to skip in the current sort order.
Whether to retrieve data from the primary database instance. This decreases performance but ensures data retrieved is up to date even immediately after an update. Learn more about Wix Data and eventual consistency.
Default: false
List of specific field names to return, if empty all fields are returned. Affects all returned collections
List of collections.
Paging information.
curl -X GET \
'https://www.wixapis.com/wix-data/v2/collections' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>'
{
"collections": [
{
"id": "my-second-collection",
"collectionType": "NATIVE",
"displayField": "name",
"capabilities": {
"dataOperations": [
"AGGREGATE",
"BULK_INSERT",
"BULK_REMOVE",
"BULK_SAVE",
"BULK_UPDATE",
"COUNT",
"DISTINCT",
"FIND",
"GET",
"INSERT",
"INSERT_REFERENCE",
"IS_REFERENCED",
"QUERY_REFERENCED",
"REMOVE",
"REMOVE_REFERENCE",
"REPLACE_REFERENCES",
"SAVE",
"TRUNCATE",
"UPDATE"
],
"collectionOperations": ["UPDATE", "REMOVE"]
},
"fields": [
{
"key": "title",
"displayName": "Book title",
"type": "TEXT"
},
{
"key": "author_ref",
"displayName": "Book author",
"type": "REFERENCE",
"typeMetadata": {
"reference": { "referencedCollection": "my-first-collection" }
}
}
],
"permissions": {
"insert": "ADMIN",
"update": "ADMIN",
"remove": "ADMIN",
"read": "ADMIN"
},
"revision": "1",
"plugins": [],
"pagingModes": ["OFFSET"],
"createdDate": "2022-09-19T15:15:59.099Z",
"updatedDate": "2022-09-19T15:15:59.099Z"
},
{
"id": "my-first-collection",
"collectionType": "NATIVE",
"displayName": "My First Collection",
"displayField": "name",
"capabilities": {
"dataOperations": [
"AGGREGATE",
"BULK_INSERT",
"BULK_REMOVE",
"BULK_SAVE",
"BULK_UPDATE",
"COUNT",
"DISTINCT",
"FIND",
"GET",
"INSERT",
"INSERT_REFERENCE",
"IS_REFERENCED",
"QUERY_REFERENCED",
"REMOVE",
"REMOVE_REFERENCE",
"REPLACE_REFERENCES",
"SAVE",
"TRUNCATE",
"UPDATE"
],
"collectionOperations": ["UPDATE", "REMOVE"]
},
"fields": [
{
"key": "name",
"displayName": "First Name",
"type": "TEXT",
"systemField": false,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
},
{
"key": "age",
"displayName": "Age",
"type": "NUMBER",
"systemField": false,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
},
{
"key": "_id",
"displayName": "ID",
"type": "TEXT",
"systemField": true,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
},
{
"key": "_owner",
"displayName": "Owner",
"type": "TEXT",
"systemField": true,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
},
{
"key": "_createdDate",
"displayName": "Created Date",
"type": "DATETIME",
"systemField": true,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
},
{
"key": "_updatedDate",
"displayName": "Updated Date",
"type": "DATETIME",
"systemField": true,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
}
],
"permissions": {
"insert": "ADMIN",
"update": "ADMIN",
"remove": "ADMIN",
"read": "ADMIN"
},
"revision": "1",
"plugins": [],
"pagingModes": ["OFFSET"],
"createdDate": "2022-09-19T15:10:56.603Z",
"updatedDate": "2022-09-19T15:10:56.603Z"
}
],
"pagingMetadata": {
"count": 2,
"offset": 0,
"total": 2,
"tooManyToCount": false
}
}
Creates a new data collection.
The request body must include an ID, details for at least 1 field, and a permissions object. If any of these are missing, the collection isn't created.
You can only call this method when authenticated as a Wix app or Wix user identity.
Collection details.
Details of collection created.
curl -X POST \
'https://www.wixapis.com/wix-data/v2/collections' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
--d '{
"id": "my-first-collection",
"displayName": "My First Collection",
"fields": [
{
"key": "name",
"displayName": "First Name",
"type": "TEXT"
},
{
"key": "age",
"displayName": "Age",
"type": "NUMBER"
}
]
}'
{
"collection": {
"id": "my-first-collection",
"collectionType": "NATIVE",
"displayName": "My First Collection",
"displayField": "name",
"capabilities": {
"dataOperations": [
"AGGREGATE",
"BULK_INSERT",
"BULK_REMOVE",
"BULK_SAVE",
"BULK_UPDATE",
"COUNT",
"DISTINCT",
"FIND",
"GET",
"INSERT",
"INSERT_REFERENCE",
"IS_REFERENCED",
"QUERY_REFERENCED",
"REMOVE",
"REMOVE_REFERENCE",
"REPLACE_REFERENCES",
"SAVE",
"TRUNCATE",
"UPDATE"
],
"collectionOperations": ["UPDATE", "REMOVE"]
},
"fields": [
{
"key": "name",
"displayName": "First Name",
"type": "TEXT",
"systemField": false,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
},
{
"key": "age",
"displayName": "Age",
"type": "NUMBER",
"systemField": false,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
},
{
"key": "_id",
"displayName": "ID",
"type": "TEXT",
"systemField": true,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
},
{
"key": "_owner",
"displayName": "Owner",
"type": "TEXT",
"systemField": true,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
},
{
"key": "_createdDate",
"displayName": "Created Date",
"type": "DATETIME",
"systemField": true,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
},
{
"key": "_updatedDate",
"displayName": "Updated Date",
"type": "DATETIME",
"systemField": true,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
}
],
"permissions": {
"insert": "ADMIN",
"update": "ADMIN",
"remove": "ADMIN",
"read": "ADMIN"
},
"revision": "1",
"plugins": [],
"pagingModes": ["OFFSET"],
"createdDate": "2022-09-19T15:10:56.603Z",
"updatedDate": "2022-09-19T15:10:56.603Z"
}
}
Retrieves a data collection by ID.
ID of the collection to retrieve.
Whether to retrieve data from the primary database instance. This decreases performance but ensures data retrieved is up to date even immediately after an update. Learn more about Wix Data and eventual consistency.
Default: false
List of specific field names to return, if empty all fields are returned. Affects all returned collections
Details of the collection requested.
Details of collections referenced by the collection requested.
Only populated when includeReferencedCollections
is true
in the request.
curl -X GET \
'https://www.wixapis.com/wix-data/v2/collections/my-first-collection' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>'
{
"collection": {
"id": "my-first-collection",
"collectionType": "NATIVE",
"displayName": "My First Collection",
"displayField": "name",
"capabilities": {
"dataOperations": [
"AGGREGATE",
"BULK_INSERT",
"BULK_REMOVE",
"BULK_SAVE",
"BULK_UPDATE",
"COUNT",
"DISTINCT",
"FIND",
"GET",
"INSERT",
"INSERT_REFERENCE",
"IS_REFERENCED",
"QUERY_REFERENCED",
"REMOVE",
"REMOVE_REFERENCE",
"REPLACE_REFERENCES",
"SAVE",
"TRUNCATE",
"UPDATE"
],
"collectionOperations": ["UPDATE", "REMOVE"]
},
"fields": [
{
"key": "name",
"displayName": "First Name",
"type": "TEXT",
"systemField": false,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
},
{
"key": "age",
"displayName": "Age",
"type": "NUMBER",
"systemField": false,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
},
{
"key": "_id",
"displayName": "ID",
"type": "TEXT",
"systemField": true,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
},
{
"key": "_owner",
"displayName": "Owner",
"type": "TEXT",
"systemField": true,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
},
{
"key": "_createdDate",
"displayName": "Created Date",
"type": "DATETIME",
"systemField": true,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
},
{
"key": "_updatedDate",
"displayName": "Updated Date",
"type": "DATETIME",
"systemField": true,
"capabilities": {
"sortable": true,
"queryOperators": [
"EQ",
"LT",
"GT",
"NE",
"LTE",
"GTE",
"STARTS_WITH",
"ENDS_WITH",
"CONTAINS",
"HAS_SOME",
"HAS_ALL",
"EXISTS",
"URLIZED"
]
},
"encrypted": false
}
],
"permissions": {
"insert": "ADMIN",
"update": "ADMIN",
"remove": "ADMIN",
"read": "ADMIN"
},
"revision": "1",
"plugins": [],
"pagingModes": ["OFFSET"],
"createdDate": "2022-09-19T15:10:56.603Z",
"updatedDate": "2022-09-19T15:10:56.603Z"
},
"referencedCollections": []
}
Deletes a data collection.
Note: Once a collection is deleted, it can only be restored for limited amount of time.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the collection to delete.
curl -X DELETE \
'https://www.wixapis.com/wix-data/v2/collections/my-first-collection' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>'
{}