Collections
Complex data structures can be integrated into Duda websites via collections. A collection is a list of like items (e.g. staff members, products, events, news articles, etc.), with each object in the list consisting of the same set of properties called fields. For staff members, this might be a name, bio and profile picture. For events it could be a date, time, description and a URL from which to purchase tickets.
Collections are similar to databases or a spreadsheet in that they are made up of fields (similar to columns) that are assigned a data type, and individual items consisting of the values corresponding to each field (similar to rows).
Collection Types
Duda provides two types of collections, internal and external, with the source of the data/values providing the distinction between the two. In internal collections the data is stored directly within Duda. Users are able to edit data either manually within the editor, or programmatically via our collection API endpoints. External collections receive their data from an outside source, via a JSON endpoint. This data is temporarily stored within Duda, but will be revalidated periodically or immediately via an API call. External collections are a great way to ensure outside systems stay the source-of-truth for content displayed on a website.
Field and Data Types
Similar to columns within a relational database, collection fields must be assigned a name and a data type. In Duda, data types are used to associate a field value with the type of widgets that can display that value, in addition to allowing the editor to know what types of formatting are available to the value. For example, a column with URLs as values may be set to be either an image data type or a link data type. Knowing the specific data type lets the Duda editor narrow down the types of widgets that are allowed to use that value.
Collection data can be connected to widgets in the same way it's possible to connect business-level data. However, because collection data is a list of items instead of a single piece of discrete data, only certain widgets are capable of displaying that data on a page. These types of widgets include:
- list widget
- photo gallery widget
- image slider widget
- accordion widget
Once a collection has been connected, you'll be able to connect the individual properties of the items to display within the widget's layout.
Collection Support for APIs and MCP
The tables below outline support for Collections capabilities and field types across the Duda Partner API and the Duda MCP server.
Endpoint paths in the notes below use shorthand notation. The full public API prefix is
/api/sites/multiscreen/{siteAlias}/collection/{collectionName}/...(for example,PUT /field/{name}representsPUT /api/sites/multiscreen/{siteAlias}/collection/{collectionName}/field/{fieldName}). Capabilities marked as Editor/UI only are managed within the Duda editor interface and are not part of the public API.
Schema & Field Types
| Feature | API | MCP | In Plan to Add | Notes |
|---|---|---|---|---|
| Field type — text / rich text | Yes | Yes | TEXT (rich text) and PLAIN_TEXT field types. | |
| Field type — number | Yes | Yes | NUMBER field type (values must be numeric, not strings). | |
| Field type — date | Yes | Yes | DATE_TIME field type. | |
| Field type — email | Yes | Yes | EMAIL field type. | |
| Field type — phone | Yes | Yes | PHONE field type. | |
| Field type — link | Yes | Yes | LINK field type. | |
| Field type — image | Yes | Yes | IMAGE field type. In MCP, create_collection_rows and update_collection_rows resolve an IMAGE value via resolveImageSource when prefixed with image:// or pexels:// (legacy prefix, supported for backwards compatibility). | |
| Field type — video | Yes | Yes | VIDEO field type. | |
| Field type — boolean | Yes | Yes | BOOLEAN field type. Supported in the Partner API and MCP. | |
| Field type — multi-select | Yes | Yes | MULTI_SELECT with multi_select_options. Supported explicitly by MCP create_collection and create_collection_fields. Updating the options array replaces it. | |
| Field type — single-select | Yes | No | Yes | SINGLE_SELECT with single_select_options on collection field definitions. |
| Field type — icon | Yes | No | Yes | ICON. API: cell value must be an object of the form {"icon": "<url>"} and the URL is validated. MCP: field creation works (free-form type), but create_collection_rows / update_collection_rows does not support icon objects. |
| Field type — location | Yes | No | Yes | LOCATION. API: cell value is stored as structured JSON. MCP: field creation works (free-form type), but create_collection_rows / update_collection_rows does not support location objects. |
| Field type — business hours | Yes | No | Yes | BUSINESS_HOURS. API: cell value is stored as structured JSON. MCP: field creation works (free-form type), but create_collection_rows / update_collection_rows does not support structured JSON. |
| Field type — social accounts | Yes | No | Yes | SOCIAL_ACCOUNTS. API: value must be an object of networkName:handleName pairs. MCP: field creation works (free-form type), but create_collection_rows / update_collection_rows does not support social accounts objects. |
| Field type — inner collection | Yes | No | Yes | COLLECTION, defined via inner_collection_fields. MCP: the MCP field schema has no inner_collection_fields parameter, so nested schemas cannot be defined. Nesting is limited to one level deep. |
| Field type — dynamic page | Yes | No | Yes | DYNAMIC_PAGE field type. |
| Field type — store page | Yes | No | Yes | STORE_PAGE field type. API: cell value is StorePageValue. |
| Field type — collection reference | No | No | COLLECTION_REF is a system type and unsupported on internal collections. Deprecated (replaced by dynamic filters). | |
| Field type — file | No | No | No generic FILE field type in the model. Supported media types are IMAGE and VIDEO. | |
| Read collection schema (fields + types) | Yes | Yes | API: GET /collection/{name} returns fields and types. MCP: get_collections returns the schema. | |
| Add field to collection | Yes | Yes | API: POST /collection/{name}/field. MCP: create_collection_fields. | |
| Update field (rename / change type) | Yes | Yes | Rename only. API: PUT /field/{name} (new name). MCP: update_collection_field (name only). Changing a field's type is not supported via API or MCP (editor-only type migration). | |
| Delete field | Yes | Yes | API: DELETE /field/{name}. MCP: delete_collection_field. Removes that field's data across all rows. | |
| Reorder fields | No | No | No dedicated reorder endpoint or tool; field order is managed in the editor. |
Collection Lifecycle
| Feature | API | MCP | In Plan to Add | Notes |
|---|---|---|---|---|
| Create internal collection | Yes | Yes | API: POST /sites/multiscreen/{site}/collection (at least one field required). MCP: create_collection (creates an internal collection when external_details is omitted). | |
| List / read collections on a site | Yes | Yes | API: GET /collection (list) and GET /collection/{name} (detail including fields + rows). MCP: get_collections. | |
| Rename / update collection settings | Yes | No | Yes | API: PUT /collection/{name} (rename + settings). No MCP tool updates collection settings (MCP only updates fields/rows). |
| Publish collection | Yes | No | Yes | API: POST /collection/{name}/publish. No MCP tool for publishing a collection. |
| Delete collection | Yes | No | Yes | API: DELETE /collection/{name}. No MCP delete-collection tool (MCP can delete fields/rows, not the collection). |
Rows & Data
| Feature | API | MCP | In Plan to Add | Notes |
|---|---|---|---|---|
| Create rows | Yes | Yes | API: POST /collection/{name}/row (array of {data}). MCP: create_collection_rows. | |
| Read / list rows | Yes | Yes | API: GET /collection/{name} (returns rows) and POST /query-data. MCP: get_collections — rows included, but unfiltered (no query_collection_rows tool in production). | |
| Update rows | Yes | Yes | API: PUT /collection/{name}/row (each row requires its id). MCP: update_collection_rows (must include row id + all fields). | |
| Delete rows | Yes | Yes | API: DELETE /collection/{name}/row (row ids in body) and DELETE /row/{row_id}. MCP: delete_collection_rows. | |
| Bulk row operations | Yes | Yes | Create, update, and delete row endpoints all accept arrays (batch). MCP tools mirror this (rows[] / row_ids[]). | |
| Filter / sort / paginate rows on read | Yes | No | Yes | API: POST /query-data — filters (EQ/IN/NE/NIN/GT/GTE/LT/LTE/BTWN), sort (ASC/DESC), pagination (pageSize max 200), text search, field projection. MCP: not yet available in production. |
Import & Export
| Feature | API | MCP | In Plan to Add | Notes |
|---|---|---|---|---|
| CSV import into collection | No | No | Editor/UI only. Not exposed in the public Partner API or MCP. | |
| CSV export from collection | No | No | Editor/UI only. Not exposed in the public Partner API or MCP. |
Dynamic Pages & Bindings
| Feature | API | MCP | In Plan to Add | Notes |
|---|---|---|---|---|
| Create dynamic page from a collection | No | No | Dynamic pages are created and laid out in the editor. External collections auto-generate pages, but creating the dynamic page itself is not a public API/MCP action. | |
| Dynamic page URL / slug rules | Yes | Yes | Slug source only: external_details.page_item_url_field (create/update collection) and per-row page_item_url (update rows / MCP update_collection_rows). Full URL-rule configuration is done in the editor. | |
| Bind dynamic page body to collection fields | No | No | Binding widgets on a page to collection fields is done in the editor (regular_page_bindable only toggles whether data can be bound on non-dynamic pages; the older static_page_bindable is marked deprecated). | |
| Bind page head / SEO tags to collection fields | No | No | Binding page head / SEO tags to collection fields is done in the editor. |
Multi-Language
| Feature | API | MCP | In Plan to Add | Notes |
|---|---|---|---|---|
| Write multi-language field values | No | No | Partial: create/update rows write only to the collection's default language (no per-language write parameter), so per-language translated values cannot be set via API/MCP — editor only. | |
| Read multi-language field values | Yes | No | Yes | API: POST /query-data — body field language (enum, ~90 locales). GET /collection returns default-language data only. MCP: No — get_collections returns default-language data only. |
Other Capabilities
| Feature | API | MCP | In Plan to Add | Notes |
|---|---|---|---|---|
| External collections (connect external data source) | Yes | Yes | API: create collection with external_details (external_endpoint, authorization_header_value, collection_data_json_path, custom_headers, external_id, page_item_url_field); revalidate via /revalidate. MCP: create_collection supports external collections. | |
| Revalidate / refresh external collection data | Yes | No | Yes | API: POST /collection/{name}/revalidate and POST /collections/revalidate/{external_id} (clear cache / refresh external data). No MCP tool. |
| Membership-gated collection content | No | No | Gating collection-driven content behind site membership is configured via the membership product / editor, not the collections API or MCP. | |
| Store catalog collection (read / write) | No | No | The store catalog is a system collection managed via the Store / catalog APIs & tools (e.g. store product endpoints/tools), not the collections API/MCP. It may appear read-only in collection listings. |
Caching
By default, Duda caches the data for an external collection to help with performance. By default, we cache a collection up to 2hrs. If you want to update the data in the site immediately, you can use one of the revalidate calls.
Limitations
The following limitations exist for Internal and External Collections.
| Internal | External | |
|---|---|---|
| Number of collections per site | 100 (including image collections) | 100 (including image collections) |
| Rows | 500 | |
| Fields | 50 | 100 |
| Max options on multi-select field type | 30 | 30 |
| Inner collection rows | NA | |
| Inner collection fields | NA | 15 |
| Text field character limit | 2000 | |
| Collection name character limit | 50 | 50 |
| Field name character limit | 50 | 50 |
| Page item URL character limit | 350 | 350 |
| Update data | Publish site/content library | Automatic |
Updated 15 days ago