# General concepts — What is DatoCMS? Source [docs]: https://www.datocms.com/docs/general-concepts.md DatoCMS is a cloud-based headless CMS designed to work with websites, mobile apps, and server-side applications of any kind. Freelancers, agencies, and startups use DatoCMS to empower non-technical clients and team members to manage the content of their digital products within a web-based CMS. #### What does "headless CMS" mean? A headless CMS clearly separates the actual content from the display layer and the front-end user experience. The headless CMS concept stems from the demands of the digital era and a business’s need to engage customers with personalized content via multiple channels at all stages of the customer journey. As the content in a headless CMS is considered *pure* (because it has no presentation layer attached), just one instance of it can be used for display on any device: websites (both desktop and mobile), apps, smartwatches, digital signage, Internet of Things devices, etc. To learn more, you can read our [Introduction to Headless CMS](https://www.datocms.com/academy/headless-cms/introduction-to-headless-cms.md) over at the DatoCMS academy. #### API-first DatoCMS provides a content infrastructure that comprises different APIs for working with your content. Each of these APIs serves a different purpose, so which one to use depends on what you want to do: - To obtain content for presentation to users on a website or app, it is recommended that you utilize either the [Content Delivery API](/docs/content-delivery-api.md) or the [Real-time Updates API](/docs/real-time-updates-api.md). The latter is preferable if you require dynamic content that can be updated in real-time, delivering events as they happen. - If you want to programmatically create or update content items, or make any other change to your project/schema, use the [Content Management API](/docs/content-management-api.md). #### One account, multiple projects Once you sign up to DatoCMS and create your account, you'll be able to create an arbitrary number of different projects. For each project you'll be given an administrative area at a specific domain (i.e., `[my-project].admin.datocms.com`) from which you'll be able to invite collaborators to manage its specific content. All the projects you create will be completely isolated from each other. ### New to DatoCMS? If you want to get started with DatoCMS and learn the basics, check out these video tutorials for beginners! [ (Image content) A gentle overview of all the features of DatoCMS Play video » ](https://www.youtube.com/watch?v=ALHwdztg0UQ) [ (Image content) Creating a localized blog using Next.js Play video » ](https://youtu.be/3tBeOwdVuwo) [ (Image content) Next.js + DatoCMS tutorial for beginners Play video » ](https://www.youtube.com/watch?v=_VIF1if-dNA) --- # General concepts — Workspaces: Organizations and Personal Accounts Source [docs]: https://www.datocms.com/docs/general-concepts/organizations-and-accounts.md When you only have a single DatoCMS project, it's simple to organize: just one project under one account. But when teams grow larger, they may need more powerful organizational tools. DatoCMS provides two kinds of workspaces (project groupings): (Image content) Workspaces and Projects ### Personal Accounts **Personal account** workspaces are designed for individual use. This is the default kind of workspace when you create a new project under a personal account. In this kind of workspace, projects belong to a single account (your DatoCMS login), and other people can participate only as **Project Collaborators** that you invite inside the project itself. This is the right choice when someone simply needs to work on the content or configuration of a specific project. ### Organizations **Organization** workspaces are built for teams who need to share billing, account management, and workspace-level settings, not just work on projects together. In an organizational workspace: - **Project Collaborators** are invited into specific projects, with specific [per-project roles and permissions](/docs/general-concepts/roles-and-permission-system.md) - **Organization Members** belong to the workspace itself, outside of any projects, and their workspace-level permissions control access to billing, account settings, and organization-level management. These permissions are detailed on the rest of this page. A person can be both a **Collaborator** on a project and an **Organization Member** of the workspace, and the two roles are independent. A person's account can belong to any number of projects as a collaborator, and to any number of organizations as a member. > [!PROTIP] Pro tip: Projects have Collaborators and Organizations have Members > Remember: > > - **Collaborator** roles determine what a person can see and edit inside a specific **project**. > > - **Organization Member** roles determine what a person can see and edit inside the entire **organization workspace**. ## Creating an organization You can create an organization by clicking on the scope selector in the top left of the nav bar. When you create a new organization, you will be prompted to give that team a name. This is the name your organization will have on your dashboard, and what other members will use to access your organization. (Video content) ##### Converting a Personal Account into a new organization At any time, you can move all projects, your plan, credit card and billing information linked to your personal account to a new organization. This can be especially useful for all those personal accounts created before organizations were available in DatoCMS. To convert your personal account into an organization, go to the **Edit Account** tab, and select the option "Move projects and billing information to a new organization". (Video content) Your personal account will be switched to a free Developer plan, and the new organization will hold all of your existing projects and billing information. You will also become the first owner of the newly created organization. ## Organization member permissions: Owners and Viewers When you invite someone to a DatoCMS organization, they become a **Member**. Each member can be an **Owner** or **Viewer:** ### **Organization Owners** **Owners** have full privileges to the organization and all of its projects. An owner can manage billing, change the subscription plan, invite other members to the organization, manage all projects' settings, and **automatically enter any organization-owned project with full privileges** (even without an explicit Collaborator seat inside the project). They are also the only members who can delete the organization. > [!POSITIVE] Organizations can have more than one owner! > For the sake of ownership continuity for your organization, it would ideally have at least two members with owner permissions (e.g., perhaps a manager and a billing person). This helps ensure your DatoCMS organization will continue to be accessible in the event of turnover. > > Adding additional owners will not remove any existing ownership. Each owner has their own login and can independently access and modify the organization as necessary. ### **Organization Viewers** **Viewers** can only view organization settings. They cannot change them. This role can be useful for people on your team who deal with finance/invoices/administration, so that they can download invoices and track costs without making accidental changes to existing projects or the organization itself. Unlike Owners, Viewers **do not have automatic, implicit access to the organization's projects**. They can only enter projects if they have an explicitly defined Collaborator seat inside those specific projects that grant them access. ### Table of Owner & Viewer Permissions The table below summarizes the permissions for each type of member: | Permission | Owner | Viewer | | --- | --- | --- | | Manage members/roles | ✅ Yes | 👁️ View-only Can see other org members, but not add/remove/change them. | | Manage plan and billing | ✅ Yes | 👁️ View-only Can view and download invoices, but not edit billing. | | Transfer projects | ✅ Yes | ❌ No | | Rename/delete organization | ✅ Yes | ❌ No | | Create/edit/delete projects | ✅ Yes | ❌ No | | Enter the organization's projects | ✅ Automatic full access Has automatic, implicit, fully privileged access to all projects owned by the organization — even without an explicit Collaborator seat in the project. | ❌ No automatic access Does NOT have any implicit access via the org. Can only enter project if they have a separate Collaborator seat inside the project. | ### Organizational email notifications Organization **owners** will also receive email notifications for important events, like account payment issues and subscription deactivations/reactivations. Org **viewers** and project **collaborators** will *not* receive these emails. Please see details at: [Payment failures and billing notifications](/docs/plans-pricing-and-billing/payment-failures-and-billing-notifications.md) > [!POSITIVE] Partner specific roles > Organizations that have been accepted through our [partner program](https://www.datocms.com/partner-program.md) have access to additional roles to manage their projects across clients, as you can check out [here](/docs/agency-partner-program/partners-dashboard.md#developer-and-projects-manager-roles) ### Inviting new members To invite new members to your organization, select the organization from the scope selector, then open the **Members** tab. Enter the email address of the person you would like to invite, select their role, and click the "Invite" button. (Video content) As the organization Owner, you can add new members, remove existing members, and change their roles. Members who have accepted an invitation to the team will be displayed as members with their assigned roles. ### Different ways to enter a project: Project owners, Organization Members, and Collaborators Let's recap the ways in which one can enter a DatoCMS project: ##### If the project is inside a personal account - The owner account always enters the project with full privileges, **even if they are not explicitly listed as a collaborator**. They have implicit admin permissions due to their ownership. - Accounts invited as [collaborators](/docs/general-concepts/roles-and-permission-system.md) within the project enter with the permissions of the specific [role](/docs/general-concepts/roles-and-permission-system.md) they have been given. ##### If the project is inside an organization - Members of the organization with the Owner roleenter the project with full privileges. - Accounts invited as [collaborators](/docs/general-concepts/roles-and-permission-system.md) within the project, enter with the permissions of the specific [role](/docs/general-concepts/roles-and-permission-system.md) they have been assigned. > [!WARNING] Collaborators take precedence over organization memberships > Within an organization, there is a further possibility worth emphasizing: if a member of the organization has also been invited as a collaborator, **the role as collaborator takes precedence**: they do not enter with full privileges, but with the permissions of the specific role they have been assigned as collaborator. Take, for instance, a case in which someone is responsible for billing matters but will not interact with content. In this case, it would be reasonable for them to be an organization owner (so as to modify billing information) but to also be invited to the project as collaborator using a role with few privileges — probably read-only. Also consider a user who is totally in charge of a marketing website, but should not have power within the organization itself. This user should be invited as collaborator with full privileges to the project, but should be a simple Viewer at the organization level, if they are even to belong to the organization at all. ### Leaving an organization To leave an organization, select the organization from the scope selector, then open the Members tab. Find your account in the list of members, and then press the "Leave the organization" button. (Video content) > [!WARNING] At least one member must be owner! > You can't leave an organization if you are the last remaining owner. To leave an organization, first assign the owner role to at least one organization member. > > If you are the only remaining member, you should delete the team instead. ### Forgotten Password? If you forgot the password to your DatoCMS account, you can easily [reset it](https://dashboard.datocms.com/forgot-password). You will receive an email reset link to the email associated with your login. ### Losing Access to Your Two-Factor Authentication If you find yourself unable to access your account due to issues with two-factor authentication (2FA), there are immediate steps you can take to regain access. You have two options: 1. Locate your One-Time Password (OTP) backup codes that were provided at the time you set up 2FA. These codes can be used in place of the 2FA code to log into your account. 2. If you have lost your OTP backup codes as well, or have used them all, please [contact our support team](https://www.datocms.com/support.md?topics=account-access/account-login-and-recovery) for assistance. #### Asking your organization owners for a 2FA reset Alternatively, if you do not have any personal projects and your account belongs to only one organization (meaning you are either a member of the organization or a collaborator on one of its projects), you may request a 2FA reset through your organization. To start this process, at the Authentication Code prompt, click on "Lost access to two-factor authentication." Then, select "Request 2FA reset." (Video content) The owners of your organization will be notified by email and within the Dashboard, where they can either accept or refuse your request. (Video content) After one of the organization's owners approves your request, you will be notified via email that 2FA has been disabled on your account . This will allow you to log back into the Dashboard and set up 2FA from scratch for projects that require it. (Video content) --- # General concepts — Project collaborators, roles and permissions Source [docs]: https://www.datocms.com/docs/general-concepts/roles-and-permission-system.md > [!PROTIP] Pro tip: Project Collaborators vs Organization Members > There are two main ways to invite another user to work on a project with you: > > - If they only need to work on **content** inside your CMS, you're on the right page! Invite them as a Collaborator (see below). > > - But if you want them to be able to see or change **billing and account information**,[invite them as an **Organization Member**](/docs/general-concepts/organizations-and-accounts.md) instead. > > > Someone can be both a Collaborator and an Organization Member, and that's OK. Their project Collaborator permissions determine what content they can edit, and their Organization Member permissions determine what billing/account info they can see or edit. > > **Remember: Collaborators determine project permissions. Organization Membership determines account permissions.** In addition to the [account(s) owner of the project](/docs/general-concepts/organizations-and-accounts.md#entering-a-project-project-owners-vs-collaborators), who always enters the project with full privileges, it is also possible to invite further users to a project, giving them more refined permissions. These additional users in DatoCMS are called **Collaborators**, and for them DatoCMS offers a thorough roles and permissions system to precisely specify what actions they can perform (ie., “read-only permission on every content, except for articles which can be freely created/updated but cannot be deleted or published online”). (Image content) The permissions given to a collaborator is managed separately and independently in each DatoCMS project: ie. Jack can have full privileges in project A, but can be just a proofreader in project B. ### Default roles Every DatoCMS project is automatically populated with the following roles, but you are free to create as many roles as you want, and assign them both to collaborators and API tokens: - **Admin:** Can do everything, including work with records, create and update models, configure project settings and work with API keys. - **Editor:** Can work with records, does not have access to models, API keys or project settings. For each role, you can specify what the user is allowed and not allowed to do. ### Project-wide permissions Roles can grant/deny the ability to access and configure the project's administrative settings, including: - Models, fields and navigation bar; - Project's languages, deployment, time zones and SSO settings; - Roles and invite/remove collaborators; - Webhooks; - API tokens; - Shared filters. (Image content) ### Control access to environments Roles specify *access-level permissions* to [environments](/docs/general-concepts/primary-and-sandbox-environments.md). You can allow users to access: - All environments (useful for developers) - Only the primary environment (useful for content editors) - Only the sandbox environments (mostly useful for API tokens used in CI systems) (Image content) This setting is very useful because it allows you to pre-configure the content-level permissions (which records a user can create/update/delete/etc.) on sandbox environments without letting editors actually enter the environment and make changes until it gets [promoted to primary](/docs/general-concepts/primary-and-sandbox-environments.md#promotion-of-sandbox-environments). In other words, the permission to access the environments takes precedence over the content-level permissions set inside a specific environment! ### Content-level permissions For each environment, you can specify different permissions on actions that can be performed on records. Rules can be additive or subtractive, and are defined by: - **The action:** - View - Create/duplicate - Edit - Publish/unpublish - Delete - Take over - Move to stage (for [workflows](/docs/general-concepts/workflows.md)) - **The model:** i.e., it's possible to give full access (everything allowed) to the model `meal`, but give zero access (can't even read) to the model `drink`. - **The creator:** i.e., it's possible to edit only the content which the user has created themselves (or users with its same role), and deny opening content created by other users. The most important aspect is that **everything which is not explicitly allowed is denied**. Here's an example: if you've granted a user the permission to edit some records, you also need to give them permissions to *view* them, or they won't be able to open the record and make the changes. Even though it might feel counter-intuitive, this way of handling access rights helps to prevent unsolicited access: when you set up everything explicitly, there is no chance of accidentally giving someone access to something they shouldn't have. #### Translator role, and locales permissions On an Enterprise plan, your project and models can have locale-specific permissions. For each translator role, you can define the specific locale(s) they have access to, limiting their ability to view/add/edit/remove records to just those languages. This can be applied either globally across your whole project, or more granularly defined on a per-model basis. Need locale-specific permissions? [Talk to our Sales team about an Enterprise plan](https://www.datocms.com/contact.md). (Image content) Every role can customize which locales can be edited #### Workflows permissions If some of your models are under a [Workflow](/docs/general-concepts/workflows.md), you can also define which actions are allowed depending on the specific stage a record is in. You can learn more in the [appropriate section](/docs/general-concepts/workflows.md#how-to-configure-workflows) of the documentation. #### Forking the environments When [forking an environment](/docs/general-concepts/primary-and-sandbox-environments.md#creating-a-new-sandbox-environment), for each existing role, DatoCMS duplicates the content-level permissions you had on the original environment to the copy. ### Asset permissions Together with the actions that you can perform on the records, similarly you can apply the following permissions on assets: - **The action:** - View - Create/duplicate - Edit metadata/replace asset - Delete - Edit creator - **The creator:** i.e., it's possible to edit only the assets which the user has created themselves (or users with its same role), and deny using assets created by other users. ### Asset Collection permissions If you're using Asset Collections, you can also assign specific permissions for users to those, including read, write, and a new dedicated `move` permission that controls whether users can move assets from one collection to another. (Video content) Permissions assigned to a collection are automatically inherited by its sub-collections, with inheritance rules clearly displayed in the UI. ## Putting everything together with an example To better exemplify, let’s consider a project that: - has only one environment (the primary one), and - has a *Blog Editor* role that: - **Access-level permission:**only gives access to the primary environment, and... - **Content-level permission**: …only allows to manage records of type `article`. If I fork the primary environment to a new one called `foobar`, the content-level permissions get duplicated (that is, blog editors can only manage records of type `article` also inside the `foobar` environment). **But** **they will only be able to do so when the** **`foobar`** **environment gets promoted to primary**, since the access-level permission doesn't give them access to sandbox environments. This allows to safely test and experiment changes to permissions on the roles without affecting the work of your collaborators on the primary environment, and without giving them privileges to edit sandbox environments. ## Roles inheritance As your project grows and evolves, permissions on each role can become quite complex. To allow greater modularity, simplicity and clarity, you can organize your roles in hierarchies. In this way, users with greater rights automatically inherit all the permissions of roles lower in the hierarchy, without having to duplicate permissions assignments for multiple different roles. (Image content) An example of what you can accomplish with inherited roles You can configure the hierarchy using the “Inherits permissions from” field in the Edit role form: (Image content) Every role can specify the list of roles to inherit permissions from #### Learn more about roles and permissions Get a hands-on learning experience with our tutorial videos: [ (Image content) Intro to Settings & Configurations Play video » ](https://www.datocms.com/user-guides/the-basics/intro-to-settings-configurations.md) [ (Image content) Using Roles for Content Governance Play video » ](https://youtu.be/_5bwi9SsGss) --- # General concepts — The content schema Source [docs]: https://www.datocms.com/docs/general-concepts/data-modelling.md DatoCMS can be seen as an editor-friendly interface on top of a database, so the first step is to build the actual schema upon which users will generate the website content. #### Models The way you define the kind of content you can edit inside each different administrative area involves the concept of models, which are like database tables. Each administrative area can specify a number of different models, and they represent blueprints upon which users will store the website content. For example, a website project can define different models for articles, products, categories, and so on. #### Fields Each model consists of a set of fields that you define (strings, numbers, uploads, videos, relationships between objects). Each field has a name and additional metadata, such as validations or particular configurations to better present the field to the editor. Fields in DatoCMS can also be localized if you need to accept different values based on language. #### Records DatoCMS stores the individual pieces of content you create from a model as records, which are like table rows in a database. [ (Image content) Intro to the Schema Builder Play video » ](https://www.datocms.com/user-guides/the-basics/intro-to-the-schema-builder.md) [ (Image content) Intro to Models in DatoCMS Play video » ](https://www.datocms.com/user-guides/content-modeling/intro-to-models-in-datocms.md) [ (Image content) Intro to Fields in DatoCMS Play video » ](https://www.datocms.com/user-guides/content-modeling/intro-to-fields-in-datocms.md) --- # General concepts — Organizing content Source [docs]: https://www.datocms.com/docs/general-concepts/navigation-bar.md Every time a new model is created, a new menu item is automatically added to the **Content** tab's sidebar, so that editors can start creating new content right away: (Image content) While this is great, big websites tend to require a significant number of models to properly manage every page, so it might quickly become difficult for clients/editors to understand which model in the backend is linked to which part of the frontend website. You can easily organize the different models in a more understandable way by renaming, reordering, and grouping them, so that their purpose will be clearer to editors: (Video content) Something else you can consider is using menu items that point to external URLs. This allows you to link to third-party resources, but also to create custom links to special records or filtered sets of records for fast retrieval. --- # General concepts — Record versioning Source [docs]: https://www.datocms.com/docs/general-concepts/versioning.md DatoCMS produces a snapshot of a record each time it gets saved. Record versioning allows DatoCMS users to view previously published versions of the record, find out who published a record, compare previous snapshots to the current version, and — when necessary — restore the content to the earlier state. (Video content) DatoCMS stores all the content found in the record — including localized content and references to other records and uploads. However, it does not create or store snapshots of linked entities. Therefore, if you restore a record to the earlier version containing a reference to a deleted upload, the image field will be empty. It is also important to remember that the version comparison only displays current locales and values. If your record was translated into Italian in the past, but later the Italian locale was removed from the model, the Italian text will no longer be visible or restorable. The same logic goes for deleted fields: any content that was stored within these fields in the past will no longer be displayed. To know more about how versioning on DatoCMS works, check out this video tutorial: [ (Image content) Content Records, Publishing, Scheduling, and Versioning Play video » ](https://www.datocms.com/user-guides/content-management/content-records-publishing-scheduling-and-versioning.md) [ (Image content) Working with entry & asset versions Play video » ](https://youtu.be/qJhobECFQYk) ## How long do record versions last? Record history retention depends on your plan. As of 2025, the history limits are: - 3 days on the Free plan - 60 days on the current Professional plan - Enterprise plans and older, grandfathered plans have custom limits After this period, only the latest version will remain. --- # General concepts — Draft/published system Source [docs]: https://www.datocms.com/docs/general-concepts/draft-published.md You can decide to activate the draft/published system on a per-model basis: (Video content) If you do so: - When you create a new record, it will be put into a *Draft* status. This means that the record is still not published: you can continue making changes and saving the record without having to worry about showing unfinished content to your end users. - Once you're satisfied with the changes, you can click on the *Publish* button: the latest revision of your record will be marked as the *Published version*, and it will be instantly available in the DatoCMS APIs: - With the [Content Delivery API](/docs/content-delivery-api.md) and the [Realtime Updates API](/docs/real-time-updates-api.md), the default is to return only the published record, but you can request to consider the draft with the header [`X-Include-Drafts: true`](/docs/content-delivery-api/api-endpoints.md#preview-mode-to-retrieve-draft-contenthttps://www.datocms.com/docs/content-delivery-api/api-endpoints#preview-mode-to-retrieve-draft-content). - With the [Content Management API](/docs/content-management-api.md), you can request to consider the published or draft versions of records with the parameter [`?version=current`](/docs/content-management-api/resources/item/instances.md) or [`?version=published`](/docs/content-management-api/resources/item/instances.md). - If you make a change to a published record, its status will be become **Updated**. Again, those changes won't be visible to end users and published until you explicitly click on the *Publish* button again. > [!POSITIVE] > For more information on how the system manages the draft/published status, you can refer to this in-depth guide: [Data consistency: key concepts and implications](/docs/content-modelling/data-migration.md). ### Saving Invalid Drafts In some instances you may need to create posts via the UI or the API that may not have all validations in place (for instance, bulk creating records missing a specific required field like a title). In these cases, if you have the Draft/Published flow enabled, you can also choose to allow saving records on a draft stage without passing all validations. The feature affects the CMS and, of course, the CMA (Content Management API). When draft saving is active, it's possible to POST/PUT invalid records to CMA and have them saved: the endpoints respond with a 200, and the record just saved as a payload. (Video content) However, validations will take effect when the record is published. If the record is not valid, publication fails, and editors need to fix the content to ensure all rules are handled before proceeding to move the record into the Published stage. ### Linked records must be published together When a record links to other records, they all have to be published *together* — a published record cannot link to an unpublished draft, or your visitors would just see a broken link! Our system prevents this. **For example:** - You have an article, "🟠 **Easiest Headless CMS**". This is the one you've edited and want to publish. - But it links to another article, "⚪ **CMS Comparison**". This is currently a draft (never published). - If you try to publish 🟠 **Easiest Headless CMS** without first publishing ⚪ **CMS Comparison**, the publish will fail. > [!NOTE] What do the colored dots mean? > In the CMS, a colored dot before the record name shows its current status: > > **🟢** Green\= Published > 🟠Orange = Updated (changed since the previous publish) > ⚪ Gray = Draft (never published) To resolve this, you can tell our system which behavior you prefer: whether we should fail such attempts, or try to publish the linked records ourselves. In the field's settings, under its Validations tab, there is an option: **"When a publishing is requested and this field references some unpublished records:"** - "**Fail the operation and notify the user**": The publish will be stopped and you'll see an error (or an email, in the case of a [scheduled publish](/docs/general-concepts/scheduled-publishing-unpublishing.md)). In our example, that means neither article will be published. ⚪ **CMS Comparison** will stay a unpublished draft and 🟠 **Easiest Headless CMS** will still show its older published version, not your latest changes. - "**Publish also the referenced records**": Our system will try to automatically publish all the linked-to records before publishing the linking-from record. In the example, that means it will automatically try to publish ⚪ **CMS Comparison** first, and then publish 🟠 **Easiest Headless CMS.** Both will be published at the end (assuming every linked-to record successfully published). Keep in mind that every linked-to record might, itself, have additional links and validations, subject to the same criteria. The entire "tree" of references (every linked record, and every record THEY link to) must successfully publish or the overall operation will fail — if *any* linked record *would fail* a publish, then the entire attempt is aborted and nothing is published. (In software developer terms, the entire chain of publish operations is *atomic* — it all happens together or not at all.) (Video content) ## Video tutorial To learn more about how DatoCMS saves versions, check out this video tutorial: [ (Image content) Working with entry & asset versions Play video » ](https://youtu.be/qJhobECFQYk) --- # General concepts — Scheduled publishing Source [docs]: https://www.datocms.com/docs/general-concepts/scheduled-publishing-unpublishing.md Combined with the [draft/published system](/docs/general-concepts/draft-published.md), you can schedule **future publications or unpublications**. You can access this feature using the calendar icon in the dropdown menu for the "Publish" button: (Image content) This will automatically change the state of your record on the specified date. ## Linked records and scheduled publishing When you schedule a record for publishing, and it has links to other records, those linked records must also be published at the scheduled time. You can either do this manually (publishing the linked-to records beforehand), or have our system try to automatically publish all the linked-to records at the scheduled time. To learn more, please see: [Draft/published system: Linked records must be published together](/docs/general-concepts/draft-published.md#linked-records-must-be-published-together) ## Scheduling build triggers after publications/unpublications If you are using build triggers, you can **set them to automatically trigger a build** when the scheduled publication/unpublication is done. You can find this setting in the build trigger settings: (Image content) --- # General concepts — Media Area Source [docs]: https://www.datocms.com/docs/general-concepts/media-area.md In the Media Area of your project you can upload, view, edit, and organize all your assets. (Image content) Individual assets can be viewed with their information and edited. (Image content) ### Metadata and smart tags When an image is uploaded, it is analyzed, then a set of metadata is exposed in our media area and via the APIs. If the upload is a picture with EXIF info, we expose that information together with other details, such as dominant colors and a set of machine-learning generated smart tags. (Video content) Look at all this juicy data! ### Asset organization As your collection of assets grows, organization becomes crucial. To help with this, we offer several options. You can filter assets using any number of fields with various options for each field: (Image content) If you have a useful filter that you want to save or share with the rest of the team, you can add it to your "Saved filters": (Image content) One way to organize assets that we recommend is to **combine filters with tags**, both manual and smart tags, automatically added on asset upload. You can efficiently tag assets using the bulk tagging feature: (Image content) DatoCMS also has *asset collections*, in addition to tags. You can create multiple collections, organize them in a tree structure, very much like folders on a classical file system. There are two main rules: each asset can only be assigned to one collection, and you can always view all assets by clicking on "All assets." To create collections and nested sub-collections, simply utilize the sidebar as you would with content views. (Video content) Assets can be assigned to their respective collection or sub-collection using the action bar at the bottom of the screen or via drag and drop. (Video content) Finally, you can visualize your assets in various ways (grid, masonry, and table), depending on your use case and asset type. For example, the tabular mode can be very handy for performing operations on multiple assets at once: (Image content) ### Asset management For each asset, you can specify a set of default metadata such as title and alternate text that can be applied as the default value when nothing else is selected. (Image content) For better asset organization you can specify some additional categorization fields, such as notes for colleagues and author/copyright data of the asset: (Image content) If you need to add a new revision of an asset, you can simply drag in a new version, and we'll replace the asset in every occurrence: (Image content) ### Localization When using multiple locales, you can set default metadata on a per-locale basis: (Image content) You can then override the default metadata in place when referencing the asset in a record: (Image content) ### Audio player If you host/produce audio files, you can use the embedded audio player to listen to them: (Image content) ### Image editor If you need to edit an uploaded image, you can use the built-in powerful editor to crop, rotate, apply predefined color filters, tweak colors, and add basic shapes and text to the image: (Video content) ### Image URL When an asset is uploaded to your media area, you immediately get access to a direct URL to use it wherever you want: (Image content) To understand how that URL is formatted, we first need to understand how the file name is formatted after upload: - Underscores or dashes at the beginning or end of the file name are removed - Character accents are removed - All non-alphanumeric characters, except for underscores "\_", are replaced by dashes "-" - If the file has a wrong or invalid extension in its name, it is replaced by the one matching the file type The URL then is created using the project ID, an upload timestamp, and the newly formatted file name: ```plaintext https://www.datocms-assets.com/PROJECT_ID/UPLOAD_TIMESTAMP-FORMATED_NAME ``` ### Video editor If you need to edit an uploaded video, you can use the built-in powerful editor to trim, resize, rotate, apply predefined color filters, tweak colors, and make basic changes to the video: (Video content) When serving videos, we recommend using HLS streaming whenever possible. Follow our [docs on serving videos through Mux](/docs/content-delivery-api/images-and-videos.md#videos) to implement our recommended best practices. To have an overview on all the things you can do in your media area, check out these video tutorials: [ (Image content) Intro to the Asset Area Play video » ](https://www.datocms.com/user-guides/the-basics/intro-to-the-asset-area.md) [ (Image content) Images and Image Optimization Play video » ](https://www.datocms.com/user-guides/media-management/images-and-image-optimization.md) [ (Image content) Videos and Video Optimizations Play video » ](https://www.datocms.com/user-guides/media-management/videos-and-video-optimizations.md) ### Antivirus Scanning Every file uploaded to the Media Area is automatically scanned for viruses and malware. Scans run in the background immediately after upload so that editors don't need to do anything, and there's no delay in their workflow. (Video content) **How it works** When a file is uploaded, a scan is queued automatically. Within seconds, the file is assigned one of the following statuses: | Status | What it means | | --- | --- | | Clean | No threats detected and the file is served normally. | | Infected | A threat was detected and the file is automatically quarantined and removed from the CDN. | | Skipped | The file exceeds the scanner's size or type limits and couldn't be assessed. DatoCMS cannot confirm whether these files are safe. | | Failed | A transient error occurred. The scan will be retried automatically up to 6 times and if all retries fail, the file remains in a failed state. | If an asset is replaced with a new version, the scan runs again automatically on the new file. **How infected files are handled** When a threat is detected, DatoCMS automatically: 1. Removes the file from public storage 2. Purges it from the CDN cache, and 3. Keeps the upload record visible in the Media Area, so editors can see it was flagged The file URL will no longer serve any content. At this time, there is no way to restore a quarantined file, and editors should replace the asset. > [!NOTE] Using a custom storage bucket? > If your project uses a custom storage bucket like S3 or R2, DatoCMS doesn't have permission to delete or move files from your storage. The file will remain accessible from your bucket even after being flagged as infected. The upload record will be marked accordingly, and the warning screen will display the file path so you can remove it manually from your storage provider. Infected files are surfaced throughout the Media Area: A **"Threat detected"** badge appears on the upload card in grid, masonry, and table views. On smaller cards, this collapses to an icon with a tooltip (Image content) Opening an infected file replaces the normal preview with a **warning screen** that explains the situation, shows the specific threat name (useful for investigation), and prompts the editor to replace the asset (Image content) For custom storage projects, the warning is adjusted to show the file path and advise manual removal from the bucket Editors can filter uploads by antivirus status (clean, infected, skipped, failed, pending) directly in the Media Area search. This filter is **not available** in the Content Delivery API. Scan results are delivered in real time with the antivirus status in the dashboard updating live without requiring a page refresh, and Webhooks are fired on status changes, so you can build integrations that react to scan results, for example, getting a Slack alert when an infected file is detected in your project. **API Access** The antivirus status is also available on every upload object via the CMA, under a new `meta.antivirus` field: ```json "meta": { "antivirus": { "status": "infected", "scanned_at": "2026-03-27T18:51:00Z", "threat_name": "Trojan.GenericKD.12345" } } ``` The `status` field will be one of `clean`, `infected`, `skipped`, or `failed`. The `threat_name` field is only present when a threat has been detected. Antivirus scan **results are preserved when forking environments** without any rescanning required. When duplicating projects, **infected files are automatically excluded** from the copied project to prevent propagation. --- # General concepts — Localization Source [docs]: https://www.datocms.com/docs/general-concepts/localization.md Each administrative area in DatoCMS supports multiple locales, which are defined by the short ISO locale codes (i.e. `en` or `de`). You can add or remove locales within the *Admin area \> Site settings* section: (Video content) ## Field-specific localization Each field is localized individually, so you can pick and choose which specific content needs to be translated and which does not: (Video content) As soon as a localized field is present within a model, the form to edit its records will present one tab for each locale: (Image content) ## Adding new locales along the way With DatoCMS you are free to add new locales at any time; just be aware that, once a new locale is added, if some validations are present on your fields, those validations will be enforced for every locale. Records already created will therefore be marked as “invalid”, and you won't be able to update your records until all the validations are satisfied for all the locales. For more information, take a look at the [Data migration](/docs/content-modelling/data-migration.md) chapter. > [!PROTIP] Pro tip: Build a multi-language website with Next.js > Our blog has a full walkthrough on how to set up a multi-language site from scratch using Next.js, which provides robust built-in support for internationalization. ## Optional/required locales You can configure a certain model so that your editors are not forced to insert content for every language your project supports, but just for some of them, on a per-record basis. This allows use cases such as multi-language blogs, where some articles can be written only in English, other only in Italian and others in both languages. To require all locales to be always present on every record of a specific model, you can check the *All locales required?* option in your model settings: (Video content) ## Fallback locales If you allow partial (optional) translations, some records will inevitably have gaps: a locale where only a few fields have been filled in, or a page complete except for one field. A **fallback locale** is a safety net for these situations: a backup locale that your website can show whenever a piece of content (a specific field) is missing in the locale a visitor asked for. Fallback locales work best between languages that are similar to each other, like regional dialects or variants of the same base language. Say your online store uses three locales: **English** (`en`) as the base, plus **English (US)** (`en-US`) and **English (UK)** (`en-GB`). You write each product page once in base English, and only override the handful of fields that actually differ by region. For a wool sweater, that might look like this: | Field | Base language (English, `en`) | 🇺🇸 United States (`en-US`) | 🇬🇧 United Kingdom (`en-UK`) | | --- | --- | --- | --- | | Product name | Wool Sweater | | Wool Jumper | | Description | Knitted from 100% merino wool, this classic crew neck keeps you warm without the bulk. Naturally breathable, machine washable, and made to last for years. | | | | Shipping | Available globally; fees vary | Free shipping in 3-4 business days (AK/HI extra) | Free UK delivery in 2–3 working days | With base English configured as the fallback: - 🇺🇸 US visitors see the fallback product name and description, but with US-specific shipping details - 🇬🇧 UK visitors see their own product name ("jumper" instead of "sweater") and different shipping details. They see the same fallback description Fallbacks can also be a *chain* of multiple locales. If our example store later adds **English (Australia)**, its fallback chain might be configured to try **English (Australia)** first, then **English (UK)** next (whose spelling and conventions are closer), then finally the base **English**. The first locale in the chain that actually has content in the field is the one visitors will see. > [!NOTE] Ask your developers to set up fallback locales > While the *concept* of fallback locales is explained on this page, the actual *implementation* of it requires changes in your website query code. You'll need your developers' or agency's help with this. If this feature is useful to you, please discuss it with them and point them at this corresponding developer-facing documentation: [Localization](/docs/content-delivery-api/localization.md) ## Locale-based publishing By enabling the optional locales settings, teams have the flexibility to publish content for specific locales within their project, regardless of the status of other locales. For instance, imagine a project with locales for Germany, Switzerland, Great Britain, and Belgium. With this feature, teams can focus on creating and finalizing content for Germany without the need to manage content for other locales. If the team has the capacity to work on additional locales, they can save the content as drafts without publishing it. This enables multiple team members to independently create content for different locales, aligning with their respective timelines and priorities. When a team member is prepared to publish content for a specific locale they have permission for, they can simply select the "Only publish specific content" option. A convenient popup window will then appear, allowing them to choose which locale(s) to publish, with the ability to select multiple locales if desired: (Video content) You can also selectively unpublish one (or multiple) locales: (Video content) Locale-based publishing also works on scheduled publications/unpublishing: (Video content) ## Translator roles, and locales permissions Our roles/permissions system allows specifying which locales each collaborator can add/edit/remove on any record. For each role you can define both global rules, which will be applied to all models in your project, and specific per-model rules, giving maximum flexibility: (Image content) Every role can customize which locales can be edited ## Localized CMS interface By default, the CMS interface will pick the default browser's language and, if available, will show the interface localized. If you prefer to manually pick one, you can do it like this: (Video content) If you don't find the translation that you need, and you are looking into contributing, read [this blog post](https://www.datocms.com/blog/backend-community-translation.md) to learn more and get involved. #### Learn more about localization with DatoCMS DatoCMS allows a great deal of customization when dealing with localization. Check out these tutorial videos for a hands-on approach: [ (Image content) Localizing Content in DatoCMS Play video » ](https://youtu.be/166gt1Qg-d4) [ (Image content) Creating a localized blog using Next.js Play video » ](https://youtu.be/3tBeOwdVuwo) --- # General concepts — Visual Editing Source [docs]: https://www.datocms.com/docs/general-concepts/visual-editing.md Visual Editing lets content editors click directly on any element of your website to edit it in DatoCMS, without hunting through forms and fields. Combined with draft content and real-time updates, editors see changes reflected instantly on the page as they type. ## Click-to-edit on the website Editors can visit the website in draft mode and interact with content right there. Hovering over any editable element (a title, body text, an image alt text) reveals a subtle overlay. Clicking it opens DatoCMS directly at the exact field that controls that piece of content: (Video content) Click-to-edit overlays ## Side-by-side editing inside DatoCMS The [Web Previews plugin](https://www.datocms.com/marketplace/plugins/i/datocms-plugin-web-previews.md) brings a live preview of your website directly into the DatoCMS interface. A "Visual" tab provides a full-screen, side-by-side editing view where editors click on any element in the preview and the corresponding record and field open right next to it. The connection works in both directions: browsing records in DatoCMS navigates the preview to the corresponding page, and clicking around in the preview opens the relevant record in the CMS. (Video content) Side-by-side editing ## Real-time feedback When combined with [Real-time Updates](/docs/real-time-updates-api.md), editors see their changes reflected on the preview as they type. There's no need to reload: the preview updates live, giving editors immediate confidence that their changes look right in context. ## Getting started Visual Editing is available on every DatoCMS plan (including Free) and works in any environment. The easiest way to get started is from one of our [tech starter kits](https://www.datocms.com/marketplace/starters.md), which come pre-configured with everything wired together. For a detailed walkthrough of how it works and how to set it up, see the [Visual Editing guide](/docs/visual-editing.md). --- # General concepts — Record-level collaboration: Presence & locking Source [docs]: https://www.datocms.com/docs/general-concepts/collaboration-features.md Our collaboration tools help you manage teamwork and ensure that no data is lost when switching between users. DatoCMS manages modifications to records, assets, and models in real-time, without the need for other editors to refresh the page. What it means is that every change you make is immediately visible to every user, from record creation to asset deletion. You can also add, edit or reorder fields in a model while others are working on affected records without losing their work. ## Presence Indicator A presence indicator is visible when another user opens or edit a record, with a notification that tells you if the user is either looking or editing the record. (Video content) ## Locking and Unlocking a Record To prevent two users from changing the same record at the same time, we have implemented an automatic lock. When a user starts editing a record, it will be considered locked and therefore not editable by other users. The record will be available again as soon as the first user saves or closes the editor. (Video content) You can forcefully unlock a record if your role on DatoCMS has the authority to do so. The other user will be kicked out from the editing session, and the record will be locked by you. (Video content) To avoid the involuntary loss of content, you can recover the work done by the previous user and start from their unsaved changes. To have an overview of all DatoCMS features, check this video tutorial: [ (Image content) A gentle overview of all the features of DatoCMS Play video » ](https://www.youtube.com/watch?v=ALHwdztg0UQ) --- # General concepts — Workflows Source [docs]: https://www.datocms.com/docs/general-concepts/workflows.md Larger teams often stumble through many bottlenecks caused by disconnected systems, duplicate content, and inefficient workflows. Organizations invest more in content, but their ROI remains lower due to friction, and their content engines stall. With Workflows, you can **set up a precise state machine** that can bring a draft content **from initial creation to final publication** (and beyond), through a series of intermediate, fully customizable approval steps, keeping the whole team in sync without scattering the process across a number of external software tools to keep track of what needs to be done. (Image content) A simple example of what you can achieve with DatoCMS workflows ## How it works A workflow is composed of a series of **stages**, which are essentially labels and a description. One of the stages has to be marked as the initial one, so that new records will start from there: (Image content) A workflow is composed of a series of stages, which are essentially labels Within the same DatoCMS project, you can create multiple workflows and assign them to different models. When you apply a workflow to a model, all its existing records will be assigned the initial stage: (Image content) Workflows can be assigned to multiple models Once everything is configured, users will be able to filter records by stage — optionally creating saved filters and sharing them with the team — and move records from one stage to another, in batch or one at a time: (Video content) The final experience for your editors. Clean, simple, secure. Using our [roles and permissions system](/docs/general-concepts/roles-and-permission-system.md), you can **specify exactly which team members are in charge of performing the necessary checks and operations on the content** so that it can advance to the next step in the approval chain and the team never publishes something by mistake. ## How to configure workflows **Workflows are completely custom**: you are free to tailor the stages you need with no limits, following your organization's natural processes. For this example, we'll create a new workflow with three stages: - **Writing** - **In review** - **Approved** For this workflow, we also want to enforce the following simple rules: - **Creators** work on the content in the *Writing*stage. When they're done, they move articles to the *In review* stage, so that.. - **Editors** can either reject or approve them, moving them back to *Writing* or forward to *Approved* stage; The first step is actually creating the workflow itself. Go to **Configuration \> Workflows**, and create the following workflow: (Image content) The second step is to assign this workflow to one or more models. You can do so by entering the **Schema \> Models** area, selecting a model and clicking on "Edit model": (Image content) We can move back to Configuration**\> Content permissions** to specify which actions and transitions between stages are allowed for the two **Creator** and **Editor** roles. This what you need to setup for the Creator role, for example: (Image content) The permissions are pretty self-explanatory, and refer to the same set of rules we have determined at the beginning. Rules can be both positive or negative — to allow or block a specific permission. You can setup rules for every model under a specific workflow, or even override some rules for some of your models. In this example, on top of all the rules enforced on all models that are under the workflow, we additionally block publishing only for blog posts: (Image content) ## Workflows is an Enterprise feature Workflows is a feature **available only to Enterprise customers.** Whichever plan you are on, you can still create and configure workflows to see if they solve your needs, but you won't be able to actually associate them with any model. If your company is interested in this feature, please [contact our Sales team](https://www.datocms.com/contact.md) for more details on pricing; we'll be happy to offer you a trial! To have an overview on all DatoCMS features, check out this video tutorial: [ (Image content) A gentle overview of all the features of DatoCMS Play video » ](https://www.youtube.com/watch?v=ALHwdztg0UQ) --- # General concepts — Customize CMS domain Source [docs]: https://www.datocms.com/docs/general-concepts/customize-cms-admin-domain.md To help your editors find the CMS URL, or to provide a more white-labeled solution, you can customize the URL of your project's CMS. Instead of the default `yourproject.admin.datocms.com`, you can use your own domain, like `cms.mycompany.com`. To do so, first make sure the `CNAME` record of your domain's DNS points to `admin.datocms.com`, then go to your dashboard and follow along: (Video content) > [!NOTE] The CMS domain only affects the DatoCMS admin area > Please note that this domain only affects your CMS admin area, the place you normally go to edit your project and its models and records. > > It does NOT affect the domain name for: > > - Your frontend (see [How your website and DatoCMS work together](/docs/general-concepts/how-your-website-and-datocms-work-together.md) ) > > - Your DatoCMS account dashboard (dashboard.datocms.com) --- # General concepts — Webhooks Source [docs]: https://www.datocms.com/docs/general-concepts/webhooks.md If you need to know when data has changed in one of your projects, you can create customized webhooks to get HTTP notifications as soon as the events occur. For example, you might use webhooks as the basis to: - Integrate/sync DatoCMS data with third-party systems (Snipcart, Shopify, Algolia, etc.); - Get Slack/email notifications; - Automatically post an update on Facebook/Twitter; - Produce an automatic deploy on your staging environment; You can connect DatoCMS webhooks to any endpoint you like — for example, some custom AWS lambda function. > [!PROTIP] Pro tip: DatoCMS + Zapier: no-code management of webhooks! > If you prefer not to write code, you can use [Zapier Webhooks](https://zapier.com/page/webhooks/) to connect a DatoCMS event with hundreds of different external services, creating any kind of complex automation workflow. ## Setting up a webhook You can set up a new webhook under the *Project Settings \> Webhooks* section of your administrative area. You can enter any URL as the destination for calls, add HTTP basic authentication and custom HTTP headers: (Image content) DatoCMS needs to get a status code `2XX` reply from the configured URL to confirm that the notification sent via HTTP POST has been successfully delivered. If any webhook returns a different status code or times out, DatoCMS will set the status as "Failed". ### Webhook triggers Webhook triggers let you specify under which circumstances an HTTP call will be performed towards your endpoint: (Image content) You can add as many triggers as you want to a single webhook. DatoCMS supports events for the following objects: | Entity | Available events | Additional notes | | --- | --- | --- | | Record | `create`, `update`, `delete`, `publish`, `unpublish` | You can trigger the webhook only for specific records or records belonging to specific models. See the "Record Lifecycle Events" section for details. | | Model | `create`, `update`, `delete`, | You can trigger the webhook only for specific models. Changes made to a model's field will trigger a call as well. | | Upload | `create`, `update`, `delete` | | | Build trigger | `deploy_started`, `deploy_succeeded`, `deploy_failed` | | | Environment | `deploy_started`, `deploy_succeeded`, `deploy_failed` | | | Maintenance Mode | `change` | Triggers whenever an admin activates or deactivates the maintenance mode. | | SSO User | `create` | Triggers when an SSO User is added to a project as a collaborator. | | CDA Cache Tags | `invalidate` | Triggers when CDA Cache Tags need to be invalidated. | Visit the [Data consistency: key concepts and implications](/docs/content-modelling/data-migration.md) section for more details on when the webhooks related to the records will be triggered. ## The HTTP Payload DatoCMS will perform an HTTP POST request towards the specified endpoint. The HTTP body will be in JSON format, and will contain all the information relevant to the event just happened. The body will contain the following information: | Payload property | Description | | --- | --- | | `site_id` | ID of the project where the event occurred. | | `webhook_id` | ID of the webhook that triggered the delivery. | | `environment` | ID of the environment where the entity resides. | | `is_environment_primary` | Whether the environment where the event occurred is the primary environment. | | `webhook_call_id` | ID of the specific webhook event that triggered. | | `event_triggered_at` | Date when the event originally occurred. | | `attempted_auto_retries_count` | If auto-retry is on for the webhook, this field displays the number of the current attempt. | | `entity_type` | The type of entity that triggered the webhook (ie. item, item\_type...) | | `event_type` | The type of event that triggered the webhook (i.e.: create, update, delete...) | | `entity` | The full payload of the entity serialized according to our Content Management API schema. | | `previous_entity` | Only present if the event type is "Record \> Update". It represents the serialized record BEFORE the update (useful to know what changed). | | `related_entities` | An array containing all serialized entities specified in the entity's relationships. | As an example, in the case of a *Record \> Update* event, you can access the record state both before the update operation (`previous_entity`) and after (`entity`), making it easier to make a diff and see exactly what fields in the record changed: ```json { "site_id": "example-site-id", "webhook_id": "123", "environment": "foo-bar", "is_environment_primary": true, "webhook_call_id": "456", "event_triggered_at": "2024-08-26T14:30:00Z", "attempted_auto_retries_count": 3, "entity_type": "item", "event_type": "update", "entity": { "id": "39830648", "type": "item", "attributes": { "name": "Mark Smith" }, "relationships": { "item_type": { "data": { "id": "810928", "type": "item_type" } }, "creator": { "data": { "id": "42011", "type": "account" } } }, "meta": { "created_at": "2018-10-28T18:44:32.776+01:00", "updated_at": "2021-08-17T09:11:56.145+02:00", "published_at": "2021-08-17T09:11:56.143+02:00", "first_published_at": "2018-10-28T18:44:32.789+01:00", "status": "published", "current_version": "117626080" } }, "previous_entity": { "id": "39830648", "type": "item", "attributes": { "name": "John Smith" }, "relationships": { "item_type": { "data": { "id": "810928", "type": "item_type" } }, "creator": { "data": { "id": "42011", "type": "account" } } }, "meta": { "created_at": "2018-10-28T18:44:32.776+01:00", "updated_at": "2021-08-17T09:11:53.371+02:00", "published_at": "2021-08-17T09:11:53.367+02:00", "first_published_at": "2018-10-28T18:44:32.789+01:00", "status": "published", "current_version": "117626079" } }, "related_entities": [ { "id":"810928", "type": "item_type", "attributes": { "name": "Author", "api_key": "author", ... }, "relationships": { ... } } ] } ``` ### Customize the URL or HTTP payload If you want, you can also customize the HTTP body of the outgoing requests. To do that, hit the *Send a custom payload?* switch and provide the new payload. You can use the [Mustache language](https://mustache.github.io/) to make the payload dynamic. The original payload we would send is used as source for the template. You can experiment with the Mustache language in their [sandbox](https://mustache.github.io/#demo), or read their [docs](https://mustache.github.io/mustache.5.html). As an example, this custom payload template: ```json { "message": "{{event_type}} event triggered on {{entity_type}}!", "entity_id": "{{#entity}}{{id}}{{/entity}}" } ``` Will be converted into the following HTTP body: ```json { "message": "update event triggered on item!", "entity_id": "123213" } ``` You are not limited to send JSON payloads: just make sure that if the payload is not in JSON format, you configure the proper `Content-Type` header. Similarly, you can also insert Mustache tags in the webhook URL. ## Automatic Retries Optionally, you can activate the **Automatic Retry** option in your webhook settings, so that in case of delivery failure, DatoCMS will attempt to resend the request up to 7 times, with increasing intervals between each attempt. (Video content) Each retry will use the most recent webhook settings, and the retry schedule is as follows: | Retry | Time | | --- | --- | | 1 | 2 minutes after the failure | | 2 | 6 minutes after the previous retry | | 3 | 30 minutes after the previous retry | | 4 | 1 hour after the previous retry | | 5 | 5 hours after the previous retry | | 6 | 1 day after the previous retry | | 7 | 2 days after the previous retry | ## Understanding webhook statuses Webhook calls can have different statuses to indicate the outcome of the delivery attempt: | Status | Description | | --- | --- | | Pending | The webhook call is currently being executed. | | Success | The webhook call was successfully delivered to the specified endpoint, and the server responded with an HTTP status code in the 2xx range. | | Failed | The webhook call could not be successfully delivered. This may be due to issues such as server errors, invalid endpoints, network problems or an HTTP status code not in the 2xx range. | | Rescheduled | The webhook delivery failed, but is scheduled to be retried automatically based on the webhook automatic retries setting. | ## Debug and keep track of webhooks activity You can browse webhook activity under the Project Settings \> *Webhooks activity log* section of your project, or [using our API](/docs/content-management-api.md#webhook_call-0). In both cases, you can filter/order webhook calls to refine your search based on various criteria, such as status, type of event, date, etc: (Image content) ## Manually Resend Webhook Event At any time you have the option to resend a webhook manually. To do so, click on the "Details" link and then on "Resend now" (Image content) When you choose to manually resend a webhook call, the system will repeat the exact same call with the updated webhook settings. If auto-retries are enabled: - a successful manual resend will stop further auto-retry attempts, - a failed manual resend won't add to the count of automatic retries. ## Webhook Timeouts DatoCMS enforces two timeout limits for webhook integrations: - **Connection Timeout: 2 seconds** This is the maximum time allowed to establish the initial connection to the webhook's HTTP server. - **Total Execution Timeout: 8 seconds** This is the maximum time allowed for the entire webhook process to complete. If your service exceeds either of these timeouts, DatoCMS will terminate the connection. The delivery attempt will then be marked as either Failed — or Rescheduled, if Automatic Retries are enabled. > [!PROTIP] Pro tip: Prefer asynchronous over synchronous > Due to the unpredictable nature of service completion times, it's recommended to handle the bulk of your processing in background jobs. This approach helps manage DatoCMS's timeout constraints effectively. Consider using job queue libraries such as Resque (Ruby), RQ (Python), or RabbitMQ (Java). > > The pattern we suggest is to perform the initial validation checks of the payload quickly and synchronously before starting the background jobs. This allows you to potentially respond with a status code other than `2XX` to the webhook, thereby notifying DatoCMS of the issue. ### Webhook events for record lifecycle changes This section clarifies how webhooks are fired on record lifecycle changes (such as publication or deletion). The behavior will be different if the model has the [draft/publish system](/docs/general-concepts/draft-published.md) enabled. See the following tables for details. ##### With draft/publish system enabled | When a record is... | These events will be sent | `entity.meta.status` | | --- | --- | --- | | Saved for the first time | `create` | `draft` | | Modified & saved again without publishing | `update` | `draft` | | Published | `publish` | `published` | | Modified & saved after publishing | `update` | `updated` | | Selectively published (e.g., one locale gets selectively published, but there is still saved-but-unpublished data in other locales) | `publish` | `updated` | | Scheduled to publish / unpublish | `update` | `updated` | | Unpublished | `unpublish` | `draft` | | Deleted from `draft` status | `delete` | `draft` (even though record is gone) | | Deleted from `published` status | `unpublish` `delete` | `published` (even though record is gone) | ##### With draft/pub system disabled When draft/publish system is **disabled** on a model, the `publish` and `unpublish` events will still be sent as they're implicit with record creation, update and deletion. This will result in multiple events sent for each user action on a record, with the benefit of having a uniform way to listen for record changes via webhooks, regardless of the model draft/pub preference: | When a record is... | These events will be sent | `entity.meta.status` | | --- | --- | --- | | Saved for the first time | `create` `publish` | `published` | | Updated | `update` `publish` | `published` | | Deleted | `unpublish` `delete` | `published` (even though the record is gone) | --- # General concepts — Plugins Source [docs]: https://www.datocms.com/docs/general-concepts/plugins.md While DatoCMS already offers a very wide range of options and configurations, with plugins it is possible to take a leap forward and integrate market-leading third-party services with the DatoCMS platform, or build custom integrations tailored specifically to your business. ### What can plugins do? A better question is — what do you want to achieve with plugins? Using plugins, a huge variety of enhancements to the DatoCMS web app are possible, from small field editor improvements to deeply integrated full-page applications. The [Plugin SDK](/docs/plugin-sdk/introduction.md) makes customizing the web app effortless. Some common use cases are: - Adding custom field editors to improve the editor experience; - Managing content versions for running A/B tests on structured content using personalization tools; - Customizing the default entry editor to suit your specific needs; - Seamlessly integrating DatoCMS with third-party software and services; ### Managing and distributing Plugins #### Private plugins A private plugin is built by you for your specific organization's needs to optimize your organization's editorial experience. It is fully under your control and not accessible by other organizations. The total number of plugins and installations within your organization/environment is limited based on your DatoCMS plan. #### Marketplace plugins [Marketplace plugins](https://www.datocms.com/marketplace/plugins.md) are built by our community and connect DatoCMS with other systems allowing you to assemble the stack of your choice. Everyone can (and is encouraged to) contribute with new plugins by releasing them as NPM packages. More than 100 plugins are already available on the Marketplace, and can be installed free of charge without touching a single line of code. Installation is extremely simple, and can happen both programmatically or using the interface. ### Installing Marketplace Plugins To install a new plugin for your project, go to **Configuration \> Plugins** and click on **Add a new plugin**. This action will open the **Plugin Marketplace** directly within your DatoCMS backend, allowing you to browse all available community plugins. You can filter by categories such as *Most Popular*, *Recently Released*, or use the search bar to find plugins by keyword. When you find a plugin you’d like to use, click on its card to open the details page. Here, you’ll see a description, metadata, and other relevant information about the plugin. Simply click the **Install** button to add it to your project. Once installed, the modal will close, and the newly added plugin will appear in the **Plugins** list, ready for configuration. (Video content) If you're not sure what plugins you need and want some inspiration, we've also curated commonly used plugins under collections like **Editor Favorites** and **Dev Favorites** to make it simpler for you to pick and choose the greatest hits. ### Creating new Plugins To learn how to build new plugins, and maybe share them with the community, please visit our [detailed guide](/docs/plugin-sdk/introduction.md) or take a look at this video tutorial on how to start developing a plugin from scratch. [ (Image content) Intro to the Plugin Ecosystem Play video » ](https://www.datocms.com/user-guides/the-basics/intro-to-the-plugin-ecosystem.md) [ (Image content) How to start developing plugins for DatoCMS Play video » ](https://youtu.be/sc8sm34tyWw) --- # General concepts — DatoCMS Site Search Source [docs]: https://www.datocms.com/docs/general-concepts/site-search.md DatoCMS Site Search is a way to **deliver tailored search results to your website visitors**. You can think of it as a replacement for the now discontinued Google Site Search. (Image content) There are many third-party services out there that fill this need (like [SwiftType](https://swiftype.com/), [Algolia](https://www.algolia.com/), and [Cludo](https://www.cludo.com/)). Our solution seeks to be a great option for plenty of websites: - Extremely easy to integrate with your static website - Completely customizable in terms of look & feel - Minimal configuration needed - Handles multilingual websites nicely - included in the price of DatoCMS with no additional charges #### How it works - Every time your website finishes being deployed, **we'll crawl it to fetch updated content.** - From your frontend, you can [**make AJAX requests to our Content Management API**](/docs/site-search/base-integration.md#performing-searches) **to present relevant results to your visitors**. We also provide [**React**](/docs/site-search/widget.md) **and** [**Vue**](/docs/site-search/vue-search-widget.md) **search widgets** that simplify the process. > [!PROTIP] Pro tip: Integrating Algolia and DatoCMS > If you prefer to integrate a search provider like Algolia, [this guide](https://www.datocms.com/blog/algolia-nextjs-how-to-add-algolia-instantsearch.md) demonstrates setting up a Next.js project, configuring Algolia, and creating custom search components. While the guide focuses on Algolia Intellisearch, the process for setting up other third-party services like Meilisearch, Typesense, or ElasticSearch should be relatively similar. #### Enabling Site Search for a project To get started, please see [Configuring DatoCMS Site Search](/docs/site-search/configuration.md). --- # General concepts — Project Templates Source [docs]: https://www.datocms.com/docs/general-concepts/project-starters-and-templates.md DatoCMS allows you to turn an existing project into a ready-to-clone public template project allowing anyone to bootstrap a new project based off of yours. In this guide you will learn how to make a project public and how to create and configure a clone and deploy link or button to share your project. ## Turn a project into a public template Since projects might contain sensitive information they are all private by default. To make a project public, head to the project main page in the DatoCMS dashboard and switch on the **Public template** project option in the *Danger Zone* section. **Important**: From now on anyone will be able to clone the project, so make sure it doesn't contain any sensitive information! (Image content) Once you've set your project to be a public template, you can then generate: - A "Clone project" button to perform a complete clone of an existing DatoCMS project, or - A "Project starter" button, to clone a project AND deploy a frontend capable of reading the content coming from the project itself. ## Generate a "Clone project" button The "Clone project" button helps users perform a complete clone of an existing DatoCMS project. Once clicked, they will see the following dialog, and at the end of the process a copy of the original project will be available on their dashboard: (Image content) The "Clone project" dialog Use the form below to generate a ready-to-use clone button (the project ID can be retrieved [inside the details page of the project](/docs/general-concepts/project-starters-and-templates.md#project-id)): Project ID \* Project Name \* Use the following code to share the button on your README file or documentation: URL Markdown HTML Button Preview (Image content) ## Generate a "Project Starter" button Most of the time, a DatoCMS project is associated with a frontend project (website, application, etc.) that knows how to query for its content, and renders the result in a pleasant way to users. The "Project starter" button helps users deploy new sites from templates with one single click, performing the following actions for them: 1. Clone a DatoCMS template project and put the copy inside the user account; 2. Fork a Git repository containing the frontend project inside the Github account of the user; 3. Build and publish the frontend online using a free hosting solution (Netlify, Vercel, etc.) Check out our [Marketplace](https://www.datocms.com/marketplace/starters.md) to see a fine selection of Project Starters. (Image content) The dialog that your users will see once they click on a Project Starter button Project Starters are composed of a [DatoCMS template project](/docs/general-concepts/project-starters-and-templates.md#turn-a-project-into-a-public-template), plus a Git repository containing a `datocms.json` configuration file that specifies both presentational metadata (name, preview image, URL of an example of a successful deployment) and the information necessary for creating a new project. You can use the form below to generate a `datocms.json` configuration file and a button to share the starter with the world: Project starter name Description Frontend preview screenshot URL of an example of a successful deployment Github repository that will be copied DatoCMS Project ID that will be duplicated How the project can be built and deployed?Please select one...Simply make a copy of the template repositoryIt can be deployed to any static hosting (Vercel, Netlify)It can be deployed only to VercelIt can be deployed only to NetlifyIt can be deployed only to Heroku ##### Result Copy the following code and add it to your Git repository in a file called `datocms.json`: { "name": "THIS FIELD IS MANDATORY. PLEASE PROVIDE A VALUE!", "description": "THIS FIELD IS MANDATORY. PLEASE PROVIDE A VALUE!", "previewImage": "THIS FIELD IS MANDATORY. PLEASE PROVIDE A VALUE!", "datocmsProjectId": "THIS FIELD IS MANDATORY. PLEASE PROVIDE A VALUE!", "deploymentType": "copyRepo", "environmentVariables": {} } Use the following code to share the button on your README file or documentation: MarkdownHTMLURLButton Preview \[!\[Clone DatoCMS project\](https://dashboard.datocms.com/clone/button.svg)\](https://dashboard.datocms.com/deploy?repo=YOUR-GITHUB-REPO) ##### Project ID The project ID can be retrieved inside the details page of the project in your Dashboard: (Image content) You can find your project ID in your dashboard ##### Supported deployment methods The `deploymentType` setting allows you to configure what deployment target can be used during the cloning process. By setting this value to `copyRepo`, DatoCMS will clone the template on a repository in the user org or account. Additionally, DatoCMS supports the following deployment types: - `vercel` - `netlify` - `static` (user can choose between Vercel and Netlify) When one of these is chosen, users will be asked to authenticate on the service and therefore they need an active and valid account. Once authorized, the DatoCMS integration will deploy the template repository to the service. ##### Build command When the deployment type is either `static`, `vercel` or `netlify`, you must specify the build command that will be run during the deployment of the frontend repository. DatoCMS will forward the `buildCommand` to the deployment service which will use it to build the application. ##### Environment variables When the deployment type is either `static`, `vercel` or `netlify`, you can specify a number of environment variables that will be configured on the hosting platform, before building the actual frontend. The value of each environment variable can be either: - A custom string - The URL of the cloned DatoCMS project (ie. `https://.admin.datocms.com/`) - One of the DatoCMS API tokens present in the template project (you need to specify the name of the API token, ie. "Read-only API token") ##### Post-deploy install URL When the deployment type is either `static`, `vercel`, or `netlify`, you can call a custom hook present in the frontend to add more complex configuration steps. The hook must support CORS for the https://dashboard.datocms.com `Origin`, and will receive a POST request. If the frontend is deployed to Netlify, the HTTP request body will be the following: ```json { "datocmsApiToken": , "integrationInfo": { "adapter": "netlify", "netlifySiteId": , "netlifyToken": , }, } ``` If the frontend is deployed to Vercel, the HTTP request body will be the following: ```json { "datocmsApiToken": , "integrationInfo": { "adapter": "vercel", "vercelApiToken": , "vercelTeamId": , "vercelProjectId": , }, } ``` --- # General concepts — How your website and DatoCMS work together Source [docs]: https://www.datocms.com/docs/general-concepts/how-your-website-and-datocms-work-together.md This article is for DatoCMS users who are not quite sure how a CMS connects to a website, or how a "headless" CMS affects editing workflows. We will explain: - [**How the pieces of a CMS-driven website fit together**](/docs/general-concepts/how-your-website-and-datocms-work-together.md#how-the-pieces-of-a-cms-driven-website-fit-together) - [**What a CMS & headless CMS are**](/docs/general-concepts/how-your-website-and-datocms-work-together.md#what-a-cms-and-headless-cms-are) - [**What you can and cannot edit in DatoCMS**](/docs/general-concepts/how-your-website-and-datocms-work-together.md#what-a-cms-and-headless-cms-are) - [**Who to contact for help**](/docs/general-concepts/how-your-website-and-datocms-work-together.md#who-to-contact-for-help) ## **How the pieces of a CMS-driven website fit together** - **The two main parts:** - **CMS (Content Management System):** This is where you and your team create, organize, and update your content — your articles, images, videos, and more. DatoCMS is one such content management system, and specifically, a *headless* one. More on that later. - **Frontend:** This is what visitors actually see when they go to `your-website.com`. They never directly use DatoCMS the way you do. Your frontend asks our service for the content, but then it takes that content and transforms it into the actual web pages, text, and images that your visitors see. When you hear the word "website" in casual conversation, the frontend is usually what is actually meant. In technical terms, your frontend is where all the HTML, Javascript, and CSS live, and together they form the webpage that browsers like Chrome and Safari show to your visitors. When you need to change some part of your website that isn't strictly "content" — its fonts, colors, behavior, etc. — it is likely the frontend that you (or your developers or web agency) would need to change. - **Other optional parts:** - **Backend:** Some websites also have a behind-the-scenes system for handling ecommerce purchases, complex forms, or other advanced data processing that's better suited for the cloud. Not every site needs one of these, and only rarely does a backend connect to the CMS. Usually, a frontend + CMS is enough. Your visitors never directly see your backend; just like with the CMS, your frontend stands between your visitor and the rest of your website, and the frontend is all they ever see. - **Web host(s):** One or more servers that your frontend and backend code live on. This could be a company like Vercel or Netlify, cloud services like Amazon Web Services or Azure, or rented virtual machines from smaller providers. Importantly, DatoCMS is NOT a webhost, and we do not hold any of your frontend or backend code. - **Content Delivery Networks (CDNs):** These are global networks that hold copies of your frontend (or parts of it) for global distribution, making your website faster for users all over the world. A CDN lets visitors access your website from data centers close to them, instead of having to connect to a web host half the world away (which would be much slower). - **DNS servers, domain registrars, and more:** Behind the scenes, many more services work together to ultimately enable visitors to find your website at `your-website.com`. A full explanation of all of them is beyond the scope of this article, but thankfully, these are often set-and-forget and don't require day-to-day maintenance. If anything does go wrong with them, your developers, web agency, and/or web host should be able to help. DatoCMS also does not include any of these services. ## What a CMS and *headless* CMS are A CMS is a content management system, a place to store, edit, and retrieve your content easily for use and re-use across one or more websites/apps/frontends. **Traditional CMSes manage your content and website frontend and backend together** in one big app. This heavyweight, monolithic approach was common for traditional web teams who wanted everything together in one place, inside one app, with full control of all of it. **Headless CMSes are a lightweight alternative that only deal with the content, not the rest of the website**. This was an evolutionary development in CMS design that enabled more flexibility and modularity. A "headless" setup allows CMS providers (like DatoCMS) to focus on just the CMS, a frontend company to focus on the frontend, etc. Some teams prefer this modular, mix-and-match approach because they can customize each component and choose the best fitting ones for their team. It is also a deliberate separation of concerns that allows content editors to work on content and coders to work on code, neither stepping on the other's toes. New posts can be published without needing code changes, and code changes don't need to cause a content freeze. Each system and role can focus on their sphere of responsibility. And why the term "headless"? Well, the frontend is one of the things that a headless CMS does NOT include. And the frontend is typically thought of as the "face" of a website. No face = no head. Our service only give you the content "body" of a website, and it's up to your team to design one or more "faces" for it: the layout, the behavior, the fonts, the colors, etc. Maybe there's one website for computers and a separate app or phones, or maybe there's just one unified, responsive website for a variety of devices. In either case, that's the only part your team has to worry about. In this headless setup, we provide the "body" and your team provides the "head": - Everything on **datocms.com** and **datocms-assets.com** is our responsibility and managed by us. (You still retain ownership and copyright of your content, of course.) - Everything on **your-website.com** belongs to your team, and it's up to your devs or web agency to manage those. ## What you can and *cannot* edit in DatoCMS You can use DatoCMS to edit anything on **datocms.com** and **datocms-assets.com**: - Your content and schema, like your blog posts or the fields in them. You do this through the DatoCMS admin interface, like `your-project.admin.datocms.com`. - Your images and videos that you've uploaded to the media area. These are managed and edited through the same admin area as the rest of your project. DatoCMS (the CMS software, and us, the staff) **cannot**: - Edit your website layout, fonts, colors, etc. Your frontend and backend live on a separate web host, not our servers. - Change your web hosting (like going from Vercel to Netlify, or fix issues with Amazon Web Services) - Change your domain name (like going from `your-website.com` to `new-website-name.com`) - Help with email inbox problems (like not getting email at `you@your-website.com` or deliverability issues) - Basically, anything not directly inside DatoCMS - **But if you're not sure... go ahead and ask us and we'll do our best to help you figure it out!** ## Who to contact for help - **Generally speaking, start with your own team of developers** (or the **agency that built your website**, if you don't have in-house developers). They should be able to diagnose and fix the issue directly, or at least know who can. - **DatoCMS support can only help you with DatoCMS issues**, which is any service on **datocms.com** or **datocms-assets.com**. We generally cannotdirectly help you with your website, e.g., anything on `your-website.com`. Your own team is the best resource for that. If you ask us anyway, we may take a look and try to provide some general guidance, but ultimately our reply is going to be some form of "this is what the problem looks like to us... you can share our findings with your developers, but they'll have to be the ones to fix it". We don't have any way to access, edit, or otherwise fix your website directly. We don't have your logins or access to your code. That's up to your team. But we'd be happy to take a look anyway, and offer whatever guidance we can. - If you're ever **not sure who to contact, that's perfectly OK, just reach out to us anyway!** 🙂 We don't expect you to be an expert at all this, and if you ever ask us about something we can't fix, we'll still try our best to point you in the right direction. You'll probably end up talking to your developers or web agency in the end, but at least you can start with us. We'll help you figure it out together. You can contact us using [our support form](https://www.datocms.com/support.md#form?topics=technical-support%2Fgeneral-request) or directly via email at support@datocms.com. --- # General concepts — How to deploy Source [docs]: https://www.datocms.com/docs/general-concepts/deployment.md Once you are all set with DatoCMS and your site is successfully pulling content on your local development machine, your next step is to deploy the site and then give your editors some control and visibility over the deploy process. The job of building and deploying your website is not performed directly by DatoCMS, but is delegated to an external Continuous Deployment/Continuous Integration service. To integrate DatoCMS with these tools, you can use what we call **build triggers**. Essentially, they are a set of webhooks that you can manually trigger to launch your build process on your preferred continuous integration or continuous deployment platform. We offer out-of-the-box integrations with all the most popular solutions out there (most of them have a free plan available): - [Netlify](https://www.datocms.com/marketplace/hosting/netlify.md) - [Vercel](https://www.datocms.com/marketplace/hosting/vercel.md) - [Gitlab CI](https://www.datocms.com/marketplace/hosting/gitlab.md) If you need to use another CI tool, we also offer a [custom webhook](https://www.datocms.com/marketplace/hosting/custom-webhook.md) that you can use to connect DatoCMS to your custom deployment solution. Once everything is set up, in the top navigation bar of the DatoCMS interface, you will find a "**Publish changes"** button: your editors will be able to request a new publication of the website whenever they like. If you have multiple build triggers, you'll be able to trigger builds independently and manage permissions and logs for each environment. Have a look at this quick demo to see how things work: (Video content) Check the Marketplace for all the available [Hosting and CI building](https://www.datocms.com/marketplace/hosting.md) options. --- # General concepts — Primary and sandbox environments Source [docs]: https://www.datocms.com/docs/general-concepts/primary-and-sandbox-environments.md Traditional CMSs often treat content as a one-off effort, which makes content management difficult to fit into existing development lifecycles. Content environments make it easier for your development team to **manage and maintain the content structure once your content has been published**. Think of environments as code branches: they're great for testing, development and pre-production. In short, environments ensure quick turnaround times and flexibility for developers — without interrupting the editorial workflow. ### What's an environment? By default, every project has one environment, called the **primary environment**, which is meant to be used for the regular editorial workflow. Additionally, developers can create multiple **sandbox environments** to safely test and experiment with changes in the content. (Image content) Sandbox environments start out as **exact copies of one of the existing environments** (i.e., the primary one). The process of creating a new sandbox from an existing environment is called **forking**. Each environment is identified by a name (e.g., `master`) and stores the following information: - Models - Records - Uploads - Plugins - The content navigation bar - Configuration (locales, timezone settings, appearance, SEO preferences) When making changes to any of the aforementioned entities in any environment, including the primary environment, **the data in all other environments remains unaffected**. ### Creating a new sandbox environment To manage all your project's environments, head over to the *Project Settings \> Environments* section. To create a new sandbox starting from an existing environment, click on the contextual menu \> **Fork**, and choose a name for the new environment. (Video content) DatoCMS will perform a deep copy of all the information contained inside the source and transfer it to the new sandbox. Once there's at least one sandbox environment, developers will be able to **switch environments using the top bar panel**. Editors will never see this panel due to a reduced set of permissions and will continue their editorial workflow in the primary environment as usual. (Video content) ### Promotion of sandbox environments At any time, you can **promote a sandbox environment to become the new primary environment**. The old primary environment will be demoted to a sandbox environment, and content editors will immediately see the interface refresh. From that moment, they will only be able to see and make changes to the new primary environment. To be updated when a sandbox gets promoted, you can [set up a webhook](/docs/general-concepts/webhooks.md#webhook-triggers) listening to the "Environment Promote" event. ### Renaming environments At any time, you can change the name of an existing environment. This change won't impact those working on the CMS: (Video content) To be updated when a sandbox gets renamed, you can [set up a webhook](/docs/general-concepts/webhooks.md#webhook-triggers) listening to the "Environment Update" event. ### Forcing use of sandbox environments Changes to a primary environment can be potentially disruptive, so we give you the ability to **block any user from editing the primary schema or configuration.** You can do this by going to Project settings \> Global properties and enabling "**Force the use of sandbox environments".** If enabled, no user can edit the primary environment and make changes to its schema and configuration, regardless of their role. --- # General concepts — Project usages Source [docs]: https://www.datocms.com/docs/general-concepts/project-account-usages.md On DatoCMS, usage quotas are tracked per account or per project. Let's see what they are, the differences between them, and where you can monitor them. ### Per-account resources **Each account has quotas that are shared among all projects**. In particular, the shared resources are: - Records - File storage - API calls - Bandwidth - Video encoding - Video streaming These resources can be monitored from your dashboard, [in the plan details](https://dashboard.datocms.com/plan-billing), where you can monitor how your resources are used across different projects, so you can better understand which ones you should optimize, or which of your clients should be billed more for their usage. ### Per-site resources In each project you can drill down into the traffic, API calls and video streamed: (Image content) And you can change the reports, using this dropdown: (Image content) This helps you better understand where the traffic is coming from and how to best optimize the use of resources in your project. --- # General concepts — Audit Logs Source [docs]: https://www.datocms.com/docs/general-concepts/audit-logs.md The Audit Logs functionality is for monitoring audit events happening in an Enterprise project and ensure continued compliance, safeguarding against any inappropriate system access, and allowing you to audit suspicious behavior within your enterprise. The idea is to give Enterprise organization owners the ability to query user actions in a project. With Audit Logs, you can: - Automatically feed DatoCMS access data into a SIEM or other auditing tool - Proactively monitor for potential security issues - Write custom apps to gain insight into how your organization uses DatoCMS An audit log provides insight into audit events that are actually happening across a DatoCMS project, and is therefore read-only and immutable. You can filter for specific actions or actors to see who made changes on specific resources in the app using a very powerful SQL-like language called PartiQL, or use the Query Builder GUI that lets you build a filter using a familiar UI. (Image content) Actors can include both logged-in users as well as access tokens. You can either browse and filter audit log events via the interface or through [API calls](/docs/content-management-api/resources/audit-log-event/query.md), and the retention window is fully customizable. By default, Audit Logs have a Time-to-Live (TTL) of two months from the date of writing. However, it is possible to customize the TTL for individual projects. To make such customizations, please contact [our support team](https://www.datocms.com/support.md), and we will be happy to assist you. If you're interested in trying out Audit Logs for your projects, [contact our Sales team](https://www.datocms.com/contact.md) to set up a free trial. --- # General concepts — How to manage a live and a preview site Source [docs]: https://www.datocms.com/docs/general-concepts/how-to-manage-a-live-and-a-preview-site.md As soon as you go live with a site you need to have a way to save and preview content before going live. To do that in DatoCMS you can enable the [draft/published system](/docs/general-concepts/draft-published.md) on a per-model basis. Once you have created your new draft records you might want to preview them, but how? You can combine the draft/published system with the [deployment environments](/docs/general-concepts/deployment.md) to achieve that. For example you can have your live site pulling content from the main GraphQL endpoint and instead your *staging* pulling your drafts from the [preview endpoint](/docs/content-delivery-api/api-endpoints.md). If you are using our REST API instead you can fetch the draft content using the `version` attribute, [for example on the records](/docs/content-management-api/resources/item.md#instances). Finally you can leverage the deployment environments if you want to let your editors be able to manually trigger builds for the different sites. See also: [(Image content)Web Previews](https://www.datocms.com/marketplace/plugins/i/datocms-plugin-web-previews.md), an official plugin that makes it easy to preview your changes inside or next to DatoCMS. --- # Content modelling — Introduction to Content Modeling Source [docs]: https://www.datocms.com/docs/content-modelling.md DatoCMS can be seen as an editor-friendly interface over a database, so the first step is to build the actual schema upon which users will generate the actual website content. The way you define the kind of content you can edit inside each different administrative area passes through the concept of models, which are much like database tables. Each administrative area can specify a number of different models, and they represent blueprints upon which users will store the website content. For example, a site can define different models for articles, products, categories, and so on. You can create new models in the *Settings \> Models* section of your project: (Image content) Each model consists of a set of fields that you define. Fields can be one of the following: - **Single-line string**: Ideal for titles, headings, etc. - **Multiple-paragraph text**: For simple Markdown, HTML or plain text. - [**Modular content**](/docs/content-modelling/modular-content.md): To define dynamic layouts for ie. landing-pages and give the content writers the choice between different template options. - [**Structured text**](/docs/content-modelling/structured-text.md): To store rich-text content, complete with images/videos/custom blocks using a portable JSON format. - **Asset gallery**: To store one or more files (for sliders, carousels, etc.). - **Single asset**: To store any kind of document (images, PDFs, ZIPs, videos, etc.). - **Video**: To reference to an external YouTube/Vimeo video. - **Date** and **DateTime**: A timestamp value for storing dates and times (i.e. an event start, office opening hours). - **Integer** and **Floating-point number**: For storing integer SKUs, quantities, prices, etc. - **Boolean**: For storing values that have two states, e.g., yes or no, true or false etc. - **Geolocation**: Coordinate values for storing the latitude and longitude of a physical location. - **Color**: For storing colors (with or without alpha channel). - **SEO meta tags**: To manage a page meta title, meta description, OpenGraph cards, etc. - [**Slug**](/docs/content-modelling/slug-permalinks.md): To generate a page permalink based on another textual field of the model. - [**Single and multiple links**](/docs/content-modelling/links.md): To model relationships between content, including other models. For example, linking a blog to a category. - **JSON**: For storing JSON objects. (Image content) Field type selection modal Each field has a name and additional metadata, like validations, or particular configurations to better present the field to the editor (hints, etc.): (Image content) Validations tab in Field settings (Image content) Presentation tab in Field settings Fields in DatoCMS can also be [localized](/docs/general-concepts/localization.md), if you need to accept different values based on language. DatoCMS stores the individual pieces of content you create from a model as records, which are much like table rows in a database. You (and your editors) can create new records of a certain model within the *Content* tab of your administrative area: (Image content) #### New to DatoCMS? If you want to get started with DatoCMS and learn the basics, check out these video tutorials for beginners! [ (Image content) Intro to the Schema Builder Play video » ](https://www.datocms.com/user-guides/the-basics/intro-to-the-schema-builder.md) [ (Image content) Intro to Models in DatoCMS Play video » ](https://www.datocms.com/user-guides/content-modeling/intro-to-models-in-datocms.md) [ (Image content) Intro to Fields in DatoCMS Play video » ](https://www.datocms.com/user-guides/content-modeling/intro-to-fields-in-datocms.md) --- # Content modelling — Single instance models Source [docs]: https://www.datocms.com/docs/content-modelling/single-instance.md Real-world websites have often pages which don't resemble any other (eg. the *About us* page, or even the homepage). If you want to allow the editors to change their content, you can create a Single-instance model: (Image content) While *collection* models enable the creation of multiple records, *single-instance* models allow just a single item to be edited in the administrative area. --- # Content modelling — Record ordering Source [docs]: https://www.datocms.com/docs/content-modelling/record-ordering.md The record collections can be ordered in different ways: - By the records that were last updated first (default ordering) - By one specified field, in ascending or descending order - In a tree-like structure - By drag and drop reordering The default ordering should be quite self-explanatory. The same goes for ordering by specified field. You can select the field and the ordering direction in the model settings: (Image content) The tree-like structure has [its own documentation page](/docs/content-modelling/hierarchical-sorting.md) where you can see it in action. Last but not least, we have drag and drop reordering. In this case, once you select the appropriate choice from the usual dropdown, you will have the option of dragging and dropping the records in the collection list. In case you need to move a record across pages, you can enter the record and change the position attribute in the right sidebar: (Image content) ### Caveat One thing to note about the drag and drop reordering and the tree-like structure reordering is that as soon as you change the position of a record, it's updated in the API, even for published records. This means you cannot have separate draft/published states for the position attribute. --- # Content modelling — Hierarchical sorting (Tree-like collections) Source [docs]: https://www.datocms.com/docs/content-modelling/hierarchical-sorting.md > [!NOTE] Tree-like Collections are renamed to Hierarchical Sorting > In 2025, we changed the name of this feature for better clarity. The underlying functionality is still the same. Taxonomies, product categories, navigation bars... websites are full of hierarchical data. DatoCMS is the only headless CMS that supports tree-like data structures out-of-the-box, offering a delightful editing experience for your editors and marketers. If you want to arrange a model collection as a hierarchy or tree, you need to select "Hierarchical sorting" in the model's Presentation settings, in the "Default collection ordering" field. (Image content) Hierarchical sorting, much like other models, is also presentable in a compact or a tabular view, depending on which appearance best suits your workflows. (Video content) Additionally, both the tabular and the compact view are paginated, and records are incrementally shown as they are loaded. --- # Content modelling — Record block limits and byte size limits Source [docs]: https://www.datocms.com/docs/content-modelling/record-block-limits-and-byte-size-limits.md Records are subject to technical limits that apply regardless of your DatoCMS pricing plan. These limits are in place to protect the reliability and performance of our shared infrastructure. ## Record Block Limits ### Maximum number of blocks per record Each record can have **up to 500 blocks, shared between all of a record's locales.** Examples: - A single locale can use all 500 blocks for itself - Two locales can split it 250 each, or 400 for one locale and 100 for the other - Five locales can split it 100 each, or any way they want, as long as the record total is less than 500 You do not need to "pre-assign" a particular number of blocks per locale. The limit is dynamically calculated as you type, and if you use more blocks in one locale, the others will naturally have fewer remaining. There is only ever one **per-record total blocks limit, not a per-locale one**. ### **How to see the number of blocks currently used** **The record sidebar always shows the Currently used blocks**, e.g. `90/500 (18%)`. Additionally, the system will show you a warning at the top of the record if you are at risk of hitting the record limit. (Image content) ### Maximum block nesting depth You can nest up to **5 layers of blocks** inside each other**.** If you reach the limit, you will see a "Reached maximum blocks depth!" warning: (Image content) ### How to avoid hitting the blocks limit We recommend keeping these limits in mind when you design your schema. Consider splitting up overly complex/long models into several smaller ones, and use a Link field to reference them from one another. Not only does this help you avoid reaching the limits, it also makes the editor experience more pleasant — it's generally easier to work on a few well-organized, mid-sized records than a single huge, long one. ## Record Byte Size Limits Records must stay under **300 KB**, including the content in all of its **blocks, fields and locales.** Please note that hidden content, such as invisible markup & metadata (most commonly found in HTML fields), also count towards this limit. You will see a warning below the field if we detect a field with excessive hidden content. (Image content) In that case, you should edit the source code to make sure there is no unnecessary metadata or other hidden content in the field. **The most frequent source of unexpected hidden content is copying & pasting from other desktop or web apps, such as word processors or design tools**, which can add metadata to their copied text for their internal use. Such metadata is not useful in the context of DatoCMS and your frontends and can usually be safely deleted. ## What to do if you hit the record block or size limits First, please consider whether your model schema and fields can be modified to better fit within the limits. You can split up overly an complex model with too many fields into several smaller ones, for example, and use Link fields to reference them from one another. For the cases where an extremely long page (privacy policy, legal terms & conditions, etc.) cannot be further subdivided and must have very long text and blocks in multiple locales, you can consider making one record per locale. This makes for a slightly awkward editor and developer experience, but it is better than running out of space or blocks altogether. As a last resort, in exceptional cases, we *may* raise these limits after a technical evaluation of your project. Please [contact support](https://www.datocms.com/support.md?topics=technical-support%2Fgeneral-request) and we'll review your model schema and record contents. If we cannot find a suitable workaround, we may *slightly* increase the limits — but only if we determine, in our judgment, that doing so would not degrade performance or reliability for you or other customers. --- # Content modelling — Blocks Source [docs]: https://www.datocms.com/docs/content-modelling/blocks.md Blocks are a concept unique to DatoCMS and are the foundation behind powerful flagship features such as [Modular Content](/docs/content-modelling/modular-content.md) and [Structured Text](/docs/content-modelling/structured-text.md), which we advise you to read about in detail. In a sentence, though, blocks allow you to define **complex and repeatable structures that can be embedded inside records**. Modern web design often involves the use of repeated "graphic components" across pages — call-to-actions, sliders, testimonial quotes, etc. Blocks allow developers to clearly represent each of these objects, so that they can then be used and reused in the content of individual pages by marketers and content creators, giving them significant expressive freedom. You can manage your Blocks Library inside the settings area of your project: (Image content) The "Blocks Library" section ## What can you do with Blocks? You can use blocks in two different contexts, to achieve different results: - Using [Structured Text](/docs/content-modelling/structured-text.md) fields, you can produce great pieces of content by interleaving free-form text with blocks representing predefined graphic components (CTA, quotes, image galleries, infographics, etc). - Using [Modular Content](/docs/content-modelling/modular-content.md) fields, you can create a page-builder experience that enables your editors to assemble various blocks like Lego pieces, allowing for the construction of any dynamic layout — particularly beneficial for landing pages. ## Key concepts - Just like records, a block is a composition of fields, on which you can define custom validations; - Blocks defined in the library can be reused across different models; - Unlike records, **blocks do not exist independently, but only within a parent record.** For this reason, **blocks do not count towards your plan's records limit,** and cannot be referenced in [Link fields](/docs/content-modelling/links.md). They only live inside [Modular Content](/docs/content-modelling/modular-content.md) and [Structured Text](/docs/content-modelling/structured-text.md) fields. - When a record gets deleted, all the blocks it contains are deleted with it. This leaves no orphan data structures lying around your project. - Block fields per se cannot be localized. Instead, it's the containing Modular Content or Structured Text field that can be localized, so that different content/blocks can be defined for each language. (Image content) While link fields reference other records, Modular Content and Structured Text fields let you embed blocks inside the record ## When to use blocks instead of models? It's fairly easy to recognize when a piece of content should be modeled as a model or block if you ask yourself the following questions: - *"Would I ever want to reference this content outside of the record in which it is defined?"* — if so, then it should be a model. - *"Does this content have standalone value, or does it make sense only in the context of a parent record?"* — in the first case, it should be a model; otherwise it should be a block. - *"If the parent record were to be deleted, do I want this content to be deleted as well, or would I like it to remain?"* — in the first case, it should be a block; otherwise it is a model. #### Learn more about content modelling and blocks Check out these video tutorials to get the best out of DatoCMS: [ (Image content) Intro to Blocks in DatoCMS Play video » ](https://www.datocms.com/user-guides/content-modeling/intro-to-blocks-in-datocms.md) [ (Image content) Working Together - Let's Build Blocks! Play video » ](https://www.datocms.com/user-guides/content-modeling/working-together-let-s-build-blocks.md) [ (Image content) Working Together - Enriching Content With Blocks Play video » ](https://www.datocms.com/user-guides/content-management/working-together-enriching-content-with-blocks.md) [ (Image content) Working with nested blocks Play video » ](https://youtu.be/AKkefmOZVJk) [ (Image content) Creating a Landing Page using the Atomic Design System Play video » ](https://www.youtube.com/watch?v=rajqgvg2e0w) --- # Content modelling — Modular content fields Source [docs]: https://www.datocms.com/docs/content-modelling/modular-content.md The **Modular Content** field is used to define a dynamic area for richer page layouts. For example, in a landing page, defining a Modular Content field allows the writer to choose between adding a text section, a carousel, or a call-to-action. This gives the writer the freedom to compose a landing page by alternating and ordering as many of these choices as needed. (Video content) You can use Modular content to define dynamic layouts in any of your models: blog posts, landing pages, case studies, tutorials, or any place you want to give content writers a choice between different template options. Developers are in charge of defining which elements writers can use to compose content for a specific modular content field. You can think of those as "low-level" models, called *Block models*. Authors, to compose their dynamic content, will be able to add and reorder these blocks as they prefer. ## How to build a Modular content editor Suppose we have an *Article* model, and we want to add a modular content field to manage its content. The first step is to decide the different kinds of basic blocks you want your authors to alternate. In this case, we want our content to be a flexible composition of: - Text - Quotes - Videos - Text + Image blocks To achieve this result, first, we create the Article model, and add a Modular content field to it: (Image content) In the*Validations* tab,you can choose which blocks will populate your modular content field. Let's add the Quote block: (Image content) ## Create and edit a block If you go to the *Blocks* tab in the Schema area, you will see all the blocks that you have already created, and you can create a new one: (Image content) Blocks are just a composition of fields, just like ordinary models. In our case, we want the *Quote Block* to be made of two fields: one containing the actual quote, and another containing the author. You can click on the "Create new block" button on the bottom left to create a new block. In this case, we'll add a multi-paragraph text field to contain the text of the quote, and a single-line string text to display the name of the quote's author. If this block is used in one of your Models, you will see a notice. For example, we see that our *Quote* blockis used in the *Product* modular content field, which is part of the *Article* model. (Image content) If you go to your Content area now, you should see a new option called "Quote" in the modular content field's dropdown. (Image content) ## Bulk Actions Managing Modular Content is efficient with common Bulk Actions. You can easily select multiple Modular Content items and perform actions all at once from the action bar. (Video content) Each Modular Content Block includes a checkbox for easy selection, and you can perform bulk actions such as: - Select All / Invert Selection - Expand / Collapse selected blocks - Copy multiple blocks - Delete selected items (Video content) The contextual submenu makes managing blocks in the UI equally simple, with an improved flow to: - Copy & Paste - Duplicate - Move - Delete, and - Add Blocks ## Reusing block models With these building blocks, you can start to design and develop a modular template that matches models and modular blocks in DatoCMS' schema. Once you have set up the different blocks, you can reuse them across different models. This means that the exact same block structure is reused across modular contents and models. If you modify the block in one place, the changes will be reflected across all modular contents. This will effectively enable you to develop a modular template that will allow editors to build complex pages just by creating new records in the CMS. ## Single vs Multiple blocks In your schema, there are two flavors of a Modular Content field you can opt for: Single Block and Multiple Blocks: (Image content) The Single Block allows authors to slot in just one block within the field, while the Multiple Blocks provides the flexibility to insert several. Hence, when you're fetching the value tied to modular content, you're either looking at an array of blocks or a single block. In the case of Single Block, you can still allow the author to insert different types of blocks depending on the context, but always one at a time. ## Reusing fields across models with "Frameless" Single-block As a project's complexity scales up, we frequently encounter the need to reuse subsets of fields across various models. Redundantly duplicating these fields or manually keeping them in sync isn't an appealing approach. Let's say you have different content types like "Blog Post," "News Article," and "Product Review." Each of these models may have common fields like title, author, and tags. However, they will also have specific fields like "Body" for blog posts, "Summary" for news articles, and "Rating" for product reviews. Despite the differences, they all share a common structure with some overlapping fields. In these scenarios, we can effectively leverage the reusability of block models coupled with the "frameless" display mode of the Modular Content (Single Block) field to achieve our goal. First, let's create a new type of block model. Let's call it "Bloggable", and define all the shared fields within it: (Image content) At this point, in all the "Blog Post," "News Article," and "Product Review" models, we should incorporate a Modular Content (Single block) field. The field should be arranged as follows: - It should only have "Bloggable" as its associated block model; - It should have the Required validation active; - The "Frameless" presentation mode should be active. (Video content) The "Frameless" presentation mode will conceal the Modular Content field from the authoring interface, and only show the fields of the block model **as if they're an intrinsic part of the model itself**: (Video content) ## Tutorials If you're curious to see the full power of Modular Content fields in action, take a look at this video tutorials which covers everything you need to build a customizable landing page made of different reusable blocks. [ (Image content) Intro to the Modular Content Field Play video » ](https://www.datocms.com/user-guides/content-modeling/intro-to-the-modular-content-field.md) [ (Image content) Building Pages and Deep Dive into Modular Content Play video » ](https://www.datocms.com/user-guides/content-management/building-pages-and-deep-dive-into-modular-content.md) [ (Image content) Working Together - Creating Our First Case Study Play video » ](https://www.datocms.com/user-guides/content-management/working-together-creating-our-first-case-study.md) [ (Image content) Build a dynamic landing page with Next.js and Tailwind CSS Play video » ](https://www.youtube.com/watch?v=it5nNneptgM) --- # Content modelling — Structured text fields Source [docs]: https://www.datocms.com/docs/content-modelling/structured-text.md Structured Text is a field type that enables authors to **create rich text content**. - It offers a beautiful, Notion-like editor **designed for focus**, with slash commands, a full editing toolbar, markdown/keyboard shortcuts, and drag & drop functionality. Forget the mouse, and just start typing; - It allows you to create hyperlinks to other records in your project, and **intersperse textual content with custom blocks** - which can represent galleries, videos, embeds, call-to-actions, etc. - It stores the content in a safe, semantic, and readable **JSON format**, representing a tree of well-defined nodes. ## Backstory Everyone hates HTML editors: developers know they produce dirty code, designers fear the introduction of unwanted styling, and editors struggle to use them. Markdown is better for designers, as it allows less freedom for editors from a formatting standpoint (at least until you start inserting HTML code), but it's not user friendly for editors, and it's an inflexible format for developers. Sure, DatoCMS provides both an HTML and a Markdown editor, because there are situations where they're unavoidable, but often, when a project needs rich-text, **it is advisable to use Structured Text fields** instead. ## Preview of the editor We designed the Structured Text editor to offer one of the best writing experiences on the market. It supports Slash commands, Markdown shortcuts, and full-screen focus mode. Here's a quick video of it: (Video content) For editors, familiarity with various content creation workflows is supported within the Structured Text field. In addition to slash commands, the floating formatting toolbar, and markdown support, the field also offers a full formatting toolbar visible when the field is in an active state. (Video content) The toolbar allows for advanced formatting options, as well as complete customisation with custom icons for plugins. Here is a brief look into all the available options to editors. (Video content) ## Customizing the editor A key aspect of Structured Text is the ability to customize the field so that authors are only exposed to relevant formatting options. For example, you can have fields with only certain header tags or limit the kinds of entries that can be hyperlinked or embedded: (Image content) To add custom blocks to the field, follow this short video: (Video content) Furthermore, you can enhance the field by adding custom icons into the Structured Text toolbar to interact with plugins and other customizations. ## Structured text on the API Structured Text content is stored as a JSON object. We chose [unist](https://github.com/syntax-tree/unist) as our base format to benefit from its ecosystem of utilities for working with compliant syntax trees. The `dast` format clearly specifies: - which nodes are usable within the document; - for each node, which are the possible `children` that it can contain; - any additional attribute that characterize each node. Take a look at the [**DatoCMS Abstract Syntax Tree specs**](/docs/structured-text/dast.md) to learn all the details. ### Linking records Structured Text allows hyperlinking DatoCMS records in the flow of text. This allows the following scenarios: - Using custom link functions, like React Router links, to a DatoCMS record. - Rendering a widget such as an image gallery, a product description box, a sign up form, an annotation window, or basically anything else. The following example demonstrates an hyperlinked record and an inline record: (Video content) ### Embedding blocks Similarly to [Modular Content](/docs/content-modelling/modular-content.md) fields, you can also embed block records into Structured Text. Blocks and records can be embedded either using slash commands or the toolbar. Here's a demonstration: (Video content) Just like with the Modular content field, when a record is deleted, the blocks contained inside its Structured Text fields are also deleted, without leaving orphans in the process. ### Next steps - [Structured Text format](/docs/structured-text/dast.md) - [Migrating to Structured Text](/docs/structured-text/migrating-content-to-structured-text.md) - [Creating Structured Text fields using the CMA](/docs/content-management-api/resources/field/create.md#creating-structured-text-fields) - [Creating records with Structured Text fields using the CMA](/docs/content-management-api/resources/item/create.md#structured-text-fields) - [Fetching Structured Text using the GraphQL CDA](/docs/content-delivery-api/structured-text-fields.md) ### Video tutorials [ (Image content) Intro to String (Text) Fields Play video » ](https://www.datocms.com/user-guides/content-modeling/intro-to-string-text-fields.md) [ (Image content) Deep Dive into Structured Text in DatoCMS Play video » ](https://www.datocms.com/user-guides/content-management/deep-dive-into-structured-text-in-datocms.md) [ (Image content) Working Together - Creating Our First Blog Post Play video » ](https://www.datocms.com/user-guides/content-management/working-together-creating-our-first-blog-post.md) --- # Content modelling — Link fields Source [docs]: https://www.datocms.com/docs/content-modelling/links.md Links are a powerful way to model relationships between content. Models can have link fields which point to other records, for example: - An article linking to its category (singular relationship). - An article linking to related articles (plural relationship). In DatoCMS, you don't need to define a field for the reverse relationship (i.e., the category linking to its articles): during the integration with your website, you can easily perform reverse reference lookups with just a couple of lines of code. When you add a new field of type **Link** (or **Links**) to a model, DatoCMS requires you to specify within the *Validations* tab the models that can be referenced by the field itself. To let editors select one (or more) records to link, DatoCMS will present a dropdown with auto-completion turned on: (Video content) ### Expanded view If you prefer, you can switch any link field to **Expanded view** mode, to provide your editors with a nicer, more meaningful preview of the linked records: (Image content) As with any other field, this setting can be found under the *Presentation* tab of your field: (Image content) [ (Image content) Intro to the Link Field Play video » ](https://www.datocms.com/user-guides/content-modeling/intro-to-the-link-field.md) --- # Content modelling — SEO fields Source [docs]: https://www.datocms.com/docs/content-modelling/seo-fields.md If you are building a website, you need to think about SEO and provide special content for search engines and social networks. To help content editors and marketers optimize your website, you can find a special "SEO and Social" type of field that lets you specify a custom title, description, image, and Twitter (X) card format, and gives a nice preview of how the result will look like on Google Search and Social Networks. Here's how it works: (Video content) These are all the available fields: - **Title:** Customize the SEO title for your content. - **Description:** Craft a unique meta description to enhance search engine visibility. - **Image:** Set the featured image to be displayed in social previews. - **No Index:** Control whether the page should be indexed by search engines. - **Twitter (X) Card:** Fine-tune the appearance of shared content on X. > [!PROTIP] Pro tip: Set SEO fallback > You can set up fallback options for the SEO title and description for your models in case you don’t add SEO fields to a model or if your editors do not fill in the SEO fields. Just go to the Content area and click “SEO Preferences” in the main (left) sidebar. > > See also: How SEO fallback works with the Content Delivery API is discussed here: [SEO and favicon fields](/docs/content-delivery-api/seo-and-favicon.md) ## Customizing SEO Fields and Social Link Previews #### SEO Fields Customization By navigating to *Edit field \> Presentation*, you can tailor the SEO fields that are displayed to editors, by selecting from the options. Select the fields that align with your editorial needs, providing a more focused and efficient editing environment. #### Social Link Previews Customization By navigating to *Edit field \> Presentation*, you can choose which social link previews to show your editors, ensuring your shared content looks compelling and engaging across various platforms. You can choose to display link previews for Google Search, X (Twitter), Facebook, Slack, Telegram and WhatsApp. ## Global SEO preferences Also, globally, you can define a favicon for your site and a set of fallback meta for the site title, image, and description: (Video content) ## API helpers When fetching records from our GraphQL API, you'll find a `_seoMetaTags` helper which contains all the meta tags we offer, with the data already merged with the global SEO preferences and fallbacks. You can read all the details in the relevant [section of the CDA docs](/docs/content-delivery-api/seo-and-favicon.md). Want to know more about SEO customization in DatoCMS? Check out this video tutorials: [ (Image content) Understanding SEO in DatoCMS Play video » ](https://www.datocms.com/user-guides/content-management/understanding-seo-in-datocms.md) [ (Image content) Intro to the SEO Fields Play video » ](https://www.datocms.com/user-guides/content-modeling/intro-to-the-seo-fields.md) [ (Image content) Working with and customizing SEO Fields Play video » ](https://youtu.be/WjF10isSjS0) --- # Content modelling — Slugs and permalinks Source [docs]: https://www.datocms.com/docs/content-modelling/slug-permalinks.md In DatoCMS, you can add a special field type called "Slug" to your models to let your editors specify the URL permalink of a record. A slug field is linked to another single-line string field of the same model, usually the title. As soon as the editor begins to type the title, the slug field will be filled with an URL-friendly version of the same string: (Image content) The nice thing about slug fields is that, if the editor subsequently updates the record's title, the slug won't change, preserving all the SEO benefits. ### How to add a slug field to a model Say you have a "Blog post" model; start by adding a "Title" field, then you can add an automatically-generating Slug field (you can find it under the *SEO* group) by selecting the Title field as its reference, under the *Validations* tab. (Video content) --- # Content modelling — External video field Source [docs]: https://www.datocms.com/docs/content-modelling/external-video-field.md One of the fields that you can use in DatoCMS is the **external video field**, that allows you to reference an external YouTube, Vimeo or Facebook video. Via [oEmbed](https://oembed.com/) we'll fetch and store the thumbnail image, the title and the dimensions of the video. All information that you can then retrieve via the APIs. ### How to publish a scheduled YouTube video Unfortunately, oEmbed information can only be fetched from public videos, and not private videos with a scheduled publication date. This YouTube feature is very useful together with the [scheduled publication](https://www.datocms.com/blog/scheduled-publishing-during-christmas.md) of DatoCMS's records. But how can you make the two work together? There's a little trick that you can use, it's not super handy but will do the job: - set the video to unlisted, unfortunately you cannot schedule an unlisted video to be listed - add the video to DatoCMS - set the video to private again and schedule the publication - schedule the publication of DatoCMS record together with the YouTube video That's it! A bit hackish, but it's a way to work around the limitations of the system. --- # Content modelling — Validations Source [docs]: https://www.datocms.com/docs/content-modelling/validations.md Validations are a powerful tool to enforce a sound structure of your content. They can help in different ways both editors and developers. ### For editors If you have an editorial team with different people working on content, you need to explain to everyone what are the rules they have to respect for the final page to look good and make sense. Also sometimes developers need to enforce some content rules to make everything work together. With DatoCMS **you can enforce all these rules on a per model/field basis**, preventing editors to save content that would break pages or make poor content. For example, you can make certain fields as required, enforce certain text lengths and much more. Enabling the "**Allow saving invalid drafts?**" flag on a per-model basis also allows editors to save invalid draft versions of records. In this case, validations will be enforced just right before publishing a record: if the record is not valid, it can't be published. ### For developers When you work with complex structured or semi-structured data structures often you need to write frontend code that deals with all the possible combinations of existing/non-existing code or more in general you need to double check if content matches certain rules. You end up with code that is much more complex than necessary, with lots of if-statements to protect you from unfinished content and parse and validate other parts to be sure you are getting what you need. With DatoCMS you can simplify your code and be more productive. **By enforcing the right validations you'll always get the data that you need, in the format that you expect.** Remember that **validations are normally enforced on every version of the record, even on saving a draft**. This means that if you won't be able to save a record that is not satisfying all the validations. So be careful adding only what you really need. On each model, you can enable the "**Allow saving invalid drafts?" flag to postpone the enforcement of validations when publishing records. In this case, invalid records can be saved as drafts if the "draft/published" system is enabled.** On the code side, using validations ensures that records are always published with the expected structure and format. ### Field validations Let's see together all the validations available on DatoCMS for each field. #### Single line text - *Required*: field must be present - *Unique*: every record of the same model must have different content - *Limit character count*: you can specify the number of characters in different ways, i.e. at least 10, between 10 and 20, no more than 20, exactly 20 - *Match a specific pattern*: text must be a valid URL, email address or match a specified regular expression - *Accept only specified values*: you can specify a list of values. **If you do that, the field will display as a dropdown for the editor** #### Multiple-paragraph text - *Required*: field must be present - *Limit character count*: you can specify the number of characters in different ways, e.g. at least 10, between 10 and 20, no more than 20, exactly 20 - *Match a specific pattern*: text must be a valid URL, email address or match a specified regular expression #### Modular content field - *Accept only a specified number of records*: you can specify the number of records part of the modular content in different ways, e.g. at least 10, between 10 and 20, no more than 20, exactly 20. Moreover you can specify if the number of records must be multiple of a number #### Single asset field - *Required*: field must be present - *Accept only specified file size*: enforce a certain asset size in different ways, e.g. between 500KB and 1MB, no more than 10MB, at least 1MB - *Accept only specified extensions*: allow only images, videos, documents or custom file extensions - *Accept only specified image dimensions*: enforce dimensions for image assets, e.g. between 500x500px and 1000x1000px or no more than 2000x2000px or at least 500x500px - *Require alt and/or title*: you can enforce presence of alt and/or title fields #### Asset gallery field - *Accept only a specified number of records*: you can specify the number of records part of the asset gallery in different ways, e.g. at least 10, between 10 and 20, no more than 20, exactly 20. Moreover you can specify if the number of records must be multiple of a number - *Accept only specified file size*: enforce a certain asset size in different ways, e.g. between 500KB and 1MB, no more than 10MB, at least 1MB - *Accept only specified extensions*: allow only images, videos, documents or custom file extensions - *Accept only specified image dimensions*: enforce dimensions for image assets, e.g. between 500x500px and 1000x1000px or no more than 2000x2000px or at least 500x500px - *Require alt and/or title*: you can enforce presence of alt and/or title fields #### External video field - *Required*: field must be present #### Date field - *Required*: field must be present - *Accept only specified date range*: the specified date must be in a specified range, e.g. at least 30 March 2020, no more than 21 March 2020, between 21 and 30 March 2020 #### DateTime field - *Required*: field must be present - *Accept only specified date range*: the specified date must be in a specified range, e.g. at least 30 March 2020 12:00, no more than 21 March 2020 18:00, between 21 12:00 and 30 March 2020 18:00 #### Integer number field - *Required*: field must be present - *Range*: number must be within specified range, e.g. between 1 and 10, at least 5, no more than 10 #### Boolean field No validations available #### Geolocation field - *Required*: field must be present #### Color field - *Required*: field must be present #### Slug field - *Reference field*: pick a field from which the slug is automatically pre-filled - *Required*: field must be present - *Unique*: every record of the same model must have different content - *Limit character count*: you can specify the number of characters in different ways, i.e. at least 10, between 10 and 20, no more than 20, exactly 20 #### SEO meta tags field - *Required*: field must be present - *Accept only specified file size*: enforce a certain asset size in different ways, e.g. between 500KB and 1MB, no more than 10MB, at least 1MB - *Accept only specified image dimensions*: enforce dimensions for image assets, e.g. between 500x500px and 1000x1000px or no more than 2000x2000px or at least 500x500px #### Single link field - *Accept only specified model*: pick one or more models from which you are allowed to pick links - *Required*: field must be present - *Unique*: every record of the same model must have different content #### Multiple links field - *Accept only specified model*: pick one or more models from which you are allowed to pick links - *Accept only a specified number of records*: you can specify the number of links in different ways, e.g. at least 10, between 10 and 20, no more than 20, exactly 20. Moreover you can specify if the number of records must be multiple of a number #### JSON field - *Required*: field must be present --- # Content modelling — Data consistency: key concepts and implications Source [docs]: https://www.datocms.com/docs/content-modelling/data-migration.md In DatoCMS, you are free to edit your project schema at any time. While this is great news for you, it also complicates the situation quite a bit on our part! Suppose you have an *Article* model, and you already have a number of articles stored. What happens to these existing articles in one of the following situations? - You add a new mandatory field. - You transform a non-localized field into a localized one (or vice versa). - You add a new locale in your project settings. Well, the existing articles (including those already published) suddenly become invalid: the data they contain does not comply with the new schema. In this section, we will try to explore together how DatoCMS manages these and other similar cases. To avoid simply having an endless list of unclear rules, we will start by explaining the mental model that underlies these rules, so that hopefully they will become more intuitive. ### How DatoCMS internally stores your content: a mental model This is a simplified version of the mental model to keep in mind when working with DatoCMS: (Image content) The record's meta-information, like creation date, publication date, record creator, etc.. is stored directly at the record level. The record also contains all the details about its location in the collection, whether it's for [simple](/docs/content-modelling/record-ordering.md) or [tree-like sorting](/docs/content-modelling/hierarchical-sorting.md). However, the actual value of the record's fields are versioned, allowing the history of the record's changes over time to be tracked.You can think of these versions as being in a separate table, connected to the associated record. In addition to field values, every version also keeps track of the editor who made the changes, and whether the data is valid or not, based on the compliance with the model's latest field-level validation rules. ##### Current and published versions Out of all the historical record versions, two are particularly important: the **current version** and the **published version**: - The current version represents the **latest available version**: every time a record is updated, a new version is generated and marked as the new current version. - The published version represents the version **currently marked as published**. It might coincide with the current version, or it might not. It might also not exist at all! ##### The status of a record The status of a record precisely represents the relationship between its current and published versions: - Record is **in draft**: only has the current version, and no published version; - Record is **published**: current version and published version coincide; - Record is **updated**: record has both current and published versions, but they differ. ### How our APIs expose this data structure All our APIs have been designed to be pragmatic and simplify the lives of developers by hiding some of this complexity. How? When you're pulling data about records through an API, you have the option to specify whether you're referring to the current version or the published version of your records (if you're not actively doing this, a default is implicitly applied): - With the [Content Delivery API](/docs/content-delivery-api.md) and the [Realtime Updates API](/docs/real-time-updates-api.md), the default is to consider the published versions, but you can request to consider the current versions with the header [`X-Include-Drafts: true`](/docs/content-delivery-api/api-endpoints.md#preview-mode-to-retrieve-draft-contenthttps://www.datocms.com/docs/content-delivery-api/api-endpoints#preview-mode-to-retrieve-draft-content). - With the [Content Management API](/docs/content-management-api.md), you can request to consider the published version or the current version with the parameter [`?version=current`](/docs/content-management-api/resources/item/instances.md) or [`?version=published`](/docs/content-management-api/resources/item/instances.md). With this information at hand, all APIs can now represent a record as a single entity, encompassing both the meta-information present at the record level, and the model fields data that is present at the version level. This greatly simplifies the logic of 99% of web projects that interface with DatoCMS, which can therefore work considering a single entity instead of two. What if a specific record does not have a published version, and the APIs are requested to refer to the published versions? Then that record simply won't be retrieved, as if it doesn't exist — which is exactly how one would normally want to handle this type of case on the app side. > [!POSITIVE] With CMA, you can also access all other past versions > We've optimized our system to mainly work with the current and published versions of a record, as these are typically the ones of interest. However, our Content Management API can also [return the full version history of a record](/docs/content-management-api/resources/item-version/instances.md) if needed! ### Data consistency rules guaranteed by the system DatoCMS maintains two important guarantees: - The structure of the data contained in any version of a record (even past versions) is guaranteed to be consistent with the settings of its model and fields. - The validity of a current/published version always reflects the current validation rules. ### Consequences on the published and current version of a record It is crucial to understand a significant outcome of these guarantees and data setup: there are cases where **the published version can change without a specific "publish" action** on the record, and **the current version can be modified without a distinct "update" action:** - Changes in the sort order of a record in the collection are immediately reflected online: it is not possible to keep these changes "in draft" because they are information that live directly at the record level. When the position is changed, the "published" version will also display the updated information. The same applies to other meta-information: creator, creation/publication dates, etc. - There are situations where a change to a record/asset can have repercussions on the published and current versions of other records that reference them: - Imagine a record whose current or published version references an asset in the Media Area, and the field that contains it has validations (i.e., "the asset must be an image"). If the asset is subsequently modified, replacing the asset with a new file, the new file could potentially alter the validity status of the current or published version, which is therefore updated. - Imagine a record whose current or published version references another record via a Single Link, Multiple Links, or Structured Text field: - If the field has the setting "When deletion is requested for a record referenced by this field" set to "Try to remove the reference to the deleted record", then the system must respect this setting, altering the current and/or published version. - Similarly, if the field has the setting "When unpublishing is requested for a record referenced by this field" set to "Try to remove the reference to the unpublished record", then the system must respect this setting, altering the published version. - Changing the schema of a model, or the locales of a DatoCMS project can also cause an automatic update of multiple versions because: - When a new field is added/removed to the model, this field will be immediately added/eliminated in all record versions of that model (including the published and current version). - If a field that can hold a reference to another record (Single Link, Multiple Links, Structured Text) is altered by removing a model from the list of linkable models, then all record versions of that model will be updated by eliminating any references to those models. - If a model is deleted, but there are records of that model which are referenced by other records, then all these record versions are updated by eliminating any references to the deleted model. - The same principle applies to model fields that can hold blocks (Modular Content, Structured Text). If these are altered by removing a block type from the list of embeddable options, then all record versions of that model will be adjusted by eliminating any blocks of that type. - If a model is modified, enabling the *"All locales required?"* setting, then all previously unspecified locales will be added to all record versions of that model. - If a field is modified from localized to non-localized (or vice versa), then all record versions of that model will be modified to reflect this change. - If you add a new validation rule to a field, then all existing record versions of that model will be re-checked against the new validation rules, and potentially marked as invalid. - If a locale is added/removed from the project, all record versions of all models that contain localized fields will be adjusted accordingly. ### Consequences in Webhooks Webhooks allow you to be notified of changes to the records in your project. Based on the considerations made so far, it is important to make a few clarifications here: - The **"Record creation"** event is triggered when a record is generated for the first time (and consequently its current version). - The **"Record update"** event is triggered when the current version changes (due to an explicit modification of the record, or for some of the reasons listed above). - The **"Record publish"** event is triggered when the published version of a record changes (due to an explicit publication of the record, or for some of the reasons listed above). - In the webhook payload, the `meta.status` field of the record entity always reflects the relationship between the current and published versions of the item itself at the moment the webhook is triggered. As a consequence: - You can still get "Record publish"/"Record update" events without an explicit new publish/update request from an editor or an API call. This occurs when the system automatically needs to adjusts an existing published/current version to keep it consistent with the new schema change. - When these automatic adjustments occur, it is completely normal for the `meta.status` of a record in the webhook payload of a "Record Publish" event to be "updated" instead of "published". This is because during the process, a record might be in an "updated" state, and the operation does not change this condition. --- # DatoCMS APIs at a glance — Overview of DatoCMS APIs Source [docs]: https://www.datocms.com/docs/overview/overview-of-datocms-apis.md DatoCMS offers several different APIs, each optimized for a particular use case. ## TLDR DatoCMS provides you 4 APIs to build with, each one documented in detail over the following links: - [GraphQL Content Delivery API](/docs/content-delivery-api.md) to read published content from any frontend via a fast, cached GraphQL endpoint, - [REST Content Management API](/docs/content-management-api.md) to create, update, and publish records programmatically through a typed client, - An [Asset API](/docs/asset-api/images.md) to upload, transform, and serve images and videos from a global CDN with inbuilt optimization settings and options, and - An [SSE Real-time Updates API](/docs/real-time-updates-api.md) to stream live content changes to power instant previews and live published views. ## Fetching & Serving Content for your Frontend - **Start here:** Our [**Content** **Delivery** **API**](/docs/content-delivery-api.md) (CDA) is our recommended way to connect DatoCMS to your frontend. It lets you retrieve only the records and fields you need, using a simple query language called [GraphQL](https://graphql.org/). This is a fast and safe read-only API that makes it easy to use our headless system with any frontend framework. - Our [**Site Search API**](/docs/site-search.md)lets you easily add full-text search to your website. - Our[**Real-Time Updates API**](/docs/real-time-updates-api.md) allows you to push live updates to your visitors for real-time blogging or other live events. It is also highly beneficial for previewing draft content to your editors as they compose. ## Serving Images & Videos - Our [**Images API**](/docs/asset-api/images.md)serves your images through a CDN and enables powerful URL-based transformations ([cropping, resizing, format conversion, and more](https://docs.imgix.com/apis/rendering/overview)). We partner with Imgix for this system. - Our [**Videos API**](/docs/asset-api/videos.md) uses the Mux video CDN to [ensure efficient video streaming](/docs/streaming-videos/how-to-stream-videos-efficiently.md) for users with different devices and connection speeds. ## Editing & Managing Your Data Our [**Content Management API**](/docs/content-management-api.md) (CMA) is a traditional REST API that lets your developers create, edit, export, and import your data and schema. This is also the API that lets you manage other aspects of your account and projects, such as roles & permissions, environments, collaborators, and more. ## Extending DatoCMS The [**DatoCMS Plugins SDK**](/docs/plugin-sdk/introduction.md) (and associated API methods) let your developers customize the DatoCMS UI itself, extending functionality for your editors by easily integrating third-party services or adding special logic for your specific business needs. See [DatoCMS Community Plugins](https://www.datocms.com/marketplace/plugins.md) for some examples, often open-source, built by our wonderful community. --- # DatoCMS APIs at a glance — DatoCMS Domains and Content Security Policy (CSP) Source [docs]: https://www.datocms.com/docs/overview/datocms-domains-and-content-security-policy-csp.md **Last updated: 2026-01-12** If you're trying to whitelist our domain names for the purposes of browser [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) or similar needs, this is a list of the domains used by our services. ## For API requests: - [`graphql.datocms.com`](http://graphql.datocms.com/) (Content Delivery API, GraphQL) - [`graphql-listen.datocms.com`](http://graphql-listen.datocms.com/) (Real-time Updates API for live previews via SSE) - [`site-api.datocms.com`](http://site-api.datocms.com/) (Content Management API, REST) ## For images and assets: - [`www.datocms-assets.com`](http://www.datocms-assets.com/) (primary CDN for all assets like images, PDFs, raw files) - [`datocms-assets.6c36efb897e5eae1d2a887cfa632eea9.eu.r2.cloudflarestorage.com`](https://datocms-assets.6c36efb897e5eae1d2a887cfa632eea9.eu.r2.cloudflarestorage.com/) (for uploading assets to your project) ## For HLS video streaming: - [`stream.mux.com`](http://stream.mux.com/) (video streaming via HLS and MP4 delivery) - [`image.mux.com`](http://image.mux.com/) (video thumbnails and metadata) ## Other - If you’re embedding the DatoCMS admin interface or using plugins: `*.admin.datocms.com` (the CMS editor interface). - Your plugin is likely hosted elsewhere, outside of DatoCMS altogether, like a Vercel or Netlify site. - If you’re on an Enterprise plan with a custom asset domain, you’d replace [`www.datocms-assets.com`](http://www.datocms-assets.com/) with your custom domain. The same applies if you use a custom CMS admin domain. ## For humans only These sites are unlikely to be useful to APIs, but you may wish to whitelist them for your human users. - Our forum at [`https://community.datocms.com`](https://community.datocms.com/) is helpful for troubleshooting - Your account dashboard is at [`https://dashboard.datocms.com`](https://dashboard.datocms.com/) --- # Content Delivery API — Content Delivery API Overview Source [docs]: https://www.datocms.com/docs/content-delivery-api.md This section offers a detailed reference to DatoCMS's Content Delivery API. The Content Delivery API is used to retrieve content from one of your DatoCMS projects and deliver it to your web or mobile projects. Our APIs serve content via a powerful and robust content delivery network (CDN). Multiple data centers around the world store a cached copy of your content. When a page request is made, the content is delivered to the user from the nearest server. This greatly accelerates content delivery and reduces latency. > [!NOTE] Content Delivery vs Content Management API > If you need to deliver content to your public-facing web or mobile projects, this is the API to use, while if you want to programmatically create or update your schema/content, please refer to the [Content Management API](/docs/content-management-api.md)! ### Why GraphQL? The Content Delivery API is written in GraphQL, which offers a number of advantages over classic REST APIs: #### Strongly typed schema Many developers have found themselves in situations where they needed to work with deprecated API documentation, lacking proper ways of knowing what operations are supported by an API and how to use them. GraphQL clearly defines the operations supported by the API, including input arguments and possible responses, offering an unfailing contract that specifies the capabilities of an API. #### No more over-fetching and under-fetching Developers often describe the major benefit of GraphQL as the fact that clients can retrieve exactly the data they need from the API. They don’t have to rely on REST endpoints that return predefined and fixed data structures. Instead, the client can dictate the shape of the response objects returned by the API. #### Fewer roundtrips One of the major issues of REST is that, in order to get the data you need, you are forced to call a number of different endpoints. Each API request to pull a resource is a separate HTTP request-response cycle. Fetching complicated data requires multiple round-trips between the client and server to render even a single view. On the contrary, GraphQL enables you to call several related functions without multiple round-trips. > [!PROTIP] Pro tip: DatoCMS, powered by DatoCMS > Of course, we drink our own champagne - our website is built on DatoCMS. > > Want a peek behind the curtain? The actual source code is available in this [public GitHub repo](https://github.com/datocms/astro-website) for you to explore and see how we built it. ### Want to get started with DatoCMS? If you are new to DatoCMS and you want to learn the basics, check these video tutorials for beginners! [ (Image content) Next.js + DatoCMS tutorial for beginners Play video » ](https://www.youtube.com/watch?v=_VIF1if-dNA) [ (Image content) Build a dynamic landing page with Next.js and Tailwind CSS Play video » ](https://www.youtube.com/watch?v=it5nNneptgM) [ (Image content) Creating a Landing Page using the Atomic Design System Play video » ](https://www.youtube.com/watch?v=rajqgvg2e0w) --- # Content Delivery API — Using the JavaScript CDA client Source [docs]: https://www.datocms.com/docs/content-delivery-api/your-first-request.md The DatoCMS Content Delivery API is a single GraphQL endpoint: ```plaintext https://graphql.datocms.com/ ``` The endpoint stays constant no matter what operation you perform, and it's read-only — that is, it does not offer any *mutation operation*. You can use our [Content Management API](/docs/content-management-api.md) for that. Unlike REST, the HTTP verb does not vary by operation: every request — whether you’re querying or fetching with variables — is a `POST` to that URL, with a JSON-encoded body. ### Making a raw HTTP request You can talk to the API from anything that speaks HTTP. Here's the same query sent with `curl` and with the native Fetch API: cURL Terminal window ```bash $ curl 'https://graphql.datocms.com/' \ -H 'Authorization: Bearer YOUR-API-TOKEN' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ --data-binary '{ "query": "{ allPosts { title } }" }' ``` Vanilla JS (Fetch API) ```javascript const response = await fetch('https://graphql.datocms.com/', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Authorization': `Bearer ${process.env.DATOCMS_READONLY_TOKEN}`, }, body: JSON.stringify({ query: '{ allPosts { title } }', }), }); const { data } = await response.json(); console.log(data); ``` This works, but you'll quickly need to layer extra concerns on top: rate-limit retries, draft/preview mode, environment targeting, cache tags, pagination beyond the 500-record limit, and TypeScript types. That's exactly what our official client takes care of. ### Using the `@datocms/cda-client` package `@datocms/cda-client` is a lightweight, TypeScript-first package that wraps the native Fetch API with helpers tailored for the Content Delivery API. It's the recommended way to query DatoCMS from any JavaScript or TypeScript runtime — Node.js, browsers, edge runtimes, Deno, Bun. It offers a number of benefits over making raw requests yourself: - **The package is written in TypeScript**, with full support for `TypedDocumentNode` so that — paired with [gql.tada](https://gql-tada.0no.co/) or [GraphQL Code Generator](https://the-guild.dev/graphql/codegen) — you get end-to-end type inference on every query result and variable; - All the [API headers](/docs/content-delivery-api/api-endpoints.md) that control environments, draft mode, strict mode, cache tags and Content Link are exposed as **plain options on the client**, no manual header juggling required; - API rate-limit retries are managed for you automatically, and a dedicated helper [bypasses the API's 500-record per-query limit](/docs/content-delivery-api/pagination.md) transparently. ###### Installation Terminal window ```bash npm install @datocms/cda-client ``` The package has zero runtime dependencies and works in any environment that ships a native Fetch API (Node.js ≥ 18, modern browsers, Cloudflare Workers, Vercel Edge Functions, Deno, Bun, etc.). ###### Executing a query The main entry point is `executeQuery`. It accepts a GraphQL query (as a string, `DocumentNode`, or `TypedDocumentNode`) and an options object, and returns a Promise that resolves with the query result: ```typescript import { executeQuery } from '@datocms/cda-client'; const result = await executeQuery('{ allPosts { title } }', { token: process.env.DATOCMS_READONLY_TOKEN, }); console.log(result); ``` You can pass GraphQL variables under the `variables` option: ```typescript const result = await executeQuery( `query PostsByCategory($category: String!) { allPosts(filter: { category: { eq: $category } }) { title } }`, { token: process.env.DATOCMS_READONLY_TOKEN, variables: { category: 'news' }, }, ); ``` ### TypeScript and end-to-end type safety `executeQuery` supports `TypedDocumentNode`, so the type of the response is inferred directly from your query. Combined with a code generator, you get autocomplete and compile-time checks on every field: ```typescript import { executeQuery } from '@datocms/cda-client'; import { AllArticlesQuery } from './generated/graphql'; const result = await executeQuery(AllArticlesQuery, { token: process.env.DATOCMS_READONLY_TOKEN, variables: { limit: 10 }, }); // `result.allArticles` is fully typed result.allArticles.forEach((article) => console.log(article.title)); ``` ### Error management If a request fails — either because of a non-2xx HTTP status, or because the GraphQL response contains an `errors` array — the client throws an `ApiError` exception containing all the details of the request and the response: ```typescript import { executeQuery, ApiError } from '@datocms/cda-client'; try { const result = await executeQuery('{ allPosts { title } }', { token: process.env.DATOCMS_READONLY_TOKEN, }); console.log(result); } catch (e) { if (e instanceof ApiError) { // Information about the failed request console.log(e.query); console.log(e.options); // Information about the response console.log(e.response.status); console.log(e.response.statusText); console.log(e.response.headers); console.log(e.response.body); } else { throw e; } } ``` You can learn more about the package and explore its full API surface — including `rawExecuteQuery`, `buildRequestHeaders` and `buildRequestInit` for framework integrations — on the [`@datocms/cda-client` README](https://github.com/datocms/cda-client). --- # Content Delivery API — Authentication and permissions Source [docs]: https://www.datocms.com/docs/content-delivery-api/authentication.md The Content Delivery API uses API Tokens for authentication: @datocms/cda-client ```typescript import { executeQuery } from '@datocms/cda-client'; const result = await executeQuery(query, { token: process.env.DATOCMS_READONLY_TOKEN, }); ``` Raw HTTP header ```plaintext Authorization: Bearer ``` You can find your read-only API token in the *Settings \> API tokens* section of your administrative area, or generate a new token with more specific permissions: (Video content) Regardless of which API token you use, make sure that the "Access the Content Delivery API" or "Access the Content Delivery API in Preview Mode" flags are enabled, otherwise the API token will not be able to make calls to the CDA. #### Restricting access If you want to restrict GraphQL access only to a selection of your models, you can generate a custom API token and assign it a custom [role](/docs/general-concepts/roles-and-permission-system.md). (Video content) If an API token can only access specific models, any other field **will be completely hidden from the GraphQL schema and response**, eliminating any potential information exposure. > [!WARNING] Different behavior on legacy projects > On projects created before January 8, 2024 — and that have not explicitly activated the "Improved GraphQL Security" update — the behavior will be slightly different: you can read all the details in the related [product update](https://www.datocms.com/product-updates/improved-gql-visibility-control.md). --- # Content Delivery API — Configuring requests: envs, drafts, strict mode, cache tags, etc. Source [docs]: https://www.datocms.com/docs/content-delivery-api/api-endpoints.md Each request to the GraphQL endpoint can carry **headers** that control behavior: target a specific environment, opt into draft content, narrow down GraphQL types, retrieve cache tags, and embed visual-editing metadata. Below, each section shows the raw HTTP header alongside the equivalent option on [`@datocms/cda-client`](/docs/content-delivery-api/your-first-request.md), so you can pick whichever style fits your setup. ### Specifying an environment If no environment is specified, the [primary environment](/docs/general-concepts/primary-and-sandbox-environments.md) is used. To explicitly read from a different one: @datocms/cda-client ```typescript import { executeQuery } from '@datocms/cda-client'; const result = await executeQuery(query, { token: process.env.DATOCMS_READONLY_TOKEN, environment: 'my-sandbox-environment', }); ``` Raw HTTP header ```plaintext X-Environment: ``` ### Preview mode to retrieve draft content If you have the [Draft/Published system](/docs/general-concepts/draft-published.md) active on some of your models, you can request the latest draft version of each record instead of the currently published one — useful for staging environments and local development: @datocms/cda-client ```typescript const result = await executeQuery(query, { token: process.env.DATOCMS_PREVIEW_TOKEN, includeDrafts: true, }); ``` Raw HTTP header ```plaintext X-Include-Drafts: true ``` ### Strict mode for non-nullable GraphQL types If you want to make sure that no invalid record is ever returned without having to manually add an `_isValid` filter to every query, you can opt into strict mode: @datocms/cda-client ```typescript const result = await executeQuery(query, { token: process.env.DATOCMS_READONLY_TOKEN, excludeInvalid: true, }); ``` Raw HTTP header ```plaintext X-Exclude-Invalid: true ``` In contrast to the `_isValid` filter, this header also has the effect of **narrowing down GraphQL types**: - Every field with a "Required" validation enforced will be associated with a non-nullable GraphQL type (e.g. `String` becomes `String!`) - Asset fields (both single and multiple) that have a "Image transformable by imgix" format validation will have the following properties associated with a non-nullable type: `focalPoint`, `width`, `height`, `responsiveImage` - Asset fields (both single and multiple) that have a "Video" format validation will have the following property associated with a non-nullable type: `video` - Asset fields (both single and multiple) that have a required alt and/or title validation will have the `alt` and/or `title` properties marked as non-null You can read a little bit more about Strict Mode in our [announcement blog post](https://www.datocms.com/blog/introducing-strict-mode-for-graphql-cda-get-the-best-typescript-dx.md). ### Cache tags To receive the [Cache Tags](/docs/content-delivery-api/cache-tags.md) associated with your query, opt into the dedicated header. Cache tags travel back in the `X-Cache-Tags` response header, so on the client side you'll need access to the underlying `Response` — `rawExecuteQuery` returns it alongside the parsed result: @datocms/cda-client ```typescript import { rawExecuteQuery } from '@datocms/cda-client'; const [result, response] = await rawExecuteQuery(query, { token: process.env.DATOCMS_READONLY_TOKEN, returnCacheTags: true, }); const cacheTags = response.headers.get('x-cache-tags'); ``` Raw HTTP header ```plaintext X-Cache-Tags: true ``` ### Content Link If you have [Content Link](/docs/general-concepts/visual-editing.md) available on your project, two extra headers tell the CDA to embed the metadata that powers visual editing on websites hosted on Vercel: @datocms/cda-client ```typescript const result = await executeQuery(query, { token: process.env.DATOCMS_READONLY_TOKEN, contentLink: 'v1', baseEditingUrl: 'https://your-project.admin.datocms.com', }); ``` Raw HTTP headers ```plaintext X-Visual-Editing: v1 X-Base-Editing-Url: https://.admin.datocms.com ``` `X-Base-Editing-Url` (and the equivalent `baseEditingUrl` option) can also be used in isolation: it enables the usage of the `_editingUrl` field in the GraphQL API. --- # Content Delivery API — How to fetch records Source [docs]: https://www.datocms.com/docs/content-delivery-api/how-to-fetch-records.md ### Query a single record For every model there is one query to fetch a specific record. For example if you want to get the `hero_title` field from the single-instance model called `homepage`, the following request can be used: ```graphql query { homepage { heroTitle } } ``` The query response can be further controlled by supplying `filter` and `orderBy` arguments. For example, if the `artist` model has a `name` field, you can use this query to get a specific record: ```graphql query { artist(filter: { name: { eq: "Blank Banshee" } }) { name genre } } ``` Please refer to the [filtering section](/docs/content-delivery-api/filtering-records.md) of this guide to understand how to use the `filters` and `orderBy` arguments. ### Query multiple records The API contains automatically generated queries to fetch records of a certain model. For example, for the `artist` model the top-level query `allArtists` will be generated. By default the query will return 20 records, you can change the limit by adding the `first` parameter. If the number of your records exceeds the maximum number of records we return, you will need to iterate. Read more in the [pagination section](/docs/content-delivery-api/pagination.md). A few examples for query names: - Model API identifier: `artist`, query name: `allArtists` - Model API identifier: `track`, query name: `allTracks` - Model API identifier: `use_case`, query name: `allUseCases` A query which fetches the first ten records from the `artist` model — together with the total number of artists — could look like the following: ```graphql query { allArtists(first: 10) { id name } _allArtistsMeta { count } } ``` Note: The query name approximates the plural rules of the English language. If you are unsure about the actual query name, explore available queries in your CDA Playground. The query response of a query fetching multiple records can be further controlled by supplying different query arguments to order, filter and paginate results. --- # Content Delivery API — Filtering records Source [docs]: https://www.datocms.com/docs/content-delivery-api/filtering-records.md You can supply different parameters to the `filter` argument to filter the query response accordingly. The available options depend on the fields defined on the model in question. If you supply exactly one parameter to the filter argument, the query response will only contain records that fulfill this constraint: ```graphql query { allArtists( filter: { published: { eq: false } } ) { id name published } } ``` Depending on the type of the field you want to filter by, you have access to different advanced criteria you can use to filter your query response: ```graphql query { allArtists( filter: { name: { in: [ "Blank Banshee", "Gazelle Twin" ] } } ) { id name genre } } ``` If you specify multiple conditions, they will be combined as if it was a logical AND expression: ```graphql query { allAlbums( filter: { { artist: { eq: "212" } }, { releaseDate: { gt: "2016-01-01" } } } ) { id slug artist { name } coverImage { url } } } ``` There are times where it can be more convenient to use an AND expression explicitly, for example when you need to use the same type of filter more than once: ```graphql query { allArtists( filter: { AND: [ { name: { matches: { pattern: "Blank" } } }, { name: { matches: { pattern: "Banshee" } } } ] } ) { id name genre } } ``` It is also possible to combine AND-like and OR logical expressions. For example, the following query will return all the point of interest located in New York that either have a rating greater than 4 or are a restaurant: ```graphql query { allPois( filter: { address: { matches: { pattern: "new york" } }, OR: [ { rating: { gt: 4 } }, { name: { matches: { pattern: "restaurant" } } }, ] } ) { name address rating } } ``` > [!WARNING] Structured Text and Deep Filtering > If a Structured Text field has the [deep filtering](/docs/content-delivery-api/deep-filtering.md) option enabled, its filters will slightly differ from the ones described in this page. You learn more in the next section of the doc regarding [deep filtering](/docs/content-delivery-api/deep-filtering.md). ## Filters available for field types #### Boolean fields `eq` Search for records with an exact match ```graphql query { allProducts(filter: { booleanField: { eq: true } }) { title } } ``` #### Color fields `exists` Filter records with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { colorField: { exists: true } }) { title } } ``` #### Date fields `gt` Filter records with a value that's strictly greater than the one specified ```graphql query { allProducts(filter: { dateField: { gt: "2018-02-13" } }) { title } } ``` `lt` Filter records with a value that's less than the one specified ```graphql query { allProducts(filter: { dateField: { lt: "2018-02-13" } }) { title } } ``` `gte` Filter records with a value that's greater than or equal to the one specified ```graphql query { allProducts(filter: { dateField: { gte: "2018-02-13" } }) { title } } ``` `lte` Filter records with a value that's less or equal than the one specified ```graphql query { allProducts(filter: { dateField: { lte: "2018-02-13" } }) { title } } ``` `exists` Filter records with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { dateField: { exists: true } }) { title } } ``` `eq` Search for records with an exact match ```graphql query { allProducts(filter: { dateField: { eq: "2018-02-13" } }) { title } } ``` `neq` Exclude records with an exact match ```graphql query { allProducts(filter: { dateField: { neq: "2018-02-13" } }) { title } } ``` #### DateTime fields `gt` Filter records with a value that's strictly greater than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { dateTimeField: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" gt: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `lt` Filter records with a value that's less than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { dateTimeField: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" lt: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `gte` Filter records with a value that's greater than or equal to than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { dateTimeField: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" gte: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `lte` Filter records with a value that's less or equal than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { dateTimeField: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" lte: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `eq` Filter records with a value that's within the specified minute range. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { dateTimeField: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" eq: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `neq` Filter records with a value that's outside the specified minute range. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { dateTimeField: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" neq: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `exists` Filter records with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { dateTimeField: { exists: true } }) { title } } ``` #### Single file fields `eq` Search for records with an exact match. The specified value must be an Upload ID ```graphql query { allProducts(filter: { fileField: { eq: "123" } }) { title } } ``` `neq` Exclude records with an exact match. The specified value must be an Upload ID ```graphql query { allProducts(filter: { fileField: { neq: "123" } }) { title } } ``` `in` Filter records that have one of the specified uploads ```graphql query { allProducts(filter: { fileField: { in: ["123"] } }) { title } } ``` `not_in` Filter records that do not have one of the specified uploads ```graphql query { allProducts(filter: { fileField: { notIn: ["123"] } }) { title } } ``` `exists` Filter records with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { fileField: { exists: true } }) { title } } ``` #### Floating-point number fields `gt` Filter records with a value that's strictly greater than the one specified ```graphql query { allProducts(filter: { floatField: { gt: 19.99 } }) { title } } ``` `lt` Filter records with a value that's less than the one specified ```graphql query { allProducts(filter: { floatField: { lt: 19.99 } }) { title } } ``` `gte` Filter records with a value that's greater than or equal to the one specified ```graphql query { allProducts(filter: { floatField: { gte: 19.99 } }) { title } } ``` `lte` Filter records with a value that's less or equal than the one specified ```graphql query { allProducts(filter: { floatField: { lte: 19.99 } }) { title } } ``` `exists` Filter records with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { floatField: { exists: true } }) { title } } ``` `eq` Search for records with an exact match ```graphql query { allProducts(filter: { floatField: { eq: 19.99 } }) { title } } ``` `neq` Exclude records with an exact match ```graphql query { allProducts(filter: { floatField: { neq: 19.99 } }) { title } } ``` #### Multiple files fields `eq` Search for records with an exact match. The specified values must be Upload IDs ```graphql query { allProducts(filter: { galleryField: { eq: ["123"] } }) { title } } ``` `all_in` Filter records that have all of the specified uploads. The specified values must be Upload IDs ```graphql query { allProducts(filter: { galleryField: { allIn: ["123"] } }) { title } } ``` `any_in` Filter records that have one of the specified uploads. The specified values must be Upload IDs ```graphql query { allProducts(filter: { galleryField: { anyIn: ["123"] } }) { title } } ``` `not_in` Filter records that do not have any of the specified uploads. The specified values must be Upload IDs ```graphql query { allProducts(filter: { galleryField: { notIn: ["123"] } }) { title } } ``` `exists` Filter records with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { galleryField: { exists: true } }) { title } } ``` #### Integer number fields `gt` Filter records with a value that's strictly greater than the one specified ```graphql query { allProducts(filter: { integerField: { gt: 3 } }) { title } } ``` `lt` Filter records with a value that's less than the one specified ```graphql query { allProducts(filter: { integerField: { lt: 3 } }) { title } } ``` `gte` Filter records with a value that's greater than or equal to the one specified ```graphql query { allProducts(filter: { integerField: { gte: 3 } }) { title } } ``` `lte` Filter records with a value that's less or equal than the one specified ```graphql query { allProducts(filter: { integerField: { lte: 3 } }) { title } } ``` `exists` Filter records with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { integerField: { exists: true } }) { title } } ``` `eq` Search for records with an exact match ```graphql query { allProducts(filter: { integerField: { eq: 3 } }) { title } } ``` `neq` Exclude records with an exact match ```graphql query { allProducts(filter: { integerField: { neq: 3 } }) { title } } ``` #### JSON fields `exists` Filter records with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { jsonField: { exists: true } }) { title } } ``` #### Geolocation fields `near` Filter records within the specified radius in meters ```graphql query { allProducts( filter: { latLonField: { near: { latitude: 40.73, longitude: -73.93, radius: 10 } } } ) { title } } ``` `exists` Filter records with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { latLonField: { exists: true } }) { title } } ``` #### Single link fields `eq` Search for records with an exact match. The specified value must be a Record ID ```graphql query { allProducts(filter: { linkField: { eq: "123" } }) { title } } ``` `neq` Exclude records with an exact match. The specified value must be a Record ID ```graphql query { allProducts(filter: { linkField: { neq: "123" } }) { title } } ``` `in` Filter records linked to one of the specified records ```graphql query { allProducts(filter: { linkField: { in: ["123"] } }) { title } } ``` `not_in` Filter records not linked to one of the specified records ```graphql query { allProducts(filter: { linkField: { notIn: ["123"] } }) { title } } ``` `exists` Filter records with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { linkField: { exists: true } }) { title } } ``` #### Multiple links fields `eq` Search for records with an exact match. The specified values must be Record IDs ```graphql query { allProducts(filter: { linksField: { eq: ["123"] } }) { title } } ``` `all_in` Filter records linked to all of the specified records. The specified values must be Record IDs ```graphql query { allProducts(filter: { linksField: { allIn: ["123"] } }) { title } } ``` `any_in` Filter records linked to at least one of the specified records. The specified values must be Record IDs ```graphql query { allProducts(filter: { linksField: { anyIn: ["123"] } }) { title } } ``` `not_in` Filter records not linked to any of the specified records. The specified values must be Record IDs ```graphql query { allProducts(filter: { linksField: { notIn: ["123"] } }) { title } } ``` `exists` Filter records with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { linksField: { exists: true } }) { title } } ``` #### SEO meta tags fields `exists` Filter records with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { seoField: { exists: true } }) { title } } ``` #### Slug fields `eq` Search for records with an exact match ```graphql query { allProducts(filter: { slugField: { eq: "bike" } }) { title } } ``` `neq` Exclude records with an exact match ```graphql query { allProducts(filter: { slugField: { neq: "bike" } }) { title } } ``` `in` Filter records that have one of the specified slugs ```graphql query { allProducts(filter: { slugField: { in: ["bike"] } }) { title } } ``` `not_in` Filter records that do have one of the specified slugs ```graphql query { allProducts(filter: { slugField: { notIn: ["bike"] } }) { title } } ``` #### Single-line string fields `matches` Filter records based on a regular expression ```graphql query { allProducts( filter: { stringField: { matches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` `not_matches` Exclude records based on a regular expression ```graphql query { allProducts( filter: { stringField: { notMatches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` `is_blank` Filter records with the specified field set as blank (null or empty string) ```graphql query { allProducts(filter: { stringField: { isBlank: true } }) { title } } ``` `is_present` Filter records with the specified field present (neither null, nor empty string) ```graphql query { allProducts(filter: { stringField: { isPresent: true } }) { title } } ``` `eq` Search for records with an exact match ```graphql query { allProducts(filter: { stringField: { eq: "bike" } }) { title } } ``` `neq` Exclude records with an exact match ```graphql query { allProducts(filter: { stringField: { neq: "bike" } }) { title } } ``` `in` Filter records that equal one of the specified values ```graphql query { allProducts(filter: { stringField: { in: ["bike"] } }) { title } } ``` `not_in` Filter records that do not equal one of the specified values ```graphql query { allProducts(filter: { stringField: { notIn: ["bike"] } }) { title } } ``` `exists` Filter records with the specified field defined (i.e. with any value) or not \[DEPRECATED\] ```graphql query { allProducts(filter: { stringField: { exists: true } }) { title } } ``` #### Structured text fields `matches` Filter records based on a regular expression ```graphql query { allProducts( filter: { structuredTextField: { matches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` `not_matches` Exclude records based on a regular expression ```graphql query { allProducts( filter: { structuredTextField: { notMatches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` `is_blank` Filter records with the specified field set as blank (null or single empty paragraph) ```graphql query { allProducts(filter: { structuredTextField: { isBlank: true } }) { title } } ``` `is_present` Filter records with the specified field present (neither null, nor empty string) ```graphql query { allProducts(filter: { structuredTextField: { isPresent: true } }) { title } } ``` `exists` Filter records with the specified field defined (i.e. with any value) or not \[DEPRECATED\] ```graphql query { allProducts(filter: { structuredTextField: { exists: true } }) { title } } ``` #### Multiple-paragraph text fields `matches` Filter records based on a regular expression ```graphql query { allProducts( filter: { textField: { matches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` `not_matches` Exclude records based on a regular expression ```graphql query { allProducts( filter: { textField: { notMatches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` `is_blank` Filter records with the specified field set as blank (null or empty string) ```graphql query { allProducts(filter: { textField: { isBlank: true } }) { title } } ``` `is_present` Filter records with the specified field present (neither null, nor empty string) ```graphql query { allProducts(filter: { textField: { isPresent: true } }) { title } } ``` `exists` Filter records with the specified field defined (i.e. with any value) or not \[DEPRECATED\] ```graphql query { allProducts(filter: { textField: { exists: true } }) { title } } ``` #### Video fields `exists` Filter records with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { videoField: { exists: true } }) { title } } ``` ### Filters available for meta fields #### Filter by `_createdAt` meta field `gt` Filter records with a value that's strictly greater than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _createdAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" gt: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `lt` Filter records with a value that's less than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _createdAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" lt: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `gte` Filter records with a value that's greater than or equal to than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _createdAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" gte: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `lte` Filter records with a value that's less or equal than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _createdAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" lte: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `eq` Filter records with a value that's within the specified minute range. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _createdAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" eq: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `neq` Filter records with a value that's outside the specified minute range. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _createdAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" neq: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `exists` Filter records with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { _createdAt: { exists: true } }) { title } } ``` #### Filter by `_firstPublishedAt` meta field `gt` Filter records with a value that's strictly greater than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _firstPublishedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" gt: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `lt` Filter records with a value that's less than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _firstPublishedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" lt: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `gte` Filter records with a value that's greater than or equal to than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _firstPublishedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" gte: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `lte` Filter records with a value that's less or equal than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _firstPublishedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" lte: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `eq` Filter records with a value that's within the specified minute range. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _firstPublishedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" eq: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `neq` Filter records with a value that's outside the specified minute range. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _firstPublishedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" neq: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `exists` Filter records with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { _firstPublishedAt: { exists: true } }) { title } } ``` #### Filter by `_isValid` meta field `eq` Search for records with an exact match ```graphql query { allProducts(filter: { _isValid: { eq: true } }) { title } } ``` #### Filter by `_publicationScheduledAt` meta field `gt` Filter records with a value that's strictly greater than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _publicationScheduledAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" gt: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `lt` Filter records with a value that's less than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _publicationScheduledAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" lt: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `gte` Filter records with a value that's greater than or equal to than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _publicationScheduledAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" gte: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `lte` Filter records with a value that's less or equal than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _publicationScheduledAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" lte: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `eq` Filter records with a value that's within the specified minute range. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _publicationScheduledAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" eq: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `neq` Filter records with a value that's outside the specified minute range. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _publicationScheduledAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" neq: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `exists` Filter records with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { _publicationScheduledAt: { exists: true } }) { title } } ``` #### Filter by `_publishedAt` meta field `gt` Filter records with a value that's strictly greater than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _publishedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" gt: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `lt` Filter records with a value that's less than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _publishedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" lt: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `gte` Filter records with a value that's greater than or equal to than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _publishedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" gte: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `lte` Filter records with a value that's less or equal than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _publishedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" lte: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `eq` Filter records with a value that's within the specified minute range. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _publishedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" eq: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `neq` Filter records with a value that's outside the specified minute range. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _publishedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" neq: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `exists` Filter records with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { _publishedAt: { exists: true } }) { title } } ``` #### Filter by `_status` meta field `eq` Search the record with the specified status ```graphql query { allProducts(filter: { _status: { eq: draft } }) { title } } ``` `neq` Exclude the record with the specified status ```graphql query { allProducts(filter: { _status: { neq: draft } }) { title } } ``` `in` Search records with the specified statuses ```graphql query { allProducts(filter: { _status: { in: [draft] } }) { title } } ``` `not_in` Search records without the specified statuses ```graphql query { allProducts(filter: { _status: { notIn: [draft] } }) { title } } ``` #### Filter by `_unpublishingScheduledAt` meta field `gt` Filter records with a value that's strictly greater than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _unpublishingScheduledAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" gt: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `lt` Filter records with a value that's less than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _unpublishingScheduledAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" lt: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `gte` Filter records with a value that's greater than or equal to than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _unpublishingScheduledAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" gte: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `lte` Filter records with a value that's less or equal than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _unpublishingScheduledAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" lte: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `eq` Filter records with a value that's within the specified minute range. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _unpublishingScheduledAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" eq: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `neq` Filter records with a value that's outside the specified minute range. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _unpublishingScheduledAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" neq: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `exists` Filter records with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { _unpublishingScheduledAt: { exists: true } }) { title } } ``` #### Filter by `_updatedAt` meta field `gt` Filter records with a value that's strictly greater than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _updatedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" gt: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `lt` Filter records with a value that's less than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _updatedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" lt: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `gte` Filter records with a value that's greater than or equal to than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _updatedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" gte: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `lte` Filter records with a value that's less or equal than the one specified. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _updatedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" lte: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `eq` Filter records with a value that's within the specified minute range. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _updatedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" eq: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `neq` Filter records with a value that's outside the specified minute range. Seconds and milliseconds are truncated from the argument. ```graphql query { allProducts( filter: { _updatedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" neq: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `exists` Filter records with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { _updatedAt: { exists: true } }) { title } } ``` #### Filter by `id` meta field `eq` Search the record with the specified ID ```graphql query { allProducts(filter: { id: { eq: "123" } }) { title } } ``` `neq` Exclude the record with the specified ID ```graphql query { allProducts(filter: { id: { neq: "123" } }) { title } } ``` `in` Search records with the specified IDs ```graphql query { allProducts(filter: { id: { in: ["123"] } }) { title } } ``` `not_in` Search records that do not have the specified IDs ```graphql query { allProducts(filter: { id: { notIn: ["123"] } }) { title } } ``` #### Filter by `parent` meta field `eq` Filter records children of the specified record. Value must be a Record ID ```graphql query { allProducts(filter: { parent: { eq: "123" } }) { title } } ``` `exists` Filter records with a parent record or not ```graphql query { allProducts(filter: { parent: { exists: true } }) { title } } ``` #### Filter by `position` meta field `gt` Filter records with a value that's strictly greater than the one specified ```graphql query { allProducts(filter: { position: { gt: 3 } }) { title } } ``` `lt` Filter records with a value that's less than the one specified ```graphql query { allProducts(filter: { position: { lt: 3 } }) { title } } ``` `gte` Filter records with a value that's greater than or equal to the one specified ```graphql query { allProducts(filter: { position: { gte: 3 } }) { title } } ``` `lte` Filter records with a value that's less or equal than the one specified ```graphql query { allProducts(filter: { position: { lte: 3 } }) { title } } ``` `eq` Search for records with an exact match ```graphql query { allProducts(filter: { position: { eq: 3 } }) { title } } ``` `neq` Exclude records with an exact match ```graphql query { allProducts(filter: { position: { neq: 3 } }) { title } } ``` --- # Content Delivery API — Deep Filtering Source [docs]: https://www.datocms.com/docs/content-delivery-api/deep-filtering.md [Modular Content](/docs/content-modelling/modular-content.md) and [Structured Text](/docs/content-modelling/structured-text.md) fields can embed [blocks](/docs/content-modelling/blocks.md), which are dynamic, flexible, and repeatable structures. When referring to the Content Delivery API, deep filtering allows you to **filter records based on the content within their embedded blocks**. ## Activate deep filtering Deep filtering is a feature that **needs to be explicitly enabled on a per-field basis.** This is to avoid complicating — and therefore slowing down — your GraphQL schema by generating a large number of types that will never actually be used. To activate the feature, go to a field's editing modal, and enable the deep filtering option: (Image content) Once enabled, new filters become available in the GraphQL Content Delivery API for the specified field. To be precise, there is a second necessary condition to see the newly activated GraphQL filters: the field must accept at least one block type. If the field does not allow embedding any block types within it, then deep filtering is not applicable — *there's nothing to filter!* — and therefore the GraphQL filters relative to deep filtering will not be present. > [!PROTIP] Pro tip: Explore use cases for deep filtering > Check out this [blog entry](https://www.datocms.com/blog/advanced-data-retrieval-with-deep-filtering.md) for an in-depth look at use cases where deep filtering can simplify accessing specific data without multiple API calls, enhancing performance and efficiency. ## Modular Content In the following examples, let's consider a `blog_post` model with a `content` Modular Content field that accepts two types of blocks: `hero` and `product`. #### Filter records containing at least one block matching the specified conditions To retrieve `blog_post` records that contain a `product` block with a `name` equal to `"T-Shirt"`, and a `price` greater than 30, you can use the following GraphQL query: ```graphql query { allBlogPosts( filter: { content: { any: { product: { name: { eq: "T-Shirt" }, price: { gt: 30 } } } } } ) { # ... } } ``` In other words, within a field with deep filtering enabled, you can specify an `any` key where, for each block type that the field accepts, you can define one or more filtering conditions. The word "any" can be read as: *"find records where any product block respects these conditions"*. The filtering conditions are the same ones discussed in the previous section on [Filtering records](/docs/content-delivery-api/filtering-records.md), with the only difference being that since blocks don't have meta fields like ie. `_firstPublishedAt` they cannot be used in this context. The only meta key available for blocks is `id`. #### Specifying conditions for multiple types of block If you specify conditions for more than one type of block, then all conditions must be respected. ```graphql query { allBlogPosts( filter: { content: { any: { product: { name: { eq: "T-Shirt" } } hero: { title: { matches: { pattern: "offer" } } } } } } ) { # ... } } ``` The example above will search for all blog posts that have **both** a `product` block called `"T-Shirt"`, and a hero block with a title that contains the term `"offer"`. #### Putting conditions in OR If you want to apply logical OR conditions between various conditions, you can always use the `OR` filter. The previous query can be modified to return blog posts that have either a "T-Shirt" `product` block or an "offer" `hero` block, like this: ```graphql query { allBlogPosts( filter: { OR: [ { content: { any: { product: { name: { eq: "T-Shirt" } } } } }, { content: { any: { hero: { title: { matches: { pattern: "offer" } } } } } } ] } ) { # ... } } ``` #### Filter records containing at least one block, of any kind If you are only interested into filtering records that, in a particular field, contain at least one block, regardless of its type, you can use the `exists` filter: ```graphql query { allBlogPosts( filter: { content: { exists: true } } ) { # ... } } ``` Inverting the condition into `exists: false` will find all blog posts that don't have any block in the field. #### Filter records containing at least one block of specified type If you want to be more specific and filter records that contain at least one block of one or more specific types, then you can use the `"containsAny": true` filter. You can also search for records that do not contain any blocks of a specific type with`"containsAny": false`. The following query returns all blog posts that contain at least one block of type `product`, but do not contain any blocks of type `hero`: ```graphql query { allBlogPosts( filter: { content: { containsAny: { product: true, hero: false } } } ) { # ... } } ``` ## Structured Text When deep filtering is *not* enabled on a Structured Text field, its GraphQL filters allow to filter by its textual content only, like this: ```graphql query { allProducts( filter: { structuredTextField: { matches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { # ... } } ``` However, when you activate deep filtering, the filter format will change, and the `value` argument will group together all filters related to the textual content. To put it differently, when deep filtering is turned on, the previous query needs to be rewritten as: ```graphql query { allProducts( filter: { structuredTextField: { value: { # this argument has been introduced matches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } } ) { # ... } } ``` > [!WARNING] This means a breaking change in GraphQL schema! > We just saw that enabling deep filtering on a Structured Text field will cause a change to the associated GraphQL filter type. This means that existing GraphQL queries may need to be rewritten in order to avoid errors. > > This is another reason why deep filtering is activable or not on a per-field basis: so that you are in control of when (and how) to introduce this change. > > To avoid unpleasant surprises in production, it is a good idea to test the switch to deep filtering for Structured Text fields in a a [sandbox environment](/docs/general-concepts/primary-and-sandbox-environments.md) first, and see if it breaks any of your existing GraphQL queries. All the query possibilities in deep filtering mentioned above for the Modular Content fields also apply to the Structured Text fields. The only distinction is that all the filter arguments related to blocks are nested inside the `blocks` argument: ```graphql query { allProducts( filter: { structuredTextField: { blocks: { any: { cta: { title: { eq: "Subscribe!" } } }, value: { matches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } } ) { # ... } } } ``` ## Known Issues > [!NOTE] Deep Filtering Technical Limitations > #### Depth Limit: > > Deep filtering is currently limited to only one level of depth. That is, you cannot filter records based on the content of blocks deeply nested inside other blocks. For example, if you have: > > - A modular content field > > - A parent block with a "parent title" field and another modular content field called "child blocks" > > - Inside a child block, you have another field called "child title" > > > You **can** filter by the "parent title" but you **cannot** filter by the "child title". > > #### Content Delivery API only: > > Deep filtering is currently limited to the Content Delivery API (CDA / GraphQL). You cannot deep filter records in the Content Management API (CMA / REST). --- # Content Delivery API — Ordering records Source [docs]: https://www.datocms.com/docs/content-delivery-api/ordering-records.md ## Ordering records When retrieving records of a specific model you can supply the `orderBy` argument for every scalar field of the model: `orderBy: _ASC` or `orderBy: _DESC`. For tree and sortable models, you can also order them by `position`: ```graphql query { allArtists( orderBy: [name_ASC] ) { id name } } ``` --- # Content Delivery API — Pagination Source [docs]: https://www.datocms.com/docs/content-delivery-api/pagination.md Pagination lets you retrieve large sets of records by breaking them into manageable chunks — helping optimize performance and reduce data transfer. ### Limit results with `first` Control the number of elements returned in a single query using the `first` parameter: - **Default limit:** 20 records - **Maximum limit:** 500 records The following query returns the first 5 artist records: ```graphql { allArtists(first: 5) { id name } } ``` ### Skip records with `skip` Use the `skip` parameter to offset your results, allowing you to implement pagination across multiple requests: ```graphql { allArtists(first: 5, skip: 10) { id name } } ``` This query skips the first 10 records and returns the next 5. ### Calculating the total number of results To determine the total number of records — typically to implement client-side pagination — use the `_XXXMeta` query: ```graphql query { allArtists(filter: { name: { in: ["Blank Banshee", "Gazelle Twin"] } }) { id name genre } _allArtistsMeta(filter: { name: { in: ["Blank Banshee", "Gazelle Twin"] } }) { count } } ``` Make sure to apply the same filters to both your regular query and the meta query, otherwise the two counts will diverge! ### Auto-pagination beyond the 500-record limit A single CDA query can return at most 500 records per collection. For larger result sets, the [`@datocms/cda-client`](/docs/content-delivery-api/your-first-request.md) package ships an `executeQueryWithAutoPagination` helper that rewrites the query on the fly into multiple aliased selections, executes it in a single round-trip, and stitches the results back together — transparently: ```typescript import { executeQueryWithAutoPagination } from '@datocms/cda-client'; const result = await executeQueryWithAutoPagination( `query BuildSitemapUrls { entries: allSuccessStories(first: 2500) { slug } }`, { token: process.env.DATOCMS_READONLY_TOKEN }, ); ``` ###### How it works Suppose you want to execute the following query on a model with 2,500 records: ```graphql query BuildSitemapUrls { allBlogPosts { slug } entries: allSuccessStories(first: 2500) { ...SuccessStoryUrlFragment } } fragment SuccessStoryUrlFragment on SuccessStoryRecord { slug } ``` The CDA returns at most 500 items at a time. Normally you'd paginate manually by issuing the same query five times, each with an incremented `skip`. `executeQueryWithAutoPagination` does it for you in a single round-trip by rewriting the query like this: ```graphql query BuildSitemapUrls { allBlogPosts { slug } splitted_0_entries: allSuccessStories(first: 500, skip: 0) { ...SuccessStoryUrlFragment } splitted_500_entries: allSuccessStories(first: 500, skip: 500) { ...SuccessStoryUrlFragment } splitted_1000_entries: allSuccessStories(first: 500, skip: 1000) { ...SuccessStoryUrlFragment } splitted_1500_entries: allSuccessStories(first: 500, skip: 1500) { ...SuccessStoryUrlFragment } splitted_2000_entries: allSuccessStories(first: 500, skip: 2000) { ...SuccessStoryUrlFragment } } fragment SuccessStoryUrlFragment on SuccessStoryRecord { slug } ``` Once executed, the results are collected and recomposed as if nothing happened. ###### Limitations - The query may contain **at most one** selection with an oversized `first:` argument. If two or more collections exceed 500 records in the same query, the helper throws. - The rewritten query must still respect the [GraphQL complexity cost limit](/docs/content-delivery-api/complexity.md). ###### Reading cache tags alongside auto-pagination A `rawExecuteQueryWithAutoPagination` variant is also available, with the same `[result, response]` return shape as [`rawExecuteQuery`](/docs/content-delivery-api/api-endpoints.md). It's useful when you need to combine auto-pagination with [Cache Tags](/docs/content-delivery-api/cache-tags.md): ```typescript import { rawExecuteQueryWithAutoPagination } from '@datocms/cda-client'; const [result, response] = await rawExecuteQueryWithAutoPagination(query, { token: process.env.DATOCMS_READONLY_TOKEN, returnCacheTags: true, }); const cacheTags = response.headers.get('x-cache-tags'); ``` You can find the complete API reference in the [`@datocms/cda-client` README](https://github.com/datocms/cda-client#executequerywithautopagination). --- # Content Delivery API — Localization Source [docs]: https://www.datocms.com/docs/content-delivery-api/localization.md ### Get your project locales First, you can fetch the list of locales configured in a project with the following query: ```graphql query { _site { locales # -> ["en", "it", "fr"] } } ``` ### Get the localizations available for a record In case you have a model with some localized fields, and the model itself does not require the presence of a localization for each one of the locales configured in a project, you might need to know which localizations are actually present for each record. The `_locales` field gives you exactly this information: ```graphql query { allBlogPosts { _locales # -> ["en", "it"] title } } ``` ### Filter records by available localizations The same `_locales` field can also be used to filter your records. For example, you can fetch only the records which have both an `en` and `it` localizations this way: ```graphql query { allBlogPosts(filter: {_locales: {allIn: [it]}}) { title } } ``` You can also use the `anyIn` criteria to fetch records which contain at least one of the requested localizations, or `notIn` to fetch records which do not have any of the specified localizations. ### Fetching localized content When you're fetching the value of a [localized field](/docs/general-concepts/localization.md), by default it will be returned in the project default locale — that is, the first locale in your project settings: ```graphql query { _site { locales # -> ["en", "it"] } allBlogPosts { title # -> will return the title value in "en" locale } } ``` To change that, you can add a `locale` argument to queries to specify another locale: ```graphql query { allBlogPosts(locale: it) { title # -> will return the title value in "it" locale } } ``` You can also specify a different locale on a per-field basis: ```graphql query { allBlogPosts(locale: it) { title # -> will return the title value in "it" locale enTitle: title(locale: en) # -> will return the title value in "en" locale } } ``` ### Fallback locales You can also specify a list of fallback locales (see the "Fallback Locales" section of [Localization](/docs/general-concepts/localization.md) ) together with the `locale` argument: ```graphql query { allBlogPosts(locale: it_IT, fallbackLocales: [it, en]) { title } } ``` If the field value for the specified `locale` is `null`\-ish (`null`, empty string or empty array), the system will try to find a non `null`\-ish value in each of the localizations specified in the `fallbackLocales` argument. The order of the elements in the `fallbackLocales` argument is important, as the system will start from the first element in the array, and go on from there. Just like the `locale` argument, you can specify different fallback locales on a per-field basis: ```graphql query { allBlogPosts { title(locale: it_IT, fallbackLocales: [it, en]) } } ``` ### Fetching all localizations If you want to get the value of a field in every available localization, you can use the `_all[FIELD]Locales` field: ```graphql query { allBlogPosts { _allTitleLocales { locale value } # -> returns [{ locale: "en", value: "Hi!"}, { locale: "it", value: "Ciao!"}] } } ``` #### Learn more about localization with DatoCMS DatoCMS allows a great deal of customization when dealing with localization. Check out these tutorial videos for a hands-on approach: [ (Image content) Localizing Content in DatoCMS Play video » ](https://youtu.be/166gt1Qg-d4) [ (Image content) Creating a localized blog using Next.js Play video » ](https://youtu.be/3tBeOwdVuwo) --- # Content Delivery API — Direct vs. Inverse relationships Source [docs]: https://www.datocms.com/docs/content-delivery-api/inverse-relationships.md [Link fields](/docs/content-modelling/links.md) allow you to define relationships between records — e.g., a "blog post" record can reference a "person" record through an "author" link field. Using the Content Delivery API, it is possible to follow such links between records in both directions. Continuing with our example: - Starting from a blog post, get its author (that's the *direct relationship* expressed by the link field in the blog post record). - Starting from a person, get all their blog posts (that's the *inverse relationship*, automatically derived by looking at the value of the author field in every blog post). ## Following a direct relationship It is trivial to fetch information about a record that's directly referenced through a link field: just use the ID of the field [like you would with any other](/docs/content-delivery-api/how-to-fetch-records.md): ```graphql query { allBlogPosts { title author { id firstName lastName } } } ``` ## Following an inverse relationship If you're interested in the collection of records that are referencing a specific record of your interest, first you need to enable the "Enable inverse relationships fields in GraphQL?" option in the model settings — in our example, the "person" model: (Video content) Once the option is enabled, you will be able to perform inverse relationship queries using the `_allReferencingXXX` GraphQL field: ```graphql query { allPeople { id name _allReferencingBlogPosts { id title } } } ``` > [!POSITIVE] Inverse relationship queries are blocks-aware! > Inverse relationship queries will also return results for links present inside some [blocks](/docs/content-modelling/blocks.md) embedded in the record, no matter the depth. #### Pagination With no arguments, the result will be the first 20 referencing records, but just like with regular collection queries, you can [paginate your results](/docs/content-delivery-api/pagination.md), and get the total number of records with the `_allReferencingXXXMeta` field: ```graphql query { allPeople { _allReferencingBlogPosts(first: 5, skip: 10) { ... } _allReferencingBlogPostsMeta { count } } } ``` #### Filtering references by field Suppose that our blog post model has two different link fields that point to the same "person" model: the author and the reviewer. If you're interested in only getting blog posts that link to a person via a specific field (e.g., the reviewer field), you can use the `through: { fields: }` argument: ```graphql query { allPeople { _allReferencingBlogPosts(through: {fields: {anyIn: [blogPost_reviewer]}}) { id title } } } ``` With the `through: { fields: }` argument is also possible to get only references coming from fields defined inside the record blocks embedded in a record via [Modular Content](/docs/content-modelling/modular-content.md) or [Structured Text](/docs/content-modelling/structured-text.md) fields. As an example, the following inverse relationship query: ```graphql query { allPeople { _allReferencingDocPages( through: {fields: {anyIn: [docPage_main__chapter_author]}} ) { ... } } } ``` Will only return documentation pages which link to a specific author through the `author` link of the blocks of type `chapter` defined inside the `main` field of the page itself. > [!WARNING] Use the API Explorer to make it easier to write your queries! > As you can see from the last example, arguments like `docPage_main__chapter_author` can be tricky to write, and the situation can get much worse when you start considering nested blocks! > > Always remember that in GraphQL you can harness the powers of introspection and use the API Explorer in your project to get query intelligent code-completion. #### Filtering references by locale Suppose that the "author" link in our blog post model is localized, so depending on the locale, the author of the blog post will be a different record. To filter references in a specific set of locales, ignoring the others, you can use the `through: { locales: }` argument: ```graphql query { allPeople { _allReferencingBlogPosts(through: {locales: {anyIn: [en]}}) { id title } } } ``` Likewise, if you need to filter references that are coming from non-localized fields, you can use the `_nonLocalized` enum value: ```graphql query { allPeople { _allReferencingBlogPosts(through: {locales: {anyIn: [_nonLocalized]}}) { id title } } } ``` #### Ordering To retrieve references in a specific order, you can use the `orderBy` argument. Suppose the "blog post" model has a `title` string field, you can specify the order like this: ```graphql query { allPeople { _allReferencingBlogPosts(orderBy: title_ASC) { id title } } } ``` #### Deep filtering You can even filter references based on one or more of its fields: ```graphql query { allPeople { _allReferencingBlogPosts(filter: {name: {matches: {pattern: "trip"}}}) { id title } } } ``` --- # Content Delivery API — Hierarchical sorting (Tree-like collections) Source [docs]: https://www.datocms.com/docs/content-delivery-api/hierarchical-sorting.md If you have models using [hierarchical sorting](/docs/content-modelling/hierarchical-sorting.md), you can use the `children` and `parent` attributes to find the top-level objects of the model and then navigate in depth: ```graphql query { allCategories(filter: {parent: {exists: false}}) { name children { name children { name children { name } } } } } ``` --- # Content Delivery API — Modular content fields Source [docs]: https://www.datocms.com/docs/content-delivery-api/modular-content-fields.md If you have [Modular Content fields](/docs/content-modelling/modular-content.md), you can use GraphQL fragments to fetch information about all their embedded blocks. Suppose a `blog_post` model has a modular content field called `content`, which in turn accepts the following [block models](/docs/content-modelling/modular-content.md): - Block `blog_post_text_block`: made of a `text` field (*multi-paragraph text*); - Block `blog_post_quote_block`: made of a `quote` field (*multi-paragraph text*) and `author` field (*single-line string*); - Block `blog_post_gallery_block`: made of a `gallery` field (*image gallery*); This GraphQL query will do the work: ```graphql query { allBlogPosts { title content { ... on BlogPostTextBlockRecord { id _modelApiKey text } ... on BlogPostQuoteBlockRecord { id _modelApiKey quote author } ... on BlogPostGalleryBlockRecord { id _modelApiKey gallery { url } } } } } ``` Since all records implement the GraphQL interface `RecordInterface`, you can dry up the same query like this: ```graphql query { allBlogPosts { title content { ... on RecordInterface { id _modelApiKey } ... on BlogPostTextBlockRecord { text } ... on BlogPostQuoteBlockRecord { quote author } ... on BlogPostGalleryBlockRecord { gallery { url } } } } } ``` The outcome of this query hinges on the type of Modular Content field. If we're dealing with the Multiple Blocks variant, it'll return an array of blocks. However, if we're working with the Single Block variant, it'll simply return one block, or `null` if it's absent. ### Filtering records by contained blocks If you need to filter records based on the content within their embedded blocks, please refer to the [Deep filtering](/docs/content-delivery-api/deep-filtering.md) section of this guide, where this scenario is explained in detail. --- # Content Delivery API — Structured text fields Source [docs]: https://www.datocms.com/docs/content-delivery-api/structured-text-fields.md If you have [Structured Text fields](/docs/content-modelling/structured-text.md) you can use GraphQL fragments to fetch the different blocks. Suppose a `blog_post` model has a Structured Text field called `content`, which in turn accepts [links](/docs/content-modelling/structured-text.md#linking-records) to other blog posts and the following [embedded blocks](/docs/content-modelling/structured-text.md#embedding-blocks): - Block `cta_block`: with a `label` and `url` fields (both *Single-line text*) - Block `carousel_block`: with an *Asset Gallery* field called `gallery` - Block `mention_block`: with a Single-line text field called `username` This GraphQL query will return all the data needed to render it: ```graphql query { allBlogPosts { title content { value blocks { __typename ... on RecordInterface { id } ... on CtaBlockRecord { label url } ... on CarouselBlockRecord { gallery { url } } } inlineBlocks { __typename ... on RecordInterface { id } ... on MentionBlockRecord { username } } links { __typename ... on RecordInterface { id } ... on BlogPostRecord { slug title } } } } } ``` ### Rendering Structured Text content You can then use the result of this query with one of the following libraries to render the result as HTML: - [`datocms-structured-text-to-plain-text`](https://github.com/datocms/structured-text/tree/main/packages/to-plain-text) to render it as plain text; - [`datocms-structured-text-to-html-string`](https://github.com/datocms/structured-text/tree/main/packages/to-html-string) to render it as an HTML string; - [`datocms-structured-text-to-dom-nodes`](https://github.com/datocms/structured-text/tree/main/packages/to-dom-nodes) to transform it in a list of DOM nodes; We also have ready-made components for the most popular frontend frameworks: - [React](https://github.com/datocms/react-datocms#structured-text) - [Vue](https://github.com/datocms/vue-datocms#structured-text) - [Svelte](https://github.com/datocms/datocms-svelte/tree/main/src/lib/components/StructuredText) - [Astro](https://github.com/datocms/astro-datocms/tree/main/src/StructuredText) ### Filtering records by contained blocks If you need to filter records based on the content within their embedded blocks, please refer to the [Deep filtering](/docs/content-delivery-api/deep-filtering.md) section of this guide, where this scenario is explained in detail. --- # Content Delivery API — Images and videos Source [docs]: https://www.datocms.com/docs/content-delivery-api/images-and-videos.md All the assets are augmented with some extra fields exposed via the GraphQL API, providing you some extra possibilities on the frontend. ### Images Besides all the fields that you can explore via the CMS interface, the API can return both the [BlurHash](https://blurha.sh/) and the [ThumbHash](https://evanw.github.io/thumbhash/) of every image, also as a [Data-URLs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs). You can embed the Data URL directly in the HTML of the page and then swap it with the actual image at a later time, to offer a smooth experience when loading images (LQIP). If you're on [React](/docs/next-js/managing-images.md), [Vue](/docs/nuxt.md), or [Svelte](/docs/svelte/managing-images.md) our Image components make everything extremely simple to implement. Alternatively, a more minimal option is to use the dominant colors to prepare the space where the image will be shown: ```graphql { allUploads { blurhash thumbhash blurUpThumb colors { hex } } } ``` #### Responsive images One special augmentation that we offer on top of images in our GraphQL API is the `responsiveImage` object. In this object you can find pre-computed image attributes that will help you setting up responsive images in your frontend without any additional manipulation. We support all the [imgix parameters](https://docs.imgix.com/apis/url) and also, for extra control, the [sizes](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes) argument, that we simply return inside the response so that you can control media query conditions: ```graphql { allUploads { responsiveImage(imgixParams: {fm: jpg, fit: crop, w: 600, h: 600}, sizes: "(max-width: 600px) 100vw, 600px") { # always required src srcSet width height # not required, but strongly suggested! alt title # LQIP (base64-encoded) base64 # Alternatively, a background color placeholder bgColor # you can omit 'sizes' if you explicitly pass the 'sizes' prop to the image component sizes } } ``` One particularly handy feature of the CDA Playground in DatoCMS is that you can explore all the imgix parameters and read the documentation by searching for them in the docs panel: (Video content) For imgix Parameters that accept more than one value, you can pass them as an array in your graphQL query manually: (Image content) To read all the details of the `responsiveImage` object head to [the blog post](https://www.datocms.com/blog/best-way-for-handling-react-images.md#putting-it-all-together-introducing-the-responsiveimage-query) where you can also find some examples and integrations. #### Focal points Every image in the CDA exposes a `focalPoint` field with the coordinates set by editors in the media area: ```graphql { allUploads { focalPoint { x # float from 0.0 (left) to 1.0 (right) y # float from 0.0 (top) to 1.0 (bottom) } } } ``` More importantly, the focal point is **applied automatically** to `responsiveImage` and `url` responses. When all of the following conditions are met, DatoCMS transparently injects [`fp-x`](https://docs.imgix.com/apis/rendering/focal-point-crop/focal-point-x-position), [`fp-y`](https://docs.imgix.com/apis/rendering/focal-point-crop/focal-point-y-position), and [`crop=focalpoint`](https://docs.imgix.com/apis/rendering/size/crop-mode) into the imgix parameters, with no changes needed on your side: - [`fit: crop`](https://docs.imgix.com/apis/rendering/size/resize-fit-mode) is set in `imgixParams` - A size is defined: either [`w`](https://docs.imgix.com/apis/rendering/size/image-width) + [`h`](https://docs.imgix.com/apis/rendering/size/image-height) together, or [`ar`](https://docs.imgix.com/apis/rendering/size/aspect-ratio) - No conflicting [`crop`](https://docs.imgix.com/apis/rendering/size/crop-mode) mode is set (modes like `entropy` or `faces` take priority and suppress the injection) - You have not manually specified `fp-x` or `fp-y` in the query (if you have, your values are used as-is) - The focal point is not at the default center (0.5, 0.5), which would have no effect on the crop For example, this query: ```graphql { allUploads { responsiveImage(imgixParams: {fit: crop, w: 400, h: 400}) { src srcSet } } } ``` ...automatically produces URLs with `crop=focalpoint&fp-x=...&fp-y=...` for any image that has a non-centered focal point set. During development, adding [`fp-debug: true`](https://docs.imgix.com/apis/rendering/focal-point-crop/focal-point-debug) to `imgixParams` renders a visual overlay that shows exactly where the focal point lands on the image. To learn how to set the focal point on an image from the media area, see [Images API](/docs/asset-api/images.md) . ### Videos > [!WARNING] Use HLS streaming whenever possible > In order to save costs and improve visitor UX, we strongly recommend that you serve videos via HLS (HTTP Live Streaming) whenever possible, instead of using the raw MP4 videos. > > HLS is easily served with our video components (below). Please see [How to stream videos efficiently: Raw MP4 Downloads vs HLS Streaming](/docs/streaming-videos/how-to-stream-videos-efficiently.md) for a more detailed explanation. If you chose to upload videos on DatoCMS, thanks to the integration with [Mux](https://www.mux.com/), we augment the CDA `video` objects with: - The Mux Playback ID, required for our `` component, or if you're using one of [Mux's players for other platforms](https://www.mux.com/docs/guides/play-your-videos) - HLS video streaming URL — we offer `` components for [React](https://github.com/datocms/react-datocms/blob/master/docs/video-player.md), [Vue](https://github.com/datocms/vue-datocms/tree/master/src/components/VideoPlayer) and [Svelte,](https://github.com/datocms/datocms-svelte/tree/main/src/lib/components/VideoPlayer) which act as a wrapper around [Mux's video player](https://github.com/muxinc/elements/blob/main/packages/mux-player/README.md) web component. Alternatively, you can learn [how to integrate the Mux video player into your frontend](https://docs.mux.com/guides/player/integrate-in-your-webapp); - High, medium and low quality MP4 versions of the video to support legacy browsers that do not support HLS; - Duration and frame rate of the video; - Thumbnail URL: resizable, croppable and available in JPEG, PNG and GIF format. See [Mux thumbnail query string parameters](https://docs.mux.com/guides/get-images-from-a-video#thumbnail-query-string-parameters) for available transformations. #### Example CDA Video Query This is an example GraphQL query on a `video` field: ```graphql { yourField { # API name of your media field id # The internal DatoCMS ID of the video, useful for navigating to it in the media area video { # The actual Mux video object muxPlaybackId # Playback ID, REQUIRED for the component streamingUrl # HLS URL for third-party players, e.g. https://stream.mux.com/{playbackId}.m3u8 mp4High: mp4Url(res: high) # Raw MP4 URL in high quality, https://stream.mux.com/{playbackId}/high.mp4 mp4Med: mp4Url(res: medium) # or medium.mp4 mp4Low: mp4Url(res: low) # low.mp4 width # In pixels, e.g. 1920 height # 1080 duration # seconds framerate # frames per second thumbJpg: thumbnailUrl(format: jpg) # https://image.mux.com/{playbackId}/thumbnail.jpg thumbPng: thumbnailUrl(format: png) # or thumbnail.png thumbGif: thumbnailUrl(format: gif) # thumbnail.gif thumbhash: # base64 string that encodes a thumbhash preview image posterTime # seconds with decimals, e.g. 2.345 } } } ``` #### Poster time Every video in the CDA exposes a `posterTime` field with the timestamp (in seconds, with decimals) that editors selected in the media area or in the record field as the representative frame of the video: ```graphql { yourField { video { # The actual Mux video object posterTime # seconds with decimals, e.g. 2.345 } } } ``` More importantly, the poster time is **applied automatically** to the `thumbnailUrl` response. When an editor has set a poster time, DatoCMS transparently injects the [time](https://docs.mux.com/guides/get-images-from-a-video#thumbnail-query-string-parameters) parameter into the generated Mux thumbnail URL, with no changes needed on your side. For example, the `thumbnailUrl` in this query: ```graphql { yourField { video { thumbnailUrl(format: jpg) } } } ``` ...produces a URL like `https://image.mux.com/{playbackId}/thumbnail.jpg?``**time=2.345**` for a video that has the poster time set at 2.345 seconds. This means the still image you get from `thumbnailUrl` — and the poster frame shown by our `` components before playback begins — matches the frame the editor deliberately chose, rather than defaulting to the start of the clip. ### Filtering You can filter on all the meaningful fields that we offer in the uploads. Here's an example of what you'll see in your CDA Playground: (Image content) ### Fetch uploads straight from the context For the GraphQL veterans this will be obvious, but still we are impressed how cool it is to be able to fetch all the augmented assets directly from the context where they are used: ```graphql { allAuthors { name avatar { responsiveImage { base64 sizes srcSet alt title } } } } ``` ### Image width & height errors with certain Imgix operations In most cases, our API will return the correct `width` and `height` for your images, which is necessary for correct rendering on the frontend. However, in some edge cases, like when using the Imgix [`trim`](https://docs.imgix.com/en-US/apis/rendering/trim) operation (and also [padding](https://docs.imgix.com/en-US/apis/rendering/border-and-padding/padding) and [rotation](https://docs.imgix.com/en-US/apis/rendering/rotation)), our API cannot know the true dimensions of the transformed image beforehand. This means that **using those transformations will cause our API to return the incorrect image width and height**, and you must manually calculate and override them on your frontend instead, like: ```tsx {/* Destructure the original responsiveImage object, then override its dimensions */} ``` Alternatively, you can download the transformed image (e.g. `https://www.datocms-assets.com/12345/example.png?trim=color`) and re-upload that transformation back into your DatoCMS media area as a separate file and use that directly. If you need any help with this, please contact our support team at [support@datocms.com](mailto:support@datocms.com). --- # Content Delivery API — Filtering uploads Source [docs]: https://www.datocms.com/docs/content-delivery-api/filtering-uploads.md You can supply different parameters to the `filter` argument to filter the query response accordingly: ```graphql query { allUploads(filter: { type: { eq: image } }) { url copyright exifInfo } } ``` If you specify multiple conditions, they will be combined as if it was a logical `AND` expression: ```graphql query { allUploads(filter: { type: { eq: image }, resolution: { eq: large }}) { blurUpThumb url(imgixParams: { w: 100, h: 100, fit: crop }) } } ``` You can also combine `AND` and `OR` logical expressions. For example, the following query will return all large images together with any video tagged with "fun": ```graphql query { allUploads( filter: { OR: [ { type: { eq: image }, resolution: { eq: large }}, { type: { eq: video }, tags: { contains: "fun" }} ] } ) { blurUpThumb url(imgixParams: {w: 100, h: 100, fit: crop}) } } ``` ## Available filters #### Filter by `_createdAt` `eq` Search for uploads with an exact match ```graphql query { allProducts( filter: { _createdAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" eq: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `neq` Exclude uploads with an exact match ```graphql query { allProducts( filter: { _createdAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" neq: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `lt` Filter uploads with a value that's less than the one specified ```graphql query { allProducts( filter: { _createdAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" lt: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `lte` Filter uploads with a value that's less or equal than the one specified ```graphql query { allProducts( filter: { _createdAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" lte: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `gt` Filter uploads with a value that's strictly greater than the one specified ```graphql query { allProducts( filter: { _createdAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" gt: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `gte` Filter uploads with a value that's greater than or equal to the one specified ```graphql query { allProducts( filter: { _createdAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" gte: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` #### Filter by `_updatedAt` `eq` Search for uploads with an exact match ```graphql query { allProducts( filter: { _updatedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" eq: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `neq` Exclude uploads with an exact match ```graphql query { allProducts( filter: { _updatedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" neq: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `lt` Filter uploads with a value that's less than the one specified ```graphql query { allProducts( filter: { _updatedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" lt: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `lte` Filter uploads with a value that's less or equal than the one specified ```graphql query { allProducts( filter: { _updatedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" lte: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `gt` Filter uploads with a value that's strictly greater than the one specified ```graphql query { allProducts( filter: { _updatedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" gt: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` `gte` Filter uploads with a value that's greater than or equal to the one specified ```graphql query { allProducts( filter: { _updatedAt: { # Value is truncated to the minute: "2018-02-13T14:30:00+00:00" gte: "2018-02-13T14:30:13+00:00" } } ) { title } } ``` > [!NOTE] Filtering adjacent records > Truncation to the nearest minute may cause filters to return unintended records (e.g., `gt: "2025-05-06T09:36:01+02:00"` becomes `gt: "2025-05-06T09:36:00+02:00"` and unexpectedly includes records at `2025-05-06T09:36:01+02:00`). > > Add an additional filter condition (like `slug: {neq: $slug}` in the example below) to ensure unintended records are excluded from the results: > > ```graphql > query NextArticle($slug: String, $firstPublishedAt: DateTime) { > next: article( > orderBy: _firstPublishedAt_ASC > filter: { > _firstPublishedAt: {gt: $firstPublishedAt}, > slug: {neq: $slug} > } > ) { > title > _firstPublishedAt > } > } > ``` #### Filter by `alt` `matches` Filter uploads based on a regular expression ```graphql query { allProducts( filter: { altField: { matches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` `not_matches` Exclude uploads based on a regular expression ```graphql query { allProducts( filter: { altField: { notMatches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` `eq` Search the uploads with the specified alt ```graphql query { allProducts(filter: { altField: { eq: "bike" } }) { title } } ``` `neq` Exclude the uploads with the specified alt ```graphql query { allProducts(filter: { altField: { neq: "bike" } }) { title } } ``` `in` Search uploads with the specified values as default alt ```graphql query { allProducts(filter: { altField: { in: ["bike"] } }) { title } } ``` `not_in` Search uploads that do not have the specified values as default alt ```graphql query { allProducts(filter: { altField: { notIn: ["bike"] } }) { title } } ``` `exists` Filter uploads with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { altField: { exists: true } }) { title } } ``` #### Filter by `author` `matches` Filter uploads based on a regular expression ```graphql query { allProducts( filter: { authorField: { matches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` `not_matches` Exclude uploads based on a regular expression ```graphql query { allProducts( filter: { authorField: { notMatches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` `exists` Filter uploads with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { authorField: { exists: true } }) { title } } ``` #### Filter by `basename` `matches` Filter uploads based on a regular expression ```graphql query { allProducts( filter: { basenameField: { matches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` `not_matches` Exclude uploads based on a regular expression ```graphql query { allProducts( filter: { basenameField: { notMatches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` #### Filter by `colors` `contains` Filter uploads that have the specified colors ```graphql query { allProducts(filter: { colorsField: { contains: red } }) { title } } ``` `all_in` Filter uploads that have all of the specified colors ```graphql query { allProducts(filter: { colorsField: { allIn: [red] } }) { title } } ``` `any_in` Filter uploads that have at least one of the specified colors ```graphql query { allProducts(filter: { colorsField: { anyIn: [red] } }) { title } } ``` `not_in` Filter uploads that do not have any of the specified colors ```graphql query { allProducts(filter: { colorsField: { notIn: [red] } }) { title } } ``` `eq` Search for uploads with an exact match ```graphql query { allProducts(filter: { colorsField: { eq: [red] } }) { title } } ``` #### Filter by `copyright` `matches` Filter uploads based on a regular expression ```graphql query { allProducts( filter: { copyrightField: { matches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` `not_matches` Exclude uploads based on a regular expression ```graphql query { allProducts( filter: { copyrightField: { notMatches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` `exists` Filter records with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { copyrightField: { exists: true } }) { title } } ``` #### Filter by `filename` `matches` Filter uploads based on a regular expression ```graphql query { allProducts( filter: { filenameField: { matches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` `not_matches` Exclude uploads based on a regular expression ```graphql query { allProducts( filter: { filenameField: { notMatches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` #### Filter by `format` `eq` Search the asset with the specified format ```graphql query { allProducts(filter: { formatField: { eq: "bike" } }) { title } } ``` `neq` Exclude the asset with the specified format ```graphql query { allProducts(filter: { formatField: { neq: "bike" } }) { title } } ``` `in` Search assets with the specified formats ```graphql query { allProducts(filter: { formatField: { in: ["bike"] } }) { title } } ``` `not_in` Search assets that do not have the specified formats ```graphql query { allProducts(filter: { formatField: { notIn: ["bike"] } }) { title } } ``` #### Filter by `height` `gt` Search all assets larger than the specified height ```graphql query { allProducts(filter: { heightField: { gt: 3 } }) { title } } ``` `lt` Search all assets smaller than the specified height ```graphql query { allProducts(filter: { heightField: { lt: 3 } }) { title } } ``` `gte` Search all assets larger or equal to the specified height ```graphql query { allProducts(filter: { heightField: { gte: 3 } }) { title } } ``` `lte` Search all assets larger or equal to the specified height ```graphql query { allProducts(filter: { heightField: { lte: 3 } }) { title } } ``` `eq` Search assets with the specified height ```graphql query { allProducts(filter: { heightField: { eq: 3 } }) { title } } ``` `neq` Search assets that do not have the specified height ```graphql query { allProducts(filter: { heightField: { neq: 3 } }) { title } } ``` #### Filter by `id` `eq` Search the asset with the specified ID ```graphql query { allProducts(filter: { id: { eq: "123" } }) { title } } ``` `neq` Exclude the asset with the specified ID ```graphql query { allProducts(filter: { id: { neq: "123" } }) { title } } ``` `in` Search assets with the specified IDs ```graphql query { allProducts(filter: { id: { in: ["123"] } }) { title } } ``` `not_in` Search assets that do not have the specified IDs ```graphql query { allProducts(filter: { id: { notIn: ["123"] } }) { title } } ``` #### Filter by `inUse` `eq` Search uploads that are currently used by some record or not ```graphql query { allProducts(filter: { inUseField: { eq: true } }) { title } } ``` #### Filter by `md5` `eq` Search the asset with the specified MD5 ```graphql query { allProducts(filter: { md5Field: { eq: "bike" } }) { title } } ``` `neq` Exclude the asset with the specified MD5 ```graphql query { allProducts(filter: { md5Field: { neq: "bike" } }) { title } } ``` `in` Search assets with the specified MD5s ```graphql query { allProducts(filter: { md5Field: { in: ["bike"] } }) { title } } ``` `not_in` Search assets that do not have the specified MD5s ```graphql query { allProducts(filter: { md5Field: { notIn: ["bike"] } }) { title } } ``` #### Filter by `mimeType` `matches` Filter uploads based on a regular expression ```graphql query { allProducts( filter: { mimeTypeField: { matches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` `not_matches` Exclude uploads based on a regular expression ```graphql query { allProducts( filter: { mimeTypeField: { notMatches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` `eq` Search the asset with the specified mime type ```graphql query { allProducts(filter: { mimeTypeField: { eq: "bike" } }) { title } } ``` `neq` Exclude the asset with the specified mime type ```graphql query { allProducts(filter: { mimeTypeField: { neq: "bike" } }) { title } } ``` `in` Search assets with the specified mime types ```graphql query { allProducts(filter: { mimeTypeField: { in: ["bike"] } }) { title } } ``` `not_in` Search assets that do not have the specified mime types ```graphql query { allProducts(filter: { mimeTypeField: { notIn: ["bike"] } }) { title } } ``` #### Filter by `notes` `matches` Filter uploads based on a regular expression ```graphql query { allProducts( filter: { notesField: { matches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` `not_matches` Exclude uploads based on a regular expression ```graphql query { allProducts( filter: { notesField: { notMatches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` `exists` Filter records with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { notesField: { exists: true } }) { title } } ``` #### Filter by `orientation` `eq` Search uploads with the specified orientation ```graphql query { allProducts(filter: { orientationField: { eq: landscape } }) { title } } ``` `neq` Exclude uploads with the specified orientation ```graphql query { allProducts(filter: { orientationField: { neq: landscape } }) { title } } ``` #### Filter by `path` `eq` Search the asset with the specified path ```graphql query { allProducts(filter: { pathField: { eq: "bike" } }) { title } } ``` `neq` Exclude the asset with the specified path ```graphql query { allProducts(filter: { pathField: { neq: "bike" } }) { title } } ``` `in` Search assets with the specified paths ```graphql query { allProducts(filter: { pathField: { in: ["bike"] } }) { title } } ``` `not_in` Search assets that do not have the specified paths ```graphql query { allProducts(filter: { pathField: { notIn: ["bike"] } }) { title } } ``` #### Filter by `resolution` `eq` Search uploads with the specified resolution ```graphql query { allProducts(filter: { resolutionField: { eq: icon } }) { title } } ``` `neq` Exclude uploads with the specified resolution ```graphql query { allProducts(filter: { resolutionField: { neq: icon } }) { title } } ``` `in` Search uploads with the specified resolutions ```graphql query { allProducts(filter: { resolutionField: { in: [icon] } }) { title } } ``` `not_in` Search uploads without the specified resolutions ```graphql query { allProducts(filter: { resolutionField: { notIn: [icon] } }) { title } } ``` #### Filter by `size` `gt` Search all assets larger than the specified size (in bytes) ```graphql query { allProducts(filter: { sizeField: { gt: 3 } }) { title } } ``` `lt` Search all assets smaller than the specified size (in bytes) ```graphql query { allProducts(filter: { sizeField: { lt: 3 } }) { title } } ``` `gte` Search all assets larger or equal to the specified size (in bytes) ```graphql query { allProducts(filter: { sizeField: { gte: 3 } }) { title } } ``` `lte` Search all assets larger or equal to the specified size (in bytes) ```graphql query { allProducts(filter: { sizeField: { lte: 3 } }) { title } } ``` `eq` Search assets with the specified size (in bytes) ```graphql query { allProducts(filter: { sizeField: { eq: 3 } }) { title } } ``` `neq` Search assets that do not have the specified size (in bytes) ```graphql query { allProducts(filter: { sizeField: { neq: 3 } }) { title } } ``` #### Filter by `smartTags` `contains` Filter uploads linked to the specified tag ```graphql query { allProducts(filter: { smartTagsField: { contains: "bike" } }) { title } } ``` `all_in` Filter uploads linked to all of the specified tags ```graphql query { allProducts(filter: { smartTagsField: { allIn: ["bike"] } }) { title } } ``` `any_in` Filter uploads linked to at least one of the specified tags ```graphql query { allProducts(filter: { smartTagsField: { anyIn: ["bike"] } }) { title } } ``` `not_in` Filter uploads not linked to any of the specified tags ```graphql query { allProducts(filter: { smartTagsField: { notIn: ["bike"] } }) { title } } ``` `eq` Search for uploads with an exact match ```graphql query { allProducts(filter: { smartTagsField: { eq: ["bike"] } }) { title } } ``` #### Filter by `tags` `contains` Filter uploads linked to the specified tag ```graphql query { allProducts(filter: { tagsField: { contains: "bike" } }) { title } } ``` `all_in` Filter uploads linked to all of the specified tags ```graphql query { allProducts(filter: { tagsField: { allIn: ["bike"] } }) { title } } ``` `any_in` Filter uploads linked to at least one of the specified tags ```graphql query { allProducts(filter: { tagsField: { anyIn: ["bike"] } }) { title } } ``` `not_in` Filter uploads not linked to any of the specified tags ```graphql query { allProducts(filter: { tagsField: { notIn: ["bike"] } }) { title } } ``` `eq` Search for uploads with an exact match ```graphql query { allProducts(filter: { tagsField: { eq: ["bike"] } }) { title } } ``` #### Filter by `title` `matches` Filter uploads based on a regular expression ```graphql query { allProducts( filter: { titleField: { matches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` `not_matches` Exclude uploads based on a regular expression ```graphql query { allProducts( filter: { titleField: { notMatches: { pattern: "bi(cycl|k)e", caseSensitive: false } } } ) { title } } ``` `eq` Search the asset with the specified title ```graphql query { allProducts(filter: { titleField: { eq: "bike" } }) { title } } ``` `neq` Exclude the asset with the specified title ```graphql query { allProducts(filter: { titleField: { neq: "bike" } }) { title } } ``` `in` Search assets with the specified as default title ```graphql query { allProducts(filter: { titleField: { in: ["bike"] } }) { title } } ``` `not_in` Search assets that do not have the specified as default title ```graphql query { allProducts(filter: { titleField: { notIn: ["bike"] } }) { title } } ``` `exists` Filter assets with the specified field defined (i.e. with any value) or not ```graphql query { allProducts(filter: { titleField: { exists: true } }) { title } } ``` #### Filter by `type` `eq` Search uploads with the specified type ```graphql query { allProducts(filter: { typeField: { eq: image } }) { title } } ``` `neq` Exclude uploads with the specified type ```graphql query { allProducts(filter: { typeField: { neq: image } }) { title } } ``` `in` Search uploads with the specified types ```graphql query { allProducts(filter: { typeField: { in: [image] } }) { title } } ``` `not_in` Search uploads without the specified types ```graphql query { allProducts(filter: { typeField: { notIn: [image] } }) { title } } ``` #### Filter by `width` `gt` Search all assets larger than the specified width ```graphql query { allProducts(filter: { widthField: { gt: 3 } }) { title } } ``` `lt` Search all assets smaller than the specified width ```graphql query { allProducts(filter: { widthField: { lt: 3 } }) { title } } ``` `gte` Search all assets larger or equal to the specified width ```graphql query { allProducts(filter: { widthField: { gte: 3 } }) { title } } ``` `lte` Search all assets larger or equal to the specified width ```graphql query { allProducts(filter: { widthField: { lte: 3 } }) { title } } ``` `eq` Search assets with the specified width ```graphql query { allProducts(filter: { widthField: { eq: 3 } }) { title } } ``` `neq` Search assets that do not have the specified width ```graphql query { allProducts(filter: { widthField: { neq: 3 } }) { title } } ``` --- # Content Delivery API — SEO and favicon fields Source [docs]: https://www.datocms.com/docs/content-delivery-api/seo-and-favicon.md While you can fetch the content of a ["SEO and Social" field](/docs/content-modelling/seo-fields.md) just like any other field, the GraphQL API exposes on every record a much simpler `_seoMetaTags` field that you can use to easily get HTML meta tags based on the information present in the record itself: ```graphql { blogPost { _seoMetaTags { tag attributes } } } ``` ## How are `_seoMetaTags` generated? Meta tags are generated merging the values present in the record's "SEO and Social" field, together with the [global SEO Preferences](/docs/content-modelling/seo-fields.md#global-seo-preferences) that you can configure in the Content tab. If the record doesn't have a "SEO and Social" field, the method tries to guess reasonable values by inspecting the other fields of the record (single-line strings and images). **`title,`****`og:title`****,** **`twitter:title`** These titles can be explicitly set in the "SEO and Social" field, if present. If the record does not have that SEO field, or the title is not specified, the tags will be generated from either the record title or the title provided in the global SEO settings. The *Title suffix* value from global SEO preferences will also be concatenated to the `title`field, as long as the total length of the title + suffix is 60 characters or less. If the combined length is longer, the suffix will be omitted. The suffix will NOT be added to the OpenGraph and Twitter titles, since there are already other fields for that (`og:site_name` and `twitter:site`). If needed, you can manually query for the suffix: ```graphql _site { globalSeo { titleSuffix } } ``` **`description`****,** **`og:description`****,** **`twitter:description`** These tags are generated using the description field in the "SEO and Social" field. If no such field is present, or the description is not specified, the tags will be generated from the description specified in the global SEO settings. `**og:image**`**,** `**og:image:width**`**,** `**og:image:height**`**,** **`og:image:alt`****,** `**twitter:image**`**,** `**twitter:image:alt**` These tags are generated using the image field in the "SEO and Social" field. If no such field is present, or the image is not specified, the tags will be generated from the image specified in the global SEO settings. **`robots noindex`** A `robots noindex` tag will be added if either global SEO Preferences or the "SEO and Social" field have a "Prevent from being indexed by search engines" enabled. **`og:locale`** This tag is generated using either the locale specified in the query filter, or the main locale. **`og:type`** If the model is a singleton an `og:type` of type `website` will be returned, otherwise an `og:type` of type `website` will be returned. **`og:site_name`** The tag is generated from the site name attribute (if provided) **`twitter:site`** The tag is deduced from the twitter\_account attribute (if provided) **`twitter:card`** The tag is generated from using the twitter\_card field in the "SEO and Social" field. If no such field is present, the global SEO settings will be used. **`article:modified_time`** This tag is generated using the updated\_at meta attribute of the Record **`article:publisher`** The tag is deduced from the facebook\_page\_url attribute (if provided) ## SEO title & image fallback rules (with automatic fallback) For SEO purposes, our basic philosophy is that having *some* relevant SEO is better than none at all. Thus, if a record is missing an explicit SEO title or image, **we will try to automatically** ***guess*** **a value for you using the record's own content**. This may be surprising at first, because this automatic fallback happens *before* your project-level SEO preferences are consulted. This section describes how this automatic fallback chain works. ### How SEO title fallback works We check these places, in order, and pick the **first non-blank value**: 1. **We always prefer the record's own SEO field**, if it has one, and if its title is set. If the record has 2+ SEO fields, we only look at the first field (alphabetically by API key) and ignore the others. 2. **Otherwise, we automatically pick a fallback field**, in this order: - The **"SEO fallback title" field in the model settings**, under the SEO tab, if one is set - The first (by API key) **single-line string field with "Show as heading?"** enabled in its field settings (under the Presentation tab) - The first **single-line string field** (regardless of its Presentation settings). First we pick that field, **then we check whether it has a non-blank value**. If so, we use it. If not, we skip all other fields and proceed to the next step. 3. **Last resort: the project's own "SEO preferences"** (in the left sidebar). We only check here if ALL the previous checks failed. 4. If all of the above are empty, we altogether omit `title` from the `_seoMetaTags` array. ### How SEO image fallback works We check these places, in order, and pick the **first usable image** (see below for what "usable" means): 1. **We always prefer the record's own SEO field**, if it has one, and if its image is set. If the record has 2+ SEO fields, we only look at the first field (alphabetically by API key) and ignore the others. 2. **Otherwise, we automatically pick a fallback field**, in this order: - The **"Fallback social card image" field designated in the model settings**, under the SEO tab, if there is one. - The first (by API key) **asset or gallery field with its "Accept only specified extensions" validation set to "Image (including SVG)"**. (The "Raster image, transformable by imgix" option does not count here.) - The first **asset or gallery field** (regardless of its validations). First we pick that field, **then we check whether it has a usable image or video thumbnail**. If so, we use it. If not, we skip all other fields and proceed to the next step. 3. **Last resort: the project's own "SEO preferences"** (in the left sidebar). We only check here if ALL the previous checks failed. 4. If all of the above are empty, we altogether omit `og:image`, `og:image:width`, `og:image:height`, `og:image:alt`, `twitter:image` and `twitter:image:alt` from the `_seoMetaTags` array. **What counts as a usable image:** the asset must be an image (including SVGs) or a video with a thumbnail. At any step, if the asset is another type (PDF, audio file, a video that's still awaiting processing and thumbnail creation, etc.), we skip it and move on to the next step, exactly as if it were empty. ## SEO description fallback rules The fallback system for the SEO description is much simpler, compared to the system for titles and images above. We check, in order, for the first non-empty value: 1. The record's **SEO field description** 2. The **model's designated excerpt field,** if one is set in the model's SEO tab. We convert this to plain text and truncate it 200 characters. 3. The sitewide default description set in the main sidebar's **SEO preferences** settings. 4. If none of the above have a value, the `description` tag is dropped from the `_seoMetaTags` array. ## Favicon meta tags Similarly, you can get the meta tags needed to properly show the site's favicon with the `_faviconMetaTags` attribute contained inside the `_site` field: ```graphql { _site { faviconMetaTags { tag attributes } } } ``` ## iOS and MS app icons If you're building an app, you can request additional meta tags with the `variants` argument: ```graphql { _site { faviconMetaTags(variants: [icon, appleTouchIcon, msApplication]) { tag attributes } } } ``` See an example of how the [SEO meta tags are generated in Next.js](/docs/next-js/seo-management.md). Want to know more about SEO customization in DatoCMS? Check out this video tutorial: [ (Image content) Working with and customizing SEO Fields Play video » ](https://youtu.be/WjF10isSjS0) --- # Content Delivery API — Meta fields Source [docs]: https://www.datocms.com/docs/content-delivery-api/meta-fields.md ## Record meta fields Every record has some *meta* fields that are providing some meta information on the records. For example you can get the creation date, the status, etc. All these fields are prefixed with an underscore, let's see them in detail: - `_createdAt`: date of creation of the record; - `_firstPublishedAt`: date of first publication of the record; - `_isValid`: is the record valid? This can be false if the schema has changed and the records haven't been updated yet; - `_modelApiKey`: the API key of the model; - `_publicationScheduledAt`: if the publication of a record is scheduled in the future, this field will hold the publication date; - `_seoMetaTags`: it's an object with the SEO meta tags computed from an optional SEO field and the fallback details from the main site settings. It's an object representing the meta tags: - `attributes`: the meta tag attributes; - `content`: the meta tag content; - `tag`: the meta tag name; - `_status`: represent the record status: draft/published; - `_updatedAt`: it's the date of last update; All these fields are read-only (also use the CMA) as they either represent an internal state of the record or they are precomputed by our API using other records (e.g., SEO fields). ## Site meta fields The `_site` object has a site-level meta field: - `locales`: the list of available locales. --- # Content Delivery API — Cache Tags Overview Source [docs]: https://www.datocms.com/docs/content-delivery-api/cache-tags.md DatoCMS Cache Tags help optimize your website or app's caching. They allow developers to simply tag webpages with unique identifiers, so when the content from the CMS is updated, these **tags can trigger an immediate and precise cache invalidation** only for the pages that actually include that content, and need to be regenerated. The main benefits include: - **Visitors can instantly view the most updated version of the content**, while maintaining the benefits of completely static and cached content. - **Hosting expenses and DatoCMS resource usage can be dramatically reduced** thanks to a precise caching mode that does not rely on time-based invalidation methods, or a total invalidation of the entire site when anything changes. - **It entirely relieves the developer of the duty to manage cache invalidation,** a task which is instead taken care of by DatoCMS itself. For a more comprehensive understanding of DatoCMS cache tags and the problem it solves, we recommend reading the [**feature's announcement**](https://www.datocms.com/blog/introducing-datocms-cache-tags.md) which provides some additional background. ## How does it work? Implementing cache tags on your app is a three-step process: 1. Ask the Content Delivery API to return the cache tags associated with each query, by adding an `X-Cache-Tags` header to your GraphQL requests; 2. Mark every page your website produces with the cache tags you received; 3. Implement an endpoint that invalidates those tags when DatoCMS sends them to you through a webhook. All three steps are designed to be quite straightforward to implement, allowing you to benefit from the advantages this method offers in a very short time. The rest of this section covers them in detail: - [**Cache tags in CDA responses**](/docs/content-delivery-api/cache-tags-format.md) — how to request cache tags, how they are encoded, and the limits every response respects. - [**Integrating cache tags in your project**](/docs/content-delivery-api/cache-tags-integrations.md) — how to apply the tags and purge them, first with any server behind a CDN, then with popular frameworks and hosting platforms. - [**The cache tags invalidation webhook**](/docs/content-delivery-api/cache-tags-invalidation.md) — how DatoCMS tells you what to invalidate, and what the payload looks like. ## What will be the final cache hit ratio? It is very difficult to answer this question precisely, as it is connected to a large number of factors including the type of site traffic, the frequency of content updates, the content present in your pages, the GraphQL queries you execute, and the reliability of the cache in the selected framework and hosting. Sometimes, it's simple to guess which pages will be invalidated when a content change occurs: for instance, if a blog's homepage showcases the latest posts, it's clear that adding a new post on DatoCMS will invalidate the homepage. Another straightforward example: let's say you have a query that pulls content for your website's navigation bar: any pages including that navigation bar need to be invalidated when the query creates new content. Other cases are less obvious to grasp: suppose that a post can belong to some categories, maybe more than one category. Which are the pages invalidated when an editor changes a post's categories? So, without being able to predict the actual result in terms of hit ratio, it is certainly possible to say this: - Regardless of the frequency of invalidation, a superior result will still be achieved with DatoCMS Cache Tags, compared to redeploying the entire website, invalidating all pages for each individual content change. - The benefits of cache tags increase as the number of pages on a website grows. --- # Content Delivery API — Cache tags in CDA responses Source [docs]: https://www.datocms.com/docs/content-delivery-api/cache-tags-format.md Every response from the Content Delivery API can return the list of cache tags associated with the query and its results. This page covers how to request them, how they are encoded, and the limits they respect. ## Requesting cache tags To access the cache tags, simply add the following header to your existing GraphQL POST requests: ```plaintext X-Cache-Tags: true ``` With this new header included (and the use of the `--include` flag to show HTTP headers), a CURL request would look like this: ```plaintext $ curl 'https://graphql.datocms.com/' \ -H 'Authorization: YOUR-API-TOKEN' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'X-Cache-Tags: true' \ --include \ --data-binary '{ "query": "query { allPosts { title } }" }' ``` > [!PROTIP] > The `X-Cache-Tags` is one of many headers you can use to shape up the behavior of the Content Delivery API. Refer to the related section for more information on the other [available headers in the Content Delivery API](/docs/content-delivery-api/api-endpoints.md) endpoint. The response (omitting what's not related to cache tags) will include a new `X-Cache-Tags` header: ```http HTTP/2 200 ... X-Cache-Tags: BQD?* 2.a*q f7e N*r;L 6-KZ@ t#k[uP t#k[ub t#k[uU ... { "data": { "allPosts": [ ... ] } } ``` The `X-Cache-Tags` that appears in the response is a space-separated list of strings: each string represents a cache tag, carefully generated to cover all possible invalidation scenarios. > [!POSITIVE] Cache tags are not readable, and that's a good thing! > DatoCMS provides cache tags that are intentionally opaque, to prevent misinterpretation and misuse on your end. Cache invalidation is a complicated process with a high possibility of errors and overlooking specific edge-cases. Our cache tags help us handle these complexities for you. Their non-transparent nature also allows us the flexibility to improve our tagging strategies in the future, without necessitating changes on your frontend. ## Encoding Cache tags are supposed to be opaque to the user, which means you don't have to know the meaning conveyed by each tag to use it. However, it may be useful to know and consider the encodings of the tags so that you can make sure they work properly across your tech stack. Each tag is a string encoded using an alphabet of 66 symbols: ```plaintext !"#$%&@'()*+-./0123456789:;<=>?[\]^_abcdefghijklmnopqrstuvwxyz{|}~ ``` Note that the alphabet contains **no spaces, no commas, and no uppercase letters**. Tags are therefore safe to concatenate into the comma-separated or space-separated header formats used by every major CDN, and they stay unambiguous on CDNs that treat cache tags case-insensitively (such as Netlify). > [!NOTE] Potential future encoding updates > We strive to ensure our cache tags are compatible with as many CDNs as possible. If we need to modify the encoding to support additional CDNs in the future, we'll handle the transition smoothly. Should such a change occur, we'll automatically send an invalidation event through your existing webhook configuration, allowing your system to adapt without any manual intervention required. ## Limits To ensure cache tags work across all major CDNs, DatoCMS enforces two limits on every Content Delivery API response: - **A maximum of 500 cache tags per response.** This is the lowest common denominator among the CDNs that support tag-based invalidation. - **A maximum of ~14 KB for the serialized** **`X-Cache-Tags`** **header.** Most CDNs cap the size of individual response headers (Cloudflare, for example, allows 16 KB per header and 32 KB in total), and we leave room for the rest of your response headers. - If a response would exceed either limit, our server will intelligently replace some specific tags with less granular, "catch-all" tags. This behavior ensures that your content does not become stale, at the expense of the occasional over-invalidation. Our rationale is that it's generally better to spend a few more API calls to fetch a bit more content than necessary, than to have orphaned stale content that is never correctly invalidated. ###### Granularity of cache tags A response's cache tags cover all the content its query returns, so the more content a query returns, the more often that response is invalidated. Count the tags in the `X-Cache-Tags` header to see where a query stands. A response that comes back with the maximum of 500 tags is the case worth acting on: it will be invalidated substantially more often than its content actually requires. Fetching fewer records per query — by paginating, or by splitting one large query into several smaller ones — makes invalidation more precise. --- # Content Delivery API — The cache tags invalidation webhook Source [docs]: https://www.datocms.com/docs/content-delivery-api/cache-tags-invalidation.md Once your pages carry cache tags, you need a way to invalidate them when editors change content. In implementing a caching mechanism, this is traditionally the most complex step to tackle. Fortunately, DatoCMS handles the complex job of tracking every possible alteration in your schema, text, images, and videos for you. When any change happens, DatoCMS can immediately send a list of tags that need invalidation to your frontend through a single webhook. ## Setting up the webhook Within your Project Settings, create a new webhook. Choose the "Invalidate" event of the "Content Delivery API Cache Tags" entity as the trigger: (Video content) The requests that the webhook will send will be in this JSON format: ```json POST /your/invalidation/endpoint HTTP/1.1 Content-Type: application/json { "entity_type": "cda_cache_tags", "event_type": "invalidate", "entity": { "id": "cda_cache_tags", "type": "cda_cache_tags", "attributes": { "tags": ["N*r;L", "6-KZ@", "t#k[uP"] } }, "related_entities": [] } ``` > [!WARNING] Invalidation batches can be large > DatoCMS groups invalidations over a short window, so the `tags` array has no fixed upper bound: a bulk publish can easily produce several hundred tags in a single delivery. > > Most purge APIs cap how many tags one request may carry, and rate-limit how often you can call them. Chunk the array to your provider's per-request limit, and retry on rate-limit responses. For reference, Cloudflare accepts 100 tags per purge request on Business plans. ## Implementing the endpoint The final step is to implement the endpoint that will receive incoming requests from the webhook. The task of this endpoint will be to execute cache invalidation based on the received cache tags. The way you perform cache invalidation through tags **greatly depends on the frontend framework and hosting solution you use**. In some instances it's an API call, whereas some frameworks offer specific helper functions. The integration guides cover both cases with working code. ###### Don't forget to invalidate on deploy When there's a cache layer above your application, content changes are not the only reason a cached page can go stale: a new version of your application will produce different HTML for the same content. Deploys are far less frequent than content changes, so a full purge of the CDN cache as the last step of your deploy pipeline is usually all you need. --- # Content Delivery API — Integrating cache tags in your project Source [docs]: https://www.datocms.com/docs/content-delivery-api/cache-tags-integrations.md Whatever your stack, an integration comes down to two things: marking each cached artifact with the tags that the Content Delivery API returned, and purging those tags when the invalidation webhook fires. How you do them depends on what sits between your code and your visitors. This page starts with the general case, any server behind any CDN, which is the simplest to reason about and the clearest way to see the mechanism. The second half covers popular frameworks and hosting platforms, where the picture is less uniform. ## Any server, any CDN If your application can set custom HTTP headers on a per-page basis, then regardless of language or framework you can use cache tags by **placing a CDN that supports tag-based invalidation on top of it.** ###### What is tag-based cache invalidation? Tag-based cache invalidation is a method where keywords (tags) can be assigned to cached pages. This technique is provided by all the major content delivery services such as [Netlify](https://www.netlify.com/blog/cache-tags-and-purge-api-on-netlify/), [Fastly](https://docs.fastly.com/en/guides/working-with-surrogate-keys), [Bunny](https://bunny.net/blog/introducing-tag-based-cdn-cache-purging/) and [Cloudflare](https://developers.cloudflare.com/cache/how-to/purge-cache/purge-by-tags/). The mechanism: - **Assign tags:** When your application delivers a page, it lists a series of tags in a response header (the header's name depends on the CDN). Each tag labels a piece of the content on that page. - **Caching:** The CDN stores the response under its primary cache key, the URL, together with the associated tags. - **Purging:** When content behind a tag changes, you can easily drop every cached item carrying that tag in a single call. Different services name the same concept differently. Fastly calls cache tags "Surrogate Keys". The header your application uses to declare the tags varies too: Netlify and Cloudflare read `Cache-Tag`, Bunny reads `CDN-Tag`. Netlify also accepts `Netlify-Cache-Tag`, which is preferable there because Netlify strips it from the response before it reaches the browser. What this documentation calls *"cache invalidation"*, other services call *"cache purge"*. Check your CDN's documentation for the exact details, format, and limitations. ###### The whole integration, end to end The integration is small enough to show in full. The example below uses [Hono](https://hono.dev/) as the server and [Fastly](https://docs.fastly.com/en/guides/working-with-surrogate-keys) as the CDN, but nothing in it is specific to either: the same two response headers and the same purge call apply to Express, Fastify, Rails, Laravel, or anything else that can set a header. **Tagging a response.** Ask the Content Delivery API for cache tags, then forward them to the CDN: ```javascript import { Hono } from 'hono'; import { rawExecuteQuery } from '@datocms/cda-client'; const app = new Hono(); app.get('/posts/:slug', async (c) => { const [data, response] = await rawExecuteQuery(POST_QUERY, { token: process.env.DATOCMS_CDA_TOKEN, returnCacheTags: true, variables: { slug: c.req.param('slug') }, }); const cacheTags = response.headers.get('x-cache-tags'); if (cacheTags) { c.header('Surrogate-Key', cacheTags); c.header('Surrogate-Control', 'max-age=31536000'); } return c.html(renderPost(data)); }); ``` Two details in there: - `X-Cache-Tags` is space-separated, and so is Fastly's `Surrogate-Key`: the value can travel verbatim. CDNs that expect a comma-separated `Cache-Tag` need `cacheTags.split(' ').join(',')` instead. - `Surrogate-Control` tells the CDN how long to keep the response, and Fastly strips it before the response reaches the browser. A one-year lifetime on the CDN is therefore safe, since cache tags rather than time expire the entry. Add a regular `Cache-Control` header, with a much shorter lifetime, if you also want visitors' browsers to cache the page. **Purging on content change.** The webhook endpoint receives the tags and hands them to the CDN's purge API: ```javascript app.post('/api/invalidate-cache', async (c) => { if (c.req.header('authorization') !== `Bearer ${process.env.WEBHOOK_TOKEN}`) { return c.json({ success: false }, 401); } const { entity } = await c.req.json(); const { tags } = entity.attributes; const response = await fetch( `https://api.fastly.com/service/${process.env.FASTLY_SERVICE_ID}/purge`, { method: 'POST', headers: { 'fastly-key': process.env.FASTLY_KEY, 'content-type': 'application/json', }, body: JSON.stringify({ surrogate_keys: tags }), }, ); return c.json({ success: response.ok }, response.ok ? 200 : 502); }); ``` The integration ends there: two response headers on the way out, and one POST when content changes. ## Popular frameworks and hosting platforms Some frameworks offer their own caching layer, with helpers that work across hosting providers instead of raw HTTP headers. When one is available it can be the more idiomatic path, but frameworks differ in how well they carry a set of cache tags from end to end, and that difference is worth knowing before you commit to a stack. We cannot document every framework and hosting combination. We maintain guides for the setups people ask us about most, and for the ones we are most comfortable recommending. ###### What makes a stack a good fit Three questions tell you most of what you need to know about a combination we haven't documented: - **Does it carry all your tags?** A Content Delivery API response can carry up to 500 cache tags, and the ceiling can come from either the hosting platform or the framework. Among platforms, Cloudflare's `Cache-Tag` header holds roughly 1,000 and Netlify accepts exactly 500, both above what we emit, as is Fastly's `Surrogate-Key`; [Vercel caps a cached response at 128 tags](https://vercel.com/docs/caching/cdn-cache/purge), well below our maximum. Among frameworks, Next.js applies that same figure one layer up: [it associates at most 128 tags with each `fetch()`](https://nextjs.org/docs/app/api-reference/functions/fetch#optionsnexttags), so the limit travels with the framework even when you host it elsewhere. - **Does it need extra infrastructure?** When tags travel verbatim from our response header into the CDN's header, nothing else is required. When they don't fit, you need somewhere to store the mapping between what you tagged and what we invalidate, which means a database in the request path. - **How fast can it invalidate?** Purge APIs cap the tags per request and rate-limit the calls. Cloudflare accepts 100 tags per purge request on every plan, at 5 requests per minute on Free up to 50 per second on Enterprise. Netlify allows a purge twice every five seconds, per tag or per site. Vercel's bulk endpoint accepts 16 tags per call, the tightest of the three. Since a bulk publish can produce several hundred tags in one webhook delivery, plan on chunking and retrying. ###### Where the friction shows up Next.js is the clearest example of the second question mattering. Since a `fetch()` accepts at most 128 tags, you cannot hand DatoCMS tags to Next.js directly. Our guide works around this by tagging each query with a single synthetic identifier and keeping a "query ID to cache tags" mapping in a persistent database, written whenever the cache is filled and read whenever the webhook fires. The approach works, we document it in full, and a starter project comes with it, but you will run and operate that database, and it sits in the invalidation path. The two costs belong to different layers: you pay for the mapping layer because of the framework, while the 128-tag ceiling is Vercel's and stays where it is no matter which framework renders the page. Stacks where the tags reach the CDN untouched avoid the mapping layer. Astro is a good example on the framework side: its Cache API takes `context.cache.set({ maxAge, tags })` and `cache.invalidate({ tags })`, and the adapter's cache provider forwards the tags to the platform's own header and purge API, with nothing in between. You end up with the same shape as the plain-HTTP example above, minus the platform details. Providers exist for Cloudflare, Netlify and Vercel alike, though on Vercel you keep the simplicity and still inherit the 128-tag ceiling. The hosting platform decides most of this, not the framework. Cloudflare, Netlify and Fastly all carry more tags than we emit and expose a purge-by-tag API that any code can call, so on those platforms *any* framework able to set a response header can integrate cache tags. That is the first half of this page, applied to a managed platform instead of your own CDN. A framework adds ergonomics on top: with Astro you never touch a header or a purge endpoint, because its providers wrap those same platform APIs for you. If you are still choosing, we would point you toward a platform that keeps cache tags verbatim from end to end and leaves room for all 500 of them, so Cloudflare, Netlify or Fastly, and then pick whichever framework you would have picked anyway. Both costs described above are worth avoiding when you can: a mapping layer is infrastructure you operate, and a tag ceiling below 500 is a limit you will hit one day without anyone telling you. ###### Our guides Each of these walks through one stack end to end, from the first query to the invalidation webhook: - [DatoCMS Cache Tags and Astro](/docs/astro/using-cache-tags.md): built on Astro's Cache API, and covering what changes between Cloudflare, Netlify and Vercel. - [DatoCMS Cache Tags and Next.js](/docs/next-js/using-cache-tags.md): including the mapping layer that the 128-tag ceiling makes necessary. If yours isn't here, you are not stuck: the three questions above will tell you most of what to expect from it, and the plain-HTTP integration at the top of this page works with any server that can set a response header, behind any CDN that can purge by tag. --- # Content Delivery API — Error codes & handling failures (CDA) Source [docs]: https://www.datocms.com/docs/content-delivery-api/errors.md ### Content Delivery API Errors and Failure Modes CDA errors happen when your frontend fails to query our GraphQL Content Delivery API for any reason. This can occur at different parts of the network stack, with different kinds of errors and responses, detailed below. > [!NOTE] These errors are only for the GraphQL Content Delivery API > If you're looking for errors related to our REST Content Management API, please instead see: [Error codes & handling failures (CMA)](/docs/content-management-api/errors.md) ## Network Errors **Network errors** occur when your request never made it to our servers. This can be due to a Wi-Fi problem, misconfigured VPN, corporate firewall, regional network outage, browser or HTTPS issue, etc. Rarely, it might also indicate server outages and downtime on our part. You can always check out status page at [https://status.datocms.com/](https://status.datocms.com/) or the [Outages section of the DatoCMS forum](https://community.datocms.com/c/outages/25). ## GraphQL Query Errors **GraphQL query errors** occur when the request reached our GraphQL server OK, but there was something wrong with the query itself. > [!WARNING] GraphQL query errors will still return a HTTP 200 OK > If a malformed or otherwise invalid query reaches our GraphQL server, you'll still receive a `**200 OK**` **HTTP status.** But that doesn't mean the query succeeded, only that our server received it. **The HTTP status is NOT a way to see if a query succeeded. Instead, you must check for the possible presence of an** **`errors[]`** **array.** A **successful** CDA response looks like: ```json5 // Successful CDA responses will have a data[] array and no errors[] array. // It will have a HTTP 200 OK status. { "data": { "allArticles": [ { "id": "abcdefghji12345", "title": "This is an example article", "slug": "example-article" } ] } } ``` A **failed** CDA response looks like: ```json5 // Failed CDA queries will return an errors[] array instead of data[] // Failed queries will ALSO have a HTTP 200 OK status. DO NOT TRUST THAT! { "errors": [ { "message": "Field 'Sku' doesn't exist on type 'ArticleRecord'", "locations": [ { "line": 16, "column": 5 } ], "path": [ "query", "allArticles", "Sku" ], "extensions": { "code": "undefinedField", "typeName": "ArticleRecord", "fieldName": "Sku" } } ] } ``` `**Within an errors[]**` **array**, each object will have the following properties: - `message`: The human-readable error message. - `locations`: The query line and column # where the server thinks the error occurred. Note that because of formatting and line break differences, the precise location may be slightly different in your code. - `path`: The attempted GraphQL path (e.g. `query`.`modelName`.`fieldName`) that caused the error. - `extensions`: Extended DatoCMS-specific errors that we provide to try to help you diagnose what went wrong. May be different for different kinds of query errors. ### HTTP & API Errors **HTTP & API errors** occur when the network request itself has an issue. The most common examples are invalid authorization tokens or hitting the rate limit on uncached queries. An HTTP or API error will have a shape similar to this: ```json5 { "id": "abcde12345", "type": "api_error", "attributes": { "code": "INVALID_JSON_BODY", // Machine-parseable code "details": { "message": "The JSON body you submitted is not a valid GraphQL request" // For humans } } } ``` `attributes.code` will be the machine-readable error code. See below for a list. `attributes.details.message` will be a short, human-readable explanation. ### List of HTTP & API Error Codes ###### **INVALID\_AUTHORIZATION\_HEADER** This error occurs when the provided API Authorization header is invalid or absent. Ensure that the API token used in the request is valid, has appropriate Content Delivery API (CDA) access permissions, and that the header is properly formatted. ###### **INVALID\_ENVIRONMENT** This error occurs when the GraphQL API request targets an environment that doesn’t exist. Check your environment identifier in the request. ###### INVALID\_JSON\_BODY The JSON request body is itself malformed or invalid, and our server can't find your query in the request. Perhaps you missed a bracket? Please see [Using the JavaScript CDA client](/docs/content-delivery-api/your-first-request.md) or use the "Playground" in your project, along with your browser's network inspector, to see what a properly-formed request would look like. ###### **ENVIRONMENT\_NOT\_READY** This error occurs when attempting to access an environment that exists but is not in a “ready” state. To resolve this, ensure that the environment you’re targeting has transitioned to “ready” status. You can check the current environment’s status via the DatoCMS interface or API before making modification requests. ###### **DEACTIVATED\_SITE** This error occurs when attempting to access a site that has been deactivated. To fix this, go to the DatoCMS dashboard and address any pending billing issues. ###### **SITE\_NOT\_READY** This error occurs when attempting to access a site that exists but is not in a “ready” state. The site may be initializing. Verify that the desired project is accessible, activated, and ready. ###### **INSUFFICIENT\_PERMISSIONS** This error occurs when a valid API token exists but lacks the necessary permissions to access the requested environment. The authentication succeeds, but the token doesn’t have the required authorization level for the operation. Ensure your API token has the appropriate role and permission settings for the environment you’re trying to access. ###### **INVALID\_X\_INCLUDE\_DRAFTS\_HEADER** This error occurs when the X-Include-Drafts header in your GraphQL API request has an invalid value. The header can only be set to “true” to include draft content in the response. Ensure your API request uses the correct value for this header or omit it entirely if you don’t need draft content. ###### **INVALID\_X\_EXCLUDE\_INVALID\_HEADER** This error occurs when the X-Exclude-Invalid header in your GraphQL API request has an invalid value. The header can only be set to “true” to exclude invalid content items from the response. Verify that your request uses the correct value for this header or remove it if not needed. ###### **INVALID\_X\_VISUAL\_EDITING\_HEADER** **(Enterprise Feature)** This error occurs when the X-Visual-Editing header is provided, but your site doesn’t have visual editing capabilities, which is an enterprise-only feature. Contact [support@datocms.com](mailto:support@datocms.com) for information about upgrading your plan to access this functionality. ###### **INVALID\_X\_VISUAL\_EDITING\_HEADER** **(Invalid Value)** This error occurs when the X-Visual-Editing header is provided with an invalid value. Currently, the only supported values for this header are `v1` and `vercel-v1`. Ensure your API request uses the correct value for this header when using visual editing features. ###### **INVALID\_X\_BASE\_EDITING\_URL\_HEADER** This error occurs when the X-Visual-Editing header is specified but the required X-Base-Editing-Url header is missing. When using visual editing features, you must provide the base editing URL to properly generate editing links. Ensure both headers are properly configured in your request. --- # Content Delivery API — CDA Technical Limits & Rate Limits Source [docs]: https://www.datocms.com/docs/content-delivery-api/technical-limits.md > [!NOTE] Content Delivery API (GraphQL) Only > These limits apply only to the Content Delivery API, our read-only GraphQL API. > > For other API limits, see: > > - [CMA Technical Limits & Rate Limits](/docs/content-management-api/technical-limits.md) > > - [Real-time Updates API Limits & Pricing](/docs/real-time-updates-api/limits-and-pricing.md) ## Overview To ensure system integrity and performance for all our customers, the Content Delivery API imposes 3 basic technical limits on your queries: - **Complexity**: How difficult your query is for our origin server to serve, in terms of its [**GraphQL complexity**](/docs/content-delivery-api/complexity.md) (max `10,000,000`). Queries that exceed this limit will return an error. - **Cacheability**: Your query request size, in bytes, indicating whether our CDN *can* cache it (max `12,000` bytes). Uncached or uncacheable requests are subject to rate limits (see below). - **Concurrency**: How many active, uncached requests our origin server can process for your project at once (normally `40`), shared between all of your requests that miss the cache. This primarily affects slow, long-running queries. Whenever you make a CDA query, it first goes through our CDN, Cloudflare. Per [data center](https://www.cloudflare.com/network/), we will serve the query straight from cache if possible, warm up the cache if needed, or tell you that this query can never be cached (because it's too long). Once it hits our origin server, we also check for its complexity and concurrency, process it, then return either a successful result or an [error](/docs/content-delivery-api/errors.md). To make sure your queries succeed and aren't limited, please make sure: 1. Your query's `x-complexity` HTTP header is under the maximum [GraphQL query complexity limit](/docs/content-delivery-api/complexity.md) (`10,000,000`). Requests that exceed this limit will return a `HTTP 200` with a [JSON `errors` object from our GraphQL server](/docs/content-delivery-api/errors.md) with a message like "`Query has complexity of X, which exceeds max complexity of 10000000`". 2. The `x-cacheable-on-cdn` HTTP header should return `true`. Requests that exceed this limit are too long for the CDN to cache and will always be dynamic and rate-limited. Consider breaking it down into smaller, separate queries instead. If all of the above are OK, then the bulk of your CDA responses should include a HTTP header of `cf-cache-status: HIT`, indicating a successful cache hit. For these cache hits, you don't have to worry about rate limits at all (because they only apply to uncached responses). For troubleshooting, there is a table further down this page with relevant HTTP headers. ### **Rate Limits for Uncached CDA Requests** Cached requests (see above) are not subject to a rate limit. Uncached requests must stay within two rate limits, both active simultaneously: - **40 requests/second per API token** - **1000 requests/min per API token** The rate limits are per API token. If your frontend uses the same API token across many pages, or in a big parallel build, every request made with the same token counts towards the same pool. > [!PROTIP] Pro tip: Use datocms/cda-client to automatically handle rate limits > If you use our official CDA client ( [Using the JavaScript CDA client](/docs/content-delivery-api/your-first-request.md) ), it will automatically handle our rate limits for you. > > This is great for simpler use cases, but please note that it does not account for concurrency (parallel Next.js build workers, `Promise.all()` over many simultaneous requests, etc.). #### **Rate Limit Examples** 1. If you use our official CDA client ( [Using the JavaScript CDA client](/docs/content-delivery-api/your-first-request.md) ) to make your CDA requests, we handle this for you automatically, and you don't have to worry about the other examples. 2. You make **60 requests** at once and hit the **per-second** **limit** immediately. The last 20 requests will be rejected with a `HTTP 429 Too many requests`. You should retry again after `x-ratelimit-reset: 1` second. 3. You sustain **40 requests/second** and stay within the per-second limit. But after 25 seconds, you will hit the **per-minute limit**. Remaining requests are rejected with a `429`. You should retry again after `x-ratelimit-reset: 35` seconds. 4. You sustain **40 requests/second across two worker threads, 20/sec each**: Same outcome as above. The rate limit is per API token, not per client. 5. You sustain **16 requests/second**, in total across that API token, and stay under both limits indefinitely. Well done! #### Project-wide Concurrency Limit Separate from the per-token rate limits above, there is also a **per-project limit of** **`40`** **concurrent requests**, **shared between all your API tokens**. "Concurrent" means that those requests are actively being processed by our origin server at the same time, regardless of when we received them. Whereas rate limits measure only the *frequency* of incoming requests; concurrency measures how many are still being processed at the same time — their overlapping *durations*, in other words. **An exaggerated example:** If you send us 16 requests/second, you will stay comfortably within the rate limits. But if each of those were a separate, slow and uncached query taking 10+ seconds to look up, then within 3 seconds you'll hit the concurrency limit. The first 40 requests will keep processing for the next 7+ seconds, while the last 8 requests will be rejected with a `429`. Normally, concurrency is not something the typical project or use case ever needs to worry about. It primarily affects only very slow, long-running queries that are sent at or near the same exact time, AND that are all uncached and hit our origin server. In practice, this combination of factors is extremely rare, and most of our customers never encounter it. We don't have separate error codes or HTTP headers for concurrency exceptions; they just look like regular rate limiting, and you can respond to them the same way: by simply waiting longer and respecting the `x-ratelimit-reset` header. However, if you suspect you are regularly hitting the concurrency limit, please first check your query and its filters, variables, and relationships and see if any could be simplified. If you need further help, please [contact DatoCMS Support](https://www.datocms.com/support.md) and we can help you further troubleshoot it on a case-by-case basis. ## **HTTP Headers for CDA Responses** CDA responses include the following HTTP headers to help you stay within limits and diagnose caching and rate limit issues. | Category | HTTP Header | Value | Notes | | --- | --- | --- | --- | | Complexity | `x-complexity` | `` This query's GraphQL complexity | Your request's current GraphQL complexity | | Complexity | `x-max-complexity` | `10000000` Max complexity allowed | The maximum complexity allowed, 10,000,000 by default. | | Cacheability | `cf-cache-status` | `HIT` or `MISS` or `DYNAMIC` or `BYPASS` Whether the CDN can cache this query | `HIT` indicates a cache hit, the desired behavior. No rate limits apply to this query. `MISS` indicates a cache miss, usually because it was the first time this particular request hit that data center. Repeat the same query/request and it should become a HIT next time. `DYNAMIC` means this query can NEVER be cached and will ALWAYS be subject to rate limits. May be due excess complexity, the query length limit (see below), or other error states. `BYPASS` is a special state that means our origin server told the CDN not to cache it. This should only happen on error states, either on the `429` themselves, OR sometimes on a `200` if there is a GraphQL error from our origin server. (See https://www.datocms.com/docs/content-delivery-api/errors#graphql-query-errors) | | Cacheability | `x-cacheable-on-cdn` | `true` or `false` | Whether the request body is short enough to ever be cacheable. This is the boolean summary of the following header, `x-cacheable-on-cdn-query-length-limit`. | | Cacheability | `x-cacheable-on-cdn-query-length-limit` | `/12000` Compressed query size, in bytes, out of allowed max | The actual calculation that determines if the previous header, `x-cacheable-on-cdn`, can ever be true. This is your GZIP-compressed & base64-encoded query size + our overhead, in bytes. The result must stay within 12,000 bytes (12KB decimal). | | Rate Limits | `x-ratelimit-limit` | `40` or `1000` Which rate limit bucket you're currently closer to. | `40`: You're closer to the per-second rate limit `1000`: You're closer to the per-minute rate limit | | Rate Limits | `x-ratelimit-remaining` | `` Requests remaining in closest bucket | How many requests you have remaining in the current bucket (per-second or per-minute), depending on `x-ratelimit-limit`. | | Rate Limits | `x-ratelimit-reset` | `` Seconds until next bucket refill | `1` for the per-second limit < `60` for the per-minute limit This header is only added when rate-limited, i.e., accompanying a `HTTP 429 Too many requests` status code. | | Miscellaneous | `x-request-id` | `UUIDv4` Internal ID that helps us troubleshoot specific requests | Please include this in support requests that refer to a specific GraphQL query. | ## Billing considerations Caching does not impact billing or quota calculations. 1 request = 1 API call billed against your quota, regardless of whether it's cached or cacheable. Free plans that exceed CDA limits will be temporarily suspended until the next month. Paid plans that exceed their included CDA quota will be charged per-request overages (in chunks). See [Pricing](https://www.datocms.com/pricing.md) for details. ## Notes 1. Very rarely, extreme load on our origin servers can also cause separate `429 Too many requests` errors, altogether separate from your query. You are very unlikely to ever experience this, and the remedy is the same as any other rate limit; please try again in a few seconds. 2. Invalidations happen automatically. When content in your project is changed, our system calculates the relevant queries to invalidate. For more manual control, you may wish to consider [Cache Tags](/docs/content-delivery-api/cache-tags.md). 3. If you get a `cf-cache-status: BYPASS` on a `HTTP 200 OK`, this is probably because you are getting a GraphQL error from our origin server (those errors return a `200` with a JSON body you must parse to see the actual GraphQL error). See [CDA: GraphQL Query Errors](/docs/content-delivery-api/errors.md#graphql-query-errors) for more information. --- # Content Delivery API — Complexity Source [docs]: https://www.datocms.com/docs/content-delivery-api/complexity.md Each query hitting our Content Delivery API has a complexity cost based on - which type of field is present - how many fields are present - how many filters are present - how many sorting parameters are present - the page size ### Limits Each DatoCMS plan comes with a maximum allowed complexity cost which is **10,000,000 by default**. Take a look at the "Plan and usage" section of your project in the [Account dashboard](https://dashboard.datocms.com/) to understand which is your complexity limit. The Content Delivery API sets the `X-Complexity` header in the response to let you know the calculated complexity cost for your submitted query and the `X-Max-Complexity` header containing your current plan complexity limit. If the query complexity cost above your plan limit **you'll get an error from the Content Delivery API**: ```json { "errors": [ { "message": "Query has complexity of xxx, which exceeds max complexity of yyy" } ] } ``` ### Base costs Unless specified otherwise, each requested GraphQL field has a cost of 1. Each filter argument has a cost of 250, except for [deep filtering arguments](/docs/content-delivery-api/complexity.md#deep-filtering). Each sorting parameter has a cost of 250. To calculate the pagination cost, multiply the page size by the inner fields' cost. By default, the page size is 20 but you can override it using the `first` argument. ### Model root fields #### Collection field Root fields like `allArtists` have a base cost of 100. To this, the cost of filters, the cost of sorting, and the cost of pagination must be added. The following query has a cost of 140: 100 (base) + 20 (implicit page size) x 2 (inner fields' cost) ```graphql query { # it returns at max 20 records by default allArtists { # 100 id # 1 name # 1 } } ``` The following query has a cost of 1,175: 100 (base) + 750 (filtering) + 250 (sorting) + 25 (page size) x 3 (inner fields' cost) ```graphql query { allArtists( # 100 filter: { birth: {gt: "1990-01-01", lt: "2010-01-01"}, # 250 x 2 => 500 country: {eq: "DE"} # 250 }, orderBy: [name_ASC], # 250 first: 25 # explicit page size ) { id # 1 name # 1 age # 1 } } ``` #### Collection meta field Root fields like `_allArtistsMeta` have a base cost of 1,000. To this, the cost of filters and the inner field's cost must be added. The following query has a cost of 1,251: 1,000 (base) + 250 (filtering) + 1 (inner fields' cost) ```graphql query { _allArtistsMeta( # 1,000 filter: { country: {eq: "NL"} } # 250 ) { count # 1 } } ``` #### Single record field Root fields like `artist` have a base cost of 50. To this, the cost of filters, the cost of sorting, and the inner fields' cost must be added. The following query has a complexity cost of 301: 50 (base) + 250 (filtering) + 1 (inner fields' cost) ```graphql query { artist( # 50 filter: { id: {eq: "123"} } # 250 ) { name # 1 } } ``` #### Single instance record field Root fields about single-instance records have a base cost of 25. To this, the inner field's cost must be added. The following query has a cost of 27: 25 (base) + 2 (inner fields' cost) ```graphql query { contactPage { # 25 phoneNumber # 1 emailAddress # 1 } } ``` #### Inverse relationships fields Fields like `_allReferencingMovies` can be used once activated the [inverse relationships feature](/docs/content-delivery-api/inverse-relationships.md) for the model. They have a base cost of 100. To this, the cost of filters, the cost of sorting, and the cost of pagination must be added. The following section has a cost of 1,110: 100 (base) + 500 (filtering) + 500 (sorting) + 5 (page size) x 2 (inner fields' cost) ```graphql ... _allReferencingMovies( # 100 through: { fields: {anyIn: [movie_artist]}, # 250 locales: {anyIn: en} # 250 }, orderBy: [title_ASC, _createdAt_DESC], # 500, first: 5 # explicit page size ) { id # 1 title # 1 } ... ``` Fields like `_allReferencingMoviesMeta` have a base cost of 1,000. To this, the cost of filters and the inner fields' cost must be added. The following section has a cost of 1,001. ```graphql ... _allReferencingMoviesMeta { # 1,000 count # 1 } ... ``` ### Model fields The following GraphQL fields differ from the base cost (1): - Single asset field: 5 - Asset gallery field: 5 x inner fields' cost - Multiple-paragraph text, when rendering Markdown in HTML: 5 - JSON field: 5 - Single link field: 10 - Multiple links field: 5 x inner fields' cost - Modular content field: 5 x inner fields' cost - Structured text field - value: 10 - blocks: 5 x inner fields' cost - links: 5 x inner fields' cost - `children` field (available in tree collections): 5 x inner fields' cost - `parent` field (available in tree collections): 25 - Localized field - value: number of environment's locales x inner fields' cost - SEO field - image: 5 - `_seoMetaTags`: 5 The following query has a cost of 351, composed by: - 50 (base cost of single record field) - 250 (filtering) - 5 + 1 + 5 (photo field) - 10 + 5 x 1 + 5 x 2 (content field) - 5 x 3 (movies field) ```graphql query { artist( # 50 filter: { id: {eq: "123"} } # 250 ) { photo { #single asset field: 5 url # 1 blurUpThumb # 5 } content { # structured text field value # 10 links { # 5 x inner fields' cost id # 1 } blocks { # 5 x inner fields' cost id # 1 text # 1 } } movies { # multiple links field: 5 x inner fields' cost id # 1 title # 1 releaseDate # 1 } } ``` ### Unions A GraphQL union complexity is the max complexity between all of the possible types. The modular content field `content` has a complexity cost of 10: 5 x 2 ```graphql query { artist(filter: { id: { eq: "123" }}) { name content { # 5 x max possible union's cost ... on MovieRecord { title # 1 } ... on TvSerieRecord { title # 1 channel # 1 } } } } ``` ### Deep Filtering Normally, each filter argument has a cost of 250, but when using [deep filtering](/docs/content-delivery-api/deep-filtering.md) an additional cost of 1,000,000 is added for each type of block model defined in the filter. The following query has a cost of 2,000,890: 100 (base) + 2,000,750 (filtering) + 20 (implicit page size) x 2 (inner fields' cost) ```graphql query { allBlogPosts( # 100 filter: { content: { any: { product: { # 1,000,000 name: { eq: "T-Shirt" # 250 }, price: { gt: 30 # 250 } } cta: { # 1,000,000 title: { isPresent: true # 250 } } } } } ) { id # 1 title # 1 } } ``` ### Upload root fields #### Collection field Root field `allUploads` has a base cost of 100. To this, the cost of filters, the cost of sorting, and the cost of pagination must be added. The following query has a cost of 801: 100 (base) + 250 (filtering) + 250 (sorting) + 30 (page size) x 7 (inner fields' cost) ```graphql query { allUploads( # 100 filter: {format: {eq: "jpg"}}, # 250 orderBy: [size_DESC], # 250 first: 30 # explicit page size ) { id # 1 url # 1 blurUpThumb # 5 } } ``` #### Collection meta field Root field `_allUploadsMeta` has a base cost of 1,000. To this, the cost of filters and the inner fields' cost must be added. The following query has a cost of 1,251: 1,000 (base) + 250 (filtering) + 1 (inner fields' cost) ```graphql query { _allUploadsMeta( # 1,000 filter: {format: {eq: "jpg"}} # 250 ) { count # 1 } } ``` #### Single upload field Root field `upload` has a base cost of 50. To this, the cost of filters, the cost of sorting, and the inner fields' cost must be added. The following query has a complexity cost of 308: 50 (base) + 250 (filtering) + 8 (inner fields' cost) ```graphql query { upload( # 50 filter: {id: {eq: "123"}} # 250 ) { url #1 title #1 blurUpThumb # 5 blurhash #1 } } ``` ### Upload fields The following GraphQL fields differ from the base cost (1): - blurUpThumb: 5 ### Site field Root field `_site` has a base cost of 10. To this, the inner fields' cost must be added. The following query has a cost of 13. ```graphql query { _site { # 10 globalSeo { # 1 siteName # 1 titleSuffix # 1 } } } ``` --- # Content Delivery API — Custom Scalar Types Source [docs]: https://www.datocms.com/docs/content-delivery-api/custom-scalar-types.md The API references a number of custom GraphQL Scalar Types. If you're using code generators to transform GraphQL types coming from the Content Delivery API to TypeScript, here's the list of mappings you need to specify: ```plaintext BooleanType: boolean CustomData: Record Date: string DateTime: string FloatType: number IntType: number ItemId: string JsonField: unknown MetaTagAttributes: Record UploadId: string ``` > [!PROTIP] Pro tip: How To Generate TypeScript Types From GraphQL > Generating TypeScript types from GraphQL queries improves code security, consistency, and robustness by avoiding manual type definitions. [This tutorial](https://www.datocms.com/blog/how-to-generate-typescript-types-from-graphql.md) explains how to set up graphql-codegen to automatically generate TypeScript types for a Next.js project using DatoCMS. --- # Content Delivery API — Changelog Source [docs]: https://www.datocms.com/docs/content-delivery-api/changelog.md All the changes to the Content Delivery API: ## 2022/06/10 - Add `RecordInterface` and `FileFieldInterface` interfaces - Every GraphQL type related records/blocks now implement the `RecordInterface` interface; - Every GraphQL type related to uploads, single asset or asset gallery fields now implements the `FileFieldInterface` interface. ## 2021/04/12 - Add `isBlank` filter to text fields To have a simple way to filter empty texts, especially when using a structured text field, we have added a `isBlank` filter to the textual fields. - **Changes to item fields** - **Single-line text field** Added boolean filter `isBlank` - **Multiple-line text field** Added boolean filter `isBlank` - **Structured text field** Added boolean filter `isBlank` ## 2020/05/11 - Changes in GraphQL filtering To make the API more consistent and prevent ambiguous results we have changed how filtering works in some edge cases. This is a big changeset, but should only affect edge cases and the minority of usages, following all the details. - **Changes to item fields** - **Boolean field**Filtering fields with `{eq: null}` will return an error message in response payload. Before this change, the filter would have returned always an empty array. You can still retrieve fields with `null` value using `{eq: false}` - **Color field**Filtering fields with `{exists: null}` will return an error message in response payload. Before this change, the filter would have returned the same result as `{exists: false}`. You can use `{exists: false}` from now on. - **DateTime field**Filtering fields with, for instance `{neq: "2020-04-09T00:00:00+02:00"}` will return *also* items with `null` values. Before this change, the filter would have returned only for `not null` values different from `2020-04-09T00:00:00+02:00`. - **Date field**Filtering fields with, for instance `{neq: "2020-04-09"}` will return *also* items with `null` values. Before this change, the filter would have returned only for `not null` values different from `2020-04-09`. - **Upload field** - Filtering fields with `{eq: null}` now has the same effect of using `{exists: false}`. Before this change, the filter would have returned always an empty array. - Filtering fields with `{neq: null}` now has the same effect of using `{exists: true}`. Before this change, the filter would have returned always an empty array. - Filtering fields with, for instance `{neq: "123456"}` will return *also* items with `null` values. Before this change, the filter would have returned only for items with `not null` uploads ids different from `123456`. - Filtering fields with `{exists: null}` will return an error message in response payload. Before this change, the filter would have returned the same result as `{exists: false}`. Please, use `{exists: false}` instead. - **Important**: Filtering fields with `{in: []}` will return an empty collection. Before this change, the request would have returned all items. - **Important**: Filtering fields with `{notIn: []}` will return all items. Before this change, the request would have returned an empty collection. - **Important**: Filtering fields with, for instance `{notIn: ["123456"]}` will return all items having values different from `123456` **OR** equal to `null`. Before this change, the request would have returned only items having `not null`values different from `123456`. - **Float fields** - Filtering fields with, for instance, `{neq: "2.42"}` will return *also* items with `null` values. Before this change, the filter would have returned only for items with `not null` values different from `2.42`. - Filtering fields with `{exists: null}` will return an error message in response payload. Before this change, the filter would have returned the same result as `{exists: false}`. Please, use `{exists: false}` instead. - **Gallery**Filtering fields with `{exists: null}` will return an error message in response payload. Before this change, the filter would have returned the same result as `{exists: false}`. Please, use `{exists: false}` instead. - **Integer** - Filtering fields with, for instance, `{neq: "5"}` now will return *also* items with `null` values. Before this change, the filter would have returned only for items with `not null` values different from `5`. - Filtering fields with `{exists: null}` will return an error message in response payload. Before this change, the filter would have returned the same result as `{exists: false}`. Please, use `{exists: false}` instead. - **JSON**Filtering fields with `{exists: null}` will return an error message in response payload. Before this change, the filter would have returned the same result as `{exists: false}`. Please, use `{exists: false}` instead. - **Position (geo points)**Filtering fields with `{exists: null}` will return an error message in response payload. Before this change, the filter would have returned the same result as `{exists: false}`. Please, use `{exists: false}` instead. - **Link** - Filtering fields with `{exists: null}` will return an error message in response payload. Before this change, the filter would have returned the same result as `{exists: false}`. Please, use `{exists: false}` instead. - Filtering fields with `{eq: null}` now has the same effect of using `{exists: false}`. Before this change, the filter would have returned always an empty array. - Filtering fields with `{neq: null}` now has the same effect of using `{exists: true}`. Before this change, the filter would have returned always an empty array. - Filtering fields with, for instance, `{neq: "123456"}` will return *also* items with `null` values. Before this change, the filter would have returned only for items with `not null` values different from `123456`. - **Important**: Filtering fields with `{in: []}` will return an empty collection. Before this change, the request would have returned all items. - **Important**: Filtering fields with `{notIn: []}` will return all items. Before this change, the request would have returned an empty collection. - Filtering fields with, for instance `{notIn: ["123456"]}` will return all items having values different from `123456` **OR** equal to `null`. Before this change, the request would have returned only items having `not null`values different from `123456`. - **Links**Filtering fields with `{exists: null}` will return an error message in response payload. Before this change, the filter would have returned the same result as `{exists: false}`. Please, use `{exists: false}` instead. - **Seo**Filtering fields with `{exists: null}` will return an error message in response payload. Before this change, the filter would have returned the same result as `{exists: false}`. Please, use `{exists: false}` instead. - **Slug** - Filtering fields with, for instance, `{neq: "foobar"}` now will return *also* items with `null` values. Before this change, the filter would have returned only for items with `not null` values different from `foobar`. - Filtering fields with, for instance `{notIn: ["foobar"]}` will return all items having values different from `foobar` **OR** equal to `null`. Before this change, the request would have returned only items having `not null`values different from `foobar`. - **String** - Filtering fields with `{exists: null}` will return an error message in response payload. Before this change, the filter would have returned the same result as `{exists: false}`. Please, use `{exists: false}` instead. - Filtering fields with `{eq: null}` now has the same effect of using `{exists: false}`. Before this change, the filter would have returned always an empty array. - Filtering fields with `{neq: null}` now has the same effect of using `{exists: true}`. Before this change, the filter would have returned always an empty array. - Filtering fields with, for instance, `{neq: "foobar"}` will return *also* items with `null` values. Before this change, the filter would have returned only for items with `not null` values different from `foobar`. - Filtering fields with, for instance, `{notMatches: { pattern: "foobar"}}` will return *also* items with `null` values. Before this change, the filter would have returned only for items with `not null` values different from `foobar`. - Filtering fields with, for instance `{notIn: ["foobar"]}` will return all items having values different from `foobar` **OR** equal to `null`. Before this change, the request would have returned only items having `not null`values different from `foobar`. - **Text** - Filtering fields with `{exists: null}` will return an error message in response payload. Before this change, the filter would have returned the same result as `{exists: false}`. Please, use `{exists: false}` instead. - Filtering fields with, for instance, `{notMatches: { pattern: "foobar"}}` will return *also* items with `null` values. Before this change, the filter would have returned only for items with `not null` values different from `foobar`. - **Video**Filtering fields with `{exists: null}` will return an error message in response payload. Before this change, the filter would have returned the same result as `{exists: false}`. Please, use `{exists: false}` instead. - **Changes to item metas** - **ID** - Filtering fields with `{eq: null}` will return an error message in response payload. Before this change, the filter would have returned an empty result. - Filtering fields with `{neq: null}` will return an error message in response payload. Before this change, the filter would have returned an empty result. - **Parent** - Filtering fields with `{exists: null}` will return an error message in response payload. Before this change, the filter would have returned the same result as `{exists: false}`. Please, use `{exists: false}` instead. - Filtering fields with `{eq: null}` now has the same effect of using `{exists: false}`. Before this change, the filter would have returned always an empty array. - **Position**Filtering fields with, for instance, `{neq: 3}` will return *also* items with `null` values. Before this change, the filter would have returned only for items with `not null` values different from `3`. - **Status** - Filtering fields with `{eq: null}` will return an error message in response payload. Before this change, the filter would have returned an empty result. - Filtering fields with `{neq: null}` will return an error message in response payload. Before this change, the filter would have returned an empty result. - **Changes to Upload fields** - **Alt, Title** - Added `exist` filter. - Filtering fields with `{eq: null}` now has the same effect of using `{exists: false}`. Before this change, the filter would have returned always an empty array. - Filtering fields with `{neq: null}` now has the same effect of using `{exists: true}`. Before this change, the filter would have returned always an empty array. - Filtering fields with, for instance, `{neq: "foobar"}` will return *also* items with `null` values. Before this change, the filter would have returned only for items with `not null` values different from `foobar`. - Filtering fields with, for instance, `{notMatches: { pattern: "foobar"}}` will return *also* items with `null` values. Before this change, the filter would have returned only for items with `not null` values different from `foobar`. - Filtering fields with, for instance `{notIn: ["foobar"]}` will return all items having values different from `foobar` **OR** equal to `null`. Before this change, the request would have returned only items having `not null` values different from `foobar`. - **Author** - Filtering fields with, for instance, `{notMatches: { pattern: "foobar"}}` will return *also* items with `null` values. Before this change, the filter would have returned only for items with `not null` values different from `foobar`. - Filtering fields with `{exists: null}` will return an error message in response payload. Before this change, the filter would have returned the same result as `{exists: false}`. Please, use `{exists: false}` instead. - **Copyright** - Filtering fields with, for instance, `{notMatches: { pattern: "foobar"}}` will return *also* items with `null` values. Before this change, the filter would have returned only for items with `not null` values different from `foobar`. - Filtering fields with `{exists: null}` will return an error message in response payload. Before this change, the filter would have returned the same result as `{exists: false}`. Please, use `{exists: false}` instead. - **Format**Filtering fields with `{eq: null}`, `{neq: null}`, will now return an error message in response payload. Before this change, the request would have return an empy collection. - **Height, Width**Filtering fields with, for instance, `{neq: "500"}` will return *also* items with `null` values. Before this change, the filter would have returned only for items with `not null` values different from `500`. - **ID**Filtering fields with `{eq: null}`, `{neq: null}`, will now return an error message in response payload. Before this change, the request would have return an empy collection. - **InUse**Filtering fields with `{eq: null}` will return an error message in response payload. Before this change, the filter would have returned the same result as `{eq: false}`. You can use `{eq: false}` from now on. - **MimeType**Filtering fields with `{eq: null}`, `{neq: null}`, will now return an error message in response payload. Before this change, the request would have return an empy collection. - **Notes** - Filtering fields with, for instance, `{notMatches: { pattern: "foobar"}}` will return *also* items with `null` values. Before this change, the filter would have returned only for items with `not null` values different from `foobar`. - Filtering fields with `{exists: null}` will return an error message in response payload. Before this change, the filter would have returned the same result as `{exists: false}`. Please, use `{exists: false}` instead. - **Size**Filtering fields with `{eq: null}`, `{neq: null}`, will now return an error message in response payload. Before this change, the request would have return an empy collection. - **SmartTags, Tags**Filtering fields with `{contains: null}`, will now return an error message in response payload. Before this change, the request would have return an empy collection. --- # Content Management API — Content Management API Overview Source [docs]: https://www.datocms.com/docs/content-management-api.md This document is a detailed reference to DatoCMS's Content Management API. The Content Management API (CMA) is used to manage the content of your DatoCMS projects. This includes creating, updating, deleting, and fetching content of your projects. > [!NOTE] Content Management vs Content Delivery API > If you want to programmatically create or update your schema/content, this is the API to use, while if you need to deliver content to your public-facing web or mobile projects, it is highly recommended that you use the GraphQL [Content Delivery API](/docs/content-delivery-api.md) instead, as it is under CDN and heavily optimized for fast response times! ### Core resources The Content Management API features **40+ resources,** for a total of **150+ endpoints**. Check the following sections of this documentation for a complete reference. For each single resource you will find: - The resource object and its fields, attributes and relationships; - The allowed CRUD operations you can perform on the related endpoint with basic examples of the request/response format. > [!WARNING] Some names might be different from what you expect! > Due to historical reasons and backward compatibility, the name of some specific resources in the Content Management API is different from what you'll find in the interface of the product. > > Specifically, Models are called **Item Types**, Records are called **Items**, and Assets are called **Uploads**. ### Base endpoint All API requests must be made over HTTPS to the following base endpoint: ```plaintext https://site-api.datocms.com ``` ### Basic headers The API follows the [JSON:API specification](https://jsonapi.org/) and provides an uniform and coherent way of working with every resource. To perform an HTTP request with a body, you need to pass an `Accept: application/json` header: Terminal window ```bash curl \ -H 'Accept: application/json' \ -H 'X-Api-Version: 3' \ https://site-api.datocms.com/site ``` To perform an HTTP request with a body, you need to pass a `Content-Type: application/vnd.api+json` header: Terminal window ```bash curl \ -X PUT -H 'Accept: application/json' \ -H 'X-Api-Version: 3' \ -H 'Content-Type: application/vnd.api+json' \ -d '{ ... }' \ https://site-api.datocms.com/site ``` The header `Content-Type: application/json` is also valid, but not suggested. ### Authentication To use the Content Management API, you will need to authenticate yourself with an API token. Read more about it in the [Authentication](/docs/content-management-api/authentication.md) section. ### Machine-readable API specification We expose a machine-readable JSON schema that describes what resources are available via the API, what their URLs are, how they are represented and what operations they support. This schema follows the [JSON Schema format](http://json-schema.org/), combined with the draft [Validation](http://tools.ietf.org/html/draft-fge-json-schema-validation-00) and [Hypertext](http://tools.ietf.org/html/draft-luff-json-hyper-schema-00) extensions. The latest version of the API schema will always be available at the following URL: ```plaintext https://site-api.datocms.com/docs/site-api-hyperschema.json ``` --- # Content Management API — Using the JavaScript CMA client Source [docs]: https://www.datocms.com/docs/content-management-api/using-the-nodejs-clients.md If you're familiar with Javascript/TypeScript, you can make use of our official client to perform requests to the Content Management API. It offers a number of benefits over making raw requests yourself: - **The package is written in TypeScript**, so every method is fully typed and offers editor auto-completion and type checks; - Tedious tasks like [API rate limits retry](/docs/content-management-api/technical-limits.md), [asyncronous jobs management](/docs/content-management-api/async-jobs.md), [pagination](/docs/content-management-api/pagination.md) and [creation of new assets](/docs/content-management-api/resources/upload/create.md) are either **automatically managed for you, or greatly simplified** with simple methods that hide the inner complexities. ### How to install the client DatoCMS provides three JavaScript client packages, each optimized for different runtime environments: Terminal window ```bash npm install @datocms/cma-client # Generic/agnostic (recommended for most cases) npm install @datocms/cma-client-node # Node.js with filesystem access npm install @datocms/cma-client-browser # Browser-optimized ``` **`@datocms/cma-client`** **(generic/agnostic)** — The safest and most portable choice. Use it for: - Edge functions (Cloudflare Workers, Vercel Edge Functions, etc.) - Serverless functions (AWS Lambda, Netlify Functions, etc.) - Any environment where maximum compatibility is needed **`@datocms/cma-client-node`** — Use this if you're in a Node.js environment to get the best experience. It provides specialized helper methods for [uploading files](/docs/content-management-api/resources/upload/create.md): `createFromLocalFile()` for local filesystem files and `createFromUrl()` for remote URLs. This gives you the most convenient API when working with Node.js and filesystem access. **`@datocms/cma-client-browser`** — Use this if you're in a browser environment to get the best experience. It provides the [`createFromFileOrBlob()`](/docs/content-management-api/resources/upload/create.md) helper method for handling `File` and `Blob` objects from `` elements, giving you the most convenient API when working with user file uploads. If you don't need these specialized upload helpers, the generic `@datocms/cma-client` package is the best choice — it works in more environments and avoids potential compatibility issues. ### Initializing the client You can use the `buildClient` function to initialize a new client. ```javascript import { buildClient } from '@datocms/cma-client-node'; const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); ``` ##### Specifying a sandbox environment By default, every API request you perform will point to the current primary environment, but if you want to make changes to a specific [sandbox environment](/docs/content-management-api/setting-the-environment.md), you can pass it in the initialization options: ```javascript import { buildClient } from '@datocms/cma-client-node'; const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN, environment: 'my-sandbox-environment', }); ``` ##### Logging request/responses The client can output logs of the API request and responses it performs to help you debug issues with your code. You can choose different level of logging, depending on how much information you need: ```javascript import { buildClient, LogLevel } from '@datocms/cma-client-node'; const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN, logLevel: LogLevel.BASIC, }); ``` The different levels of logging available are: - `LogLevel.NONE` (the default level): No output is generated; - `LogLevel.BASIC`: Logs HTTP requests (method, URL) and responses (status); - `LogLevel.BODY`: Logs HTTP requests (method, URL, body) and responses (status, body); - `LogLevel.BODY_AND_HEADERS`: Logs HTTP requests (method, URL, headers, body) and responses (status, headers, body). ### Entity collections and pagination Take a look at the [Pagination](/docs/content-management-api/pagination.md) section to understand how pagination works, and which methods the JavaScript client provides to make your task easier. ### Raw vs Simplified endpoint methods The client is organized by type of resource. For every resource, it offers a number of async methods to perform a CRUD request to a specific endpoint of the API: ```javascript // Example: Item Type (Model) await client.itemType.rawList(...); await client.itemType.rawFind(...); await client.itemType.rawCreate(...); await client.itemType.rawUpdate(...); await client.itemType.rawDestroy(...); ``` *"Why the* `*raw*` *prefix on all the methods?"* you might ask. Well, let's take a closer look at one specific method call — in this case, the update of an existing model. As already covered in previous sections, the API follows the `JSON:API` convention, which requires a specific format for the payloads. Every request/response has a `data` attribute, which contains a number of [Resource Objects](https://jsonapi.org/format/#document-resource-objects), which in turn contain different of top-level members (`id`, `type`, `attributes`, `relationships`, `meta`, etc), each with their own semantic: ```javascript const response = await client.itemTypes.rawUpdate('34532432', { data: { id: '34532432', type: 'item_type', attributes: { name: 'Article', api_key: 'article', }, relationships: { title_field: { data: { id: '451235', type: 'field' } }, }, } }); console.log(`Created model ${response.data.attributes.name}!`); ``` As you can see from the example above, it can become very verbose to write even simple code using this format! That's why the client also offers a "simplified" method for every endpoint — without the `raw` prefix — which greatly reduces the amount of boilerplate code required: ```javascript const itemType = await client.itemTypes.update('34532432', { name: 'Article', api_key: 'article', title_field: { id: '451235', type: 'field' }, }); console.log(`Created model ${itemType.name}!`); ``` So the complete set of methods available for the Model resource is: ```javascript // Example: Item Type (Model) await client.itemType.list(...); await client.itemType.rawList(...); await client.itemType.find(...); await client.itemType.rawFind(...); await client.itemType.create(...); await client.itemType.rawCreate(...); await client.itemType.update(...); await client.itemType.rawUpdate(...); await client.itemType.destroy(...); await client.itemType.rawDestroy(...); ``` In the next sections, you'll find a real-world usage example of the client for every endpoint offered by the API. ### Error management In case an [API call fails](/docs/content-management-api/errors.md) with HTTP status code outside of the 2xx range, an `ApiError` exception will be raised by the client, containing all the details of the request/response. ```javascript import { ApiError } from '@datocms/cma-client-node'; try { await client.itemType.create({ name: 'Article', api_key: 'article', }); } catch(e) { if (e instanceof ApiError) { // Information about the failed request console.log(e.request.url); console.log(e.request.method); console.log(e.request.headers); console.log(e.request.body); // Information about the response console.log(e.response.status); console.log(e.response.statusText); console.log(e.response.headers); console.log(e.response.body); } else { throw e; } } ``` The error object also includes a `.findError()` method that you can use to check if the response includes a particular error code: ```javascript // finds in the array of api_error entities an error with code 'INVALID_FIELD', // that in its details has the key 'field' set to 'api_key': const errorEntity = e.findError('INVALID_FIELD', { field: 'api_key' }); ``` ### `SchemaRepository` utility for efficient schema access When working with complex operations that require frequent access to schema information (models, fields, fieldsets, and plugins), the `SchemaRepository` utility provides an efficient caching layer to avoid redundant API calls. ```typescript class SchemaRepository { constructor(client: GenericClient) // Item Type methods async getAllItemTypes(): Promise async getAllModels(): Promise async getAllBlockModels(): Promise async getItemTypeByApiKey(apiKey: string): Promise async getItemTypeById(id: string): Promise // Field methods async getItemTypeFields(itemType: ItemType): Promise async getItemTypeFieldsets(itemType: ItemType): Promise // Plugin methods async getAllPlugins(): Promise async getPluginById(id: string): Promise async getPluginByPackageName(packageName: string): Promise // Raw variants (return full JSON:API response format) async getAllRawItemTypes(): Promise async getRawItemTypeByApiKey(apiKey: string): Promise // ... and more raw variants } ``` ###### **Purpose** `SchemaRepository` is designed to solve performance problems when repeatedly fetching the same schema information during operations that traverse nested blocks, structured text, or modular content. It acts as an in-memory cache for schema entities. Without `SchemaRepository`, a script processing fields containing nested blocks might make the same `client.itemTypes.list()` or `client.fields.list()` calls dozens of times: `SchemaRepository` ensures each unique schema request is made only once. ```typescript import { SchemaRepository, mapBlocksInNonLocalizedFieldValue } from '@datocms/cma-client'; const schemaRepository = new SchemaRepository(client); // These calls will hit the API and cache the results const models = await schemaRepository.getAllModels(); const blogPost = await schemaRepository.getItemTypeByApiKey('blog_post'); // These subsequent calls will return cached results (no API calls) const sameModels = await schemaRepository.getAllModels(); const sameBlogPost = await schemaRepository.getItemTypeByApiKey('blog_post'); // Pass the repository to utilities that need schema information await mapBlocksInNonLocalizedFieldValue(record.content, 'rich_text', schemaRepository, (block, path) => { // The utility will use the cached schema data internally }); ``` ###### What's it for - **Caching schema entities**: Automatically caches item types, fields, fieldsets, and plugins after the first API request - **Complex traversal operations**: Essential when using utilities like [`mapBlocksInNonLocalizedFieldValue()`](https://github.com/datocms/js-rest-api-clients/tree/main/packages/cma-client#recursive-block-operations) that need to repeatedly lookup block models and fields - **Bulk operations**: Ideal for scripts that process multiple records of different types - **Read-heavy workflows**: Perfect for scenarios where you need to repeatedly access the same schema information ###### When NOT to use it - **Schema modification**: Do NOT use if your script modifies models, fields, fieldsets, or plugins, as the cache will become stale! - **Long-running applications**: The cache has no expiration mechanism! - **Concurrent schema changes**: No protection against cache inconsistency! > [!PROTIP] Pro tip: Best practices > Create one instance per script execution, not per operation, and make sure to use `SchemaRepository` consistently throughout your script for maximum cache efficiency! ### Ponyfilling `fetch()` If your Javascript environment does not provide the [Fetch API interface](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) — for example, if you are using a version of Node lower than 18 — you will need to specify a ponyfill during client configuration: ```javascript import { buildClient } from '@datocms/cma-client-node'; import { fetch } from '@whatwg-node/fetch'; const client = buildClient({ apiToken: '', fetchFn: fetch }); ``` --- # Content Management API — API versioning Source [docs]: https://www.datocms.com/docs/content-management-api/api-versioning.md The latest version of the Content Management API is version 3. On every request you perform, you **MUST** specify the API version with the `X-Api-Version` header: Terminal window ```bash curl \ -H 'Authorization: Bearer ' \ -H 'Accept: application/json' \ -H 'X-Api-Version: 3' \ https://site-api.datocms.com/site ``` ## Breaking changes The guarantee that the Content Management API offers is to **introduce breaking changes only when the API version changes**. It is considered a "breaking change": - a change in path for an existing endpoint; - a change in the format of the request/response payload compared to what stated in this API reference; We reserve the right to change the format of payloads **without changing API version** only when: - an attribute/relationship that previously was mandatory in a HTTP request becomes optional; - a new optional attribute/relationship is introduced in a HTTP request; - a new attribute/relationship is introduced in a HTTP response; - a synchronous endpoint becomes [asynchronous](/docs/content-management-api/async-jobs.md), but the job result has exactly the same signature as the old synchronous endpoint. In other words, **no fields will ever be removed from the responses, but new ones might be added** if they do not break former behaviours. --- # Content Management API — Authentication Source [docs]: https://www.datocms.com/docs/content-management-api/authentication.md In order to make any request to the Content Management API (CMA), you need to first obtain an API token. Enter your project administrative area (ie. `http://your-project.admin.datocms.com`) and go to the *Project Settings \> API Tokens* section: (Video content) Every project comes with a read-only API token by default. If you need to perform other types of requests — like writing or deleting content — you can create a custom API token with the appropriate permissions. You can use roles to define granular access levels and control exactly what each token can do. Once you have the API Token, you need to pass it as an `Authorization` header in each HTTP request you perform: Terminal window ```bash curl \ -H 'Authorization: Bearer ' \ -H 'Accept: application/json' \ -H 'X-Api-Version: 3' \ https://site-api.datocms.com/site ``` If you're using our [Javascript client,](/docs/content-management-api/using-the-nodejs-clients.md) you can pass the same API token as an option to the `buildClient` initialization function: ```javascript import { buildClient } from '@datocms/cma-client-node'; const client = buildClient({ apiToken: '', }); ``` --- # Content Management API — Environments Source [docs]: https://www.datocms.com/docs/content-management-api/setting-the-environment.md Every DatoCMS project has one [primary environment, and can have multiple sandbox environments](/docs/general-concepts/primary-and-sandbox-environments.md). Sandbox environments are very useful to test changes in your schema/content, without interfering with the regular flow of content editors. By default, every API request you perform will point to the current primary environment, but if you want to make changes to a specific sandbox environment, you can add an `X-Environment` header. Terminal window ```bash curl \ -H 'Authorization: Bearer ' \ -H 'Accept: application/json' \ -H 'X-Api-Version: 3' \ -H 'X-Environment: my-sandbox-environment' \ https://site-api.datocms.com/site ``` If you're using our [Javascript client](/docs/content-management-api/using-the-nodejs-clients.md), you can pass the sandbox environment in the initialization options: ```javascript import { buildClient } from '@datocms/cma-client-node'; const client = buildClient({ apiToken: '', environment: 'my-sandbox-environment', }); ``` The legacy JS client has a similar option too: ```javascript const { SiteClient } = require('datocms-client'); const client = new SiteClient('YOUR-API-TOKEN', { environment: 'my-sandbox-environment', }); ``` --- # Content Management API — Error codes & handling failures (CMA) Source [docs]: https://www.datocms.com/docs/content-management-api/errors.md ### Content Management API Errors CMA errors happen when your automation script, backend, or (rarely) frontend experiences a failure while talking to our REST Content Management API. This can happen for a variety of reasons, detailed below. > [!NOTE] These errors are only for the REST Content Management API > If you're looking for errors related to our GraphQL Content Delivery API, please instead see: [Error codes & handling failures (CDA)](/docs/content-delivery-api/errors.md) ## Non-200 HTTP Status Codes When an Content Management API endpoint **fails for any reason,** it will return an **HTTP status code outside the** `**2xx**` **range**. Parse its JSON response body and use the detailed error codes below to troubleshoot. ## CMA Error JSON Body Response Structure The response body will include an array of **api\_error** entities that provide detailed information about the issue. Each error entity contains the following attributes: - **`code`**: A unique identifier for the specific error. - **`doc_url`**: A link to this documentation page for additional context. - **`details`**: Additional information describing the cause of the error. - **`transient`** *(optional)*: If set to `true`, this indicates the error is temporary. You can retry the request later as the issue may resolve itself. As an example, this could be the response for a request that tries to [create a new model](/docs/content-management-api/resources/item-type/create.md), but the provided `api_key` is already used by another model: ```json { "data": [ { "id": "ce9dcb", "type": "api_error", "attributes": { "code": "INVALID_FIELD", "doc_url": "https://www.datocms.com/docs/content-management-api/errors#INVALID_FIELD", "details": { "field": "api_key", "code": "VALIDATION_UNIQUENESS", "record_type": "ItemType" } } } ] } ``` ## Error codes ###### `ACCOUNT_ALREADY_JOINED_SITE` This error occurs when an attempt is made to invite a collaborator with an email that is already a member of the specified DatoCMS project. Ensure that the email provided for the user you are trying to invite is not already associated with an existing user in the project, or with the owner of the project itself. ###### `ALREADY_PRIMARY_ENVIRONMENT` This error occurs when an attempt is made to promote an environment that is already set as the primary. Ensure that the environment you are trying to promote differs from the existing primary. ###### `BILLING_PROFILE_DEFAULTING` This error occurs when attempting to perform an operation on a billing profile that has been cancelled. Ensure the billing profile is in an active state before retrying the request. ###### `CANNOT_CREATE_OR_DESTROY_SCHEMA_MENU_ITEM_LINKED_TO_ITEM_TYPE` This error occurs when attempting to create or delete schema menu items that are linked to a specific model. Such entities are read-only and are automatically managed by DatoCMS. Only schema menu items not linked to an model can be created/modified/deleted. ###### `CANNOT_DESTROY_CURRENT_USER` This error occurs when an API token attempts to delete itself. To resolve this issue, ensure that the request is made by a different access token than the one intended for deletion. ###### `CANNOT_DESTROY_FORKING_ORIGIN` This error occurs when attempting to delete an environment that is currently serving as an origin for another environment that is still being created. To resolve this, ensure that no existing environment is being forked from the one you wish to delete, or wait for the creation processes to complete before retrying the deletion request. ###### `CANNOT_DESTROY_PRIMARY_ENVIRONMENT` This error occurs when an attempt is made to delete the primary environment of a DatoCMS project. The primary environment serves as the main staging area for content, and deletion is not permitted to maintain data integrity. To resolve this, ensure you're targeting a non-primary environment for deletion. ###### `CANNOT_UPGRADE_MODERN_PLUGIN_INTO_LEGACY` This error occurs when attempting to update an existing modern plugin by setting properties that only make sense for legacy DatoCMS plugins (i.e., `plugin_type`). While it's possible to convert a legacy plugin into a modern one, the opposite is not possible. ###### `CLASHING_FIELD_LABELS` This error occurs when attempting to delete a fieldset, and the fieldset includes a field that carries a label already used by another field at the root level. To resolve this, make sure that all field labels within the fieldset are distinct. ###### `CONCURRENT_ENVIRONMENT_UPDATE` This error happens when you try to modify an environment while another operation is also updating the same environment. To resolve this issue, ensure that no other requests are modifying the targeted environment at the same time, or implement logic to retry the request after a delay. ###### `CONCURRENT_ITEM_TYPE_UPDATE` This error occurs when you try to modify a model or any entity connected to it while validation is in progress. To resolve this, please wait for the current validation to complete before trying your request again. ###### `CONCURRENT_ITEM_UPDATE` This error occurs when an attempt is made to modify a record that is concurrently being updated by another API request. This typically happens when two API requests try to change the same record at the same time. To resolve this, ensure that you implement retry logic in your application, allowing it to gracefully handle such conflicts by retrying the request after a brief wait. ###### `CONCURRENT_ROLE_UPDATE` This error occurs when an attempt is made to modify a role that is concurrently being updated by another API request. This typically happens when two API requests try to change the same role at the same time. To resolve this, ensure you implement retry logic in your application, allowing it to gracefully handle such conflicts by retrying the request after a brief wait. ###### `CONCURRENT_UPLOAD_UPDATE` This error occurs when an attempt is made to modify an upload that is concurrently being updated by another API request. This typically happens when two API requests try to change the same content upload at the same time. To resolve this, ensure that you implement retry logic in your application, allowing it to gracefully handle such conflicts by retrying the request after a brief wait. ###### `DEACTIVATED_SITE` This error happens when an API request tries to change content on a deactivated project. A deactivated project doesn't allow content modifications. To fix this, go to the DatoCMS dashboard and address any pending billing issues. ###### `DELETE_RESTRICTION` This error occurs when an API request attempts to delete a resource, but there's a restriction or constraint that prevents the deletion from happening. Ensure that the content you are trying to delete is not being referenced or constrained by other linked entities. This error is not related to missing user permissions. Check your request for dependencies and remove or update those references before retrying the deletion. ###### `DESTINATION_USER_REQUIRED` This error happens when you try to delete a collaborator or API token that created resources (records/uploads). Make sure the API request specifies a valid destination that will take ownership; otherwise, the operation cannot be completed. ###### `DESTRUCTIVE_REQUEST_BLOCKED` This error occurs when a write request (anything other than `GET` or `HEAD`) is sent with the `X-Abort-If-Destructive-Request` header — typically by DatoCMS's official MCP server in read-only mode. To resolve it, use the unsafe script execution tools instead of the safe ones. ###### `DUPLICATE_POSITIONS_FOUND` This error happens when an API request breaks position rules in a tree-like structure — i.e., fields/fieldsets/menu items/upload collections — often during reordering. To fix this, make sure all positions for entities are unique within their parent context to avoid duplicates. Check your payload before sending the request to prevent conflicts. ###### `DUPLICATE_SINGLETON` This error happens when trying to create a record for a "Single instance" model, but a record of that type already exists in the project. If the model is set as "single instance", check that no other instance exists before performing the request. ###### `EMAIL_NOT_VERIFIED` This error is returned when an action requires the account's email address to be verified, but the verification has not yet been completed. A verification email has been sent (or re-sent) to the address on file. Use the `email_verification_token_sent_at` field in the error details to know when the link was last dispatched, and prompt the user to check their inbox and click the verification link before retrying the operation. ###### `ENVIRONMENT_IN_READ_ONLY_MODE` This error occurs when an attempt to modify content is made while the environment is temporarily in read-only mode due to pending operations (such as an environment fast-fork). To resolve it, ensure that the environment is in a writable state before executing any modification requests. ###### `ENVIRONMENT_NOT_READY` This error occurs when a modification request is made to an environment that is not in a "ready" state. To resolve this, ensure that the environment you’re targeting has transitioned to "ready" status. You can check the current environment's status via the DatoCMS interface or API before making modification requests. ###### `EXCEPTION` This error occurs when DatoCMS encounters an unhandled exception. Should you encounter this error, we kindly ask that you contact our support team. ###### `IMMUTABLE_UPLOAD_TRACKS_IN_SANDBOX_ENVIRONMENT` This error occurs when attempting to modify upload tracks in a non-primary environment. Specifically, it's triggered if the API token's associated account is using a sandbox environment rather than a production environment, which restricts such modifications. To resolve this, ensure that your requests to create or destroy tracks are made in the primary environment. ###### `INCOMPATIBLE_WITH_UPLOAD_STORAGE_SETTINGS` This error occurs when trying to alter the Asset CDN settings for a project that uses Enterprise-level, custom upload storage configurations. If you have custom upload storage, you must manage these settings within your architecture. ###### `INSUFFICIENT_PERMISSIONS` This error occurs when the current API token lacks sufficient permissions to perform the requested action. To resolve this, ensure that the API token being used has the necessary permissions for the attempted operation. ###### `INVALID_ACCEPT_HEADER` This error happens when the API request to modify content doesn't have a valid "Accept" header (`application/json`, `application/vnd.api+json`). Make sure your request includes an "Accept" header that matches the media types required by the API. ###### `INVALID_API_VERSION` This error occurs when the `X-Api-Version` header in your request does not match any supported API version for the current DatoCMS project. Ensure that your API requests specify a valid version (e.g., `1`, `2`, or `3`). ###### `INVALID_ATTRIBUTES` This error occurs when a request to modify content includes attributes that do not match the expected schema for the specified model. Ensure that only valid fields defined in your DatoCMS model are included in the request payload, and double-check for any typos or extraneous data that may have been added inadvertently. ###### `INVALID_AUTHORIZATION_HEADER` This error occurs when the provided API `Authorization` header is invalid or absent during requests to modify content. Ensure that the API token used in the request is valid and properly formatted. ###### `INVALID_CONTENT_TYPE_HEADER` This error occurs when a request to modify content is made without a valid `Content-Type` header. Specifically, it is triggered if the header does not indicate a JSON format, which is required for POST, PUT, or PATCH requests. To resolve this, ensure that your requests contain the `Content-Type` header with `application/json` or `application/vnd.api+json`. ###### `INVALID_DATE` This error occurs when the API receives a date value that does not conform to the expected format, potentially due to an incorrect timezone or an invalid date string. To resolve it, ensure that date values are in ISO 8601 format. ###### `INVALID_DESTINATION_TYPE` This error happens when an API request includes an unrecognized ownership type. To fix this, make sure the specified type is either `user`, `account`, `organization`, `sso_user`, or `access_token`. ###### `INVALID_DESTINATION_USER` This error occurs when you attempt to delete a collaborator or API token while designating an invalid destination for ownership transfer (specifically, the user being deleted). Ensure that the API request indicates a valid destination for ownership; otherwise, the operation cannot be finalized. ###### `INVALID_DRAFT` This error occurs when an API request attempts to publish a draft that fails validation checks. To resolve this issue, ensure that the record meets the content model's validation criteria before attempting the operation. ###### `INVALID_ENDPOINT` This error occurs when an API request is made to an endpoint that does not exist or is not accessible by the current user. Check the URL for typos and confirm that the endpoint is valid for the intended resource type and user permissions to ensure proper access when modifying content. ###### `INVALID_ENTITY_ID` This error occurs when an API request attempts to pass an invalid or improperly formatted ID. Specifically, the entity ID must be a Version 4 UUID formatted in URL-safe base64. Ensure that the ID provided in the request adheres to these specifications to resolve the issue. ###### `INVALID_ENVIRONMENT` This error occurs when an API request attempts to access or modify content within an environment that does not exist or is not accessible by the current API token. Verify that the desired environment is accessible, activated, and ready. Check your authentication and environment identifiers in the request. ###### `INVALID_FIELD` This error occurs when an API request to alter content fails validation, typically due to inconsistencies or absent fields in the payload. Please examine the specifics of the error you received to identify which field is causing the problem. ###### `INVALID_FILTER_FIELDS_PARAM` This error occurs when the API receives invalid filtering parameters. Common triggers include using incorrect field names, unsupported operators, or failing to provide necessary conditions in your query. To resolve the issue, ensure that your filter parameters conform to the expected query structure, including valid field names and proper formatting. ###### `INVALID_FORMAT` This error occurs when the payload of an API request to alter content (POST, PUT, DELETE) fails validation, typically due to an invalid format or absent fields in the payload. To resolve this, please examine the specifics of the error you received to identify which part of the payload is causing the problem. ###### `INVALID_JSON_BODY` This error occurs when the API receives a request containing malformed JSON data. Common triggers include incorrect syntax, missing braces, or non-JSON compliant data types in the request body. Ensure that your JSON is correctly formatted to resolve this issue. ###### `INVALID_ORDERING` This error occurs when the combination of ordering parameters provided in your API request is invalid. Common triggers include specifying both a meta ordering and a field ordering simultaneously, or attempting to set an ordering on "single instance" models. Review your request to ensure that the ordering parameters are correctly configured. ###### `INVALID_ORDERING_FOR_SINGLETON_ITEM_TYPE` This error occurs when attempting to set an ordering field on a single instance model. Single instance models do not support custom ordering. To resolve this issue, ensure that the model is not marked as a single instance before attempting to modify ordering fields. ###### `INVALID_ORDERING_FOR_SORTABLE_ITEM_TYPE` This error occurs when an attempt is made to set an ordering field for a model designated as sortable or tree-like. To resolve this, ensure that the model’s attributes do not include the sortable or tree flags before modifying the ordering. Check the model's configuration and adjust accordingly. ###### `INVALID_PARAMS` This error occurs when the API request includes query string parameters that do not meet the required validation criteria. Review your request for completeness and compliance with the expected structure, and ensure that it adheres to all relevant constraints. ###### `INVALID_PARENT` This error occurs when a request attempts to modify an entity by assigning a parent that creates a circular relationship or exceeds the allowable hierarchy depth. Ensure that the parent entity being assigned is not already a child in the current modification path, and that the nesting limit is respected. ###### `INVALID_PARENT_ID` This error occurs when a request attempts to assign an invalid or nonexistent parent in a record under a tree-like collection. Ensure that the specified parent ID is a valid string referencing an existing record within the project and that it is not identical to the record's own ID, as this creates a circular reference. ###### `INVALID_PLUGIN_VERSION` This error occurs when an API request attempts to update a plugin to a version that is either incorrect or does not exist in the npm registry, typically due to an invalid or malformed version string. Ensure that the given package version is valid and corresponds with available plugin versions in the npm registry to resolve this issue. ###### `INVALID_POSITION` This error occurs when the API request includes an invalid type for the `position` attribute during a record modification, particularly for sortable or tree-structured models. To resolve it, ensure that the `position` field is an integer and meets the required conditions for the target model in your DatoCMS project. ###### `INVALID_RELATIONSHIP` This error occurs when a requested operation violates relationship constraints between entities in DatoCMS. Specifically, it may be triggered if you attempt to associate incorrect entities in a relationship. To resolve this, ensure that relationships between your entities are correctly defined and compatible. ###### `INVALID_REQUEST` This generic error occurs when an API request fails validation due to mismatched required properties in the request payload. ###### `INVALID_SEARCH_INDEX_ID` This error occurs when attempting to search using a `filter[search_index_id]` parameter with a value that does not correspond to any existing search index in your project. The search index ID you provided is either incorrect, the search index may have been deleted, or it is disabled. Please verify that you are using a valid and enabled search index ID from your project's search indexes list. ###### `INVALID_SITE` This error only occurs when an authentication method different from the API token is used in the request and signals that it's not possible to trace the request back to a particular DatoCMS project. This error should not happen if you're using API tokens as the authentication method. ###### `INVALID_SITE_EXPORT_SETTINGS` This error occurs in the context of offline backups, a DatoCMS Enterprise feature. Common triggers include improper values in the backup settings or an invalid adapter type. To resolve this, ensure that all required fields are correctly populated and conform to the expected types. ###### `INVALID_TYPE` This error occurs when attempting to create or update content using an model identifier that doesn't exist within your project's schema. To resolve, verify that the `item_type` relationship in your API request matches a valid model ID from your project's content model. ###### `INVALID_UPLOAD_STORAGE_SETTINGS` This error occurs in the context of custom uploads storage (S3, GCP, etc.), a DatoCMS Enterprise feature. Common triggers include improper values in the custom uploads storage settings or an invalid adapter type. To resolve this, ensure that all required fields are correctly populated and conform to the expected types. ###### `ITEM_LOCKED` This error occurs when attempting to modify a record that is currently locked for editing by another user. It typically arises if a different session holds a lock on the record, preventing concurrent modifications. To resolve this, ensure that the record is unlocked or wait for the user holding the lock to complete their changes before retrying the API request. ###### `ITEM_TYPE_CANNOT_BE_CHANGED` This error occurs when an attempt is made to change the type of an existing record in DatoCMS. Typically, this validation error arises during an update operation where the model specified in the request does not match the current model stored in the system. To resolve this, ensure that the model remains consistent with the defined schema during updates. ###### `ITEM_TYPE_IS_SINGLETON` This error occurs when attempting to modify or duplicate a record of a type designated as "single instance," which means only one record of that model is allowed. To resolve this, ensure you're not trying to create a second record for a model that is defined as "single instance" within your DatoCMS project. ###### `ITEM_TYPE_NOT_FOUND` This error occurs when the specified model in your API request does not match any existing models within the current project. Check that the model ID or API key is correct and that the current user has access to the associated project. ###### `KEEP_URL_CONTENT_TYPE_CONFLICT` This error occurs when attempting to replace an asset with the `keep_url` strategy using a file that has a different MIME type (Content-Type). Even if the file extensions match, the underlying content type must be identical to avoid Content-Type header inconsistencies and ensure proper browser handling. To resolve this error, either: - Use the `create_new_url` strategy to generate a new URL for the new content type - Ensure the replacement file has the exact same MIME type as the original file ###### `KEEP_URL_FORMAT_CONFLICT` This error occurs when attempting to replace an asset with the `keep_url` strategy using a file that has a different format/extension. You cannot replace a `.png` file with a `.jpg` file while keeping the same URL, as this would make the URL misleading about the actual file format and could cause browser compatibility and caching issues. To resolve this error, either: - Use the `create_new_url` strategy to generate a new URL with the correct extension - Ensure the replacement file has the same format/extension as the original file ###### `KEEP_URL_STORAGE_NOT_SUPPORTED` This error occurs when attempting to replace an asset with the `keep_url` strategy while using custom upload storage settings. The `keep_url` strategy is only supported when using DatoCMS's default storage configuration. To resolve this error, either: - Use the `create_new_url` strategy to generate a new URL for the replaced asset - Switch to DatoCMS's default storage settings if you need to use the `keep_url` strategy ###### `KIND_CANNOT_BE_CHANGED` This error occurs when an attempt is made to modify the "kind" of an existing schema menu item within DatoCMS. This validation ensures that the record retains its original structure, which is crucial for maintaining data integrity across the content management system. To resolve this, ensure that the "kind" attribute is not modified in your API request. ###### `MAINTENANCE_MODE` This error occurs when the current site's primary environment is under maintenance, preventing any modification requests. To resolve this issue, confirm that maintenance mode is disabled for the project or coordinate with platform admins to schedule necessary updates outside maintenance periods. ###### `MISSING_FIELDS` This error occurs when a request to create a record lacks some required fields. To resolve this, inspect the details of the error to understand which fields are missing, and ensure that your API request includes all mandatory fields. ###### `MISSING_LOCALES` This error occurs when a request to create a record containing localized fields does not specify a value for any locale at all. To resolve this, ensure that you provide at least one value for one of the environment locales for each of the localized fields of the model. ###### `MISSING_QUERY_PARAMETER` This error occurs when a Site Search does not include the required `filter[query]` query string parameter with the actual search term. To resolve this, ensure that the client request includes this parameter with a valid value. ###### `MODULAR_BLOCK_IN_USE` This error occurs when an attempt is made to delete a block model that is currently in use by one or more structured text or modular content fields within the environment. To resolve this, ensure that the block is not referenced by any field before executing deletions. ###### `MUX_ERROR` This error occurs when an operation regarding video uploads is attempted through the API, but Mux is unable to process it. To resolve this issue, please inspect the details of the error message provided for more specific information about what went wrong. ###### `NEW_PLUGIN_VERSION_IS_INCOMPATIBLE` This error occurs when a request attempts to upgrade a legacy plugin with different settings for either the plugin type, field types in which it can operate, or the settings that the plugin offers. Review your API request payload for discrepancies to resolve the issue. ###### `NON_EDITABLE_ACCESS_TOKEN` This error occurs when attempting to modify or delete a non-editable API token for the project — either the Full-access API token or the Read-only API token. To resolve this, ensure that you are not trying to modify or delete such tokens. ###### `NOT_A_VIDEO` This error occurs when an API request attempts to add a track — either an additional audio track or a subtitle — to an upload that is not classified as a video. Ensure that the upload you're working with is a valid video file to resolve this issue. ###### `NOT_FOUND` This error occurs when an API request attempts to access a resource that is not present in the system. Common triggers for this issue include specifying an invalid ID in your request. To resolve this, verify the entity ID and ensure that the API token has the necessary permissions to access it. ###### `NOT_ON_PER_SITE_PRICING` This error occurs when attempting to read entities that are only available in a DatoCMS project under the legacy per-project pricing. To resolve it, ensure that the current account or organization that owns the project has subscribed to a per-project pricing plan. ###### `NO_PRIMARY_AUDIO_TRACK` This error occurs when an attempt is made to generate automatic subtitles on uploads that lack a designated primary audio track. To resolve the issue, ensure that the upload associated with your request includes a valid primary audio track before proceeding with the operation. ###### `PLAN_UPGRADE_REQUIRED` This error occurs when a request attempts to exceed the limits defined by the current subscription plan for workflows, upload sizes, or similar features. To resolve this, review your account's plan details and consider upgrading if you need access to additional resources or functionality. ###### `PLATFORM_SCHEDULED_MAINTENANCE` This error arises when an API request is submitted during scheduled maintenance. During such maintenance, all DatoCMS projects become read-only. To address this issue, please check the status of the scheduled maintenance at [https://status.datocms.com](https://status.datocms.com/) ###### `PLUGIN_NOT_FOUND_IN_MARKETPLACE` This error occurs when trying to turn a private plugin into a public one by setting `package_name` to a package that is not published in the DatoCMS Marketplace. Make sure the package name is correct and that the plugin has actually been published to the Marketplace. ###### `PRIMARY_ENVIRONMENT_SETTINGS_READ_ONLY` This error occurs if the "Force the use of sandbox environments" setting is activated for a DatoCMS project and an attempt is made to change the primary environment settings – including changes to its content schema and role permission rules regarding the environment. To resolve this issue, either disable the "Force the use of sandbox environments" flag or ensure that your API request targets a sandbox environment. ###### `PUBLISHED_CHILDREN` This error occurs when attempting to unpublish a record in a tree-structured collection that has one or more published child records. To resolve it, either ensure that all published children are unpublished before performing the unpublish action on the parent record, or pass the `recursive=true` query string parameter to the request. ###### `PUBLISHED_REFERENCES` This error occurs when attempting to unpublish a record that is currently referenced by one or more published records. To resolve it, either change the `on_reference_unpublish_strategy` of the fields that are referencing the record to `delete_references` or `unpublish`, manually remove the references from the published records, or manually unpublish the records that reference this record as well. You can inspect the error message for more details on which specific records are causing the issue. The error `details` contain: - `referencing`: the record that is actually blocked from being unpublished (a `{ item_id, item_type_id }` pair). This is not necessarily the record you requested to unpublish: unpublishing a record can cascade into other records (for example through fields whose `on_reference_unpublish_strategy` is `unpublish`), and the failure may surface deeper in that cascade. - `items`: the published records that reference `referencing` with a `fail` strategy. - `cascade_path_item_references`: the cascade path, as an array of `{ item_id, item_type_id }` pairs, from the record you requested to unpublish down to `referencing` (the last element always equals `referencing`). When no cascade took place, it contains a single element equal to `referencing`. Only top-level records appear in the chain — nested blocks are never included. ###### `RATE_LIMIT_EXCEEDED` This error occurs when making a request to the API, but the number of requests exceeds the allowed limit within a specified time frame. To resolve the issue, ensure that your application throttles requests, waiting for the `X-RateLimit-Reset` period before retrying. Monitor your request volume and optimize where necessary to avoid triggering this limit. ###### `REQUIRED_BY_ASSOCIATION` This error occurs when you attempt to delete a record that is currently referenced by another record. To resolve this, either change the `on_reference_delete_strategy` of the fields that are referencing the record to `delete_references`, or ensure that no record relies on this record before deleting it, and consider removing those references first. ###### `SERVICE_UNAVAILABLE` This error occurs when our servers are temporarily unable to handle your request. This could be due to planned or unplanned maintenance, a system upgrade, or a server failure. These errors can also be returned during periods of high traffic. We suggest monitoring the API status at [https://status.datocms.com](https://status.datocms.com/) for ongoing issues that may affect service availability. ###### `SITE_NOT_READY` This error occurs when an API request attempts to access or modify content within a project that is not yet accessible, as it's still being finalized. Verify that the desired project is accessible, activated, and ready. ###### `SSO_SETTINGS_REQUIRED` This error occurs in the context of the Single-Sign On enterprise feature of DatoCMS, specifically when the API attempts to perform some operation but the SSO settings have not yet been configured. Ensure that Single Sign-On is enabled and its settings are properly set for the current project before making this request. ###### `STALE_ITEM_VERSION` This error occurs when an attempt is made to update a record that has already been modified since it was last read. To resolve the issue, ensure that you're working with the latest record version by re-fetching the record before making updates, and verify that the current version matches the expected value in your request payload. ###### `TECHNICAL_LIMIT_REACHED` This error occurs when you attempt to create new entities in your DatoCMS project but have exceeded allowed limits based on your current API token's subscription plan. It may happen if the content's byte size is too large, the number of blocks within a record exceeds the maximum, or if blocks are nested beyond permitted levels. To resolve it, inspect the error and find which limit is triggering the error, then check your subscription's limits and adjust your API request accordingly. ###### `TOO_MANY_OPERATIONS` This error occurs when an API request exceeds the maximum allowed number of batch operations. To resolve it, ensure that the number of operations in your batch does not exceed the limit of 200. ###### `UNMANAGED_EDIT_CONFLICT` This error typically arises when the current API token attempts to lock a record for editing, but another user has already locked it. To solve this issue, wait a few minutes and retry your request. ###### `UNPUBLISHED_LINK` This error occurs when an attempt is made to publish a record that references other unpublished records. To resolve it, either change the `on_publish_with_unpublished_references_strategy` of the fields that are referencing the record to `publish_references`, manually remove the references from the record, or manually publish the referenced records as well. You can inspect the error message for more details on which specific records are causing the issue. The error `details` contain: - `referenced_from`: the record that is actually blocked from being published (a `{ item_id, item_type_id }` pair). This is not necessarily the record you requested to publish: publishing a record can cascade into other records (for example through fields whose `on_publish_with_unpublished_references_strategy` is `publish_references`, or through unpublished tree parents), and the failure may surface deeper in that cascade. - `items`: the unpublished records that `referenced_from` links to with a `fail` strategy. - `cascade_path_item_references`: the cascade path, as an array of `{ item_id, item_type_id }` pairs, from the record you requested to publish down to `referenced_from` (the last element always equals `referenced_from`). When no cascade took place, it contains a single element equal to `referenced_from`. Only top-level records appear in the chain — nested blocks are represented by their top-level container. ###### `UNPUBLISHED_PARENT` This error occurs when attempting to publish a record that has one or more parent records that are not yet published. Ensure that all parent records are successfully published before trying to publish the intended record. Check the details of the error and record's hierarchy to find the records that need to be published first. ###### `UNRESOLVABLE_SEARCH_INDEX` This error occurs when attempting to search but no valid search index could be found. Either provide a valid `filter[search_index_id]` parameter to specify which search index to use, or ensure that at least one enabled search index exists in your project. ###### `UPLOAD_IS_CURRENTLY_IN_USE` This error occurs when you attempt to delete an upload that is currently in use by one or more records in your DatoCMS project. To resolve this, first check which records are referencing the upload by looking at the error details. Ensure that all references are removed before re-attempting the deletion. ###### `UPLOAD_NOT_PASSING_FIELD_VALIDATIONS` This error occurs when an upload is currently referenced by one or more records, and the change requested to the upload fails to meet the field validations in place for those records. To resolve this issue, you should review the validation rules for your content model. ###### `USED_AS_SLUG_SOURCE` This error occurs when attempting to modify a field that a slug field depends on. To resolve it, identify the related slug in the details of the error, and either remove it or adjust its requirement before making the desired changes to the field. ###### `USE_SEARCH_INDEX_ID_INSTEAD_OF_BUILD_TRIGGER_ID` This error occurs when attempting to search using `filter[build_trigger_id]` parameter on a build trigger that has multiple search indexes associated with it. Since the `build_trigger_id` parameter is ambiguous in this case, you must use the `filter[search_index_id]` parameter instead to explicitly specify which search index to query. --- # Content Management API — Pagination Source [docs]: https://www.datocms.com/docs/content-management-api/pagination.md When it comes to obtaining complete lists of entities exposed by the API, a distinction needs to be made. Some entities (i.e. models) can be retrieved all at once with a single API call, while others (i.e. records), are returned by the API in the form of pages. In the latter case, the response will contain the total number of resources in the `meta.total_count` property: ```json { "data": [...], "meta": { "total_count": 140 } } ``` The pagination that the API offers is offset-based: this means that you can control the results that are returned with the parameters `page[limit]` and `page[offset]`: - `page[limit]` is the maximum number of entities to be returned - `page[offset]` is the (zero-based) offset of the first entity returned in the collection (always defaults to 0) > [!NOTE] Page limit and maximum values vary by endpoint > Both the default value of `page[limit]` and its maximum (that is, the maximum number of items that can be asked per page) vary depending on the specific endpoint. To obtain this information, refer to the specific documentation for the endpoint's `page` query parameter. Setting a `page[limit]=5` and `page[offset]=5` will return entities 6 through 10: Terminal window ```bash curl \ -H 'Accept: application/json' \ -H 'Authentication: Bearer ' \ https://site-api.datocms.com/items?page[limit]=5&page[offset]=5 ``` ## Handling pagination with our JavaScript client Our [JavaScript client](/docs/content-management-api/using-the-nodejs-clients.md) makes the `list()` method available for fetching collections of entities. As we have seen, depending on the endpoint, the result may contain all the entities in the collection, or just one page. ```javascript // Returns all the models const itemTypes = await client.itemTypes.list(); // Returns a single page of records const items = await client.items.list(); ``` In the case of a paginated endpoint, you can configure the pagination with `page.limit` and `page.offset`: ```javascript // Returns the first 10 records await client.items.list({ page: { limit: 10 } }); // Returns records 6 through 10 await client.items.list({ page: { limit: 5, offset: 5 } }); ``` ### Paged iterators In the case of paginated entities, the client also provides the `listPagedIterator()` method, which allows for fetching all the pages of the collection in a simplified manner, without manually handling offset-based pagination. You can use this method in an [async iteration statement](https://github.com/tc39/proposal-async-iteration#the-async-iteration-statement-for-await-of): ```javascript // We'll be building up an array of all records using an AsyncIterator const allRecords = []; for await ( const record of client.items.listPagedIterator( // You can define any query parameter that the endpoint permits, // except for page (refer to the following example for clarification) { filter: { type: "article" } } ) ) { allRecords.push(record); } console.log(allRecords); ``` The method `listPagedIterator()` offers a few options to configure its behavior: - The `concurrency` option determines how many API calls can be performed in parallel (up to a maximum of 10). The default setting is 1, implying that the calls are made sequentially, not in parallel. - The `perPage` option specifies the size of the pages in the sub-requests that it will carry out in the background. ```javascript for await ( const record of client.items.listPagedIterator( // You can define any query parameter that the endpoint permits, // except for page { filter: { type: "article" } }, // Pagination options { concurrency: 5, perPage: 100 }, ) ) { // ... } ``` ## Manually retrieving the total count of a query result Normally, our [`listPagedIterator`](/docs/content-management-api/pagination.md#paged-iterators) handles pagination for you, but if you need to retrieve the total count of a query, you can use the `rawList()` command to access the response's `meta.total_count` property. In this example, we query records (`items`) of a certain model type (`page`) using `rawList()` with a filter, and then access `meta.total_count` for the total. ```javascript const records = await client.items.rawList({ filter: { type: 'page' // API key (that you gave it) or ID (from its URL) }, page: { limit: 0 // We don't need any actual records, just the meta } }) console.log(records.meta.total_count) // Returns `11` ``` --- # Content Management API — Asynchronous jobs Source [docs]: https://www.datocms.com/docs/content-management-api/async-jobs.md For some endpoints whose tasks are potentially time-consuming (e.g., [updating a Model](/docs/content-management-api/resources/item-type/update.md)), the API does not return a `200 OK` status code. Instead, a `202 Accepted` status code is returned, and an [asynchronous job](/docs/content-management-api/resources/job.md) starts in the background, which will complete shortly. The payload of a `202 Accepted` response contains the ID of the asynchronous job that started: ```http PUT https://site-api.datocms.com/item-types/:model_id_or_api_key HTTP/1.1 X-Api-Version: 3 Authorization: Bearer YOUR-API-TOKEN Accept: application/json Content-Type: application/json { ... } HTTP/1.1 202 Accepted Content-Type: application/json { "data": { "type": "job", "id": "4235" } } ``` To get the result of of the asynchronous job, you need to poll the [Job result](/docs/content-management-api/resources/job-result/self.md) endpoint. As long as the task is in progress, the endpoint will return a `404 Not found` status code. As soon as the job completes, the status will change to `200 OK`: ```http GET https://site-api.datocms.com/job-results/:job_result_id HTTP/1.1 X-Api-Version: 3 Authorization: Bearer YOUR-API-TOKEN Accept: application/json HTTP/1.1 200 OK Content-Type: application/json { "data": { "type": "job_result", "id": "34", "attributes": { "status": 200, "payload": { "data": { ... } } } } } ``` In the payload of the response you'll find both the status code and the payload of the original request you performed. #### Important: all endpoints could return async jobs in the future! If you are using our Content Management API directly, without any of our official clients, **you need to make sure to treat all endpoints as they might return an asynchronous job**. This is a fundamental constraint of using our Content Management API. In the event that an endpoint needs to be optimized, we want to leave ourselves the ability to return an asynchronous job without having to release a new API version. If you are implementing a custom client yourself, the easiest way to proceed is to **wrap every request you make to our API to a common logic** that checks if the response is a job, and if so, it polls for its result before returning anything to the caller. > [!POSITIVE] Official clients and async jobs > If you are using our [Javascript client](/docs/content-management-api/using-the-nodejs-clients.md), the whole async job concept is completely invisible. Everything is handled in the client itself, and the API methods return a `Promise` that resolves with the final result of the asynchronous job — or throw an exception if the job status code is different than `2xx`. --- # Content Management API — CMA Technical Limits & Rate Limits Source [docs]: https://www.datocms.com/docs/content-management-api/technical-limits.md > [!NOTE] Content Management API (REST) Only > These limits only apply to the Content Management API, our read/write REST API. > > For other API limits, please see: > > - [CDA Technical Limits & Rate Limits](/docs/content-delivery-api/technical-limits.md) > > - [Real-time Updates API Limits & Pricing](/docs/real-time-updates-api/limits-and-pricing.md) Our shared-service infrastructure is built to maintain steady performance for every customer, thanks to carefully set technical limits. If any API call or CMS action goes over these boundaries, it'll trigger an error message. Should your project require higher limits, [get in touch with us](https://www.datocms.com/support.md) to discuss further. ## CMA Technical Limits: Per-project and projectwide Here are the technical limits currently in place for the CMA: - **Per-record limits (**[**read more**](/docs/content-modelling/record-block-limits-and-byte-size-limits.md)**):** - **Maximum Record size**: 300 KB, including content in nested blocks (assets and linked records do not count toward the limit). - **Number of blocks per record**: 500 - **Maximum depth for nested blocks**: 5 levels - **Number of concurrent editors per record**: 1 (with presence indicator and record locking, [read more](/docs/general-concepts/collaboration-features.md)) - **Project-wide limits:** - **Assets upload**: Max size of 1 GB per asset - **Plugin global user-defined settings**: Max size of 10KB per plugin ([read more](/docs/plugin-sdk/field-extensions.md#adding-user-defined-settings-into-the-mix)) - **Plugin field extension user-defined settings**: Max size of 10KB per field ([read more](/docs/plugin-sdk/field-extensions.md#adding-user-defined-settings-into-the-mix)) ## CMA Rate Limits The Content Management API is limited to **60 requests every 3 seconds**. ### **CMA Rate Limit Examples** 1. You make **80 requests** at once and hit the limit immediately. The last 20 requests are rejected with a `429`. You should retry again after `x-ratelimit-reset: 3` seconds. 2. You sustain **30 requests/second**. You will hit the limit in 2 seconds. The last 30 requests are rejected with a `429`. You should retry again after `x-ratelimit-reset: 1` second. 3. You sustain **20 requests/second** and stay under the limit. Well done! > [!POSITIVE] Official clients and rate limits > Our [Javascript client](/docs/content-management-api/using-the-nodejs-clients.md) already manages rate limit errors for you with a retry mechanism! If it encounters a `429` status code, the promise won't be rejected. The client will repeat the requests until the API stops returning `429` status codes, and only then will the promise will be resolved with success. > [!WARNING] 429 Status Responses in DatoCMS Shared Infrastructure > Even when you are operating within your rate limits, there is a possibility of encountering a 429 status code in situations of high system load if your project is hosted on the DatoCMS shared infrastructure or medium-density infrastructure. > > Nevertheless, it's essential to acknowledge that this occurrence is rare, and our official clients are equipped with an automatic retry mechanism to seamlessly handle such situations. ### **HTTP Headers for CMA Rate Limit** Every CMA response will include these HTTP headers to help you stay within the rate limit: - `x-ratelimit-limit`: The number of requests you can make every 3 seconds (usually 60) - `x-ratelimit-remaining`: The number of *remaining* requests you can still make before the next refill Exceeding the CMA rate limit will cause the HTTP status code to become `429 Too Many Requests`, and an additional header will be added: - `x-ratelimit-reset`: Number of seconds until the next refill (only appears when rate-limited) ## Reaching your plan monthly API calls limit Every DatoCMS plan offers a number of API requests per month. What happens you exceed the included quota? - If your project is under a free plan, API responses will be temporarily disabled until the beginning of the following calendar month, unless you switch to a paid plan. - If your project is under a paid plan, you will pay an additional cost for the additional usage you made of the API. For more details, check our [Plans, billing and pricing page](/docs/plans-pricing-and-billing.md). --- # Content Management API — Record Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item.md DatoCMS stores the individual pieces of content you create from a model as records (for backwards compatibility the API calls these `item`). The shape of a record’s attributes depends on the fields defined by that record’s model — see the [Object payload](/docs/content-management-api/resources/item.md#object-payload) section for the full object payload documentation. ```json // A simple record { "id": "A4gkL_8pTZmcyJ-IlIEd2w", "type": "item", "attributes": { "title": "My Blog Post", "publication_date": "2024-01-15" }, "relationships": { "item_type": { "data": { "id": "BxZ9Y2aKQVeTnM4hP8wLpD", "type": "item_type" } } } } ``` > [!PROTIP] 📘 New to content modeling? > Check out the [Content Modeling Guide](/docs/content-modelling.md) to understand how to design models, fields, and relationships before diving into API usage. --- ## Field types overview ###### Scalar fields These store basic data types (ie. strings, numbers, booleans):
Single-line string The field accepts `String` values or `null`.
Slug The field accepts `String` values or `null`.
Multi-line text The field accepts simple `String` values (can include newlines) or `null`
Boolean The field accepts simple `Boolean` values or `null`.
Integer The field accepts simple `Integer` values or `null`.
Float The field accepts simple `Float` values or `null`.
Date The field accepts `String` values in ISO 8601 date format (ie. `"2015-12-29"`) or `null`.
Date time The field accepts `String` values in ISO 8601 date-time format (ie. `"2020-04-17T16:34:31.981+01:00"`) or `null`. If you're on [legacy timezone management](https://www.datocms.com/product-updates/improved-timezone-management.md), remember that when sending an ISO8601 datetime you should keep in mind that the system will ignore any provided timezone, and will use the project's timezone instead.
JSON The field accepts `String` values that are valid JSON or `null`. **Note**: Must be a JSON-serialized string, not a JavaScript object!
###### Object Fields These require structured objects:
Color The field accepts an object with the following properties, or `null`: | Property | Required | Type | | --- | --- | --- | | `red` | ✅ | `Integer` between 0 and 255 | | `green` | ✅ | `Integer` between 0 and 255 | | `blue` | ✅ | `Integer` between 0 and 255 | | `alpha` | ✅ | `Integer` between 0 and 255 |
Location The field accepts an object with the following properties, or `null`: | Property | Required | Type | | --- | --- | --- | | `latitude` | ✅ | `Float` between -90.0 to 90 | | `longitude` | ✅ | `Float` between -180.0 to 180 |
SEO The field accepts an object with the following properties, or `null`: | Property | Required | Type | Description | | --- | --- | --- | --- | | `title` | | `String` | Title meta tag (max. 320 characters) | | `description` | | `String` | Description meta tag (max. 320 characters) | | `image` | | `Upload ID` | Asset to be used for social shares | | `twitter_card` | | `"summary"`, `"summary_large_image"` | Type of Twitter card to use | | `no_index` | | `Boolean` | Whether the noindex meta tag should be returned |
External video The field accepts an object with the following properties, or `null`: | Property | Required | Type | Description | Example | | --- | --- | --- | --- | --- | | `provider` | ✅ | `"youtube"`, `"vimeo"`, `"facebook"` | External video provider | `"youtube"` | | `provider_uid` | ✅ | `String` | Unique identifier of the video within the provider | `"vUdGBEb1i9g"` | | `url` | ✅ | `URL` | URL of the video | `"https://www.youtube.com/watch?v=qJhobECFQYk"` | | `width` | ✅ | `Integer` | Video width | `459` | | `height` | ✅ | `Integer` | Video height | `344` | | `thumbnail_url` | ✅ | `URL` | URL for the video thumb | `"https://i.ytimg.com/vi/vUdGBEb1i9g/hqdefault.jpg"` | | `title` | ✅ | `String` | Title of the video | `"Next.js Conf Booth Welcoming!"` |
###### Reference Fields These point to other resources (either assets or other records):
Single-asset The field accepts an object with the following properties, or `null`: | Property | Required | Type | Description | Example | | --- | --- | --- | --- | --- | | `upload_id` | ✅ | `Upload ID` | ID of an asset | `"dhVR2HqgRVCTGFi0bWqLqA"` | | `title` | | `String` | Title for the asset, if you want to override the asset's default value (see Upload `default_field_metadata`) | `"From my trip to Italy"` | | `alt` | | `String` | Alternate text for the asset, if you want to override the asset's default value (see Upload `default_field_metadata`) | `"Florence skyline"` | | `focal_point` | | `{ x: Float, y: Float }`, `null` | Focal point for the asset, if you want to override the asset's default value (see Upload `default_field_metadata`). Values must be expressed as `Float` between 0 and 1. Focal point can only be specified for image assets. | `{ "x": 0.34, "y": 0.45 }` | | `poster_time` | | `Float`, `null` | Time (in seconds) into the video used to generate the thumbnail, if you want to override the asset's default value (see Upload `default_field_metadata`). Poster time can only be specified for video assets. | `12.5` | | `custom_data` | | `Record` | An object containing custom keys that you can use on your frontend projects | `{ "watermark_image": "true" }` | **API responses**: Always returns asset ID only (use separate asset API for details)
Asset gallery This field accepts an `Array` of objects with the following properties, or `null`: | Property | Required | Type | Description | Example | | --- | --- | --- | --- | --- | | `upload_id` | ✅ | `Upload ID` | ID of an asset | `"dhVR2HqgRVCTGFi0bWqLqA"` | | `title` | | `String` | Title for the asset, if you want to override the asset's default value (see Upload `default_field_metadata`) | `"Gallery Image Title"` | | `alt` | | `String` | Alternate text for the asset, if you want to override the asset's default value (see Upload `default_field_metadata`) | `"Gallery image description"` | | `focal_point` | | `{ x: Float, y: Float }`, `null` | Focal point for the asset, if you want to override the asset's default value (see Upload `default_field_metadata`). Values must be expressed as `Float` between 0 and 1. Focal point can only be specified for image assets. | `{ "x": 0.34, "y": 0.45 }` | | `poster_time` | | `Float`, `null` | Time (in seconds) into the video used to generate the thumbnail, if you want to override the asset's default value (see Upload `default_field_metadata`). Poster time can only be specified for video assets. | `12.5` | | `custom_data` | | `Record` | An object containing custom keys that you can use on your frontend projects | `{ "watermark_image": "true" }` | **API responses**: Always returns array of asset IDs only
Single link This field accepts a `String` representing the ID of the linked record, or `null`. See [Link Fields Guide](/docs/content-modelling/links.md) for relationship modeling concepts. **API responses**: Always returns record ID only
Multiple links This field accepts an `Array` representing the IDs of the linked records, or `null`. See [Link Fields Guide](/docs/content-modelling/links.md) for relationship modeling concepts. **API responses**: Always returns array of record IDs only
###### Block Fields These are special fields that contain **blocks within records**: | Field Type | What it contains | | --- | --- | | **Modular content** | An array of blocks, perfect for building dynamic page sections | | **Single block** | A single block instance or `null` | | **Structured text** | A rich text document that can have blocks embedded within the flow of content ([DAST format](/docs/structured-text/dast.md)) | Blocks are **records within records** - they're separate items that live inside fields of other records. > [!PROTIP] 📚 Content Modeling Context > To understand when and how to design blocks vs models, see [Blocks Guide](/docs/content-modelling/blocks.md). For field-specific concepts, see [Modular Content](/docs/content-modelling/modular-content.md) and [Structured Text](/docs/content-modelling/structured-text.md). Blocks inside those fields are unique because they can be represented in two different ways depending on the context: as a lightweight reference (an ID) or as a full content object. Understanding this duality is key to working with them effectively: - **Block ID (Lightweight Reference)**: A simple `String` that uniquely identifies the block (ie. `"dhVR2HqgRVCTGFi_0bWqLqA"`). This is useful when you only need to know *which* block is there, not what's inside it. - **Block Object (Full Content)**: The complete record object for the block, containing its own `id`, `type`, `attributes`, and `relationships`. This is used when you need to read or modify the block's actual content. ```json { "id": "dhVR2HqgRVCTGFi_0bWqLqA", "type": "item", "attributes": { "title": "Block Title", "content": "Block content..." }, "relationships": { "item_type": { "data": { "id": "BxZ9Y2aKQVeTnM4hP8wLpD", "type": "item_type" } } } } ```
Modular Content A Modular Content field holds an array of blocks. **As an array of IDs:** ```json { "content_blocks": [ "dhVR2HqgRVCTGFi_0bWqLqA", "kL9mN3pQrStUvWxYzAbCdE" ] } ``` **As an array of full objects:** ```json { "content_blocks": [ { "id": "dhVR2HqgRVCTGFi_0bWqLqA", "type": "item", "attributes": { "title": "Hero Section", "content": "Welcome to our site" }, "relationships": { "item_type": { "data": { "id": "...", "type": "item_type" } } } }, { "id": "kL9mN3pQrStUvWxYzAbCdE", "type": "item", "attributes": { "title": "Image Gallery", "images": [...] }, "relationships": { "item_type": { "data": { "id": "...", "type": "item_type" } } } } ] } ```
Single Block A Single Block field holds exactly one block, or `null`. **As an ID:** ```json { "featured_block": "dhVR2HqgRVCTGFi_0bWqLqA" } ``` **As an full object:** ```json { "featured_block": { "id": "dhVR2HqgRVCTGFi_0bWqLqA", "type": "item", "attributes": { "title": "Featured Content", "summary": "A summary..." }, "relationships": { "item_type": { "data": { "id": "...", "type": "item_type" } } } } } ```
Structured Text A Structured Text field can contain blocks within its document structure ([DAST format](/docs/structured-text/dast.md)). The item property of a `block` or `inlineBlock` node will hold either the ID or the full object. **With block IDs:** ```json { "rich_text_content": { "schema": "dast", "document": { "type": "root", "children": [ { "type": "paragraph", "children": [{ "type": "span", "value": "Text before block." }] }, { "type": "block", "item": "dhVR2HqgRVCTGFi_0bWqLqA" } ] } } } ``` **With full objects:** ```json { "rich_text_content": { "schema": "dast", "document": { "type": "root", "children": [ { "type": "paragraph", "children": [{ "type": "span", "value": "Text before block." }] }, { "type": "block", "item": { "id": "dhVR2HqgRVCTGFi_0bWqLqA", "type": "item", "attributes": { "title": "Embedded Block", "content": "..." }, "relationships": { "item_type": { "data": { "id": "...", "type": "item_type" } } } } } ] } } } ```
--- ## API response modes: Regular vs. Nested When fetching record data, the API gives you control over how block fields are represented in the response. These two modes, **Regular** and **Nested**, are available on the following endpoints: - [Retrieve a single record (`GET /items/:id`)](/docs/content-management-api/resources/item/self.md) - [Retrieve multiple records (`GET /items`)](/docs/content-management-api/resources/item/instances.md) - [Retrieve records referenced by a record (`GET /items/:id/references`)](/docs/content-management-api/resources/item/references.md) - [Retrieve records linked to an asset (`GET /upload/:id/references`)](/docs/content-management-api/resources/upload/references.md) ###### Regular mode (default) By default, the API returns block fields as IDs only. This is efficient and fast, making it ideal for listings or when you don't need the blocks' content immediately. ```json GET /items/A4gkL_8pTZmcyJ-IlIEd2w { "id": "A4gkL_8pTZmcyJ-IlIEd2w", "type": "item", "attributes": { "title": "My Blog Post", "content_blocks": ["dhVR2HqgRVCTGFi_0bWqLqA", "kL9mN3pQrStUvWxYzAbCdE"], "featured_block": "nZ8xY2vWqTuJkL3mNcBeFg" } } ``` ###### Nested mode (`?nested=true`) The same endpoint, when passing the `?nested=true` option, returns **block fields as full objects**. This is essential when you need to display or edit the content within the blocks. ```json GET /items/A4gkL_8pTZmcyJ-IlIEd2w?nested=true { "id": "A4gkL_8pTZmcyJ-IlIEd2w", "type": "item", "attributes": { "title": "My Blog Post", "content_blocks": [ { "id": "dhVR2HqgRVCTGFi_0bWqLqA", "type": "item", "attributes": { "title": "Hero Section", "content": "Welcome to our site" }, "relationships": { ... } }, { "id": "kL9mN3pQrStUvWxYzAbCdE", "type": "item", "attributes": { "title": "Image Gallery", "images": [...] }, "relationships": { ... } } ], "featured_block": { "id": "nZ8xY2vWqTuJkL3mNcBeFg", "type": "item", "attributes": { ... }, "relationships": { ... } } } } ``` > [!WARNING] Block Fields vs. Other Reference Fields > Block fields are the **only** field type that change representation between modes! Asset and link fields always return IDs. To get full details for assets or linked records, you need to make separate API calls using their IDs. ###### When to use each mode? | Use "Regular Mode" when... | Use "Nested Mode" when... | | --- | --- | | Listing many records or building navigation. | Displaying or editing block content, as it provides the actual content needed. | | You only need to know which blocks exist. | You need to read the actual block content for display or updates. | | Building navigation | Preparing to update blocks | | Performance is critical; it's faster because it returns smaller responses (block IDs instead of full content). | You are building content editing interfaces where usability is more important than raw speed. | --- ## Creating and updating blocks Working with blocks follows one fundamental constraint: **You cannot create, edit, or delete blocks directly. You must always update the parent record that contains them.** This ensures data integrity. To create/modify blocks, you send a payload to the parent record's endpoint, using a mix of Block IDs and Block Objects to describe the desired changes. ###### Key rules for block operations 1. **To create a new block**: Provide the **full object**, including `type`, `attributes`, and the `relationships.item_type` which specifies the Block Model being used. 2. **To update an existing block**: Provide the **full object**, including its `id` and the changed `attributes`. You only need to include the specific attributes that you want to change - unchanged attributes will be preserved. You don't need to specify `relationships.item_type`. 3. **To keep an existing block unchanged**: Simply provide its **Block ID** string. This is the most efficient way to handle unchanged blocks. 4. **To delete a block**: Omit it from the payload. For a Modular Content array, remove its ID. For a Single Block field, set the value to `null`. 5. **To reorder blocks** (in Modular Content): Send an array of Block IDs in the new desired order. > [!PROTIP] 🆔 Custom block IDs > Any new block payload (on create or update) may optionally include an `id` (an RFC 4122 v4 UUID expressed in URL-safe base64). If provided, that value becomes the new block's ID; otherwise the server generates one. On **update**, the `id` is interpreted as follows: if it matches a block already in the parent record, that block is updated; otherwise — provided the `id` is a valid v4-base64 UUID and not yet used by any record in the environment — a new block is created with that ID. An `id` that resolves to a record outside the parent, or is not a valid v4-base64 UUID, is rejected. The following examples show how to apply these rules.
Working with Modular Content Fields **Current state** (from a regular API response): ```json { "content_blocks": ["dhVR2HqgRVCTGFi_0bWqLqA", "kL9mN3pQrStUvWxYzAbCdE", "fG8hI1jKlMnOpQrStUvWxY"] } ``` **To update the second block and reorder the others:** ```json { "content_blocks": [ "fG8hI1jKlMnOpQrStUvWxY", // Reordered: kept as ID { "id": "kL9mN3pQrStUvWxYzAbCdE", // Updated: sent as object "type": "item", "attributes": { "title": "Updated Title" } }, "dhVR2HqgRVCTGFi_0bWqLqA" // Reordered: kept as ID ] } ``` **To add a new block at the end and remove the first block:** ```json { "content_blocks": [ "kL9mN3pQrStUvWxYzAbCdE", // Kept as ID "fG8hI1jKlMnOpQrStUvWxY", // Kept as ID { "type": "item", // New block: sent as object with relationships "attributes": { "title": "A Brand New Block" }, "relationships": { "item_type": { "data": { "id": "BxZ9Y2aKQVeTnM4hP8wLpD", "type": "item_type" } } } } ] } ```
Working with Single Block Fields **Current state** (from a regular API response): ```json { "hero_block": "dhVR2HqgRVCTGFi_0bWqLqA" } ``` **To update the block's content:** ```json { "hero_block": { "id": "dhVR2HqgRVCTGFi_0bWqLqA", "type": "item", "attributes": { "title": "Updated Hero Title" } } } ``` **To replace it with a new block:** ```json { "hero_block": { "type": "item", "attributes": { "title": "New Hero Block" }, "relationships": { "item_type": { "data": { "id": "BxZ9Y2aKQVeTnM4hP8wLpD", "type": "item_type" } } } } } ``` **To remove (delete) the block:** ```json { "hero_block": null } ```
Working with Structured Text Fields Updating blocks within Structured Text follows the same pattern: you replace the `item`'s ID with a full object for the block you want to change. **Current state** (from a regular API response): ```json { "rich_content": { "schema": "dast", "document": { "type": "root", "children": [ { "type": "block", "item": "dhVR2HqgRVCTGFi_0bWqLqA" }, { "type": "paragraph", "children": [{ "type": "span", "value": "Some text." }] } ] } } } ``` **To update the block's content:** ```json { "rich_content": { "schema": "dast", "document": { "type": "root", "children": [ { "type": "block", "item": { "id": "dhVR2HqgRVCTGFi_0bWqLqA", // The block to update "type": "item", "attributes": { "title": "Updated DAST Block Title" } } }, { "type": "paragraph", "children": [{ "type": "span", "value": "Some text." }] } ] } } } ```
###### Deeply-nested blocks Blocks can contain other blocks, creating hierarchies multiple levels deep. **The same principles apply recursively.** When you fetch a record with `?nested=true`, the API will expand nested blocks at all levels. When updating, you are always sending a payload to the top-level parent record, but you can specify changes to deeply nested blocks using the same ID vs. object rules.
Example: Updating a nested block Imagine a "Wrapper" block that contains a Modular Content field with "Child" blocks inside it. To update "Child Block 1" while leaving "Child Block 2" untouched: ```json // This payload is sent to the top-level record containing the "Parent Block" { "wrapper_block": { "id": "dhVR2HqgRVCTGFi_0bWqLqA", // ID of the parent block being updated "type": "item", "attributes": { "nested_content": [ { "id": "kL9mN3pQrStUvWxYzAbCdE", // ID of the nested block being updated "type": "item", "attributes": { "title": "Updated Child Block 1" } }, "fG8hI1jKlMnOpQrStUvWxY" // Unchanged nested block, sent as ID ], // You can skip any attribute that does not need to change } } } ```
--- ## Localization Localization allows you to store different versions of your content for different languages or regions. When you mark a field as "localizable" in your model, its structure in the API changes to accommodate multiple values. The fundamental change is that the field's value is no longer a single piece of data but an **object keyed by locale codes**. For example, a simple non-localized `title` field looks like this: ```json { "title": "Hello World" } ``` When localized, it becomes an object containing a value for each configured locale: ```json { "title": { "en": "Hello World", "it": "Ciao Mondo", "fr": "Bonjour le Monde" } } ``` This principle applies to **every type of field**, from simple strings to **Modular Content**, **Single Block**, and **Structured Text** fields. For instance, a localized Modular Content field will contain a separate array of blocks for each language. This powerful feature allows you to have completely different block structures for each locale.
Example: Localized Modular Content field In a `regular` API response, you would see different arrays of block IDs for each locale. ```json { "content_blocks": { "en": ["dhVR2HqgRVCTGFi0bWqLqA", "kL9mN3pQrStUvWxYzAbCdE"], "it": ["fG8hI1jKlMnOpQrStUvWxY", "dhVR2HqgRVCTGFi0bWqLqA"] } } ```
Example: Localized Single Block field A different block can be assigned to each locale. ```json { "hero_block": { "en": "dhVR2HqgRVCTGFi0bWqLqA", "it": "kL9mN3pQrStUvWxYzAbCdE" } } ```
Example: Localized Structured Text field The entire DAST document is localized, allowing for different text and different embedded blocks per locale. ```json { "rich_content": { "en": { "schema": "dast", "document": { "type": "root", "children": [ { "type": "paragraph", "children": [ { "type": "span", "value": "Welcome to our product showcase. Here's what we're featuring today:" } ] }, { "type": "block", "item": "dhVR2HqgRVCTGFi0bWqLqA" } ] } }, "it": { "schema": "dast", "document": { "type": "root", "children": [ { "type": "paragraph", "children": [ { "type": "span", "value": "Benvenuti nella nostra vetrina prodotti. Ecco cosa presentiamo oggi:" } ] }, { "type": "block", "item": "kL9mN3pQrStUvWxYzAbCdE" } ] } } } } ```
When reading or writing localized content, there are a few key rules to follow to ensure data integrity. ###### Locale consistency Within a single record, all localized fields must have a consistent set of locales. You cannot have a `title` with English and Italian, and a `description` with English and French in the same record. ```json // ❌ This will FAIL due to inconsistent locales ("it" vs "fr") { "title": { "en": "Title", "it": "Titolo" }, "description": { "en": "Description", "fr": "Description" } } // ✅ This is VALID because locales are consistent across all fields { "title": { "en": "Title", "it": "Titolo" }, "description": { "en": "Description", "it": "Descrizione" } } ``` ###### Models enforcing all locales You can configure a model to require every project locale to be present for its localized fields using the [`all_locales_required`](/docs/content-management-api/resources/item-type.md#object-payload) attribute. When this setting is enabled, records **must include a key for every defined locale** within each localized field. The value for a locale can be `null`, but the key itself is mandatory. ```json // ❌ FAILS: The "it" locale is missing. { "title": { "en": "Title" } } // ✅ VALID: All required locale keys ("en", "it") are present. { "title": { "en": "Title", "it": "Titolo" } } // ✅ ALSO VALID: The "it" key is present, even with a `null` value. { "title": { "en": "Title", "it": null } } ``` --- ## Type-safe development with TypeScript Since DatoCMS records don't have a predetermined structure, the JavaScript client cannot provide strict TypeScript types out of the box: ```typescript import { buildClient } from "@datocms/cma-client-node"; const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const record = await client.items.find('dhVR2HqgRVCTGFi0bWqLqA'); record.accent_color; // -> TypeScript type: unknown ``` To get **full type-safety plus auto-completions and type hints in your code editor**, you can leverage the DatoCMS CLI to automatically generate TypeScript types based on your specific project schema. ###### Generating types from your schema After [installing and configuring the CLI](/docs/scripting-migrations/installing-the-cli.md), you can use the `schema:generate` command to generate a comprehensive TypeScript definition file describing your DatoCMS project structure (models and blocks): Terminal window ```bash $ npx datocms schema:generate schema.ts ``` The output describes your DatoCMS project structure (models and blocks) and emits, for each one, both an `ItemTypeDefinition` **type** and a runtime **constant** with `ID` / `REF` properties: ```typescript // schema.ts — generated by `npx datocms schema:generate`. // // ⚠️ Do not hand-write or hand-edit these types in your own code. The // generator is authoritative: re-run it whenever the schema changes, and // import from the generated file. Redeclaring ItemTypeDefinition<...> // inline duplicates the schema and drifts silently the moment a field // is added, renamed, or removed. import type { ItemTypeDefinition } from '@datocms/cma-client'; type EnvironmentSettings = { locales: 'en' | 'it' }; export type Article = ItemTypeDefinition< EnvironmentSettings, '76hhD-LaS5CM3NPJw0991w', // ID of the Article model { name: { type: 'string' }; slug: { type: 'slug' }; accent_color: { type: 'color' }; sections: { type: 'rich_text'; blocks: ArticleSection }; } >; export const Article = { ID: '76hhD-LaS5CM3NPJw0991w', REF: { type: 'item_type', id: '76hhD-LaS5CM3NPJw0991w' }, } as const; ``` An `ItemTypeDefinition` is a minimal type blueprint for your API payloads. It only includes what's needed for typed API calls: field names, their data types, and any allowed block types. It intentionally omits details like validation rules or default values, as they don't affect the shape of the data sent to or from the API. > [!WARNING] Practical, not perfect > These types are designed for a practical developer experience, not perfect precision. In other words, you might still encounter API errors even if TypeScript gives you the green light. The types ensure the structure of a request is valid, but not necessarily the values within it (e.g., a string that's too long). > [!PROTIP] Other ways to generate types > Use `--item-types=product,article` to scope generation to specific models/blocks, or include the same definitions inline in a [migration script](/docs/scripting-migrations/scripting-migrations-with-the-datocms-cli.md#option-1-write-a-migration-script-manually) via `npx datocms migrations:new 'tweak articles' --schema=article,author` (or `--schema=all`). ###### Using markers in API calls Each generated `ItemTypeDefinition` (e.g. `Article`) acts as a **marker**: a branded type the client uses to infer the right request and response shapes when you pass it as a generic. By convention, import the generated file as a `Schema` namespace so each marker reads as `Schema.Article`, `Schema.ArticleSection`, etc.: ```typescript import * as Schema from './schema'; ``` Use a marker as a **type** when calling generic methods like `client.items.create(...)`, and as a **value** to reference the model's ID (`Schema.Article.ID`) or build an `item_type` relationship (`Schema.Article.REF`). Markers can be used as generics in all API calls related to records to get a fully typed interface: ```typescript // Fully typed record retrieval const record = await client.items.find('AZUeMuPySxuJCJ8ibEVE7w'); record.accent_color; // -> { red; green; blue; alpha } (properly typed!) // Type-safe record creation const record = await client.items.create({ item_type: Schema.Article.REF, accent_color: '#FF0000', // ✅ TypeScript catches the wrong format! }); ``` ###### Extracting a concrete field type When you need the actual TypeScript type of a field — to annotate a helper, an intermediate variable, or a function parameter — reach for one of the `FieldValue*` helpers. A marker can't be indexed directly: its top-level keys are blueprint metadata, not field API keys. ```typescript // ❌ TypeScript error — Schema.Article describes the model, not its payload type Sections = Schema.Article['sections']; ``` Which helper you pick depends on which side of the wire you're on: | Helper | Resolves to the field as it appears in… | | --- | --- | | `FieldValueInRequest` | a `client.items.create` / `client.items.update` payload | | `FieldValue` | a default response (e.g. `client.items.find(id)`) | | `FieldValueInNestedResponse` | a nested response (e.g. `client.items.find(id, { nested: true })`) | Each one accepts the same first argument in two equivalent forms: - **A value already in scope** — pass `typeof record` or `typeof block`. This is the common case when you've just fetched a record, or narrowed a nested block with `isBlockOfType`. No need to restate the model name. - **A model marker** — pass `Schema.X` directly. Use this when no value is in scope yet — typing a helper that builds a payload from scratch, or a function parameter that hasn't read anything. **From a fetched value** The same expression works on a top-level record and on a narrowed nested block: ```typescript import { buildBlockRecord, type FieldValueInRequest, isBlockOfType, } from '@datocms/cma-client'; import * as Schema from './schema'; const page = await client.items.find(id, { nested: true }); const sections: NonNullable> = []; for (const block of page.sections) { if (isBlockOfType(Schema.HeroBlock.ID, block)) { // Same expression, applied to a narrowed nested block. const ctas: NonNullable> = []; // …rebuild ctas, then push the new HeroBlock into sections… } else { sections.push(block.id); } } await client.items.update(page.id, { sections }); ``` **From a model marker** ```typescript import { buildBlockRecord, type FieldValueInRequest } from '@datocms/cma-client'; import * as Schema from './schema'; type Sections = NonNullable>; function buildLaunchSections(headline: string): Sections { return [ buildBlockRecord({ item_type: Schema.ArticleSection.REF, title: headline, }), ]; } ``` > [!PROTIP] Typing whole payloads > The `FieldValue*` helpers each materialize a single field's type. To annotate an **entire** create/update payload — or an entire response — reach for the corresponding `ApiTypes.*` shape (`ApiTypes.ItemCreateSchema`, `ApiTypes.ItemUpdateSchema`, `ApiTypes.Item`, `ApiTypes.ItemInNestedResponse`). ###### Narrowing a record or block to a specific model When you have a value whose static type is a union of models (e.g. a record pulled from a mixed `list`, or a block from a Modular Content field), TypeScript needs to know *which* one you're holding before it'll let you reach into its attributes. The model ID is the natural way to tell them apart, but its canonical location (`relationships.item_type.data.id`) is nested four levels deep and TypeScript won't auto-narrow through that path. Use the `isBlockOfType` helper from `@datocms/cma-client` instead — it's a proper type-guard predicate that works in both inline checks and array methods. It supports two equivalent calling styles: ```typescript import { isBlockOfType } from "@datocms/cma-client"; import * as Schema from './schema'; const article = await client.items.find(articleId, { nested: true, }); // 1. Inline check — pass both the model ID and the value. for (const block of article.content) { if (isBlockOfType(Schema.HeroBlock.ID, block)) { block.attributes.headline; // OK — narrowed to HeroBlock } } // 2. As a predicate — pass just the model ID, get back a curried type guard // suitable for `.filter` / `.find`. A bare equality check here would NOT // narrow the result type. const images = article.content.filter(isBlockOfType(Schema.ImageBlock.ID)); images[0].attributes.upload_id; // OK — narrowed to ImageBlock ``` > [!PROTIP] Skipping the helper for inline checks > Every record and block in responses also carries a top-level `__itemTypeId` property, so `if (item.__itemTypeId === Schema.HeroBlock.ID)` narrows just as well as `isBlockOfType` for inline checks. ## Object payload **`id`** - Type: string - Example: `"hWl-mnkWRYmMCSTq4z_piQ"` RFC 4122 UUID of record expressed in URL-safe base64 format **`type`** - Type: string Must be exactly `"item"`. **`meta.created_at`** - Type: date-time Date of creation **`meta.updated_at`** - Type: date-time Last update time **`meta.published_at`** - Type: null, date-time Date of last publication **`meta.first_published_at`** - Type: null, date-time Date of first publication **`meta.publication_scheduled_at`** - Type: null, date-time Date of future publication **`meta.unpublishing_scheduled_at`** - Type: null, date-time Date of future unpublishing **`meta.status`** - Type: null, enum - Example: `"published"` Status
Show enum values **`draft`** The record is not published **`updated`** The record has some unpublished changes **`published`** The record is published
**`meta.is_current_version_valid`** - Type: null, boolean Whether the current version of the record is valid or not **`meta.is_published_version_valid`** - Type: null, boolean Whether the published version of record is valid or not **`meta.current_version`** - Type: string - Example: `"4234"` The ID of the current record version **`meta.stage`** - Type: null, string Workflow stage in which the item is **`meta.has_children`** - Type: null, boolean When the records can be organized in a tree, indicates whether the record has children **`item_type`** - Type: [ResourceLinkage\<"item_type"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item_type.md) The record's model **`creator`** - Type: [ResourceLinkage\<"account"\>](https://www-draft.datocms.com/docs/content-management-api/resources/account.md), [ResourceLinkage\<"access_token"\>](https://www-draft.datocms.com/docs/content-management-api/resources/access_token.md), [ResourceLinkage\<"user"\>](https://www-draft.datocms.com/docs/content-management-api/resources/user.md), [ResourceLinkage\<"sso_user"\>](https://www-draft.datocms.com/docs/content-management-api/resources/sso_user.md), [ResourceLinkage\<"organization"\>](https://www-draft.datocms.com/docs/content-management-api/resources/organization.md) The entity (account/collaborator/access token/sso user) who created the record
Show deprecated **`meta.is_valid`** - Deprecated - Type: boolean Whether the current record is valid or not This field will be removed in the future: use `is_current_version_valid` or `is_published_version_valid` instead, according to the specific use case
--- # Content Management API — List all records Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item/instances.md To retrieve a collection of records, send a GET request to the `/items` endpoint. The collection is [paginated](/docs/content-management-api/pagination.md), so make sure to iterate over all the pages if you need every record in the collection! > [!PROTIP] 📚 New to DatoCMS records? > Begin by reading the [Introduction to records](/docs/content-management-api/resources/item.md) guide to familiarize yourself with field types, API response modes, and the concepts of block manipulation! ## Filter combinations You can use multiple filters to refine the records you want to retrieve. However, some combinations may be invalid, resulting in errors or ignored filters, which can lead to unexpected results: - `filter[ids]` cannot be combined with `filter[type]`, or `filter[fields]` related to model-specific fields - `filter[type]`, when specifying multiple item types, cannot be combined with `filter[ids]`, or `filter[fields]` related to model-specific fields - `filter[type]`, when specifying one (or more) block models, cannot be combined with `filter[ids]`, `filter[fields]`, or `query` ## Response modes: Regular vs. Nested The `GET /items` endpoint, just like the [single record endpoint](/docs/content-management-api/resources/item/self.md), supports two different response modes that control how block fields are returned in the JSON payload. You can switch between them using the nested query parameter. - **Regular mode (default)**: This is the most efficient mode for listing multiple records. Any block fields (like Modular Content) will contain an array of **block IDs**, not the full block content. This keeps the response size small and fast. - **Nested mode (`nested=true`)**: This mode returns the complete content for any block fields. Instead of just IDs, the API will return full **block objects**, including all their attributes. This is useful when you need to display the blocks' content immediately without making additional API calls, or to read existing content and then make an update. ###### Example Regular mode (default) Please note that if you don't specify any parameters, the API will return return the first 30 records. They can be from **any** model in your project. Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import type * as Schema from "./schema.js"; /* * Article * ├─ title: string * └─ content: text */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const results = await client.items.list({ version: "current", }); console.log("-- LISTING ITEMS --"); results.forEach((item) => { console.log(inspectItem(item)); }); } run(); ``` Returned output Showing the default number of results (30 records) from any model ```javascript -- LISTING ITEMS -- └ Item "cEzRZmM3SyeHmAxS5KE9dg" (item_type: "T6TO3fbwRdyhcljYV8fyhg") ├ title: "Third Article" └ content: "This is the content of the third article." └ Item "f2Ev8ybUTq6DFk348JeW1w" (item_type: "T6TO3fbwRdyhcljYV8fyhg") ├ title: "Second Article" └ content: "This is the content of the second article." └ Item "VJ2-B9zJQPG-xdwU-vJdOw" (item_type: "T6TO3fbwRdyhcljYV8fyhg") ├ title: "First Article" └ content: "This is the content of the first article." ``` ###### Example Nested mode > [!WARNING] Lower limits apply with Nested Mode > When `nested: true`, the maximum number of records you can request at once is restricted to 30, in contrast to the standard 500. Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import type * as Schema from "./schema.js"; /* * BlogPost * ├─ title: string * └─ content: structured_text * ├─ HeroBlock: headline, subtitle * ├─ TextBlock: content * └─ ImageBlock: image, caption */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const records = await client.items.list({ nested: true, // But retrieve its nested block content as well version: "current", }); console.log("-- RECORDS WITH NESTED BLOCKS --"); records.forEach((item) => { console.log(inspectItem(item)); }); } run(); ``` Returned output ```javascript -- RECORDS WITH NESTED BLOCKS -- └ Item "ZJ3ESh8pTBaRS5ED8loc2w" (item_type: "U4jwHd5-RCy2ItsDuWLMTQ") ├ title: "Understanding Modular Content" └ content ├ heading (level: 1) │ └ span "Welcome to Modular Content" ├ block │ └ Item "Sb5aNY5hQHaN_4KMU96H6A" (item_type: "GURToKAcQIyC-rTypPeHTw") │ ├ headline: "Hero Section" │ └ subtitle: "This is a hero block that introduces the content" ├ paragraph │ └ span "This blog post demonstrates how to work with structured text and modu..." ├ block │ └ Item "G_06E4v8SvqdChpFnEELxA" (item_type: "Y5l8wbEDQLKj7qm22CTucQ") │ └ content: "Modular content allows you to create flexible, reusable components that can b..." ├ block │ └ Item "T2lBvPruQwGAQTM9_ywm-g" (item_type: "ZsoQdbEVTkizaFPrama3IA") │ ├ image │ │ └ upload_id: "dLJdPzC3TW-mJXGo7K73Gg" │ └ caption: "A beautiful landscape showcasing the power of visual content" └ paragraph └ span "This concludes our example of nested blocks and structured content." └ Item "T2lBvPruQwGAQTM9_ywm-g" (item_type: "ZsoQdbEVTkizaFPrama3IA") ├ image │ └ upload_id: "dLJdPzC3TW-mJXGo7K73Gg" └ caption: "A beautiful landscape showcasing the power of visual content" └ Item "G_06E4v8SvqdChpFnEELxA" (item_type: "Y5l8wbEDQLKj7qm22CTucQ") └ content: "Modular content allows you to create flexible, reusable components that can b..." └ Item "Sb5aNY5hQHaN_4KMU96H6A" (item_type: "GURToKAcQIyC-rTypPeHTw") ├ headline: "Hero Section" └ subtitle: "This is a hero block that introduces the content" ``` ###### Example Filtering records by their creator (CMA only) Filter records by their creator using the `_creator` meta field. The `_creator` filter is **CMA-only** (not available via the [GraphQL Content Delivery API](/docs/content-delivery-api/filtering-records.md)). It accepts polymorphic creator references in the form `{ type, id }`, where `type` is one of: - `user` — a regular collaborator - `account` — the site owner (when owned by an account) - `organization` — the site owner (when owned by an organization) - `sso_user` — a SSO user - `access_token` — an API access token Supported operators are `eq`, `neq`, `in`, and `notIn`. The `in` and `notIn` operators accept a list of references and may mix `type` values — for example, "everything created by these users *or* these access tokens". > [!PROTIP] 🧭 Finding a creator's ID > The shape mirrors what you find under `relationships.creator.data` on any record returned by the API — copy the `type` and `id` from there. The `_creator` filter can also be used across multiple models in the same request (without `filter[type]`), making it convenient for "everything I created" cross-model queries. In this example, we take the creator of an existing `blog_post` record and list all the records of that model created by the same creator. Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import type * as Schema from "./schema.js"; /* * Blog post * └─ title: string */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // A creator reference has the shape `{ type, id }`, the same you find under // `creator` on any record returned by the API. Here we take it from an // existing blog post, but you can also write it by hand, for example // `{ type: "user", id: "12345" }`. const [anyBlogPost] = await client.items.list({ filter: { type: "blog_post" }, page: { limit: 1 }, }); if (!anyBlogPost?.creator) { throw new Error("No blog posts found"); } const records = await client.items.list({ filter: { type: "blog_post", fields: { _creator: { eq: anyBlogPost.creator, }, }, }, version: "current", }); console.log( `-- BLOG POSTS CREATED BY ${anyBlogPost.creator.type} ${anyBlogPost.creator.id} --`, ); records.forEach((item) => { console.log(inspectItem(item)); }); } run(); ``` Returned output ```javascript -- BLOG POSTS CREATED BY organization 628404 -- └ Item "KaMIqHpVSoKw9SN6P0zqjw" (item_type: "GURToKAcQIyC-rTypPeHTw") └ title: "Second post" └ Item "ZJXenqgyTsungvb2mDLfNA" (item_type: "GURToKAcQIyC-rTypPeHTw") └ title: "Hello world" ``` ## TypeScript typing Iterating records without typed schemas means every attribute on every returned record is `unknown`, and filters on model-specific fields go unchecked. The single biggest lever you have is passing a generated `Schema.X` marker as the generic on `items.list` (or `items.listPagedIterator`). TypeScript then knows the exact shape of each returned record — its field names, types, and block structures — so reads are typed end-to-end: ```ts import * as Schema from "./schema"; for await (const record of client.items.listPagedIterator({ filter: { type: "article_model_id" }, })) { record.title; // typed, not unknown } ``` For the exact type of a specific field on the returned records (to annotate a helper or intermediate variable), index `ApiTypes.Item["field_api_key"]` (or `ApiTypes.ItemInNestedResponse["field_api_key"]` when iterating with `nested: true`). See the [full TypeScript guide](https://www.datocms.com/cma-ts-schema.md) for how to generate `schema.ts` and the complete pattern. The following table contains the list of all the possible arguments, along with their type, description and examples values. ## Query parameters **`nested`** - Type: boolean For Modular Content, Structured Text and Single Block fields. If set, returns full payload for nested blocks instead of IDs **`filter`** - Type: object Attributes to filter records
Show object format **`ids`** - Type: string - Example: `"c89tCUarTvGKxA37acCEWA,aCiWeOsUT3mxY0KIzUfAhw"` Record (or block record) IDs to fetch, comma separated. If you use this filter, you _must not_ use `filter[type]`. You can combine it with meta fields (like `_published_at`, `_status`, `_creator`), but _must not_ use model-specific fields **`type`** - Type: string - Example: `"cat,dog"` Model/Block model ID or `api_key` to filter. If you use this filter, you _must not_ use `filter[ids]`. When passing a single element, you can use both meta fields and model-specific fields (note: model-specific fields only work with models, not block models). When passing multiple comma-separated values, you can use meta fields but _must not_ use model-specific fields **`query`** - Type: string - Example: `"foo"` Textual query to match. Can be combined with other filters. When used, only records (not blocks) are returned. If `locale` is defined, search within that locale. Otherwise environment's main locale will be used. **`fields`** - Type: object - Example: `{ name: { eq: "Buddy" } }` Filter by record fields. Meta fields (like `_published_at`, `_status`, `_creator`) can be used in most cases. Model-specific fields (like `title`, `name`) require `filter[type]` to specify a single model, and only work with models (not block models). Same syntax as [GraphQL API records filters](/docs/content-delivery-api/filtering-records): use square brackets to indicate nesting levels. E.g. `filter[fields][parent][eq]=`. Use snake_case for field names. The `_creator` meta filter is CMA-only (not available via the GraphQL API) and accepts polymorphic creator references in the form `{ "type": "user" | "account" | "organization" | "sso_user" | "access_token", "id": "" }`. If `locale` is defined, search within that locale. Otherwise environment's main locale will be used. **`only_valid`** - Type: string - Example: `"true"` When set, only valid records are included in the results.
**`locale`** - Type: string - Example: `"it"` When `filter[query]` or `field[fields]` is defined, filter by this locale. Default: environment's main locale **`page`** - Type: object Parameters to control offset-based pagination
Show object format **`offset`** - Type: integer - Example: `200` The (zero-based) offset of the first entity returned in the collection (defaults to 0) **`limit`** - Type: integer The maximum number of entities to return (defaults to 30, maximum is 500)
**`order_by`** - Type: string - Example: `"name_DESC"` Fields used to order results. You **must** specify also `filter[type]` with one element only to be able use this option. Format: `_(ASC|DESC)`, where `` can be either the API key of a model's field, or one of the following meta columns: `id`, `_updated_at`, `_created_at`, `_status`, `_published_at`, `_first_published_at`, `_publication_scheduled_at`, `_unpublishing_scheduled_at`, `_is_valid`, `position` (only for sortable models). You can pass multiple comma separated rules. **`version`** - Type: string - Example: `"published"` Whether you want the currently published versions (`published`) of your records, or the latest available (`current`, default) ## Returns Returns an array of resource objects of type [item](/docs/content-management-api/resources/item.md) ## Other examples ###### Example Fetching a specific page of records To fetch a specific page, you can use the `page` object in the query params together with its `offset` and `limit` parameters. They will still be from **any model** in your project. Code To get 2 records starting from position 4, we should use: `limit: 2` and `offset: 3` (because record counting starts from 0) ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import type * as Schema from "./schema.js"; /* * BlogPost * ├─ title: string * ├─ content: text * └─ author: string */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const twoRecords = await client.items.list({ page: { limit: 2, offset: 3, }, version: "current", }); console.log("-- PAGINATED ITEMS --"); twoRecords.forEach((item) => { console.log(inspectItem(item)); }); } run(); ``` Returned output ```javascript -- PAGINATED ITEMS -- └ Item "G9k168YbTietmuwlA7-evg" (item_type: "P--WAiOJQraTyQb3pwnNog") ├ title: "GraphQL Queries in DatoCMS" ├ content: "How to write efficient GraphQL queries to fetch your content." └ author: "Bob GraphQL" └ Item "Wgx-4iIaTTWsjgj7kjxV1w" (item_type: "P--WAiOJQraTyQb3pwnNog") ├ title: "Using the Management API" ├ content: "A comprehensive guide to using the DatoCMS Content Management API." └ author: "Alice Engineer" ``` ###### Example Fetching all pages Instead of fetching a single page at a time, sometimes you want to get all the pages together. You can do this using the `client.items.listPagedIterator()` method with an [async iteration statement](https://github.com/tc39/proposal-async-iteration#the-async-iteration-statement-for-await-of), which will handle pagination for you. All the details on how to use `listPagedIterator()` are outlined [on this page](/docs/content-management-api/pagination.md#paged-iterators). Note that this will return records across **all** your models, unless you specify a filter. Unfiltered, this is useful for fetching all the records in your project (e.g. for backup or export purposes). To filter by IDs or models, see the other examples below. Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import type * as Schema from "./schema.js"; /* * Product * ├─ name: string * └─ price: float * * Category * ├─ name: string * └─ description: text * * Review * ├─ rating: integer * └─ comment: text */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // We'll be building up an array of all records using an AsyncIterator, `client.items.listPagedIterator()` const allRecords = []; for await (const record of client.items.listPagedIterator< Schema.Product | Schema.Category | Schema.Review >({ version: "current" })) { allRecords.push(record); } console.log("-- ALL RECORDS ACROSS ALL PAGES --"); allRecords.forEach((item) => { console.log(inspectItem(item)); }); } run(); ``` Returned output Showing all results of `client.items.listPagedIterator()`, from any model ```javascript -- ALL RECORDS ACROSS ALL PAGES -- └ Item "ApidnkdFSgSa0fMnxut7ug" (item_type: "Y5l8wbEDQLKj7qm22CTucQ") ├ name: "Audio" └ description: "Audio equipment and sound devices" └ Item "PeKN3Mx1QMiQpxR6rIfV1Q" (item_type: "ZsoQdbEVTkizaFPrama3IA") ├ rating: 5 └ comment: "Excellent product, highly recommended!" └ Item "Fo_aNiUGQce74zJQLghgEA" (item_type: "Y5l8wbEDQLKj7qm22CTucQ") ├ name: "Electronics" └ description: "Electronic devices and accessories" └ Item "DfAtrqEiQC-BpxRkCgFxug" (item_type: "GURToKAcQIyC-rTypPeHTw") ├ name: "Bluetooth Speaker" └ price: 49.99 └ Item "XfVkvL9YT2K0KrhaqEXtrg" (item_type: "ZsoQdbEVTkizaFPrama3IA") ├ rating: 4 └ comment: "Good quality, worth the price." └ Item "d2InAHvfQze_HvxdtX3Iyw" (item_type: "GURToKAcQIyC-rTypPeHTw") ├ name: "Wireless Headphones" └ price: 99.99 ``` ###### Example Fetching records by their IDs You can retrieve a list of records (or blocks) by their record IDs. They can be from the same or different models. Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import type * as Schema from "./schema.js"; /* * Dog * ├─ name: string * └─ breed: string * * Song * ├─ title: string * ├─ artist: string * └─ duration: integer */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const records = await client.items.list({ filter: { // Specific record IDs: one dog record, and one song record // Note that it's a comma-separated string with no spaces ids: "ZsoQdbEVTkizaFPrama3IA,U4jwHd5-RCy2ItsDuWLMTQ", }, version: "current", }); console.log("-- ITEMS BY SPECIFIC IDS --"); records.forEach((item) => { console.log(inspectItem(item)); }); } run(); ``` Returned output Showing two records from different models: dog and song. The returned record order is random, not the order of the record IDs you specified. ```javascript -- ITEMS BY SPECIFIC IDS -- └ Item "U4jwHd5-RCy2ItsDuWLMTQ" (item_type: "Y5l8wbEDQLKj7qm22CTucQ") ├ title: "Bohemian Rhapsody" ├ artist: "Queen" └ duration: 355 └ Item "ZsoQdbEVTkizaFPrama3IA" (item_type: "GURToKAcQIyC-rTypPeHTw") ├ name: "Buddy" └ breed: "Golden Retriever" ``` ###### Example Fetching records belonging to a model You can filter the records by one or more model types. You can use either the model's `api_key` (that you define) or its unique ID (generated by DatoCMS). Multiple comma-separated values are accepted: Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import type * as Schema from "./schema.js"; /* * Cat * ├─ name: string * ├─ breed: string * └─ age: integer * * Dog * ├─ name: string * ├─ breed: string * └─ age: integer */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const records = await client.items.list({ filter: { // Filtering by the model with api_key "cat" and the model with ID of "dog" type: "cat,Y5l8wbEDQLKj7qm22CTucQ", }, version: "current", }); console.log("-- FILTERED BY MODEL TYPE --"); records.forEach((item) => { console.log(inspectItem(item)); }); } run(); ``` Returned output ```javascript -- FILTERED BY MODEL TYPE -- └ Item "bVlcRGmFRqiK1nKPbesN8w" (item_type: "GURToKAcQIyC-rTypPeHTw") ├ name: "Mittens" ├ breed: "Siamese" └ age: 2 └ Item "CEtirbQ_SnmHpowQ2tZ-ow" (item_type: "Y5l8wbEDQLKj7qm22CTucQ") ├ name: "Max" ├ breed: "Labrador" └ age: 4 └ Item "KyueUsNkQfWh71dfxstVWQ" (item_type: "Y5l8wbEDQLKj7qm22CTucQ") ├ name: "Buddy" ├ breed: "Golden Retriever" └ age: 5 └ Item "bRfo6K_YRJa1RrPfpUQTOg" (item_type: "GURToKAcQIyC-rTypPeHTw") ├ name: "Whiskers" ├ breed: "Persian" └ age: 3 ``` ###### Example Fetching draft or updated records and filtering by publication status By default, the API only returns published records. Using the `version` parameter, you can choose to also include drafts and updates. `version: 'current'` will return the *most recent* versions of the queried records. Sometimes this can be the same as the published version, but other times it could be an unpublished draft or update: - `draft` means the record has been created and saved, but not yet published (or was unpublished) - `published` means the record has been published, and there are no later changes (i.e., the published version *is* the most recent version) - `updated` means the record was previously published, but there are new changes that have been saved and not yet published (the current version is *ahead* of the published version) To get *only* draft, updated, or published records, you can filter on this response's `record.meta.status` property on the client side, *after* the fetch: Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import type * as Schema from "./schema.js"; /* * Post * ├─ title: string * ├─ content: text * └─ author: string */ const getPublishedAndDraftRecordsOfModel = async () => { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN, }); const allRecords = await client.items.list({ filter: { type: "post", // Model name or internal ID }, version: "current", // Fetch the latest version of the records, regardless of publication status }); // Records that have been saved but not published (or were unpublished later) const newDraftsOnly = allRecords.filter( (record) => record.meta.status === "draft", ); // Records that were published but have unsaved changes ahead of the published version const updatedRecordsOnly = allRecords.filter( (record) => record.meta.status === "updated", ); // Records that were published and have no further changes const publishedRecordsOnly = allRecords.filter( (record) => record.meta.status === "published", ); console.log(`There are ${allRecords.length} total records in this model.`); console.log(`${publishedRecordsOnly.length} are published.`); console.log(`${updatedRecordsOnly.length} have unpublished updates.`); console.log(`${newDraftsOnly.length} are unpublished drafts.`); console.log("\n-- PUBLISHED RECORDS --"); publishedRecordsOnly.forEach((item) => { console.log(inspectItem(item)); }); console.log("\n-- DRAFT RECORDS --"); newDraftsOnly.forEach((item) => { console.log(inspectItem(item)); }); console.log("\n-- UPDATED RECORDS --"); updatedRecordsOnly.forEach((item) => { console.log(inspectItem(item)); }); }; getPublishedAndDraftRecordsOfModel(); ``` Returned output ```javascript There are 4 total records in this model. 2 are published. 1 have unpublished updates. 1 are unpublished drafts. -- PUBLISHED RECORDS -- └ Item "Z1iG3QGISZON0p6ctQR7bg" (item_type: "GURToKAcQIyC-rTypPeHTw") ├ title: "Another Published Post" ├ content: "This is another published post to show multiple published items." └ author: "Alice Publisher" └ Item "Ssc2tQvNS-i0yjrcmq824A" (item_type: "GURToKAcQIyC-rTypPeHTw") ├ title: "Published Article" ├ content: "This is a published article that's live on the website." └ author: "John Author" -- DRAFT RECORDS -- └ Item "cjwt438ZT2ChDWpolIm2Sg" (item_type: "GURToKAcQIyC-rTypPeHTw") ├ title: "Draft Article" ├ content: "This is a draft article that hasn't been published yet." └ author: "Jane Writer" -- UPDATED RECORDS -- └ Item "YWrNII0ETpWdjXaO76AW3Q" (item_type: "GURToKAcQIyC-rTypPeHTw") ├ title: "Updated Article [EDITED]" ├ content: "This article was published but then updated with new content." └ author: "Bob Editor" ``` ###### Example Filtering a model's records by field values and sorting the results Within a specified model, you can further filter its records by their field values. You **must** specify a single model using `filter[type]`. You *cannot* filter by field value across multiple models at once. Valid filters are documented at [GraphQL API records filters](/docs/content-delivery-api/filtering-records.md), so please check there. However, you **cannot** use [deep filtering](/docs/content-delivery-api/deep-filtering.md) on Modular Content and Structured Text fields at the moment. - You *may* add an optional `locale` parameter if you are filtering by a localized field. - You *may* add an optional `order_by` parameter. In this example, we are filtering the model `dog` by: - A single-line string field, `name in ['Buddy','Rex']` (matching `Buddy` OR `Rex`) - A single-line string field, `breed eq 'mixed'` (matching exactly `mixed`) - A date field (`_updated_at`) (and ordering the results by the same) Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import type * as Schema from "./schema.js"; /* * Dog * ├─ name: string * ├─ breed: string * ├─ age: integer * ├─ weight: float * └─ is_trained: boolean */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const records = await client.items.list({ filter: { type: "dog", fields: { name: { in: ["Buddy", "Rex"], }, breed: { eq: "mixed", }, _updated_at: { gt: "2020-04-18T00:00:00", }, }, }, order_by: "_updated_at_ASC", version: "current", }); console.log("-- FILTERED BY FIELD VALUES --"); records.forEach((item) => { console.log(inspectItem(item)); }); } run(); ``` Returned output ```javascript -- FILTERED BY FIELD VALUES -- └ Item "bxiqfMHRTxaB1sv4bedQTQ" (item_type: "GURToKAcQIyC-rTypPeHTw") ├ name: "Buddy" ├ breed: "mixed" ├ age: 5 ├ weight: 25.5 └ is_trained: true └ Item "d9f4ZoN_T9WqJRtC-jVu_A" (item_type: "GURToKAcQIyC-rTypPeHTw") ├ name: "Rex" ├ breed: "mixed" ├ age: 3 ├ weight: 30.2 └ is_trained: false ``` ###### Example Fetching records by a textual generic query You can retrieve a list of records filtered by a textual query match. It will search in block records content too. Set the `nested` parameter to `true` to retrieve embedded block content as well. > [!WARNING] Content indexing delay > Please note that you need to wait at least 30 seconds after creating or updating content before expecting to see results in textual queries. You *can* narrow your search to some models by specifying the `filter[type]` parameter. You can use either the model's `api_key` or its unique ID. Multiple comma-separated values are accepted. You *should* specify the `locale` attribute, or the environment's default locale will be used. Returned records are ordered by rank. Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import type * as Schema from "./schema.js"; /* * Dog * ├─ name: string * ├─ description: text * └─ breed: string * * Cat * ├─ name: string * ├─ description: text * └─ breed: string */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const records = await client.items.list({ filter: { // optional, if defined, search in the specified models only type: "dog,cat", query: "chicken", }, locale: "en", order_by: "_rank_DESC", // possible values: `_rank_DESC` (default) | `_rank_ASC` version: "current", }); console.log("-- SEARCH RESULTS FOR 'chicken' --"); records.forEach((item) => { console.log(inspectItem(item)); }); } run(); ``` Returned output ```javascript -- SEARCH RESULTS FOR 'chicken' -- └ Item "c2c5cXrITwOhj972XxEIsQ" (item_type: "GURToKAcQIyC-rTypPeHTw") ├ name: "Luna" ├ description: "A playful Labrador puppy who enjoys swimming and chicken-flavored treats." └ breed: "Labrador" └ Item "LlduEUcCSd-M2F5fZARUAw" (item_type: "Y5l8wbEDQLKj7qm22CTucQ") ├ name: "Mittens" ├ description: "A curious Siamese cat who loves chicken and exploring high places." └ breed: "Siamese" └ Item "L45_GuAKQCGfcNtLE4gjKA" (item_type: "Y5l8wbEDQLKj7qm22CTucQ") ├ name: "Shadow" ├ description: "A mysterious black cat who prefers fish over chicken and sleeps during the day." └ breed: "Domestic Shorthair" └ Item "E0Y-kR8iSC-EooTe7dHx6w" (item_type: "GURToKAcQIyC-rTypPeHTw") ├ name: "Buddy" ├ description: "A friendly golden retriever who loves to play fetch and enjoys chicken treats..." └ breed: "Golden Retriever" ``` --- # Content Management API — Create a new record Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item/create.md > [!PROTIP] 📚 New to DatoCMS records? > Before creating your first record, we strongly recommend reading the [Introduction to Records](/docs/content-management-api/resources/item.md) guide. It covers fundamental concepts about field types, block manipulation, and localization that are essential for building a valid creation payload. The payload required to create a new record is determined by the specific [model](/docs/content-management-api/resources/item-type.md) it's based on and the [fields](/docs/content-management-api/resources/field.md) it contains. ###### Example Basic example This example demonstrates the basic process of creating a new record using the DatoCMS Content Management API. The example shows how to specify the item type and provide values for the record's fields. Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import * as Schema from "./schema.js"; /* * Book * ├─ title: string * ├─ genre: string * ├─ synopsis: text * └─ pages: integer */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const record = await client.items.create({ item_type: Schema.Book.REF, title: "The JavaScript Guide", genre: "Programming", synopsis: "A comprehensive guide to modern JavaScript.\nPerfect for beginners and experts alike.", pages: 450, }); console.log(inspectItem(record)); } run(); ``` Returned output ```javascript └ Item "E3eHzSH6QSGbTDmlKlSusw" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title: "The JavaScript Guide" ├ genre: "Programming" ├ synopsis: "A comprehensive guide to modern JavaScript.\nPerfect for beginners and experts..." └ pages: 450 ``` When creating a record, you don't need to specify a value for every field. Any field you omit will be set to its configured default value, or `null` if no default is set. While the [Introduction to Records guide](/docs/content-management-api/resources/item.md) offers a complete reference for every field type, there are several key rules that are especially important when **creating** a new record. ### TypeScript typing Writing a create payload without typed schemas means writing blind: every field is `unknown`, typos compile fine, and mistakes only surface as `422`s from the API. The single biggest lever you have is passing a [generated `Schema.X` marker](https://www.datocms.com/cma-ts-schema.md) as the generic on `items.create`. TypeScript then enforces the model's field names, types, and allowed block shapes at compile time: ```ts // ❌ Untyped: every field is `unknown`, typos compile. await client.items.create({ /* … */ }); // ✅ Typed: field names, types, and block shapes enforced. await client.items.create({ /* … */ }); ``` When you need the actual TypeScript type of a single field — to annotate a helper, an intermediate variable, or a function parameter — reach for `FieldValueInRequest`. The first argument is the `Schema.X` marker for the model that owns the field: > [!WARNING] ⚠️ A marker can't be indexed directly > `Schema.Article` is a phantom *type marker*, not a record shape. Writing `Schema.Article["content"]` won't give you the field type. > > ```ts > // ❌ Markers aren't indexable > type Content = Schema.Article["content"]; > > > // ✅ Use the helper instead > type Content = NonNullable>; > ``` ```ts function buildSections( page: ApiTypes.ItemInNestedResponse, ): NonNullable> { // …assemble and return the sections array… } await client.items.create({ item_type: Schema.LandingPage.REF, title: "Product Launch Landing Page", sections: buildSections(sourcePage), }); ``` The first argument also accepts an item-shaped value the CMA already produced — useful when you're cloning or migrating from an existing record: ```ts const source = await client.items.find("source-id", { nested: true }); if (source.content) { const content: NonNullable> = /* …transform source.content… */; await client.items.create({ item_type: Schema.Article.REF, content }); } ``` > [!WARNING] ⚠️ Field values are always nullable > Even fields with a **required** validator are typed as `Nullable`, because the API may still accept/return `null` in some scenarios. Wrap the helper in `NonNullable<…>` when you need the non-null shape. > [!PROTIP] 📖 Read-side counterparts > `FieldValueInRequest` is the *write*\-side helper. For values coming back from the API, use `FieldValue` (regular responses) or `FieldValueInNestedResponse` (when you fetched with `nested: true`). All three follow the same `` shape — see the [Item resource overview](/docs/content-management-api/resources/item.md) for the full helper family. ### Field value formatting Every field in your payload must be formatted according to its type. This can range from a simple string or number to a structured object. For a comprehensive breakdown of the expected format for every field type, please refer to the **[Field Types Overview](/docs/content-management-api/resources/item.md#field-types-overview)** in our main records guide. ###### Example Managing simple fields This example demonstrates how to create records with various simple field types, including text, numbers, dates, booleans, and more complex types like geo-location and color fields. Key considerations when working with different field types: - **Geo-location fields**: Provide latitude and longitude as an object with both properties - **Color fields**: Specify RGBA values as an object with red, green, blue, and alpha components - **JSON fields**: Must be provided as a JSON-serialized string, not a JavaScript object - **Date/time fields**: Use ISO 8601 format strings for precise timestamps For complete details on field value formats, see the [**Field types overview**](/docs/content-management-api/resources/item.md#field-types-overview) section. Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import * as Schema from "./schema.js"; /* * Product * ├─ name: string * ├─ category: string * ├─ description: text * ├─ price: integer * ├─ weight: float * ├─ release_date: date_time * ├─ in_stock: boolean * ├─ warehouse_location: lat_lon * ├─ brand_color: color * └─ specifications: json */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const record = await client.items.create({ item_type: Schema.Product.REF, name: "Premium Wireless Headphones", category: "Electronics", description: "High-quality noise-cancelling wireless headphones.\nPerfect for music and calls.", price: 299, weight: 0.25, release_date: "2024-03-15T10:30:00", in_stock: true, warehouse_location: { latitude: 45.0703393, longitude: 7.686864, }, brand_color: { alpha: 255, blue: 156, green: 208, red: 239, }, specifications: JSON.stringify({ bluetooth: "5.0", battery_life: "30h", warranty: "2y", }), }); console.log(inspectItem(record)); } run(); ``` Returned output ```javascript └ Item "NZwcu3wYSgWeAbqVCJVToQ" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ name: "Premium Wireless Headphones" ├ category: "Electronics" ├ description: "High-quality noise-cancelling wireless headphones.\nPerfect for music and calls." ├ price: 299 ├ weight: 0.25 ├ release_date: 2024-03-15T10:30:00+00:00 ├ in_stock: true ├ warehouse_location │ ├ latitude: 45.0703393 │ └ longitude: 7.686864 ├ brand_color: #EFD09C └ specifications: {"bluetooth":"5.0","battery_life":"30h","warranty":"2y"} ``` #### Block Fields When creating a record, any new blocks (for Modular Content, Single Block, or Structured Text fields) **must be provided as full block objects**. This object must include the `item_type` in its `relationships` to specify which Block Model to use. For a deeper dive into manipulating blocks, see the guide on **[Creating and Updating Blocks](/docs/content-management-api/resources/item.md#creating-and-updating-blocks)**. ###### Example Modular content fields This example shows how to create records with modular content fields, which allow you to compose rich, dynamic content by combining multiple blocks of different types. Each block can have its own set of fields and can be repeated as needed. The example uses the `buildBlockRecord()` helper function to create blocks more easily. You specify the block model ID and provide values for all the block's fields, similar to creating a regular record: Code ```javascript import { buildBlockRecord, buildClient, inspectItem, } from "@datocms/cma-client-node"; import * as Schema from "./schema.js"; /* * LandingPage * ├─ title: string * └─ sections: rich_text * ├─ HeroBlock: headline, subtitle, background_image * └─ TestimonialBlock: quote, author_name */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // Create asset by using a local file: const upload = await client.uploads.createFromLocalFile({ localPath: "./2018-10-17-194326.jpg", }); const record = await client.items.create({ item_type: Schema.LandingPage.REF, title: "Product Launch Landing Page", sections: [ // hero block buildBlockRecord({ item_type: Schema.HeroBlock.REF, headline: "Revolutionary New Product", subtitle: "Transform your workflow with our cutting-edge solution.\nBuilt for modern teams.", background_image: { upload_id: upload.id }, }), // testimonial block buildBlockRecord({ item_type: Schema.TestimonialBlock.REF, quote: "This product completely transformed our business operations.", author_name: "Sarah Johnson, CEO", }), ], }); console.log("-- Regular mode --"); console.log(inspectItem(record)); console.log("-- Nested mode --"); const nestedRecord = await client.items.find(record, { nested: true, }); console.log(inspectItem(nestedRecord)); } run(); ``` Returned output ```javascript -- Regular mode -- └ Item "Qw3wP3n8Qf286PjYiYzgXw" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title: "Product Launch Landing Page" └ sections ├ [0]: "XhYlJCL5Rv-2UN2kRXnPcA" └ [1]: "S3hGBEOXTyKfOs6ac4o37Q" -- Nested mode -- └ Item "Qw3wP3n8Qf286PjYiYzgXw" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title: "Product Launch Landing Page" └ sections ├ [0] Item "XhYlJCL5Rv-2UN2kRXnPcA" (item_type: "T4m4tPymSACFzsqbZS65WA") │ ├ headline: "Revolutionary New Product" │ ├ subtitle: "Transform your workflow with our cutting-edge solution.\nBuilt for modern teams." │ └ background_image │ └ upload_id: "VUkBZ214TnK1UeHbJuoAmw" └ [1] Item "S3hGBEOXTyKfOs6ac4o37Q" (item_type: "JItInCQJSIeCLX3oGPvN1w") ├ quote: "This product completely transformed our business operations." └ author_name: "Sarah Johnson, CEO" ``` ###### Example Single block fields This example shows how to create records with single block fields, which allow you to add exactly one block to a field. Unlike modular content fields that can contain multiple blocks, single block fields hold either a single block instance or `null`. The example uses the `buildBlockRecord()` helper function to create the block. You specify the block model ID and provide values for all the block's fields, similar to creating a regular record: Code ```javascript import { buildBlockRecord, buildClient, inspectItem, } from "@datocms/cma-client-node"; import * as Schema from "./schema.js"; /* * ProductPage * ├─ title: string * ├─ price: float * └─ hero_section: single_block * └─ HeroBlock * ├─ headline: string * ├─ description: text * ├─ button: single_block * │ └─ ButtonBlock * │ ├─ text: string * │ └─ url: string * └─ background_image: file */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // Create asset by using a local file: const upload = await client.uploads.createFromLocalFile({ localPath: "./hero-background.jpg", }); const record = await client.items.create({ item_type: Schema.ProductPage.REF, title: "Premium Wireless Headphones", price: 299.99, hero_section: buildBlockRecord({ item_type: Schema.HeroBlock.REF, headline: "Experience Audio Excellence", description: "Immerse yourself in crystal-clear sound with our premium wireless headphones.\nFeatures noise cancellation and 30-hour battery life.", button: buildBlockRecord({ item_type: Schema.ButtonBlock.REF, text: "Learn more", url: "/details", }), background_image: { upload_id: upload.id }, }), }); console.log("-- Regular mode --"); console.log(inspectItem(record)); console.log("-- Nested mode --"); const nestedRecord = await client.items.find(record, { nested: true, }); console.log(inspectItem(nestedRecord)); } run(); ``` Returned output ```javascript -- Regular mode -- └ Item "M54UhYRfQsSz62F1lTMHig" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title: "Premium Wireless Headphones" ├ price: 299.99 └ hero_section: "R9Gt9gafTyaRSa8IFwWJEw" -- Nested mode -- └ Item "M54UhYRfQsSz62F1lTMHig" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title: "Premium Wireless Headphones" ├ price: 299.99 └ hero_section └ Item "R9Gt9gafTyaRSa8IFwWJEw" (item_type: "T4m4tPymSACFzsqbZS65WA") ├ headline: "Experience Audio Excellence" ├ description: "Immerse yourself in crystal-clear sound with our premium wireless headphones...." ├ button │ └ Item "aSFe8RhtThyajM5W3DEUPQ" (item_type: "d-CHYg-rShOt3kiL6ZN1yA") │ ├ text: "Learn more" │ └ url: "/details" └ background_image └ upload_id: "JP0pXTl3S0SFP42PYK2Mug" ``` ###### Example Structured text fields This example demonstrates how to create records with structured text fields that combine rich formatted text with embedded blocks. Structured text is perfect for editorial content where you need to mix paragraphs, headings, and interactive elements seamlessly. The `buildBlockRecord()` helper function simplifies creating embedded blocks, and the example shows how to create upload resources for media content. For more upload creation methods, see the [Create a new upload](/docs/content-management-api/resources/upload/create.md) endpoint documentation. Code ```javascript import { buildBlockRecord, buildClient, inspectItem, } from "@datocms/cma-client-node"; import * as Schema from "./schema.js"; /* * Article * ├─ title: string * └─ content: structured_text * ├─ CtaBlock: title, description, button_text, button_url * └─ ImageGalleryBlock: title, images */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // Create upload resources from URLs (or return existing uploads if already present in the media area): const upload1 = await client.uploads.createFromUrl({ url: "https://picsum.photos/800/600?random=1", skipCreationIfAlreadyExists: true, }); const upload2 = await client.uploads.createFromUrl({ url: "https://picsum.photos/800/600?random=2", skipCreationIfAlreadyExists: true, }); const record = await client.items.create({ item_type: Schema.Article.REF, title: "The Future of Web Development", content: { schema: "dast", document: { type: "root", children: [ // article introduction { type: "paragraph", children: [ { type: "span", marks: [], value: "Web development is rapidly evolving, and new technologies are reshaping how we build digital experiences. In this article, we'll explore the latest trends and tools that are defining the future.", }, ], }, // heading { type: "heading", level: 2, children: [ { type: "span", marks: [], value: "Key Technologies to Watch", }, ], }, // paragraph with formatting { type: "paragraph", children: [ { type: "span", marks: [], value: "From ", }, { type: "span", marks: ["strong"], value: "serverless architectures", }, { type: "span", marks: [], value: " to ", }, { type: "span", marks: ["emphasis"], value: "edge computing", }, { type: "span", marks: [], value: ", developers now have unprecedented tools for building scalable applications.", }, ], }, // image gallery block { type: "block", item: buildBlockRecord({ item_type: Schema.ImageGalleryBlock.REF, title: "Modern Development Environments", images: [ { upload_id: upload1.id, alt: "Modern IDE setup", title: "Development Environment", }, { upload_id: upload2.id, alt: "Code collaboration tools", title: "Team Collaboration", }, ], }), }, // another paragraph { type: "paragraph", children: [ { type: "span", marks: [], value: "As we look ahead, the integration of AI-powered tools and improved developer experiences will continue to accelerate innovation in our field.", }, ], }, // call-to-action block { type: "block", item: buildBlockRecord({ item_type: Schema.CtaBlock.REF, title: "Ready to Level Up Your Skills?", description: "Join our community of forward-thinking developers and stay ahead of the curve with cutting-edge tutorials, tools, and insights.", button_text: "Join the Community", button_url: "https://example.com/join", }), }, ], }, }, }); console.log("-- Regular mode --"); console.log(inspectItem(record)); console.log("-- Nested mode --"); const nestedRecord = await client.items.find(record, { nested: true, }); console.log(inspectItem(nestedRecord)); } run(); ``` Returned output ```javascript -- Regular mode -- └ Item "F50TH6XjSiqyMfezCmra0w" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title: "The Future of Web Development" └ content ├ paragraph │ └ span "Web development is rapidly evolving, and new technologies are reshapi..." ├ heading (level: 2) │ └ span "Key Technologies to Watch" ├ paragraph │ ├ span "From " │ ├ span (marks: strong) "serverless architectures" │ ├ span " to " │ ├ span (marks: emphasis) "edge computing" │ └ span ", developers now have unprecedented tools for building scalable appli..." ├ block "WWVn5YmfRfmwWr9rANi_Gg" ├ paragraph │ └ span "As we look ahead, the integration of AI-powered tools and improved de..." └ block "aciFN9_oRvWNjy7XIcm-9A" -- Nested mode -- └ Item "F50TH6XjSiqyMfezCmra0w" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title: "The Future of Web Development" └ content ├ paragraph │ └ span "Web development is rapidly evolving, and new technologies are reshapi..." ├ heading (level: 2) │ └ span "Key Technologies to Watch" ├ paragraph │ ├ span "From " │ ├ span (marks: strong) "serverless architectures" │ ├ span " to " │ ├ span (marks: emphasis) "edge computing" │ └ span ", developers now have unprecedented tools for building scalable appli..." ├ block │ └ Item "WWVn5YmfRfmwWr9rANi_Gg" (item_type: "cSxBMd9XRWGGvq6xQ0qYDg") │ ├ title: "Modern Development Environments" │ └ images │ ├ [0] │ │ ├ upload_id: "LkyN_T-oTq-o0RGt9EDUMQ" │ │ ├ alt: "Modern IDE setup" │ │ └ title: "Development Environment" │ └ [1] │ ├ upload_id: "YptkFcGyRXi3QOTUymmm2A" │ ├ alt: "Code collaboration tools" │ └ title: "Team Collaboration" ├ paragraph │ └ span "As we look ahead, the integration of AI-powered tools and improved de..." └ block └ Item "aciFN9_oRvWNjy7XIcm-9A" (item_type: "T4m4tPymSACFzsqbZS65WA") ├ title: "Ready to Level Up Your Skills?" ├ description: "Join our community of forward-thinking developers and stay ahead of the curve..." ├ button_text: "Join the Community" └ button_url: "https://example.com/join" ``` #### Asset & Link Fields These reference fields require specific formats. For a comprehensive breakdown of the expected format for every field type, please refer to the **[Field Types Overview](/docs/content-management-api/resources/item.md#field-types-overview)** in our main records guide. ###### Example Linking assets to records This example shows how to create records that include image or file assets. You can work with both single assets and asset galleries by referencing existing uploads or creating new ones. The example demonstrates two approaches: - **Single asset field**: Reference an upload with optional metadata overrides - **Asset gallery field**: Create arrays of asset objects with custom properties like alt text, title, focal points, and custom data You can create new uploads from URLs using `client.uploads.createFromUrl()` or reference existing uploads from your media library. For more upload creation methods, see the [Create a new upload](/docs/content-management-api/resources/upload/create.md) endpoint documentation. Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import * as Schema from "./schema.js"; /* * Portfolio * ├─ title: string * ├─ featured_image: file * └─ gallery: gallery */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // create upload resource using URL (or return an existing upload if it's already present in the media area): const upload1 = await client.uploads.createFromUrl({ url: "https://picsum.photos/800/600?random=3", skipCreationIfAlreadyExists: true, }); // create upload resource using local file (or return an existing upload if it's already present in the media area): const upload2 = await client.uploads.createFromLocalFile({ localPath: "./local.jpg", skipCreationIfAlreadyExists: true, }); const record = await client.items.create({ item_type: Schema.Portfolio.REF, title: "Architecture Photography", featured_image: { // in this case we're just passing the upload ID, as the // upload resource's defaults for alt, title, etc. are fine: upload_id: upload1.id, }, gallery: [ // here we want to override the upload resource's defaults: { upload_id: upload2.id, alt: "Modern architecture", title: "Urban Design", focal_point: { x: 0.3, y: 0.2, }, custom_data: { add_watermark: true, }, }, ], }); console.log(inspectItem(record)); } run(); ``` Returned output ```javascript └ Item "LXN7jVhLTKaui_1dD9gLXA" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title: "Architecture Photography" ├ featured_image │ └ upload_id: "HWhE3MhgTxCfqRfIMGW7Jg" └ gallery └ [0] ├ upload_id: "KJQT9BgrRjKJPALM9fsXgA" ├ alt: "Modern architecture" ├ title: "Urban Design" ├ custom_data: {"add_watermark":true} └ focal_point: x=30% y=20% ``` ###### Example Linking records to other records This example shows how to create records that reference other existing records through link fields. The process involves first retrieving the records you want to link to, then referencing them by their IDs when creating the new record. Link fields can be either single links (referencing one record) or multiple links (referencing an array of records). The example demonstrates both scenarios and shows how to query for existing records before creating the relationships. Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import * as Schema from "./schema.js"; /* * Author * ├─ name: string * ├─ collaborators: links * └─ mentor: link */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // Let's retrieve some other authors first const otherAuthors = await client.items.list({ filter: { type: "author" }, version: "current", }); if (otherAuthors.length === 0) { throw new Error("This example expects at least one record!"); } const record = await client.items.create({ item_type: Schema.Author.REF, name: "Sarah Johnson", collaborators: otherAuthors.map((author) => author.id), mentor: otherAuthors[0]!.id, }); console.log(inspectItem(record)); } run(); ``` Returned output ```javascript └ Item "Eukon4pbSrGyuYPWbmDiPQ" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ name: "Sarah Johnson" ├ collaborators │ ├ [0]: "EF-CHNzIRAeFbt2ACY-K2Q" │ ├ [1]: "MeYQG9_HTEi0ZwhQi7kffA" │ └ [2]: "fHgaJ1AaTZm-U6hFdEthgw" └ mentor: "EF-CHNzIRAeFbt2ACY-K2Q" ``` ### Localization If the record's model contains localized fields, your creation payload must adhere to specific rules: - All localized fields in a single payload must specify the same set of locales to ensure consistency. - If the model is configured to require all locales ([`all_locales_required`](/docs/content-management-api/resources/item-type.md#object-payload)), then the payload must include a key for every available locale for each localized field. The value of a field for a locale can be `null`, but the key itself is mandatory. For a full explanation of how to structure localized data, refer to the [localization Guide](/docs/content-management-api/resources/item.md#localization). ###### Example Managing localized fields The code shows two scenarios: 1. Providing content for a subset of available locales (`en`, `it`) with consistent locale keys across all localized fields 2. Including all available locales (`en`, `it`, `fr`) even when some translations are `null` Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import * as Schema from "./schema.js"; /* * Pet * ├─ name: string (localized) * ├─ description: string (localized) * └─ category: string */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // Example 1: Basic localization - consistent locales across all localized fields const basicRecord = await client.items.create({ item_type: Schema.Pet.REF, name: { en: "Sir Fluffington McWhiskers", it: "Signor Pelosetto Baffetti", }, description: { en: "A noble cat with an impeccable mustache.", it: "Un gatto nobile con baffi impeccabili.", }, // Non-localized field - single value for all locales category: "indoor", }); console.log("-- Basic record --"); console.log(inspectItem(basicRecord)); // Example 2: When all_locales_required is true - must include all locales // even if some values are null const allLocalesRecord = await client.items.create({ item_type: Schema.Pet.REF, name: { en: "Luna", it: "Luna", fr: null, // Translation not ready yet, but key is required }, description: { en: "A mysterious black cat that appears at midnight.", it: "Un gatto nero misterioso che appare a mezzanotte.", fr: null, // Translation not ready yet, but key is required }, category: "outdoor", }); console.log("-- All locales record --"); console.log(inspectItem(allLocalesRecord)); } run(); ``` Returned output ```javascript -- Basic record -- └ Item "PHz_ILZNR7uJ-r4PQsHEqg" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ name │ ├ en: "Sir Fluffington McWhiskers" │ └ it: "Signor Pelosetto Baffetti" ├ description │ ├ en: "A noble cat with an impeccable mustache." │ └ it: "Un gatto nobile con baffi impeccabili." └ category: "indoor" -- All locales record -- └ Item "OBvZ6gKbTOSGY7NGB_9fqA" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ name │ ├ en: "Luna" │ ├ fr: "" │ └ it: "Luna" ├ description │ ├ en: "A mysterious black cat that appears at midnight." │ ├ fr: "" │ └ it: "Un gatto nero misterioso che appare a mezzanotte." └ category: "outdoor" ``` ## Body parameters **`id`** - Optional - Type: string - Example: `"hWl-mnkWRYmMCSTq4z_piQ"` RFC 4122 UUID of record expressed in URL-safe base64 format **`meta.created_at`** - Optional - Type: string Date of creation **`meta.first_published_at`** - Optional - Type: null, string Date of first publication **`item_type`** - Required - Type: [ResourceLinkage\<"item_type"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item_type.md) The record's model **`creator`** - Optional - Type: [ResourceLinkage\<"account"\>](https://www-draft.datocms.com/docs/content-management-api/resources/account.md), [ResourceLinkage\<"access_token"\>](https://www-draft.datocms.com/docs/content-management-api/resources/access_token.md), [ResourceLinkage\<"user"\>](https://www-draft.datocms.com/docs/content-management-api/resources/user.md), [ResourceLinkage\<"sso_user"\>](https://www-draft.datocms.com/docs/content-management-api/resources/sso_user.md), [ResourceLinkage\<"organization"\>](https://www-draft.datocms.com/docs/content-management-api/resources/organization.md) The entity (account/collaborator/access token/sso user) who created the record ## Returns Returns a resource object of type [item](/docs/content-management-api/resources/item.md) ## Other examples ###### Example Tree-like structure This example demonstrates how to create records in tree-structured collections, where records can form hierarchical relationships with parent-child connections. Tree structures are useful for navigation menus, category hierarchies, organizational charts, and any content that needs nested organization. When creating records in tree-like collections, you can specify: - **`parent_id`**: Links the record to its parent in the hierarchy - **`position`**: Sets the ordering among sibling records The example shows how to build a hierarchy by creating records that reference each other: Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import * as Schema from "./schema.js"; /* * Category * ├─ name: string * ├─ position: integer * └─ parent_id: string */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const parent = await client.items.create({ item_type: Schema.Category.REF, name: "Parent", }); console.log(inspectItem(parent)); const child1 = await client.items.create({ item_type: Schema.Category.REF, name: "Child 1", parent_id: parent.id, position: 1, }); console.log(inspectItem(child1)); const child2 = await client.items.create({ item_type: Schema.Category.REF, name: "Child 2", parent_id: parent.id, position: 2, }); console.log(inspectItem(child2)); } run(); ``` Returned output ```javascript └ Item "Ov5N1h4_QwW89_IzbUBb4g" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ name: "Parent" ├ position: 1 └ parent_id: null └ Item "a8A-nl0cRXCqBNniQMAxog" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ name: "Child 1" ├ position: 1 └ parent_id: "Ov5N1h4_QwW89_IzbUBb4g" └ Item "d6Gl9tPMSTqSF2bOMIcOYw" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ name: "Child 2" ├ position: 2 └ parent_id: "Ov5N1h4_QwW89_IzbUBb4g" ``` --- # Content Management API — Duplicate a record Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item/duplicate.md ## Returns Returns a resource object of type [item](/docs/content-management-api/resources/item.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemId = "hWl-mnkWRYmMCSTq4z_piQ"; const item = await client.items.duplicate(itemId); // Check the 'Returned output' tab for the result ☝️ console.log(item); } run(); ``` Returned output ```javascript { id: "hWl-mnkWRYmMCSTq4z_piQ", title: "My first blog post!", content: "Lorem ipsum dolor sit amet...", category: "24", image: { alt: "Alt text", title: "Image title", custom_data: {}, focal_point: null, upload_id: "20042921", }, meta: { created_at: "2020-04-21T07:57:11.124Z", updated_at: "2020-04-21T07:57:11.124Z", published_at: "2020-04-21T07:57:11.124Z", first_published_at: "2020-04-21T07:57:11.124Z", publication_scheduled_at: "2020-04-21T07:57:11.124Z", unpublishing_scheduled_at: "2020-04-21T07:57:11.124Z", status: "published", is_current_version_valid: true, is_published_version_valid: true, current_version: "4234", stage: null, has_children: true, }, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, } ``` --- # Content Management API — Update a record Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item/update.md > [!PROTIP] 📚 New to DatoCMS records? > We strongly recommend reading the [Introduction to Records](/docs/content-management-api/resources/item.md) guide first. The payload for updating a record follows the same structure as [creating one](/docs/content-management-api/resources/item/create.md), so that guide is also an essential prerequisite. The fundamental rules for structuring field values (i.e., strings, numbers, objects, references) are the same for both creating and updating records. For a complete reference on how to format the value for every field type, please see the **[Field Types Overview](/docs/content-management-api/resources/item.md#field-types-overview)** in the main records guide. **When updating an existing record, you only need to provide the fields you want to change. Any fields you omit from your payload will remain untouched.** > [!WARNING] ⚠️ Null vs. Omitted Fields > There's a crucial difference between omitting a field and explicitly setting it to `null` or an empty value: > > - **Omitted fields** keep their existing values unchanged > - **Fields set to `null` or empty values** (like `[]` for arrays) are cleared/deleted ###### Example Simple update operation Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import type * as Schema from "./schema.js"; /* * BlogPost * ├─ title: string * ├─ description: string * ├─ featured_image: file * └─ content_blocks: modular_content * └─ HeroBlock: headline */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const record = await client.items.find( "T4m4tPymSACFzsqbZS65WA", { nested: true, }, ); console.log("-- BEFORE UPDATE --"); console.log(inspectItem(record)); const item = await client.items.update( "T4m4tPymSACFzsqbZS65WA", { title: "[EDIT] My first blog post!", featured_image: null, content_blocks: [], }, ); console.log("-- AFTER UPDATE --"); console.log(inspectItem(item)); } run(); ``` Returned output ```javascript -- BEFORE UPDATE -- └ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title: "My first blog post!" ├ description: "An introduction to our new blog platform" ├ featured_image: null └ content_blocks └ [0] Item "WtzyjA4sTLiLiOQ9TBNgtQ" (item_type: "DB5xsyzCQ3iHTx0dZPb3sw") └ headline: "Hello!" -- AFTER UPDATE -- └ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title: "[EDIT] My first blog post!" ├ description: "An introduction to our new blog platform" ├ featured_image: null └ content_blocks: [] ``` The following sections highlight the rules and strategies that are specific to the update process. ### TypeScript typing Writing an update payload without typed schemas means writing blind: every field is `unknown`, typos compile fine, and mistakes only surface as `422`s from the API. The single biggest lever you have is passing a [generated `Schema.X` marker](https://www.datocms.com/cma-ts-schema.md) as the generic on `items.update`. TypeScript then enforces the model's field names, types, and allowed block shapes at compile time: ```ts // ❌ Untyped: every field is `unknown`, typos compile. await client.items.update("record-id", { /* … */ }); // ✅ Typed: field names, types, and block shapes enforced. await client.items.update("record-id", { /* … */ }); ``` When you're rebuilding a field value piece-by-piece — typically an array of blocks or links — annotate the accumulator with `FieldValueInRequest`. The first argument accepts any item-shaped value the CMA produces (top-level record or nested block, narrowed or not) **or** a `Schema.X` marker directly when no value is in scope yet: ```ts const article = await client.items.find("record-id", { nested: true }); if (article.content) { const content: NonNullable> = /* ...transform article.content... */; await client.items.update("record-id", { content }); } // Same expression on a narrowed nested block: for (const block of article.sections) { if (isBlockOfType(Schema.HeroBlock.ID, block)) { const ctas: NonNullable> = []; // …rebuild the nested field… } } // Or, if you don't have a value yet, pass the marker: type ArticleContent = NonNullable>; ``` > [!WARNING] ⚠️ Field values are always nullable > Even fields with a **required** validator are typed as `Nullable`, because the API may still accept/return `null` in some scenarios. > > The example therefore checks `if (article.content)` and uses `NonNullable<…>` to narrow the type. Without this, accessing nested properties like `content.document.children` would require optional chaining (`?.`). ### Updating Block Fields The general workflow is the same for every block field type: 1. **Generate types** with the [TypeScript schema generator](https://www.datocms.com/cma-ts-schema.md). 2. **Fetch records with `nested: true`** so blocks come back as full objects you can edit. Without it you only get IDs — fine for keep/reorder/delete, not for editing. 3. **Build the payload** following the per-field-type rules below. Lean on the provided helpers as much as possible instead of assembling structures by hand. 4. **Send a single `client.items.update
` call**, omitting fields you don't change. #### Modular Content Payload is an array of blocks. Each entry expresses one operation: | Operation | Entry | | --- | --- | | Keep | block ID string | | Edit | `buildBlockRecord({ id, ...changedAttrs })` | | Create | `buildBlockRecord({ ...allAttrs })` | | Clone | `duplicateBlockRecord(block, schemaRepository)` | | Delete | omit from the array | | Reorder | rearrange the array | ###### Example Managing blocks in Modular Content fields Demonstrates every Modular Content operation in a single `items.update` call — keep, edit, create, clone, delete, and reorder all happen at once — and shows that the same accumulator pattern composes recursively when a block holds its own modular field: - **Create** — top of the array: `buildBlockRecord({ item_type, ...attrs })` (no `id`, since it's brand new). - **Clone** — duplicate the first existing testimonial with `duplicateBlockRecord(block, schemaRepository)`. The helper deep-copies and strips block IDs, so the result becomes a separate block rather than the same one moved. - **Delete** — `.filter(...)` drops the trailing "Start Your Free Trial" CTA. Any block missing from the new array is removed; missing IDs are how the API encodes deletion. - **Edit (flat)** — `buildBlockRecord({ id, button_url })` with only the changed attributes; omitted attributes (`button_text`) stay as-is on the server. - **Edit (nested)** — when the iterated block is a `HeroBlock`, rebuild *its* `ctas` modular array with the **same** accumulator pattern: `NonNullable>` types the inner array, and the inner loop reuses `buildBlockRecord` / bare-ID-string the same way the outer loop does. The pattern composes uniformly to whatever depth the schema reaches. - **Keep** — return the bare ID string. Cheapest possible payload entry, used both at the top level and inside the nested `ctas`. - **Reorder** — implicit; the new array's order *is* the final order. `isBlockOfType(ID)` is the curried predicate for `Array#filter` / `Array#find` and the inline guard inside `.map` callbacks — narrows `block.attributes` and `block.__itemTypeId` to the matching block model. Code ```javascript import { buildBlockRecord, buildClient, duplicateBlockRecord, type FieldValueInRequest, inspectItem, isBlockOfType, SchemaRepository, } from "@datocms/cma-client-node"; import * as Schema from "./schema.js"; /* * LandingPage * ├─ title: string * └─ sections: modular_content * ├─ HeroBlock: headline, subtitle * │ └─ ctas: modular_content * │ └─ ButtonBlock: label, url * ├─ CallToActionBlock: button_text, button_url * └─ TestimonialBlock: quote, author */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const schemaRepository = new SchemaRepository(client); const currentPage = await client.items.find( "W4wcrs_2REiM4fc6dlDZCQ", { nested: true }, ); console.log("-- BEFORE UPDATE --"); console.log(inspectItem(currentPage)); const firstTestimonial = currentPage.sections.find( isBlockOfType(Schema.TestimonialBlock.ID), ); const duplicatedTestimonial = firstTestimonial ? await duplicateBlockRecord( firstTestimonial, schemaRepository, ) : null; const sections: NonNullable< FieldValueInRequest > = [ // Create — fresh CallToActionBlock at the top buildBlockRecord({ item_type: Schema.CallToActionBlock.REF, button_text: "Watch a 2-minute demo", button_url: "https://www.datocms.com/demo", }), // Clone — duplicated testimonial ...(duplicatedTestimonial ? [duplicatedTestimonial] : []), ...currentPage.sections // Delete — drop the trailing CTA by filtering it out .filter( (block) => !( isBlockOfType(Schema.CallToActionBlock.ID, block) && block.attributes.button_text === "Start Your Free Trial" ), ) .map((block) => { if (isBlockOfType(Schema.HeroBlock.ID, block)) { // Edit (nested) — rebuild the HeroBlock's `ctas` using the SAME // accumulator pattern, applied recursively to a nested block's // modular field. const ctas: NonNullable> = block.attributes.ctas.map((cta) => { if ( isBlockOfType(Schema.ButtonBlock.ID, cta) && cta.attributes.label === "Get started" ) { const url = new URL( cta.attributes.url || "https://www.datocms.com", ); url.searchParams.set("utm_source", "hero"); return buildBlockRecord({ id: cta.id, url: url.toString(), }); } return cta.id; }); return buildBlockRecord({ id: block.id, ctas }); } if (isBlockOfType(Schema.CallToActionBlock.ID, block)) { // Edit (flat) const url = new URL( block.attributes.button_url || "https://www.datocms.com", ); url.searchParams.set("utm_source", "landing_page"); url.searchParams.set("utm_medium", "cta"); url.searchParams.set("utm_campaign", "q1_2024"); return buildBlockRecord({ id: block.id, button_url: url.toString(), }); } // Keep — return the bare ID for unchanged blocks return block.id; }), ]; console.log("-- UPDATE OPERATION --"); console.log(inspectItem({ sections })); await client.items.update(currentPage, { sections }); const updatedPage = await client.items.find(currentPage, { nested: true, }); console.log("-- AFTER UPDATE --"); console.log(inspectItem(updatedPage)); } run(); ``` Returned output ```javascript -- BEFORE UPDATE -- └ Item "W4wcrs_2REiM4fc6dlDZCQ" (item_type: "ZV0o9497SsqWxQR8HEQddw") ├ title: "Product Launch Landing Page" └ sections ├ [0] Item "Ngzm6x8JS2y9UuQnTf9wBw" (item_type: "d-CHYg-rShOt3kiL6ZN1yA") │ ├ headline: "Revolutionary New Solution" │ ├ subtitle: "Discover the future of productivity with our cutting-edge platform designed f..." │ └ ctas │ ├ [0] Item "IfiDssuLSEa5HH2-Ce2nCw" (item_type: "TNTfjVnfQieREzX98q3xnw") │ │ ├ label: "Get started" │ │ └ url: "https://www.datocms.com/signup" │ └ [1] Item "IOggXsdxRAmFWCOPhbFXYw" (item_type: "TNTfjVnfQieREzX98q3xnw") │ ├ label: "Read the docs" │ └ url: "https://www.datocms.com/docs" ├ [1] Item "Iu1vi__ASDeDrrpPpKbknQ" (item_type: "I8Q6k-HqQmaZ498WKtvFbg") │ ├ button_text: "Get Started Free" │ └ button_url: "https://www.datocms.com/signup" ├ [2] Item "NxszxFtnSpmftjnxguWPOg" (item_type: "Dy9C52o4S6eF3mqSOmeUtg") │ ├ quote: "This platform completely transformed how our team collaborates. We've seen a ..." │ └ author: "Sarah Chen, Product Manager at TechCorp" ├ [3] Item "MIJbkpwMQiqzwOYQkuAVIw" (item_type: "Dy9C52o4S6eF3mqSOmeUtg") │ ├ quote: "The best investment we've made this year. The ROI was evident within the firs..." │ └ author: "Michael Rodriguez, CTO at InnovateLabs" └ [4] Item "CVcgWRiaRYKF53DvqZHpFA" (item_type: "I8Q6k-HqQmaZ498WKtvFbg") ├ button_text: "Start Your Free Trial" └ button_url: "https://www.datocms.com/trial" -- UPDATE OPERATION -- └ Item └ sections ├ [0] Item (item_type: "I8Q6k-HqQmaZ498WKtvFbg") │ ├ button_text: "Watch a 2-minute demo" │ └ button_url: "https://www.datocms.com/demo" ├ [1] Item (item_type: "Dy9C52o4S6eF3mqSOmeUtg") │ ├ quote: "This platform completely transformed how our team collaborates. We've seen a ..." │ └ author: "Sarah Chen, Product Manager at TechCorp" ├ [2] Item "Ngzm6x8JS2y9UuQnTf9wBw" │ └ ctas │ ├ [0] Item "IfiDssuLSEa5HH2-Ce2nCw" │ │ └ url: "https://www.datocms.com/signup?utm_source=hero" │ └ [1] "IOggXsdxRAmFWCOPhbFXYw" ├ [3] Item "Iu1vi__ASDeDrrpPpKbknQ" │ └ button_url: "https://www.datocms.com/signup?utm_source=landing_page&utm_medium=cta&utm_cam..." ├ [4] "NxszxFtnSpmftjnxguWPOg" └ [5] "MIJbkpwMQiqzwOYQkuAVIw" -- AFTER UPDATE -- └ Item "W4wcrs_2REiM4fc6dlDZCQ" (item_type: "ZV0o9497SsqWxQR8HEQddw") ├ title: "Product Launch Landing Page" └ sections ├ [0] Item "O43QkMpUQFy4mTck48Ayeg" (item_type: "I8Q6k-HqQmaZ498WKtvFbg") │ ├ button_text: "Watch a 2-minute demo" │ └ button_url: "https://www.datocms.com/demo" ├ [1] Item "JQOSGafZTgK1cDWaFgtK9Q" (item_type: "Dy9C52o4S6eF3mqSOmeUtg") │ ├ quote: "This platform completely transformed how our team collaborates. We've seen a ..." │ └ author: "Sarah Chen, Product Manager at TechCorp" ├ [2] Item "Ngzm6x8JS2y9UuQnTf9wBw" (item_type: "d-CHYg-rShOt3kiL6ZN1yA") │ ├ headline: "Revolutionary New Solution" │ ├ subtitle: "Discover the future of productivity with our cutting-edge platform designed f..." │ └ ctas │ ├ [0] Item "IfiDssuLSEa5HH2-Ce2nCw" (item_type: "TNTfjVnfQieREzX98q3xnw") │ │ ├ label: "Get started" │ │ └ url: "https://www.datocms.com/signup?utm_source=hero" │ └ [1] Item "IOggXsdxRAmFWCOPhbFXYw" (item_type: "TNTfjVnfQieREzX98q3xnw") │ ├ label: "Read the docs" │ └ url: "https://www.datocms.com/docs" ├ [3] Item "Iu1vi__ASDeDrrpPpKbknQ" (item_type: "I8Q6k-HqQmaZ498WKtvFbg") │ ├ button_text: "Get Started Free" │ └ button_url: "https://www.datocms.com/signup?utm_source=landing_page&utm_medium=cta&utm_cam..." ├ [4] Item "NxszxFtnSpmftjnxguWPOg" (item_type: "Dy9C52o4S6eF3mqSOmeUtg") │ ├ quote: "This platform completely transformed how our team collaborates. We've seen a ..." │ └ author: "Sarah Chen, Product Manager at TechCorp" └ [5] Item "MIJbkpwMQiqzwOYQkuAVIw" (item_type: "Dy9C52o4S6eF3mqSOmeUtg") ├ quote: "The best investment we've made this year. The ROI was evident within the firs..." └ author: "Michael Rodriguez, CTO at InnovateLabs" ``` #### Single Block A single-block field holds at most one block (or `null`), so the payload is the value itself — not an array. The Modular Content rules apply, minus anything position-related. ###### Example Managing Single Block fields Demonstrates every Single Block operation across multiple `items.update` calls — the field holds at most one block (or `null`): - **Edit** — `buildBlockRecord({ id, button_text, style })` keeps the same block ID, changes the listed attributes, leaves the rest (`button_url`) untouched. - **Replace via duplicate** — `duplicateBlockRecord(currentProduct.hero_section, schemaRepository)` deep-copies and strips IDs; the slot ends up with a brand-new block, not the same one re-used. - **Replace with a different block type** — `buildBlockRecord({ item_type, ...attrs })` swaps the slot's model entirely (no `id`, since the block doesn't exist yet). - **Delete** — set the field to `null`. Omitting the field would leave the existing block in place (see the parent guide's null-vs-omit warning). The response uses `__itemTypeId` as a discriminant: narrowing on it (`if (currentProduct.hero_section.__itemTypeId === CTA_ID)`) lets TypeScript see the matching block-model attributes before any string ops. Code ```javascript import { type ApiTypes, buildBlockRecord, buildClient, duplicateBlockRecord, inspectItem, SchemaRepository, } from "@datocms/cma-client-node"; import * as Schema from "./schema.js"; /* * ProductPage * ├─ title: string * ├─ price: float * └─ hero_section: single_block * ├─ HeroBlock: headline, description, background_image * ├─ CallToActionBlock: button_text, button_url, style * └─ VideoBlock: video_url, thumbnail_image, autoplay */ // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); async function run() { const schemaRepository = new SchemaRepository(client); const currentProduct = await client.items.find( "W4wcrs_2REiM4fc6dlDZCQ", { nested: true }, ); console.log("-- BEFORE UPDATE --"); console.log(inspectItem(currentProduct)); if ( currentProduct.hero_section && currentProduct.hero_section.__itemTypeId === Schema.CallToActionBlock.ID ) { await client.items.update(currentProduct, { hero_section: buildBlockRecord({ id: currentProduct.hero_section.id, button_text: currentProduct.hero_section.attributes.button_text?.toUpperCase() || "SHOP NOW", style: "primary-large", }), }); console.log("-- EXISTING BLOCK UPDATED --"); await inspectItemWithNestedBlocks(currentProduct); } await client.items.update(currentProduct, { hero_section: await duplicateBlockRecord< Schema.HeroBlock | Schema.CallToActionBlock | Schema.VideoBlock >(currentProduct.hero_section!, schemaRepository), }); console.log("-- BLOCK DUPLICATE --"); await inspectItemWithNestedBlocks(currentProduct); const upload = await client.uploads.createFromUrl({ url: "https://picsum.photos/800/600?random=1", }); const productWithVideo = await client.items.update( currentProduct, { hero_section: buildBlockRecord({ item_type: Schema.VideoBlock.REF, video_url: "https://videos.datocms.com/product-demo.mp4", thumbnail_image: { upload_id: upload.id }, autoplay: false, }), }, ); console.log("-- BLOCK REPLACED --"); await inspectItemWithNestedBlocks(currentProduct); await client.items.update(productWithVideo, { hero_section: null, }); console.log("-- BLOCK REMOVED --"); await inspectItemWithNestedBlocks(currentProduct); } run(); async function inspectItemWithNestedBlocks(item: ApiTypes.Item) { const itemWithNestedBlocks = await client.items.find(item, { nested: true, }); console.log(inspectItem(itemWithNestedBlocks)); } ``` Returned output ```javascript -- BEFORE UPDATE -- └ Item "W4wcrs_2REiM4fc6dlDZCQ" (item_type: "ZV0o9497SsqWxQR8HEQddw") ├ title: "Premium Wireless Headphones" ├ price: 299.99 └ hero_section └ Item "MolF0AwpSLeXrdE5kdcEtw" (item_type: "I8Q6k-HqQmaZ498WKtvFbg") ├ button_text: "Buy Now" ├ button_url: "https://example.com/buy" └ style: "primary" -- EXISTING BLOCK UPDATED -- └ Item "W4wcrs_2REiM4fc6dlDZCQ" (item_type: "ZV0o9497SsqWxQR8HEQddw") ├ title: "Premium Wireless Headphones" ├ price: 299.99 └ hero_section └ Item "MolF0AwpSLeXrdE5kdcEtw" (item_type: "I8Q6k-HqQmaZ498WKtvFbg") ├ button_text: "BUY NOW" ├ button_url: "https://example.com/buy" └ style: "primary-large" -- BLOCK DUPLICATE -- └ Item "W4wcrs_2REiM4fc6dlDZCQ" (item_type: "ZV0o9497SsqWxQR8HEQddw") ├ title: "Premium Wireless Headphones" ├ price: 299.99 └ hero_section └ Item "QXqFgPHVTfq8F1tOmQEwEg" (item_type: "I8Q6k-HqQmaZ498WKtvFbg") ├ button_text: "Buy Now" ├ button_url: "https://example.com/buy" └ style: "primary" -- BLOCK REPLACED -- └ Item "W4wcrs_2REiM4fc6dlDZCQ" (item_type: "ZV0o9497SsqWxQR8HEQddw") ├ title: "Premium Wireless Headphones" ├ price: 299.99 └ hero_section └ Item "JIHRl3kyQiGXAJHcP-7v7Q" (item_type: "Dy9C52o4S6eF3mqSOmeUtg") ├ video_url: "https://videos.datocms.com/product-demo.mp4" ├ thumbnail_image │ └ upload_id: "WwqHexgISQqQdMKJSYE8VA" └ autoplay: false -- BLOCK REMOVED -- └ Item "W4wcrs_2REiM4fc6dlDZCQ" (item_type: "ZV0o9497SsqWxQR8HEQddw") ├ title: "Premium Wireless Headphones" ├ price: 299.99 └ hero_section: null ``` #### Structured Text Structured Text stores rich content as a [DAST](/docs/structured-text/dast.md) tree. Embedded records show up as two extra node kinds: `block` and `inlineBlock`. Both wrap a full DatoCMS block, so the same `buildBlockRecord`/`duplicateBlockRecord` primitives from Modular Content and Single Block still apply, but they're composed inside a tree-mutation pipeline rather than dropped into an array slot. The pipeline has two passes, each exposing the document at a different level of granularity. Pick the highest-level pass that can still see what you want to change. Going lower buys you more power but costs you a lot of tree gymnastics. ###### Pass 1: Rewrite the prose (dastdown) [`datocms-structured-text-dastdown`](https://github.com/datocms/structured-text/tree/main/packages/dastdown) translates the DAST tree to and from a markdown-like text format: ```markdown A normal paragraph with ==highlighted==, ++underlined++ and ~~struck~~ text. Links can carry trailers: [our docs](https:datocms.com){target="_blank"}. References to other records read like [this article](dato:item/abc123), or inline as . > A pull quote from the interview. > {attribution="Jane Doe"} Inline blocks sit mid-sentence. ``` This allows you to make changes with ordinary string operations and let `parse()` rebuild the tree: ```ts import { parse, serialize } from "datocms-structured-text-dastdown"; const text = serialize(currentRecord.content); const edited = text .replace(/Jane Doe/g, "Jane Smith") .replace(/==([^=]+)==/g, "**$1**"); const content = parse(edited, currentRecord.content); ``` Blocks appear in dastdown only as ID placeholders: you can move or delete them, but you can't touch what's inside. If you can describe the change as something you'd do in a text editor — find-and-replace, rewriting a paragraph, reshaping a list — `dastdown` is the right tool. It also wins on the opposite end of the spectrum from Pass 2: one-off spot edits, and agentic flows where an LLM reads the serialized text and rewrites it directly. ###### Pass 2: Mutate the tree (`mapNodes` + block helpers) Reach for Pass 2 when dastdown can't see what you want to change — anything that depends on node *kind* rather than text, or on a block's *internal fields* rather than its position. Both flavors of edit live inside the same `mapNodes` walk: - **Transforming prose nodes.** Rewrite every link's URL, lowercase every heading, bump every `level: 2` heading to `level: 3`, drop every empty paragraph, wrap every occurrence of "click here" in a link. dastdown is the right tool while edits stay mostly text-shaped; once you find yourself writing regex to fish node kinds back out of the serialized form, the AST is the cleaner layer. - **Editing or building embedded blocks.** Edit a block's attributes, swap it for another, or drop a brand-new block into the tree. Embedded blocks are opaque to Pass 1 (dastdown serializes them to `` placeholders that hide their fields), so anything touching block contents lands here. Use `buildBlockRecord` to shape the payload — pass an `id` to edit an existing block, omit it to create a new one — and `duplicateBlockRecord` to deep-clone one. `mapNodes` from `datocms-structured-text-utils` walks the tree **bottom-up** (a node's descendants have already been transformed by the time the callback sees it, and what you return for that node is final). Return one node (1:1, the default), an array splatted into siblings (1:N — split, wrap, insert), or `null`/`undefined` to drop (1:0 — illegal at the root). When a node doesn't need to change, just `return node`. The CMA accepts the nested-response shape it came in as. **Adding root-level nodes** (a brand-new paragraph, a fresh top-level block) sits just outside the callback: `mapNodes` can't splat at the root, so push directly into `content.document.children` after the walk — using `buildBlockRecord` / `duplicateBlockRecord` to shape any new `block` entry. > [!WARNING] ⚠️ Combine passes in order: 1 → 2 > Pass 1's `parse()` uses the *original* document as the lookup table for `` placeholders. A block created by Pass 2 first would either be missing from that lookup (and `parse` throws) or get silently overwritten when Pass 1 rehydrates. If you need both, always run Pass 1 before Pass 2. ###### Example Pass 1: Prose edits via dastdown Demonstrates Pass 1 (dastdown round-trip) on a structured-text field with no embedded blocks. Three text-level transformations expressed as plain string operations: - **Brand swap** — `text.replace(/ZEIT/g, "Vercel")` rewrites every occurrence across spans, headings, and link text in a single regex. - **Autolink emails** — turn bare addresses into markdown links: `support@example.com` → `[support@example.com](mailto:support@example.com)`. - **Set `target="_blank"` on a specific link** — append the dastdown link-meta trailer `{target="_blank"}` to the matching `(url)`. The negative lookahead `(?!\{)` makes the regex idempotent (a second run is a no-op). Block placeholders aren't relevant here, but `parse(text, currentGuide.body)` always uses the second argument as the `` lookup table; missing IDs throw, which is the signal to fall back to Pass 2. Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import { parse, serialize } from "datocms-structured-text-dastdown"; import type * as Schema from "./schema.js"; /* * Guide * ├─ title: string * └─ body: structured_text (no embedded blocks for this example) */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const currentGuide = await client.items.find( "Q9zHRrIESkGYBV3hVVe2Hg", ); // `currentGuide.body` is typed nullable — guard before touching the document. // Wrapping in `if (currentGuide.body) { ... }` also avoids a top-level // `return`, letting peek + mutate live in a single script. if (currentGuide.body) { console.log("-- BEFORE UPDATE --"); console.log(inspectItem(currentGuide)); const text = serialize(currentGuide.body); const edited = text .replace(/ZEIT/g, "Vercel") .replace(/(\b[\w.+-]+@[\w-]+\.[\w.-]+\b)/g, "[$1](mailto:$1)") .replace( /\(https:\/\/example\.com\/migration\)(?!\{)/g, '(https://example.com/migration){target="_blank"}', ); // 2nd arg is the lookup table for `` placeholders; missing IDs throw. const body = parse(edited, currentGuide.body); await client.items.update(currentGuide.id, { body }); console.log("-- AFTER UPDATE --"); console.log( inspectItem(await client.items.find(currentGuide.id)), ); } } run(); ``` Returned output ```javascript -- BEFORE UPDATE -- └ Item "Q9zHRrIESkGYBV3hVVe2Hg" (item_type: "f6sjkkPgQGiSDi6lwG3UjA") ├ title: "Deploying with ZEIT" └ body ├ heading (level: 1) │ └ span "Deploying with ZEIT" ├ paragraph │ └ span "ZEIT lets you ship static sites and serverless functions in seconds. ..." └ paragraph ├ span "Read our " ├ link (url: "https://example.com/migration") │ └ span "migration guide" └ span " before upgrading from ZEIT v1." -- AFTER UPDATE -- └ Item "Q9zHRrIESkGYBV3hVVe2Hg" (item_type: "f6sjkkPgQGiSDi6lwG3UjA") ├ title: "Deploying with ZEIT" └ body ├ heading (level: 1) │ └ span "Deploying with Vercel" ├ paragraph │ ├ span "Vercel lets you ship static sites and serverless functions in seconds..." │ ├ link (url: "mailto:support@zeit.co") │ │ └ span "support@zeit.co" │ └ span " for help." └ paragraph ├ span "Read our " ├ link (url: "https://example.com/migration", meta: {target="_blank"}) │ └ span "migration guide" └ span " before upgrading from Vercel v1." ``` ###### Example Pass 2: Node transformations Demonstrates Pass 2 on prose nodes — `mapNodes` with one of each return mode (1:1 transforms, 1:0 drop) plus a post-walk root-level append. The callback applies five edits across the tree: - **Demote `h1` → `h2`** for hierarchy hygiene (`as const` keeps the literal `level` type). - **Bold every span that mentions the brand**, deduping the `marks` array with a `Set` (canonical marks: `'strong' | 'emphasis' | 'code' | 'underline' | 'strikethrough' | 'highlight'`). - **Brand swap** — `value.replace(/ZEIT/g, "Vercel")` on every matching span. - **Add `target="_blank"`** to `link` and `itemLink` nodes, deduping any prior `target` entry in `meta`. - **Drop empty paragraphs** by returning `null` from the callback. After `mapNodes` returns, a fresh paragraph is pushed into `content.document.children` — root-level inserts can't go through the callback (splat-at-root throws). Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import { isHeading, isItemLink, isLink, isParagraph, isSpan, mapNodes, reduceNodes, } from "datocms-structured-text-utils"; import type * as Schema from "./schema.js"; /* * BlogPost * ├─ title: string * ├─ slug: string * └─ content: structured_text (no embedded blocks for this example) */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const currentPost = await client.items.find( "T4m4tPymSACFzsqbZS65WA", ); // Guard the nullable field — also keeps peek + mutate in a single script // without a top-level `return`. if (currentPost.content) { console.log("-- BEFORE UPDATE --"); console.log(inspectItem(currentPost)); const content = mapNodes(currentPost.content, (node) => { if (isHeading(node) && node.level === 1) { // `as const` preserves the literal `2` instead of widening to `number`. return { ...node, level: 2 as const }; } if (isSpan(node) && node.value.includes("ZEIT")) { const marks = new Set(node.marks ?? []); marks.add("strong"); return { ...node, value: node.value.replace(/ZEIT/g, "Vercel"), marks: [...marks], }; } if (isLink(node) || isItemLink(node)) { const meta = [ ...(node.meta ?? []).filter((m) => m.id !== "target"), { id: "target", value: "_blank" }, ]; return { ...node, meta }; } if ( isParagraph(node) && reduceNodes( node, (acc, n) => (isSpan(n) ? acc + n.value.trim() : acc), "", ).length === 0 ) { return null; } return node; }); // Root-level inserts can't go through `mapNodes` (splat-at-root throws); push directly. content.document.children.push({ type: "paragraph", children: [{ type: "span", value: "Last updated by the content team." }], }); await client.items.update(currentPost.id, { content }); console.log("-- AFTER UPDATE --"); console.log( inspectItem(await client.items.find(currentPost.id)), ); } } run(); ``` Returned output ```javascript -- BEFORE UPDATE -- └ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title: "What is ZEIT?" ├ slug: "what-is-zeit" └ content ├ heading (level: 1) │ └ span "Understanding ZEIT" ├ paragraph │ └ span "ZEIT is a cloud platform for static sites and serverless functions. I..." ├ paragraph │ └ span "" ├ paragraph │ └ span "" ├ heading (level: 1) │ └ span "Key Features" ├ paragraph │ ├ span "ZEIT offers automatic HTTPS, global CDN distribution, and instant dep..." │ ├ link (url: "https://example.com/blog") │ │ └ span "detailed comparison" │ └ span " for more insights." └ paragraph ├ span "Visit our " ├ itemLink (item: "fpgJWZadRI66eqXB-ucSSQ") │ └ span "migration guide" └ span " for step-by-step instructions." -- AFTER UPDATE -- └ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title: "What is ZEIT?" ├ slug: "what-is-zeit" └ content ├ heading (level: 2) │ └ span (marks: strong) "Understanding Vercel" ├ paragraph │ └ span (marks: strong) "Vercel is a cloud platform for static sites and serverless functions...." ├ heading (level: 2) │ └ span "Key Features" ├ paragraph │ ├ span (marks: strong) "Vercel offers automatic HTTPS, global CDN distribution, and instant d..." │ ├ link (url: "https://example.com/blog", meta: {target="_blank"}) │ │ └ span "detailed comparison" │ └ span " for more insights." ├ paragraph │ ├ span "Visit our " │ ├ itemLink (item: "fpgJWZadRI66eqXB-ucSSQ", meta: {target="_blank"}) │ │ └ span "migration guide" │ └ span " for step-by-step instructions." └ paragraph └ span "Last updated by the content team." ``` ###### Example Pass 2 (cont.): Editing & creating embedded blocks Demonstrates Pass 2 on embedded blocks — editing block attributes from inside a `mapNodes` callback, then duplicating and appending a block after the walk. What the script does: - **Edit CTA blocks**: rewrite `button_url` from `old-domain.com` to `new-domain.com`, returning `{ ...node, item: buildBlockRecord({ id, button_url }) }` from the `mapNodes` callback. - **Tag inline product mentions**: append `?source=article_mention` to `affiliate_url` with the same pattern, narrowing via `isInlineBlockWithItemOfType`. - **Pass through unmatched blocks** (the `ImageGalleryBlock` here) with a bare `return node` — the CMA accepts the nested-response shape it came in as. - **Duplicate the first CTA** with `duplicateBlockRecord` and push it as a new root-level child, *after* `mapNodes` runs. A few things to notice: - **`isBlockWithItemOfType` has two call styles.** `isBlockWithItemOfType(ID, node)` is the inline form for `if`; the curried form `isBlockWithItemOfType(ID)` is the predicate for `findFirstNode` / `Array#find` / `Array#filter`. Same guard, different ergonomics. With `ID` declared `as const`, both auto-narrow `node.item` to the matching block-model shape. - **Source the duplicate from the original tree.** Look up the source block on `currentArticle.content` (the original response), not on the mapped result — `mapNodes` is allowed to rewrite `node.item`, so the post-map tree is not a reliable source for cloning. Code ```javascript import { buildBlockRecord, buildClient, duplicateBlockRecord, type FieldValueInRequest, inspectItem, SchemaRepository, } from "@datocms/cma-client-node"; import { findFirstNode, isBlockWithItemOfType, isInlineBlockWithItemOfType, mapNodes, } from "datocms-structured-text-utils"; import * as Schema from "./schema.js"; /* * Article * ├─ title: string * ├─ author: string * └─ content: structured_text * ├─ CtaBlock: title, description, button_text, button_url * ├─ ProductMentionInline: product_name, price, affiliate_url * └─ ImageGalleryBlock: title, images */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // `duplicateBlockRecord` looks up nested-block field definitions through this. const repo = new SchemaRepository(client); const currentArticle = await client.items.find( "RSfdsZbbR7ixGgMBSmcaVA", { nested: true, }, ); // Guard the nullable field — also keeps peek + mutate in a single script // without a top-level `return`. if (currentArticle.content) { console.log("-- BEFORE UPDATE --"); console.log(inspectItem(currentArticle)); let content: NonNullable< FieldValueInRequest > = currentArticle.content; content = mapNodes(content, (node) => { if (isBlockWithItemOfType(Schema.CtaBlock.ID, node)) { const url = node.item.attributes.button_url; if (url?.includes("old-domain.com")) { return { ...node, item: buildBlockRecord({ id: node.item.id, button_url: url.replace("old-domain.com", "new-domain.com"), }), }; } } if (isInlineBlockWithItemOfType(Schema.ProductMentionInline.ID, node)) { const raw = node.item.attributes.affiliate_url; if (raw) { const url = new URL(raw); url.searchParams.set("source", "article_mention"); return { ...node, item: buildBlockRecord({ id: node.item.id, affiliate_url: url.toString(), }), }; } } return node; }); // Source the duplicate from the original tree: `mapNodes` may have // rewritten `node.item`, so post-map `content` is not safe to clone from. const firstCta = findFirstNode( currentArticle.content, isBlockWithItemOfType(Schema.CtaBlock.ID), ); if (firstCta) { const dup = await duplicateBlockRecord( firstCta.node.item, repo, ); content.document.children.push({ type: "block", item: dup }); } await client.items.update(currentArticle.id, { content }); console.log("-- AFTER UPDATE --"); console.log( inspectItem( await client.items.find(currentArticle.id, { nested: true, }), ), ); } } run(); ``` Returned output ```javascript -- BEFORE UPDATE -- └ Item "RSfdsZbbR7ixGgMBSmcaVA" (item_type: "ZV0o9497SsqWxQR8HEQddw") ├ title: "The Future of E-commerce Technology" ├ author: "Alex Thompson" └ content ├ paragraph │ ├ span "E-commerce is evolving rapidly with new technologies like " │ ├ inlineBlock │ │ └ Item "LQlcO4LCTYaOrfj2A705DQ" (item_type: "VGXgXav9SwG5P48frGrFxA") │ │ ├ product_name: "AI Shopping Assistant" │ │ ├ price: 99.99 │ │ └ affiliate_url: "https://old-domain.com/product?ref=blog" │ └ span " transforming how customers shop online." ├ block │ └ Item "FqTxaDO8TJmtkoTgDjbK8Q" (item_type: "d-CHYg-rShOt3kiL6ZN1yA") │ ├ title: "Join the Revolution" │ ├ description: "Stay ahead of the curve with our e-commerce insights." │ ├ button_text: "Subscribe Now" │ └ button_url: "https://old-domain.com/subscribe" └ block └ Item "JwT0hvgiR4WB0-SO9QG7Ig" (item_type: "I8Q6k-HqQmaZ498WKtvFbg") ├ title: "E-commerce Innovation Gallery" └ images ├ [0] │ ├ upload_id: "eLVHtrefRUq7qkVMpzG6mQ" │ ├ alt: "Modern e-commerce interface" │ └ title: "Next-gen Shopping" └ [1] ├ upload_id: "UFIyIRQFT1GQ7YAG34ub5w" ├ alt: "AI-powered recommendations" └ title: "Smart Product Discovery" -- AFTER UPDATE -- └ Item "RSfdsZbbR7ixGgMBSmcaVA" (item_type: "ZV0o9497SsqWxQR8HEQddw") ├ title: "The Future of E-commerce Technology" ├ author: "Alex Thompson" └ content ├ paragraph │ ├ span "E-commerce is evolving rapidly with new technologies like " │ ├ inlineBlock │ │ └ Item "LQlcO4LCTYaOrfj2A705DQ" (item_type: "VGXgXav9SwG5P48frGrFxA") │ │ ├ product_name: "AI Shopping Assistant" │ │ ├ price: 99.99 │ │ └ affiliate_url: "https://old-domain.com/product?ref=blog&source=article_mention" │ └ span " transforming how customers shop online." ├ block │ └ Item "FqTxaDO8TJmtkoTgDjbK8Q" (item_type: "d-CHYg-rShOt3kiL6ZN1yA") │ ├ title: "Join the Revolution" │ ├ description: "Stay ahead of the curve with our e-commerce insights." │ ├ button_text: "Subscribe Now" │ └ button_url: "https://new-domain.com/subscribe" ├ block │ └ Item "JwT0hvgiR4WB0-SO9QG7Ig" (item_type: "I8Q6k-HqQmaZ498WKtvFbg") │ ├ title: "E-commerce Innovation Gallery" │ └ images │ ├ [0] │ │ ├ upload_id: "eLVHtrefRUq7qkVMpzG6mQ" │ │ ├ alt: "Modern e-commerce interface" │ │ └ title: "Next-gen Shopping" │ └ [1] │ ├ upload_id: "UFIyIRQFT1GQ7YAG34ub5w" │ ├ alt: "AI-powered recommendations" │ └ title: "Smart Product Discovery" └ block └ Item "czplSGgiSnizmFZ7gMT-_g" (item_type: "d-CHYg-rShOt3kiL6ZN1yA") ├ title: "Join the Revolution" ├ description: "Stay ahead of the curve with our e-commerce insights." ├ button_text: "Subscribe Now" └ button_url: "https://old-domain.com/subscribe" ``` #### Block & node helpers Curated index of the helpers used above. ###### Block helpers Used by all three block field types. Full reference: [block-processing-utilities](https://github.com/datocms/js-rest-api-clients/tree/main/packages/cma-client#block-processing-utilities). | Need | Helper | | --- | --- | | Build a block (create / edit) | `buildBlockRecord(...)` | | Clone a block (deep copy, IDs stripped) | `duplicateBlockRecord(block, schemaRepository)` | | Inspect a record or block (debug) | `inspectItem(record)` | | Inline narrowing on a block union | `block.__itemTypeId === "..."` | | Type-guard predicate for `Array#filter` / `Array#find` | `isBlockOfType(id)` | | Recurse into every block (any depth, any field) | `visitBlocks*` / `mapBlocks*` / `filterBlocks*` / `findAllBlocks*` / `reduceBlocks*` / `someBlocks*` / `everyBlocks*` `InNonLocalizedFieldValue` | ###### Structured-text node helpers Used only by `structured_text`. Each helper has an `*Async` mirror (`mapNodes` → `mapNodesAsync`) for async callbacks. Full reference: [tree-manipulation-utilities](https://github.com/datocms/structured-text/tree/main/packages/utils#tree-manipulation-utilities). | Need | Helper | | --- | --- | | Narrow a node to a kind | `isParagraph`, `isHeading`, `isSpan`, `isLink`, `isItemLink`, `isInlineItem`, `isBlock`, `isInlineBlock`, `isList`, ... | | Narrow a block / inline-block node to a specific model in one step | `isBlockWithItemOfType(id)`, `isInlineBlockWithItemOfType(id)` | | Walk every node (side effect) | `forEachNode` | | Transform every node (1:1, splat into siblings, or drop) | `mapNodes` | | Find first / collect every match | `findFirstNode`, `collectNodes` | | Fold to a single value | `reduceNodes` | | Short-circuit checks | `someNode`, `everyNode` | | ASCII-tree debug | `inspect` | ### Updating Localized Fields **➡️ [Before proceeding, ensure you have read the general guide on Localization](/docs/content-management-api/resources/item.md#localization)** When you send an update request, the API follows these strict rules. ###### Rule 1: To change a locale value, send the whole set When you update a translated field, you must provide the **entire object** for that field, including all the languages you want to keep unchanged. You can't just send the one language you're changing. - **Correct:** To update the Italian title, you send both English and Italian: ```json { "title": { "en": "Hello World", "it": "Ciao a tutti! (Updated)" } } ``` - **Incorrect:** If you only send the Italian value, the API will assume you want to **delete** the English one! ###### Rule 2: To add/remove a language, send all translated fields This is the only time you can't just send the one field you're changing. To add or remove a language from an entire record, you **must include all translated fields** in your request. This is to enforce the **Locale Sync Rule** and ensure all fields remain consistent. - **Example:** To add French to a blog post that already has a translated `title` and `content`, your request must include both fields with the new `fr` locale. ###### Rule 3: Limited permissions? Only send what you can manage If your API key only has permission for certain languages (e.g., only English), you must **only include those languages** in your update. The system is smart and will automatically **protect and preserve** the content for the languages you can't access (like Italian or French). ###### Update scenarios at a glance This table shows what happens in different situations. The key takeaway is that your update payload defines the **new final state** for the languages you are allowed to manage. | Your Role manages | Record currently Has | Your payload sends | Result | | --- | --- | --- | --- | | English | English | English | ✅ English is updated. | | English, Italian | English | English, Italian | ✅ English is updated. ➕ Italian is **added**. | | English, Italian | English, Italian | English | ✅ English is updated. ➖ Italian is **removed**. | | English, Italian | English, Italian | English, Italian | ✅ English is updated. ✅ Italian is updated. | | Eng, Ita, Fre | English, Italian | English, French | ✅ English is updated. ➖ Italian is **removed**. ➕ French is **added**. | | English | English, Italian | English | ✅ English is updated. 🛡️ Italian is **preserved**. | | English, Italian | English, French | English, Italian | ✅ English is updated. 🛡️ French is **preserved**. ➕ Italian is **added**. | | English, Italian | English, French | Italian | ➖ English is **removed**. 🛡️ French is **preserved**. ➕ Italian is **added**. | ###### Block fields The rules about localization work in combination with the rules for updating blocks: you use full block objects to create/update and block IDs to leave unchanged, but you do so *within* the object for a specific locale.
Example: Updating a block in one locale This payload updates the title of an existing block in the `en` locale, while leaving the second English block and all Italian blocks untouched. The `it` locale needs to be included in the payload, or the Italian locale will be deleted! ```json { "content_blocks": { "en": [ { "id": "dhVR2HqgRVCTGFi0bWqLqA", "type": "item", "attributes": { "title": "Updated English Title" } }, "kL9mN3pQrStUvWxYzAbCdE" ], "it": [ "dhVR2HqgRVCTGFi_0bWqLqA", "kL9mN3pQrStUvWxYzAbCdE" ] } } ```
Example: Adding a new block to one locale This payload adds a new block to the `it` locale only. The `en` locale needs to be included in the payload, or the Italian locale will be deleted! ```json { "content_blocks": { "en": [ "dhVR2HqgRVCTGFi_0bWqLqA", "kL9mN3pQrStUvWxYzAbCdE" ], "it": [ "fG8hI1jKlMnOpQrStUvWxY", { "type": "item", "attributes": { "title": "Nuovo Blocco" }, "relationships": { "item_type": { "data": { "id": "BxZ9Y2aKQVeTnM4hP8wLpD", "type": "item_type" } } } }, "dhVR2HqgRVCTGFi0bWqLqA" ] } } ```
Example: Adding a new locale To add a new locale to an existing record, you must provide values for all localized fields for that new locale, and include existing locales that you want to preserve. ```json { "title": { "en": "English Title", "fr": "Titre Français", }, "content_blocks": { "en": [ "dhVR2HqgRVCTGFi_0bWqLqA", "kL9mN3pQrStUvWxYzAbCdE" ], "fr": [ { "type": "item", "attributes": { "title": "Nouveau Bloc Français" }, "relationships": { "item_type": { "data": { "id": "BxZ9Y2aKQVeTnM4hP8wLpD", "type": "item_type" } } } } ] } } ```
> [!POSITIVE] One code path for localized and non-localized fields > Helpers shipped with our JS CMA clients let you skip the "does this field have a locale object or just a value" branching when reading or transforming field values — jump to [Unified locale helpers](/docs/content-management-api/resources/item/update.md#unified-locale-helpers). ###### Example Adding a new locale Adds the `de` locale to a record that currently has `en` and `it`, in an environment whose locales are `['en', 'it', 'de']`. Per Rule 2 above, the payload must include **every** localized field, with the existing locales preserved alongside the new one. Requires [`all_locales_required`](/docs/content-management-api/resources/item-type.md#object-payload) to be `false` on the model. Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import type * as Schema from "./schema.js"; /* * Article * ├─ author: string * ├─ title: string (localized) * └─ content: text (localized) */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const item = await client.items.update( "T4m4tPymSACFzsqbZS65WA", { title: { en: "My title", it: "Il mio titolo", de: "Mein Titel", }, content: { en: "Schema.Article content", it: "Contenuto articolo", de: "Artikelinhalt", }, }, ); console.log(inspectItem(item)); } run(); ``` Returned output ```javascript └ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ author: "Stefano Verna" ├ title │ ├ de: "Mein Titel" │ ├ en: "My title" │ └ it: "Il mio titolo" └ content ├ de: "Artikelinhalt" ├ en: "Article content" └ it: "Contenuto articolo" ``` ###### Example Removing an existing locale If the [`all_locales_required`](/docs/content-management-api/resources/item-type.md#object-payload) option in a model is turned off, then its records do not need all environment's locales to be defined for localized fields, so you're free to add/remove locales during an update operation. This example demonstrates two approaches for removing a locale from records: - **When schema is known:** When you know the exact structure of your models, you can use `ItemTypeDefinition`s to work with full type safety. This approach is ideal for specific, targeted operations. - **When schema is unknown:** When you need to work with models dynamically (without knowing their structure ahead of time), you can use [`client.fields.list()`](/docs/content-management-api/resources/field/instances.md) to discover field definitions at runtime. This approach is perfect for bulk operations across multiple models. Both approaches remove the `it` locale by **omitting the unwanted locale** from all localized fields while preserving other locales and non-localized fields. Code ```javascript import type { ApiTypes } from "@datocms/cma-client-node"; import { buildClient, inspectItem, isLocalized, type LocalizedFieldValue, } from "@datocms/cma-client-node"; import lodash from "lodash"; import type * as Schema from "./schema.js"; /* * Article * ├─ title: string (localized) * ├─ content: structured_text (localized) * ├─ cta_block: single_block * │ └─ CtaBlock: title, button_text, button_url * └─ cover_image: file * * ArticleCopy * ├─ title: string (localized) * ├─ content: structured_text (localized) * ├─ cta_block: single_block * │ └─ CtaBlock * └─ cover_image: file */ // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); async function removeLocaleWhenSchemaIsKnown() { // First, fetch the existing record to get current values const existingRecord = await client.items.find( "T4m4tPymSACFzsqbZS65WA", ); console.log("-- BEFORE UPDATE --"); console.log(inspectItem(existingRecord)); // Update the record to remove the "it" locale by omitting it from all localized fields // Using lodash omit() for clean, readable locale removal const updatedRecord = await client.items.update( "T4m4tPymSACFzsqbZS65WA", { title: lodash.omit(existingRecord.title, "it"), content: lodash.omit(existingRecord.content, "it"), // Do not pass non-localized fields (ie. cover_image, cta_block), as we want to keep them unchanged }, ); console.log("-- AFTER LOCALE REMOVAL --"); console.log(inspectItem(updatedRecord)); } // When you don't know the model structure ahead of time, // you can dynamically load the fields and perform the same operation async function removeLocaleWhenSchemaIsUnknown() { // Get the model fields const fields = await client.fields.list("ZV0o9497SsqWxQR8HEQddw"); // Filter to only localized fields using the isLocalized helper const localizedFields = fields.filter(isLocalized); // Process all records of this model type for await (const record of client.items.listPagedIterator({ filter: { type: "ZV0o9497SsqWxQR8HEQddw" }, })) { const updatePayload: ApiTypes.ItemUpdateSchema = {}; // Build update payload by processing each localized field for (const field of localizedFields) { const fieldValue = record[field.api_key] as LocalizedFieldValue; // Remove the "it" locale from each field's localized values updatePayload[field.api_key] = lodash.omit(fieldValue, "it"); } // Update the record with the modified locale data await client.items.update(record.id, updatePayload); } console.log("Removed 'it' locale from all records of the model"); } async function run() { // Run both examples await removeLocaleWhenSchemaIsKnown(); await removeLocaleWhenSchemaIsUnknown(); } run(); ``` Returned output ```javascript -- BEFORE UPDATE -- └ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title │ ├ de: "Content-Management verstehen" │ ├ en: "Understanding Content Management" │ └ it: "Capire la gestione dei contenuti" ├ content │ ├ de │ │ └ paragraph │ │ └ span "Ein umfassender Leitfaden für moderne Content-Management-Systeme und ..." │ ├ en │ │ └ paragraph │ │ └ span "A comprehensive guide to modern content management systems and best p..." │ └ it │ └ paragraph │ └ span "Una guida completa ai sistemi di gestione dei contenuti moderni e all..." ├ cta_block: "ZPfQFuaqTn2cdoQnPSsu_g" └ cover_image └ upload_id: "adCusKKeRPO5wtjrIIcGjw" -- AFTER LOCALE REMOVAL -- └ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title │ ├ de: "Content-Management verstehen" │ └ en: "Understanding Content Management" ├ content │ ├ de │ │ └ paragraph │ │ └ span "Ein umfassender Leitfaden für moderne Content-Management-Systeme und ..." │ └ en │ └ paragraph │ └ span "A comprehensive guide to modern content management systems and best p..." ├ cta_block: "ZPfQFuaqTn2cdoQnPSsu_g" └ cover_image └ upload_id: "adCusKKeRPO5wtjrIIcGjw" Removed 'it' locale from all records of the model ``` ###### Example Copying content from one locale to another Copies all localized content from `en` to `en-AT` across every model in the project — useful for seeding a new locale, region-specific variations (e.g. UK → Austrian English), or fallback content for incomplete translations. The script iterates through every model, walks each localized field with [`mapNormalizedFieldValuesAsync`](https://github.com/datocms/js-rest-api-clients/tree/main/packages/cma-client#mapnormalizedfieldvalues--mapnormalizedfieldvaluesasync), and recurses into nested blocks with [`mapBlocksInNonLocalizedFieldValue`](https://github.com/datocms/js-rest-api-clients/tree/main/packages/cma-client#mapblocksinnonlocalizedfieldvalue) to strip their IDs — that way the target locale gets fresh block instances instead of references to the source ones. Code ```javascript import assert from "node:assert"; import type { ApiTypes } from "@datocms/cma-client-node"; import { buildClient, inspectItem, isItemWithOptionalMeta, isLocalized, type LocalizedFieldValue, mapBlocksInNonLocalizedFieldValue, mapNormalizedFieldValuesAsync, SchemaRepository, } from "@datocms/cma-client-node"; async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const schemaRepository = new SchemaRepository(client); for (const model of await schemaRepository.getAllModels()) { const fields = await schemaRepository.getItemTypeFields(model); const localizedFields = fields.filter(isLocalized); // Iterating across every model discovered at runtime, so no single // `` generic fits — keep `listPagedIterator` untyped and narrow // field values dynamically below. for await (const record of client.items.listPagedIterator({ filter: { type: model.api_key }, version: "current", nested: true, })) { const updatePayload: ApiTypes.ItemUpdateSchema = {}; let hasChanges = false; for (const field of localizedFields) { const fieldValueWithNestedBlocks = record[ field.api_key ] as LocalizedFieldValue; if (!fieldValueWithNestedBlocks["en"]) { continue; } const newFieldValue = (await mapNormalizedFieldValuesAsync( fieldValueWithNestedBlocks, field, async (_locale, fieldValueForLocale) => { return mapBlocksInNonLocalizedFieldValue( fieldValueForLocale, field.field_type, schemaRepository, (block) => { assert(isItemWithOptionalMeta(block)); return block.id; }, ); }, )) as LocalizedFieldValue; // Strip IDs from cloned blocks so en-AT gets fresh instances rather // than references to the en blocks. newFieldValue["en-AT"] = await mapBlocksInNonLocalizedFieldValue( fieldValueWithNestedBlocks["en"], field.field_type, schemaRepository, (block) => { assert(isItemWithOptionalMeta(block)); const { id, ...blockWithoutId } = block; return blockWithoutId; }, ); updatePayload[field.api_key] = newFieldValue; hasChanges = true; } if (hasChanges) { console.log("-- EXISTING RECORD --"); console.log(inspectItem(record)); console.log("-- UPDATE PAYLOAD --"); console.log(inspectItem(updatePayload)); await client.items.update(record.id, updatePayload); const nestedRecord = await client.items.find(record.id, { nested: true, }); console.log("-- RECORD AFTER UPDATE --"); console.log(inspectItem(nestedRecord)); } } } } run(); ``` Returned output ```javascript -- EXISTING RECORD -- └ Item "Bz0dHLjeRuCW10fJl1GF0w" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ name │ ├ de: "Premium Kabellose Kopfhörer" │ └ en: "Premium Wireless Headphones" ├ description │ ├ de: "Erleben Sie kristallklaren Klang mit unseren hochwertigen kabellosen Kopfhöre..." │ └ en: "Experience crystal-clear audio with our top-of-the-line wireless headphones f..." ├ features │ ├ de │ │ ├ [0] Item "YazSxGr2TlKLJZjJmyhg0Q" (item_type: "T4m4tPymSACFzsqbZS65WA") │ │ │ ├ title: "Aktive Geräuschunterdrückung" │ │ │ └ description: "Blockieren Sie unerwünschte Geräusche mit unserer fortschrittlichen ANC-Techn..." │ │ └ [1] Item "D1Zh8Ff2SaC1CCG67Ic1sQ" (item_type: "T4m4tPymSACFzsqbZS65WA") │ │ ├ title: "30 Stunden Akkulaufzeit" │ │ └ description: "Ganztägiges Hören mit Schnellladefunktion." │ └ en │ ├ [0] Item "HqZZmo8sRKuKMfaUZbkNig" (item_type: "T4m4tPymSACFzsqbZS65WA") │ │ ├ title: "Active Noise Cancellation" │ │ └ description: "Block out unwanted noise with our advanced ANC technology." │ └ [1] Item "NKaGQ1AUQZSfHHhL0c3eLA" (item_type: "T4m4tPymSACFzsqbZS65WA") │ ├ title: "30-Hour Battery Life" │ └ description: "All-day listening with fast charging capabilities." └ price: 299.99 -- UPDATE PAYLOAD -- └ Item ├ description │ ├ de: "Erleben Sie kristallklaren Klang mit unseren hochwertigen kabellosen Kopfhöre..." │ ├ en: "Experience crystal-clear audio with our top-of-the-line wireless headphones f..." │ └ en-AT: "Experience crystal-clear audio with our top-of-the-line wireless headphones f..." ├ features │ ├ de │ │ ├ [0] "YazSxGr2TlKLJZjJmyhg0Q" │ │ └ [1] "D1Zh8Ff2SaC1CCG67Ic1sQ" │ ├ en │ │ ├ [0] "HqZZmo8sRKuKMfaUZbkNig" │ │ └ [1] "NKaGQ1AUQZSfHHhL0c3eLA" │ └ en-AT │ ├ [0] Item (item_type: "T4m4tPymSACFzsqbZS65WA") │ │ ├ title: "Active Noise Cancellation" │ │ └ description: "Block out unwanted noise with our advanced ANC technology." │ └ [1] Item (item_type: "T4m4tPymSACFzsqbZS65WA") │ ├ title: "30-Hour Battery Life" │ └ description: "All-day listening with fast charging capabilities." └ name ├ de: "Premium Kabellose Kopfhörer" ├ en: "Premium Wireless Headphones" └ en-AT: "Premium Wireless Headphones" -- RECORD AFTER UPDATE -- └ Item "Bz0dHLjeRuCW10fJl1GF0w" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ name │ ├ de: "Premium Kabellose Kopfhörer" │ ├ en: "Premium Wireless Headphones" │ └ en-AT: "Premium Wireless Headphones" ├ description │ ├ de: "Erleben Sie kristallklaren Klang mit unseren hochwertigen kabellosen Kopfhöre..." │ ├ en: "Experience crystal-clear audio with our top-of-the-line wireless headphones f..." │ └ en-AT: "Experience crystal-clear audio with our top-of-the-line wireless headphones f..." ├ features │ ├ de │ │ ├ [0] Item "YazSxGr2TlKLJZjJmyhg0Q" (item_type: "T4m4tPymSACFzsqbZS65WA") │ │ │ ├ title: "Aktive Geräuschunterdrückung" │ │ │ └ description: "Blockieren Sie unerwünschte Geräusche mit unserer fortschrittlichen ANC-Techn..." │ │ └ [1] Item "D1Zh8Ff2SaC1CCG67Ic1sQ" (item_type: "T4m4tPymSACFzsqbZS65WA") │ │ ├ title: "30 Stunden Akkulaufzeit" │ │ └ description: "Ganztägiges Hören mit Schnellladefunktion." │ ├ en │ │ ├ [0] Item "HqZZmo8sRKuKMfaUZbkNig" (item_type: "T4m4tPymSACFzsqbZS65WA") │ │ │ ├ title: "Active Noise Cancellation" │ │ │ └ description: "Block out unwanted noise with our advanced ANC technology." │ │ └ [1] Item "NKaGQ1AUQZSfHHhL0c3eLA" (item_type: "T4m4tPymSACFzsqbZS65WA") │ │ ├ title: "30-Hour Battery Life" │ │ └ description: "All-day listening with fast charging capabilities." │ └ en-AT │ ├ [0] Item "Txk_qqFJSL6VP3wFzmE_2w" (item_type: "T4m4tPymSACFzsqbZS65WA") │ │ ├ title: "Active Noise Cancellation" │ │ └ description: "Block out unwanted noise with our advanced ANC technology." │ └ [1] Item "eValhxXxTZe-6FW-mwe80g" (item_type: "T4m4tPymSACFzsqbZS65WA") │ ├ title: "30-Hour Battery Life" │ └ description: "All-day listening with fast charging capabilities." └ price: 299.99 ``` #### Unified locale helpers These utilities let you treat localized and non-localized field values with the same code path — no branching on "does this field have a locale object or just a value". Each helper has an `*Async` mirror (`mapNormalizedFieldValues` → `mapNormalizedFieldValuesAsync`) for async callbacks. See the **[full helper reference](https://github.com/datocms/js-rest-api-clients/tree/main/packages/cma-client#unified-field-processing-localized--non-localized)** for signatures and examples. - `mapNormalizedFieldValues()`: apply a transformation to each locale (or to the single value on non-localized fields) - `filterNormalizedFieldValues()`: keep only locales / values matching a predicate - `visitNormalizedFieldValues()`: run a side effect for each locale / value - `someNormalizedFieldValues()`: `true` if at least one locale / value matches - `everyNormalizedFieldValue()`: `true` if all locales / values match - `toNormalizedFieldValueEntries()` / `fromNormalizedFieldValueEntries()`: convert to / from a unified `[locale, value][]` shape for iteration ### Bulk block operations Sometimes, you need to perform mass operations on any block of a specific kind, regardless of where they're embedded in your content structure — whether in Modular Content fields, Single Block fields, or deeply nested within Structured Text documents. In these cases, manually traversing each record and field would be extremely time-consuming and error-prone. DatoCMS provides powerful utilities that can systematically discover, traverse, and manipulate blocks across your entire content hierarchy. These utilities handle the complexity of localized content, nested structures, and different field types automatically, making what would otherwise be a complex operation straightforward and reliable. ###### Example Edit blocks across all content Edits specific blocks wherever they're embedded — Modular Content, Single Block, or Structured Text fields, including deeply nested structures and localized content. To avoid scanning the whole project, the script discovers only the models that can (directly or transitively) embed the target block via [`SchemaRepository.getRawModelsEmbeddingBlocks()`](https://github.com/datocms/js-rest-api-clients/tree/main/packages/cma-client#schemarepository), then walks each record with [`mapNormalizedFieldValuesAsync`](https://github.com/datocms/js-rest-api-clients/tree/main/packages/cma-client#mapnormalizedfieldvalues--mapnormalizedfieldvaluesasync) and [`mapBlocksInNonLocalizedFieldValue`](https://github.com/datocms/js-rest-api-clients/tree/main/packages/cma-client#mapblocksinnonlocalizedfieldvalue). In this case, every CTA block gets its `style` set to `"primary"` for high-intent copy and `"muted"` otherwise, based on the button text. Code ```javascript import assert from "node:assert"; import { type ApiTypes, buildBlockRecord, buildClient, inspectItem, isItemWithOptionalMeta, mapBlocksInNonLocalizedFieldValue, mapNormalizedFieldValuesAsync, type RawApiTypes, SchemaRepository, } from "@datocms/cma-client-node"; import * as Schema from "./schema.js"; /* * Article * ├─ title: string (localized) * ├─ content: structured_text (localized) * │ └─ CtaBlock: title, description, button_text, button_url, style * └─ sidebar: rich_text * └─ CtaBlock * * LandingPage * └─ hero_cta: single_block * └─ CtaBlock */ // Simplified style decision logic function computeCtaStyle(text: string | null): "primary" | "muted" { if (!text) return "muted"; return /buy|get started|start free|sign up|upgrade/i.test(text) ? "primary" : "muted"; } // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); async function run() { const schemaRepository = new SchemaRepository(client); const ctaBlockModel = await schemaRepository.getItemTypeById( Schema.CtaBlock.ID, ); // 1. Find all models that can embed CTA blocks (directly or indirectly) const modelsEmbeddingCtas = await schemaRepository.getModelsEmbeddingBlocks([ ctaBlockModel, ]); // 2. Process each model and its records for (const model of modelsEmbeddingCtas) { console.log( `\n📋 Processing records of model: ${model.name} (${model.api_key})`, ); const fields = await schemaRepository.getItemTypeFields(model); // This script iterates records across every model discovered at runtime, // so there is no single `` generic that fits — we keep // `rawListPagedIterator` untyped here and narrow block values dynamically // below. Per-model scripts should always pass the generated marker. for await (const record of client.items.rawListPagedIterator({ filter: { type: model.id }, version: "current", nested: true, // Get full block objects })) { console.log(`\n--- Processing ${record.id} ---`); console.log("BEFORE:"); console.log(inspectItem(record)); const updatedAttributes: ApiTypes.ItemUpdateSchema = {}; // 3. Use mapNormalizedFieldValuesAsync to handle localized/non-localized uniformly for (const field of fields) { const fieldValue = record.attributes[field.api_key]; let fieldHasChanges = false; const updatedFieldValue = await mapNormalizedFieldValuesAsync( fieldValue, field, async (_locale, normalizedFieldValue) => mapBlocksInNonLocalizedFieldValue( normalizedFieldValue, field.field_type, schemaRepository, (block) => { assert(isItemWithOptionalMeta(block)); if (block.__itemTypeId !== Schema.CtaBlock.ID) { return block.id; // Keep non-CTA blocks as is } // The raw iterator yields records (and their embedded blocks) // in the raw API shape; narrow to this specific block model // via the ItemInNestedResponse schema indexed by Schema.CtaBlock. const ctaBlock = block as RawApiTypes.ItemInNestedResponse; const currentStyle = ctaBlock.attributes.style; const desiredStyle = computeCtaStyle( ctaBlock.attributes.button_text, ); if (currentStyle !== desiredStyle) { fieldHasChanges = true; // Return an updated block record with new style return buildBlockRecord({ id: ctaBlock.id, style: desiredStyle, }); } return block.id; // No change needed }, ), ); if (fieldHasChanges) { updatedAttributes[field.api_key] = updatedFieldValue; } } // 4. Update the record if there were changes if (Object.keys(updatedAttributes).length > 0) { const updatedRecord = await client.items.update( record.id, updatedAttributes, ); console.log("AFTER:"); await inspectItemWithNestedBlocks(updatedRecord); } else { console.log("✨ No changes needed for this record"); } } } } run(); async function inspectItemWithNestedBlocks(item: ApiTypes.Item) { const itemWithNestedBlocks = await client.items.find(item, { nested: true }); console.log(inspectItem(itemWithNestedBlocks)); } ``` Returned output ```javascript 📋 Processing records of model: Landing Page (landing_page) --- Processing IwcHsSQ5SSa2LYzpk_Ddjw --- BEFORE: └ Item "IwcHsSQ5SSa2LYzpk_Ddjw" (item_type: "KUz2pYAvQvOWqv3dVwVw3w") └ hero_cta └ Item "fnclskI4RG25uLQC92XE5g" (item_type: "DC2XVF6BTjGBgQaoaih6Og") ├ title: "Transform Your Business" ├ description: "Take the next step forward" ├ button_text: "Get started" ├ button_url: "/start" └ style: "muted" AFTER: └ Item "IwcHsSQ5SSa2LYzpk_Ddjw" (item_type: "KUz2pYAvQvOWqv3dVwVw3w") └ hero_cta └ Item "fnclskI4RG25uLQC92XE5g" (item_type: "DC2XVF6BTjGBgQaoaih6Og") ├ title: "Transform Your Business" ├ description: "Take the next step forward" ├ button_text: "Get started" ├ button_url: "/start" └ style: "primary" 📋 Processing records of model: Article (article) --- Processing JPplplyPTMKpCbB-wipxeA --- BEFORE: └ Item "JPplplyPTMKpCbB-wipxeA" (item_type: "ONxSjA4WTWaoNJY2zokUoQ") ├ title │ ├ en: "Sample Article" │ └ it: "Articolo di Esempio" ├ content │ ├ en │ │ ├ paragraph │ │ │ └ span "Introduction text" │ │ ├ block │ │ │ └ Item "BOps1UFgSU-CSm-fRjoqCA" (item_type: "DC2XVF6BTjGBgQaoaih6Og") │ │ │ ├ title: "Join Our Platform" │ │ │ ├ description: "Start your journey today" │ │ │ ├ button_text: "Sign up" │ │ │ ├ button_url: "/signup" │ │ │ └ style: "muted" │ │ └ paragraph │ │ └ span "Conclusion text" │ └ it │ ├ paragraph │ │ └ span "Testo introduttivo" │ └ block │ └ Item "SSVQgIbZS_uoPQWg-qYzWg" (item_type: "DC2XVF6BTjGBgQaoaih6Og") │ ├ title: "Scopri di Più" │ ├ description: "Leggi la nostra guida" │ ├ button_text: "Learn more" │ ├ button_url: "/guide" │ └ style: "primary" └ sidebar └ [0] Item "f86JBAwxTsasu7J3XxXqJg" (item_type: "DC2XVF6BTjGBgQaoaih6Og") ├ title: "Special Offer" ├ description: "Limited time promotion" ├ button_text: "Buy now" ├ button_url: "/buy" └ style: "muted" AFTER: └ Item "JPplplyPTMKpCbB-wipxeA" (item_type: "ONxSjA4WTWaoNJY2zokUoQ") ├ title │ ├ en: "Sample Article" │ └ it: "Articolo di Esempio" ├ content │ ├ en │ │ ├ paragraph │ │ │ └ span "Introduction text" │ │ ├ block │ │ │ └ Item "BOps1UFgSU-CSm-fRjoqCA" (item_type: "DC2XVF6BTjGBgQaoaih6Og") │ │ │ ├ title: "Join Our Platform" │ │ │ ├ description: "Start your journey today" │ │ │ ├ button_text: "Sign up" │ │ │ ├ button_url: "/signup" │ │ │ └ style: "primary" │ │ └ paragraph │ │ └ span "Conclusion text" │ └ it │ ├ paragraph │ │ └ span "Testo introduttivo" │ └ block │ └ Item "SSVQgIbZS_uoPQWg-qYzWg" (item_type: "DC2XVF6BTjGBgQaoaih6Og") │ ├ title: "Scopri di Più" │ ├ description: "Leggi la nostra guida" │ ├ button_text: "Learn more" │ ├ button_url: "/guide" │ └ style: "muted" └ sidebar └ [0] Item "f86JBAwxTsasu7J3XxXqJg" (item_type: "DC2XVF6BTjGBgQaoaih6Og") ├ title: "Special Offer" ├ description: "Limited time promotion" ├ button_text: "Buy now" ├ button_url: "/buy" └ style: "primary" ``` ###### Example Delete blocks across all content Removes specific blocks wherever they're embedded — Modular Content, Single Block, or Structured Text fields, including deeply nested structures and localized content. To avoid scanning the whole project, the script discovers only the models that can (directly or transitively) embed the target block via [`SchemaRepository.getRawModelsEmbeddingBlocks()`](https://github.com/datocms/js-rest-api-clients/tree/main/packages/cma-client#schemarepository), then walks each record with [`mapNormalizedFieldValuesAsync`](https://github.com/datocms/js-rest-api-clients/tree/main/packages/cma-client#mapnormalizedfieldvalues--mapnormalizedfieldvaluesasync) and [`filterBlocksInNonLocalizedFieldValue`](https://github.com/datocms/js-rest-api-clients/tree/main/packages/cma-client#filterblocksinnonlocalizedfieldvalue). The removal predicate is an async check (mocked here as an ecommerce SKU lookup), so the same shape works for any external decision. Code ```javascript import assert from "node:assert"; import { type ApiTypes, buildClient, filterBlocksInNonLocalizedFieldValue, inspectItem, isItemWithOptionalMeta, mapNormalizedFieldValuesAsync, type RawApiTypes, SchemaRepository, } from "@datocms/cma-client-node"; import * as Schema from "./schema.js"; /* * Article * ├─ title: string (localized) * ├─ content: structured_text (localized) * │ └─ ProductBlock: sku * └─ sidebar: rich_text * └─ ProductBlock * * ProductPage * └─ featured_product: single_block * └─ ProductBlock */ // Mock external ecommerce system check async function isValidSKU(sku: string | null): Promise { // For demo purposes, consider SKUs starting with "INVALID" as discontinued return Boolean(sku && !sku.startsWith("INVALID")); } async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const schemaRepository = new SchemaRepository(client); const productBlockModel = await schemaRepository.getItemTypeById( Schema.ProductBlock.ID, ); // 1. Find all models that can embed Product blocks (directly or indirectly) const modelsEmbeddingProductBlocks = await schemaRepository.getModelsEmbeddingBlocks([productBlockModel]); // 2. Process each model and its records for (const model of modelsEmbeddingProductBlocks) { console.log( `\n📋 Processing records of model: ${model.name} (${model.api_key})`, ); const fields = await schemaRepository.getItemTypeFields(model); // This script iterates records across every model discovered at runtime, // so there is no single `` generic that fits — we keep // `rawListPagedIterator` untyped here and narrow block values dynamically // below. Per-model scripts should always pass the generated marker. for await (const record of client.items.rawListPagedIterator({ filter: { type: model.id }, version: "current", nested: true, // Get full block objects })) { console.log(`\n--- Processing ${record.id} ---`); console.log("BEFORE:"); console.log(inspectItem(record)); const updatedAttributes: ApiTypes.ItemUpdateSchema = {}; // 3. Use mapNormalizedFieldValuesAsync to handle localized/non-localized fields uniformly for (const field of fields) { const fieldValue = record.attributes[field.api_key]; let fieldHasChanges = false; const updatedFieldValue = await mapNormalizedFieldValuesAsync( fieldValue, field, async (_locale, normalizedFieldValue) => { // 4. Use filterBlocksInNonLocalizedFieldValue to recursively filter blocks const filteredValue = await filterBlocksInNonLocalizedFieldValue( normalizedFieldValue, field.field_type, schemaRepository, async (block) => { assert(isItemWithOptionalMeta(block)); // Only check Product blocks if (block.__itemTypeId !== Schema.ProductBlock.ID) { return true; // Keep other blocks } // The raw iterator yields records (and their embedded blocks) // in the raw API shape; narrow to this specific block model // via the ItemInNestedResponse schema indexed by Schema.ProductBlock. const productBlock = block as RawApiTypes.ItemInNestedResponse; // Check if the product SKU is still valid in external system const isValid = await isValidSKU(productBlock.attributes.sku); if (!isValid) { fieldHasChanges = true; } return isValid; }, ); return filteredValue; }, ); if (fieldHasChanges) { updatedAttributes[field.api_key] = updatedFieldValue; } } // 5. Update the record if there were changes if (Object.keys(updatedAttributes).length > 0) { const updatedRecord = await client.items.update( record.id, updatedAttributes, ); console.log("AFTER:"); console.log(inspectItem(updatedRecord)); } else { console.log("✨ No changes needed for this record"); } } } } run(); ``` Returned output ```javascript 📋 Processing records of model: Product Page (product_page) --- Processing RZfnYc3iSya7yYaTxoW0VA --- BEFORE: └ Item "RZfnYc3iSya7yYaTxoW0VA" (item_type: "KUz2pYAvQvOWqv3dVwVw3w") └ featured_product └ Item "XayqICFqQEyEqGFypcK07w" (item_type: "DC2XVF6BTjGBgQaoaih6Og") └ sku: "INVALID-SKU-004" AFTER: └ Item "RZfnYc3iSya7yYaTxoW0VA" (item_type: "KUz2pYAvQvOWqv3dVwVw3w") └ featured_product: null 📋 Processing records of model: Article (article) --- Processing Iaa0ZiZMSjCqeFWfs3JeuQ --- BEFORE: └ Item "Iaa0ZiZMSjCqeFWfs3JeuQ" (item_type: "ONxSjA4WTWaoNJY2zokUoQ") ├ title │ ├ en: "Sample Article" │ └ it: "Articolo di Esempio" ├ content │ ├ en │ │ ├ paragraph │ │ │ └ span "Introduction text" │ │ ├ block │ │ │ └ Item "Z-xM-VpKTzytfo-5jzSlOw" (item_type: "DC2XVF6BTjGBgQaoaih6Og") │ │ │ └ sku: "INVALID-SKU-001" │ │ └ paragraph │ │ └ span "Conclusion text" │ └ it │ ├ paragraph │ │ └ span "Testo introduttivo" │ └ block │ └ Item "YoCq3DtzSa2NIbB6ARsiVw" (item_type: "DC2XVF6BTjGBgQaoaih6Og") │ └ sku: "VALID-SKU-002" └ sidebar └ [0] Item "Ulk5GEEoRGSURyyPNSBcow" (item_type: "DC2XVF6BTjGBgQaoaih6Og") └ sku: "INVALID-SKU-003" AFTER: └ Item "Iaa0ZiZMSjCqeFWfs3JeuQ" (item_type: "ONxSjA4WTWaoNJY2zokUoQ") ├ title │ ├ en: "Sample Article" │ └ it: "Articolo di Esempio" ├ content │ ├ en │ │ ├ paragraph │ │ │ └ span "Introduction text" │ │ └ paragraph │ │ └ span "Conclusion text" │ └ it │ ├ paragraph │ │ └ span "Testo introduttivo" │ └ block "YoCq3DtzSa2NIbB6ARsiVw" └ sidebar: [] ``` ### Optimistic Locking To prevent clients from accidentally overwriting each other's changes, the update endpoint supports optimistic locking. You can include the record's current version number in the `meta` object of your payload. If the version on the server is newer than the one you provide, the API will reject the update with a `422 STALE_ITEM_VERSION` error, indicating that the record has been modified since you last fetched it. ###### Example Optimistic-locking update operation Code ```javascript import { ApiError, type ApiTypes, buildClient } from "@datocms/cma-client-node"; import type * as Schema from "./schema.js"; /* * Counter * ├─ counter: integer * └─ description: string */ // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); async function run() { const itemId = "T4m4tPymSACFzsqbZS65WA"; console.log("🚀 Starting concurrent updates simulation...\n"); // Create two competing updates that will run concurrently const updateA = updateRecordWithRetry( itemId, (record) => ({ counter: (record.counter || 0) + 10, description: `Updated by Process A at ${new Date().toISOString()}`, }), "Process A", ); const updateB = updateRecordWithRetry( itemId, (record) => ({ counter: (record.counter || 0) + 5, description: `Updated by Process B at ${new Date().toISOString()}`, }), "Process B", ); try { // Run both updates concurrently - one will likely trigger STALE_ITEM_VERSION const [resultA, resultB] = await Promise.all([updateA, updateB]); console.log("\n✅ Both updates completed successfully!"); console.log( "Final counter value:", Math.max(resultA.counter || 0, resultB.counter || 0), ); // Get the final state to see which update won const finalRecord = await client.items.find(itemId); console.log("\nFinal record state:"); console.log("- Schema.Counter:", finalRecord.counter); console.log("- Description:", finalRecord.description); console.log("- Version:", finalRecord.meta.current_version); } catch (error) { console.error("❌ Unexpected error:", error); } } async function updateRecordWithRetry( itemId: string, updateFunction: (record: ApiTypes.Item) => { counter?: number; description?: string; }, operationName: string, ) { // Get the current record const record = await client.items.find(itemId); console.log( `${operationName}: Got record version ${record.meta.current_version}`, ); try { // Apply the update with optimistic locking const updatedRecord = await client.items.update(itemId, { ...updateFunction(record), meta: { current_version: record.meta.current_version }, }); console.log( `${operationName}: Update successful! New version: ${updatedRecord.meta.current_version}`, ); return updatedRecord; } catch (e) { // Handle STALE_ITEM_VERSION error by retrying if (e instanceof ApiError && e.findError("STALE_ITEM_VERSION")) { console.log( `${operationName}: ❌ STALE_ITEM_VERSION detected! Record was modified by another client.`, ); console.log(`${operationName}: 🔄 Retrying with fresh data...`); // Recursive retry with exponential backoff await new Promise((resolve) => setTimeout(resolve, Math.random() * 100 + 50), ); return updateRecordWithRetry(itemId, updateFunction, operationName); } throw e; } } run(); ``` Returned output ```javascript 🚀 Starting concurrent updates simulation... Process A: Got record version L80WevK_R6Gh6ijMyW0AkQ Process B: Got record version L80WevK_R6Gh6ijMyW0AkQ Process A: Update successful! New version: QHXWBDr7S9ipQo6_JjQpAg Process B: ❌ STALE_ITEM_VERSION detected! Record was modified by another client. Process B: 🔄 Retrying with fresh data... Process B: Got record version QHXWBDr7S9ipQo6_JjQpAg Process B: Update successful! New version: A4VMeUdtRT26NWd07g6pzw ✅ Both updates completed successfully! Final counter value: 15 Final record state: - Counter: 15 - Description: Updated by Process B at 2025-09-26T08:25:53.088Z - Version: A4VMeUdtRT26NWd07g6pzw ``` ## Body parameters **`meta.created_at`** - Optional - Type: string Date of creation **`meta.first_published_at`** - Optional - Type: null, string Date of first publication **`meta.current_version`** - Optional - Type: string - Example: `"4234"` The ID of the current record version (for optimistic locking, see the example) **`meta.stage`** - Optional - Type: string, null The new stage to move the record to **`item_type`** - Optional - Type: [ResourceLinkage\<"item_type"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item_type.md) The record's model **`creator`** - Optional - Type: [ResourceLinkage\<"account"\>](https://www-draft.datocms.com/docs/content-management-api/resources/account.md), [ResourceLinkage\<"access_token"\>](https://www-draft.datocms.com/docs/content-management-api/resources/access_token.md), [ResourceLinkage\<"user"\>](https://www-draft.datocms.com/docs/content-management-api/resources/user.md), [ResourceLinkage\<"sso_user"\>](https://www-draft.datocms.com/docs/content-management-api/resources/sso_user.md), [ResourceLinkage\<"organization"\>](https://www-draft.datocms.com/docs/content-management-api/resources/organization.md) The entity (account/collaborator/access token/sso user) who created the record ## Returns Returns a resource object of type [item](/docs/content-management-api/resources/item.md) --- # Content Management API — Referenced records Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item/references.md List all records that link to a specific record ## Query parameters **`nested`** - Type: boolean For Modular Content, Structured Text and Single Block fields, return full payload for nested blocks instead of IDs **`version`** - Type: null, enum - Example: `"current"` Retrieve only the selected type of version that is linked to the record; current, published or both
Show enum values **`current`** Return records that in their latest version available link to the record **`published`** Return records that in their published version link to the record **`published-or-current`** Return records that either in their published version or in their latest version available link to the record
## Returns Returns an array of resource objects of type [item](/docs/content-management-api/resources/item.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemId = "hWl-mnkWRYmMCSTq4z_piQ"; const items = await client.items.references(itemId); for (const item of items) { // Check the 'Returned output' tab for the result ☝️ console.log(item); } } run(); ``` Returned output ```javascript { id: "hWl-mnkWRYmMCSTq4z_piQ", title: "My first blog post!", content: "Lorem ipsum dolor sit amet...", category: "24", image: { alt: "Alt text", title: "Image title", custom_data: {}, focal_point: null, upload_id: "20042921", }, meta: { created_at: "2020-04-21T07:57:11.124Z", updated_at: "2020-04-21T07:57:11.124Z", published_at: "2020-04-21T07:57:11.124Z", first_published_at: "2020-04-21T07:57:11.124Z", publication_scheduled_at: "2020-04-21T07:57:11.124Z", unpublishing_scheduled_at: "2020-04-21T07:57:11.124Z", status: "published", is_current_version_valid: true, is_published_version_valid: true, current_version: "4234", stage: null, has_children: true, }, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, } ``` --- # Content Management API — Retrieve a record Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item/self.md > [!PROTIP] 📚 New to DatoCMS records? > Begin by reading the [Introduction to records](/docs/content-management-api/resources/item.md) guide to familiarize yourself with field types, API response modes, and the concepts of block manipulation! To retrieve a single record, send a GET request to the `/items/:id` endpoint. ## Response modes: Regular vs. Nested The `GET /items/:id` endpoint, just like the [List all records](/docs/content-management-api/resources/item/instances.md) endpoint, supports two different response modes that control how block fields are returned in the JSON payload. You can switch between them using the nested query parameter. - **Regular mode (default):** This is the most efficient mode for listing records. Any block fields (like Modular Content) will contain an array of **block IDs**, not the full block content. This keeps the response size small and fast. - **Nested mode (`nested=true`):** This mode returns the complete content for any block fields. Instead of just IDs, the API will return full **block objects**, including all their attributes. This is useful when you need to display the blocks' content immediately without making additional API calls, or to read existing content and then make an update. ###### Example Regular mode (default) Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemId = "hWl-mnkWRYmMCSTq4z_piQ"; const item = await client.items.find(itemId); // Check the 'Returned output' tab for the result ☝️ console.log(item); } run(); ``` Returned output ```javascript { id: "hWl-mnkWRYmMCSTq4z_piQ", title: "My first blog post!", content: "Lorem ipsum dolor sit amet...", category: "24", image: { alt: "Alt text", title: "Image title", custom_data: {}, focal_point: null, upload_id: "20042921", }, meta: { created_at: "2020-04-21T07:57:11.124Z", updated_at: "2020-04-21T07:57:11.124Z", published_at: "2020-04-21T07:57:11.124Z", first_published_at: "2020-04-21T07:57:11.124Z", publication_scheduled_at: "2020-04-21T07:57:11.124Z", unpublishing_scheduled_at: "2020-04-21T07:57:11.124Z", status: "published", is_current_version_valid: true, is_published_version_valid: true, current_version: "4234", stage: null, has_children: true, }, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, } ``` ###### Example Nested mode Sometimes, you may wish to fetch a record that has embedded blocks inside Modular Content, Single Block or Structured Text fields. By default, those nested blocks are returned as block IDs (ie. `"dhVR2HqgRVCTGFi_0bWqLqA"`), but if you add the `nested: true` query parameter, we'll embed the blocks content *inline* for you. Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import type * as Schema from "./schema.js"; /* * BlogPost * ├─ title: string * └─ sections: rich_text * └─ HeroBlock: headline */ async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // Regular mode — the `sections` field contains bare block IDs. const regular = await client.items.find( "FEzWmQhjQgeHsCrUtvlEMw", ); console.log("-- Regular mode --"); console.log(inspectItem(regular)); // Nested mode — the same `sections` field contains the full block // objects inline, ready to be read or re-sent to the API. const nested = await client.items.find( "FEzWmQhjQgeHsCrUtvlEMw", { nested: true, }, ); console.log("-- Nested mode --"); console.log(inspectItem(nested)); } run(); ``` Returned output ```javascript { id: "FEzWmQhjQgeHsCrUtvlEMw", type: "item", structured_text_field: { schema: "dast", document: { children: [ { item: { type: "item", attributes: { button_label: "Example button", button_url: "https://www.example.com", }, relationships: { item_type: { data: { id: "SkVjHJSGR5CyK16E8TfJxg", type: "item_type" }, }, }, id: "ahxSnFQEQ02K3TjttWAg-Q", }, type: "block", }, { item: { type: "item", attributes: { nested_structured_text_field: { schema: "dast", document: { children: [ { children: [ { type: "span", value: "This is a " }, { marks: ["emphasis"], type: "span", value: "nested", }, { type: "span", value: " structured text block inside the parent structured text field.", }, ], type: "paragraph", }, { item: { type: "item", attributes: { button_label: "And this is a button inside the nested structured text block", button_url: "https://www.example2.com", }, relationships: { item_type: { data: { id: "SkVjHJSGR5CyK16E8TfJxg", type: "item_type", }, }, }, id: "CGqwjPDsTHKGFy1IbC0RAQ", }, type: "block", }, ], type: "root", }, }, }, relationships: { item_type: { data: { id: "Ty4S40cbQH6_VMNnGdd9KA", type: "item_type" }, }, }, id: "AppHB06oRBm-er3oooL_LA", }, type: "block", }, ], type: "root", }, }, item_type: { id: "UVa_hHEBSeefLEUnwoQFig", type: "item_type" }, creator: { id: "104280", type: "account" }, meta: { created_at: "2024-03-13T17:01:19.243+00:00", updated_at: "2024-03-13T17:14:17.444+00:00", published_at: "2024-03-13T17:14:17.597+00:00", publication_scheduled_at: null, unpublishing_scheduled_at: null, first_published_at: "2024-03-13T17:01:19.326+00:00", is_valid: true, is_current_version_valid: true, is_published_version_valid: true, status: "published", current_version: "DLtyHZ2MTDqYMg7g5mgYEw", stage: null, }, } ``` ## TypeScript typing Reading a record without typed schemas means every attribute comes back as `unknown`, and the IDE can't help you navigate it. The single biggest lever you have is passing a generated `Schema.X` marker as the generic on `items.find`. TypeScript then knows the exact shape of the returned record — its field names, types, and block structures — so reads are typed end-to-end: ```ts import * as Schema from "./schema"; const record = await client.items.find("record-id"); record.title; // typed, not unknown ``` For the exact type of a specific field on the returned record (to annotate a helper or intermediate variable), index `ApiTypes.Item["field_api_key"]` (or `ApiTypes.ItemInNestedResponse["field_api_key"]` when fetching with `nested: true`). See the [full TypeScript guide](https://www.datocms.com/cma-ts-schema.md) for how to generate `schema.ts` and the complete pattern. ## Query parameters **`nested`** - Type: boolean For Modular Content, Structured Text and Single Block fields. If set, returns full payload for nested blocks instead of IDs **`version`** - Type: string - Example: `"published"` Whether you want the currently published versions (`published`) of your records, or the latest available (`current`, default) ## Returns Returns a resource object of type [item](/docs/content-management-api/resources/item.md) --- # Content Management API — Delete a record Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item/destroy.md ## Returns Returns a resource object of type [item](/docs/content-management-api/resources/item.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemId = "hWl-mnkWRYmMCSTq4z_piQ"; const item = await client.items.destroy(itemId); // Check the 'Returned output' tab for the result ☝️ console.log(item); } run(); ``` Returned output ```javascript { id: "hWl-mnkWRYmMCSTq4z_piQ", title: "My first blog post!", content: "Lorem ipsum dolor sit amet...", category: "24", image: { alt: "Alt text", title: "Image title", custom_data: {}, focal_point: null, upload_id: "20042921", }, meta: { created_at: "2020-04-21T07:57:11.124Z", updated_at: "2020-04-21T07:57:11.124Z", published_at: "2020-04-21T07:57:11.124Z", first_published_at: "2020-04-21T07:57:11.124Z", publication_scheduled_at: "2020-04-21T07:57:11.124Z", unpublishing_scheduled_at: "2020-04-21T07:57:11.124Z", status: "published", is_current_version_valid: true, is_published_version_valid: true, current_version: "4234", stage: null, has_children: true, }, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, } ``` --- # Content Management API — Publish a record Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item/publish.md When the [draft/published system](/docs/general-concepts/draft-published.md) is enabled for a model, records will remain in a *Draft* status until they are *Published*. When publishing a record, you can choose to either publish the whole record, or just some of its locales / non-localized content. This is similar to how the "Publish" dropdown button in the UI works. ###### Example Publish entire record (all locales & non-localized content) This is the default behavior when you don't provide a request body. This will publish the entire record, including all its localized and non-localized fields. Do not include a request body at all — not even an empty object `{}`. Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import type * as Schema from "./schema.js"; /* * BlogPost * ├─ title: string * └─ slug: slug */ async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemId = "T4m4tPymSACFzsqbZS65WA"; // The record starts as a Draft. The attributes are the same before and // after publishing; what changes is the record's publication state, which // lives in `meta` (status / published_at / first_published_at). const beforePublish = await client.items.find(itemId); console.log("-- BEFORE PUBLISH --"); console.log(`meta.status: "${beforePublish.meta.status}"`); console.log(`meta.published_at: ${beforePublish.meta.published_at}`); console.log(inspectItem(beforePublish)); const publishedRecord = await client.items.publish(itemId); console.log("-- AFTER PUBLISH --"); console.log(`meta.status: "${publishedRecord.meta.status}"`); console.log(`meta.published_at: ${publishedRecord.meta.published_at}`); console.log(inspectItem(publishedRecord)); } run(); ``` Returned output ```javascript -- BEFORE PUBLISH -- meta.status: "draft" meta.published_at: null └ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title: "My first blog post!" └ slug: "my-first-blog-post" -- AFTER PUBLISH -- meta.status: "published" meta.published_at: 2026-04-23T10:02:27.599+01:00 └ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title: "My first blog post!" └ slug: "my-first-blog-post" ``` ###### Example Selective publishing (only specified locales or non-localized content) Selective publishing is used when you don't want to publish the entire record. Instead, you can publish a combination of: - Zero or more [specified locales](http://localhost:3000/product-updates/get-locales-list-from-graphql) - And/or all of this record's non-localized fields In this example, we will only publish the `en` locale. The `it` and `es` versions of `localized_title` will not be published, and will retain their previously published titles. `non_localized_field` will also keep its previously published value. Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import type * as Schema from "./schema.js"; /* * BlogPost * ├─ title: string (localized) * └─ slug: slug */ async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemId = "T4m4tPymSACFzsqbZS65WA"; // The record is already Published with content in both locales, but its // `en` title has newer draft changes that haven't been published yet. // Pass `version: "published"` to read the latest *published* version so // we can see what is actually live. const publishedBefore = await client.items.find(itemId, { version: "published", }); console.log("-- Published version BEFORE --"); console.log(inspectItem(publishedBefore)); // Selectively publish only the `en` locale — leave `it` untouched and // do not re-publish non-localized fields (the slug). await client.items.publish(itemId, { content_in_locales: ["en"], non_localized_content: false, }); // Re-read the published version: `en` is now the updated text; `it` and // `slug` are unchanged. const publishedAfter = await client.items.find(itemId, { version: "published", }); console.log("-- Published version AFTER --"); console.log(inspectItem(publishedAfter)); } run(); ``` Returned output ```javascript -- Published version BEFORE -- └ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title │ ├ en: "My first blog post!" │ └ it: "Il mio primo post!" └ slug: "my-first-blog-post" -- Published version AFTER -- └ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title │ ├ en: "My first blog post! (updated)" │ └ it: "Il mio primo post!" └ slug: "my-first-blog-post" ``` ## TypeScript typing Publishing a record without typed schemas gives you back a record whose attributes are all `unknown` — any downstream code that reads from it is fighting TypeScript. The single biggest lever you have is passing a generated `Schema.X` marker as the generic on `items.publish`. TypeScript then knows the exact shape of the returned record — its field names, types, and block structures — so reads are typed end-to-end: ```ts import * as Schema from "./schema"; const record = await client.items.publish("record-id"); record.title; // typed, not unknown ``` For the exact type of a specific field on the returned record (to annotate a helper or intermediate variable), index `ApiTypes.Item["field_api_key"]`. See the [full TypeScript guide](https://www.datocms.com/cma-ts-schema.md) for how to generate `schema.ts` and the complete pattern. ## Query parameters **`recursive`** - Type: boolean When `recursive` is `true`, if the record belongs to a [tree-like collection](https://www.datocms.com/docs/content-modelling/trees), and any of the parent records aren't published, those parent records will published as well. When `recursive` is `false` or not specified, an `UNPUBLISHED_PARENT` error will occur in such cases. ## Body parameters For this endpoint, the body is not required and can be entirely omitted. **`content_in_locales`** - Required - Type: Array\ - Examples: `["en"]`, `["en", "it"]` Array of [valid locale codes in this project](/product-updates/get-locales-list-from-graphql) to publish. **`non_localized_content`** - Required - Type: boolean Whether non-localized content will be published ## Returns Returns a resource object of type [item](/docs/content-management-api/resources/item.md) ## Other examples ###### Example Known issue with legacy client: 'id' is not a permitted key If you're using the the older, now-deprecated [`datocms-client`](https://www.npmjs.com/package/datocms-client) instead of the current [`@datocms/cma-client`](https://www.npmjs.com/package/@datocms/cma-client), there is a known issue with the `item.publish()` method. It will return an error like: ```json { "data": [ { "id": "abcdef", "type": "api_error", "attributes": { "code": "INVALID_FORMAT", "details": { "messages": [ "#/data: failed schema #/definitions/item/links/13/schema/properties/data: \"id\" is not a permitted key." ] } } } ] } ``` The workaround is to add `{serializeRequest: false}` as the third parameter of that method, like: ```js await client.item.publish( "1234567890", // record ID {}, // body {}, // query string { serializeRequest: false } // this is the actual workaround ); ``` This tells the deprecated client to skip some of its internal serialization rules (which used to work, but no longer) and instead just send the raw syntax that you provide. While this should allow that method to continue working for the time being, it is important that you upgrade to the modern client as soon as possible. As of 2024, the old client has been deprecated for more than 2 years and will not receive any further updates. It is possible that this method and others will further break over time, possibly impacting production workflows. Code ```javascript import { SiteClient } from "datocms-client"; async function run() { const client = new SiteClient(process.env.DATOCMS_API_TOKEN); const itemId = "T4m4tPymSACFzsqbZS65WA"; const publishedRecord = await client.items.publish( itemId, {}, // body {}, // query string { serializeRequest: false }, // this is the actual workaround ); console.log(publishedRecord); } run(); ``` Returned output ```javascript { id: "hWl-mnkWRYmMCSTq4z_piQ", title: "My first blog post!", content: "Lorem ipsum dolor sit amet...", category: "24", image: { alt: "Alt text", title: "Image title", custom_data: {}, focal_point: null, upload_id: "20042921", }, meta: { created_at: "2020-04-21T07:57:11.124Z", updated_at: "2020-04-21T07:57:11.124Z", published_at: "2020-04-21T07:57:11.124Z", first_published_at: "2020-04-21T07:57:11.124Z", publication_scheduled_at: "2020-04-21T07:57:11.124Z", unpublishing_scheduled_at: "2020-04-21T07:57:11.124Z", status: "published", is_current_version_valid: true, is_published_version_valid: true, current_version: "4234", stage: null, has_children: true, }, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, } ``` --- # Content Management API — Unpublish a record Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item/unpublish.md In a model where the [draft/published system](/docs/general-concepts/draft-published.md) is enabled, *Published* records can subsequently be **Unpublished** in order to return them to *Draft* status. When unpublishing a record, you can choose to either unpublish the whole record, or just some of its locales, similar to how the "Unpublish" dropdown button in the UI sidebar works. ###### Example Unpublish entire record (all locales) This is the default behavior when you don't provide a request body. This will unpublish the entire record, including all its localizations. Do not include a request body at all — not even an empty object `{}`. Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import type * as Schema from "./schema.js"; /* * BlogPost * ├─ title: string * └─ slug: slug */ async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemId = "fyq6ADkeTL6Ryk7s98xmHw"; // The record starts as Published. The attributes are the same before and // after unpublishing; what changes is the record's publication state, // which lives in `meta` (status / published_at). const beforeUnpublish = await client.items.find(itemId); console.log("-- BEFORE UNPUBLISH --"); console.log(`meta.status: "${beforeUnpublish.meta.status}"`); console.log(`meta.published_at: ${beforeUnpublish.meta.published_at}`); console.log(inspectItem(beforeUnpublish)); const unpublishedItem = await client.items.unpublish(itemId); console.log("-- AFTER UNPUBLISH --"); console.log(`meta.status: "${unpublishedItem.meta.status}"`); console.log(`meta.published_at: ${unpublishedItem.meta.published_at}`); console.log(inspectItem(unpublishedItem)); } run(); ``` Returned output ```javascript -- BEFORE UNPUBLISH -- meta.status: "published" meta.published_at: 2026-04-23T10:02:26.737+01:00 └ Item "fyq6ADkeTL6Ryk7s98xmHw" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title: "My first blog post!" └ slug: "my-first-blog-post" -- AFTER UNPUBLISH -- meta.status: "draft" meta.published_at: null └ Item "fyq6ADkeTL6Ryk7s98xmHw" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title: "My first blog post!" └ slug: "my-first-blog-post" ``` ###### Example Selective unpublishing (unpublish specified locales only, keeping others published) Selective unpublishing is used when you only want to unpublish certain localizations instead of the whole record. **Please note**: You can only unpublish locales that are currently published within a specific record. If you try to unpublish a record's locale that is already unpublished (i.e. in draft state) or doesn't exist in the record at all (even if the project has that locale), you will get a `VALIDATION_INVALID` error on the `content_in_locales` field. Code ```javascript import { buildClient, inspectItem } from "@datocms/cma-client-node"; import type * as Schema from "./schema.js"; /* * BlogPost * ├─ title: string (localized) * └─ slug: slug */ async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemId = "fyq6ADkeTL6Ryk7s98xmHw"; // Read the current published version so we can compare it to the new // published version after the selective unpublish. const publishedBefore = await client.items.find(itemId, { version: "published", }); console.log("-- Published version BEFORE --"); console.log(inspectItem(publishedBefore)); // Unpublish only the `it` locale — the `en` locale and the non-localized // fields stay published. await client.items.unpublish(itemId, { content_in_locales: ["it"], }); // Re-read the published version: the `it` translation is gone; `en` and // `slug` are unchanged. const publishedAfter = await client.items.find(itemId, { version: "published", }); console.log("-- Published version AFTER --"); console.log(inspectItem(publishedAfter)); } run(); ``` Returned output ```javascript -- Published version BEFORE -- └ Item "fyq6ADkeTL6Ryk7s98xmHw" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title │ ├ en: "My first blog post!" │ └ it: "Il mio primo post!" └ slug: "my-first-blog-post" -- Published version AFTER -- └ Item "fyq6ADkeTL6Ryk7s98xmHw" (item_type: "UZyfjdBES8y2W2ruMEHSoA") ├ title │ └ en: "My first blog post!" └ slug: "my-first-blog-post" ``` ## TypeScript typing Unpublishing a record without typed schemas gives you back a record whose attributes are all `unknown` — any downstream code that reads from it is fighting TypeScript. The single biggest lever you have is passing a generated `Schema.X` marker as the generic on `items.unpublish`. TypeScript then knows the exact shape of the returned record — its field names, types, and block structures — so reads are typed end-to-end: ```ts import * as Schema from "./schema"; const record = await client.items.unpublish("record-id"); record.title; // typed, not unknown ``` For the exact type of a specific field on the returned record (to annotate a helper or intermediate variable), index `ApiTypes.Item["field_api_key"]`. See the [full TypeScript guide](https://www.datocms.com/cma-ts-schema.md) for how to generate `schema.ts` and the complete pattern. ## Query parameters **`recursive`** - Type: boolean When `recursive` is `true`, if the record belongs to a [tree-like collection](https://www.datocms.com/docs/content-modelling/trees), and any of the children records are published, those children records will unpublished as well. When `recursive` is `false` or not specified, a `PUBLISHED_CHILDREN` error will occur in such cases. ## Body parameters For this endpoint, the body is not required and can be entirely omitted. **`content_in_locales`** - Required - Type: Array\ - Examples: `["en"]`, `["en", "it"]` Array of locales to publish. They must be currently published in this record. To unpublish all locales, do NOT use this parameter, but instead unpublish the entire record by leaving the body blank (see example above). ## Returns Returns a resource object of type [item](/docs/content-management-api/resources/item.md) --- # Content Management API — Publish items in bulk Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item/bulk_publish.md ## Body parameters **`items`** - Required - Type: Array<[ResourceLinkage\<"item"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item.md)> Records to publish (a maximum of 200 records are allowed per request) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const item = await client.items.bulkPublish({ items: [{ type: "item", id: "hWl-mnkWRYmMCSTq4z_piQ" }], }); // Check the 'Returned output' tab for the result ☝️ console.log(item); } run(); ``` Returned output ```javascript [] ``` --- # Content Management API — Unpublish items in bulk Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item/bulk_unpublish.md ## Body parameters **`items`** - Required - Type: Array<[ResourceLinkage\<"item"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item.md)> Records to unpublish (a maximum of 200 records are allowed per request) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const item = await client.items.bulkUnpublish({ items: [{ type: "item", id: "hWl-mnkWRYmMCSTq4z_piQ" }], }); // Check the 'Returned output' tab for the result ☝️ console.log(item); } run(); ``` Returned output ```javascript [] ``` --- # Content Management API — Destroy items in bulk Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item/bulk_destroy.md ## Body parameters **`items`** - Required - Type: Array<[ResourceLinkage\<"item"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item.md)> Records to delete (a maximum of 200 records are allowed per request) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const item = await client.items.bulkDestroy({ items: [{ type: "item", id: "hWl-mnkWRYmMCSTq4z_piQ" }], }); // Check the 'Returned output' tab for the result ☝️ console.log(item); } run(); ``` Returned output ```javascript [] ``` --- # Content Management API — Move items to stage in bulk Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item/bulk_move_to_stage.md ## Body parameters **`stage`** - Required - Type: string - Example: `"in_review"` Stage to be moved to **`items`** - Required - Type: Array<[ResourceLinkage\<"item"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item.md)> Records to move (a maximum of 200 records are allowed per request) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const item = await client.items.bulkMoveToStage({ stage: "in_review", items: [{ type: "item", id: "hWl-mnkWRYmMCSTq4z_piQ" }], }); // Check the 'Returned output' tab for the result ☝️ console.log(item); } run(); ``` Returned output ```javascript [] ``` --- # Content Management API — Scheduled publication Source [docs]: https://www.datocms.com/docs/content-management-api/resources/scheduled-publication.md You can create scheduled publication to publish records in the future ## Object payload **`id`** - Type: string - Example: `"34"` ID of scheduled_publication **`type`** - Type: string Must be exactly `"scheduled_publication"`. **`publication_scheduled_at`** - Type: date-time - Example: `"2025-02-10T11:03:42Z"` The future date for the publication **`selective_publication`** - Type: null, object Specifies which content should be published. If null, the whole record will be published.
Show object format **`content_in_locales`** - Type: Array\ List of locales whose content will be published **`non_localized_content`** - Type: boolean Whether the non-localized content has to be published or not
**`item`** - Type: [ResourceLinkage\<"item"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item.md) Item --- # Content Management API — Create a new scheduled publication Source [docs]: https://www.datocms.com/docs/content-management-api/resources/scheduled-publication/create.md ## Body parameters **`publication_scheduled_at`** - Required - Type: date-time - Example: `"2025-02-10T11:03:42Z"` The future date for the publication **`selective_publication`** - Optional - Type: null, object Specifies which content should be published. If null, the whole record will be published.
Show object format **`content_in_locales`** - Required - Type: Array\ List of locales whose content will be published **`non_localized_content`** - Required - Type: boolean Whether the non-localized content has to be published or not
## Returns Returns a resource object of type [scheduled\_publication](/docs/content-management-api/resources/scheduled-publication.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemId = "34"; const scheduledPublication = await client.scheduledPublication.create( itemId, { publication_scheduled_at: "2025-02-10T11:03:42Z" }, ); // Check the 'Returned output' tab for the result ☝️ console.log(scheduledPublication); } run(); ``` Returned output ```javascript { id: "34", publication_scheduled_at: "2025-02-10T11:03:42Z", selective_publication: { content_in_locales: ["en"], non_localized_content: true, }, item: { type: "item", id: "hWl-mnkWRYmMCSTq4z_piQ" }, } ``` --- # Content Management API — Delete a scheduled publication Source [docs]: https://www.datocms.com/docs/content-management-api/resources/scheduled-publication/destroy.md ## Returns Returns a resource object of type [item](/docs/content-management-api/resources/item.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemId = "34"; const scheduledPublication = await client.scheduledPublication.destroy(itemId); // Check the 'Returned output' tab for the result ☝️ console.log(scheduledPublication); } run(); ``` Returned output ```javascript { id: "hWl-mnkWRYmMCSTq4z_piQ", title: "My first blog post!", content: "Lorem ipsum dolor sit amet...", category: "24", image: { alt: "Alt text", title: "Image title", custom_data: {}, focal_point: null, upload_id: "20042921", }, meta: { created_at: "2020-04-21T07:57:11.124Z", updated_at: "2020-04-21T07:57:11.124Z", published_at: "2020-04-21T07:57:11.124Z", first_published_at: "2020-04-21T07:57:11.124Z", publication_scheduled_at: "2020-04-21T07:57:11.124Z", unpublishing_scheduled_at: "2020-04-21T07:57:11.124Z", status: "published", is_current_version_valid: true, is_published_version_valid: true, current_version: "4234", stage: null, has_children: true, }, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, } ``` --- # Content Management API — Scheduled unpublishing Source [docs]: https://www.datocms.com/docs/content-management-api/resources/scheduled-unpublishing.md You can create a scheduled unpublishing to unpublish records in the future ## Object payload **`id`** - Type: string - Example: `"34"` ID of scheduled_unpublishing **`type`** - Type: string Must be exactly `"scheduled_unpublishing"`. **`unpublishing_scheduled_at`** - Type: date-time - Example: `"2025-02-10T11:03:42Z"` The future date for the unpublishing **`content_in_locales`** - Type: null, Array\ List of locales whose content will be unpublished, or nil if the whole record needs to be unpublished **`item`** - Type: [ResourceLinkage\<"item"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item.md) Item --- # Content Management API — Create a new scheduled unpublishing Source [docs]: https://www.datocms.com/docs/content-management-api/resources/scheduled-unpublishing/create.md ## Body parameters **`unpublishing_scheduled_at`** - Required - Type: date-time - Example: `"2025-02-10T11:03:42Z"` The future date for the unpublishing **`content_in_locales`** - Optional - Type: null, Array\ List of locales whose content will be unpublished, or nil if the whole record needs to be unpublished ## Returns Returns a resource object of type [scheduled\_unpublishing](/docs/content-management-api/resources/scheduled-unpublishing.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemId = "34"; const scheduledUnpublishing = await client.scheduledUnpublishing.create( itemId, { unpublishing_scheduled_at: "2025-02-10T11:03:42Z" }, ); // Check the 'Returned output' tab for the result ☝️ console.log(scheduledUnpublishing); } run(); ``` Returned output ```javascript { id: "34", unpublishing_scheduled_at: "2025-02-10T11:03:42Z", content_in_locales: ["en"], item: { type: "item", id: "hWl-mnkWRYmMCSTq4z_piQ" }, } ``` --- # Content Management API — Delete a scheduled unpublishing Source [docs]: https://www.datocms.com/docs/content-management-api/resources/scheduled-unpublishing/destroy.md ## Returns Returns a resource object of type [item](/docs/content-management-api/resources/item.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemId = "34"; const scheduledUnpublishing = await client.scheduledUnpublishing.destroy(itemId); // Check the 'Returned output' tab for the result ☝️ console.log(scheduledUnpublishing); } run(); ``` Returned output ```javascript { id: "hWl-mnkWRYmMCSTq4z_piQ", title: "My first blog post!", content: "Lorem ipsum dolor sit amet...", category: "24", image: { alt: "Alt text", title: "Image title", custom_data: {}, focal_point: null, upload_id: "20042921", }, meta: { created_at: "2020-04-21T07:57:11.124Z", updated_at: "2020-04-21T07:57:11.124Z", published_at: "2020-04-21T07:57:11.124Z", first_published_at: "2020-04-21T07:57:11.124Z", publication_scheduled_at: "2020-04-21T07:57:11.124Z", unpublishing_scheduled_at: "2020-04-21T07:57:11.124Z", status: "published", is_current_version_valid: true, is_published_version_valid: true, current_version: "4234", stage: null, has_children: true, }, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, } ``` --- # Content Management API — Upload Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload.md Each media object you upload to the Media Area of your DatoCMS project is represented as an `upload` entity. ## Object payload **`id`** - Type: string - Example: `"q0VNpiNQSkG6z0lif_O1zg"` RFC 4122 UUID of upload expressed in URL-safe base64 format **`type`** - Type: string Must be exactly `"upload"`. **`size`** - Type: integer - Example: `444` size of the upload **`width`** - Type: null, integer - Example: `30` Width of image **`height`** - Type: null, integer - Example: `30` Height of image **`path`** - Type: string - Example: `"/45/1496845848-digital-cats.jpg"` Upload path **`basename`** - Type: string - Example: `"digital-cats"` Upload basename **`filename`** - Type: string - Example: `"digital-cats.jpg"` Upload filename **`url`** - Type: string - Example: `"https://www.datocms-assets.com/45/1496845848-digital-cats.jpg"` Upload URL **`format`** - Type: string, null - Example: `"jpg"` Format **`author`** - Type: string, null - Example: `"Mark Smith"` Author **`copyright`** - Type: string, null - Example: `"2020 DatoCMS"` Copyright **`notes`** - Type: string, null - Example: `"Nyan the cat"` Notes **`md5`** - Type: string - Example: `"873c296d0f2b7ee569f2d7ddaebc0d33"` The MD5 hash of the asset **`duration`** - Type: integer, null - Example: `62` Seconds of duration for the video **`frame_rate`** - Type: integer, null - Example: `30` Frame rate (FPS) for the video **`blurhash`** - Type: string, null - Example: `"LEHV6nWB2yk8pyo0adR*.7kCMdnj"` Blurhash for the asset **`thumbhash`** - Type: string, null - Example: `"UhqCDQIkrHOfVG8wBa2v39z7CXeqZWFLdg=="` Base64 encoded ThumbHash for the asset **`mux_playback_id`** - Type: string, null - Example: `"a1B2c3D4e5F6g7H8i9"` Public Mux playback ID. Used with stream.mux.com to create the source URL for a video player. **`mux_mp4_highest_res`** - Type: enum, null - Example: `"high"` Maximum quality of MP4 rendition available
Show enum values **`high`** **`medium`** **`low`**
**`default_field_metadata`** - Type: object Per-asset default metadata applied when no record-level overrides are present. `alt`, `title`, and `custom_data` are objects keyed by locale; `focal_point` (image assets) and `poster_time` (video assets) are a single value per asset. See [non-localized focal points](https://www.datocms.com/product-updates/non-localized-focal-points) for more info. Example: ```json { alt: { en: "this is the default alternate text" }, title: { en: "this is the default title" }, custom_data: { en: { foo: "bar" } }, focal_point: { x: 0.5, y: 0.5 }, poster_time: 12.5, } ```
Show object format **`alt`** - Type: object - Example: `{ en: "Alternate text" }` Alternate text per locale **`title`** - Type: object - Example: `{ en: "Title" }` Title per locale **`custom_data`** - Type: object - Example: `{ en: { add_watermark: true } }` Object with arbitrary metadata, per locale **`focal_point`** - Type: object, null Focal point (only for image assets)
Show object format **`x`** - Type: number - Example: `0.5` Horizontal position expressed as float between 0 and 1 **`y`** - Type: number - Example: `0.5` Vertical position expressed as float between 0 and 1
**`poster_time`** - Type: number, null - Example: `12.5` Poster time in seconds (only for video assets). Float seconds into the video used to generate the thumbnail; null uses Mux's default (middle of the video)
**`is_image`** - Type: boolean Is this upload an image? **`created_at`** - Type: null, date-time Date of upload **`updated_at`** - Type: null, date-time Date of last update **`mime_type`** - Type: null, string - Example: `"image/jpeg"` Mime type of upload **`tags`** - Type: Array\ - Example: `["cats"]` Tags **`smart_tags`** - Type: Array\ - Example: `["robot-cats"]` Smart tags **`exif_info`** - Type: object Exif information Example: ```json { iso: 10000, model: "ILCE-7", flash_mode: 16, focal_length: 35, exposure_time: 0.0166667, } ``` **`colors`** - Type: Array\ Dominant colors of the image Example: ```json [ { red: 206, green: 203, blue: 167, alpha: 255 }, { red: 158, green: 163, blue: 93, alpha: 255 }, ] ```
Show objects format inside array **`red`** - Type: integer - Example: `115` Red value (from 0 to 255) **`green`** - Type: integer - Example: `133` Green value (from 0 to 255) **`blue`** - Type: integer - Example: `27` Blue value (from 0 to 255) **`alpha`** - Type: integer - Example: `255` Alpha value (from 0 to 255)
**`meta.antivirus`** - Type: object Antivirus scan information
Show object format **`status`** - Type: enum - Example: `"clean"` Antivirus scan status of the asset
Show enum values **`pending`** **`clean`** **`infected`** **`failed`** **`skipped`**
**`checked_at`** - Type: date-time, null Date of the last antivirus scan **`threat_name`** - Type: string, null Name of the threat detected by the antivirus scan, if any
**`creator`** - Type: [ResourceLinkage\<"account"\>](https://www-draft.datocms.com/docs/content-management-api/resources/account.md), [ResourceLinkage\<"access_token"\>](https://www-draft.datocms.com/docs/content-management-api/resources/access_token.md), [ResourceLinkage\<"user"\>](https://www-draft.datocms.com/docs/content-management-api/resources/user.md), [ResourceLinkage\<"sso_user"\>](https://www-draft.datocms.com/docs/content-management-api/resources/sso_user.md), [ResourceLinkage\<"organization"\>](https://www-draft.datocms.com/docs/content-management-api/resources/organization.md) The entity (account/collaborator/access token) who created the asset **`upload_collection`** - Type: [ResourceLinkage\<"upload_collection"\>](https://www-draft.datocms.com/docs/content-management-api/resources/upload_collection.md), null Upload collection to which the asset belongs --- # Content Management API — Create a new upload Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload/create.md The DatoCMS clients provide numerous methods for users to upload resources. The method you choose can be influenced by different aspects like the platform you're using (such as Node.js or a browser) and where the resource is coming from — like a local file, a remote URL, or a [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) or [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) obtained from `` elements. ###### Example Node.js: Create an upload from a local file This example shows how to add assets to the Media Area by uploading a local file. Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // Create upload resource from a local file const upload2 = await client.uploads.createFromLocalFile({ // local path of the file to upload localPath: "./image.png", // if you want, you can specify a different base name for the uploaded file filename: "different-image-name.png", // skip the upload and return an existing resource if it's already present in the Media Area: skipCreationIfAlreadyExists: true, // specify some additional metadata to the upload resource author: "New author!", copyright: "New copyright", default_field_metadata: { alt: { en: "New default alt" }, title: { en: "New default title" }, custom_data: { en: { watermark: true, }, }, focal_point: { x: 0.3, y: 0.6, }, }, }); console.log(upload2); } run(); ``` Returned output ```javascript const result = { id: "4124", size: 444, width: 30, height: 30, path: "/45/1496845848-different-image-name.png", basename: "image", url: "https://www.datocms-assets.com/45/1496845848-different-image-name.png", format: "jpg", author: "New author!", copyright: "New copyright", notes: null, default_field_metadata: { alt: { en: "new default alt" }, title: { en: "new default title" }, custom_data: { en: { watermark: true, }, }, focal_point: { x: 0.3, y: 0.6, }, }, is_image: true, tags: [], }; ``` ###### Example Node.js: Create an upload from a remote URL Here's a demonstration of how you can uploading an asset from a remote location, accessible through a URL. Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // Create upload resource from a remote URL const upload = await client.uploads.createFromUrl({ // remote URL to upload url: "https://example.com/image.png", // if you want, you can specify a different base name for the uploaded file filename: "different-image-name.png", // skip the upload and return an existing resource if it's already present in the Media Area: skipCreationIfAlreadyExists: true, // specify some additional metadata to the upload resource author: "New author!", copyright: "New copyright", }); console.log(upload); } run(); ``` Returned output ```javascript const result = { id: "4124", size: 444, width: 30, height: 30, path: "/45/1496845848-different-image-name.png", basename: "image", url: "https://www.datocms-assets.com/45/1496845848-different-image-name.png", format: "jpg", author: "New author!", copyright: "New copyright", notes: null, default_field_metadata: { alt: { en: "new default alt" }, title: { en: "new default title" }, custom_data: { en: { watermark: true, }, }, focal_point: { x: 0.3, y: 0.6, }, }, is_image: true, tags: [], }; ``` ###### Example Browser: Create an upload from a File or Blob object This example shows how to add assets to the Media Area from the browser, starting from a [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) or [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) object. **Important!** Make sure to use the `@datocms/cma-client-browser` package, or the `client.uploads.createFromFileOrBlob()` method won't be available! Code ```javascript import { buildClient } from "@datocms/cma-client-browser"; // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); function createUpload(file: File) { return client.uploads.createFromFileOrBlob({ // File object to upload fileOrBlob: file, // if you want, you can specify a different base name for the uploaded file filename: "different-image-name.png", // specify some additional metadata to the upload resource author: "New author!", copyright: "New copyright", default_field_metadata: { alt: { en: "New default alt" }, title: { en: "New default title" }, custom_data: { en: { watermark: true, }, }, focal_point: { x: 0.3, y: 0.6, }, }, }); } const fileInput = document.querySelector( 'input[type="file"]', ) as HTMLInputElement; fileInput.addEventListener("change", async (event) => { const target = event.target as HTMLInputElement; const files = target.files; if (files) { for (let i = 0; i < files.length; i++) { const file = files[i]; if (file) { createUpload(file).then((upload) => console.log(upload)); } } } }); ``` Returned output ```javascript const response = { id: "4124", size: 444, width: 30, height: 30, path: "/45/1496845848-different-image-name.png", basename: "image", url: "https://www.datocms-assets.com/45/1496845848-different-image-name.png", format: "jpg", author: "New author!", copyright: "New copyright", notes: null, default_field_metadata: { alt: { en: "new default alt" }, title: { en: "new default title" }, custom_data: { en: { watermark: true, }, }, focal_point: { x: 0.3, y: 0.6, }, }, is_image: true, tags: [], }; ``` ###### Example Monitoring the progress Regardless of the upload method, you can always get information about the operation's progress by listening to the events that hit the `onProgress` callback. Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); await client.uploads.createFromUrl({ url: "https://example.com/image.png", onProgress: ({ type, ...rest }) => { // info.type can be one of the following: // // * DOWNLOADING_FILE: client is downloading the asset from the specified URL // * REQUESTING_UPLOAD_URL: client is requesting permission to upload the asset to the DatoCMS CDN // * UPLOADING_FILE: client is uploading the asset // * CREATING_UPLOAD_OBJECT: client is finalizing the creation of the upload resource // // The rest of the information depends on the type of notification console.log(type, rest); }, }); } run(); ``` Returned output ```javascript DOWNLOADING_FILE { url: "https://example.com/image.png", progress: 20 } DOWNLOADING_FILE { url: "https://example.com/image.png", progress: 90 } DOWNLOADING_FILE { url: "https://example.com/image.png", progress: 100 } REQUESTING_UPLOAD_URL { filaname: 'image.png' } UPLOADING_FILE { progress: 10 } UPLOADING_FILE { progress: 80 } UPLOADING_FILE { progress: 100 } CREATING_UPLOAD_OBJECT undefined ``` Each available method yields a cancellable promise, granting the ability to halt a currently running upload operation. ###### Example Cancelling an in-progress upload It is possible to cancel an upload operation by calling the `.cancel()` method on the promise returned by one of the upload creation methods (`createFromUrl()`, `createFromLocalFile()` in NodeJS, `createFromFileOrBlob()` in browser): Code ```javascript import { type ApiTypes, buildClient, type CancelablePromise, CanceledPromiseError, } from "@datocms/cma-client-browser"; // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); let cancelablePromise: CancelablePromise | null = null; const cancelButton = document.querySelector("button")!; cancelButton.addEventListener("click", () => { if (cancelablePromise) { cancelablePromise.cancel(); } }); const fileInput = document.querySelector( 'input[type="file"]', ) as HTMLInputElement; fileInput.addEventListener("change", async (event) => { const target = event.target as HTMLInputElement; const files = target.files; if (files?.[0]) { cancelablePromise = client.uploads.createFromFileOrBlob({ fileOrBlob: files[0], }); cancelablePromise .then((upload) => { cancelablePromise = null; console.log(upload); }) .catch((e) => { if (e instanceof CanceledPromiseError) { console.log("User canceled the upload process!"); } else { throw e; } }); } }); ``` Returned output ```javascript { id: "q0VNpiNQSkG6z0lif_O1zg", size: 444, width: 30, height: 30, path: "/45/1496845848-digital-cats.jpg", basename: "digital-cats", filename: "digital-cats.jpg", url: "https://www.datocms-assets.com/45/1496845848-digital-cats.jpg", format: "jpg", author: "Mark Smith", copyright: "2020 DatoCMS", notes: "Nyan the cat", md5: "873c296d0f2b7ee569f2d7ddaebc0d33", duration: 62, frame_rate: 30, blurhash: "LEHV6nWB2yk8pyo0adR*.7kCMdnj", thumbhash: "UhqCDQIkrHOfVG8wBa2v39z7CXeqZWFLdg==", mux_playback_id: "a1B2c3D4e5F6g7H8i9", mux_mp4_highest_res: "high", default_field_metadata: { alt: { en: "this is the default alternate text" }, title: { en: "this is the default title" }, custom_data: { en: { foo: "bar" } }, focal_point: { x: 0.5, y: 0.5 }, poster_time: 12.5, }, is_image: true, created_at: "2020-04-21T07:57:11.124Z", updated_at: "2020-04-21T07:57:11.124Z", mime_type: "image/jpeg", tags: ["cats"], smart_tags: ["robot-cats"], exif_info: { iso: 10000, model: "ILCE-7", flash_mode: 16, focal_length: 35, exposure_time: 0.0166667, }, colors: [ { red: 206, green: 203, blue: 167, alpha: 255 }, { red: 158, green: 163, blue: 93, alpha: 255 }, ], meta: { antivirus: { status: "clean", checked_at: "2020-04-21T07:57:11.124Z", threat_name: null, }, }, creator: { type: "account", id: "312" }, upload_collection: { type: "upload_collection", id: "uinr2zfqQLeCo_1O0-ao-Q", }, } ``` ## Body parameters **`id`** - Optional - Type: string - Example: `"q0VNpiNQSkG6z0lif_O1zg"` RFC 4122 UUID of upload expressed in URL-safe base64 format **`path`** - Required - Type: string - Example: `"/45/1496845848-digital-cats.jpg"` Upload path **`copyright`** - Optional - Type: string, null - Example: `"2020 DatoCMS"` Copyright **`author`** - Optional - Type: string, null - Example: `"Mark Smith"` Author **`notes`** - Optional - Type: string, null - Example: `"Nyan the cat"` Notes **`default_field_metadata`** - Optional - Type: object Patch the asset's default metadata. Send any subset of `alt`/`title`/`custom_data`/`focal_point`/`poster_time` — missing keys preserve their stored values. See the response shape for the full structure and per-key semantics.
Show object format **`alt`** - Optional - Type: object - Example: `{ en: "Alternate text" }` Alternate text per locale **`title`** - Optional - Type: object - Example: `{ en: "Title" }` Title per locale **`custom_data`** - Optional - Type: object - Example: `{ en: { add_watermark: true } }` Object with arbitrary metadata, per locale **`focal_point`** - Optional - Type: object, null Focal point (only for image assets)
Show object format **`x`** - Required - Type: number - Example: `0.5` Horizontal position expressed as float between 0 and 1 **`y`** - Required - Type: number - Example: `0.5` Vertical position expressed as float between 0 and 1
**`poster_time`** - Optional - Type: number, null - Example: `12.5` Poster time in seconds (only for video assets). Float seconds into the video used to generate the thumbnail; null uses Mux's default (middle of the video)
**`tags`** - Optional - Type: Array\ - Example: `["cats"]` Tags **`upload_collection`** - Optional - Type: [ResourceLinkage\<"upload_collection"\>](https://www-draft.datocms.com/docs/content-management-api/resources/upload_collection.md), null Upload collection to which the asset belongs ## Returns Returns a resource object of type [upload](/docs/content-management-api/resources/upload.md) --- # Content Management API — List all uploads Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload/instances.md To retrieve a collection of uploads, send a GET request to the `/uploads` endpoint. The collection is [paginated](/docs/content-management-api/pagination.md), so make sure to iterate over all the pages if you need every record in the collection! The following table contains the list of all the possible arguments, along with their type, description and examples values. Pro tip: in case of any doubts you can always inspect the network calls that the CMS interface is doing, as it's using the Content Management API as well! ## Query parameters **`filter`** - Type: object Attributes to filter uploads
Show object format **`ids`** - Type: string - Example: `"12,31"` IDs to fetch, comma separated **`query`** - Type: string - Example: `"foobar"` Textual query to match. If `locale` is defined, search within that locale. Otherwise environment's main locale will be used. **`fields`** - Type: object - Example: `{ type: { eq: "image" }, size: { gt: 5000000 } }` Same as [GraphQL API uploads filters](/docs/content-delivery-api/filtering-uploads). Use snake_case for fields names. If `locale` is defined, search within that locale. Otherwise environment's main locale will be used.
**`locale`** - Type: string - Example: `"it"` When `filter[query]` or `field[fields]` is defined, filter by this locale. Default: environment's main locale **`order_by`** - Type: string - Example: `"_created_at_DESC,size_ASC"` Fields used to order results. Format: `_`. You can pass multiple comma separated rules. **`page`** - Type: object Parameters to control offset-based pagination
Show object format **`offset`** - Type: integer - Example: `200` The (zero-based) offset of the first entity returned in the collection (defaults to 0) **`limit`** - Type: integer The maximum number of entities to return (defaults to 30, maximum is 500)
## Returns Returns an array of resource objects of type [upload](/docs/content-management-api/resources/upload.md) ## Other examples ###### Example Fetching one page of results vs. the whole collection The `client.uploads.list()` method returns a single page of records, while if you need to iterate over **every** resource in the collection (and not just the first page of results), you can use the `client.uploads.listPagedIterator()` method with an [async iteration statement](https://github.com/tc39/proposal-async-iteration#the-async-iteration-statement-for-await-of), which automatically handles pagination for you. All the details on how to use `list()` and `listPagedIterator()` are outlined [on this page](/docs/content-management-api/pagination.md#paged-iterators). ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // iterates over every page of results for await (const upload of client.uploads.listPagedIterator()) { // Check the 'Returned output' tab for the result ☝️ console.log(upload); } } run(); ``` ###### Example Fetching a filtered list of uploads You can retrieve a list of uploads filtered by a set of conditions. There are different options and you can combine multiple filters together. In this example we are filtering by type and size. In particular, we are searching for images bigger than 5MB. The filtering options are the same as the [GraphQL API uploads filters](/docs/content-delivery-api/filtering-uploads.md). So please check there all the options. ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const uploads = await client.uploads.list({ filter: { fields: { type: { eq: "image", }, size: { gt: 5000000, }, }, }, }); console.log(uploads); } run(); ``` --- # Content Management API — Retrieve an upload Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload/self.md ## Returns Returns a resource object of type [upload](/docs/content-management-api/resources/upload.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const uploadId = "q0VNpiNQSkG6z0lif_O1zg"; const upload = await client.uploads.find(uploadId); // Check the 'Returned output' tab for the result ☝️ console.log(upload); } run(); ``` Returned output ```javascript { id: "q0VNpiNQSkG6z0lif_O1zg", size: 444, width: 30, height: 30, path: "/45/1496845848-digital-cats.jpg", basename: "digital-cats", filename: "digital-cats.jpg", url: "https://www.datocms-assets.com/45/1496845848-digital-cats.jpg", format: "jpg", author: "Mark Smith", copyright: "2020 DatoCMS", notes: "Nyan the cat", md5: "873c296d0f2b7ee569f2d7ddaebc0d33", duration: 62, frame_rate: 30, blurhash: "LEHV6nWB2yk8pyo0adR*.7kCMdnj", thumbhash: "UhqCDQIkrHOfVG8wBa2v39z7CXeqZWFLdg==", mux_playback_id: "a1B2c3D4e5F6g7H8i9", mux_mp4_highest_res: "high", default_field_metadata: { alt: { en: "this is the default alternate text" }, title: { en: "this is the default title" }, custom_data: { en: { foo: "bar" } }, focal_point: { x: 0.5, y: 0.5 }, poster_time: 12.5, }, is_image: true, created_at: "2020-04-21T07:57:11.124Z", updated_at: "2020-04-21T07:57:11.124Z", mime_type: "image/jpeg", tags: ["cats"], smart_tags: ["robot-cats"], exif_info: { iso: 10000, model: "ILCE-7", flash_mode: 16, focal_length: 35, exposure_time: 0.0166667, }, colors: [ { red: 206, green: 203, blue: 167, alpha: 255 }, { red: 158, green: 163, blue: 93, alpha: 255 }, ], meta: { antivirus: { status: "clean", checked_at: "2020-04-21T07:57:11.124Z", threat_name: null, }, }, creator: { type: "account", id: "312" }, upload_collection: { type: "upload_collection", id: "uinr2zfqQLeCo_1O0-ao-Q", }, } ``` --- # Content Management API — Delete an upload Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload/destroy.md ## Returns Returns a resource object of type [upload](/docs/content-management-api/resources/upload.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const uploadId = "q0VNpiNQSkG6z0lif_O1zg"; const upload = await client.uploads.destroy(uploadId); // Check the 'Returned output' tab for the result ☝️ console.log(upload); } run(); ``` Returned output ```javascript { id: "q0VNpiNQSkG6z0lif_O1zg", size: 444, width: 30, height: 30, path: "/45/1496845848-digital-cats.jpg", basename: "digital-cats", filename: "digital-cats.jpg", url: "https://www.datocms-assets.com/45/1496845848-digital-cats.jpg", format: "jpg", author: "Mark Smith", copyright: "2020 DatoCMS", notes: "Nyan the cat", md5: "873c296d0f2b7ee569f2d7ddaebc0d33", duration: 62, frame_rate: 30, blurhash: "LEHV6nWB2yk8pyo0adR*.7kCMdnj", thumbhash: "UhqCDQIkrHOfVG8wBa2v39z7CXeqZWFLdg==", mux_playback_id: "a1B2c3D4e5F6g7H8i9", mux_mp4_highest_res: "high", default_field_metadata: { alt: { en: "this is the default alternate text" }, title: { en: "this is the default title" }, custom_data: { en: { foo: "bar" } }, focal_point: { x: 0.5, y: 0.5 }, poster_time: 12.5, }, is_image: true, created_at: "2020-04-21T07:57:11.124Z", updated_at: "2020-04-21T07:57:11.124Z", mime_type: "image/jpeg", tags: ["cats"], smart_tags: ["robot-cats"], exif_info: { iso: 10000, model: "ILCE-7", flash_mode: 16, focal_length: 35, exposure_time: 0.0166667, }, colors: [ { red: 206, green: 203, blue: 167, alpha: 255 }, { red: 158, green: 163, blue: 93, alpha: 255 }, ], meta: { antivirus: { status: "clean", checked_at: "2020-04-21T07:57:11.124Z", threat_name: null, }, }, creator: { type: "account", id: "312" }, upload_collection: { type: "upload_collection", id: "uinr2zfqQLeCo_1O0-ao-Q", }, } ``` --- # Content Management API — Update an upload Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload/update.md Depending on the attributes that you pass, you can use this endpoint to: - **Update regular attributes** like `author`, `notes`, `copyright`, `default_field_metadata`, etc.; - **Rename the asset** by passing a different `basename` attribute; - **Upload a new version of the asset** by passing a different `path` attribute; Just like `POST /uploads` endpoint, an asyncronous job ID might be returned instead of the regular response. See the [Create a new upload](/docs/content-management-api/resources/upload.md#create) section for more details. **We strongly recommend to use our JS or Ruby client to upload new assets**, as they provide helper methods that take care of all the details for you. ## Query parameters **`replace_strategy`** - Type: enum - Example: `"keep_url"` Strategy to use when replacing the asset file. If not specified, a new URL will be generated.
Show enum values **`create_new_url`** Generate a new URL for the asset (default behavior) **`keep_url`** Maintain the same URL by overwriting the file at the existing path
## Body parameters **`path`** - Optional - Type: string - Example: `"/45/1496845848-digital-cats.jpg"` Upload path **`basename`** - Optional - Type: string - Example: `"digital-cats"` Upload basename **`copyright`** - Optional - Type: string, null - Example: `"2020 DatoCMS"` Copyright **`author`** - Optional - Type: string, null - Example: `"Mark Smith"` Author **`notes`** - Optional - Type: string, null - Example: `"Nyan the cat"` Notes **`tags`** - Optional - Type: Array\ - Example: `["cats"]` Tags **`default_field_metadata`** - Optional - Type: object Patch the asset's default metadata. Send any subset of `alt`/`title`/`custom_data`/`focal_point`/`poster_time` — missing keys preserve their stored values. See the response shape for the full structure and per-key semantics.
Show object format **`alt`** - Optional - Type: object - Example: `{ en: "Alternate text" }` Alternate text per locale **`title`** - Optional - Type: object - Example: `{ en: "Title" }` Title per locale **`custom_data`** - Optional - Type: object - Example: `{ en: { add_watermark: true } }` Object with arbitrary metadata, per locale **`focal_point`** - Optional - Type: object, null Focal point (only for image assets)
Show object format **`x`** - Required - Type: number - Example: `0.5` Horizontal position expressed as float between 0 and 1 **`y`** - Required - Type: number - Example: `0.5` Vertical position expressed as float between 0 and 1
**`poster_time`** - Optional - Type: number, null - Example: `12.5` Poster time in seconds (only for video assets). Float seconds into the video used to generate the thumbnail; null uses Mux's default (middle of the video)
**`creator`** - Optional - Type: [ResourceLinkage\<"account"\>](https://www-draft.datocms.com/docs/content-management-api/resources/account.md), [ResourceLinkage\<"access_token"\>](https://www-draft.datocms.com/docs/content-management-api/resources/access_token.md), [ResourceLinkage\<"user"\>](https://www-draft.datocms.com/docs/content-management-api/resources/user.md), [ResourceLinkage\<"sso_user"\>](https://www-draft.datocms.com/docs/content-management-api/resources/sso_user.md), [ResourceLinkage\<"organization"\>](https://www-draft.datocms.com/docs/content-management-api/resources/organization.md) The entity (account/collaborator/access token) who created the asset **`upload_collection`** - Optional - Type: [ResourceLinkage\<"upload_collection"\>](https://www-draft.datocms.com/docs/content-management-api/resources/upload_collection.md), null Upload collection to which the asset belongs ## Returns Returns a resource object of type [upload](/docs/content-management-api/resources/upload.md) ## Other examples ###### Example Update asset attributes This example demonstrates how to update the metadata attributes of an existing asset without changing the underlying file. You can update fields like: - **`author`**: The creator or photographer of the asset - **`copyright`**: Copyright information for the asset - **`default_field_metadata`**: Default metadata for the asset. `alt`, `title`, and `custom_data` are keyed by locale, while `focal_point` (images) and `poster_time` (videos) are single, non-localized values The `default_field_metadata` object allows you to set defaults that will be used when the asset is referenced in records, unless overridden at the record level. Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const uploadId = "FWYwxZZ1SUG1ReKlzdDAEA"; const updatedUpload = await client.uploads.update(uploadId, { author: "New author!", copyright: "New copyright", default_field_metadata: { alt: { en: "new default alt" }, title: { en: "new default title" }, custom_data: { en: {} }, focal_point: { x: 0.3, y: 0.6, }, }, }); console.log({ id: updatedUpload.id, author: updatedUpload.author, copyright: updatedUpload.copyright, default_field_metadata: updatedUpload.default_field_metadata, }); } run(); ``` Returned output ```javascript { id: 'FWYwxZZ1SUG1ReKlzdDAEA', author: 'New author!', copyright: 'New copyright', default_field_metadata: { alt: { en: 'new default alt' }, title: { en: 'new default title' }, custom_data: { en: {} }, focal_point: { x: 0.3, y: 0.6 }, poster_time: null } } ``` ###### Example Replace the asset file This example demonstrates how to replace the file associated with an existing upload while keeping the same upload ID. When replacing an asset, you have two options: **Create new URL** (default): The new asset is available immediately with a fresh URL. The old URL will be purged from cache and will disappear after complete propagation. Use this when you need immediate availability of the new file. **Keep the original URL**: Existing links continue to work automatically, but changes take 5-10 minutes to appear everywhere due to CDN and browser cache propagation. Some users may temporarily see the old version. Use this when you have many existing references and want to avoid updating URLs. > [!WARNING] Important considerations for keep_url > The `keep_url` option is only available when the new file has the same format/extension as the original (e.g., replacing a `.jpg` with another `.jpg`/`.jpeg`). If the formats differ, you must use the default `create_new_url` strategy. > > Also note that since different upload entities across environments can share the same asset URL, using `keep_url` will automatically update all uploads that reference this asset path. This ensures consistency across environments but means the change affects more than just the current upload. The `uploadLocalFileAndReturnPath()` helper handles: - Requesting upload permissions from DatoCMS - Uploading the file to the storage bucket - Returning the path to use in the update call Code ```javascript import { buildClient, uploadLocalFileAndReturnPath, } from "@datocms/cma-client-node"; async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // Fetch the original uploads to show their URLs before replacement const original1 = await client.uploads.find("bDb8xUJIRaGteyJYldfKsA"); const original2 = await client.uploads.find("II2mHvSkQESUl-2401HZgg"); console.log("Before replacement:"); console.log(" Upload 1 URL:", original1.url); console.log(" Upload 2 URL:", original2.url); // Upload the new file and get the path const newFilePath = await uploadLocalFileAndReturnPath( client, "./new-image.jpg", ); // ============================================================ // Option 1: Create new URL (default) // ============================================================ // The new asset is available immediately with a fresh URL. // Use this when you need immediate availability. const uploadWithNewUrl = await client.uploads.update( "bDb8xUJIRaGteyJYldfKsA", { path: newFilePath }, ); // ============================================================ // Option 2: Keep the original URL // ============================================================ // Existing links work automatically, but changes take 5-10 minutes // to propagate. Use this when you have many existing references. const uploadKeepingUrl = await client.uploads.update( "II2mHvSkQESUl-2401HZgg", { path: newFilePath }, { replace_strategy: "keep_url" }, ); console.log("\nAfter replacement:"); console.log(" Option 1 (new URL):", uploadWithNewUrl.url); console.log(" Option 2 (keep URL):", uploadKeepingUrl.url); } run(); ``` Returned output ```javascript Before replacement: Upload 1 URL: https://www.datocms-assets.com/190734/1768292263-old-image.jpg Upload 2 URL: https://www.datocms-assets.com/190734/1768292270-old-image.jpg After replacement: Option 1 (new URL): https://www.datocms-assets.com/190734/1768292279-new-image.jpg Option 2 (keep URL): https://www.datocms-assets.com/190734/1768292270-old-image.jpg ``` ###### Example Rename the file This example demonstrates how to rename an uploaded file in the CDN by changing its `basename`. This is particularly useful for SEO purposes, as the filename becomes part of the asset's URL. Renaming allows you to use descriptive, keyword-rich filenames without needing to re-upload the file. The `basename` is the filename without the extension. For example, setting `basename` to `"premium-headphones"` for a `.jpg` file would result in a URL ending in `premium-headphones.jpg`. Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const uploadId = "ey4EL5V0QYCdODxbbUj2cQ"; // Rename the uploaded file in the CDN (for SEO purposes) const updatedUpload = await client.uploads.update(uploadId, { basename: "this-will-be-the-new-file-basename", }); console.log({ id: updatedUpload.id, basename: updatedUpload.basename, path: updatedUpload.path, url: updatedUpload.url, }); } run(); ``` Returned output ```javascript { id: 'ey4EL5V0QYCdODxbbUj2cQ', basename: 'this-will-be-the-new-file-basename', path: '/190729/1768291467-this-will-be-the-new-file-basename.jpeg', url: 'https://www.datocms-assets.com/190729/1768291467-this-will-be-the-new-file-basename.jpeg' } ``` --- # Content Management API — Referenced records Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload/references.md Retrieve all records that are linked to this upload ## Query parameters **`nested`** - Type: boolean For Modular Content, Structured Text and Single Block fields, return full payload for nested blocks instead of IDs **`version`** - Type: null, enum - Example: `"current"` Retrieve only the selected type of version that is linked to the upload; current, published or both
Show enum values **`current`** Return records that are linked to the upload in their latest version available **`published`** Return records that are linked to the upload in their published version **`published-or-current`** Return records that are linked to the upload either in their published version or in their latest version available
## Returns Returns an array of resource objects of type [item](/docs/content-management-api/resources/item.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const uploadId = "q0VNpiNQSkG6z0lif_O1zg"; const uploads = await client.uploads.references(uploadId); for (const upload of uploads) { // Check the 'Returned output' tab for the result ☝️ console.log(upload); } } run(); ``` Returned output ```javascript { id: "hWl-mnkWRYmMCSTq4z_piQ", title: "My first blog post!", content: "Lorem ipsum dolor sit amet...", category: "24", image: { alt: "Alt text", title: "Image title", custom_data: {}, focal_point: null, upload_id: "20042921", }, meta: { created_at: "2020-04-21T07:57:11.124Z", updated_at: "2020-04-21T07:57:11.124Z", published_at: "2020-04-21T07:57:11.124Z", first_published_at: "2020-04-21T07:57:11.124Z", publication_scheduled_at: "2020-04-21T07:57:11.124Z", unpublishing_scheduled_at: "2020-04-21T07:57:11.124Z", status: "published", is_current_version_valid: true, is_published_version_valid: true, current_version: "4234", stage: null, has_children: true, }, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, } ``` --- # Content Management API — Add tags to assets in bulk Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload/bulk_tag.md ## Body parameters **`tags`** - Required - Type: Array\ - Example: `["cats"]` The tags to add to the assets **`uploads`** - Required - Type: Array<[ResourceLinkage\<"upload"\>](https://www-draft.datocms.com/docs/content-management-api/resources/upload.md)> Assets to tag ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const upload = await client.uploads.bulkTag({ tags: ["cats"], uploads: [{ type: "upload", id: "q0VNpiNQSkG6z0lif_O1zg" }], }); // Check the 'Returned output' tab for the result ☝️ console.log(upload); } run(); ``` Returned output ```javascript [] ``` --- # Content Management API — Put assets into a collection in bulk Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload/bulk_set_upload_collection.md ## Body parameters **`uploads`** - Required - Type: Array<[ResourceLinkage\<"upload"\>](https://www-draft.datocms.com/docs/content-management-api/resources/upload.md)> Assets to assign to the collection **`upload_collection`** - Required - Type: null, [ResourceLinkage\<"upload_collection"\>](https://www-draft.datocms.com/docs/content-management-api/resources/upload_collection.md) Asset collection to put uploads into ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const upload = await client.uploads.bulkSetUploadCollection({ uploads: [{ type: "upload", id: "q0VNpiNQSkG6z0lif_O1zg" }], upload_collection: null, }); // Check the 'Returned output' tab for the result ☝️ console.log(upload); } run(); ``` Returned output ```javascript [] ``` --- # Content Management API — Destroy uploads Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload/bulk_destroy.md Delete assets in bulk ## Body parameters **`uploads`** - Required - Type: Array<[ResourceLinkage\<"upload"\>](https://www-draft.datocms.com/docs/content-management-api/resources/upload.md)> Assets to delete ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const upload = await client.uploads.bulkDestroy({ uploads: [{ type: "upload", id: "q0VNpiNQSkG6z0lif_O1zg" }], }); // Check the 'Returned output' tab for the result ☝️ console.log(upload); } run(); ``` Returned output ```javascript [] ``` --- # Content Management API — Site Source [docs]: https://www.datocms.com/docs/content-management-api/resources/site.md A site represents a specific DatoCMS administrative area ## Object payload **`id`** - Type: string - Example: `"155"` ID of site **`type`** - Type: string Must be exactly `"site"`. **`domain`** - Type: string, null - Example: `"admin.my-awesome-website.com"` Administrative area custom domain **`favicon`** - Type: string, null - Example: `"123"` The upload id for the favicon **`global_seo`** - Type: object, null Specifies default global settings
Show object format **`site_name`** - Type: string - Example: `"My Awesome Website"` Site name, used in social sharing **`fallback_seo`** - Type: object
Show object format **`title`** - Type: string - Example: `"Default meta title"` **`description`** - Type: string - Example: `"Default meta description"` **`image`** - Type: null, string - Example: `"123"` The id of the image **`twitter_card`** - Type: null, enum - Example: `"summary_large_image"` Determines how a Twitter link preview is shown
Show enum values **`summary`** Twitter summary card **`summary_large_image`** Twitter summary card with large image
**`title_suffix`** - Type: null, string - Example: `" - My Awesome Website"` Title meta tag suffix **`facebook_page_url`** - Type: null, string - Example: `"http://facebook.com/awesomewebsite"` URL of facebook page **`twitter_account`** - Type: null, string - Example: `"@awesomewebsite"` Twitter account associated to website
**`google_maps_api_token`** - Type: string, null - Example: `"xxxxxxxxxxxxx"` Google API Key to be used by the LatLon field editor. Only the DatoCMS interface uses it: it returns `null` for any other caller. **`imgix_host`** - Type: string, null - Example: `"www.datocms-assets.com"` Imgix host **`internal_domain`** - Type: string, null - Example: `"my-website.admin.datocms.com"` DatoCMS internal domain for the administrative area. Returns `null` if the credentials you are using cannot read the configuration of the project. **`last_data_change_at`** - Type: null, date-time - Example: `"2017-03-30T09:29:14.872Z"` Specifies the last time when a change of data occurred **`locales`** - Type: Array\ - Example: `["en"]` Available locales **`name`** - Type: string - Example: `"My Awesome Website"` Site name **`no_index`** - Type: boolean Whether the website needs to be indexed by search engines or not **`require_2fa`** - Type: boolean, null Specifies whether all users of this site need to authenticate using two-factor authentication. Returns `null` if the credentials you are using cannot read the configuration of the project. **`theme`** - Type: object Specifies the theme to use in administrative area. For monochromatic themes the response only includes type, hue, and logo — frontends must derive the palette from the hue. For custom themes the primary_color, light_color, accent_color, and dark_color fields are returned.
Show object format **`type`** - Type: enum - Example: `"monochromatic"` If type is monochromatic, the hue will determine the color palette. Dark color is a legacy property, and it won't be used on the interface
Show enum values **`custom`** Use custom color palette (deprecated) **`monochromatic`** Use monochromatic, accessible color palette
**`hue`** - Type: integer, null - Example: `16` If the type is monochromatic, the value will fall between 0 and 359. If it's not, the value will be null. **`logo`** - Type: string, null - Example: `"123"` The upload ID that is used as the logo for the project **`color_channel`** - Type: integer - Example: `128` An integer color channel value (0-255)
Show deprecated **`color`** - Deprecated - Type: object An RGBA color value Custom color palettes are deprecated.
Show object format **`red`** - Type: integer - Example: `128` An integer color channel value (0-255) **`green`** - Type: integer - Example: `128` An integer color channel value (0-255) **`blue`** - Type: integer - Example: `128` An integer color channel value (0-255) **`alpha`** - Type: integer - Example: `128` An integer color channel value (0-255)
**`primary_color`** - Deprecated - Type: object An RGBA color value Custom color palettes are deprecated.
Show object format **`red`** - Type: integer - Example: `128` An integer color channel value (0-255) **`green`** - Type: integer - Example: `128` An integer color channel value (0-255) **`blue`** - Type: integer - Example: `128` An integer color channel value (0-255) **`alpha`** - Type: integer - Example: `128` An integer color channel value (0-255)
**`light_color`** - Deprecated - Type: object An RGBA color value Custom color palettes are deprecated.
Show object format **`red`** - Type: integer - Example: `128` An integer color channel value (0-255) **`green`** - Type: integer - Example: `128` An integer color channel value (0-255) **`blue`** - Type: integer - Example: `128` An integer color channel value (0-255) **`alpha`** - Type: integer - Example: `128` An integer color channel value (0-255)
**`accent_color`** - Deprecated - Type: object An RGBA color value Custom color palettes are deprecated.
Show object format **`red`** - Type: integer - Example: `128` An integer color channel value (0-255) **`green`** - Type: integer - Example: `128` An integer color channel value (0-255) **`blue`** - Type: integer - Example: `128` An integer color channel value (0-255) **`alpha`** - Type: integer - Example: `128` An integer color channel value (0-255)
**`dark_color`** - Deprecated - Type: object An RGBA color value Custom color palettes are deprecated.
Show object format **`red`** - Type: integer - Example: `128` An integer color channel value (0-255) **`green`** - Type: integer - Example: `128` An integer color channel value (0-255) **`blue`** - Type: integer - Example: `128` An integer color channel value (0-255) **`alpha`** - Type: integer - Example: `128` An integer color channel value (0-255)
**`timezone`** - Type: string - Example: `"Europe/London"` Site default timezone **`ip_tracking_enabled`** - Type: boolean, null Specifies whether you want IPs to be tracked in the Project usages section. Returns `null` if the credentials you are using cannot read the configuration of the project. **`force_use_of_sandbox_environments`** - Type: boolean If enabled, blocks schema changes of primary environment **`assets_cdn_default_settings`** - Type: object Allows setting default parameters for assets served through the CDN
Show object format **`image`** - Type: object Allows setting default parameters for optimizing images served by the CDN
Show object format **`q`** - Type: integer - Example: `50` Controls the output quality of lossy file formats (jpg, pjpg, webp, avif, or jxr). Valid values are in the range 0 – 100 and the default is 75. **`auto`** - Type: Array\ - Example: `["compress", "format"]` The auto parameter helps automating a baseline level of optimization. Specify one or more settings **`cs`** - Type: enum - Example: `"srgb"` Specifies the color space of the output image
Show enum values **`srgb`** Uses the sRGB colorspace which is an internet standard. This is the default **`adobergb1998`** Refers to the Adobe RGB (1998) color space, which provides accurate color reproduction from screen to print **`tinysrgb`** Reduces the color space metadata but may cause a slight shift in color values **`strip`** Removes the colorspace for maximum size reduction. Note that colors will still be rendered, but a colorspace will not be specified **`origin`** Keeps the color space of the origin image. This is the default value unless auto=compress
**`video`** - Type: object Allows setting default parameters for optimizing videos served by the CDN
Show object format **`disable_serving_raw_videos`** - Type: boolean When true, attempting to retrieve raw video files directly instead of their optimized counterparts will result in a HTTP 422 status code
**`meta.created_at`** - Type: date-time Date of project creation **`meta.improved_timezone_management`** - Type: boolean Whether the [Improved API Timezone Management](https://www.datocms.com/product-updates/improved-timezone-management) opt-in product update is active or not **`meta.improved_hex_management`** - Type: boolean Whether the [Improved API Hex Management](https://www.datocms.com/product-updates/improved-hex-management) opt-in product update is active or not **`meta.improved_gql_multilocale_fields`** - Type: boolean Whether the [Improved GraphQL multi-locale fields](https://www.datocms.com/product-updates/improved-gql-multilocale-fields) opt-in product update is active or not **`meta.improved_gql_visibility_control`** - Type: boolean Whether the [Improved GraphQL visibility control](https://www.datocms.com/product-updates/improved-gql-visibility-control) opt-in product update is active or not **`meta.improved_boolean_fields`** - Type: boolean Whether the [Improved boolean fields](https://www.datocms.com/product-updates/improved-boolean-fields) opt-in product update is active or not **`meta.draft_mode_default`** - Type: boolean The default value for the draft mode option in all the environment's models **`meta.improved_validation_at_publishing`** - Type: boolean Whether the [Improved validation at publishing](https://www.datocms.com/product-updates/force-validations-on-records-when-publishing) opt-in product update is active or not **`meta.improved_exposure_of_inline_blocks_in_cda`** - Type: boolean Whether the [Improved exposure of inline blocks in the Content Delivery API](https://www.datocms.com/product-updates/improved-exposure-of-inline-blocks-in-cda) opt-in product update is active or not **`meta.improved_items_listing`** - Type: boolean Whether the [Improved items listing](https://www.datocms.com/product-updates/improved-items-listing) opt-in product update is active or not **`meta.milliseconds_in_datetime`** - Type: boolean Whether the [Milliseconds in datetime](https://www.datocms.com/product-updates/milliseconds-in-datetime) opt-in product update is active or not **`meta.non_localized_focal_points`** - Type: boolean Whether the [Non-localized focal points](https://www.datocms.com/product-updates/non-localized-focal-points) opt-in product update is active or not **`meta.allow_custom_theme`** - Type: boolean Whether the project can still use a custom color palette for the theme. Custom palettes are deprecated. **`meta.custom_upload_storage_settings`** - Type: boolean Whether the site has custom upload storage settings **`item_types`** - Type: Array<[ResourceLinkage\<"item_type"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item_type.md)> **`owner`** - Type: [ResourceLinkage\<"account"\>](https://www-draft.datocms.com/docs/content-management-api/resources/account.md), [ResourceLinkage\<"organization"\>](https://www-draft.datocms.com/docs/content-management-api/resources/organization.md)
Show deprecated **`account`** - Deprecated - Type: null, [ResourceLinkage\<"account"\>](https://www-draft.datocms.com/docs/content-management-api/resources/account.md) Please user the owner relationship instead
--- # Content Management API — Retrieve the site Source [docs]: https://www.datocms.com/docs/content-management-api/resources/site/self.md ## Query parameters **`include`** - Type: string - Example: `"item_types,item_types.fields"` Comma-separated list of [relationship paths](https://jsonapi.org/format/#fetching-includes). A relationship path is a dot-separated list of relationship names. Allowed relationship paths: `item_types`, `item_types.fields`, `item_types.fieldsets`, `item_types.singleton_item`, `account`, `owner`. **`fields`** - Type: object Sparse fieldsets: for each entity type, the attributes and the relationships to return, separated by commas. Each entity declares its attributes and its relationships in its own schema.
Show object format **`site`** - Type: string - Example: `"name,domain,google_maps_api_token,owner"` Attributes and relationships to return for each `site` that this endpoint returns. **`item_type`** - Type: string - Example: `"name,api_key,collection_appearance,singleton_item"` Attributes and relationships to return for each `item_type` that this endpoint returns. **`field`** - Type: string - Example: `"label,field_type,localized,item_type"` Attributes and relationships to return for each `field` that this endpoint returns. **`fieldset`** - Type: string - Example: `"title,hint,collapsible,item_type"` Attributes and relationships to return for each `fieldset` that this endpoint returns. **`item`** - Type: string - Example: `"title,content,category,item_type"` Attributes and relationships to return for each `item` that this endpoint returns. **`account`** - Type: string - Example: `"email,first_name,last_name"` Attributes and relationships to return for each `account` that this endpoint returns. **`organization`** - Type: string - Example: `"name"` Attributes and relationships to return for each `organization` that this endpoint returns.
## Returns Returns a resource object of type [site](/docs/content-management-api/resources/site.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const site = await client.site.find(); // Check the 'Returned output' tab for the result ☝️ console.log(site); } run(); ``` Returned output ```javascript { id: "155", domain: "admin.my-awesome-website.com", favicon: "123", global_seo: {}, google_maps_api_token: "xxxxxxxxxxxxx", imgix_host: "www.datocms-assets.com", internal_domain: "my-website.admin.datocms.com", last_data_change_at: "2017-03-30T09:29:14.872Z", locales: ["en"], name: "My Awesome Website", no_index: true, require_2fa: false, theme: { type: "monochromatic", hue: 16, logo: "123" }, timezone: "Europe/London", ip_tracking_enabled: true, force_use_of_sandbox_environments: true, assets_cdn_default_settings: { image: {}, video: {} }, meta: { created_at: "2020-04-21T07:57:11.124Z", improved_timezone_management: true, improved_hex_management: true, improved_gql_multilocale_fields: true, improved_gql_visibility_control: true, improved_boolean_fields: true, draft_mode_default: true, improved_validation_at_publishing: true, improved_exposure_of_inline_blocks_in_cda: true, improved_items_listing: true, milliseconds_in_datetime: true, non_localized_focal_points: true, allow_custom_theme: true, }, item_types: [{ type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }], owner: { type: "account", id: "312" }, } ``` --- # Content Management API — Update the site's settings Source [docs]: https://www.datocms.com/docs/content-management-api/resources/site/update.md ## Body parameters **`no_index`** - Optional - Type: boolean Whether the website needs to be indexed by search engines or not **`favicon`** - Optional - Type: string, null - Example: `"123"` The upload id for the favicon **`global_seo`** - Optional - Type: object, null Specifies default global settings
Show object format **`site_name`** - Optional - Type: string - Example: `"My Awesome Website"` Site name, used in social sharing **`fallback_seo`** - Optional - Type: object
Show object format **`title`** - Required - Type: string - Example: `"Default meta title"` **`description`** - Required - Type: string - Example: `"Default meta description"` **`image`** - Required - Type: null, string - Example: `"123"` The id of the image **`twitter_card`** - Optional - Type: null, enum - Example: `"summary_large_image"` Determines how a Twitter link preview is shown
Show enum values **`summary`** - Optional Twitter summary card **`summary_large_image`** - Optional Twitter summary card with large image
**`title_suffix`** - Optional - Type: null, string - Example: `" - My Awesome Website"` Title meta tag suffix **`facebook_page_url`** - Optional - Type: null, string - Example: `"http://facebook.com/awesomewebsite"` URL of facebook page **`twitter_account`** - Optional - Type: null, string - Example: `"@awesomewebsite"` Twitter account associated to website
**`name`** - Optional - Type: string - Example: `"My Awesome Website"` Site name **`theme`** - Optional - Type: object **`locales`** - Optional - Type: Array\ - Example: `["en"]` Available locales **`timezone`** - Optional - Type: string - Example: `"Europe/London"` Site default timezone **`require_2fa`** - Optional - Type: boolean Specifies whether all users of this site need to authenticate using two-factor authentication. **`ip_tracking_enabled`** - Optional - Type: boolean Specifies whether you want IPs to be tracked in the Project usages section. **`force_use_of_sandbox_environments`** - Optional - Type: boolean If enabled, blocks schema changes of primary environment **`meta.improved_timezone_management`** - Optional - Type: boolean Whether the [Improved API Timezone Management](https://www.datocms.com/product-updates/improved-timezone-management) opt-in product update is active or not **`meta.improved_hex_management`** - Optional - Type: boolean Whether the [Improved API Hex Management](https://www.datocms.com/product-updates/improved-hex-management) opt-in product update is active or not **`meta.improved_gql_multilocale_fields`** - Optional - Type: boolean Whether the [Improved GraphQL multi-locale fields](https://www.datocms.com/product-updates/improved-gql-multilocale-fields) opt-in product update is active or not **`meta.improved_gql_visibility_control`** - Optional - Type: boolean Whether the [Improved GraphQL visibility control](https://www.datocms.com/product-updates/improved-gql-visibility-control) opt-in product update is active or not **`meta.improved_boolean_fields`** - Optional - Type: boolean Whether the [Improved boolean fields](https://www.datocms.com/product-updates/improved-boolean-fields) opt-in product update is active or not **`meta.draft_mode_default`** - Optional - Type: boolean The default value for the draft mode option in all the environment's models **`meta.improved_validation_at_publishing`** - Optional - Type: boolean Whether the [Improved validation at publishing](https://www.datocms.com/product-updates/force-validations-on-records-when-publishing) opt-in product update is active or not **`meta.custom_upload_storage_settings`** - Optional - Type: boolean Whether the site has custom upload storage settings **`meta.improved_exposure_of_inline_blocks_in_cda`** - Optional - Type: boolean Whether the [Improved exposure of inline blocks in the Content Delivery API](https://www.datocms.com/product-updates/improved-exposure-of-inline-blocks-in-cda) opt-in product update is active or not **`meta.improved_items_listing`** - Optional - Type: boolean Whether the [Improved items listing](https://www.datocms.com/product-updates/improved-items-listing) opt-in product update is active or not **`meta.milliseconds_in_datetime`** - Optional - Type: boolean Whether the [Milliseconds in datetime](https://www.datocms.com/product-updates/milliseconds-in-datetime) opt-in product update is active or not **`meta.non_localized_focal_points`** - Optional - Type: boolean Whether the [Non-localized focal points](https://www.datocms.com/product-updates/non-localized-focal-points) opt-in product update is active or not ## Returns Returns a resource object of type [site](/docs/content-management-api/resources/site.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const site = await client.site.update({}); // Check the 'Returned output' tab for the result ☝️ console.log(site); } run(); ``` Returned output ```javascript { id: "155", domain: "admin.my-awesome-website.com", favicon: "123", global_seo: {}, google_maps_api_token: "xxxxxxxxxxxxx", imgix_host: "www.datocms-assets.com", internal_domain: "my-website.admin.datocms.com", last_data_change_at: "2017-03-30T09:29:14.872Z", locales: ["en"], name: "My Awesome Website", no_index: true, require_2fa: false, theme: { type: "monochromatic", hue: 16, logo: "123" }, timezone: "Europe/London", ip_tracking_enabled: true, force_use_of_sandbox_environments: true, assets_cdn_default_settings: { image: {}, video: {} }, meta: { created_at: "2020-04-21T07:57:11.124Z", improved_timezone_management: true, improved_hex_management: true, improved_gql_multilocale_fields: true, improved_gql_visibility_control: true, improved_boolean_fields: true, draft_mode_default: true, improved_validation_at_publishing: true, improved_exposure_of_inline_blocks_in_cda: true, improved_items_listing: true, milliseconds_in_datetime: true, non_localized_focal_points: true, allow_custom_theme: true, }, item_types: [{ type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }], owner: { type: "account", id: "312" }, } ``` --- # Content Management API — Model/Block model Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item-type.md The way you define the kind of content you can edit inside a DatoCMS project passes through the concept of **models** and **block models**. For backward-compatibility reasons, the API refers to both as "item types". ## Models Models are much like database tables — they define the structure of your main content types (e.g., blog posts, products, landing pages). Each model is composed of fields with custom validations. Records created from models exist independently and can be referenced by other records through link fields. ## Block Models Block models define complex and repeatable structures that can be embedded inside records. They are the foundation behind features like [Modular Content](/docs/content-modelling/modular-content.md) and [Structured Text](/docs/content-modelling/structured-text.md). ### Key differences: - **Models** create standalone records that can be referenced and have independent value - **Block models** create blocks that only exist within parent records and cannot be referenced via link fields - Block models defined in the library can be reused across different models - When a record gets deleted, all the blocks it contains are deleted with it - Blocks do not count towards your plan's records limit You can distinguish between models and block models using the `modular_block` attribute: `true` indicates a block model, `false` indicates a regular model. ## Object payload **`id`** - Type: string - Example: `"DxMaW10UQiCmZcuuA-IkkA"` RFC 4122 UUID of item type expressed in URL-safe base64 format **`type`** - Type: string Must be exactly `"item_type"`. **`name`** - Type: string - Example: `"Blog post"` Name of the model/block model **`api_key`** - Type: string - Example: `"post"` API key of the model/block model **`singleton`** - Type: boolean Whether the model is single-instance or not. This property only applies to models, not block models **`sortable`** - Type: boolean Whether editors can sort records via drag & drop or not. Must be false for block models **`modular_block`** - Type: boolean Whether this is a block model or not. Block models define structures that can be embedded inside records, while regular models create standalone records **`tree`** - Type: boolean Whether editors can organize records in a tree or not. Must be false for block models **`ordering_direction`** - Type: enum, null If an ordering field is set, this field specifies the sorting direction. This property does not apply to block models
Show enum values **`asc`** Ascending order **`desc`** Descending order
**`ordering_meta`** - Type: enum, null - Example: `"created_at"` Specifies the model's sorting method. Cannot be set in concurrency with ordering_field. This property does not apply to block models
Show enum values **`created_at`** Order by date of creation **`updated_at`** Order by date of last update **`first_published_at`** Order by date of first publication **`published_at`** Order by date of last publication
**`draft_mode_active`** - Type: boolean Whether draft/published mode is active or not. Must be false for block models **`all_locales_required`** - Type: boolean Whether we require all the project locales to be present for each localized field or not **`collection_appearance`** - Type: enum - Example: `"compact"` The way the model/block model collection should be presented to the editors
Show enum values **`compact`** Compact view **`table`** Tabular view
**`hint`** - Type: string, null - Example: `"Blog posts will be shown in our website under the Blog section"` A hint shown to editors to help them understand the purpose of this model/block model **`inverse_relationships_enabled`** - Type: boolean Whether inverse relationships fields are expressed in GraphQL or not. Must be false for block models **`draft_saving_active`** - Type: boolean Whether draft records can be saved without satisfying the validations or not. Must be false for block models **`meta.has_singleton_item`** - Type: boolean If this model is single-instance, this tells whether the single-instance record has already been created or not. This property only applies to models, not block models **`singleton_item`** - Type: [ResourceLinkage\<"item"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item.md), null The record instance related to this model. This relationship only applies to single-instance models, not block models **`fields`** - Type: Array<[ResourceLinkage\<"field"\>](https://www-draft.datocms.com/docs/content-management-api/resources/field.md)> The list of fields for this model/block model **`fieldsets`** - Type: Array<[ResourceLinkage\<"fieldset"\>](https://www-draft.datocms.com/docs/content-management-api/resources/fieldset.md)> The list of fieldsets for this model/block model **`presentation_title_field`** - Type: [ResourceLinkage\<"field"\>](https://www-draft.datocms.com/docs/content-management-api/resources/field.md), null The field to use as presentation title **`presentation_image_field`** - Type: [ResourceLinkage\<"field"\>](https://www-draft.datocms.com/docs/content-management-api/resources/field.md), null The field to use as presentation image **`title_field`** - Type: [ResourceLinkage\<"field"\>](https://www-draft.datocms.com/docs/content-management-api/resources/field.md), null The field to use as fallback title for SEO purposes. This relationship does not apply to block models **`image_preview_field`** - Type: [ResourceLinkage\<"field"\>](https://www-draft.datocms.com/docs/content-management-api/resources/field.md), null The field to use as fallback image for SEO purposes. This relationship does not apply to block models **`excerpt_field`** - Type: [ResourceLinkage\<"field"\>](https://www-draft.datocms.com/docs/content-management-api/resources/field.md), null The field to use as fallback description for SEO purposes. This relationship does not apply to block models **`ordering_field`** - Type: [ResourceLinkage\<"field"\>](https://www-draft.datocms.com/docs/content-management-api/resources/field.md), null The field upon which the collection is sorted. This relationship does not apply to block models **`workflow`** - Type: [ResourceLinkage\<"workflow"\>](https://www-draft.datocms.com/docs/content-management-api/resources/workflow.md), null The workflow to enforce on records
Show deprecated **`collection_appeareance`** - Deprecated - Type: enum - Example: `"compact"` The way the model collection should be presented to the editors This field contains a typo and will be removed in future versions: use `collection_appearance` instead
Show enum values **`compact`** Compact view **`table`** Tabular view
**`has_singleton_item`** - Deprecated - Type: boolean If this model is single-instance, this tells whether the single-instance record has already been created or not. This property only applies to models, not block models This field will be removed in future versions: instead, use the equivalent `has_singleton_item` field in the meta collection
--- # Content Management API — Create a new model/block model Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item-type/create.md ## Query parameters **`skip_menu_item_creation`** - Type: boolean Skip the creation of a menu item linked to the model **`menu_item_id`** - Type: string - Example: `"FF-P5of6Qp-DD2w0xoaa6Q"` Explicitely specify the ID of the menu item that will be linked to the model **`schema_menu_item_id`** - Type: string - Example: `"FF-P5of6Qp-DD2w0xoaa6Q"` Explicitely specify the ID of the schema menu item that will be linked to the model ## Body parameters **`id`** - Optional - Type: string - Example: `"DxMaW10UQiCmZcuuA-IkkA"` RFC 4122 UUID of item type expressed in URL-safe base64 format **`name`** - Required - Type: string - Example: `"Blog post"` Name of the model/block model **`api_key`** - Required - Type: string - Example: `"post"` API key of the model/block model **`singleton`** - Optional - Type: boolean Whether the model is single-instance or not. This property only applies to models, not block models **`all_locales_required`** - Optional - Type: boolean Whether we require all the project locales to be present for each localized field or not **`sortable`** - Optional - Type: boolean Whether editors can sort records via drag & drop or not. Must be false for block models **`modular_block`** - Optional - Type: boolean Whether this is a block model or not. Block models define structures that can be embedded inside records, while regular models create standalone records **`draft_mode_active`** - Optional - Type: boolean Whether draft/published mode is active or not. Must be false for block models **`draft_saving_active`** - Optional - Type: boolean Whether draft records can be saved without satisfying the validations or not. Must be false for block models **`tree`** - Optional - Type: boolean Whether editors can organize records in a tree or not. Must be false for block models **`ordering_direction`** - Optional - Type: enum, null If an ordering field is set, this field specifies the sorting direction. This property does not apply to block models
Show enum values **`asc`** - Optional Ascending order **`desc`** - Optional Descending order
**`ordering_meta`** - Optional - Type: enum, null - Example: `"created_at"` Specifies the model's sorting method. Cannot be set in concurrency with ordering_field. This property does not apply to block models
Show enum values **`created_at`** - Optional Order by date of creation **`updated_at`** - Optional Order by date of last update **`first_published_at`** - Optional Order by date of first publication **`published_at`** - Optional Order by date of last publication
**`collection_appearance`** - Optional - Type: enum - Example: `"compact"` The way the model/block model collection should be presented to the editors
Show enum values **`compact`** - Optional Compact view **`table`** - Optional Tabular view
**`hint`** - Optional - Type: string, null - Example: `"Blog posts will be shown in our website under the Blog section"` A hint shown to editors to help them understand the purpose of this model/block model **`inverse_relationships_enabled`** - Optional - Type: boolean Whether inverse relationships fields are expressed in GraphQL or not. Must be false for block models **`ordering_field`** - Optional - Type: [ResourceLinkage\<"field"\>](https://www-draft.datocms.com/docs/content-management-api/resources/field.md), null The field upon which the collection is sorted. This relationship does not apply to block models **`presentation_title_field`** - Optional - Type: [ResourceLinkage\<"field"\>](https://www-draft.datocms.com/docs/content-management-api/resources/field.md), null The field to use as presentation title **`presentation_image_field`** - Optional - Type: [ResourceLinkage\<"field"\>](https://www-draft.datocms.com/docs/content-management-api/resources/field.md), null The field to use as presentation image **`title_field`** - Optional - Type: [ResourceLinkage\<"field"\>](https://www-draft.datocms.com/docs/content-management-api/resources/field.md), null The field to use as fallback title for SEO purposes. This relationship does not apply to block models **`image_preview_field`** - Optional - Type: [ResourceLinkage\<"field"\>](https://www-draft.datocms.com/docs/content-management-api/resources/field.md), null The field to use as fallback image for SEO purposes. This relationship does not apply to block models **`excerpt_field`** - Optional - Type: [ResourceLinkage\<"field"\>](https://www-draft.datocms.com/docs/content-management-api/resources/field.md), null The field to use as fallback description for SEO purposes. This relationship does not apply to block models **`workflow`** - Optional - Type: [ResourceLinkage\<"workflow"\>](https://www-draft.datocms.com/docs/content-management-api/resources/workflow.md), null The workflow to enforce on records
Show deprecated **`collection_appeareance`** - Deprecated - Type: enum - Example: `"compact"` The way the model collection should be presented to the editors This field contains a typo and will be removed in future versions: use `collection_appearance` instead
Show enum values **`compact`** - Optional Compact view **`table`** - Optional Tabular view
## Returns Returns a resource object of type [item\_type](/docs/content-management-api/resources/item-type.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemType = await client.itemTypes.create({ name: "Blog post", api_key: "post", }); // Check the 'Returned output' tab for the result ☝️ console.log(itemType); } run(); ``` Returned output ```javascript { id: "DxMaW10UQiCmZcuuA-IkkA", name: "Blog post", api_key: "post", singleton: false, sortable: true, modular_block: false, tree: false, ordering_direction: null, ordering_meta: "created_at", draft_mode_active: false, all_locales_required: false, collection_appearance: "compact", hint: "Blog posts will be shown in our website under the Blog section", inverse_relationships_enabled: false, draft_saving_active: false, meta: { has_singleton_item: false }, singleton_item: null, fields: [{ type: "field", id: "Pkg-oztERp6o-Rj76nYKJg" }], fieldsets: [{ type: "fieldset", id: "93Y1C2sySkG4Eg0atBRIwg" }], presentation_title_field: null, presentation_image_field: null, title_field: null, image_preview_field: null, excerpt_field: null, ordering_field: null, workflow: null, } ``` --- # Content Management API — Update a model/block model Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item-type/update.md ## Body parameters **`name`** - Optional - Type: string - Example: `"Blog post"` Name of the model/block model **`api_key`** - Optional - Type: string - Example: `"post"` API key of the model/block model **`collection_appearance`** - Optional - Type: enum - Example: `"compact"` The way the model/block model collection should be presented to the editors
Show enum values **`compact`** - Optional Compact view **`table`** - Optional Tabular view
**`singleton`** - Optional - Type: boolean Whether the model is single-instance or not. This property only applies to models, not block models **`all_locales_required`** - Optional - Type: boolean Whether we require all the project locales to be present for each localized field or not **`sortable`** - Optional - Type: boolean Whether editors can sort records via drag & drop or not. Must be false for block models **`modular_block`** - Optional - Type: boolean Whether this is a block model or not. Block models define structures that can be embedded inside records, while regular models create standalone records **`draft_mode_active`** - Optional - Type: boolean Whether draft/published mode is active or not. Must be false for block models **`draft_saving_active`** - Optional - Type: boolean Whether draft records can be saved without satisfying the validations or not. Must be false for block models **`tree`** - Optional - Type: boolean Whether editors can organize records in a tree or not. Must be false for block models **`ordering_direction`** - Optional - Type: enum, null If an ordering field is set, this field specifies the sorting direction. This property does not apply to block models
Show enum values **`asc`** - Optional Ascending order **`desc`** - Optional Descending order
**`ordering_meta`** - Optional - Type: enum, null - Example: `"created_at"` Specifies the model's sorting method. Cannot be set in concurrency with ordering_field. This property does not apply to block models
Show enum values **`created_at`** - Optional Order by date of creation **`updated_at`** - Optional Order by date of last update **`first_published_at`** - Optional Order by date of first publication **`published_at`** - Optional Order by date of last publication
**`hint`** - Optional - Type: string, null - Example: `"Blog posts will be shown in our website under the Blog section"` A hint shown to editors to help them understand the purpose of this model/block model **`inverse_relationships_enabled`** - Optional - Type: boolean Whether inverse relationships fields are expressed in GraphQL or not. Must be false for block models **`meta.has_singleton_item`** - Optional - Type: boolean If this model is single-instance, this tells whether the single-instance record has already been created or not. This property only applies to models, not block models **`ordering_field`** - Optional - Type: [ResourceLinkage\<"field"\>](https://www-draft.datocms.com/docs/content-management-api/resources/field.md), null The field upon which the collection is sorted. This relationship does not apply to block models **`presentation_title_field`** - Optional - Type: [ResourceLinkage\<"field"\>](https://www-draft.datocms.com/docs/content-management-api/resources/field.md), null The field to use as presentation title **`presentation_image_field`** - Optional - Type: [ResourceLinkage\<"field"\>](https://www-draft.datocms.com/docs/content-management-api/resources/field.md), null The field to use as presentation image **`title_field`** - Optional - Type: [ResourceLinkage\<"field"\>](https://www-draft.datocms.com/docs/content-management-api/resources/field.md), null The field to use as fallback title for SEO purposes. This relationship does not apply to block models **`image_preview_field`** - Optional - Type: [ResourceLinkage\<"field"\>](https://www-draft.datocms.com/docs/content-management-api/resources/field.md), null The field to use as fallback image for SEO purposes. This relationship does not apply to block models **`excerpt_field`** - Optional - Type: [ResourceLinkage\<"field"\>](https://www-draft.datocms.com/docs/content-management-api/resources/field.md), null The field to use as fallback description for SEO purposes. This relationship does not apply to block models **`workflow`** - Optional - Type: [ResourceLinkage\<"workflow"\>](https://www-draft.datocms.com/docs/content-management-api/resources/workflow.md), null The workflow to enforce on records
Show deprecated **`collection_appeareance`** - Deprecated - Type: enum - Example: `"compact"` The way the model collection should be presented to the editors This field contains a typo and will be removed in future versions: use `collection_appearance` instead
Show enum values **`compact`** - Optional Compact view **`table`** - Optional Tabular view
## Returns Returns a resource object of type [item\_type](/docs/content-management-api/resources/item-type.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const modelIdOrApiKey = "blog_post"; const itemType = await client.itemTypes.update(modelIdOrApiKey, { id: "DxMaW10UQiCmZcuuA-IkkA", }); // Check the 'Returned output' tab for the result ☝️ console.log(itemType); } run(); ``` Returned output ```javascript { id: "DxMaW10UQiCmZcuuA-IkkA", name: "Blog post", api_key: "post", singleton: false, sortable: true, modular_block: false, tree: false, ordering_direction: null, ordering_meta: "created_at", draft_mode_active: false, all_locales_required: false, collection_appearance: "compact", hint: "Blog posts will be shown in our website under the Blog section", inverse_relationships_enabled: false, draft_saving_active: false, meta: { has_singleton_item: false }, singleton_item: null, fields: [{ type: "field", id: "Pkg-oztERp6o-Rj76nYKJg" }], fieldsets: [{ type: "fieldset", id: "93Y1C2sySkG4Eg0atBRIwg" }], presentation_title_field: null, presentation_image_field: null, title_field: null, image_preview_field: null, excerpt_field: null, ordering_field: null, workflow: null, } ``` --- # Content Management API — List all models/block models Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item-type/instances.md ## Query parameters **`fields`** - Type: object Sparse fieldsets: for each entity type, the attributes and the relationships to return, separated by commas. Each entity declares its attributes and its relationships in its own schema.
Show object format **`item_type`** - Type: string - Example: `"name,api_key,collection_appearance,singleton_item"` Attributes and relationships to return for each `item_type` that this endpoint returns.
## Returns Returns an array of resource objects of type [item\_type](/docs/content-management-api/resources/item-type.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemTypes = await client.itemTypes.list(); for (const itemType of itemTypes) { // Check the 'Returned output' tab for the result ☝️ console.log(itemType); } } run(); ``` Returned output ```javascript { id: "DxMaW10UQiCmZcuuA-IkkA", name: "Blog post", api_key: "post", singleton: false, sortable: true, modular_block: false, tree: false, ordering_direction: null, ordering_meta: "created_at", draft_mode_active: false, all_locales_required: false, collection_appearance: "compact", hint: "Blog posts will be shown in our website under the Blog section", inverse_relationships_enabled: false, draft_saving_active: false, meta: { has_singleton_item: false }, singleton_item: null, fields: [{ type: "field", id: "Pkg-oztERp6o-Rj76nYKJg" }], fieldsets: [{ type: "fieldset", id: "93Y1C2sySkG4Eg0atBRIwg" }], presentation_title_field: null, presentation_image_field: null, title_field: null, image_preview_field: null, excerpt_field: null, ordering_field: null, workflow: null, } ``` --- # Content Management API — Retrieve a model/block model Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item-type/self.md ## Query parameters **`fields`** - Type: object Sparse fieldsets: for each entity type, the attributes and the relationships to return, separated by commas. Each entity declares its attributes and its relationships in its own schema.
Show object format **`item_type`** - Type: string - Example: `"name,api_key,collection_appearance,singleton_item"` Attributes and relationships to return for each `item_type` that this endpoint returns. **`field`** - Type: string - Example: `"label,field_type,localized,item_type"` Attributes and relationships to return for each `field` that this endpoint returns.
## Returns Returns a resource object of type [item\_type](/docs/content-management-api/resources/item-type.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const modelIdOrApiKey = "blog_post"; const itemType = await client.itemTypes.find(modelIdOrApiKey); // Check the 'Returned output' tab for the result ☝️ console.log(itemType); } run(); ``` Returned output ```javascript { id: "DxMaW10UQiCmZcuuA-IkkA", name: "Blog post", api_key: "post", singleton: false, sortable: true, modular_block: false, tree: false, ordering_direction: null, ordering_meta: "created_at", draft_mode_active: false, all_locales_required: false, collection_appearance: "compact", hint: "Blog posts will be shown in our website under the Blog section", inverse_relationships_enabled: false, draft_saving_active: false, meta: { has_singleton_item: false }, singleton_item: null, fields: [{ type: "field", id: "Pkg-oztERp6o-Rj76nYKJg" }], fieldsets: [{ type: "fieldset", id: "93Y1C2sySkG4Eg0atBRIwg" }], presentation_title_field: null, presentation_image_field: null, title_field: null, image_preview_field: null, excerpt_field: null, ordering_field: null, workflow: null, } ``` --- # Content Management API — Duplicate model/block model Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item-type/duplicate.md ## Returns Returns a resource object of type [item\_type](/docs/content-management-api/resources/item-type.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const modelIdOrApiKey = "blog_post"; const itemType = await client.itemTypes.duplicate(modelIdOrApiKey); // Check the 'Returned output' tab for the result ☝️ console.log(itemType); } run(); ``` Returned output ```javascript { id: "DxMaW10UQiCmZcuuA-IkkA", name: "Blog post", api_key: "post", singleton: false, sortable: true, modular_block: false, tree: false, ordering_direction: null, ordering_meta: "created_at", draft_mode_active: false, all_locales_required: false, collection_appearance: "compact", hint: "Blog posts will be shown in our website under the Blog section", inverse_relationships_enabled: false, draft_saving_active: false, meta: { has_singleton_item: false }, singleton_item: null, fields: [{ type: "field", id: "Pkg-oztERp6o-Rj76nYKJg" }], fieldsets: [{ type: "fieldset", id: "93Y1C2sySkG4Eg0atBRIwg" }], presentation_title_field: null, presentation_image_field: null, title_field: null, image_preview_field: null, excerpt_field: null, ordering_field: null, workflow: null, } ``` --- # Content Management API — Delete a model/block model Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item-type/destroy.md ## Query parameters **`skip_menu_items_deletion`** - Type: boolean Skip the deletion of the menu items linked to the model ## Returns Returns a resource object of type [item\_type](/docs/content-management-api/resources/item-type.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const modelIdOrApiKey = "blog_post"; const itemType = await client.itemTypes.destroy(modelIdOrApiKey); // Check the 'Returned output' tab for the result ☝️ console.log(itemType); } run(); ``` Returned output ```javascript { id: "DxMaW10UQiCmZcuuA-IkkA", name: "Blog post", api_key: "post", singleton: false, sortable: true, modular_block: false, tree: false, ordering_direction: null, ordering_meta: "created_at", draft_mode_active: false, all_locales_required: false, collection_appearance: "compact", hint: "Blog posts will be shown in our website under the Blog section", inverse_relationships_enabled: false, draft_saving_active: false, meta: { has_singleton_item: false }, singleton_item: null, fields: [{ type: "field", id: "Pkg-oztERp6o-Rj76nYKJg" }], fieldsets: [{ type: "fieldset", id: "93Y1C2sySkG4Eg0atBRIwg" }], presentation_title_field: null, presentation_image_field: null, title_field: null, image_preview_field: null, excerpt_field: null, ordering_field: null, workflow: null, } ``` --- # Content Management API — List models referencing another model/block Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item-type/referencing.md Returns all models that reference the specified item type, either directly through fields or indirectly through nested blocks. ## For Block Models (modular\_block: true) Returns all models that can embed the specified block model, including: **Direct embedding via:** - `rich_text` fields (Modular Content) — specified in the `rich_text_blocks` validator - `single_block` fields — specified in the `single_block_blocks` validator - `structured_text` fields — specified in the `structured_text_blocks` or `structured_text_inline_blocks` validators **Indirect embedding:** - Models that embed other block models, which themselves contain fields that can embed the target block (recursive traversal through nested block structures) ## For Regular Models (modular\_block: false) Returns all models that reference the specified model, including: **Direct references via:** - `link` fields (Single link) — specified in the `item_item_type` validator - `links` fields (Multiple links) — specified in the `items_item_type` validator - `structured_text` fields — specified in the `structured_text_links` validator **Indirect references:** - Models that embed block models containing fields that reference the target model (traversal through nested block structures to find references within blocks) ## Query parameters **`fields`** - Type: object Sparse fieldsets: for each entity type, the attributes and the relationships to return, separated by commas. Each entity declares its attributes and its relationships in its own schema.
Show object format **`item_type`** - Type: string - Example: `"name,api_key,collection_appearance,singleton_item"` Attributes and relationships to return for each `item_type` that this endpoint returns.
## Returns Returns an array of resource objects of type [item\_type](/docs/content-management-api/resources/item-type.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const modelIdOrApiKey = "blog_post"; const itemTypes = await client.itemTypes.referencing(modelIdOrApiKey); for (const itemType of itemTypes) { // Check the 'Returned output' tab for the result ☝️ console.log(itemType); } } run(); ``` Returned output ```javascript { id: "DxMaW10UQiCmZcuuA-IkkA", name: "Blog post", api_key: "post", singleton: false, sortable: true, modular_block: false, tree: false, ordering_direction: null, ordering_meta: "created_at", draft_mode_active: false, all_locales_required: false, collection_appearance: "compact", hint: "Blog posts will be shown in our website under the Blog section", inverse_relationships_enabled: false, draft_saving_active: false, meta: { has_singleton_item: false }, singleton_item: null, fields: [{ type: "field", id: "Pkg-oztERp6o-Rj76nYKJg" }], fieldsets: [{ type: "fieldset", id: "93Y1C2sySkG4Eg0atBRIwg" }], presentation_title_field: null, presentation_image_field: null, title_field: null, image_preview_field: null, excerpt_field: null, ordering_field: null, workflow: null, } ``` --- # Content Management API — Field Source [docs]: https://www.datocms.com/docs/content-management-api/resources/field.md DatoCMS offers a number of different fields that you can combine together to create a [Model](/docs/content-management-api/resources/item-type.md). Using the database metaphore, fields are like table columns, and when creating them you need to specify their type (`string`, `float`, etc.) and any required validation. ### Different field types require different settings When looking at a field resource, you have to pay attention to two particular properties, `validators` and `appearance`. The `validators` property expresses the set of validations to be performed server-side on a specific field value for it to be considered valid, while the `appearance` property lets you specify *how* the field itself will be presented inside the form to the final editor. For both properties, the value to specify depends on the type of field itself. For example, you can add a "Limit character count" validation to a *Single-line string* field, or set its appearence to "Show it as heading", but they won't be accepted for a ie. *Color* field, as it supports different validations and appearance settings. ### Specifying validations The `validators` property requires an object whose keys are the validations that you want to be enforced, and the values are objects representing any settings that the validation itself requires. If the validation doesn't have additional settings, you just pass down an empty object. This is a valid example for a *Single-line string* field: ```js { "validators": { // "required" validator has no settings "required": {}, // "length" validator requires "min" and/or "max" properties "length": { "min": 80 } } } ``` Below you'll find a summary of all the validators available for each field type with their settings. Some validators are required for a specific type of field. For example, the *Modular Content* field needs to have a `rich_text_blocks` validator, specifying which types of blocks it can contain. ### Specifying the appearance The `appearance` property requires an object with three specific properties: `editor`, `parameters` and `addons`. The `editor` represents the type of editor that the users will see inside the form to change the value of this specific field. Depending on the type of field, DatoCMS offers a number of different editors for you to choose from. The `parameters` property is an object representing any additional settings that the editor itself might require. This is a valid example for a *Single-line string* field: ```js { "appearance": { // single_line is a DatoCMS built-in editor that you can use with single-line string fields "editor": "single_line", // each built-in editor has specific settings "parameters": { "heading": true, "placeholder": "My blog post title" }, "addons": [] }, } ``` Following you'll find a summary of all the editors available for each field type with their settings. #### Setting the appearance to a field editor provided by a plugin If the project contains a plugin that exposes [manual field editors](/docs/plugin-sdk/manual-field-extensions.md), you can also configure the field to be presented with it instead of using one of the built-in editors. In this case: - the `editor` property is the plugin's project-specific autogenerated UUID. You can get it from the last part of the plugin's URL within your project's Configuration screen (e.g. `https://your-project.admin.datocms.com/configuration/plugins/PLUGIN_UUID/`), or via API with a [List all plugins](/docs/content-management-api/resources/plugin/instances.md) call. - the `field_extension` property must be the ID of the specific manual field editor that the plugin exposes. This is set in the plugin's own source code, within a `manualFieldExtension()` call in its entry point (usually something like `index.tsx`). - the `parameters` property must provide a configuration object compatible with the [config screen of the manual field extension](/docs/plugin-sdk/manual-field-extensions.md#add-per-field-config-screens-to-manual-field-extensions), or an empty object if it doesn't require any configuration. ```js { "appearance": { // "2132" is a the ID of a plugin exposing a manual field editor "editor": "2134", // "starRating" is a manual field editor exposed by the plugin "field_extension": "starRating", // this is a valid configuration for the "starRating" field editor "parameters": { "maxRating": 5, "starsColor": "#ff0000" }, "addons": [] }, } ``` #### Configuring manual field addons If the project contains plugins that expose [manual field addons](/docs/plugin-sdk/manual-field-extensions.md), you can also add them to the field via the `addons` property. ```js { "appearance": { "editor": "single_line", "parameters": { "heading": true, "placeholder": "My blog post title" }, "addons": [ { // "2138" is a the ID of a plugin exposing a manual addon editor "id": "2138", // "loremIpsumGenerator" is a manual field addon exposed by the plugin "field_extension": "loremIpsumGenerator", // this is a valid configuration for the "loremIpsumGenerator" field addon "parameters": { "sentences": 2 }, } ] }, } ``` ### Available field types
Single-line string (string) | Property | Value | | --- | --- | | Code | `string` | | Built-in editors for the field | `single_line`, `string_radio_group`, `string_select` | | Available validators | `required`, `unique`, `length`, `format`, `enum` |
Multi-line text (text) | Property | Value | | --- | --- | | Code | `text` | | Built-in editors for the field | `markdown`, `wysiwyg`, `textarea` | | Available validators | `required`, `length`, `format`, `sanitized_html` |
Boolean (boolean) | Property | Value | | --- | --- | | Code | `boolean` | | Built-in editors for the field | `boolean`, `boolean_radio_group` | | Available validators | no validators available |
Integer (integer) | Property | Value | | --- | --- | | Code | `integer` | | Built-in editors for the field | `integer` | | Available validators | `required`, `number_range` |
Float (float) | Property | Value | | --- | --- | | Code | `float` | | Built-in editors for the field | `float` | | Available validators | `required`, `number_range` |
Date (date) | Property | Value | | --- | --- | | Code | `date` | | Built-in editors for the field | `date_picker` | | Available validators | `required`, `date_range` |
Date time (date_time) | Property | Value | | --- | --- | | Code | `date_time` | | Built-in editors for the field | `date_time_picker` | | Available validators | `required`, `date_time_range` |
Color (color) | Property | Value | | --- | --- | | Code | `color` | | Built-in editors for the field | `color_picker` | | Available validators | `required` |
JSON (json) | Property | Value | | --- | --- | | Code | `json` | | Built-in editors for the field | `json`, `string_multi_select`, `string_checkbox_group` | | Available validators | `required` |
Location (lat_lon) | Property | Value | | --- | --- | | Code | `lat_lon` | | Built-in editors for the field | `map` | | Available validators | `required` |
SEO and Social (seo) | Property | Value | | --- | --- | | Code | `seo` | | Built-in editors for the field | `seo` | | Available validators | `required_seo_fields`, `file_size`, `image_dimensions`, `image_aspect_ratio`, `title_length`, `description_length` |
Slug (slug) | Property | Value | | --- | --- | | Code | `slug` | | Built-in editors for the field | `slug` | | Available validators | `required`, `unique`, `length`, `slug_format`, `slug_title_field` |
External video (video) | Property | Value | | --- | --- | | Code | `video` | | Built-in editors for the field | `video` | | Available validators | `required` |
Single-asset (file) | Property | Value | | --- | --- | | Code | `file` | | Built-in editors for the field | `file` | | Available validators | `required`, `file_size`, `image_dimensions`, `image_aspect_ratio`, `extension`, `required_alt_title` |
Asset gallery (gallery) | Property | Value | | --- | --- | | Code | `gallery` | | Built-in editors for the field | `gallery` | | Available validators | `size`, `file_size`, `image_dimensions`, `image_aspect_ratio`, `extension`, `required_alt_title` |
Single link (link) | Property | Value | | --- | --- | | Code | `link` | | Built-in editors for the field | `link_select`, `link_embed` | | Default `editor` | `link_select` | | Required validators | `item_item_type` | | Other validators available | `required`, `unique` |
Multiple links (links) | Property | Value | | --- | --- | | Code | `links` | | Built-in editors for the field | `links_select`, `links_embed` | | Default `editor` | `links_select` | | Required validators | `items_item_type` | | Other validators available | `size` |
Modular content (rich_text) | Property | Value | | --- | --- | | Code | `rich_text` | | Built-in editors for the field | `rich_text` | | Required validators | `rich_text_blocks` | | Other validators available | `size` |
Single Block (single_block) | Property | Value | | --- | --- | | Code | `single_block` | | Built-in editors for the field | `framed_single_block`, `frameless_single_block` | | Required validators | `single_block_blocks` | | Other validators available | `required` |
Structured text (structured_text) | Property | Value | | --- | --- | | Code | `structured_text` | | Built-in editors for the field | `structured_text` | | Required validators | `structured_text_blocks`, `structured_text_links` | | Other validators available | `required`, `length`, `structured_text_inline_blocks` |
### Validators
date_range Accept dates only inside a specified date range. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `min` | ISO 8601 date | | Minimum date | | `max` | ISO 8601 date | | Maximum date | At least one of the parameters must be specified.
date_time_range Accept date times only inside a specified date range. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `min` | ISO 8601 datetime | | Minimum datetime | | `max` | ISO 8601 datetime | | Maximum datetime | At least one of the parameters must be specified.
enum Only accept a specific set of values | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `values` | `Array` | ✅ | Set of allowed values |
extension Only accept assets with specific file extensions. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `extensions` | `Array` | | Set of allowed file extensions | | `predefined_list` | one of `"image"`, `"transformable_image"`, `"video"`, `"document"` | | Allowed file type | Only one of the parameters must be specified.
file_size Accept assets only inside a specified date range. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `min_value` | `Integer` | | Numeric value for minimum filesize | | `min_unit` | one of `"B"`, `"KB"`, `"MB"` | | Unit for minimum filesize | | `max_value` | `Integer` | | Numeric value for maximum filesize | | `max_unit` | one of `"B"`, `"KB"`, `"MB"` | | Unit for maximum filesize | At least one couple of value/unit must be specified.
format Accepts only strings that match a specified format. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `custom_pattern` | `Regexp` | Optional | Custom regular expression for validation | | `predefined_pattern` | `"email"` or `"url"` | Optional | Specifies a pre-defined format (email or URL) | **Note:** Only one of `custom_pattern` or `predefined_pattern` should be specified. If `custom_pattern` is used, an additional `description` parameter can be provided to serve as a hint for the user. This hint offers a simple explanation of the expected pattern, such as `"The field must end with an 's'"`, instead of the default message like `"Field must match the pattern: /s$/"`.
slug_format Only accept slugs having a specific format. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `custom_pattern` | `Regexp` | | Regular expression to be validated | | `predefined_pattern` | `"webpage_slug"` | | Allowed format | Only one of the parameters must be specified.
image_dimensions Accept assets only within a specified height and width range. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `width_min_value` | `Integer` | | Numeric value for minimum width | | `width_max_value` | `Integer` | | Numeric value for maximum height | | `height_min_value` | `Integer` | | Numeric value for minimum width | | `height_max_value` | `Integer` | | Numeric value for maximum height | At least one pair of height/width parameters must be specified.
image_aspect_ratio Accept assets only within a specified aspect ratio range. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `min_ar_numerator` | `Integer` | | Numerator part of the minimum aspect ratio | | `min_ar_denominator` | `Integer` | | Denominator part of the minimum aspect ratio | | `eq_ar_numerator` | `Integer` | | Numerator part for the required aspect ratio | | `eq_ar_denominator` | `Integer` | | Denominator part for the required aspect ratio | | `max_ar_numerator` | `Integer` | | Numerator part of the maximum aspect ratio | | `max_ar_denominator` | `Integer` | | Denominator part of the maximum aspect ratio | At least one pair of numerator/denominator must be specified.
item_item_type Only accept references to records of the specified models. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `item_types` | `Array` | ✅ | Set of allowed model IDs | | `on_publish_with_unpublished_references_strategy` | `"fail"`, `"publish_references"` (default value: `"fail"`) | | Strategy to apply when a publishing is requested and this field references some unpublished records | | `on_reference_unpublish_strategy` | `"fail"`, `"unpublish"`, `"delete_references"` (default value: `"fail"`) | | Strategy to apply when unpublishing is requested for a record referenced by this field | | `on_reference_delete_strategy` | `"fail"`, `"delete_references"` (default value: `"delete_references"`) | | Strategy to apply when deletion is requested for a record referenced by this field | Possible values for `on_publish_with_unpublished_references_strategy`: - `"fail"`: Fail the operation and notify the user - `"publish_references"`: Publish also the referenced records Possible values for `on_reference_unpublish_strategy`: - `"fail"`: Fail the operation and notify the user - `"unpublish"`: Unpublish also this record - `"delete_references"`: Try to remove the reference to the unpublished record (if the field has a `required` validation it will fail) Possible values for `on_reference_delete_strategy`: - `"fail"`: Fail the operation and notify the user - `"delete_references"`: Try to remove the reference to the deleted record (if the field has a `required` validation it will fail)
items_item_type Only accept references to records of the specified models. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `item_types` | `Array` | ✅ | Set of allowed model IDs | | `on_publish_with_unpublished_references_strategy` | `"fail"`, `"publish_references"` (default value: `"fail"`) | | Strategy to apply when a publishing is requested and this field references some unpublished records | | `on_reference_unpublish_strategy` | `"fail"`, `"unpublish"`, `"delete_references"` (default value: `"fail"`) | | Strategy to apply when unpublishing is requested for a record referenced by this field | | `on_reference_delete_strategy` | `"fail"`, `"delete_references"` (default value: `"delete_references"`) | | Strategy to apply when deletion is requested for a record referenced by this field | Possible values for `on_publish_with_unpublished_references_strategy`: - `"fail"`: Fail the operation and notify the user - `"publish_references"`: Publish also the referenced records Possible values for `on_reference_unpublish_strategy`: - `"fail"`: Fail the operation and notify the user - `"unpublish"`: Unpublish also this record - `"delete_references"`: Try to remove the reference to the unpublished record (if the field has a `required` validation it will fail) Possible values for `on_reference_delete_strategy`: - `"fail"`: Fail the operation and notify the user - `"delete_references"`: Try to remove the reference to the deleted record (if the field has a `required` validation it will fail)
length Accept strings only with a specified number of characters. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `min` | `Integer` | | Minimum length | | `eq` | `Integer` | | Expected length | | `max` | `Integer` | | Maximum length | At least one parameter must be specified.
number_range Accept numbers only inside a specified range. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `min` | `Float` | | Minimum value | | `max` | `Float` | | Maximum value | At least one of the parameters must be specified.
required Value must be specified or it won't be valid.
required_alt_title Assets contained in the field are required to specify custom title or alternate text, or they won't be valid. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `title` | `Boolean` | | Whether the title for the asset must be specified | | `alt` | `Boolean` | | Whether the alternate text for the asset must be specified | At least one of the parameters must be specified.
required_seo_fields SEO field has to specify one or more properties, or it won't be valid. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `title` | `Boolean` | | Whether the meta title must be specified | | `description` | `Boolean` | | Whether the meta description must be specified | | `image` | `Boolean` | | Whether the social sharing image must be specified | | `twitter_card` | `Boolean` | | Whether the type of Twitter card must be specified | At least one of the parameters must be specified.
title_length Limits the length of the title for a SEO field. Search engines usually truncate title tags to 60 character so it is a good practice to keep the title around this length. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `min` | `Integer` | | Minimum value | | `max` | `Integer` | | Maximum value | At least one of the parameters must be specified.
description_length Limits the length of the description for a SEO field. Search engines usually truncate description tags to 160 character so it is a good practice to keep the description around this length. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `min` | `Integer` | | Minimum value | | `max` | `Integer` | | Maximum value | At least one of the parameters must be specified.
rich_text_blocks Only accept references to block records of the specified block models. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `item_types` | `Array` | ✅ | Set of allowed Block Model IDs |
single_block_blocks Only accept references to block records of the specified block models. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `item_types` | `Array` | ✅ | Set of allowed Block Model IDs |
sanitized_html Checks for the presence of malicious code in HTML fields: content is valid if no dangerous code is present. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `sanitize_before_validation` | `Boolean` | ✅ | Content is actively sanitized before applying the validation |
structured_text_blocks Only accept references to block records of the specified block models. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `item_types` | `Array` | ✅ | Set of allowed Block Model IDs |
structured_text_inline_blocks Only accept references to block records of the specified block models. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `item_types` | `Array` | ✅ | Set of allowed Block Model IDs |
structured_text_links Only accept `itemLink` to `inlineItem` nodes for records of the specified models. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `item_types` | `Array` | ✅ | Set of allowed model IDs | | `on_publish_with_unpublished_references_strategy` | `"fail"`, `"publish_references"` (default value: `"fail"`) | | Strategy to apply when a publishing is requested and this field references some unpublished records | | `on_reference_unpublish_strategy` | `"fail"`, `"unpublish"`, `"delete_references"` (default value: `"delete_references"`) | | Strategy to apply when unpublishing is requested for a record referenced by this field | | `on_reference_delete_strategy` | `"fail"`, `"delete_references"` (default value: `"delete_references"`) | | Strategy to apply when deletion is requested for a record referenced by this field | Possible values for `on_publish_with_unpublished_references_strategy`: - `"fail"`: Fail the operation and notify the user - `"publish_references"`: Publish also the referenced records Possible values for `on_reference_unpublish_strategy`: - `"fail"`: Fail the operation and notify the user - `"unpublish"`: Unpublish also this record - `"delete_references"`: Try to remove the reference to the unpublished record (if the field has a `required` validation it will fail) Possible values for `on_reference_delete_strategy`: - `"fail"`: Fail the operation and notify the user - `"delete_references"`: Try to remove the reference to the deleted record (if the field has a `required` validation it will fail)
size Only accept a number of items within the specified range. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `min` | `Integer` | | Minimum length | | `eq` | `Integer` | | Expected length | | `max` | `Integer` | | Maximum length | | `multiple_of` | `Integer` | | The number of items must be multiple of this value | At least one parameter must be specified.
slug_title_field Specifies the ID of the *Single-line string* field that will be used to generate the slug | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `title_field_id` | `Field ID` | ✅ | The field that will be used to generate the slug |
unique The value must be unique across the whole collection of records.
### Configuration parameters for DatoCMS built-in field editors If a field editor is not specified in this table, just pass an empty object `{}` as its configuration parameters.
boolean_radio_group Radio group input for *boolean* fields. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `positive_radio` | `{ label: string, hint?: string }` | ✅ | Radio input for positive choice (`true`) | | `negative_radio` | `{ label: string, hint?: string }` | ✅ | Radio input for negative choice (`false`) |
string_radio_group Radio group input for *string* fields. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `radios` | `Array<{ label: string, value: string, hint?: string }>` | ✅ | The different radio options |
string_select Select input for *string* fields. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `options` | `Array<{ label: string, value: string, hint?: string }>` | ✅ | The different select options |
string_multi_select Select input for *JSON* fields, to edit an array of strings. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `options` | `Array<{ label: string, value: string, hint?: string }>` | ✅ | The different select options |
string_checkbox_group Multiple chechboxes input for *JSON* fields, to edit an array of strings. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `options` | `Array<{ label: string, value: string, hint?: string }>` | ✅ | The different select options |
single_line Simple textual input for *Single-line string* fields. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `heading` | `Boolean` | ✅ | Indicates if the field should be shown bigger, as a field representing a heading | | `placeholder` | `String` | | A placeholder that will be shown in the editor's input to provide editors with an example. |
markdown Markdown editor for *Multiple-paragraph text* fields. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `toolbar` | `Array` | ✅ | Specify which buttons the toolbar should have. Valid values: `"heading"`, `"bold"`, `"italic"`, `"strikethrough"`, `"code"`, `"unordered_list"`, `"ordered_list"`, `"quote"`, `"link"`, `"image"`, `"fullscreen"` |
wysiwyg HTML editor for *Multiple-paragraph text* fields. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `toolbar` | `Array` | ✅ | Specify which buttons the toolbar should have. Valid values: `"format"`, `"bold"`, `"italic"`, `"strikethrough"`, `"code"`, `"ordered_list"`, `"unordered_list"`, `"quote"`, `"table"`, `"link"`, `"image"`, `"show_source"`, `"undo"`, `"redo"`, `"align_left"`, `"align_center"`, `"align_right"`, `"align_justify"`, `"outdent"`, `"indent"`, `"fullscreen"` |
textarea Basic textarea editor for *Multiple-paragraph text* fields. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `placeholder` | `String` | | A placeholder that will be shown in the editor's input to provide editors with an example. |
color_picker Built-in editor for *Color* fields. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `enable_alpha` | `Boolean` | ✅ | Should the color picker allow to specify the alpha value? | | `preset_colors` | `Array` | ✅ | List of preset colors to offer to the user |
slug Built-in editor for *Slug* fields. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `url_prefix` | `String` | | A prefix that will be shown in the editor's form to give some context to your editors. | | `placeholder` | `String` | | A placeholder that will be shown in the editor's input to provide editors with an example. |
seo Built-in editor for *seo* fields. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `fields` | `Array` | ✅ | Specify which fields of the SEO input should be visible to editors. Valid values: `"title"`, `"description"`, `"image"`, `"no_index"`, `"twitter_card"` | | `previews` | `Array` | ✅ | Specify which previews should be visible to editors. Valid values: `"google"`, `"twitter"`, `"slack"`, `"whatsapp"`, `"telegram"`, `"facebook"`, `"linkedin"` |
rich_text Built-in editor for *Modular content* fields. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `start_collapsed` | `Boolean` | | Whether you want block records collapsed by default or not |
framed_single_block Built-in editor for *Single block* fields. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `start_collapsed` | `Boolean` | | Whether you want block record collapsed by default or not |
structured_text Built-in editor for *Structured text* fields. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `nodes` | `Array` | ✅ | Specify which nodes the field should allow. Valid values: `"blockquote"`, `"code"`, `"heading"`, `"link"`, `"list"`, `"thematicBreak"` | | `marks` | `Array` | ✅ | Specify which marks the field should allow. Valid values: `"strong"`, `"emphasis"`, `"underline"`, `"strikethrough"`, `"code"`, `"highlight"` | | `heading_levels` | `Array` | ✅ | If `nodes` includes `"heading"`, specify which heading levels the field should allow. Valid values: numbers between 1 and 6 | | `blocks_start_collapsed` | `Boolean` | | Whether you want block nodes collapsed by default or not | | `show_links_target_blank` | `Boolean` | | Whether you want to show the "Open this link in a new tab?" checkbox, that fills in the `target: "_blank"` meta attribute for links | | `show_links_meta_editor` | `Boolean` | | Whether you want to show the complete meta editor for links |
link_select and links_select Use a select input with auto-completion to pick the records to reference inside the field.
link_embed and links_embed Use an expanded view with records' image preview to pick the records to reference inside the field.
integer Built-in editor for *Integer* fields. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `placeholder` | `String` | | A placeholder that will be shown in the editor's input to provide editors with an example. |
float Built-in editor for *Float* fields. | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `placeholder` | `String` | | A placeholder that will be shown in the editor's input to provide editors with an example. |
## Object payload **`id`** - Type: string - Example: `"Pkg-oztERp6o-Rj76nYKJg"` RFC 4122 UUID of field expressed in URL-safe base64 format **`type`** - Type: string Must be exactly `"field"`. **`label`** - Type: string - Example: `"Title"` The label of the field **`field_type`** - Type: enum - Example: `"string"` Type of input
Show enum values **`boolean`** **`color`** **`date`** **`date_time`** **`file`** **`float`** **`gallery`** **`integer`** **`json`** **`lat_lon`** **`link`** **`links`** **`rich_text`** **`seo`** **`single_block`** **`slug`** **`string`** **`structured_text`** **`text`** **`video`**
**`api_key`** - Type: string - Example: `"title"` Field API key **`localized`** - Type: boolean Whether the field needs to be multilanguage or not **`validators`** - Type: object - Example: `{ required: {} }` Optional field validations **`position`** - Type: integer - Example: `1` Ordering index **`hint`** - Type: string, null - Example: `"This field will be used as post title"` Field hint **`default_value`** - Type: boolean, null, string, number, object - Example: `{ en: "A default value", it: "Un valore di default" }` Default value for Field. When field is localized accepts an object of default values with site locales as keys **`appearance`** - Type: object Field appearance details, plugin configuration and field add-ons Example: ```json { editor: "single_line", parameters: { heading: false }, addons: [{ id: "1234", field_extension: "lorem_ipsum", parameters: {} }], } ```
Show object format **`editor`** - Type: string A valid editor can be a DatoCMS default field editor type (ie. `"single_line"`), or a plugin ID offering a custom field editor **`parameters`** - Type: object The editor plugin's parameters **`addons`** - Type: Array\ An array of add-on plugins with id and parameters
Show objects format inside array **`id`** - Type: string The ID of a plugin offering a field addon **`parameters`** - Type: object **`field_extension`** - Type: string The specific field extension to use for the field (only if the editor is a modern plugin)
**`field_extension`** - Type: string The specific field extension to use for the field (only if the editor is a modern plugin)
**`deep_filtering_enabled`** - Type: boolean Whether deep filtering for block models is enabled in GraphQL or not **`content_link_enabled`** - Type: boolean Whether Content Link (visual editing) encoding is emitted for this field's value in the Content Delivery API. Defaults to `true`; can only be set to `false` on `string`, `text` and `structured_text` fields **`item_type`** - Type: [ResourceLinkage\<"item_type"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item_type.md) Field item type **`fieldset`** - Type: null, [ResourceLinkage\<"fieldset"\>](https://www-draft.datocms.com/docs/content-management-api/resources/fieldset.md) Fieldset linkage
Show deprecated **`appeareance`** - Deprecated - Type: object Field appearance This field contains a typo and will be removed in future versions: use `appearance` instead
Show object format **`editor`** - Type: string **`parameters`** - Type: object
--- # Content Management API — Create a new field Source [docs]: https://www.datocms.com/docs/content-management-api/resources/field/create.md ## Body parameters **`id`** - Optional - Type: string - Example: `"Pkg-oztERp6o-Rj76nYKJg"` RFC 4122 UUID of field expressed in URL-safe base64 format **`label`** - Required - Type: string - Example: `"Title"` The label of the field **`field_type`** - Required - Type: enum - Example: `"string"` Type of input
Show enum values **`boolean`** - Optional **`color`** - Optional **`date`** - Optional **`date_time`** - Optional **`file`** - Optional **`float`** - Optional **`gallery`** - Optional **`integer`** - Optional **`json`** - Optional **`lat_lon`** - Optional **`link`** - Optional **`links`** - Optional **`rich_text`** - Optional **`seo`** - Optional **`single_block`** - Optional **`slug`** - Optional **`string`** - Optional **`structured_text`** - Optional **`text`** - Optional **`video`** - Optional
**`api_key`** - Required - Type: string - Example: `"title"` Field API key **`localized`** - Optional - Type: boolean Whether the field needs to be multilanguage or not **`validators`** - Optional - Type: object - Example: `{ required: {} }` Optional field validations **`appearance`** - Optional - Type: object Field appearance details, plugin configuration and field add-ons Example: ```json { editor: "single_line", parameters: { heading: false }, addons: [{ id: "1234", field_extension: "lorem_ipsum", parameters: {} }], } ```
Show object format **`editor`** - Required - Type: string A valid editor can be a DatoCMS default field editor type (ie. `"single_line"`), or a plugin ID offering a custom field editor **`parameters`** - Required - Type: object The editor plugin's parameters **`addons`** - Required - Type: Array\ An array of add-on plugins with id and parameters
Show objects format inside array **`id`** - Required - Type: string The ID of a plugin offering a field addon **`parameters`** - Required - Type: object **`field_extension`** - Optional - Type: string The specific field extension to use for the field (only if the editor is a modern plugin)
**`field_extension`** - Optional - Type: string The specific field extension to use for the field (only if the editor is a modern plugin)
**`position`** - Optional - Type: integer - Example: `1` Ordering index **`hint`** - Optional - Type: string, null - Example: `"This field will be used as post title"` Field hint **`default_value`** - Optional - Type: boolean, null, string, number, object - Example: `{ en: "A default value", it: "Un valore di default" }` Default value for Field. When field is localized accepts an object of default values with site locales as keys **`deep_filtering_enabled`** - Optional - Type: boolean Whether deep filtering for block models is enabled in GraphQL or not **`content_link_enabled`** - Optional - Type: boolean Whether Content Link (visual editing) encoding is emitted for this field's value in the Content Delivery API. Defaults to `true`; can only be set to `false` on `string`, `text` and `structured_text` fields **`fieldset`** - Optional - Type: null, [ResourceLinkage\<"fieldset"\>](https://www-draft.datocms.com/docs/content-management-api/resources/fieldset.md) Fieldset linkage
Show deprecated **`appeareance`** - Deprecated - Type: object Field appearance This field contains a typo and will be removed in future versions: use `appearance` instead
Show object format **`editor`** - Required - Type: string **`parameters`** - Required - Type: object
## Returns Returns a resource object of type [field](/docs/content-management-api/resources/field.md) ## Other examples ###### Example Basic example This is a complete example for creating a new localized *Single-line string* field: Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const modelIdOrApiKey = "blog_post"; const field = await client.fields.create(modelIdOrApiKey, { label: "Title", field_type: "string", api_key: "title", }); // Check the 'Returned output' tab for the result ☝️ console.log(field); } run(); ``` Returned output ```javascript { id: "Pkg-oztERp6o-Rj76nYKJg", label: "Title", field_type: "string", api_key: "title", localized: true, validators: { required: {} }, position: 1, hint: "This field will be used as post title", default_value: { en: "A default value", it: "Un valore di default" }, appearance: { editor: "single_line", parameters: { heading: false }, addons: [{ id: "1234", field_extension: "lorem_ipsum", parameters: {} }], }, deep_filtering_enabled: true, content_link_enabled: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, fieldset: null, } ``` ###### Example Creating Modular Content fields In this example: - first we create some [block models](/docs/content-modelling/blocks.md) using the `client.itemTypes.create()` method, making sure to set the `modular_block` attribute to `true` — this tells the API that they're in fact block models, and not regular models; - we then create a [Modular content](/docs/content-modelling/modular-content.md) field, passing down the allowed block models in the `rich_text_blocks` validator: Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const modularBlock1 = await client.itemTypes.create({ name: "Modular Block 1", api_key: "modular_block1", modular_block: true, }); const modularBlock2 = await client.itemTypes.create({ name: "Modular Block 2", api_key: "modular_block2", modular_block: true, }); const field = await client.fields.create("UZyfjdBES8y2W2ruMEHSoA", { label: "Content", field_type: "rich_text", api_key: "content", validators: { rich_text_blocks: { item_types: [modularBlock1.id, modularBlock2.id], }, }, }); console.log(field); } run(); ``` Returned output ```javascript { id: "Pkg-oztERp6o-Rj76nYKJg", label: "Title", field_type: "string", api_key: "title", localized: true, validators: { required: {} }, position: 1, hint: "This field will be used as post title", default_value: { en: "A default value", it: "Un valore di default" }, appearance: { editor: "single_line", parameters: { heading: false }, addons: [{ id: "1234", field_extension: "lorem_ipsum", parameters: {} }], }, deep_filtering_enabled: true, content_link_enabled: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, fieldset: null, } ``` ###### Example Creating Structured Text fields [Structured Text](/docs/content-modelling/structured-text.md) fields support both embedded block records and links to other regular records. For DatoCMS, a block model is just like a regular model, so we'll create them with `client.itemTypes.create()`, passing the `modularBlock` property to `true`: In this example: - first we create some [block models](/docs/content-modelling/blocks.md) using the `client.itemTypes.create()` method, making sure to set the `modular_block` attribute to `true` — this tells the API that they're in fact block models, and not regular models; - we then create the Structured Text field, passing down the embeddable block models in the `structured_text_blocks` and `structured_text_inline_blocks` validator, and the linkable record models in the `structured_text_links` validator: Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const modularBlock1 = await client.itemTypes.create({ name: "Modular Block 1", api_key: "modular_block1", modular_block: true, }); const modularBlock2 = await client.itemTypes.create({ name: "Modular Block 2", api_key: "modular_block2", modular_block: true, }); const field = await client.fields.create("UZyfjdBES8y2W2ruMEHSoA", { label: "Structured content", field_type: "structured_text", api_key: "content", validators: { structured_text_blocks: { item_types: [modularBlock1.id, modularBlock2.id], }, structured_text_inline_blocks: { item_types: [modularBlock1.id], }, structured_text_links: { item_types: ["UZyfjdBES8y2W2ruMEHSoA"], }, }, }); console.log(field); } run(); ``` Returned output ```javascript { id: "Pkg-oztERp6o-Rj76nYKJg", label: "Title", field_type: "string", api_key: "title", localized: true, validators: { required: {} }, position: 1, hint: "This field will be used as post title", default_value: { en: "A default value", it: "Un valore di default" }, appearance: { editor: "single_line", parameters: { heading: false }, addons: [{ id: "1234", field_extension: "lorem_ipsum", parameters: {} }], }, deep_filtering_enabled: true, content_link_enabled: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, fieldset: null, } ``` --- # Content Management API — Update a field Source [docs]: https://www.datocms.com/docs/content-management-api/resources/field/update.md ## Body parameters **`default_value`** - Optional - Type: boolean, null, string, number, object - Example: `{ en: "A default value", it: "Un valore di default" }` Default value for Field. When field is localized accepts an object of default values with site locales as keys **`label`** - Optional - Type: string - Example: `"Title"` The label of the field **`api_key`** - Optional - Type: string - Example: `"title"` Field API key **`localized`** - Optional - Type: boolean Whether the field needs to be multilanguage or not **`validators`** - Optional - Type: object - Example: `{ required: {} }` Optional field validations **`appearance`** - Optional - Type: object Field appearance details, plugin configuration and field add-ons Example: ```json { editor: "single_line", parameters: { heading: false }, addons: [{ id: "1234", field_extension: "lorem_ipsum", parameters: {} }], } ```
Show object format **`editor`** - Required - Type: string A valid editor can be a DatoCMS default field editor type (ie. `"single_line"`), or a plugin ID offering a custom field editor **`parameters`** - Required - Type: object The editor plugin's parameters **`addons`** - Required - Type: Array\ An array of add-on plugins with id and parameters
Show objects format inside array **`id`** - Required - Type: string The ID of a plugin offering a field addon **`parameters`** - Required - Type: object **`field_extension`** - Optional - Type: string The specific field extension to use for the field (only if the editor is a modern plugin)
**`field_extension`** - Optional - Type: string The specific field extension to use for the field (only if the editor is a modern plugin)
**`position`** - Optional - Type: integer - Example: `1` Ordering index **`field_type`** - Optional - Type: enum - Example: `"string"` Type of input
Show enum values **`boolean`** - Optional **`color`** - Optional **`date`** - Optional **`date_time`** - Optional **`file`** - Optional **`float`** - Optional **`gallery`** - Optional **`integer`** - Optional **`json`** - Optional **`lat_lon`** - Optional **`link`** - Optional **`links`** - Optional **`rich_text`** - Optional **`seo`** - Optional **`single_block`** - Optional **`slug`** - Optional **`string`** - Optional **`structured_text`** - Optional **`text`** - Optional **`video`** - Optional
**`hint`** - Optional - Type: string, null - Example: `"This field will be used as post title"` Field hint **`deep_filtering_enabled`** - Optional - Type: boolean Whether deep filtering for block models is enabled in GraphQL or not **`content_link_enabled`** - Optional - Type: boolean Whether Content Link (visual editing) encoding is emitted for this field's value in the Content Delivery API. Defaults to `true`; can only be set to `false` on `string`, `text` and `structured_text` fields **`fieldset`** - Optional - Type: null, [ResourceLinkage\<"fieldset"\>](https://www-draft.datocms.com/docs/content-management-api/resources/fieldset.md) Fieldset linkage
Show deprecated **`appeareance`** - Deprecated - Type: object Field appearance This field contains a typo and will be removed in future versions: use `appearance` instead
Show object format **`editor`** - Required - Type: string **`parameters`** - Required - Type: object
## Returns Returns a resource object of type [field](/docs/content-management-api/resources/field.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const fieldIdOrApiKey = "blog_post::title"; const field = await client.fields.update(fieldIdOrApiKey, { id: "Pkg-oztERp6o-Rj76nYKJg", }); // Check the 'Returned output' tab for the result ☝️ console.log(field); } run(); ``` Returned output ```javascript { id: "Pkg-oztERp6o-Rj76nYKJg", label: "Title", field_type: "string", api_key: "title", localized: true, validators: { required: {} }, position: 1, hint: "This field will be used as post title", default_value: { en: "A default value", it: "Un valore di default" }, appearance: { editor: "single_line", parameters: { heading: false }, addons: [{ id: "1234", field_extension: "lorem_ipsum", parameters: {} }], }, deep_filtering_enabled: true, content_link_enabled: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, fieldset: null, } ``` --- # Content Management API — List all fields of a model/block Source [docs]: https://www.datocms.com/docs/content-management-api/resources/field/instances.md ## Query parameters **`fields`** - Type: object Sparse fieldsets: for each entity type, the attributes and the relationships to return, separated by commas. Each entity declares its attributes and its relationships in its own schema.
Show object format **`field`** - Type: string - Example: `"label,field_type,localized,item_type"` Attributes and relationships to return for each `field` that this endpoint returns.
## Returns Returns an array of resource objects of type [field](/docs/content-management-api/resources/field.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const modelIdOrApiKey = "blog_post"; const fields = await client.fields.list(modelIdOrApiKey); for (const field of fields) { // Check the 'Returned output' tab for the result ☝️ console.log(field); } } run(); ``` Returned output ```javascript { id: "Pkg-oztERp6o-Rj76nYKJg", label: "Title", field_type: "string", api_key: "title", localized: true, validators: { required: {} }, position: 1, hint: "This field will be used as post title", default_value: { en: "A default value", it: "Un valore di default" }, appearance: { editor: "single_line", parameters: { heading: false }, addons: [{ id: "1234", field_extension: "lorem_ipsum", parameters: {} }], }, deep_filtering_enabled: true, content_link_enabled: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, fieldset: null, } ``` --- # Content Management API — List fields referencing a model/block Source [docs]: https://www.datocms.com/docs/content-management-api/resources/field/referencing.md Returns all fields in the project that reference a specific model (works both for Models and Block Models) ## Query parameters **`fields`** - Type: object Sparse fieldsets: for each entity type, the attributes and the relationships to return, separated by commas. Each entity declares its attributes and its relationships in its own schema.
Show object format **`field`** - Type: string - Example: `"label,field_type,localized,item_type"` Attributes and relationships to return for each `field` that this endpoint returns.
## Returns Returns an array of resource objects of type [field](/docs/content-management-api/resources/field.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const modelIdOrApiKey = "blog_post"; const fields = await client.fields.referencing(modelIdOrApiKey); for (const field of fields) { // Check the 'Returned output' tab for the result ☝️ console.log(field); } } run(); ``` Returned output ```javascript { id: "Pkg-oztERp6o-Rj76nYKJg", label: "Title", field_type: "string", api_key: "title", localized: true, validators: { required: {} }, position: 1, hint: "This field will be used as post title", default_value: { en: "A default value", it: "Un valore di default" }, appearance: { editor: "single_line", parameters: { heading: false }, addons: [{ id: "1234", field_extension: "lorem_ipsum", parameters: {} }], }, deep_filtering_enabled: true, content_link_enabled: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, fieldset: null, } ``` --- # Content Management API — Retrieve a field Source [docs]: https://www.datocms.com/docs/content-management-api/resources/field/self.md ## Query parameters **`fields`** - Type: object Sparse fieldsets: for each entity type, the attributes and the relationships to return, separated by commas. Each entity declares its attributes and its relationships in its own schema.
Show object format **`field`** - Type: string - Example: `"label,field_type,localized,item_type"` Attributes and relationships to return for each `field` that this endpoint returns.
## Returns Returns a resource object of type [field](/docs/content-management-api/resources/field.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const fieldIdOrApiKey = "blog_post::title"; const field = await client.fields.find(fieldIdOrApiKey); // Check the 'Returned output' tab for the result ☝️ console.log(field); } run(); ``` Returned output ```javascript { id: "Pkg-oztERp6o-Rj76nYKJg", label: "Title", field_type: "string", api_key: "title", localized: true, validators: { required: {} }, position: 1, hint: "This field will be used as post title", default_value: { en: "A default value", it: "Un valore di default" }, appearance: { editor: "single_line", parameters: { heading: false }, addons: [{ id: "1234", field_extension: "lorem_ipsum", parameters: {} }], }, deep_filtering_enabled: true, content_link_enabled: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, fieldset: null, } ``` --- # Content Management API — Delete a field Source [docs]: https://www.datocms.com/docs/content-management-api/resources/field/destroy.md ## Returns Returns a resource object of type [field](/docs/content-management-api/resources/field.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const fieldIdOrApiKey = "blog_post::title"; const field = await client.fields.destroy(fieldIdOrApiKey); // Check the 'Returned output' tab for the result ☝️ console.log(field); } run(); ``` Returned output ```javascript { id: "Pkg-oztERp6o-Rj76nYKJg", label: "Title", field_type: "string", api_key: "title", localized: true, validators: { required: {} }, position: 1, hint: "This field will be used as post title", default_value: { en: "A default value", it: "Un valore di default" }, appearance: { editor: "single_line", parameters: { heading: false }, addons: [{ id: "1234", field_extension: "lorem_ipsum", parameters: {} }], }, deep_filtering_enabled: true, content_link_enabled: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, fieldset: null, } ``` --- # Content Management API — Duplicate a field Source [docs]: https://www.datocms.com/docs/content-management-api/resources/field/duplicate.md ## Returns Returns a resource object of type [field](/docs/content-management-api/resources/field.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const fieldIdOrApiKey = "blog_post::title"; const field = await client.fields.duplicate(fieldIdOrApiKey); // Check the 'Returned output' tab for the result ☝️ console.log(field); } run(); ``` Returned output ```javascript { id: "Pkg-oztERp6o-Rj76nYKJg", label: "Title", field_type: "string", api_key: "title", localized: true, validators: { required: {} }, position: 1, hint: "This field will be used as post title", default_value: { en: "A default value", it: "Un valore di default" }, appearance: { editor: "single_line", parameters: { heading: false }, addons: [{ id: "1234", field_extension: "lorem_ipsum", parameters: {} }], }, deep_filtering_enabled: true, content_link_enabled: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, fieldset: null, } ``` --- # Content Management API — Fieldset Source [docs]: https://www.datocms.com/docs/content-management-api/resources/fieldset.md Fields can be organized and grouped into fieldset to better present them to editors. ## Object payload **`id`** - Type: string - Example: `"93Y1C2sySkG4Eg0atBRIwg"` RFC 4122 UUID of fieldset expressed in URL-safe base64 format **`type`** - Type: string Must be exactly `"fieldset"`. **`title`** - Type: string - Example: `"SEO-related fields"` The title of the fieldset **`hint`** - Type: string, null - Example: `"Please fill in these fields!"` Description/contextual hint for the fieldset **`position`** - Type: integer - Example: `1` Ordering index **`collapsible`** - Type: boolean Whether the fieldset can be collapsed or not **`start_collapsed`** - Type: boolean When fieldset is collapsible, determines if the default is to start collapsed or not **`item_type`** - Type: [ResourceLinkage\<"item_type"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item_type.md) Fieldset item type --- # Content Management API — Create a new fieldset Source [docs]: https://www.datocms.com/docs/content-management-api/resources/fieldset/create.md ## Body parameters **`id`** - Optional - Type: string - Example: `"93Y1C2sySkG4Eg0atBRIwg"` RFC 4122 UUID of fieldset expressed in URL-safe base64 format **`title`** - Required - Type: string - Example: `"SEO-related fields"` The title of the fieldset **`hint`** - Optional - Type: string, null - Example: `"Please fill in these fields!"` Description/contextual hint for the fieldset **`position`** - Optional - Type: integer - Example: `1` Ordering index **`collapsible`** - Optional - Type: boolean Whether the fieldset can be collapsed or not **`start_collapsed`** - Optional - Type: boolean When fieldset is collapsible, determines if the default is to start collapsed or not ## Returns Returns a resource object of type [fieldset](/docs/content-management-api/resources/fieldset.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const modelIdOrApiKey = "blog_post"; const fieldset = await client.fieldsets.create(modelIdOrApiKey, { title: "SEO-related fields", }); // Check the 'Returned output' tab for the result ☝️ console.log(fieldset); } run(); ``` Returned output ```javascript { id: "93Y1C2sySkG4Eg0atBRIwg", title: "SEO-related fields", hint: "Please fill in these fields!", position: 1, collapsible: true, start_collapsed: false, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, } ``` --- # Content Management API — Update a fieldset Source [docs]: https://www.datocms.com/docs/content-management-api/resources/fieldset/update.md ## Body parameters **`title`** - Optional - Type: string - Example: `"SEO-related fields"` The title of the fieldset **`hint`** - Optional - Type: string, null - Example: `"Please fill in these fields!"` Description/contextual hint for the fieldset **`position`** - Optional - Type: integer - Example: `1` Ordering index **`collapsible`** - Optional - Type: boolean Whether the fieldset can be collapsed or not **`start_collapsed`** - Optional - Type: boolean When fieldset is collapsible, determines if the default is to start collapsed or not ## Returns Returns a resource object of type [fieldset](/docs/content-management-api/resources/fieldset.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const fieldsetId = "93Y1C2sySkG4Eg0atBRIwg"; const fieldset = await client.fieldsets.update(fieldsetId, { id: "93Y1C2sySkG4Eg0atBRIwg", }); // Check the 'Returned output' tab for the result ☝️ console.log(fieldset); } run(); ``` Returned output ```javascript { id: "93Y1C2sySkG4Eg0atBRIwg", title: "SEO-related fields", hint: "Please fill in these fields!", position: 1, collapsible: true, start_collapsed: false, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, } ``` --- # Content Management API — List all fieldsets of a model/block Source [docs]: https://www.datocms.com/docs/content-management-api/resources/fieldset/instances.md ## Query parameters **`fields`** - Type: object Sparse fieldsets: for each entity type, the attributes and the relationships to return, separated by commas. Each entity declares its attributes and its relationships in its own schema.
Show object format **`fieldset`** - Type: string - Example: `"title,hint,collapsible,item_type"` Attributes and relationships to return for each `fieldset` that this endpoint returns.
## Returns Returns an array of resource objects of type [fieldset](/docs/content-management-api/resources/fieldset.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const modelIdOrApiKey = "blog_post"; const fieldsets = await client.fieldsets.list(modelIdOrApiKey); for (const fieldset of fieldsets) { // Check the 'Returned output' tab for the result ☝️ console.log(fieldset); } } run(); ``` Returned output ```javascript { id: "93Y1C2sySkG4Eg0atBRIwg", title: "SEO-related fields", hint: "Please fill in these fields!", position: 1, collapsible: true, start_collapsed: false, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, } ``` --- # Content Management API — Retrieve a fieldset Source [docs]: https://www.datocms.com/docs/content-management-api/resources/fieldset/self.md ## Query parameters **`fields`** - Type: object Sparse fieldsets: for each entity type, the attributes and the relationships to return, separated by commas. Each entity declares its attributes and its relationships in its own schema.
Show object format **`fieldset`** - Type: string - Example: `"title,hint,collapsible,item_type"` Attributes and relationships to return for each `fieldset` that this endpoint returns.
## Returns Returns a resource object of type [fieldset](/docs/content-management-api/resources/fieldset.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const fieldsetId = "93Y1C2sySkG4Eg0atBRIwg"; const fieldset = await client.fieldsets.find(fieldsetId); // Check the 'Returned output' tab for the result ☝️ console.log(fieldset); } run(); ``` Returned output ```javascript { id: "93Y1C2sySkG4Eg0atBRIwg", title: "SEO-related fields", hint: "Please fill in these fields!", position: 1, collapsible: true, start_collapsed: false, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, } ``` --- # Content Management API — Delete a fieldset Source [docs]: https://www.datocms.com/docs/content-management-api/resources/fieldset/destroy.md ## Returns Returns a resource object of type [fieldset](/docs/content-management-api/resources/fieldset.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const fieldsetId = "93Y1C2sySkG4Eg0atBRIwg"; const fieldset = await client.fieldsets.destroy(fieldsetId); // Check the 'Returned output' tab for the result ☝️ console.log(fieldset); } run(); ``` Returned output ```javascript { id: "93Y1C2sySkG4Eg0atBRIwg", title: "SEO-related fields", hint: "Please fill in these fields!", position: 1, collapsible: true, start_collapsed: false, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, } ``` --- # Content Management API — Record version Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item-version.md Every change to a record is stored as a separate record version in DatoCMS. ## Object payload **`id`** - Type: string - Example: `"59JSonvYTCOUDz_b7_6hvA"` RFC 4122 UUID of redord version expressed in URL-safe base64 format **`type`** - Type: string Must be exactly `"item_version"`. **`meta.created_at`** - Type: date-time Date of record version creation **`meta.is_published`** - Type: boolean Whether the record version is the published version or not **`meta.published_from`** - Type: date-time, null Date this version became the published version of the record, or `null` if it has never been published. May also be `null` for versions that were published before publication-history tracking was introduced; in that case, fall back to `is_published` to determine the live status. **`meta.published_until`** - Type: date-time, null Date this version stopped being the published version of the record (either replaced by a newer published version, or explicitly unpublished). `null` when the version is currently published or has never been published. **`meta.is_current`** - Type: boolean Whether the record version is the most recent version or not **`item_type`** - Type: [ResourceLinkage\<"item_type"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item_type.md) The record version's model **`item`** - Type: [ResourceLinkage\<"item"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item.md) The record this version belongs to **`editor`** - Type: [ResourceLinkage\<"account"\>](https://www-draft.datocms.com/docs/content-management-api/resources/account.md), [ResourceLinkage\<"access_token"\>](https://www-draft.datocms.com/docs/content-management-api/resources/access_token.md), [ResourceLinkage\<"user"\>](https://www-draft.datocms.com/docs/content-management-api/resources/user.md), [ResourceLinkage\<"sso_user"\>](https://www-draft.datocms.com/docs/content-management-api/resources/sso_user.md), [ResourceLinkage\<"organization"\>](https://www-draft.datocms.com/docs/content-management-api/resources/organization.md) The entity (account/collaborator/access token/sso user) who made this change to the record
Show deprecated **`meta.is_valid`** - Deprecated - Type: boolean Whether the record version is valid or not Validity of a version can only be established in the context of all the current or published item's versions (think about uniqueness validations, for example): use item's `is_current_version_valid` or `is_published_version_valid` fields instead.
--- # Content Management API — Restore an old record version Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item-version/restore.md ## Returns Returns an array of resource objects of type [item](/docs/content-management-api/resources/item.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemVersionId = "59JSonvYTCOUDz_b7_6hvA"; const itemVersion = await client.itemVersions.restore(itemVersionId); // Check the 'Returned output' tab for the result ☝️ console.log(itemVersion); } run(); ``` Returned output ```javascript { id: "hWl-mnkWRYmMCSTq4z_piQ", title: "My first blog post!", content: "Lorem ipsum dolor sit amet...", category: "24", image: { alt: "Alt text", title: "Image title", custom_data: {}, focal_point: null, upload_id: "20042921", }, meta: { created_at: "2020-04-21T07:57:11.124Z", updated_at: "2020-04-21T07:57:11.124Z", published_at: "2020-04-21T07:57:11.124Z", first_published_at: "2020-04-21T07:57:11.124Z", publication_scheduled_at: "2020-04-21T07:57:11.124Z", unpublishing_scheduled_at: "2020-04-21T07:57:11.124Z", status: "published", is_current_version_valid: true, is_published_version_valid: true, current_version: "4234", stage: null, has_children: true, }, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, } ``` --- # Content Management API — List all record versions Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item-version/instances.md ## Query parameters **`nested`** - Type: boolean For Modular Content, Structured Text and Single Block fields. If set, returns full payload for nested blocks instead of IDs **`page`** - Type: object Parameters to control offset-based pagination
Show object format **`offset`** - Type: integer - Example: `200` The (zero-based) offset of the first entity returned in the collection (defaults to 0) **`limit`** - Type: integer The maximum number of entities to return (defaults to 15, maximum is 50)
## Returns Returns an array of resource objects of type [item\_version](/docs/content-management-api/resources/item-version.md) ## Examples ###### Example Basic example ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemId = "59JSonvYTCOUDz_b7_6hvA"; // iterates over every page of results for await (const itemVersion of client.itemVersions.listPagedIterator( itemId, )) { // Check the 'Returned output' tab for the result ☝️ console.log(itemVersion); } } run(); ``` --- # Content Management API — Retrieve a record version Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item-version/self.md ## Query parameters **`nested`** - Type: boolean For Modular Content, Structured Text and Single Block fields, return full payload for nested blocks instead of IDs ## Returns Returns a resource object of type [item\_version](/docs/content-management-api/resources/item-version.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemVersionId = "59JSonvYTCOUDz_b7_6hvA"; const itemVersion = await client.itemVersions.find(itemVersionId); // Check the 'Returned output' tab for the result ☝️ console.log(itemVersion); } run(); ``` Returned output ```javascript { id: "59JSonvYTCOUDz_b7_6hvA", title: "My first blog post!", content: "Lorem ipsum dolor sit amet...", category: "24", image: { alt: "Alt text", title: "Image title", custom_data: {}, focal_point: null, upload_id: "20042921", }, meta: { created_at: "2020-04-21T07:57:11.124Z", is_published: true, published_from: "2020-04-21T07:57:11.124Z", published_until: "2020-04-21T07:57:11.124Z", is_current: true, }, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, item: { type: "item", id: "hWl-mnkWRYmMCSTq4z_piQ" }, editor: { type: "account", id: "312" }, } ``` --- # Content Management API — Upload permission Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-request.md To upload a file with the Content Management API, first you need to obtain an upload permission. The `upload_request` entity contains the S3-like URL where you will be able to upload the file with a raw/binary PUT request. ## Object payload **`id`** - Type: string - Example: `"/7/1455102967-image.png"` The S3 path where the file will be stored **`type`** - Type: string Must be exactly `"upload_request"`. **`url`** - Type: string - Example: `"https://dato-images.s3-eu-west-1.amazonaws.com/7/1455102967-image.png?X-Amz-Credential=AKIAJDTXTZHHDUCKAUMA%2F20160210"` The URL to use to upload the file with a raw/binary PUT request **`request_headers`** - Type: object Specifies the additional headers that need to be included in the direct PUT upload request --- # Content Management API — Request a new permission to upload a file Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-request/create.md ⚠️ **We highly advocate for [utilizing our JavaScript client when uploading new assets](/docs/content-management-api/resources/upload/create.md)**, as the `client.upload` resource comes equipped with high-level helper methods that handle all the nitty-gritty for you. This endpoint is required to acquire the S3-like URL where you can upload a file using a raw/binary PUT request. ## Body parameters **`filename`** - Optional - Type: string - Example: `"image.png"` The original file name **`upload_collection`** - Optional - Type: [ResourceLinkage\<"upload_collection"\>](https://www-draft.datocms.com/docs/content-management-api/resources/upload_collection.md), null Upload collection to which the asset belongs ## Returns Returns a resource object of type [upload\_request](/docs/content-management-api/resources/upload-request.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const uploadRequest = await client.uploadRequest.create({}); // Check the 'Returned output' tab for the result ☝️ console.log(uploadRequest); } run(); ``` Returned output ```javascript { id: "/7/1455102967-image.png", url: "https://dato-images.s3-eu-west-1.amazonaws.com/7/1455102967-image.png?X-Amz-Credential=AKIAJDTXTZHHDUCKAUMA%2F20160210", request_headers: {}, } ``` --- # Content Management API — Upload track Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-track.md If the asset linked to an Upload entity is a video file, you have the option to include additional audio tracks and subtitle tracks to it. ## Object payload **`id`** - Type: string - Example: `"xBe7u01029ipxBLQhYzZCJ1cke01zCkuUsgnYtH0017nNzbpv2YcsoMDmw"` ID of the upload track **`type`** - Type: enum - Example: `"subtitles"` The type of track (audio or subtitles)
Show enum values **`subtitles`** Subtitles **`audio`** Audio
**`name`** - Type: string - Example: `"Italiano"` The human-readable name of the track **`language_code`** - Type: string - Example: `"it-IT"` A valid BCP 47 specification compliant language code **`closed_captions`** - Type: null, boolean Indicates if the track provides subtitles for the Deaf or Hard-of-hearing (SDH) **`status`** - Type: enum - Example: `"ready"` The status of the asset
Show enum values **`preparing`** Preparing **`ready`** Ready **`errored`** Errored
**`error`** - Type: null, string When status is `errored`, explains the reason for the error **`upload`** - Type: [ResourceLinkage\<"upload"\>](https://www-draft.datocms.com/docs/content-management-api/resources/upload.md) The upload containing the track --- # Content Management API — Create a new upload track Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-track/create.md ## Body parameters **`url_or_upload_request_id`** - Required - Type: string - Example: `"/7/1455102967-image.png"` Either an URL to download, or the ID of an upload request **`type`** - Required - Type: enum - Example: `"subtitles"` The type of track (audio or subtitles)
Show enum values **`subtitles`** - Optional Subtitles **`audio`** - Optional Audio
**`language_code`** - Required - Type: string - Example: `"it-IT"` A valid BCP 47 specification compliant language code **`name`** - Optional - Type: string - Example: `"Italiano"` The human-readable name of the track **`closed_captions`** - Optional - Type: null, boolean Indicates if the track provides subtitles for the Deaf or Hard-of-hearing (SDH) ## Returns Returns a resource object of type [upload\_track](/docs/content-management-api/resources/upload-track.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const uploadId = "xBe7u01029ipxBLQhYzZCJ1cke01zCkuUsgnYtH0017nNzbpv2YcsoMDmw"; const uploadTrack = await client.uploadTracks.create(uploadId, { url_or_upload_request_id: "/7/1455102967-image.png", type: "subtitles", language_code: "it-IT", }); // Check the 'Returned output' tab for the result ☝️ console.log(uploadTrack); } run(); ``` Returned output ```javascript { id: "xBe7u01029ipxBLQhYzZCJ1cke01zCkuUsgnYtH0017nNzbpv2YcsoMDmw", type: "subtitles", name: "Italiano", language_code: "it-IT", closed_captions: false, status: "ready", error: null, upload: { type: "upload", id: "q0VNpiNQSkG6z0lif_O1zg" }, } ``` --- # Content Management API — List upload tracks Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-track/instances.md ## Returns Returns an array of resource objects of type [upload\_track](/docs/content-management-api/resources/upload-track.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const uploadId = "xBe7u01029ipxBLQhYzZCJ1cke01zCkuUsgnYtH0017nNzbpv2YcsoMDmw"; const uploadTracks = await client.uploadTracks.list(uploadId); for (const uploadTrack of uploadTracks) { // Check the 'Returned output' tab for the result ☝️ console.log(uploadTrack); } } run(); ``` Returned output ```javascript { id: "xBe7u01029ipxBLQhYzZCJ1cke01zCkuUsgnYtH0017nNzbpv2YcsoMDmw", type: "subtitles", name: "Italiano", language_code: "it-IT", closed_captions: false, status: "ready", error: null, upload: { type: "upload", id: "q0VNpiNQSkG6z0lif_O1zg" }, } ``` --- # Content Management API — Delete an upload track Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-track/destroy.md ## Returns Returns a resource object of type [upload\_track](/docs/content-management-api/resources/upload-track.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const uploadId = "xBe7u01029ipxBLQhYzZCJ1cke01zCkuUsgnYtH0017nNzbpv2YcsoMDmw"; const uploadTrackId = "xBe7u01029ipxBLQhYzZCJ1cke01zCkuUsgnYtH0017nNzbpv2YcsoMDmw"; const uploadTrack = await client.uploadTracks.destroy( uploadId, uploadTrackId, ); // Check the 'Returned output' tab for the result ☝️ console.log(uploadTrack); } run(); ``` Returned output ```javascript { id: "xBe7u01029ipxBLQhYzZCJ1cke01zCkuUsgnYtH0017nNzbpv2YcsoMDmw", type: "subtitles", name: "Italiano", language_code: "it-IT", closed_captions: false, status: "ready", error: null, upload: { type: "upload", id: "q0VNpiNQSkG6z0lif_O1zg" }, } ``` --- # Content Management API — Manual tags Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-tag.md All the project's upload tags ## Object payload **`id`** - Type: string - Example: `"42"` ID of upload tag **`type`** - Type: string Must be exactly `"upload_tag"`. **`name`** - Type: string - Example: `"Pictures of me"` The tag name --- # Content Management API — List all manually created upload tags Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-tag/instances.md The results are sorted by name and paginated by default. ## Query parameters **`filter`** - Type: object Attributes to filter tags
Show object format **`query`** - Type: string - Example: `"foobar"` Textual query to match.
**`page`** - Type: object Parameters to control offset-based pagination
Show object format **`offset`** - Type: integer - Example: `200` The (zero-based) offset of the first entity returned in the collection (defaults to 0) **`limit`** - Type: integer The maximum number of entities to return (defaults to 50, maximum is 500)
## Returns Returns an array of resource objects of type [upload\_tag](/docs/content-management-api/resources/upload-tag.md) ## Examples ###### Example Basic example ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // iterates over every page of results for await (const uploadTag of client.uploadTags.listPagedIterator()) { // Check the 'Returned output' tab for the result ☝️ console.log(uploadTag); } } run(); ``` --- # Content Management API — Create a new upload tag Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-tag/create.md ## Body parameters **`name`** - Required - Type: string - Example: `"Pictures of me"` The tag name ## Returns Returns a resource object of type [upload\_tag](/docs/content-management-api/resources/upload-tag.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const uploadTag = await client.uploadTags.create({ name: "Pictures of me" }); // Check the 'Returned output' tab for the result ☝️ console.log(uploadTag); } run(); ``` Returned output ```javascript { id: "42", name: "Pictures of me" } ``` --- # Content Management API — Smart tags Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-smart-tag.md All the site's upload automatically generated tags ## Object payload **`id`** - Type: string - Example: `"42"` ID of upload tag **`type`** - Type: string Must be exactly `"upload_smart_tag"`. **`name`** - Type: string - Example: `"building"` The tag name --- # Content Management API — List all automatically created upload tags Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-smart-tag/instances.md The results are sorted by name and paginated by default. ## Query parameters **`filter`** - Type: object Attributes to filter tags
Show object format **`query`** - Type: string - Example: `"foobar"` Textual query to match.
**`page`** - Type: object Parameters to control offset-based pagination
Show object format **`offset`** - Type: integer - Example: `200` The (zero-based) offset of the first entity returned in the collection (defaults to 0) **`limit`** - Type: integer The maximum number of entities to return (defaults to 50, maximum is 500)
## Returns Returns an array of resource objects of type [upload\_smart\_tag](/docs/content-management-api/resources/upload-smart-tag.md) ## Examples ###### Example Basic example ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // iterates over every page of results for await (const uploadSmartTag of client.uploadSmartTags.listPagedIterator()) { // Check the 'Returned output' tab for the result ☝️ console.log(uploadSmartTag); } } run(); ``` --- # Content Management API — Upload Collection Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-collection.md In DatoCMS you can organize the uploads present in your administrative area in collection, so that the final editors can easily navigate uploads. ## Object payload **`id`** - Type: string - Example: `"uinr2zfqQLeCo_1O0-ao-Q"` RFC 4122 UUID of upload collection expressed in URL-safe base64 format **`type`** - Type: string Must be exactly `"upload_collection"`. JSON API type field **`label`** - Type: string - Example: `"Posts"` The label of the upload collection **`position`** - Type: integer - Example: `1` Ordering index **`parent`** - Type: null, [ResourceLinkage\<"upload_collection"\>](https://www-draft.datocms.com/docs/content-management-api/resources/upload_collection.md) Parent upload collection **`children`** - Type: Array<[ResourceLinkage\<"upload_collection"\>](https://www-draft.datocms.com/docs/content-management-api/resources/upload_collection.md)> Underlying upload collections --- # Content Management API — Create a new upload collection Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-collection/create.md ## Body parameters **`id`** - Optional - Type: string - Example: `"uinr2zfqQLeCo_1O0-ao-Q"` RFC 4122 UUID of upload collection expressed in URL-safe base64 format **`label`** - Required - Type: string - Example: `"Posts"` The label of the upload collection **`position`** - Optional - Type: integer - Example: `1` Ordering index **`parent`** - Optional - Type: null, [ResourceLinkage\<"upload_collection"\>](https://www-draft.datocms.com/docs/content-management-api/resources/upload_collection.md) Parent upload collection ## Returns Returns a resource object of type [upload\_collection](/docs/content-management-api/resources/upload-collection.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const uploadCollection = await client.uploadCollections.create({ label: "Posts", }); // Check the 'Returned output' tab for the result ☝️ console.log(uploadCollection); } run(); ``` Returned output ```javascript { id: "uinr2zfqQLeCo_1O0-ao-Q", label: "Posts", position: 1, parent: null, children: [{ type: "upload_collection", id: "uinr2zfqQLeCo_1O0-ao-Q" }], } ``` --- # Content Management API — Update a upload collection Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-collection/update.md ## Body parameters **`label`** - Optional - Type: string - Example: `"Posts"` The label of the upload collection **`position`** - Optional - Type: integer - Example: `1` Ordering index **`parent`** - Optional - Type: null, [ResourceLinkage\<"upload_collection"\>](https://www-draft.datocms.com/docs/content-management-api/resources/upload_collection.md) Parent upload collection **`children`** - Optional - Type: Array<[ResourceLinkage\<"upload_collection"\>](https://www-draft.datocms.com/docs/content-management-api/resources/upload_collection.md)> Underlying upload collections ## Returns Returns a resource object of type [upload\_collection](/docs/content-management-api/resources/upload-collection.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const uploadCollectionId = "uinr2zfqQLeCo_1O0-ao-Q"; const uploadCollection = await client.uploadCollections.update( uploadCollectionId, { id: "uinr2zfqQLeCo_1O0-ao-Q" }, ); // Check the 'Returned output' tab for the result ☝️ console.log(uploadCollection); } run(); ``` Returned output ```javascript { id: "uinr2zfqQLeCo_1O0-ao-Q", label: "Posts", position: 1, parent: null, children: [{ type: "upload_collection", id: "uinr2zfqQLeCo_1O0-ao-Q" }], } ``` --- # Content Management API — List all upload collections Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-collection/instances.md ## Query parameters **`filter`** - Type: object
Show object format **`ids`** - Type: string - Example: `"42,554"` IDs to fetch, comma separated
## Returns Returns an array of resource objects of type [upload\_collection](/docs/content-management-api/resources/upload-collection.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const uploadCollections = await client.uploadCollections.list(); for (const uploadCollection of uploadCollections) { // Check the 'Returned output' tab for the result ☝️ console.log(uploadCollection); } } run(); ``` Returned output ```javascript { id: "uinr2zfqQLeCo_1O0-ao-Q", label: "Posts", position: 1, parent: null, children: [{ type: "upload_collection", id: "uinr2zfqQLeCo_1O0-ao-Q" }], } ``` --- # Content Management API — Retrieve a upload collection Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-collection/self.md ## Returns Returns a resource object of type [upload\_collection](/docs/content-management-api/resources/upload-collection.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const uploadCollectionId = "uinr2zfqQLeCo_1O0-ao-Q"; const uploadCollection = await client.uploadCollections.find(uploadCollectionId); // Check the 'Returned output' tab for the result ☝️ console.log(uploadCollection); } run(); ``` Returned output ```javascript { id: "uinr2zfqQLeCo_1O0-ao-Q", label: "Posts", position: 1, parent: null, children: [{ type: "upload_collection", id: "uinr2zfqQLeCo_1O0-ao-Q" }], } ``` --- # Content Management API — Delete a upload collection Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-collection/destroy.md ## Returns Returns a resource object of type [upload\_collection](/docs/content-management-api/resources/upload-collection.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const uploadCollectionId = "uinr2zfqQLeCo_1O0-ao-Q"; const uploadCollection = await client.uploadCollections.destroy(uploadCollectionId); // Check the 'Returned output' tab for the result ☝️ console.log(uploadCollection); } run(); ``` Returned output ```javascript { id: "uinr2zfqQLeCo_1O0-ao-Q", label: "Posts", position: 1, parent: null, children: [{ type: "upload_collection", id: "uinr2zfqQLeCo_1O0-ao-Q" }], } ``` --- # Content Management API — Search Index Source [docs]: https://www.datocms.com/docs/content-management-api/resources/search-index.md A Search Index is used to index a website to provide DatoCMS Site Search functionality. ## Object payload **`id`** - Type: string - Example: `"1822"` ID of search_index **`type`** - Type: string Must be exactly `"search_index"`. **`name`** - Type: string - Example: `"Production Website"` Name of the search index **`enabled`** - Type: boolean Whether the search index is enabled or not **`frontend_url`** - Type: string, null - Example: `"https://www.mywebsite.com/"` The public URL of the website. This is the starting point from which the website's spidering will start **`user_agent_suffix`** - Type: string, null - Example: `"v1.0.0"` Optional suffix to append to the DatoCmsSearchBot user agent when indexing the website **`meta.indexing_status`** - Type: enum - Example: `"success"` Status of the search indexing
Show enum values **`unstarted`** **`pending`** **`success`** **`failed`**
**`meta.last_indexing_completed_at`** - Type: date-time, null - Example: `"2025-03-30T09:29:14.872Z"` Timestamp of the last completed indexing **`build_triggers`** - Type: Array<[ResourceLinkage\<"build_trigger"\>](https://www-draft.datocms.com/docs/content-management-api/resources/build_trigger.md)> The build triggers that can trigger this search index --- # Content Management API — List all search indexes for a site Source [docs]: https://www.datocms.com/docs/content-management-api/resources/search-index/instances.md ## Returns Returns an array of resource objects of type [search\_index](/docs/content-management-api/resources/search-index.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const searchIndexs = await client.searchIndexes.list(); for (const searchIndex of searchIndexs) { // Check the 'Returned output' tab for the result ☝️ console.log(searchIndex); } } run(); ``` Returned output ```javascript { id: "1822", name: "Production Website", enabled: true, frontend_url: "https://www.mywebsite.com/", user_agent_suffix: "v1.0.0", meta: { indexing_status: "success", last_indexing_completed_at: "2025-03-30T09:29:14.872Z", }, build_triggers: [{ type: "build_trigger", id: "1822" }], } ``` --- # Content Management API — Retrieve a search index Source [docs]: https://www.datocms.com/docs/content-management-api/resources/search-index/self.md ## Returns Returns a resource object of type [search\_index](/docs/content-management-api/resources/search-index.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const searchIndexId = "1822"; const searchIndex = await client.searchIndexes.find(searchIndexId); // Check the 'Returned output' tab for the result ☝️ console.log(searchIndex); } run(); ``` Returned output ```javascript { id: "1822", name: "Production Website", enabled: true, frontend_url: "https://www.mywebsite.com/", user_agent_suffix: "v1.0.0", meta: { indexing_status: "success", last_indexing_completed_at: "2025-03-30T09:29:14.872Z", }, build_triggers: [{ type: "build_trigger", id: "1822" }], } ``` --- # Content Management API — Create a search index Source [docs]: https://www.datocms.com/docs/content-management-api/resources/search-index/create.md ## Body parameters **`name`** - Required - Type: string - Example: `"Production Website"` Name of the search index **`enabled`** - Required - Type: boolean Whether the search index is enabled or not **`frontend_url`** - Required - Type: string, null - Example: `"https://www.mywebsite.com/"` The public URL of the website. This is the starting point from which the website's spidering will start **`user_agent_suffix`** - Optional - Type: string, null - Example: `"v1.0.0"` Optional suffix to append to the DatoCmsSearchBot user agent when indexing the website **`build_triggers`** - Optional - Type: Array<[ResourceLinkage\<"build_trigger"\>](https://www-draft.datocms.com/docs/content-management-api/resources/build_trigger.md)> The build triggers that can trigger this search index ## Returns Returns a resource object of type [search\_index](/docs/content-management-api/resources/search-index.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const searchIndex = await client.searchIndexes.create({ name: "Production Website", enabled: true, frontend_url: "https://www.mywebsite.com/", }); // Check the 'Returned output' tab for the result ☝️ console.log(searchIndex); } run(); ``` Returned output ```javascript { id: "1822", name: "Production Website", enabled: true, frontend_url: "https://www.mywebsite.com/", user_agent_suffix: "v1.0.0", meta: { indexing_status: "success", last_indexing_completed_at: "2025-03-30T09:29:14.872Z", }, build_triggers: [{ type: "build_trigger", id: "1822" }], } ``` --- # Content Management API — Update a search index Source [docs]: https://www.datocms.com/docs/content-management-api/resources/search-index/update.md ## Body parameters **`name`** - Optional - Type: string - Example: `"Production Website"` Name of the search index **`enabled`** - Optional - Type: boolean Whether the search index is enabled or not **`frontend_url`** - Optional - Type: string, null - Example: `"https://www.mywebsite.com/"` The public URL of the website. This is the starting point from which the website's spidering will start **`user_agent_suffix`** - Optional - Type: string, null - Example: `"v1.0.0"` Optional suffix to append to the DatoCmsSearchBot user agent when indexing the website **`build_triggers`** - Optional - Type: Array<[ResourceLinkage\<"build_trigger"\>](https://www-draft.datocms.com/docs/content-management-api/resources/build_trigger.md)> The build triggers that can trigger this search index ## Returns Returns a resource object of type [search\_index](/docs/content-management-api/resources/search-index.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const searchIndexId = "1822"; const searchIndex = await client.searchIndexes.update(searchIndexId, { id: "1822", }); // Check the 'Returned output' tab for the result ☝️ console.log(searchIndex); } run(); ``` Returned output ```javascript { id: "1822", name: "Production Website", enabled: true, frontend_url: "https://www.mywebsite.com/", user_agent_suffix: "v1.0.0", meta: { indexing_status: "success", last_indexing_completed_at: "2025-03-30T09:29:14.872Z", }, build_triggers: [{ type: "build_trigger", id: "1822" }], } ``` --- # Content Management API — Trigger the indexing process Source [docs]: https://www.datocms.com/docs/content-management-api/resources/search-index/trigger.md Manually trigger a spidering of the website to update the search index ## Examples ###### Example Basic example ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const searchIndexId = "1822"; await client.searchIndexes.trigger(searchIndexId); } run(); ``` --- # Content Management API — Abort a the current indexing process and mark it as failed Source [docs]: https://www.datocms.com/docs/content-management-api/resources/search-index/abort.md ## Examples ###### Example Basic example ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const searchIndexId = "1822"; await client.searchIndexes.abort(searchIndexId); } run(); ``` --- # Content Management API — Delete a search index Source [docs]: https://www.datocms.com/docs/content-management-api/resources/search-index/destroy.md ## Returns Returns a resource object of type [search\_index](/docs/content-management-api/resources/search-index.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const searchIndexId = "1822"; const searchIndex = await client.searchIndexes.destroy(searchIndexId); // Check the 'Returned output' tab for the result ☝️ console.log(searchIndex); } run(); ``` Returned output ```javascript { id: "1822", name: "Production Website", enabled: true, frontend_url: "https://www.mywebsite.com/", user_agent_suffix: "v1.0.0", meta: { indexing_status: "success", last_indexing_completed_at: "2025-03-30T09:29:14.872Z", }, build_triggers: [{ type: "build_trigger", id: "1822" }], } ``` --- # Content Management API — Search result Source [docs]: https://www.datocms.com/docs/content-management-api/resources/search-result.md DatoCMS Site Search is a way to deliver tailored search results to your site visitors. This is the endpoint you can use to query for results. ## Object payload **`id`** - Type: string - Example: `"12adNIIB8rFJF1DoTgCk"` ID of result **`type`** - Type: string Must be exactly `"search_result"`. **`title`** - Type: string - Example: `"Florence Apartments for Rent | Long Term Student Accommodation Rentals"` Title of the page **`body_excerpt`** - Type: string - Example: `"Finding a place to live while planning to study abroad in Florence can be both exciting and challenging. With this in mind, Housing in Florence assists you in finding conveniently-located housing based..."` First 200 characters of page body, unformatted **`url`** - Type: string - Example: `"http://www.website.com/some-page"` URL **`score`** - Type: number - Example: `11.3` Search score **`highlight`** - Type: object
Show object format **`title`** - Type: Array\, null **`body`** - Type: Array\, null
--- # Content Management API — Search for results Source [docs]: https://www.datocms.com/docs/content-management-api/resources/search-result/instances.md Returns a list of search results matching your query. By default, it returns 20 results. You can paginate the results using `limit` and `offset` parameters. In any case, a maximum number of 100 results is returned. ## Query parameters **`filter`** - Type: object Attributes to filter search results
Show object format **`query`** - Type: string - Example: `"florence apartments"` Text to search **`fuzzy`** - Type: boolean When any value is passed, it enables the fuzzy search: the Levenshtein Edit Distance is used to match more results. **`search_index_id`** - Type: string - Example: `"12345"` The search index ID on which the search will be performed. If not provided, the first enabled search index will be used. **`locale`** - Type: string - Example: `"it"` Restrict the search on pages in a specific locale
Show deprecated **`build_trigger_id`** - Deprecated - Type: string - Example: `"44"` The build trigger ID or name on which the search will be performed. Use `search_index_id` instead: this parameter is only supported for backward compatibility and will return an error if the build trigger has multiple search indexes associated.
**`page`** - Type: object Parameters to control offset-based pagination
Show object format **`offset`** - Type: integer - Example: `200` The (zero-based) offset of the first entity returned in the collection (defaults to 0) **`limit`** - Type: integer The maximum number of entities to return (defaults to 20, maximum is 100)
## Returns Returns an array of resource objects of type [search\_result](/docs/content-management-api/resources/search-result.md) ## Examples ###### Example Basic example ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // iterates over every page of results for await (const searchResult of client.searchResults.listPagedIterator({ filter: { query: "florence apartments" }, })) { // Check the 'Returned output' tab for the result ☝️ console.log(searchResult); } } run(); ``` --- # Content Management API — Search indexing activity Source [docs]: https://www.datocms.com/docs/content-management-api/resources/search-index-event.md Represents an event occurred during the indexing process via search indexes. ## Object payload **`id`** - Type: string - Example: `"34"` ID of search index event **`type`** - Type: string Must be exactly `"search_index_event"`. **`event_type`** - Type: enum - Example: `"indexing_success"` The type of activity
Show enum values **`indexing_started`** Site indexing started **`indexing_success`** Site indexing completed successfully **`indexing_failure`** Site indexing failed **`indexing_aborted`** Site indexing aborted by user
**`data`** - Type: object Any details regarding the event Example: ```json { pages: [ "https://www.example.com/ (language: en)", "https://www.example.com/about (language: en)", ], } ``` **`created_at`** - Type: date-time - Example: `"2016-09-20T18:50:24.914Z"` The moment the activity occurred **`search_index`** - Type: [ResourceLinkage\<"search_index"\>](https://www-draft.datocms.com/docs/content-management-api/resources/search_index.md) Source search index --- # Content Management API — List all search indexing events Source [docs]: https://www.datocms.com/docs/content-management-api/resources/search-index-event/instances.md ## Query parameters **`page`** - Type: object Parameters to control offset-based pagination
Show object format **`offset`** - Type: integer The (zero-based) offset of the first entity returned in the collection (defaults to 0) **`limit`** - Type: integer The maximum number of entities to return (defaults to 30, maximum is 500)
**`filter`** - Type: object Attributes to filter
Show object format **`ids`** - Type: string - Example: `"42,554"` IDs to fetch, comma separated **`fields`** - Type: object
Show object format **`search_index_id`** - Type: object
Show object format **`eq`** - Type: string
**`event_type`** - Type: object
Show object format **`eq`** - Type: enum - Example: `"indexing_success"` The type of activity
Show enum values **`indexing_started`** Site indexing started **`indexing_success`** Site indexing completed successfully **`indexing_failure`** Site indexing failed **`indexing_aborted`** Site indexing aborted by user
**`created_at`** - Type: object
Show object format **`gt`** - Type: date-time **`lt`** - Type: date-time
**`order_by`** - Type: enum - Example: `"created_at_desc"` Fields used to order results
Show enum values **`search_index_id_asc`** **`search_index_id_desc`** **`created_at_asc`** **`created_at_desc`** **`event_type_asc`** **`event_type_desc`**
## Returns Returns an array of resource objects of type [search\_index\_event](/docs/content-management-api/resources/search-index-event.md) ## Examples ###### Example Basic example ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // iterates over every page of results for await (const searchIndexEvent of client.searchIndexEvents.listPagedIterator()) { // Check the 'Returned output' tab for the result ☝️ console.log(searchIndexEvent); } } run(); ``` --- # Content Management API — Retrieve a search indexing event Source [docs]: https://www.datocms.com/docs/content-management-api/resources/search-index-event/self.md ## Returns Returns a resource object of type [search\_index\_event](/docs/content-management-api/resources/search-index-event.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const searchIndexEventId = "34"; const searchIndexEvent = await client.searchIndexEvents.find(searchIndexEventId); // Check the 'Returned output' tab for the result ☝️ console.log(searchIndexEvent); } run(); ``` Returned output ```javascript { id: "34", event_type: "indexing_success", data: { pages: [ "https://www.example.com/ (language: en)", "https://www.example.com/about (language: en)", ], }, created_at: "2016-09-20T18:50:24.914Z", search_index: { type: "search_index", id: "1822" }, } ``` --- # Content Management API — Environment Source [docs]: https://www.datocms.com/docs/content-management-api/resources/environment.md [Environments](/docs/general-concepts/primary-and-sandbox-environments.md) make it easier for your development team to **manage and maintain content structure once your content has been published**. You can think of environments like code branches: great for testing, development and pre-production environments. By default, every project has one environment, called **primary environment**, which is meant to be used for the regular editorial workflow. Additionally, multiple **sandbox environments** can be created by developers to safely test/experiment new changes in the content. Sandbox environments start out as **exact copies of one of the existing environments** (ie. the primary one). The process of creating a new sandbox starting off from an existing environment is called fork. Each environment is identified by a name (ie. `master`) and stores the following information: - Models - Records - Uploads - Plugins - Locales and timezone settings - UI Theme (colors and logo) - Global SEO settings - The content navigation bar When making changes to any of the aforementioned entities in any environment, including the primary environment, **the data in all other environments isn’t affected** and stays the same. ## Object payload **`id`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`type`** - Type: string Must be exactly `"environment"`. **`meta.status`** - Type: enum - Example: `"ready"` Status of the environment
Show enum values **`creating`** The environment is being forked **`ready`** The environment is ready **`destroying`** The environment is being destroyed
**`meta.fork_completion_percentage`** - Type: number - Example: `95` The completion percentage of the fork operation (only present if the status is `creating`) **`meta.read_only_mode`** - Type: boolean Is this environment the in read-only mode because of a fast-fork? **`meta.created_at`** - Type: date-time Date of creation **`meta.last_data_change_at`** - Type: date-time Last data change **`meta.primary`** - Type: boolean Is this environment the primary for the project? **`meta.forked_from`** - Type: string, null - Example: `"main"` ID of the environment that's been forked to generate this one --- # Content Management API — Fork an existing environment Source [docs]: https://www.datocms.com/docs/content-management-api/resources/environment/fork.md ## Query parameters **`immediate_return`** - Type: boolean Whether the call should immediately return a pending environment, or wait for the completion of the fork **`fast`** - Type: boolean Performing a fast fork reduces processing time, but it also prevents writing to the source environment during the process **`force`** - Type: boolean Force the start of fast fork, even if there are collaborators editing some records ## Body parameters **`id`** - Required - Type: string - Example: `"my-sandbox-env"` The ID of the forked environment ## Returns Returns a resource object of type [environment](/docs/content-management-api/resources/environment.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const environmentId = "main"; const environment = await client.environments.fork(environmentId, {}); // Check the 'Returned output' tab for the result ☝️ console.log(environment); } run(); ``` Returned output ```javascript { id: "main", meta: { status: "ready", created_at: "2020-04-21T07:57:11.124Z", read_only_mode: true, last_data_change_at: "2020-04-21T07:57:11.124Z", primary: true, forked_from: "main", }, } ``` --- # Content Management API — Promote an environment to primary Source [docs]: https://www.datocms.com/docs/content-management-api/resources/environment/promote.md ## Returns Returns a resource object of type [environment](/docs/content-management-api/resources/environment.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const environmentId = "main"; const environment = await client.environments.promote(environmentId); // Check the 'Returned output' tab for the result ☝️ console.log(environment); } run(); ``` Returned output ```javascript { id: "main", meta: { status: "ready", created_at: "2020-04-21T07:57:11.124Z", read_only_mode: true, last_data_change_at: "2020-04-21T07:57:11.124Z", primary: true, forked_from: "main", }, } ``` --- # Content Management API — Rename an environment Source [docs]: https://www.datocms.com/docs/content-management-api/resources/environment/rename.md ## Body parameters ## Returns Returns a resource object of type [environment](/docs/content-management-api/resources/environment.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const environmentId = "main"; const environment = await client.environments.rename(environmentId, { id: "renamed-sandbox", }); // Check the 'Returned output' tab for the result ☝️ console.log(environment); } run(); ``` Returned output ```javascript { id: "main", meta: { status: "ready", created_at: "2020-04-21T07:57:11.124Z", read_only_mode: true, last_data_change_at: "2020-04-21T07:57:11.124Z", primary: true, forked_from: "main", }, } ``` --- # Content Management API — List all environments Source [docs]: https://www.datocms.com/docs/content-management-api/resources/environment/instances.md ## Returns Returns an array of resource objects of type [environment](/docs/content-management-api/resources/environment.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const environments = await client.environments.list(); for (const environment of environments) { // Check the 'Returned output' tab for the result ☝️ console.log(environment); } } run(); ``` Returned output ```javascript { id: "main", meta: { status: "ready", created_at: "2020-04-21T07:57:11.124Z", read_only_mode: true, last_data_change_at: "2020-04-21T07:57:11.124Z", primary: true, forked_from: "main", }, } ``` --- # Content Management API — Retrieve a environment Source [docs]: https://www.datocms.com/docs/content-management-api/resources/environment/self.md ## Returns Returns a resource object of type [environment](/docs/content-management-api/resources/environment.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const environmentId = "main"; const environment = await client.environments.find(environmentId); // Check the 'Returned output' tab for the result ☝️ console.log(environment); } run(); ``` Returned output ```javascript { id: "main", meta: { status: "ready", created_at: "2020-04-21T07:57:11.124Z", read_only_mode: true, last_data_change_at: "2020-04-21T07:57:11.124Z", primary: true, forked_from: "main", }, } ``` --- # Content Management API — Delete a environment Source [docs]: https://www.datocms.com/docs/content-management-api/resources/environment/destroy.md ## Returns Returns a resource object of type [environment](/docs/content-management-api/resources/environment.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const environmentId = "main"; const environment = await client.environments.destroy(environmentId); // Check the 'Returned output' tab for the result ☝️ console.log(environment); } run(); ``` Returned output ```javascript { id: "main", meta: { status: "ready", created_at: "2020-04-21T07:57:11.124Z", read_only_mode: true, last_data_change_at: "2020-04-21T07:57:11.124Z", primary: true, forked_from: "main", }, } ``` --- # Content Management API — Maintenance mode Source [docs]: https://www.datocms.com/docs/content-management-api/resources/maintenance-mode.md ## Object payload **`id`** - Type: string - Example: `"maintenance_mode"` ID of maintenance_mode **`type`** - Type: string Must be exactly `"maintenance_mode"`. **`active`** - Type: boolean Whether maintenance mode is currently active or not --- # Content Management API — Retrieve maintenence mode Source [docs]: https://www.datocms.com/docs/content-management-api/resources/maintenance-mode/self.md ## Returns Returns a resource object of type [maintenance\_mode](/docs/content-management-api/resources/maintenance-mode.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const maintenanceMode = await client.maintenanceMode.find(); // Check the 'Returned output' tab for the result ☝️ console.log(maintenanceMode); } run(); ``` Returned output ```javascript { id: "maintenance_mode", active: false } ``` --- # Content Management API — Activate maintenance mode: this means that the primary environment will be read-only Source [docs]: https://www.datocms.com/docs/content-management-api/resources/maintenance-mode/activate.md ## Query parameters **`force`** - Type: boolean Force the activation, even if there are collaborators editing some records. ## Returns Returns a resource object of type [maintenance\_mode](/docs/content-management-api/resources/maintenance-mode.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const maintenanceMode = await client.maintenanceMode.activate(); // Check the 'Returned output' tab for the result ☝️ console.log(maintenanceMode); } run(); ``` Returned output ```javascript { id: "maintenance_mode", active: false } ``` --- # Content Management API — De-activate maintenance mode Source [docs]: https://www.datocms.com/docs/content-management-api/resources/maintenance-mode/deactivate.md ## Returns Returns a resource object of type [maintenance\_mode](/docs/content-management-api/resources/maintenance-mode.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const maintenanceMode = await client.maintenanceMode.deactivate(); // Check the 'Returned output' tab for the result ☝️ console.log(maintenanceMode); } run(); ``` Returned output ```javascript { id: "maintenance_mode", active: false } ``` --- # Content Management API — Menu Item Source [docs]: https://www.datocms.com/docs/content-management-api/resources/menu-item.md In DatoCMS you can organize the different Models present in your administrative area reordering and grouping them, so that their purpose will be more clear to the final editor. ## Object payload **`id`** - Type: string - Example: `"uinr2zfqQLeCo_1O0-ao-Q"` RFC 4122 UUID of menu item expressed in URL-safe base64 format **`type`** - Type: string Must be exactly `"menu_item"`. **`label`** - Type: string - Example: `"Posts"` The label of the menu item **`position`** - Type: integer - Example: `1` Ordering index **`external_url`** - Type: null, string The URL to which the menu item points to **`open_in_new_tab`** - Type: boolean Opens link in new tab (to be used together with `external_url`) **`item_type`** - Type: [ResourceLinkage\<"item_type"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item_type.md), null Item type associated with the menu item **`item_type_filter`** - Type: [ResourceLinkage\<"item_type_filter"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item_type_filter.md), null Item type filter associated with the menu item (to be used together with `item_type` relationship) **`parent`** - Type: null, [ResourceLinkage\<"menu_item"\>](https://www-draft.datocms.com/docs/content-management-api/resources/menu_item.md) Parent menu item **`children`** - Type: Array<[ResourceLinkage\<"menu_item"\>](https://www-draft.datocms.com/docs/content-management-api/resources/menu_item.md)> Underlying menu items --- # Content Management API — Create a new menu item Source [docs]: https://www.datocms.com/docs/content-management-api/resources/menu-item/create.md ## Body parameters **`id`** - Optional - Type: string - Example: `"uinr2zfqQLeCo_1O0-ao-Q"` RFC 4122 UUID of menu item expressed in URL-safe base64 format **`label`** - Required - Type: string - Example: `"Posts"` The label of the menu item **`external_url`** - Optional - Type: null, string The URL to which the menu item points to **`position`** - Optional - Type: integer - Example: `1` Ordering index **`open_in_new_tab`** - Optional - Type: boolean Opens link in new tab (to be used together with `external_url`) **`item_type`** - Optional - Type: [ResourceLinkage\<"item_type"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item_type.md), null Item type associated with the menu item **`item_type_filter`** - Optional - Type: [ResourceLinkage\<"item_type_filter"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item_type_filter.md), null Item type filter associated with the menu item (to be used together with `item_type` relationship) **`parent`** - Optional - Type: null, [ResourceLinkage\<"menu_item"\>](https://www-draft.datocms.com/docs/content-management-api/resources/menu_item.md) Parent menu item ## Returns Returns a resource object of type [menu\_item](/docs/content-management-api/resources/menu-item.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const menuItem = await client.menuItems.create({ label: "Posts" }); // Check the 'Returned output' tab for the result ☝️ console.log(menuItem); } run(); ``` Returned output ```javascript { id: "uinr2zfqQLeCo_1O0-ao-Q", label: "Posts", position: 1, external_url: "", open_in_new_tab: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, item_type_filter: { type: "item_type_filter", id: "FF-P5of6Qp-DD2w0xoaa6Q" }, parent: null, children: [{ type: "menu_item", id: "uinr2zfqQLeCo_1O0-ao-Q" }], } ``` --- # Content Management API — Update a menu item Source [docs]: https://www.datocms.com/docs/content-management-api/resources/menu-item/update.md ## Body parameters **`label`** - Optional - Type: string - Example: `"Posts"` The label of the menu item **`external_url`** - Optional - Type: null, string The URL to which the menu item points to **`position`** - Optional - Type: integer - Example: `1` Ordering index **`open_in_new_tab`** - Optional - Type: boolean Opens link in new tab (to be used together with `external_url`) **`item_type`** - Optional - Type: [ResourceLinkage\<"item_type"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item_type.md), null Item type associated with the menu item **`item_type_filter`** - Optional - Type: [ResourceLinkage\<"item_type_filter"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item_type_filter.md), null Item type filter associated with the menu item (to be used together with `item_type` relationship) **`parent`** - Optional - Type: null, [ResourceLinkage\<"menu_item"\>](https://www-draft.datocms.com/docs/content-management-api/resources/menu_item.md) Parent menu item ## Returns Returns a resource object of type [menu\_item](/docs/content-management-api/resources/menu-item.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const menuItemId = "uinr2zfqQLeCo_1O0-ao-Q"; const menuItem = await client.menuItems.update(menuItemId, { id: "uinr2zfqQLeCo_1O0-ao-Q", }); // Check the 'Returned output' tab for the result ☝️ console.log(menuItem); } run(); ``` Returned output ```javascript { id: "uinr2zfqQLeCo_1O0-ao-Q", label: "Posts", position: 1, external_url: "", open_in_new_tab: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, item_type_filter: { type: "item_type_filter", id: "FF-P5of6Qp-DD2w0xoaa6Q" }, parent: null, children: [{ type: "menu_item", id: "uinr2zfqQLeCo_1O0-ao-Q" }], } ``` --- # Content Management API — List all menu items Source [docs]: https://www.datocms.com/docs/content-management-api/resources/menu-item/instances.md ## Query parameters **`filter`** - Type: object
Show object format **`ids`** - Type: string - Example: `"42,554"` IDs to fetch, comma separated
## Returns Returns an array of resource objects of type [menu\_item](/docs/content-management-api/resources/menu-item.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const menuItems = await client.menuItems.list(); for (const menuItem of menuItems) { // Check the 'Returned output' tab for the result ☝️ console.log(menuItem); } } run(); ``` Returned output ```javascript { id: "uinr2zfqQLeCo_1O0-ao-Q", label: "Posts", position: 1, external_url: "", open_in_new_tab: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, item_type_filter: { type: "item_type_filter", id: "FF-P5of6Qp-DD2w0xoaa6Q" }, parent: null, children: [{ type: "menu_item", id: "uinr2zfqQLeCo_1O0-ao-Q" }], } ``` --- # Content Management API — Retrieve a menu item Source [docs]: https://www.datocms.com/docs/content-management-api/resources/menu-item/self.md ## Returns Returns a resource object of type [menu\_item](/docs/content-management-api/resources/menu-item.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const menuItemId = "uinr2zfqQLeCo_1O0-ao-Q"; const menuItem = await client.menuItems.find(menuItemId); // Check the 'Returned output' tab for the result ☝️ console.log(menuItem); } run(); ``` Returned output ```javascript { id: "uinr2zfqQLeCo_1O0-ao-Q", label: "Posts", position: 1, external_url: "", open_in_new_tab: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, item_type_filter: { type: "item_type_filter", id: "FF-P5of6Qp-DD2w0xoaa6Q" }, parent: null, children: [{ type: "menu_item", id: "uinr2zfqQLeCo_1O0-ao-Q" }], } ``` --- # Content Management API — Delete a menu item Source [docs]: https://www.datocms.com/docs/content-management-api/resources/menu-item/destroy.md ## Returns Returns a resource object of type [menu\_item](/docs/content-management-api/resources/menu-item.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const menuItemId = "uinr2zfqQLeCo_1O0-ao-Q"; const menuItem = await client.menuItems.destroy(menuItemId); // Check the 'Returned output' tab for the result ☝️ console.log(menuItem); } run(); ``` Returned output ```javascript { id: "uinr2zfqQLeCo_1O0-ao-Q", label: "Posts", position: 1, external_url: "", open_in_new_tab: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, item_type_filter: { type: "item_type_filter", id: "FF-P5of6Qp-DD2w0xoaa6Q" }, parent: null, children: [{ type: "menu_item", id: "uinr2zfqQLeCo_1O0-ao-Q" }], } ``` --- # Content Management API — Schema Menu Item Source [docs]: https://www.datocms.com/docs/content-management-api/resources/schema-menu-item.md In DatoCMS you can organize the different models and blocks present in your administrative area reordering and grouping them, so that their purpose will be more clear to the final editor. ## Object payload **`id`** - Type: string - Example: `"uinr2zfqQLeCo_1O0-ao-Q"` RFC 4122 UUID of schema menu item expressed in URL-safe base64 format **`type`** - Type: string Must be exactly `"schema_menu_item"`. JSON API type field **`label`** - Type: null, string - Example: `"Posts"` The label of the schema menu item (only present when the schema menu item is not linked to an item type) **`position`** - Type: integer - Example: `1` Ordering index **`kind`** - Type: enum - Example: `"item_type"` Indicates if the schema menu item refers to an item type or a modular block
Show enum values **`item_type`** **`modular_block`**
**`item_type`** - Type: [ResourceLinkage\<"item_type"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item_type.md), null Item type associated with the schema menu item **`parent`** - Type: null, [ResourceLinkage\<"schema_menu_item"\>](https://www-draft.datocms.com/docs/content-management-api/resources/schema_menu_item.md) Parent schema menu item **`children`** - Type: Array<[ResourceLinkage\<"schema_menu_item"\>](https://www-draft.datocms.com/docs/content-management-api/resources/schema_menu_item.md)> Underlying schema menu items --- # Content Management API — Create a new schema menu item Source [docs]: https://www.datocms.com/docs/content-management-api/resources/schema-menu-item/create.md ## Body parameters **`id`** - Optional - Type: string - Example: `"uinr2zfqQLeCo_1O0-ao-Q"` RFC 4122 UUID of schema menu item expressed in URL-safe base64 format **`label`** - Required - Type: null, string - Example: `"Posts"` The label of the schema menu item (only present when the schema menu item is not linked to an item type) **`kind`** - Required - Type: enum - Example: `"item_type"` Indicates if the schema menu item refers to an item type or a modular block
Show enum values **`item_type`** - Optional **`modular_block`** - Optional
**`position`** - Optional - Type: integer - Example: `1` Ordering index **`item_type`** - Optional - Type: [ResourceLinkage\<"item_type"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item_type.md), null Item type associated with the menu item **`parent`** - Optional - Type: null, [ResourceLinkage\<"schema_menu_item"\>](https://www-draft.datocms.com/docs/content-management-api/resources/schema_menu_item.md) Parent schema menu item ## Returns Returns a resource object of type [schema\_menu\_item](/docs/content-management-api/resources/schema-menu-item.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const schemaMenuItem = await client.schemaMenuItems.create({ label: "Posts", kind: "item_type", }); // Check the 'Returned output' tab for the result ☝️ console.log(schemaMenuItem); } run(); ``` Returned output ```javascript { id: "uinr2zfqQLeCo_1O0-ao-Q", label: "Posts", position: 1, kind: "item_type", item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, parent: null, children: [{ type: "schema_menu_item", id: "uinr2zfqQLeCo_1O0-ao-Q" }], } ``` --- # Content Management API — Update a schema menu item Source [docs]: https://www.datocms.com/docs/content-management-api/resources/schema-menu-item/update.md ## Body parameters **`label`** - Optional - Type: null, string - Example: `"Posts"` The label of the schema menu item (only present when the schema menu item is not linked to an item type) **`position`** - Optional - Type: integer - Example: `1` Ordering index **`kind`** - Optional - Type: enum - Example: `"item_type"` Indicates if the schema menu item refers to an item type or a modular block
Show enum values **`item_type`** - Optional **`modular_block`** - Optional
**`item_type`** - Optional - Type: [ResourceLinkage\<"item_type"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item_type.md), null Item type associated with the menu item **`parent`** - Optional - Type: null, [ResourceLinkage\<"schema_menu_item"\>](https://www-draft.datocms.com/docs/content-management-api/resources/schema_menu_item.md) Parent schema menu item **`children`** - Optional - Type: Array<[ResourceLinkage\<"schema_menu_item"\>](https://www-draft.datocms.com/docs/content-management-api/resources/schema_menu_item.md)> Underlying schema menu items ## Returns Returns a resource object of type [schema\_menu\_item](/docs/content-management-api/resources/schema-menu-item.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const schemaMenuItemId = "uinr2zfqQLeCo_1O0-ao-Q"; const schemaMenuItem = await client.schemaMenuItems.update(schemaMenuItemId, { id: "uinr2zfqQLeCo_1O0-ao-Q", }); // Check the 'Returned output' tab for the result ☝️ console.log(schemaMenuItem); } run(); ``` Returned output ```javascript { id: "uinr2zfqQLeCo_1O0-ao-Q", label: "Posts", position: 1, kind: "item_type", item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, parent: null, children: [{ type: "schema_menu_item", id: "uinr2zfqQLeCo_1O0-ao-Q" }], } ``` --- # Content Management API — List all schema menu items Source [docs]: https://www.datocms.com/docs/content-management-api/resources/schema-menu-item/instances.md ## Query parameters **`filter`** - Type: object
Show object format **`ids`** - Type: string - Example: `"42,554"` IDs to fetch, comma separated
## Returns Returns an array of resource objects of type [schema\_menu\_item](/docs/content-management-api/resources/schema-menu-item.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const schemaMenuItems = await client.schemaMenuItems.list(); for (const schemaMenuItem of schemaMenuItems) { // Check the 'Returned output' tab for the result ☝️ console.log(schemaMenuItem); } } run(); ``` Returned output ```javascript { id: "uinr2zfqQLeCo_1O0-ao-Q", label: "Posts", position: 1, kind: "item_type", item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, parent: null, children: [{ type: "schema_menu_item", id: "uinr2zfqQLeCo_1O0-ao-Q" }], } ``` --- # Content Management API — Retrieve a schema menu item Source [docs]: https://www.datocms.com/docs/content-management-api/resources/schema-menu-item/self.md ## Returns Returns a resource object of type [schema\_menu\_item](/docs/content-management-api/resources/schema-menu-item.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const schemaMenuItemId = "uinr2zfqQLeCo_1O0-ao-Q"; const schemaMenuItem = await client.schemaMenuItems.find(schemaMenuItemId); // Check the 'Returned output' tab for the result ☝️ console.log(schemaMenuItem); } run(); ``` Returned output ```javascript { id: "uinr2zfqQLeCo_1O0-ao-Q", label: "Posts", position: 1, kind: "item_type", item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, parent: null, children: [{ type: "schema_menu_item", id: "uinr2zfqQLeCo_1O0-ao-Q" }], } ``` --- # Content Management API — Delete a schema menu item Source [docs]: https://www.datocms.com/docs/content-management-api/resources/schema-menu-item/destroy.md ## Returns Returns a resource object of type [schema\_menu\_item](/docs/content-management-api/resources/schema-menu-item.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const schemaMenuItemId = "uinr2zfqQLeCo_1O0-ao-Q"; const schemaMenuItem = await client.schemaMenuItems.destroy(schemaMenuItemId); // Check the 'Returned output' tab for the result ☝️ console.log(schemaMenuItem); } run(); ``` Returned output ```javascript { id: "uinr2zfqQLeCo_1O0-ao-Q", label: "Posts", position: 1, kind: "item_type", item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, parent: null, children: [{ type: "schema_menu_item", id: "uinr2zfqQLeCo_1O0-ao-Q" }], } ``` --- # Content Management API — Uploads filter Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-filter.md In DatoCMS you can create filters to help you (and other editors) quickly search for uploads ## Object payload **`id`** - Type: string - Example: `"-Lo34LFSTLmgPToamzJLcg"` RFC 4122 UUID of upload filter expressed in URL-safe base64 format **`type`** - Type: string Must be exactly `"upload_filter"`. **`name`** - Type: string - Example: `"Draft posts"` The name of the filter **`filter`** - Type: object - Example: `{ status: { eq: "draft" } }` The actual filter **`shared`** - Type: boolean Whether it's a shared filter or not --- # Content Management API — Create a new filter Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-filter/create.md ## Body parameters **`id`** - Optional - Type: string - Example: `"-Lo34LFSTLmgPToamzJLcg"` RFC 4122 UUID of upload filter expressed in URL-safe base64 format **`name`** - Required - Type: string - Example: `"Draft posts"` The name of the filter **`filter`** - Required - Type: object - Example: `{ status: { eq: "draft" } }` The actual filter **`shared`** - Required - Type: boolean Whether it's a shared filter or not ## Returns Returns a resource object of type [upload\_filter](/docs/content-management-api/resources/upload-filter.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const uploadFilter = await client.uploadFilters.create({ name: "Draft posts", filter: { status: { eq: "draft" } }, shared: true, }); // Check the 'Returned output' tab for the result ☝️ console.log(uploadFilter); } run(); ``` Returned output ```javascript { id: "-Lo34LFSTLmgPToamzJLcg", name: "Draft posts", filter: { status: { eq: "draft" } }, shared: true, } ``` --- # Content Management API — Update a filter Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-filter/update.md ## Body parameters **`name`** - Required - Type: string - Example: `"Draft posts"` The name of the filter **`filter`** - Required - Type: object - Example: `{ status: { eq: "draft" } }` The actual filter **`shared`** - Optional - Type: boolean Whether it's a shared filter or not ## Returns Returns a resource object of type [upload\_filter](/docs/content-management-api/resources/upload-filter.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const uploadFilterId = "-Lo34LFSTLmgPToamzJLcg"; const uploadFilter = await client.uploadFilters.update(uploadFilterId, { id: "-Lo34LFSTLmgPToamzJLcg", name: "Draft posts", filter: { status: { eq: "draft" } }, }); // Check the 'Returned output' tab for the result ☝️ console.log(uploadFilter); } run(); ``` Returned output ```javascript { id: "-Lo34LFSTLmgPToamzJLcg", name: "Draft posts", filter: { status: { eq: "draft" } }, shared: true, } ``` --- # Content Management API — List all filters Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-filter/instances.md ## Returns Returns an array of resource objects of type [upload\_filter](/docs/content-management-api/resources/upload-filter.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const uploadFilters = await client.uploadFilters.list(); for (const uploadFilter of uploadFilters) { // Check the 'Returned output' tab for the result ☝️ console.log(uploadFilter); } } run(); ``` Returned output ```javascript { id: "-Lo34LFSTLmgPToamzJLcg", name: "Draft posts", filter: { status: { eq: "draft" } }, shared: true, } ``` --- # Content Management API — Retrieve a filter Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-filter/self.md ## Returns Returns a resource object of type [upload\_filter](/docs/content-management-api/resources/upload-filter.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const uploadFilterId = "-Lo34LFSTLmgPToamzJLcg"; const uploadFilter = await client.uploadFilters.find(uploadFilterId); // Check the 'Returned output' tab for the result ☝️ console.log(uploadFilter); } run(); ``` Returned output ```javascript { id: "-Lo34LFSTLmgPToamzJLcg", name: "Draft posts", filter: { status: { eq: "draft" } }, shared: true, } ``` --- # Content Management API — Delete a filter Source [docs]: https://www.datocms.com/docs/content-management-api/resources/upload-filter/destroy.md ## Returns Returns a resource object of type [upload\_filter](/docs/content-management-api/resources/upload-filter.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const uploadFilterId = "-Lo34LFSTLmgPToamzJLcg"; const uploadFilter = await client.uploadFilters.destroy(uploadFilterId); // Check the 'Returned output' tab for the result ☝️ console.log(uploadFilter); } run(); ``` Returned output ```javascript { id: "-Lo34LFSTLmgPToamzJLcg", name: "Draft posts", filter: { status: { eq: "draft" } }, shared: true, } ``` --- # Content Management API — Model filter Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item-type-filter.md In DatoCMS you can create filters to help you (and other editors) quickly search for records ## Object payload **`id`** - Type: string - Example: `"FF-P5of6Qp-DD2w0xoaa6Q"` RFC 4122 UUID of filter expressed in URL-safe base64 format **`type`** - Type: string Must be exactly `"item_type_filter"`. **`name`** - Type: string - Example: `"Draft posts"` The name of the filter **`filter`** - Type: object The actual filter. It follows the form of the `filter` query parameter of the [List all records](https://www.datocms.com/docs/content-management-api/resources/item/instances) endpoint. Example: ```json { query: "foo bar", fields: { _status: { eq: "draft" }, title: { matches: { pattern: "qux", case_sensitive: "false", regexp: "false" }, }, }, } ``` **`columns`** - Type: Array\, null The columns to show with this filter Example: ```json [ { name: "_preview", width: 0.6 }, { name: "slug", width: 0.1 }, { name: "_status", width: 0.1 }, { name: "_updated_at", width: 0.2 }, ] ```
Show objects format inside array **`name`** - Type: string Can be either the API key of a model's field, or one of the following meta columns: `id`, `_preview`, `_updated_at`, `_created_at`, `_creator`, `_status`, `_published_at`, `_first_published_at`, `_publication_scheduled_at`, `_unpublishing_scheduled_at`, `position` (only for sortable models), `_stage (only for models associated with a workflow). **`width`** - Type: number The percentage width for the column (float, from 0 to 1.0)
**`order_by`** - Type: string, null - Example: `"_updated_at_ASC"` The ordering to apply with this filter, or `null` for the default model ordering. It follows the form of the `order_by` query parameter of the [List all records](https://www.datocms.com/docs/content-management-api/resources/item/instances) endpoint. **`shared`** - Type: boolean Whether it's a shared filter or not **`item_type`** - Type: [ResourceLinkage\<"item_type"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item_type.md) Model associated with the filter --- # Content Management API — Create a new filter Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item-type-filter/create.md ## Body parameters **`id`** - Optional - Type: string - Example: `"FF-P5of6Qp-DD2w0xoaa6Q"` RFC 4122 UUID of filter expressed in URL-safe base64 format **`name`** - Required - Type: string - Example: `"Draft posts"` The name of the filter **`filter`** - Optional - Type: object The actual filter. It follows the form of the `filter` query parameter of the [List all records](https://www.datocms.com/docs/content-management-api/resources/item/instances) endpoint. Example: ```json { query: "foo bar", fields: { _status: { eq: "draft" }, title: { matches: { pattern: "qux", case_sensitive: "false", regexp: "false" }, }, }, } ``` **`columns`** - Optional - Type: Array\, null The columns to show with this filter Example: ```json [ { name: "_preview", width: 0.6 }, { name: "slug", width: 0.1 }, { name: "_status", width: 0.1 }, { name: "_updated_at", width: 0.2 }, ] ```
Show objects format inside array **`name`** - Required - Type: string Can be either the API key of a model's field, or one of the following meta columns: `id`, `_preview`, `_updated_at`, `_created_at`, `_creator`, `_status`, `_published_at`, `_first_published_at`, `_publication_scheduled_at`, `_unpublishing_scheduled_at`, `position` (only for sortable models), `_stage (only for models associated with a workflow). **`width`** - Required - Type: number The percentage width for the column (float, from 0 to 1.0)
**`order_by`** - Optional - Type: string, null - Example: `"_updated_at_ASC"` The ordering to apply with this filter, or `null` for the default model ordering. It follows the form of the `order_by` query parameter of the [List all records](https://www.datocms.com/docs/content-management-api/resources/item/instances) endpoint. **`shared`** - Optional - Type: boolean Whether it's a shared filter or not **`item_type`** - Required - Type: [ResourceLinkage\<"item_type"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item_type.md) Model associated with the filter ## Returns Returns a resource object of type [item\_type\_filter](/docs/content-management-api/resources/item-type-filter.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemTypeFilter = await client.itemTypeFilters.create({ name: "Draft posts", item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, }); // Check the 'Returned output' tab for the result ☝️ console.log(itemTypeFilter); } run(); ``` Returned output ```javascript { id: "FF-P5of6Qp-DD2w0xoaa6Q", name: "Draft posts", filter: { query: "foo bar", fields: { _status: { eq: "draft" }, title: { matches: { pattern: "qux", case_sensitive: "false", regexp: "false" }, }, }, }, columns: [ { name: "_preview", width: 0.6 }, { name: "slug", width: 0.1 }, { name: "_status", width: 0.1 }, { name: "_updated_at", width: 0.2 }, ], order_by: "_updated_at_ASC", shared: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, } ``` --- # Content Management API — Update a filter Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item-type-filter/update.md ## Body parameters **`name`** - Optional - Type: string - Example: `"Draft posts"` The name of the filter **`columns`** - Optional - Type: Array\, null The columns to show with this filter Example: ```json [ { name: "_preview", width: 0.6 }, { name: "slug", width: 0.1 }, { name: "_status", width: 0.1 }, { name: "_updated_at", width: 0.2 }, ] ```
Show objects format inside array **`name`** - Required - Type: string Can be either the API key of a model's field, or one of the following meta columns: `id`, `_preview`, `_updated_at`, `_created_at`, `_creator`, `_status`, `_published_at`, `_first_published_at`, `_publication_scheduled_at`, `_unpublishing_scheduled_at`, `position` (only for sortable models), `_stage (only for models associated with a workflow). **`width`** - Required - Type: number The percentage width for the column (float, from 0 to 1.0)
**`order_by`** - Optional - Type: string, null - Example: `"_updated_at_ASC"` The ordering to apply with this filter, or `null` for the default model ordering. It follows the form of the `order_by` query parameter of the [List all records](https://www.datocms.com/docs/content-management-api/resources/item/instances) endpoint. **`shared`** - Optional - Type: boolean Whether it's a shared filter or not **`filter`** - Optional - Type: object The actual filter. It follows the form of the `filter` query parameter of the [List all records](https://www.datocms.com/docs/content-management-api/resources/item/instances) endpoint. Example: ```json { query: "foo bar", fields: { _status: { eq: "draft" }, title: { matches: { pattern: "qux", case_sensitive: "false", regexp: "false" }, }, }, } ``` **`item_type`** - Optional - Type: [ResourceLinkage\<"item_type"\>](https://www-draft.datocms.com/docs/content-management-api/resources/item_type.md) Model associated with the filter ## Returns Returns a resource object of type [item\_type\_filter](/docs/content-management-api/resources/item-type-filter.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemTypeFilterId = "FF-P5of6Qp-DD2w0xoaa6Q"; const itemTypeFilter = await client.itemTypeFilters.update(itemTypeFilterId, { id: "FF-P5of6Qp-DD2w0xoaa6Q", }); // Check the 'Returned output' tab for the result ☝️ console.log(itemTypeFilter); } run(); ``` Returned output ```javascript { id: "FF-P5of6Qp-DD2w0xoaa6Q", name: "Draft posts", filter: { query: "foo bar", fields: { _status: { eq: "draft" }, title: { matches: { pattern: "qux", case_sensitive: "false", regexp: "false" }, }, }, }, columns: [ { name: "_preview", width: 0.6 }, { name: "slug", width: 0.1 }, { name: "_status", width: 0.1 }, { name: "_updated_at", width: 0.2 }, ], order_by: "_updated_at_ASC", shared: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, } ``` --- # Content Management API — List all filters Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item-type-filter/instances.md ## Returns Returns an array of resource objects of type [item\_type\_filter](/docs/content-management-api/resources/item-type-filter.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemTypeFilters = await client.itemTypeFilters.list(); for (const itemTypeFilter of itemTypeFilters) { // Check the 'Returned output' tab for the result ☝️ console.log(itemTypeFilter); } } run(); ``` Returned output ```javascript { id: "FF-P5of6Qp-DD2w0xoaa6Q", name: "Draft posts", filter: { query: "foo bar", fields: { _status: { eq: "draft" }, title: { matches: { pattern: "qux", case_sensitive: "false", regexp: "false" }, }, }, }, columns: [ { name: "_preview", width: 0.6 }, { name: "slug", width: 0.1 }, { name: "_status", width: 0.1 }, { name: "_updated_at", width: 0.2 }, ], order_by: "_updated_at_ASC", shared: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, } ``` --- # Content Management API — Retrieve a filter Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item-type-filter/self.md ## Returns Returns a resource object of type [item\_type\_filter](/docs/content-management-api/resources/item-type-filter.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemTypeFilterId = "FF-P5of6Qp-DD2w0xoaa6Q"; const itemTypeFilter = await client.itemTypeFilters.find(itemTypeFilterId); // Check the 'Returned output' tab for the result ☝️ console.log(itemTypeFilter); } run(); ``` Returned output ```javascript { id: "FF-P5of6Qp-DD2w0xoaa6Q", name: "Draft posts", filter: { query: "foo bar", fields: { _status: { eq: "draft" }, title: { matches: { pattern: "qux", case_sensitive: "false", regexp: "false" }, }, }, }, columns: [ { name: "_preview", width: 0.6 }, { name: "slug", width: 0.1 }, { name: "_status", width: 0.1 }, { name: "_updated_at", width: 0.2 }, ], order_by: "_updated_at_ASC", shared: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, } ``` --- # Content Management API — Delete a filter Source [docs]: https://www.datocms.com/docs/content-management-api/resources/item-type-filter/destroy.md ## Returns Returns a resource object of type [item\_type\_filter](/docs/content-management-api/resources/item-type-filter.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const itemTypeFilterId = "FF-P5of6Qp-DD2w0xoaa6Q"; const itemTypeFilter = await client.itemTypeFilters.destroy(itemTypeFilterId); // Check the 'Returned output' tab for the result ☝️ console.log(itemTypeFilter); } run(); ``` Returned output ```javascript { id: "FF-P5of6Qp-DD2w0xoaa6Q", name: "Draft posts", filter: { query: "foo bar", fields: { _status: { eq: "draft" }, title: { matches: { pattern: "qux", case_sensitive: "false", regexp: "false" }, }, }, }, columns: [ { name: "_preview", width: 0.6 }, { name: "slug", width: 0.1 }, { name: "_status", width: 0.1 }, { name: "_updated_at", width: 0.2 }, ], order_by: "_updated_at_ASC", shared: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, } ``` --- # Content Management API — Plugin Source [docs]: https://www.datocms.com/docs/content-management-api/resources/plugin.md Plugins enable developers to replace DatoCMS field components with HTML5 applications so the editing experiences of the DatoCMS web app can be customized. ## Object payload **`id`** - Type: string - Example: `"RMAMRffBRlmBuDlQsIWZ0g"` RFC 4122 UUID of plugin expressed in URL-safe base64 format **`type`** - Type: string Must be exactly `"plugin"`. **`name`** - Type: string - Example: `"5 stars"` The name of the plugin **`description`** - Type: null, string - Example: `"A better rating experience!"` A description of the plugin **`url`** - Type: string - Example: `"https://cdn.rawgit.com/datocms/extensions/master/samples/five-stars/extension.ts"` The entry point URL of the plugin **`parameters`** - Type: null, object - Example: `{ devMode: true }` Global plugin configuration. Plugins can persist whatever information they want in this object to reuse it later. Refer to the CMA for details about technical limits. It returns `null` if the credentials you are using cannot edit the schema of the project. **`package_name`** - Type: null, string - Example: `"datocms-plugin-star-rating-editor"` NPM package name of the plugin (or null if it's a private plugin) **`package_version`** - Type: null, string - Example: `"0.0.4"` The installed version of the plugin (or null if it's a private plugin) **`permissions`** - Type: Array\ Permissions granted to this plugin **`enabled`** - Type: boolean Whether the plugin is enabled or not. When disabled, the plugin behaves as if it didn't exist: fields using it as editor/addon fall back to the default editor, and any sidebar panel/page/config screen/asset source it registers does not render. **`meta.version`** - Type: string - Example: `"2"` Version of the plugin. Legacy plugins are v1, new plugins are v2
Show deprecated **`plugin_type`** - Deprecated - Type: null, enum The type of field extension a legacy plugin implements This field makes sense for legacy plugins only. Modern plugins declare their capabilities at run-time.
Show enum values **`field_editor`** Field editor plugin **`sidebar`** Sidebar plugin **`field_addon`** Field addon plugin
**`field_types`** - Deprecated - Type: null, Array\ On which types of field in which a legacy plugin can be used This field makes sense for legacy plugins only. Modern plugins declare their capabilities at run-time. **`parameter_definitions`** - Deprecated - Type: null, object The schema for the parameters a legacy plugin can persist This field makes sense for legacy plugins only. Modern plugins declare can store anything they want in the parameters attribute.
Show object format **`global`** - Type: Array **`instance`** - Type: Array
--- # Content Management API — Create a new plugin Source [docs]: https://www.datocms.com/docs/content-management-api/resources/plugin/create.md ## Body parameters **`id`** - Optional - Type: string - Example: `"RMAMRffBRlmBuDlQsIWZ0g"` RFC 4122 UUID of plugin expressed in URL-safe base64 format **`package_name`** - Optional - Type: null, string - Example: `"datocms-plugin-star-rating-editor"` NPM package name of the public plugin you want to install. For public plugins, that's the only attribute you need to pass. **`name`** - Optional - Type: string - Example: `"5 stars"` The name of the plugin. Only to be passed if package name key is not specified. **`description`** - Optional - Type: null, string - Example: `"A better rating experience!"` A description of the plugin. Only to be passed if package name key is not specified. **`url`** - Optional - Type: string - Example: `"https://cdn.rawgit.com/datocms/extensions/master/samples/five-stars/extension.ts"` The entry point URL of the plugin. Only to be passed if package name key is not specified. **`permissions`** - Optional - Type: Array\ Permissions granted to this plugin. Only to be passed if package name key is not specified. **`enabled`** - Optional - Type: boolean Whether the plugin is enabled or not. Defaults to `true`.
Show deprecated **`plugin_type`** - Deprecated - Type: enum - Example: `"field_editor"` The type of field extension this legacy plugin implements. Only to be passed if package name key is not specified. Pass this field only if you plan to create a legacy plugin. Modern plugins declare their capabilities at run-time.
Show enum values **`field_editor`** - Optional Field editor plugin **`sidebar`** - Optional Sidebar plugin **`field_addon`** - Optional Field addon plugin
**`field_types`** - Deprecated - Type: Array\ - Example: `["integer", "float"]` On which types of field in which this legacy plugin can be used. Only to be passed if package name key is not specified. Pass this field only if you plan to create a legacy plugin. Modern plugins declare their capabilities at run-time. **`parameter_definitions`** - Deprecated - Type: object The schema for the parameters this legacy plugin can persist This field makes sense for legacy plugins only. Modern plugins declare can store anything they want in the parameters attribute. Example: ```json { global: [ { id: "devMode", type: "boolean", label: "Run in development mode" }, ], instance: [ { id: "halfStars", type: "boolean", label: "Allow half stars ratings?", default: false, hint: "If enabled, rate using whole stars, if enabled, it doesn't use half-steps", }, { id: "totalStars", type: "integer", label: "Amount of stars to show", default: 5, hint: "", }, ], } ```
Show object format **`global`** - Required - Type: Array **`instance`** - Required - Type: Array
## Returns Returns a resource object of type [plugin](/docs/content-management-api/resources/plugin.md) ## Other examples ###### Example Installation of a public plugin from NPM Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const plugin = await client.plugins.create({ package_name: "datocms-plugin-star-rating-editor", }); console.log(plugin); } run(); ``` Returned output ```javascript const result = { type: "plugin", id: "124", name: "5 stars", description: "A better rating experience!", package_name: "datocms-plugin-star-rating-editor", package_version: "0.0.4", url: "https://cdn.rawgit.com/datocms/extensions/master/samples/five-stars/extension.js", permissions: ["currentUserAccessToken"], parameters: {}, }; ``` ###### Example Creation of a private plugin Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const plugin = await client.plugins.create({ name: "5 stars", description: "A better rating experience!", url: "https://cdn.rawgit.com/datocms/extensions/master/samples/five-stars/extension.js", permissions: ["currentUserAccessToken"], }); console.log(plugin); } run(); ``` Returned output ```javascript const result = { type: "plugin", id: "124", name: "5 stars", description: "A better rating experience!", url: "https://cdn.rawgit.com/datocms/extensions/master/samples/five-stars/extension.js", permissions: ["currentUserAccessToken"], parameters: {}, }; ``` --- # Content Management API — Update a plugin Source [docs]: https://www.datocms.com/docs/content-management-api/resources/plugin/update.md ## Body parameters **`name`** - Optional - Type: string - Example: `"5 stars"` The name of the plugin **`description`** - Optional - Type: null, string - Example: `"A better rating experience!"` A description of the plugin **`url`** - Optional - Type: string - Example: `"https://cdn.rawgit.com/datocms/extensions/master/samples/five-stars/extension.ts"` The entry point URL of the plugin **`package_name`** - Optional - Type: string - Example: `"datocms-plugin-star-rating-editor"` Turns a private plugin into a Marketplace plugin, installing the specified package from the DatoCMS Marketplace. Only accepted for private, non-legacy plugins, and cannot be combined with other attributes (except `enabled`). Name, description, URL, version and permissions are replaced with the ones published in the Marketplace, while the existing `parameters` are preserved. **`parameters`** - Optional - Type: object - Example: `{ devMode: true }` Global plugin configuration. Plugins can persist whatever information they want in this object to reuse it later. Refer to the CMA for details about technical limits. **`package_version`** - Optional - Type: null, string - Example: `"0.0.4"` The installed version of the plugin (or null if it's a private plugin) **`permissions`** - Optional - Type: Array\ Permissions granted to this plugin **`enabled`** - Optional - Type: boolean Whether the plugin is enabled or not. When disabled, the plugin behaves as if it didn't exist: fields using it as editor/addon fall back to the default editor, and any sidebar panel/page/config screen/asset source it registers does not render. ## Returns Returns a resource object of type [plugin](/docs/content-management-api/resources/plugin.md) ## Other examples ###### Example Update of plugin global parameters (both private and public) Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const pluginId = "124"; const plugin = await client.plugins.update(pluginId, { parameters: { foo: "bar" }, }); console.log(plugin); } run(); ``` Returned output ```javascript const result = { type: "plugin", id: "124", name: "5 stars", /* ... */ parameters: { foo: "bar" }, }; ``` ###### Example Upgrade of a public plugin Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const pluginId = "124"; const plugin = await client.plugins.update(pluginId, { package_version: "2.0.0", }); console.log(plugin); } run(); ``` Returned output ```javascript const result = { type: "plugin", id: "124", name: "5 stars", /* ... */ package_version: "2.0.0", }; ``` ###### Example Update of private plugin configuration Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const pluginId = "124"; const plugin = await client.plugins.update(pluginId, { name: "5 stars", description: "A better rating experience!", url: "https://cdn.rawgit.com/datocms/extensions/master/samples/five-stars/extension.js", permissions: ["currentUserAccessToken"], }); console.log(plugin); } run(); ``` Returned output ```javascript const result = { type: "plugin", id: "124", name: "5 stars", description: "A better rating experience!", package_name: null, package_version: null, url: "https://cdn.rawgit.com/datocms/extensions/master/samples/five-stars/extension.js", permissions: ["currentUserAccessToken"], parameters: { foo: "bar" }, }; ``` ###### Example Turning a private plugin into a Marketplace plugin Once a privately-hosted plugin gets published to the DatoCMS Marketplace, you can turn the private plugin into a Marketplace plugin. Its global parameters are preserved. Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const pluginId = "124"; const plugin = await client.plugins.update(pluginId, { package_name: "datocms-plugin-star-rating-editor", }); console.log(plugin); } run(); ``` Returned output ```javascript const result = { type: "plugin", id: "124", name: "Star rating", description: "A better rating experience!", package_name: "datocms-plugin-star-rating-editor", package_version: "0.0.4", url: "https://plugins-cdn.datocms.com/datocms-plugin-star-rating-editor@0.0.4/dist/index.html", permissions: [], parameters: { foo: "bar" }, enabled: true, }; ``` --- # Content Management API — List all plugins Source [docs]: https://www.datocms.com/docs/content-management-api/resources/plugin/instances.md ## Returns Returns an array of resource objects of type [plugin](/docs/content-management-api/resources/plugin.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const plugins = await client.plugins.list(); for (const plugin of plugins) { // Check the 'Returned output' tab for the result ☝️ console.log(plugin); } } run(); ``` Returned output ```javascript { id: "RMAMRffBRlmBuDlQsIWZ0g", name: "5 stars", description: "A better rating experience!", url: "https://cdn.rawgit.com/datocms/extensions/master/samples/five-stars/extension.ts", parameters: { devMode: true }, package_name: "datocms-plugin-star-rating-editor", package_version: "0.0.4", permissions: ["currentUserAccessToken"], enabled: true, meta: { version: "2" }, } ``` --- # Content Management API — Retrieve a plugin Source [docs]: https://www.datocms.com/docs/content-management-api/resources/plugin/self.md ## Returns Returns a resource object of type [plugin](/docs/content-management-api/resources/plugin.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const pluginId = "RMAMRffBRlmBuDlQsIWZ0g"; const plugin = await client.plugins.find(pluginId); // Check the 'Returned output' tab for the result ☝️ console.log(plugin); } run(); ``` Returned output ```javascript { id: "RMAMRffBRlmBuDlQsIWZ0g", name: "5 stars", description: "A better rating experience!", url: "https://cdn.rawgit.com/datocms/extensions/master/samples/five-stars/extension.ts", parameters: { devMode: true }, package_name: "datocms-plugin-star-rating-editor", package_version: "0.0.4", permissions: ["currentUserAccessToken"], enabled: true, meta: { version: "2" }, } ``` --- # Content Management API — Delete a plugin Source [docs]: https://www.datocms.com/docs/content-management-api/resources/plugin/destroy.md ## Returns Returns a resource object of type [plugin](/docs/content-management-api/resources/plugin.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const pluginId = "RMAMRffBRlmBuDlQsIWZ0g"; const plugin = await client.plugins.destroy(pluginId); // Check the 'Returned output' tab for the result ☝️ console.log(plugin); } run(); ``` Returned output ```javascript { id: "RMAMRffBRlmBuDlQsIWZ0g", name: "5 stars", description: "A better rating experience!", url: "https://cdn.rawgit.com/datocms/extensions/master/samples/five-stars/extension.ts", parameters: { devMode: true }, package_name: "datocms-plugin-star-rating-editor", package_version: "0.0.4", permissions: ["currentUserAccessToken"], enabled: true, meta: { version: "2" }, } ``` --- # Content Management API — Retrieve all fields using the plugin Source [docs]: https://www.datocms.com/docs/content-management-api/resources/plugin/fields.md ## Returns Returns an array of resource objects of type [field](/docs/content-management-api/resources/field.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const pluginId = "RMAMRffBRlmBuDlQsIWZ0g"; const plugins = await client.plugins.fields(pluginId); for (const plugin of plugins) { // Check the 'Returned output' tab for the result ☝️ console.log(plugin); } } run(); ``` Returned output ```javascript { id: "Pkg-oztERp6o-Rj76nYKJg", label: "Title", field_type: "string", api_key: "title", localized: true, validators: { required: {} }, position: 1, hint: "This field will be used as post title", default_value: { en: "A default value", it: "Un valore di default" }, appearance: { editor: "single_line", parameters: { heading: false }, addons: [{ id: "1234", field_extension: "lorem_ipsum", parameters: {} }], }, deep_filtering_enabled: true, content_link_enabled: true, item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, fieldset: null, } ``` --- # Content Management API — Workflow Source [docs]: https://www.datocms.com/docs/content-management-api/resources/workflow.md Through workflows it is possible to set up a precise state machine able to bring a draft content up to the final publication (and beyond), through a series of intermediate, fully customizable approval steps. ## Object payload **`id`** - Type: string - Example: `"uJzC2b6YQg-DW2A5edpQYQ"` RFC 4122 UUID of workflow expressed in URL-safe base64 format **`type`** - Type: string Must be exactly `"workflow"`. **`name`** - Type: string - Example: `"Approval by editors required"` The name of the workflow **`stages`** - Type: Array\ - Example: `[{ id: "waiting_for_review", name: "Waiting for review", initial: true }]` The stages of the workflow
Show objects format inside array **`id`** - Type: string - Example: `"waiting_for_review"` ID of the stage **`name`** - Type: string - Example: `"Waiting for review"` Name of the stage **`description`** - Type: string, null - Example: `"Editor has finished writing and is waiting for approval from a supervisor"` Description of the stage **`initial`** - Type: boolean Whether this is the initial stage or not
**`api_key`** - Type: string - Example: `"approval_by_editors"` Workflow API key --- # Content Management API — Create a new workflow Source [docs]: https://www.datocms.com/docs/content-management-api/resources/workflow/create.md ## Body parameters **`id`** - Optional - Type: string - Example: `"uJzC2b6YQg-DW2A5edpQYQ"` RFC 4122 UUID of workflow expressed in URL-safe base64 format **`name`** - Required - Type: string - Example: `"Approval by editors required"` The name of the workflow **`stages`** - Required - Type: Array\ - Example: `[{ id: "waiting_for_review", name: "Waiting for review", initial: true }]` The stages of the workflow
Show objects format inside array **`id`** - Required - Type: string - Example: `"waiting_for_review"` ID of the stage **`name`** - Required - Type: string - Example: `"Waiting for review"` Name of the stage **`description`** - Optional - Type: string, null - Example: `"Editor has finished writing and is waiting for approval from a supervisor"` Description of the stage **`initial`** - Optional - Type: boolean Whether this is the initial stage or not
**`api_key`** - Required - Type: string - Example: `"approval_by_editors"` Workflow API key ## Returns Returns a resource object of type [workflow](/docs/content-management-api/resources/workflow.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const workflow = await client.workflows.create({ name: "Approval by editors required", stages: [ { id: "waiting_for_review", name: "Waiting for review", initial: true }, ], api_key: "approval_by_editors", }); // Check the 'Returned output' tab for the result ☝️ console.log(workflow); } run(); ``` Returned output ```javascript { id: "uJzC2b6YQg-DW2A5edpQYQ", name: "Approval by editors required", stages: [ { id: "waiting_for_review", name: "Waiting for review", initial: true }, ], api_key: "approval_by_editors", } ``` --- # Content Management API — Update a workflow Source [docs]: https://www.datocms.com/docs/content-management-api/resources/workflow/update.md ## Body parameters **`name`** - Optional - Type: string - Example: `"Approval by editors required"` The name of the workflow **`api_key`** - Optional - Type: string - Example: `"approval_by_editors"` Workflow API key **`stages`** - Optional - Type: Array\ - Example: `[{ id: "waiting_for_review", name: "Waiting for review", initial: true }]` The stages of the workflow
Show objects format inside array **`id`** - Required - Type: string - Example: `"waiting_for_review"` ID of the stage **`name`** - Required - Type: string - Example: `"Waiting for review"` Name of the stage **`description`** - Optional - Type: string, null - Example: `"Editor has finished writing and is waiting for approval from a supervisor"` Description of the stage **`initial`** - Optional - Type: boolean Whether this is the initial stage or not
## Returns Returns a resource object of type [workflow](/docs/content-management-api/resources/workflow.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const workflowId = "uJzC2b6YQg-DW2A5edpQYQ"; const workflow = await client.workflows.update(workflowId, { id: "uJzC2b6YQg-DW2A5edpQYQ", }); // Check the 'Returned output' tab for the result ☝️ console.log(workflow); } run(); ``` Returned output ```javascript { id: "uJzC2b6YQg-DW2A5edpQYQ", name: "Approval by editors required", stages: [ { id: "waiting_for_review", name: "Waiting for review", initial: true }, ], api_key: "approval_by_editors", } ``` --- # Content Management API — List all workflows Source [docs]: https://www.datocms.com/docs/content-management-api/resources/workflow/instances.md ## Returns Returns an array of resource objects of type [workflow](/docs/content-management-api/resources/workflow.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const workflows = await client.workflows.list(); for (const workflow of workflows) { // Check the 'Returned output' tab for the result ☝️ console.log(workflow); } } run(); ``` Returned output ```javascript { id: "uJzC2b6YQg-DW2A5edpQYQ", name: "Approval by editors required", stages: [ { id: "waiting_for_review", name: "Waiting for review", initial: true }, ], api_key: "approval_by_editors", } ``` --- # Content Management API — Retrieve a workflow Source [docs]: https://www.datocms.com/docs/content-management-api/resources/workflow/self.md ## Returns Returns a resource object of type [workflow](/docs/content-management-api/resources/workflow.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const workflowId = "uJzC2b6YQg-DW2A5edpQYQ"; const workflow = await client.workflows.find(workflowId); // Check the 'Returned output' tab for the result ☝️ console.log(workflow); } run(); ``` Returned output ```javascript { id: "uJzC2b6YQg-DW2A5edpQYQ", name: "Approval by editors required", stages: [ { id: "waiting_for_review", name: "Waiting for review", initial: true }, ], api_key: "approval_by_editors", } ``` --- # Content Management API — Delete a workflow Source [docs]: https://www.datocms.com/docs/content-management-api/resources/workflow/destroy.md ## Examples ###### Example Basic example ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const workflowId = "uJzC2b6YQg-DW2A5edpQYQ"; await client.workflows.destroy(workflowId); } run(); ``` --- # Content Management API — Asynchronous job Source [docs]: https://www.datocms.com/docs/content-management-api/resources/job.md ## Object payload **`id`** - Type: string - Example: `"4235"` ID of job **`type`** - Type: string Must be exactly `"job"`. --- # Content Management API — Job result Source [docs]: https://www.datocms.com/docs/content-management-api/resources/job-result.md Some API endpoint give results asynchronously, returning the ID of a job. ## Object payload **`id`** - Type: string - Example: `"34"` ID of job result **`type`** - Type: string Must be exactly `"job_result"`. **`status`** - Type: integer - Example: `200` Status of delayed HTTP response **`payload`** - Type: null, object - Example: `{ data: { id: 999, type: "item_type", attributes: { some: "attributes" } } }` JSON API response of the HTTP request --- # Content Management API — Retrieve a job result Source [docs]: https://www.datocms.com/docs/content-management-api/resources/job-result/self.md ## Returns Returns a resource object of type [job\_result](/docs/content-management-api/resources/job-result.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const jobResultId = "34"; const jobResult = await client.jobResults.find(jobResultId); // Check the 'Returned output' tab for the result ☝️ console.log(jobResult); } run(); ``` Returned output ```javascript { id: "34", status: 200, payload: { data: { id: 999, type: "item_type", attributes: { some: "attributes" } }, }, } ``` --- # Content Management API — Account Source [docs]: https://www.datocms.com/docs/content-management-api/resources/account.md DatoCMS account ## Object payload **`id`** - Type: string - Example: `"312"` ID of account **`type`** - Type: string Must be exactly `"account"`. **`email`** - Type: string - Example: `"foo@bar.com"` Email **`first_name`** - Type: string, null - Example: `"Mark"` First name **`last_name`** - Type: string, null - Example: `"Smith"` Last name **`company`** - Type: string, null - Example: `"Dundler Mifflin"` Company name --- # Content Management API — Organization Source [docs]: https://www.datocms.com/docs/content-management-api/resources/organization.md DatoCMS organization ## Object payload **`id`** - Type: string - Example: `"312"` ID of organization **`type`** - Type: string Must be exactly `"organization"`. **`name`** - Type: string - Example: `"Acme Inc."` Name of the organization --- # Content Management API — Invitation Source [docs]: https://www.datocms.com/docs/content-management-api/resources/site-invitation.md A DatoCMS administrative area can be accessed by multiple people. Every invitation is linked to a specific Role, which describes what actions it will be able to perform once the user will register. ## Object payload **`id`** - Type: string - Example: `"312"` ID of invitation **`type`** - Type: string Must be exactly `"site_invitation"`. **`email`** - Type: string - Example: `"mark.smith@example.com"` Email **`expired`** - Type: boolean - Example: `"mark.smith@example.com"` Whether this invitation has expired **`invitation_link`** - Type: null, string - Example: `"https://dashboard.datocms.com/join-site?email=my-email%40datocms.comff&id=43796&preference=signup&token=xxx"` The link to join a DatoCMS project. Shown only on creation and reset **`role`** - Type: [ResourceLinkage\<"role"\>](https://www-draft.datocms.com/docs/content-management-api/resources/role.md) Role --- # Content Management API — Invite a new user Source [docs]: https://www.datocms.com/docs/content-management-api/resources/site-invitation/create.md ## Body parameters **`email`** - Required - Type: string - Example: `"mark.smith@example.com"` Email **`role`** - Required - Type: [ResourceLinkage\<"role"\>](https://www-draft.datocms.com/docs/content-management-api/resources/role.md) Role ## Returns Returns a resource object of type [site\_invitation](/docs/content-management-api/resources/site-invitation.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const siteInvitation = await client.siteInvitations.create({ email: "mark.smith@example.com", role: { type: "role", id: "34" }, }); // Check the 'Returned output' tab for the result ☝️ console.log(siteInvitation); } run(); ``` Returned output ```javascript { id: "312", email: "mark.smith@example.com", expired: "mark.smith@example.com", role: { type: "role", id: "34" }, } ``` --- # Content Management API — Update an invitation Source [docs]: https://www.datocms.com/docs/content-management-api/resources/site-invitation/update.md ## Body parameters **`role`** - Optional - Type: [ResourceLinkage\<"role"\>](https://www-draft.datocms.com/docs/content-management-api/resources/role.md) Role ## Returns Returns a resource object of type [site\_invitation](/docs/content-management-api/resources/site-invitation.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const siteInvitationId = "312"; const siteInvitation = await client.siteInvitations.update(siteInvitationId, { id: "312", }); // Check the 'Returned output' tab for the result ☝️ console.log(siteInvitation); } run(); ``` Returned output ```javascript { id: "312", email: "mark.smith@example.com", expired: "mark.smith@example.com", role: { type: "role", id: "34" }, } ``` --- # Content Management API — List all invitations Source [docs]: https://www.datocms.com/docs/content-management-api/resources/site-invitation/instances.md ## Returns Returns an array of resource objects of type [site\_invitation](/docs/content-management-api/resources/site-invitation.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const siteInvitations = await client.siteInvitations.list(); for (const siteInvitation of siteInvitations) { // Check the 'Returned output' tab for the result ☝️ console.log(siteInvitation); } } run(); ``` Returned output ```javascript { id: "312", email: "mark.smith@example.com", expired: "mark.smith@example.com", role: { type: "role", id: "34" }, } ``` --- # Content Management API — Retrieve an invitation Source [docs]: https://www.datocms.com/docs/content-management-api/resources/site-invitation/self.md ## Returns Returns a resource object of type [site\_invitation](/docs/content-management-api/resources/site-invitation.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const siteInvitationId = "312"; const siteInvitation = await client.siteInvitations.find(siteInvitationId); // Check the 'Returned output' tab for the result ☝️ console.log(siteInvitation); } run(); ``` Returned output ```javascript { id: "312", email: "mark.smith@example.com", expired: "mark.smith@example.com", role: { type: "role", id: "34" }, } ``` --- # Content Management API — Delete an invitation Source [docs]: https://www.datocms.com/docs/content-management-api/resources/site-invitation/destroy.md ## Returns Returns a resource object of type [site\_invitation](/docs/content-management-api/resources/site-invitation.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const siteInvitationId = "312"; const siteInvitation = await client.siteInvitations.destroy(siteInvitationId); // Check the 'Returned output' tab for the result ☝️ console.log(siteInvitation); } run(); ``` Returned output ```javascript { id: "312", email: "mark.smith@example.com", expired: "mark.smith@example.com", role: { type: "role", id: "34" }, } ``` --- # Content Management API — Resend an invitation Source [docs]: https://www.datocms.com/docs/content-management-api/resources/site-invitation/resend.md Resends the email invitation ## Returns Returns a resource object of type [site\_invitation](/docs/content-management-api/resources/site-invitation.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const siteInvitationId = "312"; const siteInvitation = await client.siteInvitations.resend(siteInvitationId); // Check the 'Returned output' tab for the result ☝️ console.log(siteInvitation); } run(); ``` Returned output ```javascript { id: "312", email: "mark.smith@example.com", expired: "mark.smith@example.com", role: { type: "role", id: "34" }, } ``` --- # Content Management API — Collaborator Source [docs]: https://www.datocms.com/docs/content-management-api/resources/user.md A DatoCMS administrative area can be accessed by multiple people. Every collaborator is linked to a specific Role, which describes what actions it will be able to perform once logged in. ## Object payload **`id`** - Type: string - Example: `"312"` ID of collaborator **`type`** - Type: string Must be exactly `"user"`. **`email`** - Type: string - Example: `"mark.smith@example.com"` Email **`is_2fa_active`** - Type: boolean, null Whether 2-factor authentication is active for this account or not. It returns `null` if the credentials you are using cannot manage the collaborators of the project. **`full_name`** - Type: string - Example: `"Mark Smith"` Full name **`is_active`** - Type: boolean Whether the user is active or not **`meta.last_access`** - Type: date-time, null - Example: `"2018-03-25T21:50:24.914Z"` Date of last reading/interaction. It returns `null` if the credentials you are using cannot manage the collaborators of the project. **`role`** - Type: [ResourceLinkage\<"role"\>](https://www-draft.datocms.com/docs/content-management-api/resources/role.md) Role --- # Content Management API — Update a collaborator Source [docs]: https://www.datocms.com/docs/content-management-api/resources/user/update.md ## Body parameters **`is_active`** - Optional - Type: boolean Whether the user is active or not **`role`** - Optional - Type: [ResourceLinkage\<"role"\>](https://www-draft.datocms.com/docs/content-management-api/resources/role.md) Role ## Returns Returns a resource object of type [user](/docs/content-management-api/resources/user.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const userId = "312"; const user = await client.users.update(userId, { id: "312" }); // Check the 'Returned output' tab for the result ☝️ console.log(user); } run(); ``` Returned output ```javascript { id: "312", email: "mark.smith@example.com", is_2fa_active: true, full_name: "Mark Smith", is_active: true, role: { type: "role", id: "34" }, } ``` --- # Content Management API — List all collaborators Source [docs]: https://www.datocms.com/docs/content-management-api/resources/user/instances.md ## Returns Returns an array of resource objects of type [user](/docs/content-management-api/resources/user.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const users = await client.users.list(); for (const user of users) { // Check the 'Returned output' tab for the result ☝️ console.log(user); } } run(); ``` Returned output ```javascript { id: "312", email: "mark.smith@example.com", is_2fa_active: true, full_name: "Mark Smith", is_active: true, role: { type: "role", id: "34" }, } ``` --- # Content Management API — Retrieve a collaborator Source [docs]: https://www.datocms.com/docs/content-management-api/resources/user/self.md ## Query parameters **`include`** - Type: string - Example: `"role"` Comma-separated list of [relationship paths](https://jsonapi.org/format/#fetching-includes). A relationship path is a dot-separated list of relationship names. Allowed relationship paths: `role`. ## Returns Returns a resource object of type [user](/docs/content-management-api/resources/user.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const userId = "312"; const user = await client.users.find(userId); // Check the 'Returned output' tab for the result ☝️ console.log(user); } run(); ``` Returned output ```javascript { id: "312", email: "mark.smith@example.com", is_2fa_active: true, full_name: "Mark Smith", is_active: true, role: { type: "role", id: "34" }, } ``` --- # Content Management API — Retrieve current signed-in user Source [docs]: https://www.datocms.com/docs/content-management-api/resources/user/me.md ## Query parameters **`include`** - Type: string - Example: `"role"` Comma-separated list of [relationship paths](https://jsonapi.org/format/#fetching-includes). A relationship path is a dot-separated list of relationship names. Allowed relationship paths: `role`. ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const user = await client.users.findMe(); // Check the 'Returned output' tab for the result ☝️ console.log(user); } run(); ``` Returned output ```javascript { id: "312", email: "mark.smith@example.com", is_2fa_active: true, full_name: "Mark Smith", is_active: true, role: { type: "role", id: "34" }, } ``` --- # Content Management API — Delete a collaborator Source [docs]: https://www.datocms.com/docs/content-management-api/resources/user/destroy.md ## Query parameters **`destination_user_type`** - Type: enum - Example: `"user"` New owner for resources previously owned by the deleted user. This argument specifies the new owner type.
Show enum values **`account`** **`user`** **`access_token`** **`sso_user`**
**`destination_user_id`** - Type: string - Example: `"7865"` New owner for resources previously owned by the deleted user. This argument specifies the new owner ID. ## Returns Returns a resource object of type [user](/docs/content-management-api/resources/user.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const userId = "312"; const user = await client.users.destroy(userId); // Check the 'Returned output' tab for the result ☝️ console.log(user); } run(); ``` Returned output ```javascript { id: "312", email: "mark.smith@example.com", is_2fa_active: true, full_name: "Mark Smith", is_active: true, role: { type: "role", id: "34" }, } ``` --- # Content Management API — Role Source [docs]: https://www.datocms.com/docs/content-management-api/resources/role.md A Role groups the permissions that govern what a credential can do in a project. The same role definition is applied to **collaborators**, **SSO users**, and **API tokens** alike — design roles around what the *credential* should be allowed to do, not who is holding it. > [!PROTIP] 📘 Same role, different identities > Ask "what is the *credential* allowed to do?" — not "what is this *person* allowed to do?". For API tokens specifically, the role's permissions are further constrained by the token's API surface flags (`can_access_cda`, `can_access_cda_preview`, `can_access_cma`); see the [API token](/docs/content-management-api/resources/access-token.md) resource for details. ## How permissions are computed Most of the granular permissions on a role come as a `positive__permissions` / `negative__permissions` pair: build triggers, search indexes, records (`item_type`), uploads. They all follow the same rule: > Effective permissions = `(inherited ∪ positive_*) − negative_*` Positive entries (and entries pulled in via `relationships.inherits_permissions_from`) grant access. Negative entries always win when they overlap. The idiomatic recipe for "almost everything" is a single `action: "all"` positive entry plus targeted negative entries to subtract — instead of enumerating each allowed action. > [!WARNING] ⚠️ Send positive_* and negative_* together > For each resource family (records, uploads, build triggers, search indexes), the matching `positive_*` and `negative_*` arrays must be **both present or both absent** in a create/update payload. On **update**, sent arrays *replace* the stored ones wholesale, so always read the role first and pass back the existing entries on the side you're not changing — sending `[]` to satisfy the constraint will erase everything that was there. (On create, `[]` is fine since there's nothing to lose.) The [Update endpoint](/docs/content-management-api/resources/role/update.md) documents an SDK helper that handles this diff for records and uploads. The computed result is exposed on every role response under `meta.final_permissions`; the raw declared values stay on `attributes.*`. See [Effective vs declared permissions](/docs/content-management-api/resources/role.md#effective-vs-declared-permissions) below. ## Project-level permissions These attributes gate access to project-wide capabilities. They apply uniformly across the whole project; granular control over individual records and uploads lives under [Per-environment content permissions](/docs/content-management-api/resources/role.md#per-environment-content-permissions). - **Project-wide flags.** Boolean attributes named `can_*` (`can_edit_schema`, `can_manage_environments`, `can_manage_access_tokens`, …) cover the schema, environments, users, webhooks, and so on — see the property table for the full list. - **Environment access.** `environments_access` controls *which* environments the credential can enter at all (`all`, `primary_only`, `sandbox_only`, or `none`). Use `none` when the role is meant only to be inherited from. - **Build triggers.** The role may **manually fire** the build triggers listed in `positive_build_trigger_permissions`, minus those listed in `negative_build_trigger_permissions`. Use `build_trigger: null` on an entry to cover every trigger at once. Creating, editing, or deleting trigger definitions is gated separately by `can_manage_build_triggers`. - **Search indexes.** The role may **manually re-index** the search indexes listed in `positive_search_index_permissions`, minus those listed in `negative_search_index_permissions`. Use `search_index: null` on an entry to cover every index. Managing the index definitions themselves is gated separately by `can_manage_search_indexes`. ## Per-environment content permissions The role's access to **records** and **uploads** is governed by two positive/negative array pairs. Every entry is **scoped to a single environment** via the required `environment` field — to grant the same permission across multiple environments, repeat the entry once per environment id (or use `inherits_permissions_from` together with `environments_access`). The computation is the same `(inherited ∪ positive_*) − negative_*` rule from [How permissions are computed](/docs/content-management-api/resources/role.md#how-permissions-are-computed), evaluated per environment. ###### Records Permission entries live in `positive_item_type_permissions` (and the `negative_*` counterpart). Each entry is a discriminated union keyed by `action`: - `all` — every action below - `read` — read records - `create` — create new records - `update` — edit existing records - `publish` — publish/unpublish records - `duplicate` — duplicate records - `delete` — destroy records - `edit_creator` — change a record's `creator` relationship - `take_over` — wrest a record from another user currently editing it - `move_to_stage` — move a record between workflow stages Per entry you can also restrict by: - `item_type` — restrict to a specific model (`null` = all models) - `workflow` — restrict to records associated with a workflow (mutually exclusive with `item_type`) - `on_creator` — `anyone`, `self` (records the credential created), or `role` (records created by anyone with this role) - `localization_scope` + `locale` — for `create`/`update`/`publish`/`all`: restrict to localized vs non-localized content, optionally pinning to one locale (on `all` the scope is forced to `"all"`) - `on_stage` / `to_stage` — for workflow-aware actions: restrict to records currently on a stage, or to moves towards a stage The shape of each entry depends on the `action` — see the property tables on each endpoint for which sub-fields are valid per branch. > [!WARNING] ⚠️ Some restrictors require an Enterprise plan > Workflow-aware permissions — the `move_to_stage` action and the `workflow` / `on_stage` / `to_stage` restrictors — require [Workflows](https://www.datocms.com/features/workflows.md), an Enterprise feature. Per-content-scope restrictions are also gated: only `localization_scope: "all"` is available on every plan, while `"localized"` (with its companion `locale`) and `"not_localized"` both require Enterprise. Setting any of these on a non-Enterprise project will return an error — check the [pricing page](https://www.datocms.com/pricing.md) before relying on them. ###### Uploads Permission entries live in `positive_upload_permissions` (and the `negative_*` counterpart). Same discriminated-union shape as records, with the upload-relevant actions (`read`, `create`, `update`, `delete`, `edit_creator`, `replace_asset`, `move`, `all`), scoped by `upload_collection` instead of `item_type`. The `move` action also accepts `move_to_upload_collection` to restrict the destination of the move. ## Inheriting from other roles `relationships.inherits_permissions_from` accepts a list of role ids whose permissions are unioned into this role's positive set before the negative set is subtracted (per [How permissions are computed](/docs/content-management-api/resources/role.md#how-permissions-are-computed)). This is how built-in roles are typically extended without copying their full permission tree — duplicate the closest built-in role, then add a `negative_*` entry to take something away, or set `inherits_permissions_from` and add only the positive entries that differ. ## Effective vs declared permissions Two views of a role's permissions are surfaced on the response: - **`attributes.*`** — the permissions declared *on this role directly*. This is what was sent on create/update; it does not reflect anything inherited from `relationships.inherits_permissions_from`. - **`meta.final_permissions`** — the **effective** permissions after walking the inheritance chain and applying the rule from [How permissions are computed](/docs/content-management-api/resources/role.md#how-permissions-are-computed). This is the set actually enforced when a credential bound to this role makes a request. When debugging "why can't this user do X?", read `meta.final_permissions`, not `attributes`. ## Object payload **`id`** - Type: string - Example: `"34"` ID of role **`type`** - Type: string Must be exactly `"role"`. **`name`** - Type: string - Example: `"Editor"` The name of the role **`can_edit_site`** - Type: boolean Can change project-wide settings (project name, internal subdomain, frontend preview URL, deployment settings) **`can_edit_favicon`** - Type: boolean Can edit favicon, global SEO settings and no-index policy **`can_edit_schema`** - Type: boolean Can create and edit the project schema: models, block models, fields, fieldsets, validators, and plugins **`can_manage_menu`** - Type: boolean Can customize content navigation bar **`can_manage_users`** - Type: boolean Can create and edit roles and invite/remove collaborators **`can_manage_shared_filters`** - Type: boolean Can create and edit shared filters (both for models and the media area) **`can_manage_search_indexes`** - Type: boolean Can create and edit search indexes **`can_manage_upload_collections`** - Type: boolean Can create and edit upload collections **`can_manage_environments`** - Type: boolean Can create, fork, and delete sandbox environments. Promotion to primary is gated separately by `can_promote_environments`. **`can_manage_webhooks`** - Type: boolean Can create and edit webhooks **`environments_access`** - Type: enum - Example: `"primary_only"` Specifies the environments the user can access
Show enum values **`all`** Grants access to all environments **`primary_only`** Grants access exclusively to the primary environment **`sandbox_only`** Grants access exclusively to sandbox environments **`none`** No access to any environment. This value is typically used when the role is intended to inherit access settings from other roles
**`can_manage_sso`** - Type: boolean Can manage Single Sign-On settings **`can_access_audit_log`** - Type: boolean Can access Audit Log **`can_manage_workflows`** - Type: boolean Can create and edit workflows **`can_edit_environment`** - Type: boolean Can edit per-environment settings of the environments this role has access to: locales, timezone, and UI theme. This is *not* about creating or switching environments — see `can_manage_environments` for that, and `environments_access` for which environments this role can enter at all. **`can_promote_environments`** - Type: boolean Can promote a sandbox environment to primary (atomic swap) and toggle the project's maintenance mode. Distinct from `can_manage_environments`, which covers creating/forking/deleting sandboxes. **`can_manage_build_triggers`** - Type: boolean Can create and edit build triggers **`can_manage_access_tokens`** - Type: boolean Can manage API tokens **`can_perform_site_search`** - Type: boolean Can perform Site Search API calls **`can_access_build_events_log`** - Type: boolean Can access the build events log **`can_access_search_index_events_log`** - Type: boolean Can access the search index events log **`positive_item_type_permissions`** - Type: Array\ Allowed actions on a model (or all) for a role. The shape of each entry depends on the `action` (discriminated union). Idiomatic recipes: - To grant every action, use a single `action: "all"` entry with `localization_scope: "all"`. - To grant a subset (e.g. create+read+update but not delete), prefer a single `action: "all"` entry plus `negative_item_type_permissions` entries for the actions to exclude — instead of listing each allowed action separately.
Show object format when action is "all" **`action`** - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`localization_scope`** - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`**
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Type: string, null Restrict to moves towards a specific workflow stage.
Show object format when action is "read" **`action`** - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
Show object format when action is "create" **`action`** - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`localization_scope`** - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** Any content (localized/unlocalized) **`localized`** Content under a specific locale (`locale` must be defined) **`not_localized`** Non-localized content
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`locale`** - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "update" or "publish" **`action`** - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`** **`publish`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`localization_scope`** - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** Any content (localized/unlocalized) **`localized`** Content under a specific locale (`locale` must be defined) **`not_localized`** Non-localized content
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Type: string, null Restrict to records currently on a workflow stage. **`locale`** - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "duplicate" **`action`** - Type: enum - Example: `"duplicate"` Permitted action
Show enum values **`duplicate`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "delete" or "edit_creator" or "take_over" **`action`** - Type: enum - Example: `"delete"` Permitted action
Show enum values **`delete`** **`edit_creator`** **`take_over`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "move_to_stage" **`action`** - Type: enum - Example: `"move_to_stage"` Permitted action
Show enum values **`move_to_stage`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Type: string, null Restrict to moves towards a specific workflow stage.
**`negative_item_type_permissions`** - Type: Array\ Prohibited actions on a model (or all) for a role. Negative permissions take precedence and are typically paired with a broader positive `action: "all"` entry to subtract specific actions (e.g. forbid `delete`).
Show object format when action is "all" **`action`** - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`localization_scope`** - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`**
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Type: string, null Restrict to moves towards a specific workflow stage.
Show object format when action is "read" **`action`** - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
Show object format when action is "create" **`action`** - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`localization_scope`** - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** Any content (localized/unlocalized) **`localized`** Content under a specific locale (`locale` must be defined) **`not_localized`** Non-localized content
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`locale`** - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "update" or "publish" **`action`** - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`** **`publish`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`localization_scope`** - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** Any content (localized/unlocalized) **`localized`** Content under a specific locale (`locale` must be defined) **`not_localized`** Non-localized content
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Type: string, null Restrict to records currently on a workflow stage. **`locale`** - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "duplicate" **`action`** - Type: enum - Example: `"duplicate"` Permitted action
Show enum values **`duplicate`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "delete" or "edit_creator" or "take_over" **`action`** - Type: enum - Example: `"delete"` Permitted action
Show enum values **`delete`** **`edit_creator`** **`take_over`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "move_to_stage" **`action`** - Type: enum - Example: `"move_to_stage"` Permitted action
Show enum values **`move_to_stage`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Type: string, null Restrict to moves towards a specific workflow stage.
**`positive_upload_permissions`** - Type: Array\ Allowed actions on uploads (or all) for a role. The shape of each entry depends on the `action` (discriminated union). To grant a subset, prefer a single `action: "all"` entry plus `negative_upload_permissions` entries for the actions to exclude.
Show object format when action is "all" **`action`** - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`localization_scope`** - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`**
**`upload_collection`** - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "update" **`action`** - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`localization_scope`** - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** Any content (localized/unlocalized) **`localized`** Localized content in a specific locale (`locale` must be defined) **`not_localized`** Non-localized content
**`upload_collection`** - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`locale`** - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "create" **`action`** - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`upload_collection`** - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "read" or "delete" or "edit_creator" or "replace_asset" **`action`** - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`** **`delete`** **`edit_creator`** **`replace_asset`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`upload_collection`** - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "move" **`action`** - Type: enum - Example: `"move"` Permitted action
Show enum values **`move`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`upload_collection`** - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`move_to_upload_collection`** - Type: string, null Restricts the destination upload collection of the move action. When `null`, any destination is allowed.
**`negative_upload_permissions`** - Type: Array\ Prohibited actions on uploads (or all) for a role. Negative permissions take precedence and are typically paired with a broader positive `action: "all"` entry to subtract specific actions.
Show object format when action is "all" **`action`** - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`localization_scope`** - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`**
**`upload_collection`** - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "update" **`action`** - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`localization_scope`** - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** Any content (localized/unlocalized) **`localized`** Localized content in a specific locale (`locale` must be defined) **`not_localized`** Non-localized content
**`upload_collection`** - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`locale`** - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "create" **`action`** - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`upload_collection`** - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "read" or "delete" or "edit_creator" or "replace_asset" **`action`** - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`** **`delete`** **`edit_creator`** **`replace_asset`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`upload_collection`** - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "move" **`action`** - Type: enum - Example: `"move"` Permitted action
Show enum values **`move`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`upload_collection`** - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`move_to_upload_collection`** - Type: string, null Restricts the destination upload collection of the move action. When `null`, any destination is allowed.
**`positive_build_trigger_permissions`** - Type: Array\ Build triggers this role is allowed to **manually fire**. An entry with `build_trigger: null` covers every build trigger. Note: this does not control creating/editing build triggers themselves — that is gated by `can_manage_build_triggers`.
Show objects format inside array **`build_trigger`** - Type: string, null
**`negative_build_trigger_permissions`** - Type: Array\ Build triggers this role is **forbidden** from manually firing. Negative entries take precedence over positive ones; pair with a `build_trigger: null` positive entry to allow all-but-N.
Show objects format inside array **`build_trigger`** - Type: string, null
**`positive_search_index_permissions`** - Type: Array\ Search indexes this role is allowed to **manually re-index**. An entry with `search_index: null` covers every search index. Note: this does not control creating/editing search indexes themselves — that is gated by `can_manage_search_indexes`.
Show objects format inside array **`search_index`** - Type: string, null
**`negative_search_index_permissions`** - Type: Array\ Search indexes this role is **forbidden** from manually re-indexing. Negative entries take precedence over positive ones; pair with a `search_index: null` positive entry to allow all-but-N.
Show objects format inside array **`search_index`** - Type: string, null
**`meta.final_permissions`** - Type: object The final set of permissions considering also inherited roles
Show object format **`can_edit_site`** - Type: boolean Can change project-wide settings (project name, internal subdomain, frontend preview URL, deployment settings) **`can_edit_favicon`** - Type: boolean Can edit favicon, global SEO settings and no-index policy **`can_edit_schema`** - Type: boolean Can create and edit the project schema: models, block models, fields, fieldsets, validators, and plugins **`can_manage_menu`** - Type: boolean Can customize content navigation bar **`can_manage_users`** - Type: boolean Can create and edit roles and invite/remove collaborators **`can_manage_environments`** - Type: boolean Can create, fork, and delete sandbox environments. Promotion to primary is gated separately by `can_promote_environments`. **`can_manage_webhooks`** - Type: boolean Can create and edit webhooks **`environments_access`** - Type: enum - Example: `"primary_only"` Specifies the environments the user can access
Show enum values **`all`** Grants access to all environments **`primary_only`** Grants access exclusively to the primary environment **`sandbox_only`** Grants access exclusively to sandbox environments **`none`** No access to any environment. This value is typically used when the role is intended to inherit access settings from other roles
**`can_manage_sso`** - Type: boolean Can manage Single Sign-On settings **`can_access_audit_log`** - Type: boolean Can access Audit Log **`can_manage_workflows`** - Type: boolean Can create and edit workflows **`can_edit_environment`** - Type: boolean Can edit per-environment settings of the environments this role has access to: locales, timezone, and UI theme. This is *not* about creating or switching environments — see `can_manage_environments` for that, and `environments_access` for which environments this role can enter at all. **`can_promote_environments`** - Type: boolean Can promote a sandbox environment to primary (atomic swap) and toggle the project's maintenance mode. Distinct from `can_manage_environments`, which covers creating/forking/deleting sandboxes. **`can_manage_shared_filters`** - Type: boolean Can create and edit shared filters (both for models and the media area) **`can_manage_search_indexes`** - Type: boolean Can create and edit search indexes **`can_manage_build_triggers`** - Type: boolean Can create and edit build triggers **`can_manage_upload_collections`** - Type: boolean Can create and edit upload collections **`can_manage_access_tokens`** - Type: boolean Can manage API tokens **`can_perform_site_search`** - Type: boolean Can perform Site Search API calls **`can_access_build_events_log`** - Type: boolean Can access the build events log **`can_access_search_index_events_log`** - Type: boolean Can access the search index events log **`positive_item_type_permissions`** - Type: Array\ Allowed actions on a model (or all) for a role. The shape of each entry depends on the `action` (discriminated union). Idiomatic recipes: - To grant every action, use a single `action: "all"` entry with `localization_scope: "all"`. - To grant a subset (e.g. create+read+update but not delete), prefer a single `action: "all"` entry plus `negative_item_type_permissions` entries for the actions to exclude — instead of listing each allowed action separately.
Show object format when action is "all" **`action`** - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`localization_scope`** - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`**
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Type: string, null Restrict to moves towards a specific workflow stage.
Show object format when action is "read" **`action`** - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
Show object format when action is "create" **`action`** - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`localization_scope`** - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** Any content (localized/unlocalized) **`localized`** Content under a specific locale (`locale` must be defined) **`not_localized`** Non-localized content
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`locale`** - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "update" or "publish" **`action`** - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`** **`publish`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`localization_scope`** - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** Any content (localized/unlocalized) **`localized`** Content under a specific locale (`locale` must be defined) **`not_localized`** Non-localized content
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Type: string, null Restrict to records currently on a workflow stage. **`locale`** - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "duplicate" **`action`** - Type: enum - Example: `"duplicate"` Permitted action
Show enum values **`duplicate`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "delete" or "edit_creator" or "take_over" **`action`** - Type: enum - Example: `"delete"` Permitted action
Show enum values **`delete`** **`edit_creator`** **`take_over`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "move_to_stage" **`action`** - Type: enum - Example: `"move_to_stage"` Permitted action
Show enum values **`move_to_stage`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Type: string, null Restrict to moves towards a specific workflow stage.
**`negative_item_type_permissions`** - Type: Array\ Prohibited actions on a model (or all) for a role. Negative permissions take precedence and are typically paired with a broader positive `action: "all"` entry to subtract specific actions (e.g. forbid `delete`).
Show object format when action is "all" **`action`** - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`localization_scope`** - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`**
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Type: string, null Restrict to moves towards a specific workflow stage.
Show object format when action is "read" **`action`** - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
Show object format when action is "create" **`action`** - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`localization_scope`** - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** Any content (localized/unlocalized) **`localized`** Content under a specific locale (`locale` must be defined) **`not_localized`** Non-localized content
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`locale`** - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "update" or "publish" **`action`** - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`** **`publish`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`localization_scope`** - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** Any content (localized/unlocalized) **`localized`** Content under a specific locale (`locale` must be defined) **`not_localized`** Non-localized content
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Type: string, null Restrict to records currently on a workflow stage. **`locale`** - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "duplicate" **`action`** - Type: enum - Example: `"duplicate"` Permitted action
Show enum values **`duplicate`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "delete" or "edit_creator" or "take_over" **`action`** - Type: enum - Example: `"delete"` Permitted action
Show enum values **`delete`** **`edit_creator`** **`take_over`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "move_to_stage" **`action`** - Type: enum - Example: `"move_to_stage"` Permitted action
Show enum values **`move_to_stage`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`item_type`** - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Type: string, null Restrict to moves towards a specific workflow stage.
**`positive_upload_permissions`** - Type: Array\ Allowed actions on uploads (or all) for a role. The shape of each entry depends on the `action` (discriminated union). To grant a subset, prefer a single `action: "all"` entry plus `negative_upload_permissions` entries for the actions to exclude.
Show object format when action is "all" **`action`** - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`localization_scope`** - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`**
**`upload_collection`** - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "update" **`action`** - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`localization_scope`** - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** Any content (localized/unlocalized) **`localized`** Localized content in a specific locale (`locale` must be defined) **`not_localized`** Non-localized content
**`upload_collection`** - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`locale`** - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "create" **`action`** - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`upload_collection`** - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "read" or "delete" or "edit_creator" or "replace_asset" **`action`** - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`** **`delete`** **`edit_creator`** **`replace_asset`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`upload_collection`** - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "move" **`action`** - Type: enum - Example: `"move"` Permitted action
Show enum values **`move`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`upload_collection`** - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`move_to_upload_collection`** - Type: string, null Restricts the destination upload collection of the move action. When `null`, any destination is allowed.
**`negative_upload_permissions`** - Type: Array\ Prohibited actions on uploads (or all) for a role. Negative permissions take precedence and are typically paired with a broader positive `action: "all"` entry to subtract specific actions.
Show object format when action is "all" **`action`** - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`localization_scope`** - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`**
**`upload_collection`** - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "update" **`action`** - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`localization_scope`** - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** Any content (localized/unlocalized) **`localized`** Localized content in a specific locale (`locale` must be defined) **`not_localized`** Non-localized content
**`upload_collection`** - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`locale`** - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "create" **`action`** - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`upload_collection`** - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "read" or "delete" or "edit_creator" or "replace_asset" **`action`** - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`** **`delete`** **`edit_creator`** **`replace_asset`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`upload_collection`** - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "move" **`action`** - Type: enum - Example: `"move"` Permitted action
Show enum values **`move`**
**`environment`** - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** Created by anyone **`self`** Created by the user itself **`role`** Created by a user with the same role
**`upload_collection`** - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`move_to_upload_collection`** - Type: string, null Restricts the destination upload collection of the move action. When `null`, any destination is allowed.
**`positive_build_trigger_permissions`** - Type: Array\ Build triggers this role is allowed to **manually fire**. An entry with `build_trigger: null` covers every build trigger. Note: this does not control creating/editing build triggers themselves — that is gated by `can_manage_build_triggers`.
Show objects format inside array **`build_trigger`** - Type: string, null
**`negative_build_trigger_permissions`** - Type: Array\ Build triggers this role is **forbidden** from manually firing. Negative entries take precedence over positive ones; pair with a `build_trigger: null` positive entry to allow all-but-N.
Show objects format inside array **`build_trigger`** - Type: string, null
**`positive_search_index_permissions`** - Type: Array\ Search indexes this role is allowed to **manually re-index**. An entry with `search_index: null` covers every search index. Note: this does not control creating/editing search indexes themselves — that is gated by `can_manage_search_indexes`.
Show objects format inside array **`search_index`** - Type: string, null
**`negative_search_index_permissions`** - Type: Array\ Search indexes this role is **forbidden** from manually re-indexing. Negative entries take precedence over positive ones; pair with a `search_index: null` positive entry to allow all-but-N.
Show objects format inside array **`search_index`** - Type: string, null
**`inherits_permissions_from`** - Type: Array<[ResourceLinkage\<"role"\>](https://www-draft.datocms.com/docs/content-management-api/resources/role.md)> The roles from which this role inherits permissions --- # Content Management API — Create a new role Source [docs]: https://www.datocms.com/docs/content-management-api/resources/role/create.md Creates a new role in the project. The role is immediately assignable to **collaborators**, **SSO users**, and **API tokens**. For the conceptual model — project-level vs content permissions, the discriminated-union shape of each `positive_*` / `negative_*` entry, and how inheritance is resolved — see the [Role resource overview](/docs/content-management-api/resources/role.md). > [!PROTIP] 💡 Don't start from scratch > Most custom roles are easier to build by [duplicating](/docs/content-management-api/resources/role/duplicate.md) the closest-matching built-in role (e.g. *Editor*) and then editing the result, rather than constructing a permission tree from zero. Use this endpoint when you genuinely need a role that doesn't resemble any of the existing ones. ## Body parameters **`name`** - Required - Type: string - Example: `"Editor"` The name of the role **`can_edit_favicon`** - Optional - Type: boolean Can edit favicon, global SEO settings and no-index policy **`can_edit_site`** - Optional - Type: boolean Can change project-wide settings (project name, internal subdomain, frontend preview URL, deployment settings) **`can_edit_schema`** - Optional - Type: boolean Can create and edit the project schema: models, block models, fields, fieldsets, validators, and plugins **`can_manage_menu`** - Optional - Type: boolean Can customize content navigation bar **`can_edit_environment`** - Optional - Type: boolean Can edit per-environment settings of the environments this role has access to: locales, timezone, and UI theme. This is *not* about creating or switching environments — see `can_manage_environments` for that, and `environments_access` for which environments this role can enter at all. **`can_promote_environments`** - Optional - Type: boolean Can promote a sandbox environment to primary (atomic swap) and toggle the project's maintenance mode. Distinct from `can_manage_environments`, which covers creating/forking/deleting sandboxes. **`environments_access`** - Optional - Type: enum - Example: `"primary_only"` Specifies the environments the user can access
Show enum values **`all`** - Optional Grants access to all environments **`primary_only`** - Optional Grants access exclusively to the primary environment **`sandbox_only`** - Optional Grants access exclusively to sandbox environments **`none`** - Optional No access to any environment. This value is typically used when the role is intended to inherit access settings from other roles
**`can_manage_users`** - Optional - Type: boolean Can create and edit roles and invite/remove collaborators **`can_manage_shared_filters`** - Optional - Type: boolean Can create and edit shared filters (both for models and the media area) **`can_manage_search_indexes`** - Optional - Type: boolean Can create and edit search indexes **`can_manage_upload_collections`** - Optional - Type: boolean Can create and edit upload collections **`can_manage_build_triggers`** - Optional - Type: boolean Can create and edit build triggers **`can_manage_webhooks`** - Optional - Type: boolean Can create and edit webhooks **`can_manage_environments`** - Optional - Type: boolean Can create, fork, and delete sandbox environments. Promotion to primary is gated separately by `can_promote_environments`. **`can_manage_sso`** - Optional - Type: boolean Can manage Single Sign-On settings **`can_access_audit_log`** - Optional - Type: boolean Can access Audit Log **`can_manage_workflows`** - Optional - Type: boolean Can create and edit workflows **`can_manage_access_tokens`** - Optional - Type: boolean Can manage API tokens **`can_perform_site_search`** - Optional - Type: boolean Can perform Site Search API calls **`can_access_build_events_log`** - Optional - Type: boolean Can access the build events log **`can_access_search_index_events_log`** - Optional - Type: boolean Can access the search index events log **`positive_item_type_permissions`** - Optional - Type: Array\ Allowed actions on a model (or all) for a role. The shape of each entry depends on the `action` (discriminated union). Idiomatic recipes: - To grant every action, use a single `action: "all"` entry with `localization_scope: "all"`. - To grant a subset (e.g. create+read+update but not delete), prefer a single `action: "all"` entry plus `negative_item_type_permissions` entries for the actions to exclude — instead of listing each allowed action separately.
Show object format when action is "all" **`action`** - Required - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`** - Optional
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Optional - Type: string, null Restrict to moves towards a specific workflow stage.
Show object format when action is "read" **`action`** - Required - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
Show object format when action is "create" **`action`** - Required - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Content under a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "update" or "publish" **`action`** - Required - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`** - Optional **`publish`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Content under a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "duplicate" **`action`** - Required - Type: enum - Example: `"duplicate"` Permitted action
Show enum values **`duplicate`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "delete" or "edit_creator" or "take_over" **`action`** - Required - Type: enum - Example: `"delete"` Permitted action
Show enum values **`delete`** - Optional **`edit_creator`** - Optional **`take_over`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "move_to_stage" **`action`** - Required - Type: enum - Example: `"move_to_stage"` Permitted action
Show enum values **`move_to_stage`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Optional - Type: string, null Restrict to moves towards a specific workflow stage.
**`negative_item_type_permissions`** - Optional - Type: Array\ Prohibited actions on a model (or all) for a role. Negative permissions take precedence and are typically paired with a broader positive `action: "all"` entry to subtract specific actions (e.g. forbid `delete`).
Show object format when action is "all" **`action`** - Required - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`** - Optional
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Optional - Type: string, null Restrict to moves towards a specific workflow stage.
Show object format when action is "read" **`action`** - Required - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
Show object format when action is "create" **`action`** - Required - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Content under a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "update" or "publish" **`action`** - Required - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`** - Optional **`publish`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Content under a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "duplicate" **`action`** - Required - Type: enum - Example: `"duplicate"` Permitted action
Show enum values **`duplicate`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "delete" or "edit_creator" or "take_over" **`action`** - Required - Type: enum - Example: `"delete"` Permitted action
Show enum values **`delete`** - Optional **`edit_creator`** - Optional **`take_over`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "move_to_stage" **`action`** - Required - Type: enum - Example: `"move_to_stage"` Permitted action
Show enum values **`move_to_stage`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Optional - Type: string, null Restrict to moves towards a specific workflow stage.
**`positive_upload_permissions`** - Optional - Type: Array\ Allowed actions on uploads (or all) for a role. The shape of each entry depends on the `action` (discriminated union). To grant a subset, prefer a single `action: "all"` entry plus `negative_upload_permissions` entries for the actions to exclude.
Show object format when action is "all" **`action`** - Required - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`** - Optional
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "update" **`action`** - Required - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Localized content in a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "create" **`action`** - Required - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "read" or "delete" or "edit_creator" or "replace_asset" **`action`** - Required - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`** - Optional **`delete`** - Optional **`edit_creator`** - Optional **`replace_asset`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "move" **`action`** - Required - Type: enum - Example: `"move"` Permitted action
Show enum values **`move`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`move_to_upload_collection`** - Optional - Type: string, null Restricts the destination upload collection of the move action. When `null`, any destination is allowed.
**`negative_upload_permissions`** - Optional - Type: Array\ Prohibited actions on uploads (or all) for a role. Negative permissions take precedence and are typically paired with a broader positive `action: "all"` entry to subtract specific actions.
Show object format when action is "all" **`action`** - Required - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`** - Optional
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "update" **`action`** - Required - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Localized content in a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "create" **`action`** - Required - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "read" or "delete" or "edit_creator" or "replace_asset" **`action`** - Required - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`** - Optional **`delete`** - Optional **`edit_creator`** - Optional **`replace_asset`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "move" **`action`** - Required - Type: enum - Example: `"move"` Permitted action
Show enum values **`move`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`move_to_upload_collection`** - Optional - Type: string, null Restricts the destination upload collection of the move action. When `null`, any destination is allowed.
**`positive_build_trigger_permissions`** - Optional - Type: Array\ Build triggers this role is allowed to **manually fire**. An entry with `build_trigger: null` covers every build trigger. Note: this does not control creating/editing build triggers themselves — that is gated by `can_manage_build_triggers`.
Show objects format inside array **`build_trigger`** - Optional - Type: string, null
**`negative_build_trigger_permissions`** - Optional - Type: Array\ Build triggers this role is **forbidden** from manually firing. Negative entries take precedence over positive ones; pair with a `build_trigger: null` positive entry to allow all-but-N.
Show objects format inside array **`build_trigger`** - Optional - Type: string, null
**`positive_search_index_permissions`** - Optional - Type: Array\ Search indexes this role is allowed to **manually re-index**. An entry with `search_index: null` covers every search index. Note: this does not control creating/editing search indexes themselves — that is gated by `can_manage_search_indexes`.
Show objects format inside array **`search_index`** - Optional - Type: string, null
**`negative_search_index_permissions`** - Optional - Type: Array\ Search indexes this role is **forbidden** from manually re-indexing. Negative entries take precedence over positive ones; pair with a `search_index: null` positive entry to allow all-but-N.
Show objects format inside array **`search_index`** - Optional - Type: string, null
**`meta.final_permissions`** - Required - Type: object The final set of permissions considering also inherited roles
Show object format **`can_edit_site`** - Required - Type: boolean Can change project-wide settings (project name, internal subdomain, frontend preview URL, deployment settings) **`can_edit_favicon`** - Required - Type: boolean Can edit favicon, global SEO settings and no-index policy **`can_edit_schema`** - Required - Type: boolean Can create and edit the project schema: models, block models, fields, fieldsets, validators, and plugins **`can_manage_menu`** - Required - Type: boolean Can customize content navigation bar **`can_manage_users`** - Required - Type: boolean Can create and edit roles and invite/remove collaborators **`can_manage_environments`** - Required - Type: boolean Can create, fork, and delete sandbox environments. Promotion to primary is gated separately by `can_promote_environments`. **`can_manage_webhooks`** - Required - Type: boolean Can create and edit webhooks **`environments_access`** - Required - Type: enum - Example: `"primary_only"` Specifies the environments the user can access
Show enum values **`all`** - Optional Grants access to all environments **`primary_only`** - Optional Grants access exclusively to the primary environment **`sandbox_only`** - Optional Grants access exclusively to sandbox environments **`none`** - Optional No access to any environment. This value is typically used when the role is intended to inherit access settings from other roles
**`can_manage_sso`** - Required - Type: boolean Can manage Single Sign-On settings **`can_access_audit_log`** - Required - Type: boolean Can access Audit Log **`can_manage_workflows`** - Required - Type: boolean Can create and edit workflows **`can_edit_environment`** - Required - Type: boolean Can edit per-environment settings of the environments this role has access to: locales, timezone, and UI theme. This is *not* about creating or switching environments — see `can_manage_environments` for that, and `environments_access` for which environments this role can enter at all. **`can_promote_environments`** - Required - Type: boolean Can promote a sandbox environment to primary (atomic swap) and toggle the project's maintenance mode. Distinct from `can_manage_environments`, which covers creating/forking/deleting sandboxes. **`can_manage_shared_filters`** - Required - Type: boolean Can create and edit shared filters (both for models and the media area) **`can_manage_search_indexes`** - Required - Type: boolean Can create and edit search indexes **`can_manage_build_triggers`** - Required - Type: boolean Can create and edit build triggers **`can_manage_upload_collections`** - Required - Type: boolean Can create and edit upload collections **`can_manage_access_tokens`** - Required - Type: boolean Can manage API tokens **`can_perform_site_search`** - Required - Type: boolean Can perform Site Search API calls **`can_access_build_events_log`** - Required - Type: boolean Can access the build events log **`can_access_search_index_events_log`** - Required - Type: boolean Can access the search index events log **`positive_item_type_permissions`** - Required - Type: Array\ Allowed actions on a model (or all) for a role. The shape of each entry depends on the `action` (discriminated union). Idiomatic recipes: - To grant every action, use a single `action: "all"` entry with `localization_scope: "all"`. - To grant a subset (e.g. create+read+update but not delete), prefer a single `action: "all"` entry plus `negative_item_type_permissions` entries for the actions to exclude — instead of listing each allowed action separately.
Show object format when action is "all" **`action`** - Required - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`** - Optional
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Optional - Type: string, null Restrict to moves towards a specific workflow stage.
Show object format when action is "read" **`action`** - Required - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
Show object format when action is "create" **`action`** - Required - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Content under a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "update" or "publish" **`action`** - Required - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`** - Optional **`publish`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Content under a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "duplicate" **`action`** - Required - Type: enum - Example: `"duplicate"` Permitted action
Show enum values **`duplicate`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "delete" or "edit_creator" or "take_over" **`action`** - Required - Type: enum - Example: `"delete"` Permitted action
Show enum values **`delete`** - Optional **`edit_creator`** - Optional **`take_over`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "move_to_stage" **`action`** - Required - Type: enum - Example: `"move_to_stage"` Permitted action
Show enum values **`move_to_stage`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Optional - Type: string, null Restrict to moves towards a specific workflow stage.
**`negative_item_type_permissions`** - Required - Type: Array\ Prohibited actions on a model (or all) for a role. Negative permissions take precedence and are typically paired with a broader positive `action: "all"` entry to subtract specific actions (e.g. forbid `delete`).
Show object format when action is "all" **`action`** - Required - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`** - Optional
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Optional - Type: string, null Restrict to moves towards a specific workflow stage.
Show object format when action is "read" **`action`** - Required - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
Show object format when action is "create" **`action`** - Required - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Content under a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "update" or "publish" **`action`** - Required - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`** - Optional **`publish`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Content under a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "duplicate" **`action`** - Required - Type: enum - Example: `"duplicate"` Permitted action
Show enum values **`duplicate`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "delete" or "edit_creator" or "take_over" **`action`** - Required - Type: enum - Example: `"delete"` Permitted action
Show enum values **`delete`** - Optional **`edit_creator`** - Optional **`take_over`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "move_to_stage" **`action`** - Required - Type: enum - Example: `"move_to_stage"` Permitted action
Show enum values **`move_to_stage`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Optional - Type: string, null Restrict to moves towards a specific workflow stage.
**`positive_upload_permissions`** - Required - Type: Array\ Allowed actions on uploads (or all) for a role. The shape of each entry depends on the `action` (discriminated union). To grant a subset, prefer a single `action: "all"` entry plus `negative_upload_permissions` entries for the actions to exclude.
Show object format when action is "all" **`action`** - Required - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`** - Optional
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "update" **`action`** - Required - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Localized content in a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "create" **`action`** - Required - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "read" or "delete" or "edit_creator" or "replace_asset" **`action`** - Required - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`** - Optional **`delete`** - Optional **`edit_creator`** - Optional **`replace_asset`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "move" **`action`** - Required - Type: enum - Example: `"move"` Permitted action
Show enum values **`move`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`move_to_upload_collection`** - Optional - Type: string, null Restricts the destination upload collection of the move action. When `null`, any destination is allowed.
**`negative_upload_permissions`** - Required - Type: Array\ Prohibited actions on uploads (or all) for a role. Negative permissions take precedence and are typically paired with a broader positive `action: "all"` entry to subtract specific actions.
Show object format when action is "all" **`action`** - Required - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`** - Optional
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "update" **`action`** - Required - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Localized content in a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "create" **`action`** - Required - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "read" or "delete" or "edit_creator" or "replace_asset" **`action`** - Required - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`** - Optional **`delete`** - Optional **`edit_creator`** - Optional **`replace_asset`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "move" **`action`** - Required - Type: enum - Example: `"move"` Permitted action
Show enum values **`move`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`move_to_upload_collection`** - Optional - Type: string, null Restricts the destination upload collection of the move action. When `null`, any destination is allowed.
**`positive_build_trigger_permissions`** - Required - Type: Array\ Build triggers this role is allowed to **manually fire**. An entry with `build_trigger: null` covers every build trigger. Note: this does not control creating/editing build triggers themselves — that is gated by `can_manage_build_triggers`.
Show objects format inside array **`build_trigger`** - Optional - Type: string, null
**`negative_build_trigger_permissions`** - Required - Type: Array\ Build triggers this role is **forbidden** from manually firing. Negative entries take precedence over positive ones; pair with a `build_trigger: null` positive entry to allow all-but-N.
Show objects format inside array **`build_trigger`** - Optional - Type: string, null
**`positive_search_index_permissions`** - Required - Type: Array\ Search indexes this role is allowed to **manually re-index**. An entry with `search_index: null` covers every search index. Note: this does not control creating/editing search indexes themselves — that is gated by `can_manage_search_indexes`.
Show objects format inside array **`search_index`** - Optional - Type: string, null
**`negative_search_index_permissions`** - Required - Type: Array\ Search indexes this role is **forbidden** from manually re-indexing. Negative entries take precedence over positive ones; pair with a `search_index: null` positive entry to allow all-but-N.
Show objects format inside array **`search_index`** - Optional - Type: string, null
**`inherits_permissions_from`** - Optional - Type: Array<[ResourceLinkage\<"role"\>](https://www-draft.datocms.com/docs/content-management-api/resources/role.md)> The roles from which this role inherits permissions ## Returns Returns a resource object of type [role](/docs/content-management-api/resources/role.md) ## Other examples ###### Example Inherit from a built-in role and subtract one action A role that inherits the project's built-in *Editor* role but **forbids `delete`** on records. The new role's `attributes.*` is almost empty — every grant comes from the inherited role; only the negative entry is declared directly. Reading `meta.final_permissions` on the response shows the resolved set. This is the canonical "extend a built-in role" recipe: do not copy the parent's permission tree, just point at it via `inherits_permissions_from` and use `negative_item_type_permissions` to subtract. Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // Look up the built-in "Editor" role to inherit from. const allRoles = await client.roles.list(); const editorRole = allRoles.find((role) => role.name === "Editor")!; // Find the primary environment id — required on every permission entry. const environments = await client.environments.list(); const primaryEnv = environments.find( (environment) => environment.meta.primary, )!; // Create a new role that inherits everything from "Editor" except the // `delete` action on records, which is subtracted via a negative entry. // The API requires positive_* and negative_* arrays to be both present or // both absent — so we pass an explicit empty positive array. const role = await client.roles.create({ name: "Editor (no delete)", inherits_permissions_from: [{ type: "role", id: editorRole.id }], positive_item_type_permissions: [], negative_item_type_permissions: [ { environment: primaryEnv.id, action: "delete", on_creator: "anyone", }, ], }); console.log("Created role:", role.id, "—", role.name); console.log( "Effective record permissions (final_permissions):", JSON.stringify( role.meta.final_permissions.positive_item_type_permissions, null, 2, ), ); console.log( "Effective negative entries:", JSON.stringify( role.meta.final_permissions.negative_item_type_permissions, null, 2, ), ); } run(); ``` Returned output ```javascript Created role: 443077 — Editor (no delete) Effective record permissions (final_permissions): [ { "environment": "main", "item_type": null, "workflow": null, "on_stage": null, "to_stage": null, "action": "all", "on_creator": "anyone", "localization_scope": "all", "locale": null } ] Effective negative entries: [ { "environment": "main", "item_type": null, "workflow": null, "on_stage": null, "to_stage": null, "action": "delete", "on_creator": "anyone", "localization_scope": null, "locale": null } ] ``` --- # Content Management API — Update a role Source [docs]: https://www.datocms.com/docs/content-management-api/resources/role/update.md Updates an existing role. Any attribute or relationship omitted from the payload is left unchanged. The full `positive_*` / `negative_*` permission arrays are **replaced wholesale** when sent — there is no "patch a single permission entry" operation on this endpoint. Read the role first and forward the entries you don't want to change, or use the SDK helper described below. ## Safer permission edits with `updateCurrentEnvironmentPermissions` For records and uploads in the *current* environment, the SDK ships a higher-level helper: ```ts client.roles.updateCurrentEnvironmentPermissions(roleId, { positive_item_type_permissions: { add: [...], remove: [...] }, negative_item_type_permissions: { add: [...], remove: [...] }, positive_upload_permissions: { add: [...], remove: [...] }, negative_upload_permissions: { add: [...], remove: [...] }, }); ``` It reads the role, applies the diff against the entries scoped to the current environment, and forwards the merged arrays — so individual entries can be added or removed without rewriting the surrounding state. Build trigger and search index permissions, and entries scoped to *other* environments, still need a direct `client.roles.update(...)` call. ###### Example Subtract one action from a role that grants "all" Subtract a single action from a role that already grants `action: "all"`. The fix is to append a `negative_item_type_permissions` entry naming the action to take away — the existing positive `all` entry stays, and the formula `(positive_*) − negative_*` resolves to "everything but `delete`". Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // Look up the existing "Power editor" role to patch. const allRoles = await client.roles.list(); const role = allRoles.find((candidate) => candidate.name === "Power editor")!; // Append a negative entry forbidding `delete` to the current environment. const updated = await client.roles.updateCurrentEnvironmentPermissions( role.id, { negative_item_type_permissions: { add: [ { action: "delete", on_creator: "anyone", }, ], }, }, ); console.log("Updated role:", updated.id, "—", updated.name); console.log( "Negative permissions now:", JSON.stringify(updated.negative_item_type_permissions, null, 2), ); } run(); ``` Returned output ```javascript Updated role: 443075 — Power editor Negative permissions now: [ { "environment": "main", "item_type": null, "workflow": null, "on_stage": null, "to_stage": null, "action": "delete", "on_creator": "anyone", "localization_scope": null, "locale": null } ] ``` ## Effects on bound credentials Changes take effect immediately for every credential bound to this role: collaborators, SSO users, and API tokens will see new requests evaluated against the updated `meta.final_permissions` on their next call. ## Body parameters **`name`** - Optional - Type: string - Example: `"Editor"` The name of the role **`can_edit_favicon`** - Optional - Type: boolean Can edit favicon, global SEO settings and no-index policy **`can_edit_site`** - Optional - Type: boolean Can change project-wide settings (project name, internal subdomain, frontend preview URL, deployment settings) **`can_edit_schema`** - Optional - Type: boolean Can create and edit the project schema: models, block models, fields, fieldsets, validators, and plugins **`can_manage_menu`** - Optional - Type: boolean Can customize content navigation bar **`can_edit_environment`** - Optional - Type: boolean Can edit per-environment settings of the environments this role has access to: locales, timezone, and UI theme. This is *not* about creating or switching environments — see `can_manage_environments` for that, and `environments_access` for which environments this role can enter at all. **`can_promote_environments`** - Optional - Type: boolean Can promote a sandbox environment to primary (atomic swap) and toggle the project's maintenance mode. Distinct from `can_manage_environments`, which covers creating/forking/deleting sandboxes. **`environments_access`** - Optional - Type: enum - Example: `"primary_only"` Specifies the environments the user can access
Show enum values **`all`** - Optional Grants access to all environments **`primary_only`** - Optional Grants access exclusively to the primary environment **`sandbox_only`** - Optional Grants access exclusively to sandbox environments **`none`** - Optional No access to any environment. This value is typically used when the role is intended to inherit access settings from other roles
**`can_manage_users`** - Optional - Type: boolean Can create and edit roles and invite/remove collaborators **`can_manage_shared_filters`** - Optional - Type: boolean Can create and edit shared filters (both for models and the media area) **`can_manage_search_indexes`** - Optional - Type: boolean Can create and edit search indexes **`can_manage_upload_collections`** - Optional - Type: boolean Can create and edit upload collections **`can_manage_build_triggers`** - Optional - Type: boolean Can create and edit build triggers **`can_manage_webhooks`** - Optional - Type: boolean Can create and edit webhooks **`can_manage_environments`** - Optional - Type: boolean Can create, fork, and delete sandbox environments. Promotion to primary is gated separately by `can_promote_environments`. **`can_manage_sso`** - Optional - Type: boolean Can manage Single Sign-On settings **`can_access_audit_log`** - Optional - Type: boolean Can access Audit Log **`can_manage_workflows`** - Optional - Type: boolean Can create and edit workflows **`can_manage_access_tokens`** - Optional - Type: boolean Can manage API tokens **`can_perform_site_search`** - Optional - Type: boolean Can perform Site Search API calls **`can_access_build_events_log`** - Optional - Type: boolean Can access the build events log **`can_access_search_index_events_log`** - Optional - Type: boolean Can access the search index events log **`positive_item_type_permissions`** - Optional - Type: Array\ Allowed actions on a model (or all) for a role. The shape of each entry depends on the `action` (discriminated union). Idiomatic recipes: - To grant every action, use a single `action: "all"` entry with `localization_scope: "all"`. - To grant a subset (e.g. create+read+update but not delete), prefer a single `action: "all"` entry plus `negative_item_type_permissions` entries for the actions to exclude — instead of listing each allowed action separately.
Show object format when action is "all" **`action`** - Required - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`** - Optional
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Optional - Type: string, null Restrict to moves towards a specific workflow stage.
Show object format when action is "read" **`action`** - Required - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
Show object format when action is "create" **`action`** - Required - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Content under a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "update" or "publish" **`action`** - Required - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`** - Optional **`publish`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Content under a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "duplicate" **`action`** - Required - Type: enum - Example: `"duplicate"` Permitted action
Show enum values **`duplicate`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "delete" or "edit_creator" or "take_over" **`action`** - Required - Type: enum - Example: `"delete"` Permitted action
Show enum values **`delete`** - Optional **`edit_creator`** - Optional **`take_over`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "move_to_stage" **`action`** - Required - Type: enum - Example: `"move_to_stage"` Permitted action
Show enum values **`move_to_stage`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Optional - Type: string, null Restrict to moves towards a specific workflow stage.
**`negative_item_type_permissions`** - Optional - Type: Array\ Prohibited actions on a model (or all) for a role. Negative permissions take precedence and are typically paired with a broader positive `action: "all"` entry to subtract specific actions (e.g. forbid `delete`).
Show object format when action is "all" **`action`** - Required - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`** - Optional
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Optional - Type: string, null Restrict to moves towards a specific workflow stage.
Show object format when action is "read" **`action`** - Required - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
Show object format when action is "create" **`action`** - Required - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Content under a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "update" or "publish" **`action`** - Required - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`** - Optional **`publish`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Content under a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "duplicate" **`action`** - Required - Type: enum - Example: `"duplicate"` Permitted action
Show enum values **`duplicate`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "delete" or "edit_creator" or "take_over" **`action`** - Required - Type: enum - Example: `"delete"` Permitted action
Show enum values **`delete`** - Optional **`edit_creator`** - Optional **`take_over`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "move_to_stage" **`action`** - Required - Type: enum - Example: `"move_to_stage"` Permitted action
Show enum values **`move_to_stage`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Optional - Type: string, null Restrict to moves towards a specific workflow stage.
**`positive_upload_permissions`** - Optional - Type: Array\ Allowed actions on uploads (or all) for a role. The shape of each entry depends on the `action` (discriminated union). To grant a subset, prefer a single `action: "all"` entry plus `negative_upload_permissions` entries for the actions to exclude.
Show object format when action is "all" **`action`** - Required - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`** - Optional
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "update" **`action`** - Required - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Localized content in a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "create" **`action`** - Required - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "read" or "delete" or "edit_creator" or "replace_asset" **`action`** - Required - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`** - Optional **`delete`** - Optional **`edit_creator`** - Optional **`replace_asset`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "move" **`action`** - Required - Type: enum - Example: `"move"` Permitted action
Show enum values **`move`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`move_to_upload_collection`** - Optional - Type: string, null Restricts the destination upload collection of the move action. When `null`, any destination is allowed.
**`negative_upload_permissions`** - Optional - Type: Array\ Prohibited actions on uploads (or all) for a role. Negative permissions take precedence and are typically paired with a broader positive `action: "all"` entry to subtract specific actions.
Show object format when action is "all" **`action`** - Required - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`** - Optional
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "update" **`action`** - Required - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Localized content in a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "create" **`action`** - Required - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "read" or "delete" or "edit_creator" or "replace_asset" **`action`** - Required - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`** - Optional **`delete`** - Optional **`edit_creator`** - Optional **`replace_asset`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "move" **`action`** - Required - Type: enum - Example: `"move"` Permitted action
Show enum values **`move`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`move_to_upload_collection`** - Optional - Type: string, null Restricts the destination upload collection of the move action. When `null`, any destination is allowed.
**`positive_build_trigger_permissions`** - Optional - Type: Array\ Build triggers this role is allowed to **manually fire**. An entry with `build_trigger: null` covers every build trigger. Note: this does not control creating/editing build triggers themselves — that is gated by `can_manage_build_triggers`.
Show objects format inside array **`build_trigger`** - Optional - Type: string, null
**`negative_build_trigger_permissions`** - Optional - Type: Array\ Build triggers this role is **forbidden** from manually firing. Negative entries take precedence over positive ones; pair with a `build_trigger: null` positive entry to allow all-but-N.
Show objects format inside array **`build_trigger`** - Optional - Type: string, null
**`positive_search_index_permissions`** - Optional - Type: Array\ Search indexes this role is allowed to **manually re-index**. An entry with `search_index: null` covers every search index. Note: this does not control creating/editing search indexes themselves — that is gated by `can_manage_search_indexes`.
Show objects format inside array **`search_index`** - Optional - Type: string, null
**`negative_search_index_permissions`** - Optional - Type: Array\ Search indexes this role is **forbidden** from manually re-indexing. Negative entries take precedence over positive ones; pair with a `search_index: null` positive entry to allow all-but-N.
Show objects format inside array **`search_index`** - Optional - Type: string, null
**`meta.final_permissions`** - Optional - Type: object The final set of permissions considering also inherited roles
Show object format **`can_edit_site`** - Required - Type: boolean Can change project-wide settings (project name, internal subdomain, frontend preview URL, deployment settings) **`can_edit_favicon`** - Required - Type: boolean Can edit favicon, global SEO settings and no-index policy **`can_edit_schema`** - Required - Type: boolean Can create and edit the project schema: models, block models, fields, fieldsets, validators, and plugins **`can_manage_menu`** - Required - Type: boolean Can customize content navigation bar **`can_manage_users`** - Required - Type: boolean Can create and edit roles and invite/remove collaborators **`can_manage_environments`** - Required - Type: boolean Can create, fork, and delete sandbox environments. Promotion to primary is gated separately by `can_promote_environments`. **`can_manage_webhooks`** - Required - Type: boolean Can create and edit webhooks **`environments_access`** - Required - Type: enum - Example: `"primary_only"` Specifies the environments the user can access
Show enum values **`all`** - Optional Grants access to all environments **`primary_only`** - Optional Grants access exclusively to the primary environment **`sandbox_only`** - Optional Grants access exclusively to sandbox environments **`none`** - Optional No access to any environment. This value is typically used when the role is intended to inherit access settings from other roles
**`can_manage_sso`** - Required - Type: boolean Can manage Single Sign-On settings **`can_access_audit_log`** - Required - Type: boolean Can access Audit Log **`can_manage_workflows`** - Required - Type: boolean Can create and edit workflows **`can_edit_environment`** - Required - Type: boolean Can edit per-environment settings of the environments this role has access to: locales, timezone, and UI theme. This is *not* about creating or switching environments — see `can_manage_environments` for that, and `environments_access` for which environments this role can enter at all. **`can_promote_environments`** - Required - Type: boolean Can promote a sandbox environment to primary (atomic swap) and toggle the project's maintenance mode. Distinct from `can_manage_environments`, which covers creating/forking/deleting sandboxes. **`can_manage_shared_filters`** - Required - Type: boolean Can create and edit shared filters (both for models and the media area) **`can_manage_search_indexes`** - Required - Type: boolean Can create and edit search indexes **`can_manage_build_triggers`** - Required - Type: boolean Can create and edit build triggers **`can_manage_upload_collections`** - Required - Type: boolean Can create and edit upload collections **`can_manage_access_tokens`** - Required - Type: boolean Can manage API tokens **`can_perform_site_search`** - Required - Type: boolean Can perform Site Search API calls **`can_access_build_events_log`** - Required - Type: boolean Can access the build events log **`can_access_search_index_events_log`** - Required - Type: boolean Can access the search index events log **`positive_item_type_permissions`** - Required - Type: Array\ Allowed actions on a model (or all) for a role. The shape of each entry depends on the `action` (discriminated union). Idiomatic recipes: - To grant every action, use a single `action: "all"` entry with `localization_scope: "all"`. - To grant a subset (e.g. create+read+update but not delete), prefer a single `action: "all"` entry plus `negative_item_type_permissions` entries for the actions to exclude — instead of listing each allowed action separately.
Show object format when action is "all" **`action`** - Required - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`** - Optional
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Optional - Type: string, null Restrict to moves towards a specific workflow stage.
Show object format when action is "read" **`action`** - Required - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
Show object format when action is "create" **`action`** - Required - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Content under a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "update" or "publish" **`action`** - Required - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`** - Optional **`publish`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Content under a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "duplicate" **`action`** - Required - Type: enum - Example: `"duplicate"` Permitted action
Show enum values **`duplicate`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "delete" or "edit_creator" or "take_over" **`action`** - Required - Type: enum - Example: `"delete"` Permitted action
Show enum values **`delete`** - Optional **`edit_creator`** - Optional **`take_over`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "move_to_stage" **`action`** - Required - Type: enum - Example: `"move_to_stage"` Permitted action
Show enum values **`move_to_stage`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Optional - Type: string, null Restrict to moves towards a specific workflow stage.
**`negative_item_type_permissions`** - Required - Type: Array\ Prohibited actions on a model (or all) for a role. Negative permissions take precedence and are typically paired with a broader positive `action: "all"` entry to subtract specific actions (e.g. forbid `delete`).
Show object format when action is "all" **`action`** - Required - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`** - Optional
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Optional - Type: string, null Restrict to moves towards a specific workflow stage.
Show object format when action is "read" **`action`** - Required - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`.
Show object format when action is "create" **`action`** - Required - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Content under a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "update" or "publish" **`action`** - Required - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`** - Optional **`publish`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Content under a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "duplicate" **`action`** - Required - Type: enum - Example: `"duplicate"` Permitted action
Show enum values **`duplicate`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "delete" or "edit_creator" or "take_over" **`action`** - Required - Type: enum - Example: `"delete"` Permitted action
Show enum values **`delete`** - Optional **`edit_creator`** - Optional **`take_over`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage.
Show object format when action is "move_to_stage" **`action`** - Required - Type: enum - Example: `"move_to_stage"` Permitted action
Show enum values **`move_to_stage`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`item_type`** - Optional - Type: string, null Restricts the permission to a specific model. When `null`, the permission applies to all models. **`workflow`** - Optional - Type: string, null Restricts the permission to records associated with a specific workflow. Mutually exclusive with `item_type`. **`on_stage`** - Optional - Type: string, null Restrict to records currently on a workflow stage. **`to_stage`** - Optional - Type: string, null Restrict to moves towards a specific workflow stage.
**`positive_upload_permissions`** - Required - Type: Array\ Allowed actions on uploads (or all) for a role. The shape of each entry depends on the `action` (discriminated union). To grant a subset, prefer a single `action: "all"` entry plus `negative_upload_permissions` entries for the actions to exclude.
Show object format when action is "all" **`action`** - Required - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`** - Optional
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "update" **`action`** - Required - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Localized content in a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "create" **`action`** - Required - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "read" or "delete" or "edit_creator" or "replace_asset" **`action`** - Required - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`** - Optional **`delete`** - Optional **`edit_creator`** - Optional **`replace_asset`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "move" **`action`** - Required - Type: enum - Example: `"move"` Permitted action
Show enum values **`move`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`move_to_upload_collection`** - Optional - Type: string, null Restricts the destination upload collection of the move action. When `null`, any destination is allowed.
**`negative_upload_permissions`** - Required - Type: Array\ Prohibited actions on uploads (or all) for a role. Negative permissions take precedence and are typically paired with a broader positive `action: "all"` entry to subtract specific actions.
Show object format when action is "all" **`action`** - Required - Type: enum - Example: `"all"` Permitted action
Show enum values **`all`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` For `action: "all"` this must be `"all"`.
Show enum values **`all`** - Optional
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "update" **`action`** - Required - Type: enum - Example: `"update"` Permitted action
Show enum values **`update`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`localization_scope`** - Required - Type: enum - Example: `"all"` Permitted content scope
Show enum values **`all`** - Optional Any content (localized/unlocalized) **`localized`** - Optional Localized content in a specific locale (`locale` must be defined) **`not_localized`** - Optional Non-localized content
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`locale`** - Optional - Type: string, null - Example: `"en"` Required (non-null) when `localization_scope` is `"localized"`; must be omitted otherwise.
Show object format when action is "create" **`action`** - Required - Type: enum - Example: `"create"` Permitted action
Show enum values **`create`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "read" or "delete" or "edit_creator" or "replace_asset" **`action`** - Required - Type: enum - Example: `"read"` Permitted action
Show enum values **`read`** - Optional **`delete`** - Optional **`edit_creator`** - Optional **`replace_asset`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections.
Show object format when action is "move" **`action`** - Required - Type: enum - Example: `"move"` Permitted action
Show enum values **`move`** - Optional
**`environment`** - Required - Type: string - Example: `"main"` ID of environment. Can only contain lowercase letters, numbers and dashes **`on_creator`** - Required - Type: enum - Example: `"anyone"` Permitted creator
Show enum values **`anyone`** - Optional Created by anyone **`self`** - Optional Created by the user itself **`role`** - Optional Created by a user with the same role
**`upload_collection`** - Optional - Type: string, null Restricts the permission to a specific upload collection. When `null`, the permission applies to all collections. **`move_to_upload_collection`** - Optional - Type: string, null Restricts the destination upload collection of the move action. When `null`, any destination is allowed.
**`positive_build_trigger_permissions`** - Required - Type: Array\ Build triggers this role is allowed to **manually fire**. An entry with `build_trigger: null` covers every build trigger. Note: this does not control creating/editing build triggers themselves — that is gated by `can_manage_build_triggers`.
Show objects format inside array **`build_trigger`** - Optional - Type: string, null
**`negative_build_trigger_permissions`** - Required - Type: Array\ Build triggers this role is **forbidden** from manually firing. Negative entries take precedence over positive ones; pair with a `build_trigger: null` positive entry to allow all-but-N.
Show objects format inside array **`build_trigger`** - Optional - Type: string, null
**`positive_search_index_permissions`** - Required - Type: Array\ Search indexes this role is allowed to **manually re-index**. An entry with `search_index: null` covers every search index. Note: this does not control creating/editing search indexes themselves — that is gated by `can_manage_search_indexes`.
Show objects format inside array **`search_index`** - Optional - Type: string, null
**`negative_search_index_permissions`** - Required - Type: Array\ Search indexes this role is **forbidden** from manually re-indexing. Negative entries take precedence over positive ones; pair with a `search_index: null` positive entry to allow all-but-N.
Show objects format inside array **`search_index`** - Optional - Type: string, null
**`inherits_permissions_from`** - Optional - Type: Array<[ResourceLinkage\<"role"\>](https://www-draft.datocms.com/docs/content-management-api/resources/role.md)> The roles from which this role inherits permissions ## Returns Returns a resource object of type [role](/docs/content-management-api/resources/role.md) --- # Content Management API — List all roles Source [docs]: https://www.datocms.com/docs/content-management-api/resources/role/instances.md Lists every role defined on the project, including the built-in factory roles (e.g. *Admin*, *Editor*) and any custom ones. Each entry includes both the directly-declared `attributes` and the inheritance-aware `meta.final_permissions` (see the [Retrieve a role](/docs/content-management-api/resources/role/self.md) endpoint for the difference). ## Returns Returns an array of resource objects of type [role](/docs/content-management-api/resources/role.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const roles = await client.roles.list(); for (const role of roles) { // Check the 'Returned output' tab for the result ☝️ console.log(role); } } run(); ``` Returned output ```javascript { id: "34", name: "Editor", can_edit_site: true, can_edit_favicon: true, can_edit_schema: true, can_manage_menu: true, can_manage_users: true, can_manage_shared_filters: true, can_manage_search_indexes: true, can_manage_upload_collections: true, can_manage_environments: true, can_manage_webhooks: true, environments_access: "primary_only", can_manage_sso: true, can_access_audit_log: true, can_manage_workflows: true, can_edit_environment: true, can_promote_environments: true, can_manage_build_triggers: true, can_manage_access_tokens: true, can_perform_site_search: true, can_access_build_events_log: true, can_access_search_index_events_log: true, positive_item_type_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "create", environment: "main", localization_scope: "all" }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "duplicate", environment: "main" }, { action: "delete", environment: "main", on_creator: "anyone" }, { action: "move_to_stage", environment: "main", on_creator: "anyone" }, ], negative_item_type_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "create", environment: "main", localization_scope: "all" }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "duplicate", environment: "main" }, { action: "delete", environment: "main", on_creator: "anyone" }, { action: "move_to_stage", environment: "main", on_creator: "anyone" }, ], positive_upload_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "create", environment: "main" }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "move", environment: "main", on_creator: "anyone" }, ], negative_upload_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "create", environment: "main" }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "move", environment: "main", on_creator: "anyone" }, ], positive_build_trigger_permissions: [{}], negative_build_trigger_permissions: [{}], positive_search_index_permissions: [{}], negative_search_index_permissions: [{}], meta: { final_permissions: { can_edit_site: true, can_edit_favicon: true, can_edit_schema: true, can_manage_menu: true, can_manage_users: true, can_manage_environments: true, can_manage_webhooks: true, environments_access: "primary_only", can_manage_sso: true, can_access_audit_log: true, can_manage_workflows: true, can_edit_environment: true, can_promote_environments: true, can_manage_shared_filters: true, can_manage_search_indexes: true, can_manage_build_triggers: true, can_manage_upload_collections: true, can_manage_access_tokens: true, can_perform_site_search: true, can_access_build_events_log: true, can_access_search_index_events_log: true, positive_item_type_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "create", environment: "main", localization_scope: "all" }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "duplicate", environment: "main" }, { action: "delete", environment: "main", on_creator: "anyone" }, { action: "move_to_stage", environment: "main", on_creator: "anyone" }, ], negative_item_type_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "create", environment: "main", localization_scope: "all" }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "duplicate", environment: "main" }, { action: "delete", environment: "main", on_creator: "anyone" }, { action: "move_to_stage", environment: "main", on_creator: "anyone" }, ], positive_upload_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "create", environment: "main" }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "move", environment: "main", on_creator: "anyone" }, ], negative_upload_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "create", environment: "main" }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "move", environment: "main", on_creator: "anyone" }, ], positive_build_trigger_permissions: [{}], negative_build_trigger_permissions: [{}], positive_search_index_permissions: [{}], negative_search_index_permissions: [{}], }, }, inherits_permissions_from: [{ type: "role", id: "34" }], } ``` --- # Content Management API — Retrieve a role Source [docs]: https://www.datocms.com/docs/content-management-api/resources/role/self.md Returns a single role by id. The response includes both the directly-declared `attributes.*` and the inheritance-aware `meta.final_permissions` — see the [Role resource overview](/docs/content-management-api/resources/role.md#effective-vs-declared-permissions) for the difference between the two. ## Returns Returns a resource object of type [role](/docs/content-management-api/resources/role.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const roleId = "34"; const role = await client.roles.find(roleId); // Check the 'Returned output' tab for the result ☝️ console.log(role); } run(); ``` Returned output ```javascript { id: "34", name: "Editor", can_edit_site: true, can_edit_favicon: true, can_edit_schema: true, can_manage_menu: true, can_manage_users: true, can_manage_shared_filters: true, can_manage_search_indexes: true, can_manage_upload_collections: true, can_manage_environments: true, can_manage_webhooks: true, environments_access: "primary_only", can_manage_sso: true, can_access_audit_log: true, can_manage_workflows: true, can_edit_environment: true, can_promote_environments: true, can_manage_build_triggers: true, can_manage_access_tokens: true, can_perform_site_search: true, can_access_build_events_log: true, can_access_search_index_events_log: true, positive_item_type_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "create", environment: "main", localization_scope: "all" }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "duplicate", environment: "main" }, { action: "delete", environment: "main", on_creator: "anyone" }, { action: "move_to_stage", environment: "main", on_creator: "anyone" }, ], negative_item_type_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "create", environment: "main", localization_scope: "all" }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "duplicate", environment: "main" }, { action: "delete", environment: "main", on_creator: "anyone" }, { action: "move_to_stage", environment: "main", on_creator: "anyone" }, ], positive_upload_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "create", environment: "main" }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "move", environment: "main", on_creator: "anyone" }, ], negative_upload_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "create", environment: "main" }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "move", environment: "main", on_creator: "anyone" }, ], positive_build_trigger_permissions: [{}], negative_build_trigger_permissions: [{}], positive_search_index_permissions: [{}], negative_search_index_permissions: [{}], meta: { final_permissions: { can_edit_site: true, can_edit_favicon: true, can_edit_schema: true, can_manage_menu: true, can_manage_users: true, can_manage_environments: true, can_manage_webhooks: true, environments_access: "primary_only", can_manage_sso: true, can_access_audit_log: true, can_manage_workflows: true, can_edit_environment: true, can_promote_environments: true, can_manage_shared_filters: true, can_manage_search_indexes: true, can_manage_build_triggers: true, can_manage_upload_collections: true, can_manage_access_tokens: true, can_perform_site_search: true, can_access_build_events_log: true, can_access_search_index_events_log: true, positive_item_type_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "create", environment: "main", localization_scope: "all" }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "duplicate", environment: "main" }, { action: "delete", environment: "main", on_creator: "anyone" }, { action: "move_to_stage", environment: "main", on_creator: "anyone" }, ], negative_item_type_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "create", environment: "main", localization_scope: "all" }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "duplicate", environment: "main" }, { action: "delete", environment: "main", on_creator: "anyone" }, { action: "move_to_stage", environment: "main", on_creator: "anyone" }, ], positive_upload_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "create", environment: "main" }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "move", environment: "main", on_creator: "anyone" }, ], negative_upload_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "create", environment: "main" }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "move", environment: "main", on_creator: "anyone" }, ], positive_build_trigger_permissions: [{}], negative_build_trigger_permissions: [{}], positive_search_index_permissions: [{}], negative_search_index_permissions: [{}], }, }, inherits_permissions_from: [{ type: "role", id: "34" }], } ``` --- # Content Management API — Delete a role Source [docs]: https://www.datocms.com/docs/content-management-api/resources/role/destroy.md > [!WARNING] ⚠️ Reassign credentials first > A role cannot be deleted while collaborators, SSO users, or API tokens are still bound to it (nor while it's set as the project's SSO default role). Move every assignee to a different role before calling this endpoint, or the request will be rejected. ## Returns Returns a resource object of type [role](/docs/content-management-api/resources/role.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const roleId = "34"; const role = await client.roles.destroy(roleId); // Check the 'Returned output' tab for the result ☝️ console.log(role); } run(); ``` Returned output ```javascript { id: "34", name: "Editor", can_edit_site: true, can_edit_favicon: true, can_edit_schema: true, can_manage_menu: true, can_manage_users: true, can_manage_shared_filters: true, can_manage_search_indexes: true, can_manage_upload_collections: true, can_manage_environments: true, can_manage_webhooks: true, environments_access: "primary_only", can_manage_sso: true, can_access_audit_log: true, can_manage_workflows: true, can_edit_environment: true, can_promote_environments: true, can_manage_build_triggers: true, can_manage_access_tokens: true, can_perform_site_search: true, can_access_build_events_log: true, can_access_search_index_events_log: true, positive_item_type_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "create", environment: "main", localization_scope: "all" }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "duplicate", environment: "main" }, { action: "delete", environment: "main", on_creator: "anyone" }, { action: "move_to_stage", environment: "main", on_creator: "anyone" }, ], negative_item_type_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "create", environment: "main", localization_scope: "all" }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "duplicate", environment: "main" }, { action: "delete", environment: "main", on_creator: "anyone" }, { action: "move_to_stage", environment: "main", on_creator: "anyone" }, ], positive_upload_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "create", environment: "main" }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "move", environment: "main", on_creator: "anyone" }, ], negative_upload_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "create", environment: "main" }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "move", environment: "main", on_creator: "anyone" }, ], positive_build_trigger_permissions: [{}], negative_build_trigger_permissions: [{}], positive_search_index_permissions: [{}], negative_search_index_permissions: [{}], meta: { final_permissions: { can_edit_site: true, can_edit_favicon: true, can_edit_schema: true, can_manage_menu: true, can_manage_users: true, can_manage_environments: true, can_manage_webhooks: true, environments_access: "primary_only", can_manage_sso: true, can_access_audit_log: true, can_manage_workflows: true, can_edit_environment: true, can_promote_environments: true, can_manage_shared_filters: true, can_manage_search_indexes: true, can_manage_build_triggers: true, can_manage_upload_collections: true, can_manage_access_tokens: true, can_perform_site_search: true, can_access_build_events_log: true, can_access_search_index_events_log: true, positive_item_type_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "create", environment: "main", localization_scope: "all" }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "duplicate", environment: "main" }, { action: "delete", environment: "main", on_creator: "anyone" }, { action: "move_to_stage", environment: "main", on_creator: "anyone" }, ], negative_item_type_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "create", environment: "main", localization_scope: "all" }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "duplicate", environment: "main" }, { action: "delete", environment: "main", on_creator: "anyone" }, { action: "move_to_stage", environment: "main", on_creator: "anyone" }, ], positive_upload_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "create", environment: "main" }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "move", environment: "main", on_creator: "anyone" }, ], negative_upload_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "create", environment: "main" }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "move", environment: "main", on_creator: "anyone" }, ], positive_build_trigger_permissions: [{}], negative_build_trigger_permissions: [{}], positive_search_index_permissions: [{}], negative_search_index_permissions: [{}], }, }, inherits_permissions_from: [{ type: "role", id: "34" }], } ``` --- # Content Management API — Duplicate a role Source [docs]: https://www.datocms.com/docs/content-management-api/resources/role/duplicate.md Creates a new role that copies an existing one — its project-wide flags, `environments_access`, model permissions, upload permissions, build trigger permissions, and the `inherits_permissions_from` relationship are all carried over. This is the most common starting point for a custom role: duplicate the closest-matching built-in role (e.g. *Editor*), then `PUT` the result with the few changes you actually need. Faster and less error-prone than reconstructing a permission tree from scratch. The new role's `name` is automatically suffixed ( `(duplicate #N)`) to keep it unique within the project; rename it via the [Update endpoint](/docs/content-management-api/resources/role/update.md) right after duplicating. ## Returns Returns a resource object of type [role](/docs/content-management-api/resources/role.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const roleId = "34"; const role = await client.roles.duplicate(roleId); // Check the 'Returned output' tab for the result ☝️ console.log(role); } run(); ``` Returned output ```javascript { id: "34", name: "Editor", can_edit_site: true, can_edit_favicon: true, can_edit_schema: true, can_manage_menu: true, can_manage_users: true, can_manage_shared_filters: true, can_manage_search_indexes: true, can_manage_upload_collections: true, can_manage_environments: true, can_manage_webhooks: true, environments_access: "primary_only", can_manage_sso: true, can_access_audit_log: true, can_manage_workflows: true, can_edit_environment: true, can_promote_environments: true, can_manage_build_triggers: true, can_manage_access_tokens: true, can_perform_site_search: true, can_access_build_events_log: true, can_access_search_index_events_log: true, positive_item_type_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "create", environment: "main", localization_scope: "all" }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "duplicate", environment: "main" }, { action: "delete", environment: "main", on_creator: "anyone" }, { action: "move_to_stage", environment: "main", on_creator: "anyone" }, ], negative_item_type_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "create", environment: "main", localization_scope: "all" }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "duplicate", environment: "main" }, { action: "delete", environment: "main", on_creator: "anyone" }, { action: "move_to_stage", environment: "main", on_creator: "anyone" }, ], positive_upload_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "create", environment: "main" }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "move", environment: "main", on_creator: "anyone" }, ], negative_upload_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "create", environment: "main" }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "move", environment: "main", on_creator: "anyone" }, ], positive_build_trigger_permissions: [{}], negative_build_trigger_permissions: [{}], positive_search_index_permissions: [{}], negative_search_index_permissions: [{}], meta: { final_permissions: { can_edit_site: true, can_edit_favicon: true, can_edit_schema: true, can_manage_menu: true, can_manage_users: true, can_manage_environments: true, can_manage_webhooks: true, environments_access: "primary_only", can_manage_sso: true, can_access_audit_log: true, can_manage_workflows: true, can_edit_environment: true, can_promote_environments: true, can_manage_shared_filters: true, can_manage_search_indexes: true, can_manage_build_triggers: true, can_manage_upload_collections: true, can_manage_access_tokens: true, can_perform_site_search: true, can_access_build_events_log: true, can_access_search_index_events_log: true, positive_item_type_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "create", environment: "main", localization_scope: "all" }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "duplicate", environment: "main" }, { action: "delete", environment: "main", on_creator: "anyone" }, { action: "move_to_stage", environment: "main", on_creator: "anyone" }, ], negative_item_type_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "create", environment: "main", localization_scope: "all" }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "duplicate", environment: "main" }, { action: "delete", environment: "main", on_creator: "anyone" }, { action: "move_to_stage", environment: "main", on_creator: "anyone" }, ], positive_upload_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "create", environment: "main" }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "move", environment: "main", on_creator: "anyone" }, ], negative_upload_permissions: [ { action: "all", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "update", environment: "main", on_creator: "anyone", localization_scope: "all", }, { action: "create", environment: "main" }, { action: "read", environment: "main", on_creator: "anyone" }, { action: "move", environment: "main", on_creator: "anyone" }, ], positive_build_trigger_permissions: [{}], negative_build_trigger_permissions: [{}], positive_search_index_permissions: [{}], negative_search_index_permissions: [{}], }, }, inherits_permissions_from: [{ type: "role", id: "34" }], } ``` --- # Content Management API — API token Source [docs]: https://www.datocms.com/docs/content-management-api/resources/access-token.md An API token authenticates programmatic access to a project. Each token combines two layers of access control: 1. A **Role** that defines what actions are permitted (the same Role resource used for human collaborators). 2. A set of **API surface flags** (`can_access_cda`, `can_access_cda_preview`, `can_access_cma`) that gate which APIs the token can hit at all. The token's effective capabilities are the *intersection* of the two. > [!PROTIP] 💡 A CDA-only token can safely reuse a write-capable Role > A token with only `can_access_cda: true` is safe to attach to a Role that grants `update`/`publish`/`delete` — the Content Delivery API exposes no write endpoints, so those actions have no surface to act on. This makes it practical to share a single Role definition between an editor (acting via the dashboard / CMA) and a public read token (used by a frontend / CDA) for the same project. ## Object payload **`id`** - Type: string - Example: `"312"` ID of access_token **`type`** - Type: string Must be exactly `"access_token"`. **`name`** - Type: string - Example: `"Read-only API token"` Name of API token **`hardcoded_type`** - Type: null, string Internal marker for the project's built-in factory tokens (e.g. read-only API token), seeded by DatoCMS when the project is created. Read-only attribute. When non-null, attribute updates are rejected with `NON_EDITABLE_ACCESS_TOKEN`, but the token can still be deleted and regenerated. `null` for any token created via this API. **`can_access_cda`** - Type: boolean Whether this API token can call the Content Delivery API (`graphql.datocms.com`) to fetch **published** content. **`can_access_cda_preview`** - Type: boolean Whether this API token can call the Content Delivery API with the `X-Include-Drafts: true` header to fetch **draft** (current, unpublished) content. There is no separate endpoint — the CDA is a single GraphQL endpoint and this flag governs whether requesting drafts is allowed. **`can_access_cma`** - Type: boolean Whether this API token can access the Content Management API **`last_cma_access`** - Type: enum, null - Example: `"never"` When this API token was last used to access the Content Management API. It returns `null` if the credentials you are using cannot manage the API tokens of the project.
Show enum values **`today`** Today **`yesterday`** Yesterday **`this_week`** This week (Monday-Sunday) **`last_week`** Last week (Monday-Sunday) **`this_month`** This calendar month **`last_month`** Last calendar month **`never`** No recent usage (beyond last month)
**`last_cda_access`** - Type: enum, null - Example: `"never"` When this API token was last used to access the Content Delivery API. It returns `null` if the credentials you are using cannot manage the API tokens of the project.
Show enum values **`today`** Today **`yesterday`** Yesterday **`this_week`** This week (Monday-Sunday) **`last_week`** Last week (Monday-Sunday) **`this_month`** This calendar month **`last_month`** Last calendar month **`never`** No recent usage (beyond last month)
**`token`** - Type: null, string - Example: `"XXXXXXXXXXXXXXX"` The secret value used as the `Authorization: Bearer ` credential. Returned on every endpoint (create, update, retrieve, list, rotate) to callers whose current role has `can_manage_access_tokens`; otherwise `null`. **`role`** - Type: [ResourceLinkage\<"role"\>](https://www-draft.datocms.com/docs/content-management-api/resources/role.md), null Role --- # Content Management API — Create a new API token Source [docs]: https://www.datocms.com/docs/content-management-api/resources/access-token/create.md Creates a new API token for the project. Each token combines a **Role** (which actions are permitted) with a set of **API surface flags** (`can_access_cda`, `can_access_cda_preview`, `can_access_cma`) that gate which APIs the token can call at all. Effective capabilities are the *intersection* of the two layers. > [!POSITIVE] ✅ A CDA-only token + write-capable role is safe by construction > The Content Delivery API has no write endpoints. If a token has `can_access_cda: true` (and/or `can_access_cda_preview: true`) but `can_access_cma: false`, attaching it to a role with `update`/`publish`/`delete` permissions is harmless — those actions have no surface to act on. This is useful when you want to share a single Role definition between an editor (who acts via the dashboard / CMA) and the public-facing read token of the same project (used by a frontend / CDA). The new token's secret is returned in `attributes.token` of the response (and on every subsequent read, as long as the caller has `can_manage_access_tokens`). ## Body parameters **`name`** - Required - Type: string - Example: `"Read-only API token"` Name of API token **`can_access_cda`** - Required - Type: boolean Whether this API token can call the Content Delivery API (`graphql.datocms.com`) to fetch **published** content. **`can_access_cda_preview`** - Required - Type: boolean Whether this API token can call the Content Delivery API with the `X-Include-Drafts: true` header to fetch **draft** (current, unpublished) content. There is no separate endpoint — the CDA is a single GraphQL endpoint and this flag governs whether requesting drafts is allowed. **`can_access_cma`** - Required - Type: boolean Whether this API token can access the Content Management API **`role`** - Required - Type: [ResourceLinkage\<"role"\>](https://www-draft.datocms.com/docs/content-management-api/resources/role.md) Role ## Returns Returns a resource object of type [access\_token](/docs/content-management-api/resources/access-token.md) ## Other examples ###### Example CDA-only token bound to a write-capable role An API token bound to a **write-capable role**, but with the Content Management API surface *closed off*: only `can_access_cda` is enabled. Any attempt to use this token against `site-api.datocms.com` returns 401, while the same token can freely query `graphql.datocms.com` for published content. The role on its own would let a credential edit, publish, and delete records. The CDA has no write endpoints, so attaching it here is harmless: the role's write permissions have no surface to act on. This is the safety-by-construction story called out on the [API token resource overview](/docs/content-management-api/resources/access-token.md). Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // Look up the write-capable role this token will be bound to. const allRoles = await client.roles.list(); const role = allRoles.find( (candidate) => candidate.name === "Editorial team", )!; // Create a token with the full role attached, but with the CMA closed off. // Result: this token can only fetch published content via the CDA — its // role's update/publish/delete capabilities have no surface to act on. const accessToken = await client.accessTokens.create({ name: "Public CDA token", role: { type: "role", id: role.id }, can_access_cda: true, can_access_cda_preview: false, can_access_cma: false, }); console.log("Created token:", accessToken.id, "—", accessToken.name); console.log("Secret value:", accessToken.token); console.log("Effective surfaces: CDA only (CMA disabled)"); } run(); ``` Returned output ```javascript Created token: 407203 — Public CDA token Secret value: 427db8a23d5777bbb5bb363d405380 Effective surfaces: CDA only (CMA disabled) ``` --- # Content Management API — Update an API token Source [docs]: https://www.datocms.com/docs/content-management-api/resources/access-token/update.md Updates an API token's name, role, or API surface flags. The token's secret value is not affected — to rotate it, use the [Rotate API token](/docs/content-management-api/resources/access-token/regenerate-token.md) endpoint. If you omit `relationships` from the payload, the token's existing role is preserved. Send `relationships.role` only when you want to reassign the token to a different role. Changes to the role or surface flags take effect immediately. A request that was permitted under the previous configuration may be rejected on the very next call once the new permissions have been written. > [!WARNING] ⚠️ Hardcoded tokens cannot be edited > The project's built-in factory tokens (those whose `attributes.hardcoded_type` is non-null) reject this endpoint with `NON_EDITABLE_ACCESS_TOKEN`. They can still be deleted or rotated. ## Body parameters **`name`** - Required - Type: string - Example: `"Read-only API token"` Name of API token **`can_access_cda`** - Required - Type: boolean Whether this API token can call the Content Delivery API (`graphql.datocms.com`) to fetch **published** content. **`can_access_cda_preview`** - Required - Type: boolean Whether this API token can call the Content Delivery API with the `X-Include-Drafts: true` header to fetch **draft** (current, unpublished) content. There is no separate endpoint — the CDA is a single GraphQL endpoint and this flag governs whether requesting drafts is allowed. **`can_access_cma`** - Required - Type: boolean Whether this API token can access the Content Management API **`role`** - Optional - Type: [ResourceLinkage\<"role"\>](https://www-draft.datocms.com/docs/content-management-api/resources/role.md) Role ## Returns Returns a resource object of type [access\_token](/docs/content-management-api/resources/access-token.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const accessTokenId = "312"; const accessToken = await client.accessTokens.update(accessTokenId, { id: "312", name: "Read-only API token", can_access_cda: true, can_access_cda_preview: true, can_access_cma: true, }); // Check the 'Returned output' tab for the result ☝️ console.log(accessToken); } run(); ``` Returned output ```javascript { id: "312", name: "Read-only API token", hardcoded_type: "", can_access_cda: true, can_access_cda_preview: true, can_access_cma: true, last_cma_access: "never", last_cda_access: "never", role: { type: "role", id: "34" }, } ``` --- # Content Management API — List all API tokens Source [docs]: https://www.datocms.com/docs/content-management-api/resources/access-token/instances.md Lists every API token defined on the project, including the built-in factory tokens (read-only, full-access, …) seeded by DatoCMS. Each entry's `attributes.token` is included for callers whose role has `can_manage_access_tokens` (and is `null` otherwise). Use `attributes.last_cma_access` / `attributes.last_cda_access` to spot tokens that haven't been used recently and may be safe to revoke. ## Returns Returns an array of resource objects of type [access\_token](/docs/content-management-api/resources/access-token.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const accessTokens = await client.accessTokens.list(); for (const accessToken of accessTokens) { // Check the 'Returned output' tab for the result ☝️ console.log(accessToken); } } run(); ``` Returned output ```javascript { id: "312", name: "Read-only API token", hardcoded_type: "", can_access_cda: true, can_access_cda_preview: true, can_access_cma: true, last_cma_access: "never", last_cda_access: "never", role: { type: "role", id: "34" }, } ``` --- # Content Management API — Retrieve an API token Source [docs]: https://www.datocms.com/docs/content-management-api/resources/access-token/self.md Returns a single API token by id, including its bound role, API surface flags, and — if the caller's role has `can_manage_access_tokens` — the `attributes.token` secret value. Without that permission, `attributes.token` is `null` and the rest of the payload is still returned. ## Returns Returns a resource object of type [access\_token](/docs/content-management-api/resources/access-token.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const accessTokenId = "312"; const accessToken = await client.accessTokens.find(accessTokenId); // Check the 'Returned output' tab for the result ☝️ console.log(accessToken); } run(); ``` Returned output ```javascript { id: "312", name: "Read-only API token", hardcoded_type: "", can_access_cda: true, can_access_cda_preview: true, can_access_cma: true, last_cma_access: "never", last_cda_access: "never", role: { type: "role", id: "34" }, } ``` --- # Content Management API — Rotate API token Source [docs]: https://www.datocms.com/docs/content-management-api/resources/access-token/regenerate_token.md Rotates the secret value of an API token. The role and API surface flags are preserved; only the `attributes.token` value changes. > [!WARNING] ⚠️ The previous secret is invalidated immediately > Any client still using the old value will start receiving `401 Unauthorized` on its very next request. Rotate during a deploy window where you can ship the new secret to all consumers atomically, or accept a brief outage for any caller you forget to update. The new secret is returned in `attributes.token` of the response (and on every subsequent read, as long as the caller has `can_manage_access_tokens`). ## Returns Returns a resource object of type [access\_token](/docs/content-management-api/resources/access-token.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const accessTokenId = "312"; const accessToken = await client.accessTokens.regenerateToken(accessTokenId); // Check the 'Returned output' tab for the result ☝️ console.log(accessToken); } run(); ``` Returned output ```javascript { id: "312", name: "Read-only API token", hardcoded_type: "", can_access_cda: true, can_access_cda_preview: true, can_access_cma: true, last_cma_access: "never", last_cda_access: "never", role: { type: "role", id: "34" }, } ``` --- # Content Management API — Delete an API token Source [docs]: https://www.datocms.com/docs/content-management-api/resources/access-token/destroy.md Deletes an API token. The secret is invalidated immediately and any client still using it will receive `401 Unauthorized` on its next request. API tokens are first-class users in DatoCMS — they can own records, uploads, filters, and editing sessions. When the token to delete owns any such resources, the request **must** specify a destination owner via the `destination_user_type` (`user`, `sso_user`, `access_token`, or `account`) and `destination_user_id` query parameters; ownership is transferred to that user before the token is removed. If the token owns nothing, the parameters can be omitted. A token cannot delete itself — this endpoint rejects requests authenticated with the very token being destroyed (`CANNOT_DESTROY_CURRENT_USER`). Use a different credential to revoke it. ## Query parameters **`destination_user_type`** - Type: enum - Example: `"account"` New owner for resources previously owned by the deleted access token. This argument specifies the new owner type. Use `account` or `organization` to reassign to the project's owner — `client.site.find().owner` returns the right type/id pair to pass.
Show enum values **`account`** **`organization`** **`user`** **`access_token`** **`sso_user`**
**`destination_user_id`** - Type: string - Example: `"7865"` New owner for resources previously owned by the deleted access token. This argument specifies the new owner ID. ## Returns Returns a resource object of type [access\_token](/docs/content-management-api/resources/access-token.md) ## Other examples ###### Example Delete a token and reassign its owned resources An API token may own resources — records it created, uploads it pushed, shared filters, editing sessions. Deleting the token transfers ownership of those resources to the user identified by the `destination_user_type` + `destination_user_id` query parameters before destroying the token. This example reassigns to the project's **owner** — `client.site.find().owner` is always present and returns the `account` or `organization` directly, so it works as a universal fallback. Set `destination_user_type` to `user`, `sso_user`, or `access_token` instead to reassign to a specific collaborator or sibling token. If you skip the parameters and the token still owns resources, the deletion will leave them orphaned. Always pass a destination unless you've verified the token owns nothing. Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // Look up the token we want to retire. const allTokens = await client.accessTokens.list(); const tokenToDelete = allTokens.find( (candidate) => candidate.name === "Legacy CI token", )!; // The project's owner — an account or an organization — is always present // and is the safest fallback destination for orphaned resources. const site = await client.site.find(); await client.accessTokens.destroy(tokenToDelete.id, { destination_user_type: site.owner.type, destination_user_id: site.owner.id, }); console.log( `Deleted token ${tokenToDelete.id}; resources transferred to ${site.owner.type} ${site.owner.id}.`, ); } run(); ``` Returned output ```javascript Deleted token 407202; resources transferred to organization 628404. ``` --- # Content Management API — Webhook Source [docs]: https://www.datocms.com/docs/content-management-api/resources/webhook.md A webhook allows to make requests following certain Dato events. It is linked to a Role, which describes what actions can be performed. ## Object payload **`id`** - Type: string - Example: `"312"` ID of webhook **`type`** - Type: string Must be exactly `"webhook"`. **`name`** - Type: string - Example: `"Item type creation/update"` Unique name for the webhook **`url`** - Type: string - Example: `"https://www.example.com/webhook"` The URL to be called **`enabled`** - Type: boolean Whether the webhook is enabled and sending events or not **`headers`** - Type: null, object - Example: `{ "X-Foo": "Bar" }` Additional headers that will be sent. It returns `null` if the credentials you are using cannot manage the webhooks of the project. **`events`** - Type: Array\
Show objects format inside array **`entity_type`** - Type: enum - Example: `"item"` The subject of webhook triggering
Show enum values **`item_type`** **`item`** **`upload`** **`build_trigger`** **`environment`** **`maintenance_mode`** **`sso_user`** **`cda_cache_tags`**
**`event_types`** - Type: Array\ **`filters`** - Type: Array\, null
Show objects format inside array **`entity_type`** - Type: enum
Show enum values **`item_type`** **`item`** **`build_trigger`** **`environment`** **`environment_type`**
**`entity_ids`** - Type: Array\
**`http_basic_user`** - Type: string, null - Example: `"user"` HTTP Basic Authorization username **`http_basic_password`** - Type: string, null - Example: `"password"` HTTP Basic Authorization password. It is `null` when the webhook has no basic auth, or when the credentials you are using cannot manage the webhooks of the project. **`custom_payload`** - Type: string, null - Example: `'{ "message": "{{event_type}} event triggered on {{entity_type}}!", "entity_id": "{{#entity}}{{id}}{{/entity}}"] }'` A custom payload **`payload_api_version`** - Type: string - Example: `"3"` Specifies which API version to use when serializing entities in the webhook payload **`nested_items_in_payload`** - Type: boolean Whether the you want records present in the payload to show blocks expanded or not **`auto_retry`** - Type: boolean If enabled, the system will attempt to retry the call several times when the webhook operation fails due to timeouts or errors. --- # Content Management API — Create a new webhook Source [docs]: https://www.datocms.com/docs/content-management-api/resources/webhook/create.md ## Body parameters **`name`** - Required - Type: string - Example: `"Item type creation/update"` Unique name for the webhook **`url`** - Required - Type: string - Example: `"https://www.example.com/webhook"` The URL to be called **`headers`** - Required - Type: object - Example: `{ "X-Foo": "Bar" }` Additional headers that will be sent **`events`** - Required - Type: Array\
Show objects format inside array **`entity_type`** - Required - Type: enum - Example: `"item"` The subject of webhook triggering
Show enum values **`item_type`** - Optional **`item`** - Optional **`upload`** - Optional **`build_trigger`** - Optional **`environment`** - Optional **`maintenance_mode`** - Optional **`sso_user`** - Optional **`cda_cache_tags`** - Optional
**`event_types`** - Required - Type: Array\ **`filters`** - Optional - Type: Array\, null
Show objects format inside array **`entity_type`** - Required - Type: enum
Show enum values **`item_type`** - Optional **`item`** - Optional **`build_trigger`** - Optional **`environment`** - Optional **`environment_type`** - Optional
**`entity_ids`** - Required - Type: Array\
**`custom_payload`** - Required - Type: string, null - Example: `'{ "message": "{{event_type}} event triggered on {{entity_type}}!", "entity_id": "{{#entity}}{{id}}{{/entity}}"] }'` A custom payload **`http_basic_user`** - Required - Type: string, null - Example: `"user"` HTTP Basic Authorization username **`http_basic_password`** - Required - Type: string, null - Example: `"password"` HTTP Basic Authorization password. It is `null` when the webhook has no basic auth, or when the credentials you are using cannot manage the webhooks of the project. **`enabled`** - Optional - Type: boolean Whether the webhook is enabled and sending events or not **`payload_api_version`** - Optional - Type: string - Example: `"3"` Specifies which API version to use when serializing entities in the webhook payload **`nested_items_in_payload`** - Optional - Type: boolean Whether the you want records present in the payload to show blocks expanded or not **`auto_retry`** - Optional - Type: boolean If enabled, the system will attempt to retry the call several times when the webhook operation fails due to timeouts or errors. ## Returns Returns a resource object of type [webhook](/docs/content-management-api/resources/webhook.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const webhook = await client.webhooks.create({ name: "Item type creation/update", url: "https://www.example.com/webhook", headers: { "X-Foo": "Bar" }, events: [{ entity_type: "item", event_types: ["update"] }], custom_payload: '{ "message": "{{event_type}} event triggered on {{entity_type}}!", "entity_id": "{{#entity}}{{id}}{{/entity}}"] }', http_basic_user: "user", http_basic_password: "password", }); // Check the 'Returned output' tab for the result ☝️ console.log(webhook); } run(); ``` Returned output ```javascript { id: "312", name: "Item type creation/update", url: "https://www.example.com/webhook", enabled: true, headers: { "X-Foo": "Bar" }, events: [{ entity_type: "item", event_types: ["update"] }], http_basic_user: "user", http_basic_password: "password", custom_payload: '{ "message": "{{event_type}} event triggered on {{entity_type}}!", "entity_id": "{{#entity}}{{id}}{{/entity}}"] }', payload_api_version: "3", nested_items_in_payload: true, auto_retry: true, } ``` --- # Content Management API — Update a webhook Source [docs]: https://www.datocms.com/docs/content-management-api/resources/webhook/update.md ## Body parameters **`name`** - Optional - Type: string - Example: `"Item type creation/update"` Unique name for the webhook **`url`** - Optional - Type: string - Example: `"https://www.example.com/webhook"` The URL to be called **`custom_payload`** - Optional - Type: string, null - Example: `'{ "message": "{{event_type}} event triggered on {{entity_type}}!", "entity_id": "{{#entity}}{{id}}{{/entity}}"] }'` A custom payload **`headers`** - Optional - Type: object - Example: `{ "X-Foo": "Bar" }` Additional headers that will be sent **`events`** - Optional - Type: Array\
Show objects format inside array **`entity_type`** - Required - Type: enum - Example: `"item"` The subject of webhook triggering
Show enum values **`item_type`** - Optional **`item`** - Optional **`upload`** - Optional **`build_trigger`** - Optional **`environment`** - Optional **`maintenance_mode`** - Optional **`sso_user`** - Optional **`cda_cache_tags`** - Optional
**`event_types`** - Required - Type: Array\ **`filters`** - Optional - Type: Array\, null
Show objects format inside array **`entity_type`** - Required - Type: enum
Show enum values **`item_type`** - Optional **`item`** - Optional **`build_trigger`** - Optional **`environment`** - Optional **`environment_type`** - Optional
**`entity_ids`** - Required - Type: Array\
**`http_basic_user`** - Optional - Type: string, null - Example: `"user"` HTTP Basic Authorization username **`http_basic_password`** - Optional - Type: string, null - Example: `"password"` HTTP Basic Authorization password. It is `null` when the webhook has no basic auth, or when the credentials you are using cannot manage the webhooks of the project. **`enabled`** - Optional - Type: boolean Whether the webhook is enabled and sending events or not **`payload_api_version`** - Optional - Type: string - Example: `"3"` Specifies which API version to use when serializing entities in the webhook payload **`nested_items_in_payload`** - Optional - Type: boolean Whether the you want records present in the payload to show blocks expanded or not **`auto_retry`** - Optional - Type: boolean If enabled, the system will attempt to retry the call several times when the webhook operation fails due to timeouts or errors. ## Returns Returns a resource object of type [webhook](/docs/content-management-api/resources/webhook.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const webhookId = "312"; const webhook = await client.webhooks.update(webhookId, { id: "312" }); // Check the 'Returned output' tab for the result ☝️ console.log(webhook); } run(); ``` Returned output ```javascript { id: "312", name: "Item type creation/update", url: "https://www.example.com/webhook", enabled: true, headers: { "X-Foo": "Bar" }, events: [{ entity_type: "item", event_types: ["update"] }], http_basic_user: "user", http_basic_password: "password", custom_payload: '{ "message": "{{event_type}} event triggered on {{entity_type}}!", "entity_id": "{{#entity}}{{id}}{{/entity}}"] }', payload_api_version: "3", nested_items_in_payload: true, auto_retry: true, } ``` --- # Content Management API — List all webhooks Source [docs]: https://www.datocms.com/docs/content-management-api/resources/webhook/instances.md ## Returns Returns an array of resource objects of type [webhook](/docs/content-management-api/resources/webhook.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const webhooks = await client.webhooks.list(); for (const webhook of webhooks) { // Check the 'Returned output' tab for the result ☝️ console.log(webhook); } } run(); ``` Returned output ```javascript { id: "312", name: "Item type creation/update", url: "https://www.example.com/webhook", enabled: true, headers: { "X-Foo": "Bar" }, events: [{ entity_type: "item", event_types: ["update"] }], http_basic_user: "user", http_basic_password: "password", custom_payload: '{ "message": "{{event_type}} event triggered on {{entity_type}}!", "entity_id": "{{#entity}}{{id}}{{/entity}}"] }', payload_api_version: "3", nested_items_in_payload: true, auto_retry: true, } ``` --- # Content Management API — Retrieve a webhook Source [docs]: https://www.datocms.com/docs/content-management-api/resources/webhook/self.md ## Returns Returns a resource object of type [webhook](/docs/content-management-api/resources/webhook.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const webhookId = "312"; const webhook = await client.webhooks.find(webhookId); // Check the 'Returned output' tab for the result ☝️ console.log(webhook); } run(); ``` Returned output ```javascript { id: "312", name: "Item type creation/update", url: "https://www.example.com/webhook", enabled: true, headers: { "X-Foo": "Bar" }, events: [{ entity_type: "item", event_types: ["update"] }], http_basic_user: "user", http_basic_password: "password", custom_payload: '{ "message": "{{event_type}} event triggered on {{entity_type}}!", "entity_id": "{{#entity}}{{id}}{{/entity}}"] }', payload_api_version: "3", nested_items_in_payload: true, auto_retry: true, } ``` --- # Content Management API — Delete a webhook Source [docs]: https://www.datocms.com/docs/content-management-api/resources/webhook/destroy.md ## Returns Returns a resource object of type [webhook](/docs/content-management-api/resources/webhook.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const webhookId = "312"; const webhook = await client.webhooks.destroy(webhookId); // Check the 'Returned output' tab for the result ☝️ console.log(webhook); } run(); ``` Returned output ```javascript { id: "312", name: "Item type creation/update", url: "https://www.example.com/webhook", enabled: true, headers: { "X-Foo": "Bar" }, events: [{ entity_type: "item", event_types: ["update"] }], http_basic_user: "user", http_basic_password: "password", custom_payload: '{ "message": "{{event_type}} event triggered on {{entity_type}}!", "entity_id": "{{#entity}}{{id}}{{/entity}}"] }', payload_api_version: "3", nested_items_in_payload: true, auto_retry: true, } ``` --- # Content Management API — Webhook call Source [docs]: https://www.datocms.com/docs/content-management-api/resources/webhook-call.md This represents a log entry in the webhooks activity list, detailing a specific webhook event along with its delivery attempt information. ## Object payload **`id`** - Type: string - Example: `"42"` ID of webhook call **`type`** - Type: string Must be exactly `"webhook_call"`. **`entity_type`** - Type: enum - Example: `"item"` The subject of webhook triggering
Show enum values **`item_type`** **`item`** **`upload`** **`build_trigger`** **`environment`** **`maintenance_mode`** **`sso_user`** **`cda_cache_tags`**
**`event_type`** - Type: enum - Example: `"update"` The event that triggers the webhook call
Show enum values **`create`** **`update`** **`delete`** **`publish`** **`unpublish`** **`promote`** **`deploy_started`** **`deploy_succeeded`** **`deploy_failed`** **`change`** **`invalidate`**
**`created_at`** - Type: date-time - Example: `"2016-09-20T18:50:24.914Z"` The moment the event was created **`request_url`** - Type: string - Example: `"https://www.example.com/webhook"` The url that the webhook called **`request_headers`** - Type: object The request's headers Example: ```json { Accept: "*/*", "User-Agent": "DatoCMS (datocms.com)", Authorization: "Basic Y2lhbzptaWFv", "Content-Type": "application/json", } ``` **`request_payload`** - Type: string - Example: `'{"webhook_call_id":"103216210","event_triggered_at":"2024-08-26T12:49:16Z","attempted_auto_retries_count":0,"webhook_id":"28374","site_id":"205","environment":"main","is_environment_primary":true,"entity_type":"maintenance_mode","event_type":"change","entity":{"id":"maintenance_mode","type":"maintenance_mode","attributes":{"active":false}},"related_entities":[]}'` The webhook's request payload is encoded as a string. Use `JSON.parse()` to parse it. **`response_status`** - Type: integer, null - Example: `200` The status of the response **`response_headers`** - Type: object, null The response's headers Example: ```json { via: "1.1 vegur, 1.1 37c0945d19329fccc23efb283d01aa06.cloudfront.net (CloudFront)", date: "Fri, 27 Jul 2018 11:59:20 GMT", server: "gunicorn/19.6.0", } ``` **`response_payload`** - Type: string, null - Example: `"ok"` The body of the response **`attempted_auto_retries_count`** - Type: integer - Example: `2` The number of retries attempted so far **`last_sent_at`** - Type: date-time - Example: `"2016-09-20T18:50:24.914Z"` The last moment the call occurred **`next_retry_at`** - Type: date-time, null - Example: `"2016-09-20T18:50:24.914Z"` The date when the next retry attempt is scheduled to run. If no retry attempt is scheduled, it is set to null **`status`** - Type: enum - Example: `"success"` The current status
Show enum values **`pending`** The delivery attempt is currently in process **`success`** Delivery completed successfully **`failed`** Delivery attempt(s) failed due to errors/timeouts **`rescheduled`** The last delivery attempt failed, a new one will be retried later
**`webhook`** - Type: [ResourceLinkage\<"webhook"\>](https://www-draft.datocms.com/docs/content-management-api/resources/webhook.md) The webhook which has been called --- # Content Management API — List all webhooks calls Source [docs]: https://www.datocms.com/docs/content-management-api/resources/webhook-call/instances.md ## Query parameters **`page`** - Type: object Parameters to control offset-based pagination
Show object format **`offset`** - Type: integer The (zero-based) offset of the first entity returned in the collection (defaults to 0) **`limit`** - Type: integer The maximum number of entities to return (defaults to 30, maximum is 500)
**`filter`** - Type: object Attributes to filter
Show object format **`ids`** - Type: string - Example: `"42,554"` IDs to fetch, comma separated **`fields`** - Type: object
Show object format **`webhook_id`** - Type: object
Show object format **`eq`** - Type: string
**`entity_type`** - Type: object
Show object format **`eq`** - Type: enum - Example: `"item"` The subject of webhook triggering
Show enum values **`item_type`** **`item`** **`upload`** **`build_trigger`** **`environment`** **`maintenance_mode`** **`sso_user`** **`cda_cache_tags`**
**`event_type`** - Type: object
Show object format **`eq`** - Type: enum - Example: `"update"` The event that triggers the webhook call
Show enum values **`create`** **`update`** **`delete`** **`publish`** **`unpublish`** **`promote`** **`deploy_started`** **`deploy_succeeded`** **`deploy_failed`** **`change`** **`invalidate`**
**`status`** - Type: object
Show object format **`eq`** - Type: enum - Example: `"success"` The current status
Show enum values **`pending`** The delivery attempt is currently in process **`success`** Delivery completed successfully **`failed`** Delivery attempt(s) failed due to errors/timeouts **`rescheduled`** The last delivery attempt failed, a new one will be retried later
**`last_sent_at`** - Type: object
Show object format **`gt`** - Type: date-time **`lt`** - Type: date-time
**`next_retry_at`** - Type: object
Show object format **`gt`** - Type: date-time **`lt`** - Type: date-time
**`created_at`** - Type: object
Show object format **`gt`** - Type: date-time **`lt`** - Type: date-time
**`order_by`** - Type: enum - Example: `"created_at_desc"` Fields used to order results
Show enum values **`webhook_id_asc`** **`webhook_id_desc`** **`created_at_asc`** **`created_at_desc`** **`last_sent_at_asc`** **`last_sent_at_desc`** **`next_retry_at_asc`** **`next_retry_at_desc`**
## Returns Returns an array of resource objects of type [webhook\_call](/docs/content-management-api/resources/webhook-call.md) ## Other examples ###### Example List all calls Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const webhookCalls = await client.webhookCalls.list(); console.log(webhookCalls); } run(); ``` Returned output ```javascript [ { id: "84033321", type: "webhook_call", request_url: "https://www.example.com/webhook", request_payload: '{ \ "environment": "main", \ "entity_type": "item", \ "event_type": "create", \ "entity": { \ "id": "Ke9nrZ4iRHWpKbJplG_zdQ", \ "type": "item", \ "attributes": { \ "text_field": "Test" \ }, \ "relationships": { \ "item_type": { \ "data": { \ "id": "Dq4WEbdjStWIeSeH_lBA-Q", \ "type": "item_type" \ } \ }, \ "creator": { \ "data": { \ "id": "104280", \ "type": "account" \ } \ } \ }, \ "meta": { \ "created_at": "2024-04-03T22:47:43.488+01:00", \ "updated_at": "2024-04-03T22:47:43.496+01:00", \ "published_at": "2024-04-03T22:47:43.532+01:00", \ "publication_scheduled_at": null, \ "unpublishing_scheduled_at": null, \ "first_published_at": "2024-04-03T22:47:43.532+01:00", \ "is_valid": true, \ "is_current_version_valid": true, \ "is_published_version_valid": true, \ "status": "published", \ "current_version": "QXuPXVc6SDmXcDh1MnImHQ", \ "stage": null \ } \ }, \ "related_entities": [ \ { \ "id": "Dq4WEbdjStWIeSeH_lBA-Q", \ "type": "item_type", \ "attributes": { \ "name": "Example Model", \ "singleton": true, \ "sortable": false, \ "api_key": "example_model", \ "ordering_direction": null, \ "ordering_meta": null, \ "tree": false, \ "modular_block": false, \ "draft_mode_active": false, \ "all_locales_required": false, \ "collection_appearance": "table", \ "has_singleton_item": true, \ "hint": null, \ "inverse_relationships_enabled": false \ }, \ "relationships": { \ "fields": { \ "data": [ \ { \ "id": "TuzswqxpQXyzJGv_3JtBAA", \ "type": "field" \ } \ ] \ }, \ "fieldsets": { \ "data": [] \ }, \ "singleton_item": { \ "data": { \ "id": "Ke9nrZ4iRHWpKbJplG_zdQ", \ "type": "item" \ } \ }, \ "ordering_field": { \ "data": null \ }, \ "title_field": { \ "data": { \ "id": "TuzswqxpQXyzJGv_3JtBAA", \ "type": "field" \ } \ }, \ "image_preview_field": { \ "data": null \ }, \ "excerpt_field": { \ "data": null \ }, \ "workflow": { \ "data": null \ } \ }, \ "meta": { \ "has_singleton_item": true \ } \ } \ ] \ }', request_headers: { Accept: "*/*", "X-Site-Id": "128378", "User-Agent": "DatoCMS (datocms.com)", "Content-Type": "application/json", "X-Webhook-Id": "27321", "X-Environment": "main", }, response_status: 200, response_headers: { date: "Wed, 03 Apr 2024 21:47:44 GMT", "content-length": "2", }, created_at: "2024-04-03T21:47:44.093Z", response_payload: "OK", entity_type: "item", event_type: "create", webhook: { id: "27321", type: "webhook" }, }, // etc ] ``` ###### Example Filter webhook calls by environment The `webhookCalls.list()` method does NOT support serverside filtering. If you wish to filter the calls by some payload attribute, you must fetch them from the server and then filter them clientside, after decoding their `request_payload` fields with `JSON.parse()`. This example shows how to filter the calls by their environment names. Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { // Make sure the API token has access to the CMA, and is stored securely const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // Which environment to look for const environmentNameToFilterBy = "main"; // Because we can't filter serverside, we'll have to fetch all the calls and then deal with them clientside const iterator = await client.webhookCalls.listPagedIterator(); // Empty array will be filled by the iterator const filteredWebhookCalls = []; // Go through the async iterable one at a time for await (const call of iterator) { // Parse the stringified webhook payload const payload = JSON.parse(call.request_payload); // Only push to the array if the environment matches const environment = payload.environment; if (environment === environmentNameToFilterBy) { filteredWebhookCalls.push(call); } } console.log(filteredWebhookCalls); } run(); ``` Returned output ```javascript [ { id: "84033321", type: "webhook_call", request_url: "https://www.example.com/webhook", request_payload: '{ \ "environment": "main", \ "entity_type": "item", \ "event_type": "create", \ "entity": { \ "id": "Ke9nrZ4iRHWpKbJplG_zdQ", \ "type": "item", \ "attributes": { \ "text_field": "Test" \ }, \ "relationships": { \ "item_type": { \ "data": { \ "id": "Dq4WEbdjStWIeSeH_lBA-Q", \ "type": "item_type" \ } \ }, \ "creator": { \ "data": { \ "id": "104280", \ "type": "account" \ } \ } \ }, \ "meta": { \ "created_at": "2024-04-03T22:47:43.488+01:00", \ "updated_at": "2024-04-03T22:47:43.496+01:00", \ "published_at": "2024-04-03T22:47:43.532+01:00", \ "publication_scheduled_at": null, \ "unpublishing_scheduled_at": null, \ "first_published_at": "2024-04-03T22:47:43.532+01:00", \ "is_valid": true, \ "is_current_version_valid": true, \ "is_published_version_valid": true, \ "status": "published", \ "current_version": "QXuPXVc6SDmXcDh1MnImHQ", \ "stage": null \ } \ }, \ "related_entities": [ \ { \ "id": "Dq4WEbdjStWIeSeH_lBA-Q", \ "type": "item_type", \ "attributes": { \ "name": "Example Model", \ "singleton": true, \ "sortable": false, \ "api_key": "example_model", \ "ordering_direction": null, \ "ordering_meta": null, \ "tree": false, \ "modular_block": false, \ "draft_mode_active": false, \ "all_locales_required": false, \ "collection_appearance": "table", \ "has_singleton_item": true, \ "hint": null, \ "inverse_relationships_enabled": false \ }, \ "relationships": { \ "fields": { \ "data": [ \ { \ "id": "TuzswqxpQXyzJGv_3JtBAA", \ "type": "field" \ } \ ] \ }, \ "fieldsets": { \ "data": [] \ }, \ "singleton_item": { \ "data": { \ "id": "Ke9nrZ4iRHWpKbJplG_zdQ", \ "type": "item" \ } \ }, \ "ordering_field": { \ "data": null \ }, \ "title_field": { \ "data": { \ "id": "TuzswqxpQXyzJGv_3JtBAA", \ "type": "field" \ } \ }, \ "image_preview_field": { \ "data": null \ }, \ "excerpt_field": { \ "data": null \ }, \ "workflow": { \ "data": null \ } \ }, \ "meta": { \ "has_singleton_item": true \ } \ } \ ] \ }', request_headers: { Accept: "*/*", "X-Site-Id": "128378", "User-Agent": "DatoCMS (datocms.com)", "Content-Type": "application/json", "X-Webhook-Id": "27321", "X-Environment": "main", }, response_status: 200, response_headers: { date: "Wed, 03 Apr 2024 21:47:44 GMT", "content-length": "2", }, created_at: "2024-04-03T21:47:44.093Z", response_payload: "OK", entity_type: "item", event_type: "create", webhook: { id: "27321", type: "webhook" }, }, // other calls filtered out, so only this one remains ] ``` --- # Content Management API — Retrieve a webhook call Source [docs]: https://www.datocms.com/docs/content-management-api/resources/webhook-call/self.md ## Returns Returns a resource object of type [webhook\_call](/docs/content-management-api/resources/webhook-call.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const webhookCallId = "42"; const webhookCall = await client.webhookCalls.find(webhookCallId); // Check the 'Returned output' tab for the result ☝️ console.log(webhookCall); } run(); ``` Returned output ```javascript { id: "42", entity_type: "item", event_type: "update", created_at: "2016-09-20T18:50:24.914Z", request_url: "https://www.example.com/webhook", request_headers: { Accept: "*/*", "User-Agent": "DatoCMS (datocms.com)", Authorization: "Basic Y2lhbzptaWFv", "Content-Type": "application/json", }, request_payload: '{"webhook_call_id":"103216210","event_triggered_at":"2024-08-26T12:49:16Z","attempted_auto_retries_count":0,"webhook_id":"28374","site_id":"205","environment":"main","is_environment_primary":true,"entity_type":"maintenance_mode","event_type":"change","entity":{"id":"maintenance_mode","type":"maintenance_mode","attributes":{"active":false}},"related_entities":[]}', response_status: 200, response_headers: { via: "1.1 vegur, 1.1 37c0945d19329fccc23efb283d01aa06.cloudfront.net (CloudFront)", date: "Fri, 27 Jul 2018 11:59:20 GMT", server: "gunicorn/19.6.0", }, response_payload: "ok", attempted_auto_retries_count: 2, last_sent_at: "2016-09-20T18:50:24.914Z", next_retry_at: "2016-09-20T18:50:24.914Z", status: "success", webhook: { type: "webhook", id: "312" }, } ``` --- # Content Management API — Re-send the webhook call Source [docs]: https://www.datocms.com/docs/content-management-api/resources/webhook-call/resend_webhook.md ## Examples ###### Example Basic example ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const webhookCallId = "42"; await client.webhookCalls.resendWebhook(webhookCallId); } run(); ``` --- # Content Management API — Build trigger Source [docs]: https://www.datocms.com/docs/content-management-api/resources/build-trigger.md Configuration for different build triggers. You can have different staging and production environments in order to test your site before final deploy ## Object payload **`id`** - Type: string - Example: `"1822"` ID of build_trigger **`type`** - Type: string Must be exactly `"build_trigger"`. **`name`** - Type: string - Example: `"Custom build trigger"` Name of the build trigger **`adapter`** - Type: enum - Example: `"custom"` The type of build trigger
Show enum values **`custom`** `adapter_settings` must include the following properties: `trigger_url`, `headers` and `payload`. The custom adapter also supports CircleCI webhooks for backward compatibility. **`netlify`** `adapter_settings` must include the following properties: `trigger_url`, `access_token`, `branch`, `site_id` **`vercel`** `adapter_settings` must include the following properties: `project_id`, `token`, `branch`, `team_id`, `deploy_hook_url` **`gitlab`** `adapter_settings` must include the following properties: `trigger_url`, `token`, `ref`, `build_parameters`
**`adapter_settings`** - Type: null, object Additional settings for the build trigger. The value depends on the `adapter`. It returns `null` if the credentials you are using cannot manage the build triggers of the project. Example: ```json { trigger_url: "http://some-url.com/trigger", headers: { Authorization: "Bearer abc123" }, payload: { type: "build_request" }, } ``` **`last_build_completed_at`** - Type: date-time, null - Example: `"2017-03-30T09:29:14.872Z"` Timestamp of the last build **`build_status`** - Type: string - Example: `"success"` Status of last build **`webhook_token`** - Type: null, string - Example: `"xA1239ajsk123"` Unique token for the webhook (it's the same token present in `webhook_url`). It returns `null` if the credentials you are using cannot manage the build triggers of the project. **`webhook_url`** - Type: null, string - Example: `"https://webhooks.datocoms.com/xA1239ajsk123/deploy-results"` The URL of the webhook your service has to call when the build completes to report it's status (success or error). It returns `null` if the credentials you are using cannot manage the build triggers of the project. **`frontend_url`** - Type: string, null - Example: `"https://www.mywebsite.com/"` The public URL of the frontend. **`enabled`** - Type: boolean Whether the build trigger is enabled or not **`autotrigger_on_scheduled_publications`** - Type: boolean Wheter an automatic build request to `webhook_url` should be made on scheduled publications/unpublishings
Show deprecated **`indexing_status`** - Deprecated - Type: string - Example: `"success"` Status of Site Search for the frontend Site Search features have been detached from build triggers. This attribute has no effect anymore: we keep it present for retrocompatibility. If you're programmatically using this field, please get in touch with support@datocms.com **`indexing_enabled`** - Deprecated - Type: boolean Wether Site Search is enabled or not. With Site Search, everytime the website is built, DatoCMS will respider it to get updated content Site Search features have been detached from build triggers. This attribute has no effect anymore: we keep it present for retrocompatibility. If you're programmatically using this field, please get in touch with support@datocms.com
--- # Content Management API — List all build triggers for a site Source [docs]: https://www.datocms.com/docs/content-management-api/resources/build-trigger/instances.md ## Returns Returns an array of resource objects of type [build\_trigger](/docs/content-management-api/resources/build-trigger.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const buildTriggers = await client.buildTriggers.list(); for (const buildTrigger of buildTriggers) { // Check the 'Returned output' tab for the result ☝️ console.log(buildTrigger); } } run(); ``` Returned output ```javascript { id: "1822", name: "Custom build trigger", adapter: "custom", adapter_settings: { trigger_url: "http://some-url.com/trigger", headers: { Authorization: "Bearer abc123" }, payload: { type: "build_request" }, }, last_build_completed_at: "2017-03-30T09:29:14.872Z", build_status: "success", webhook_token: "xA1239ajsk123", webhook_url: "https://webhooks.datocoms.com/xA1239ajsk123/deploy-results", frontend_url: "https://www.mywebsite.com/", enabled: true, autotrigger_on_scheduled_publications: true, } ``` --- # Content Management API — Retrieve a build trigger Source [docs]: https://www.datocms.com/docs/content-management-api/resources/build-trigger/self.md ## Returns Returns a resource object of type [build\_trigger](/docs/content-management-api/resources/build-trigger.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const buildTriggerId = "1822"; const buildTrigger = await client.buildTriggers.find(buildTriggerId); // Check the 'Returned output' tab for the result ☝️ console.log(buildTrigger); } run(); ``` Returned output ```javascript { id: "1822", name: "Custom build trigger", adapter: "custom", adapter_settings: { trigger_url: "http://some-url.com/trigger", headers: { Authorization: "Bearer abc123" }, payload: { type: "build_request" }, }, last_build_completed_at: "2017-03-30T09:29:14.872Z", build_status: "success", webhook_token: "xA1239ajsk123", webhook_url: "https://webhooks.datocoms.com/xA1239ajsk123/deploy-results", frontend_url: "https://www.mywebsite.com/", enabled: true, autotrigger_on_scheduled_publications: true, } ``` --- # Content Management API — Create build trigger Source [docs]: https://www.datocms.com/docs/content-management-api/resources/build-trigger/create.md ## Body parameters **`name`** - Required - Type: string - Example: `"Custom build trigger"` Name of the build trigger **`adapter`** - Required - Type: enum - Example: `"custom"` The type of build trigger
Show enum values **`custom`** - Optional `adapter_settings` must include the following properties: `trigger_url`, `headers` and `payload`. The custom adapter also supports CircleCI webhooks for backward compatibility. **`netlify`** - Optional `adapter_settings` must include the following properties: `trigger_url`, `access_token`, `branch`, `site_id` **`vercel`** - Optional `adapter_settings` must include the following properties: `project_id`, `token`, `branch`, `team_id`, `deploy_hook_url` **`gitlab`** - Optional `adapter_settings` must include the following properties: `trigger_url`, `token`, `ref`, `build_parameters`
**`frontend_url`** - Required - Type: string, null - Example: `"https://www.mywebsite.com/"` The public URL of the frontend. **`adapter_settings`** - Required - Type: object Additional settings for the build trigger. The value depends on the `adapter`. Example: ```json { trigger_url: "http://some-url.com/trigger", headers: { Authorization: "Bearer abc123" }, payload: { type: "build_request" }, } ``` **`autotrigger_on_scheduled_publications`** - Required - Type: boolean Wheter an automatic build request to `webhook_url` should be made on scheduled publications/unpublishings **`webhook_token`** - Optional - Type: string - Example: `"xA1239ajsk123"` Unique token for the webhook (it's the same token present in `webhook_url`) **`enabled`** - Optional - Type: boolean Whether the build trigger is enabled or not
Show deprecated **`indexing_enabled`** - Deprecated - Type: boolean Wether Site Search is enabled or not. With Site Search, everytime the website is built, DatoCMS will respider it to get updated content Site Search features have been detached from build triggers. This attribute has no effect anymore: we keep it present for retrocompatibility. If you're programmatically using this field, please get in touch with support@datocms.com
## Returns Returns a resource object of type [build\_trigger](/docs/content-management-api/resources/build-trigger.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const buildTrigger = await client.buildTriggers.create({ name: "Custom build trigger", adapter: "custom", frontend_url: "https://www.mywebsite.com/", adapter_settings: { trigger_url: "http://some-url.com/trigger", headers: { Authorization: "Bearer abc123" }, payload: { type: "build_request" }, }, autotrigger_on_scheduled_publications: true, }); // Check the 'Returned output' tab for the result ☝️ console.log(buildTrigger); } run(); ``` Returned output ```javascript { id: "1822", name: "Custom build trigger", adapter: "custom", adapter_settings: { trigger_url: "http://some-url.com/trigger", headers: { Authorization: "Bearer abc123" }, payload: { type: "build_request" }, }, last_build_completed_at: "2017-03-30T09:29:14.872Z", build_status: "success", webhook_token: "xA1239ajsk123", webhook_url: "https://webhooks.datocoms.com/xA1239ajsk123/deploy-results", frontend_url: "https://www.mywebsite.com/", enabled: true, autotrigger_on_scheduled_publications: true, } ``` --- # Content Management API — Update build trigger Source [docs]: https://www.datocms.com/docs/content-management-api/resources/build-trigger/update.md ## Body parameters **`name`** - Optional - Type: string - Example: `"Custom build trigger"` Name of the build trigger **`adapter`** - Optional - Type: enum - Example: `"custom"` The type of build trigger
Show enum values **`custom`** - Optional `adapter_settings` must include the following properties: `trigger_url`, `headers` and `payload`. The custom adapter also supports CircleCI webhooks for backward compatibility. **`netlify`** - Optional `adapter_settings` must include the following properties: `trigger_url`, `access_token`, `branch`, `site_id` **`vercel`** - Optional `adapter_settings` must include the following properties: `project_id`, `token`, `branch`, `team_id`, `deploy_hook_url` **`gitlab`** - Optional `adapter_settings` must include the following properties: `trigger_url`, `token`, `ref`, `build_parameters`
**`enabled`** - Optional - Type: boolean Whether the build trigger is enabled or not **`frontend_url`** - Optional - Type: string, null - Example: `"https://www.mywebsite.com/"` The public URL of the frontend. **`autotrigger_on_scheduled_publications`** - Optional - Type: boolean Wheter an automatic build request to `webhook_url` should be made on scheduled publications/unpublishings **`adapter_settings`** - Optional - Type: object Additional settings for the build trigger. The value depends on the `adapter`. Example: ```json { trigger_url: "http://some-url.com/trigger", headers: { Authorization: "Bearer abc123" }, payload: { type: "build_request" }, } ```
Show deprecated **`indexing_enabled`** - Deprecated - Type: boolean Wether Site Search is enabled or not. With Site Search, everytime the website is built, DatoCMS will respider it to get updated content Site Search features have been detached from build triggers. This attribute has no effect anymore: we keep it present for retrocompatibility. If you're programmatically using this field, please get in touch with support@datocms.com
## Returns Returns a resource object of type [build\_trigger](/docs/content-management-api/resources/build-trigger.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const buildTriggerId = "1822"; const buildTrigger = await client.buildTriggers.update(buildTriggerId, { id: "1822", }); // Check the 'Returned output' tab for the result ☝️ console.log(buildTrigger); } run(); ``` Returned output ```javascript { id: "1822", name: "Custom build trigger", adapter: "custom", adapter_settings: { trigger_url: "http://some-url.com/trigger", headers: { Authorization: "Bearer abc123" }, payload: { type: "build_request" }, }, last_build_completed_at: "2017-03-30T09:29:14.872Z", build_status: "success", webhook_token: "xA1239ajsk123", webhook_url: "https://webhooks.datocoms.com/xA1239ajsk123/deploy-results", frontend_url: "https://www.mywebsite.com/", enabled: true, autotrigger_on_scheduled_publications: true, } ``` --- # Content Management API — Trigger a deploy Source [docs]: https://www.datocms.com/docs/content-management-api/resources/build-trigger/trigger.md ## Examples ###### Example Basic example ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const buildTriggerId = "1822"; await client.buildTriggers.trigger(buildTriggerId); } run(); ``` --- # Content Management API — Abort a deploy and mark it as failed Source [docs]: https://www.datocms.com/docs/content-management-api/resources/build-trigger/abort.md ## Examples ###### Example Basic example ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const buildTriggerId = "1822"; await client.buildTriggers.abort(buildTriggerId); } run(); ``` --- # Content Management API — Abort a site search spidering and mark it as failed Source [docs]: https://www.datocms.com/docs/content-management-api/resources/build-trigger/abort_indexing.md ## Examples ###### Example Basic example ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const buildTriggerId = "1822"; await client.buildTriggers.abortIndexing(buildTriggerId); } run(); ``` --- # Content Management API — Trigger a new site search spidering of the website Source [docs]: https://www.datocms.com/docs/content-management-api/resources/build-trigger/reindex.md By default a spidering of the site is performed automatically at the end of a deploy. If you only need the spidering without a deploy, you can trigger it by calling this endpoint. ## Examples ###### Example Basic example ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const buildTriggerId = "1822"; await client.buildTriggers.reindex(buildTriggerId); } run(); ``` --- # Content Management API — Delete a build trigger Source [docs]: https://www.datocms.com/docs/content-management-api/resources/build-trigger/destroy.md ## Returns Returns a resource object of type [build\_trigger](/docs/content-management-api/resources/build-trigger.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const buildTriggerId = "1822"; const buildTrigger = await client.buildTriggers.destroy(buildTriggerId); // Check the 'Returned output' tab for the result ☝️ console.log(buildTrigger); } run(); ``` Returned output ```javascript { id: "1822", name: "Custom build trigger", adapter: "custom", adapter_settings: { trigger_url: "http://some-url.com/trigger", headers: { Authorization: "Bearer abc123" }, payload: { type: "build_request" }, }, last_build_completed_at: "2017-03-30T09:29:14.872Z", build_status: "success", webhook_token: "xA1239ajsk123", webhook_url: "https://webhooks.datocoms.com/xA1239ajsk123/deploy-results", frontend_url: "https://www.mywebsite.com/", enabled: true, autotrigger_on_scheduled_publications: true, } ``` --- # Content Management API — Deploy activity Source [docs]: https://www.datocms.com/docs/content-management-api/resources/build-event.md Represents an event occurred during the deploy process of a build trigger. ## Object payload **`id`** - Type: string - Example: `"34"` ID of menu item **`type`** - Type: string Must be exactly `"build_event"`. **`event_type`** - Type: enum - Example: `"response_success"` The type of activity
Show enum values **`request_success`** Build requested successfully **`request_failure`** Build request failed **`response_success`** Successful build notification **`response_failure`** Failed build notification **`request_aborted`** Build request aborted by user **`response_unprocessable`** Received notification is not valid
**`data`** - Type: object Any details regarding the event Example: ```json { request_body: '{"object_kind":"build","ref":"master","tag":false,"before_sha":"0000000000000000000000000000000000000000","sha":"ecfccf5ea28af900c14b499a2b762e029c7492","build_id":10495,"build_name":"build","build_stage":"test","build_status":"success","build_started_at":"2016-09-20 18:49:22 UTC","build_finished_at":"2016-09-20 18:50:24 UTC","build_duration":62.279854524,"build_allow_failure":false,"project_id":195,"project_id":"Stefano Verna / awesome-website","user":{"id":null,"name":null,"email":null},"commit":{"id":6754,"sha":"ecfccf5ea28af900c6614b499a2b762e029c7492","message":"Update gems\\n","author_name":"Stefano Verna","author_email":"s.verna@datocms.com","status":"success","duration":62,"started_at":"2016-09-20 18:49:22 UTC","finished_at":"2016-09-20 18:50:24 UTC"},"repository":{"name":"awesome-website","url":"git@gitlab.com:stefanoverna/awesome-website.git","description":"","visibility_level":0}}', request_headers: { Via: "1.1 vegur", Host: "webhooks.datocms.com", Origin: null, Version: "HTTP/1.1", Connection: "close", "Connect-Time": "0", "X-Request-Id": "5c1beced-0fe3-4c5b-b45d-68ba4a15b5f3", "X-Gitlab-Event": "Build Hook", "X-Forwarded-For": "46.101.135.219", "X-Request-Start": "1474397424903", "Total-Route-Time": "0", "X-Forwarded-Port": "443", "X-Forwarded-Proto": "https", }, } ``` **`created_at`** - Type: date-time - Example: `"2016-09-20T18:50:24.914Z"` The moment the activity occurred **`build_trigger`** - Type: [ResourceLinkage\<"build_trigger"\>](https://www-draft.datocms.com/docs/content-management-api/resources/build_trigger.md) Source build trigger --- # Content Management API — List all deploy events Source [docs]: https://www.datocms.com/docs/content-management-api/resources/build-event/instances.md ## Query parameters **`page`** - Type: object Parameters to control offset-based pagination
Show object format **`offset`** - Type: integer The (zero-based) offset of the first entity returned in the collection (defaults to 0) **`limit`** - Type: integer The maximum number of entities to return (defaults to 30, maximum is 500)
**`filter`** - Type: object Attributes to filter
Show object format **`ids`** - Type: string - Example: `"42,554"` IDs to fetch, comma separated **`fields`** - Type: object
Show object format **`build_trigger_id`** - Type: object
Show object format **`eq`** - Type: string
**`event_type`** - Type: object
Show object format **`eq`** - Type: enum - Example: `"response_success"` The type of activity
Show enum values **`request_success`** Build requested successfully **`request_failure`** Build request failed **`response_success`** Successful build notification **`response_failure`** Failed build notification **`request_aborted`** Build request aborted by user **`response_unprocessable`** Received notification is not valid
**`created_at`** - Type: object
Show object format **`gt`** - Type: date-time **`lt`** - Type: date-time
**`order_by`** - Type: enum - Example: `"created_at_desc"` Fields used to order results
Show enum values **`build_trigger_id_asc`** **`build_trigger_id_desc`** **`created_at_asc`** **`created_at_desc`** **`event_type_asc`** **`event_type_desc`**
## Returns Returns an array of resource objects of type [build\_event](/docs/content-management-api/resources/build-event.md) ## Examples ###### Example Basic example ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); // iterates over every page of results for await (const buildEvent of client.buildEvents.listPagedIterator()) { // Check the 'Returned output' tab for the result ☝️ console.log(buildEvent); } } run(); ``` --- # Content Management API — Retrieve a deploy event Source [docs]: https://www.datocms.com/docs/content-management-api/resources/build-event/self.md ## Returns Returns a resource object of type [build\_event](/docs/content-management-api/resources/build-event.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const buildEventId = "34"; const buildEvent = await client.buildEvents.find(buildEventId); // Check the 'Returned output' tab for the result ☝️ console.log(buildEvent); } run(); ``` Returned output ```javascript { id: "34", event_type: "response_success", data: { request_body: '{"object_kind":"build","ref":"master","tag":false,"before_sha":"0000000000000000000000000000000000000000","sha":"ecfccf5ea28af900c14b499a2b762e029c7492","build_id":10495,"build_name":"build","build_stage":"test","build_status":"success","build_started_at":"2016-09-20 18:49:22 UTC","build_finished_at":"2016-09-20 18:50:24 UTC","build_duration":62.279854524,"build_allow_failure":false,"project_id":195,"project_id":"Stefano Verna / awesome-website","user":{"id":null,"name":null,"email":null},"commit":{"id":6754,"sha":"ecfccf5ea28af900c6614b499a2b762e029c7492","message":"Update gems\\n","author_name":"Stefano Verna","author_email":"s.verna@datocms.com","status":"success","duration":62,"started_at":"2016-09-20 18:49:22 UTC","finished_at":"2016-09-20 18:50:24 UTC"},"repository":{"name":"awesome-website","url":"git@gitlab.com:stefanoverna/awesome-website.git","description":"","visibility_level":0}}', request_headers: { Via: "1.1 vegur", Host: "webhooks.datocms.com", Origin: null, Version: "HTTP/1.1", Connection: "close", "Connect-Time": "0", "X-Request-Id": "5c1beced-0fe3-4c5b-b45d-68ba4a15b5f3", "X-Gitlab-Event": "Build Hook", "X-Forwarded-For": "46.101.135.219", "X-Request-Start": "1474397424903", "Total-Route-Time": "0", "X-Forwarded-Port": "443", "X-Forwarded-Proto": "https", }, }, created_at: "2016-09-20T18:50:24.914Z", build_trigger: { type: "build_trigger", id: "1822" }, } ``` --- # Content Management API — Subscription limit Source [docs]: https://www.datocms.com/docs/content-management-api/resources/subscription-limit.md ## Object payload **`id`** - Type: string - Example: `"locales"` ID of limit **`type`** - Type: string Must be exactly `"subscription_limit"`. **`code`** - Type: string - Example: `"users"` The codename for the limit **`usage`** - Type: integer - Example: `2` Current usage **`limit`** - Type: integer, null - Example: `10` The actual limit --- # Content Management API — Get all the subscription limits Source [docs]: https://www.datocms.com/docs/content-management-api/resources/subscription-limit/instances.md ## Returns Returns an array of resource objects of type [subscription\_limit](/docs/content-management-api/resources/subscription-limit.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const subscriptionLimits = await client.subscriptionLimits.list(); for (const subscriptionLimit of subscriptionLimits) { // Check the 'Returned output' tab for the result ☝️ console.log(subscriptionLimit); } } run(); ``` Returned output ```javascript { id: "locales", code: "users", usage: 2, limit: 10 } ``` --- # Content Management API — Get a single subscription limit Source [docs]: https://www.datocms.com/docs/content-management-api/resources/subscription-limit/self.md ## Returns Returns a resource object of type [subscription\_limit](/docs/content-management-api/resources/subscription-limit.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const subscriptionLimitId = "locales"; const subscriptionLimit = await client.subscriptionLimits.find(subscriptionLimitId); // Check the 'Returned output' tab for the result ☝️ console.log(subscriptionLimit); } run(); ``` Returned output ```javascript { id: "locales", code: "users", usage: 2, limit: 10 } ``` --- # Content Management API — Subscription feature Source [docs]: https://www.datocms.com/docs/content-management-api/resources/subscription-feature.md ## Object payload **`id`** - Type: string - Example: `"locales"` ID of feature **`type`** - Type: string Must be exactly `"subscription_feature"`. **`code`** - Type: string - Example: `"sso"` The codename for the feature **`enabled`** - Type: boolean Whether the feature is available on the current project **`in_use`** - Type: boolean Whether the project is currently using the feature --- # Content Management API — Get all the subscription features Source [docs]: https://www.datocms.com/docs/content-management-api/resources/subscription-feature/instances.md ## Returns Returns an array of resource objects of type [subscription\_feature](/docs/content-management-api/resources/subscription-feature.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const subscriptionFeatures = await client.subscriptionFeatures.list(); for (const subscriptionFeature of subscriptionFeatures) { // Check the 'Returned output' tab for the result ☝️ console.log(subscriptionFeature); } } run(); ``` Returned output ```javascript { id: "locales", code: "sso", enabled: true } ``` --- # Content Management API — SSO Settings Source [docs]: https://www.datocms.com/docs/content-management-api/resources/sso-settings.md Represents the Single Sign-on settings of the current DatoCMS project ## Object payload **`id`** - Type: string - Example: `"312"` ID **`type`** - Type: string Must be exactly `"sso_settings"`. **`idp_saml_metadata_url`** - Type: null, string - Example: `"https://my-org.oktapreview.com/app/XXXX/sso/saml/metadata"` URL of Identity Provider SAML Metadata endpoint **`scim_base_url`** - Type: string - Example: `"https://sso.datocms.com/scim"` DatoCMS SCIM base URL **`saml_acs_url`** - Type: string - Example: `"https://sso.datocms.com/XXX/saml/consume"` DatoCMS SAML ACS URL **`sp_saml_metadata_url`** - Type: string - Example: `"https://sso.datocms.com/XXX/saml/metadata"` DatoCMS SAML Metadata URL **`sp_saml_base_url`** - Type: string - Example: `"https://sso.datocms.com/XXX/saml"` DatoCMS SAML Base URL **`saml_token`** - Type: string - Example: `"a2a24ae5fbb2d955b1b4fa73f2dd58"` DatoCMS SAML Token **`idp_saml_metadata_xml`** - Type: null, string - Example: `'...'` Identity Provider SAML Metadata **`scim_api_token`** - Type: string - Example: `"as3dasjh1234hj1"` DatoCMS SCIM API Token **`default_role`** - Type: null, [ResourceLinkage\<"role"\>](https://www-draft.datocms.com/docs/content-management-api/resources/role.md) The default role assigned to SSO users that do not belong to any SSO group --- # Content Management API — Retrieve SSO Settings Source [docs]: https://www.datocms.com/docs/content-management-api/resources/sso-settings/self.md ## Returns Returns a resource object of type [sso\_settings](/docs/content-management-api/resources/sso-settings.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const ssoSettings = await client.ssoSettings.find(); // Check the 'Returned output' tab for the result ☝️ console.log(ssoSettings); } run(); ``` Returned output ```javascript { id: "312", idp_saml_metadata_url: "https://my-org.oktapreview.com/app/XXXX/sso/saml/metadata", scim_base_url: "https://sso.datocms.com/scim", saml_acs_url: "https://sso.datocms.com/XXX/saml/consume", sp_saml_metadata_url: "https://sso.datocms.com/XXX/saml/metadata", sp_saml_base_url: "https://sso.datocms.com/XXX/saml", saml_token: "a2a24ae5fbb2d955b1b4fa73f2dd58", default_role: null, } ``` --- # Content Management API — Generate SSO token Source [docs]: https://www.datocms.com/docs/content-management-api/resources/sso-settings/generate_token.md ## Returns Returns a resource object of type [sso\_token](/docs/content-management-api/resources/sso-token.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const ssoSettings = await client.ssoSettings.generateToken(); // Check the 'Returned output' tab for the result ☝️ console.log(ssoSettings); } run(); ``` Returned output ```javascript { id: "312", scim_api_token: "as3dasjh1234hj1" } ``` --- # Content Management API — Update SSO Settings Source [docs]: https://www.datocms.com/docs/content-management-api/resources/sso-settings/update.md ## Body parameters **`idp_saml_metadata_url`** - Optional - Type: null, string - Example: `"https://my-org.oktapreview.com/app/XXXX/sso/saml/metadata"` URL of Identity Provider SAML Metadata endpoint **`idp_saml_metadata_xml`** - Optional - Type: null, string - Example: `'...'` Identity Provider SAML Metadata **`default_role`** - Optional - Type: [ResourceLinkage\<"role"\>](https://www-draft.datocms.com/docs/content-management-api/resources/role.md) The default role assigned to SSO users that do not belong to any SSO group ## Returns Returns a resource object of type [sso\_settings](/docs/content-management-api/resources/sso-settings.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const ssoSettings = await client.ssoSettings.update({}); // Check the 'Returned output' tab for the result ☝️ console.log(ssoSettings); } run(); ``` Returned output ```javascript { id: "312", idp_saml_metadata_url: "https://my-org.oktapreview.com/app/XXXX/sso/saml/metadata", scim_base_url: "https://sso.datocms.com/scim", saml_acs_url: "https://sso.datocms.com/XXX/saml/consume", sp_saml_metadata_url: "https://sso.datocms.com/XXX/saml/metadata", sp_saml_base_url: "https://sso.datocms.com/XXX/saml", saml_token: "a2a24ae5fbb2d955b1b4fa73f2dd58", default_role: null, } ``` --- # Content Management API — SSO User Source [docs]: https://www.datocms.com/docs/content-management-api/resources/sso-user.md A Single Sign-On user exists when a DatoCMS project is connected to an external Identity Provider. An SSO user will not use the standard login procedure but has to go through SAML authentication. It can also be linked to one or more IdP groups. ## Object payload **`id`** - Type: string - Example: `"312"` ID of user **`type`** - Type: string Must be exactly `"sso_user"`. **`username`** - Type: string - Example: `"mark.smith@example.com"` Email **`external_id`** - Type: string, null - Example: `"Ja23ekjhsad"` Identity provider ID. It returns `null` if the credentials you are using cannot manage the SSO users of the project. **`is_active`** - Type: boolean Whether this user is active on the identity provider. De-activated users won't be able to login. **`first_name`** - Type: string, null - Example: `"Mark"` First name **`last_name`** - Type: string, null - Example: `"Smith"` Last name **`meta.last_access`** - Type: date-time, null - Example: `"2018-03-25T21:50:24.914Z"` Date of last reading/interaction. It returns `null` if the credentials you are using cannot manage the SSO users of the project. **`groups`** - Type: Array<[ResourceLinkage\<"sso_group"\>](https://www-draft.datocms.com/docs/content-management-api/resources/sso_group.md)> All the users's groups **`role`** - Type: [ResourceLinkage\<"role"\>](https://www-draft.datocms.com/docs/content-management-api/resources/role.md), null The user role --- # Content Management API — List all users Source [docs]: https://www.datocms.com/docs/content-management-api/resources/sso-user/instances.md ## Returns Returns an array of resource objects of type [sso\_user](/docs/content-management-api/resources/sso-user.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const ssoUsers = await client.ssoUsers.list(); for (const ssoUser of ssoUsers) { // Check the 'Returned output' tab for the result ☝️ console.log(ssoUser); } } run(); ``` Returned output ```javascript { id: "312", username: "mark.smith@example.com", external_id: "Ja23ekjhsad", is_active: true, first_name: "Mark", last_name: "Smith", meta: { last_access: "2018-03-25T21:50:24.914Z" }, groups: [{ type: "sso_group", id: "312" }], role: { type: "role", id: "34" }, } ``` --- # Content Management API — Returns a SSO user Source [docs]: https://www.datocms.com/docs/content-management-api/resources/sso-user/self.md ## Returns Returns a resource object of type [sso\_user](/docs/content-management-api/resources/sso-user.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const userId = "312"; const ssoUser = await client.ssoUsers.find(userId); // Check the 'Returned output' tab for the result ☝️ console.log(ssoUser); } run(); ``` Returned output ```javascript { id: "312", username: "mark.smith@example.com", external_id: "Ja23ekjhsad", is_active: true, first_name: "Mark", last_name: "Smith", meta: { last_access: "2018-03-25T21:50:24.914Z" }, groups: [{ type: "sso_group", id: "312" }], role: { type: "role", id: "34" }, } ``` --- # Content Management API — Copy editors as SSO users Source [docs]: https://www.datocms.com/docs/content-management-api/resources/sso-user/copy_users.md Copy existing users into SSO users ## Returns Returns an array of resource objects of type [sso\_user](/docs/content-management-api/resources/sso-user.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const ssoUsers = await client.ssoUsers.copyUsers(); for (const ssoUser of ssoUsers) { // Check the 'Returned output' tab for the result ☝️ console.log(ssoUser); } } run(); ``` Returned output ```javascript { id: "312", username: "mark.smith@example.com", external_id: "Ja23ekjhsad", is_active: true, first_name: "Mark", last_name: "Smith", meta: { last_access: "2018-03-25T21:50:24.914Z" }, groups: [{ type: "sso_group", id: "312" }], role: { type: "role", id: "34" }, } ``` --- # Content Management API — Delete a SSO user Source [docs]: https://www.datocms.com/docs/content-management-api/resources/sso-user/destroy.md ## Query parameters **`destination_user_type`** - Type: enum - Example: `"user"` New owner for resources previously owned by the deleted SSO user. This argument specifies the new owner type.
Show enum values **`account`** **`user`** **`access_token`** **`sso_user`**
**`destination_user_id`** - Type: string - Example: `"7865"` New owner for resources previously owned by the deleted SSO user. This argument specifies the new owner ID. ## Returns Returns a resource object of type [sso\_user](/docs/content-management-api/resources/sso-user.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const userId = "312"; const ssoUser = await client.ssoUsers.destroy(userId); // Check the 'Returned output' tab for the result ☝️ console.log(ssoUser); } run(); ``` Returned output ```javascript { id: "312", username: "mark.smith@example.com", external_id: "Ja23ekjhsad", is_active: true, first_name: "Mark", last_name: "Smith", meta: { last_access: "2018-03-25T21:50:24.914Z" }, groups: [{ type: "sso_group", id: "312" }], role: { type: "role", id: "34" }, } ``` --- # Content Management API — SSO Group Source [docs]: https://www.datocms.com/docs/content-management-api/resources/sso-group.md A Single Sign-On group exists when a DatoCMS project is connected to an Identity Provider. These groups can be used to link DatoCMS roles to the Identity Provider's groups. ## Object payload **`id`** - Type: string - Example: `"312"` ID of group **`type`** - Type: string Must be exactly `"sso_group"`. **`name`** - Type: string - Example: `"Admin"` Name of the group **`priority`** - Type: integer - Example: `1` When an user belongs to multiple groups, the role associated to the group with the highest priority will be used **`role`** - Type: [ResourceLinkage\<"role"\>](https://www-draft.datocms.com/docs/content-management-api/resources/role.md) Sso Group's role **`users`** - Type: Array<[ResourceLinkage\<"sso_user"\>](https://www-draft.datocms.com/docs/content-management-api/resources/sso_user.md)> Group members --- # Content Management API — List all SSO groups Source [docs]: https://www.datocms.com/docs/content-management-api/resources/sso-group/instances.md ## Returns Returns an array of resource objects of type [sso\_group](/docs/content-management-api/resources/sso-group.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const ssoGroups = await client.ssoGroups.list(); for (const ssoGroup of ssoGroups) { // Check the 'Returned output' tab for the result ☝️ console.log(ssoGroup); } } run(); ``` Returned output ```javascript { id: "312", name: "Admin", priority: 1, role: { type: "role", id: "34" }, users: [{ type: "sso_user", id: "312" }], } ``` --- # Content Management API — Sync SSO provider groups to DatoCMS roles Source [docs]: https://www.datocms.com/docs/content-management-api/resources/sso-group/copy_roles.md ## Returns Returns a resource object of type [sso\_group](/docs/content-management-api/resources/sso-group.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const ssoGroupId = "312"; const ssoGroup = await client.ssoGroups.copyRoles(ssoGroupId); // Check the 'Returned output' tab for the result ☝️ console.log(ssoGroup); } run(); ``` Returned output ```javascript { id: "312", name: "Admin", priority: 1, role: { type: "role", id: "34" }, users: [{ type: "sso_user", id: "312" }], } ``` --- # Content Management API — Update a SSO group Source [docs]: https://www.datocms.com/docs/content-management-api/resources/sso-group/update.md ## Body parameters **`priority`** - Required - Type: integer - Example: `1` When an user belongs to multiple groups, the role associated to the group with the highest priority will be used **`role`** - Required - Type: [ResourceLinkage\<"role"\>](https://www-draft.datocms.com/docs/content-management-api/resources/role.md) Sso Group's role ## Returns Returns a resource object of type [sso\_group](/docs/content-management-api/resources/sso-group.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const ssoGroupId = "312"; const ssoGroup = await client.ssoGroups.update(ssoGroupId, { id: "312", priority: 1, role: { type: "role", id: "34" }, }); // Check the 'Returned output' tab for the result ☝️ console.log(ssoGroup); } run(); ``` Returned output ```javascript { id: "312", name: "Admin", priority: 1, role: { type: "role", id: "34" }, users: [{ type: "sso_user", id: "312" }], } ``` --- # Content Management API — Delete a group Source [docs]: https://www.datocms.com/docs/content-management-api/resources/sso-group/destroy.md ## Returns Returns a resource object of type [sso\_group](/docs/content-management-api/resources/sso-group.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const ssoGroupId = "312"; const ssoGroup = await client.ssoGroups.destroy(ssoGroupId); // Check the 'Returned output' tab for the result ☝️ console.log(ssoGroup); } run(); ``` Returned output ```javascript { id: "312", name: "Admin", priority: 1, role: { type: "role", id: "34" }, users: [{ type: "sso_user", id: "312" }], } ``` --- # Content Management API — White-label settings Source [docs]: https://www.datocms.com/docs/content-management-api/resources/white-label-settings.md Represents the white-label settings of the current DatoCMS project ## Object payload **`id`** - Type: string - Example: `"312"` ID **`type`** - Type: string Must be exactly `"white_label_settings"`. **`custom_i18n_messages_template_url`** - Type: null, string - Example: `"https://my-app-messages.netlify.app/:locale/message.json"` URL of custom I18n messages. The :locale placeholder represents the current DatoCMS UI locale. --- # Content Management API — Retrieve white-label settings Source [docs]: https://www.datocms.com/docs/content-management-api/resources/white-label-settings/self.md ## Returns Returns a resource object of type [white\_label\_settings](/docs/content-management-api/resources/white-label-settings.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const whiteLabelSettings = await client.whiteLabelSettings.find(); // Check the 'Returned output' tab for the result ☝️ console.log(whiteLabelSettings); } run(); ``` Returned output ```javascript { id: "312", custom_i18n_messages_template_url: "https://my-app-messages.netlify.app/:locale/message.json", } ``` --- # Content Management API — Update white-label settings Source [docs]: https://www.datocms.com/docs/content-management-api/resources/white-label-settings/update.md ## Body parameters **`custom_i18n_messages_template_url`** - Optional - Type: null, string - Example: `"https://my-app-messages.netlify.app/:locale/message.json"` URL of custom I18n messages. The :locale placeholder represents the current DatoCMS UI locale. ## Returns Returns a resource object of type [white\_label\_settings](/docs/content-management-api/resources/white-label-settings.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const whiteLabelSettings = await client.whiteLabelSettings.update({}); // Check the 'Returned output' tab for the result ☝️ console.log(whiteLabelSettings); } run(); ``` Returned output ```javascript { id: "312", custom_i18n_messages_template_url: "https://my-app-messages.netlify.app/:locale/message.json", } ``` --- # Content Management API — Audit log event Source [docs]: https://www.datocms.com/docs/content-management-api/resources/audit-log-event.md If the Audit log functionality is enabled in a project, logged events can be queried using SQL-like language and fetched in full detail so that they can be exported or analyzed. ## Object payload **`id`** - Type: string - Example: `"01F8WDQJR03M4VC6NTK49R83QW"` ULID of event (https://github.com/ulid/spec) **`type`** - Type: string Must be exactly `"audit_log_event"`. **`action_name`** - Type: string - Example: `"items.publish"` The actual action performed **`actor`** - Type: object - Example: `{ type: "user", id: "3845289", name: "mark@acme.com" }` The actor who performed the action
Show object format **`type`** - Type: string - Example: `"user"` The type of actor (can be `account`, `user`, `sso_user` or `access_token`) **`id`** - Type: string - Example: `"3845289"` The ID of the actor **`name`** - Type: string - Example: `"mark@acme.com"` An human representation of the actor (name/email/username depending on the type of actor)
**`role`** - Type: null, object - Example: `{ id: "455281", name: "Editor" }` The role of the actor at the time the action was performed
Show object format **`name`** - Type: string - Example: `"Editor"` The name of the role **`id`** - Type: string - Example: `"455281"` The ID of the role
**`environment`** - Type: object - Example: `{ id: "main", primary: true }` The environment inside of which the action was performed
Show object format **`id`** - Type: string - Example: `"main"` The ID of the environment **`primary`** - Type: boolean Whether the environment was the primary one at the time the action was performed
**`request`** - Type: object The actual request being performed Example: ```json { id: "894f9f6c-a693-4f93-a3fb-452454b41313", method: "PUT", path: "/items/37823421/publish", payload: {}, } ```
Show object format **`path`** - Type: string - Example: `"/items/37823421/publish"` The full path of the request **`method`** - Type: string - Example: `"PUT"` The HTTP method of the request **`id`** - Type: string - Example: `"894f9f6c-a693-4f93-a3fb-452454b41313"` The X-Request-ID header of the request **`payload`** - Type: null, object - Example: `{}` The full HTTP body of the request
**`response`** - Type: null, object - Example: `{ status: 200, payload: {} }` The actual response being returned by DatoCMS
Show object format **`status`** - Type: integer - Example: `"200"` The HTTP status code of the response **`payload`** - Type: object - Example: `"PUT"` The full HTTP body of the response
**`impersonated`** - Type: null, boolean Whether the action was performed during a debug (impersonation) session by DatoCMS staff **`meta.occurred_at`** - Type: date-time - Example: `"2016-09-20T18:50:24.914Z"` The date of the event --- # Content Management API — List Audit Log events Source [docs]: https://www.datocms.com/docs/content-management-api/resources/audit-log-event/query.md The Audit Logs API allows to monitor events happening in an Enterprise project. It ensures continued compliance, safeguarding against any inappropriate system access, and allows you to audit suspicious behavior within your enterprise. You can use this part of the API to: - Automatically feed DatoCMS access data into an SIEM or other auditing tool; - Proactively monitor for potential security issues or malicious access attempts; - Write custom apps to gain insight into how your organization uses DatoCMS. Please note that DatoCMS does not perform any kind of automated intrusion detection. The Audit Logs API will return the data but can not automatically determine or indicate whether an action was appropriate. ### Pagination A single request might not return the full results. To get the remaining results, you can use the `meta.next_token` of a response as a `next_token` attribute for the next request, until the response returns `null` as the next token. ### Filtering by date range You can use the `since` and `before` parameters to restrict the events to a specific time range. Both accept an ISO 8601 datetime string. For example, to return actions performed in Q1 2024 (January to March), set `since` to `"2024-01-01T00:00:00Z"` and `before` to `"2024-04-01T00:00:00Z"`. ### Filtering events You can use the `filter` parameter to pass an SQL-like query ([PartiQL](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ql-reference.html)) to filter events. Any attribute of the event payload can be used in a condition. ```sql -- Return actions of type 'items.update' only action_name = 'items.update' -- Returns actions whose name begins with 'fields' begins_with(action_name, 'fields') -- Includes `fields.update`, `fields.destroy`, etc, -- Returns actions containing 'destroy' contains(action_name, 'update') -- Includes `fields.update`, `plugins.update`, `items.update`, etc. -- Return actions performed by a collaborator actor['type'] = 'user' -- Return actions performed by a specific collaborator actor['type'] = 'user' AND actor['id'] = '4845293' -- Return publishing actions for the record 239408 request['path'] = '/items/239408/publish' -- Return all record creations for the model 855832 action_name = 'items.create' AND request['payload']['data']['relationships']['item_type']['data']['id'] = '855832' ``` ## Body parameters **`since`** - Optional - Type: string - Example: `"2024-01-01T00:00:00Z"` Only return events occurred at or after this ISO 8601 datetime **`before`** - Optional - Type: string - Example: `"2024-04-01T00:00:00Z"` Only return events occurred before this ISO 8601 datetime **`filter`** - Optional - Type: string - Example: `"action_name = 'items.update'"` An SQL-like expression to filter the events **`next_token`** - Optional - Type: string - Example: `"E5188+SCXtvvXVUFkqmwtQJd3V3lJIOsZBjHvTYz"` Set this value to get remaining results, if a meta.next_token was returned in the previous query response **`detailed_log`** - Optional - Type: boolean Whether a detailed log complete with full request and response payload must be returned or not ## Returns Returns an array of resource objects of type [audit\_log\_event](/docs/content-management-api/resources/audit-log-event.md) ## Examples ###### Example Basic example Code ```javascript import { buildClient } from "@datocms/cma-client-node"; async function run() { const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN }); const auditLogEvents = await client.auditLogEvents.query({}); for (const auditLogEvent of auditLogEvents) { // Check the 'Returned output' tab for the result ☝️ console.log(auditLogEvent); } } run(); ``` Returned output ```javascript { id: "01F8WDQJR03M4VC6NTK49R83QW", action_name: "items.publish", actor: { type: "user", id: "3845289", name: "mark@acme.com" }, role: { id: "455281", name: "Editor" }, environment: { id: "main", primary: true }, request: { id: "894f9f6c-a693-4f93-a3fb-452454b41313", method: "PUT", path: "/items/37823421/publish", payload: {}, }, response: { status: 200, payload: {} }, meta: { occurred_at: "2016-09-20T18:50:24.914Z" }, } ``` --- # Asset API — Images API Source [docs]: https://www.datocms.com/docs/asset-api/images.md Every asset you upload in DatoCMS is stored on [Imgix](https://www.imgix.com/), a super-fast CDN optimized for image delivery, which provides **on-the-fly image manipulations and caching**. What that means is that simply by adding some parameters to your images URL, you can enhance, resize, crop, compress and change format for better performance. You can also create complex compositions and extract useful metadata. At any time you can request your image in a new size — with a new crop or whatever transformation you might need — the asset is created for you and automatically cached close to your users. One thing to keep in mind as you implement your front-end is that to achieve maximum performance, **you should take care to reuse crops and sizes across your front-end** to ensure your cached assets are re-used. Also, all new projects in are configured with an [automatic image optimization](/docs/asset-api/asset-cdn-settings.md) preset that selects the best format for compression without compromising the visual quality of your assets. > [!NOTE] Should I use the Images API or the CDA with responsiveImage parameters? > All your images on DatoCMS go through Imgix, but the same transformations and parameters can be accessed through two related APIs: > > - The Images API (this page) lets you apply image transformations directly via URL parameters, which is good for testing and directly fetching images. > > - But most production frontends use our GraphQL-based Content Delivery API (CDA) instead. And in that API, you can directly specify Imgix parameters right inside your query, and our GraphQL will automatically generate the correct Image API URL parameters for you. For more details, please see Content Delivery API: [Images and videos](/docs/content-delivery-api/images-and-videos.md) ### Powerful transformations at your disposal (Image content) The URL that DatoCMS will assign to the images you upload to your project will follow this structure: ```plaintext https:////-. Example: -> https://www.datocms-assets.com/205/1570696780-example.jpg ``` If you fetch this URL, you will be served the original asset. This wastes a lot of bandwidth as content editors should upload full resolution assets. Thanks to Imgix, the DatoCMS image pipeline allows to scale, crop, and process images on the fly based on the URL-parameters you provide. For example, by appending `?h=200` to the base URL, you instruct DatoCMS to scale the image to be 200 pixels tall: ```plaintext https://www.datocms-assets.com/205/1570696780-example.jpg?h=200 ``` But you can specify any number of parameters! Take a look at [Imgix's Image API Reference](https://docs.imgix.com/apis/url) page to see all the transformations available. ```plaintext https://www.datocms-assets.com/205/1570542926-example.jpg?fit=facearea&faceindex=2&facepad=5&sat=-100&w=800&h=500&fm=png&txt=%C2%A9%20Matheus%20Ferrero&txt-align=bottom,center&txt-color=FFF&txt-size=15&txt-pad=20 ``` In the example above, the parameters will: - crop the image to be 800x500px, centering around the second face it recognizes inside the picture; - desaturate the image; - add a copyright caption at the bottom; - transform the format to be a PNG. > [!PROTIP] Pro tip: Caching of transformations > The first time the image is called with these parameters, Imgix will cache and propagate the resulting image in all their geographically positioned CDN servers; subsequent calls with the same parameters will not need to reprocess the image. ### Focal points When the same image is used in different contexts with different aspect ratios, the classic problem we might encounter is being able to crop it **while preserving the key parts**: (Image content) DatoCMS provides a complete set of [automatic controls on the crop](https://docs.imgix.com/apis/rendering/size/crop-mode), but unfortunately these detection methods are all automatic, so the result in some cases may not be exactly what we expect. With focal points, you can now **ensure that the key part of your images doesn't get cut off or misaligned** across multiple image sizes and ratios, by explicitly specifying a focal point for the image. The interface allows you to preview the result of the crop operation on different aspect ratios: (Video content) Note that **the focal point is not automatically applied at the CDN level**: if you construct an image URL manually with crop parameters, the focal point has no effect unless you explicitly add `fp-x`, `fp-y`, and `crop=focalpoint` to the URL yourself. The automatic injection of these parameters happens only through the GraphQL Content Delivery API. When you use the `responsiveImage` or `url` fields with `fit: crop`, DatoCMS transparently adds the right Imgix parameters to center the crop on the focal point. The result looks like this: (Image content) To have an overview on the media area and its features, check out this video tutorial: [ (Image content) Images and Image Optimization Play video » ](https://www.datocms.com/user-guides/media-management/images-and-image-optimization.md) [ (Image content) Working with the Media Manager in DatoCMS Play video » ](https://youtu.be/OmRFyDhSXG4) ### Using the Images API with our GraphQL Content Delivery API While this page covers how to use our images API directly (by appending URL parameters), you can also programmatically define these same parameters in a GraphQL query when you are using our Content Delivery API. For details on that, please see: Content Delivery API: [Images and videos](/docs/content-delivery-api/images-and-videos.md) . --- # Asset API — Video API Source [docs]: https://www.datocms.com/docs/asset-api/videos.md DatoCMS natively supports video encoding and streaming, thanks to the integration with [Mux](https://mux.com/), the fastest and most advanced cloud encoding platform for on-demand streaming video. Every video you upload to your DatoCMS project will be instantly available for streaming. We can ingest almost every available codec, including those for broadcast and professional applications like H.264, H.265, VP9, and Apple ProRes. Thanks to HLS Adaptive Bitrate (ABR) streaming, every viewer will always download the right video size for their device and connection speed from the nearest CDN node. > [!NOTE] Prefer using YouTube streaming instead? > No problem! We also support integrations with embedded videos from YouTube/Vimeo/Facebook as a special field type you can add to your models and blocks. ### Uploading videos You can upload videos in the same way you upload regular assets. Through the interface, you can access some metadata related to the video, and you'll have the ability to preview it instantly: (Image content) You can add a video to your models using the *Single Asset* or *Asset Gallery* fields. ### What gets exposed via API From your application, you can obtain everything you need to generate a video player through the API, as well as any thumbnails and other metadata. Take a look at the documentation of our [Content Delivery API](/docs/content-delivery-api/images-and-videos.md#videos) for all the details. DatoCMS also offers `` components for [React](https://github.com/datocms/react-datocms/blob/master/docs/video-player.md), [Vue](https://github.com/datocms/vue-datocms/tree/master/src/components/VideoPlayer), and [Svelte](https://github.com/datocms/datocms-svelte/tree/main/src/lib/components/VideoPlayer), making it easy to display a fully-featured video with captions, multiple audio tracks, and timeline hover previews using data retrieved from the API. ### Subtitles, closed captions, additional audio tracks With every video you upload, you can make your content more accessible and reach a global audience with subtitles, closed captions, and extra audio tracks. After you've uploaded a video, and it's been processed correctly (i.e. you see the thumbnail and can play the preview), head over to the "Additional audio tracks and subtitles" section to upload both alternate audio tracks (in M4A, MP3, or WAV format) and subtitles (in SRT or VTT format). (Video content) ### Auto-generated captions We offer the option to automatically generate closed captions for your video directly from its audio using speech recognition and machine learning. All you need to provide is the language of your video and the description to display in the player. (Video content) The transcription quality is usually pretty good, but since it's machine-generated, we recommend double-checking the results, particularly when used with suboptimal audio recordings. If you want to make adjustments, you can download the generated subtitles in .vtt format by clicking on the icon next to the subtitles name, make your changes, and then re-upload the file. (Image content) > [!WARNING] Feature limited to recently added videos > The option to automatically generate captions is only available for videos uploaded in the last 7 days. ### **Poster time** By default, the still image used to represent a video — the thumbnail you see in listings, and the poster frame the player shows before playback starts — is taken from the very middle-point frame of the clip. That frame is often not the one you want. With **poster time**, you can pick the exact moment that best represents the video by scrubbing to the frame you want and setting it as the poster directly in the interface. (Image content) Note that **the poster time is not automatically applied when you build a thumbnail URL manually**: if you construct a Mux thumbnail URL yourself, you'll get the middle-point frame unless you explicitly add the **time** parameter to the URL. The automatic injection of this parameter happens through the GraphQL Content Delivery API. When you request the `thumbnailUrl` field, DatoCMS transparently adds the correct timestamp so the generated thumbnail lands in the frame you chose. For details, see Content Delivery API: [Images and videos](/docs/content-delivery-api/images-and-videos.md#videos). ### Stream videos in 4K > [!NOTE] Available only on Enterprise plans > As of today, 4K video streaming is only available upon request for Enterprise plans. If you want it enabled for your account, you'll need to [reach out to our team](https://www.datocms.com/support.md). If you upload a video with a resolution that exceeds 1080p, and have the "4K Video Streaming" feature enabled on your plan, the video player will be able to serve higher resolution streaming for your viewers (2K/1440p or 4k/2160p). The video player selects the best video resolution based both on the density of the screen and the actual size of the player in the page, so it will only serve these higher resolutions when supported. In case you want to limit this case, you can stop providing streaming for a video above a certain resolution by using a `max_resolution` query parameter to the regular Playback URL. This modifies the resolution options available for the player to select from: ```none https://stream.mux.com/{PLAYBACK_ID}.m3u8?max_resolution=1080p ``` The `max_resolution` parameter can be set to `720p`, `1080p`, `1440p`, or `2160p`. ### Pricing and availability Integration with Mux is offered across all DatoCMS packages, each incorporating a generous amount of encoding/streaming minutes into the cost. If you're subscribed to a paid plan and exceed your quota, your website will not experience any service disruption. At the end of the month, we'll bill you for any additional usage. If your plan has 4K video streaming enabled, it will have an additional cost - actual seconds of videos delivered in a resolution higher than 1080p will be charged with a 3x multiplier on DatoCMS due to the higher costs that Mux applies in this case ([read more](/docs/plans-pricing-and-billing/overcharges-on-api-and-bandwidth.md#4k-video-streaming)). ### What happens if you downgrade or cancel your subscription? Videos will be kept for 60 days after the subscription ends. After that, we'll delete the videos. If you then change your mind and reactivate the project, you will need to re-upload the videos. This behavior is particular to videos, as they can be very big and expensive to retain. This does not apply to other assets or data in general. ### Explore more! To gain a comprehensive understanding of videos and video optimization in DatoCMS, take a look at this video tutorial: [ (Image content) Videos and Video Optimizations Play video » ](https://www.datocms.com/user-guides/media-management/videos-and-video-optimizations.md) --- # Asset API — Asset CDN Settings Source [docs]: https://www.datocms.com/docs/asset-api/asset-cdn-settings.md ## Accessing Asset CDN Settings Advanced Asset Settings are located within your "Project settings", under the "Asset CDN settings" section. Here, administrators with the appropriate permissions can set default parameters that will apply to all assets of a project. (Image content) ## Automatic Image Optimization DatoCMS offers a set of customizable parameters that can significantly boost your project's performance by leveraging the robust image optimizations and transformations of Imgix, our image CDN partner. We strongly recommend you read the following documentation thoroughly before implementing changes. For a more technical reference about how these parameters work, please see the [Imgix Rendering API documentation](https://docs.imgix.com/apis/rendering/overview). > [!NOTE] How are automatic optimization settings applied? > The default Automatic Image Optimization settings that you define here will be **combined** with any additional ones you explicitly specify in the URL. For instance, if you have your defaults set to `?auto=format&q=50` (via "Custom settings"), then: > > - Adding `?w=40` to the URL of an image will make the final parameters equal to `auto=format&q=50&w=40`. Even though the default parameters are not explicitly visible, they are still implicitly applied. > > - Applying `?auto=enhance` to the URL will behave as `?auto=enhance&q=50`, because the same parameter (`auto`) specified again at the URL level will override the previously set default. > > > If you ever want to bypass the defaults, you can skip automatic optimization by using the URL parameter `?skip-default-optimizations=true` (or using the argument `skipDefaultOptimizations: true` in your CDA requests). > > Therefore, `?auto=enhance&skip-default-optimizations=true` will simply behave as `?auto=enhance`, with no additional parameters (`q=50` will be skipped even though it was specified in the defaults). But please be careful when using the `skip-default-optimizations` parameter, as it could significantly increase your bandwidth costs. ### Option 1: DatoCMS presets (recommended) This is the default setting for newly-created DatoCMS projects. This presets applies the `auto=format` parameter to your images, and is our recommended approach for basic image optimization. This preset has been carefully selected to intelligently optimize images, selecting the best format for efficient compression without compromising visual quality. [Learn more about what `auto=format` does in the Imgix documentation](https://docs.imgix.com/apis/rendering/automatic#format). ### Option 2: Custom settings For more control, you can also choose to specify custom defaults for three Imgix settings: `auto`, quality (`q`), and color space (`cs`): (Image content) #### Automatic (`auto`) parameter The [`auto` parameter](https://docs.imgix.com/apis/rendering/auto/auto) simplifies the optimization process automated across your image repository. It offers four distinct settings, which might also be combined: `auto=compress` - Reduces image size through best-effort techniques, applying aggressive compression. - Serves images in AVIF format, with fallbacks to WebP or JPEG based on browser support. - Overrides `fm` parameter for non-animated assets when used with `auto=compress`. `auto=enhance` - Improves image quality by enhancing highlights, midtones, and shadows across all RGB channels. - Gives images a vibrant appeareance, which is ideal for editorial, stock, and user-generated content. `auto=true` - Automatically adjusts images by applying additional parameters, starting with `auto=enhance`. - If `crop=faces` is set, `auto=true` will triggers `auto=redeye` for red-eye removal. `auto=format` - Determines the optimal image format through automatic content negotiation. - Attempts to serve images in AVIF, falling back to WebP, JPEG, or PNG based on browser support. - Can be combined with `auto=compress` and/or `fm` to customize fallback logic. `auto=redeye` - Automatically removes red-eye from detected faces, enhancing image quality. For more details, refer to the [imgix documentation on `auto` parameter](https://docs.imgix.com/apis/rendering/auto/auto). #### Output Quality `q` parameter The [`q` parameter](https://docs.imgix.com/apis/rendering/format/q) controls the output quality of lossy file formats like jpg, webp, avif, or jxr. Key points include: - Values range from 0 to 100, with 75 set as the default - higher values increase image file size. - Quality can often be set lower than default, especially for high-DPR (Device Pixel Ratio) images. - When auto=compress is applied, the default is automatically set to 45, unless overridden. Explore more about the [q parameter in `imgix` documentation](https://docs.imgix.com/apis/rendering/format/q). #### Color Space ( `cs` ) parameter The [`cs` parameter](https://docs.imgix.com/apis/rendering/format/cs) specifies the color space of the output image. Options include: - **sRGB**: Default value, standard web color representation. - **Adobe RGB (1998)**: Provides accurate color reproduction from digital screens to print. - **TinysRGB**: Reduced color space metadata, potentially resulting in a slight color shift. - **Strip**: Removes color space for maximum size reduction. Learn more about the [cs parameter in `imgix` documentation](https://docs.imgix.com/apis/rendering/format/cs). ## Option 3: No settings No automatic image optimizations will be applied. This option is not typically recommended, because bypassing `auto=format` will result in significant bandwidth usage, especially if you're serving large .PNG files. Nonetheless, it can be useful if you prefer to use URL queries or GraphQL parameters to more precisely optimize your images on your frontend. ## Video optimization ### Block Serving Raw Videos This is enabled by default for newly-created DatoCMS projects, and we recommend leaving it on unless you have a special use case for raw videos. By "raw", we mean that you are serving the video file (typically a .MP4, sometimes a .MOV or .AVI or other file type) directly from `datocms-assets.com`, without any optimizations for different connection speeds or devices. This can result in an inferior user experience. Instead of serving the files directly, we generally recommend using HLS (HTTP Live Streaming) to serve videos to your visitors, because this improves performance and user experience for them, and minimizes bandwidth charges for you. Please see our documentation on [How to stream videos efficiently](/docs/streaming-videos/how-to-stream-videos-efficiently.md) for more information on how this works. This setting allows project administrators to completely block raw video files from being served from your project, enforcing the use of HLS and Mux instead. This can help prevent human error (editors or developers accidentally linking to a raw .MP4) causing severe slowdowns for your visitors and excessive bandwidth use in your project. Enabling this feature means that accessing a video's raw URL will result in a 422 error. This policy supports our standard best practice of [utilizing Mux for video delivery](/docs/asset-api/videos.md), optimizing video streaming and ensuring consistency across the platform. [ (Image content) Images and Image Optimization Play video » ](https://www.datocms.com/user-guides/media-management/images-and-image-optimization.md) [ (Image content) Videos and Video Optimizations Play video » ](https://www.datocms.com/user-guides/media-management/videos-and-video-optimizations.md) --- # Real-time Updates API — Real-Time Updates API Overview Source [docs]: https://www.datocms.com/docs/real-time-updates-api.md The Real-time Updates API allows clients to **listen for content changes using a stable connection that streams events as they occur**. It supports the exact same GraphQL queries available in the [Content Delivery API](/docs/content-delivery-api.md), but returns a streaming channel implementing the [Server-Sent Events protocol](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events), which is natively supported by modern browsers. ### Use cases Live updates can be **extremely useful for content editors** to preview draft content on the real website as it gets authored, without needing a page refresh or additional staging servers: (Video content) Live updates **can also be pushed to regular visitors**, so that thay can immediately see new content as it gets published by editors, allowing all kinds of real-time interactions with your website/app. Imagine a real-time updated event coverage liveblog, for example: (Video content) ### Examples and API reference We recommend using our [client libraries](/docs/real-time-updates-api/listening-to-queries.md) to listen for updates, as they will set-up the streaming channel for you. If you need to implement the streaming logic on other environments than the browser, then read the [low-level reference](/docs/real-time-updates-api/api-reference.md) of the underlying endpoints. --- # Real-time Updates API — How to use it Source [docs]: https://www.datocms.com/docs/real-time-updates-api/listening-to-queries.md If you want to use real-time updates on the browser, the easiest way is to use one of our libraries. They will handle all the hard-wiring for you, including reconnecting to a new subscription channel in case of network errors. ### Next.js Please take a look at our [Next.js integration guide](/docs/next-js/real-time-updates.md) to learn how you can use the Real-time Updates API to produce instant refresh of content as soon as it gets saved into DatoCMS. We have also prepared a [step-by-step tutorial](https://www.datocms.com/blog/live-preview-with-next-js.md) that shows how to get to live-previews of draft content, so be sure to check that out! You can also deploy and play with the code of one of our Next.js project starters, as they both support real-time updates: [ (Image content) Next.js Starter Kit Try this demo » ](https://www.datocms.com/marketplace/starters/next-js-starter-kit.md) ### React If you're in a React project the [`react-datocms`](https://github.com/datocms/react-datocms#live-real-time-updates) package exposes a `useQuerySubscription` hook that makes it trivial to make any webpage updated in real-time. For more info on all the available options, please refer to its [documentation on Github](https://github.com/datocms/react-datocms#live-real-time-updates): ```jsx import React from "react"; import { useQuerySubscription } from "react-datocms"; const App: React.FC = () => { const { status, error, data } = useQuerySubscription({ query: ` query AppQuery($first: IntType) { allBlogPosts { slug title } }`, variables: { first: 10 }, token: "YOUR_API_TOKEN", }); const statusMessage = { connecting: "Connecting to DatoCMS...", connected: "Connected to DatoCMS, receiving live updates!", closed: "Connection closed", }; return (

Connection status: {statusMessage[status]}

{error && (

Error: {error.code}

{error.message}
{error.response && ( 
{JSON.stringify(error.response, null, 2)}
)}
)} {data && (
    {data.allBlogPosts.map((blogPost) => (
  • {blogPost.title}
    • ))}
)}
); }; ``` ### Vanilla JS On any other JS environment you can use the [`datocms-listen`](https://github.com/datocms/datocms-listen) package which exposes a generic `subscribeToQuery` function that encapsulates all the connection logic. For more info on all the available options, please refer to its [documentation on Github](https://github.com/datocms/datocms-listen): ```javascript import { subscribeToQuery } from "datocms-listen"; const unsubscribe = await subscribeToQuery({ query: ` query BlogPosts($first: IntType!) { allBlogPosts(first: $first) { title nonExistingField } } `, variables: { first: 10 }, token: "YOUR_TOKEN", includeDrafts: true, onUpdate: (response) => { // response is the GraphQL response console.log(update.response.data); }, onStatusChange: (status) => { // status can be "connected", "connecting" or "closed" console.log(status); }, onChannelError: (error) => { // error will be something like: // { // code: "INVALID_QUERY", // message: "The query returned an erroneous response. Please consult the response details to understand the cause.", // response: { // errors: [ // { // fields: ["query", "allBlogPosts", "nonExistingField"], // locations: [{ column: 67, line: 1 }], // message: "Field 'nonExistingField' doesn't exist on type 'BlogPostRecord'", // }, // ], // }, // } console.error(error); }, }); ``` --- # Real-time Updates API — API reference Source [docs]: https://www.datocms.com/docs/real-time-updates-api/api-reference.md The Real-time Content API is built upon and extends the capabilities of the GraphQL [Content Delivery API](/docs/content-delivery-api.md): theyboth support exactly the same [authentication method](/docs/content-delivery-api/authentication.md), [endpoints](/docs/content-delivery-api/api-endpoints.md) and [GraphQL queries](/docs/content-delivery-api/how-to-fetch-records.md). What's different is the domain you use to perform the POST request: - Content Delivery API: `https://graphql.datocms.com` - **Real-time Content API:** `https://graphql-listen.datocms.com` And of course the response you'll receive: - a call to the Content Delivery API simply returns a JSON with the response to the requested query, whereas - the same call to the Real-time Content API **returns the URL of a persistent channel** implementing the [Server-Sent Events protocol](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events). Here's a diagram representing the differences between the two: (Image content) In the following video, you can see how how easy it is to interact with the API simply using `curl`: (Video content) ## Obtaining the URL of the channel Using the same headers, API token and endpoint you use with the [Content Delivery API](/docs/content-delivery-api.md), you can perform a request to `https://graphql-listen.datocms.com` and get back the URL of a Server-Sent Events channel that streams events as they occur: Terminal window ```bash # Content Delivery API call ~() curl https://graphql.datocms.com/ \ -H 'Authorization: Bearer YOUR_TOKEN' \ -H 'X-Include-Drafts: true' \ -d '{"query":"{ blogPost{ id } }"}' { "data": { "blogPost": { "id": "9721019" } } } # Real-time Content API call ~() curl https://graphql-listen.datocms.com/preview \ -H 'Authorization: Bearer YOUR_TOKEN' \ -d '{"query":"{ blogPost{ id } }"}' { "url": "https://graphql-listen.datocms.com/channels/e4dae1a0-146e-4956-90e6-076ca9123eeb" } ``` The channel URL is ephemeral: after 15 seconds you will no longer be able to access it, so be sure to connect to it within a few seconds, or you will need to make a new call to get a new URL. ## Receiving the events Once you obtain the URL of a subscription channel, you can connect to it and stream events as they occur. All modern browsers offer a native interface to connect to Server-Sent Events channels called `EventSource`: ```javascript const eventSource = new EventSource( "https://graphql-listen.datocms.com/channels/e4dae1a0-146e-4956-90e6-076ca9123eeb" ); eventSource.addEventListener("open", () => { console.log("connected to channel!"); }); ``` Immediately after the connection, the channel will send an `update` event with the result of the GraphQL query. The same event will then be sent every time the result of the query changes due to a change of the underlying content: ```javascript eventSource.addEventListener("update", (event) => { const result = JSON.parse(event.data); // result will be something like: { data: { blogPost: { id: "9721019" } } } console.log("updated graphql result: ", result); }); ``` When something goes wrong, the channel can also send `channelError` events. The cause for the error could be an invalid GraphQL query for example: ```javascript eventSource.addEventListener("channelError", (event) => { const error = JSON.parse(event.data); // error will be something like: // { // code: "INVALID_QUERY", // message: "The query returned an erroneous response. Please consult the response details to understand the cause.", // fatal: true, // response: { // errors: [ // { // fields: ["query", "blogPost", "coverImage", "url", "wrongParameter"], // locations: [{ column: 99, line: 1 }], // message: "Field 'url' doesn't accept argument 'wrongParameter'", // }, // ], // }, // } if (error.fatal) { eventSource.close(); } }); ``` The `fatal` field in the error object is useful to know if the error is temporary (ie. connectivity/network problems) and therefore it is possible that additional `update`\-type events are sent, or if the error is fatal (ie. invalid query) so you need to close the channel permanently. ## Closed channels An SSE channel stays open as long as possible, but it is perfectly normal that it closes after some time. The channel closure may be due to an automatic re-scaling of our servers to cope with an increase in requests, for example. The official clients we have released handle this case transparently, and reconnect automatically if the channel closes. If you don't use one of our libraries, you'll have to make sure to reopen a new channel yourself in case the event happens. --- # Real-time Updates API — Real-time Updates API Limits & Pricing Source [docs]: https://www.datocms.com/docs/real-time-updates-api/limits-and-pricing.md The Real-time Updates API is capable of supporting hundreds of thousands of concurrent connections. ### Technical Limits Every plan comes with a **technical limit of a maximum of 500 concurrent connections per project**. This means, at the same time, that there can be a maximum of 500 open SSE connections to the same project. If you need more, please [contact us](https://www.datocms.com/support.md?topics=technical-support/general-request) so we can discuss your needs and see how we can help you scale. ### Pricing Even though the Real-time Updates API is not billed per se, it uses the [Content Delivery API](/docs/content-delivery-api.md) to function, so it contributes to the number of API calls to it. What makes the cost predictable is that **CDA usage is independent of the number of connected clients**. Clients that open an identical subscription request are served by a single shared re-fetch. Whether 1 or 500 clients are watching, a content change triggers the same single CDA request, and every client receives the update. A few consequences follow from this model: - **One request per relevant change.** Each content change that affects a query's result triggers exactly one CDA request for that query. - **Irrelevant changes are free.** Edits elsewhere in the project that don't affect a query's result trigger no re-fetch, and therefore no CDA request, for that query. - **Usage scales with distinct subscriptions, not clients.** Subscriptions are grouped together only when their requests match exactly; any difference — in the query, its variables, or any other request detail — makes them count separately, each with its own re-fetch. Your CDA usage therefore grows with the number of *distinct* subscriptions being watched, not with the number of connected clients. #### Example Imagine 500 visitors viewing the same homepage, all subscribed to the same hardcoded query, with content changing every 30 seconds. Because every visitor shares the same query, they are served by a single re-fetch. Each change produces one CDA request, so a change every 30 seconds results in **2 CDA requests per minute in total — regardless of the 500 connected clients**. By contrast, if those same 500 visitors each subscribed to a *different* query, a single homepage change could trigger up to 500 re-fetches — one per unique query — because there is no longer anything to share. --- # AI & Automation at a glance — AI and Automation Source [docs]: https://www.datocms.com/docs/ai-overview/overview-of-ai-and-automation.md DatoCMS offers several approaches to help you automate your work when managing content with LLMs. ## Agent Skills DatoCMS Skills are playbooks that AI coding assistants load on demand. Without them, your LLM can call DatoCMS APIs, but might take a guess at conventions, pick wrong field types, and miss integration patterns. With DatoCMS's agent skills, agents work with correct GraphQL queries, solid content modeling, idiomatic frontend integrations, clean migrations, and well-structured plugins, all on the first try. Agent skills are currently available to help you build with DatoCMS (Content Modeling, Reading Content, Writing Content, CLI Workflows, and handling Frontend Integrations), and to extend DatoCMS's capabilities with helping you develop Plugins (Plugin Scaffolding, maintenance, and managing the design system). Get started with DatoCMS [Agent Skills here](/docs/agent-skills.md), Or [check out the repo here](https://github.com/datocms/agent-skills). ## DatoCMS MCP Server The DatoCMS MCP server connects DatoCMS directly to AI assistants through the Model Context Protocol (MCP). It allows MCP-compatible tools, such as Claude Code, Claude Desktop, ChatGPT, Cursor, VS Code, and Windsurf, to interact with your DatoCMS projects using natural language commands. Our recommendation is to use the DatoCMS MCP to help your content and editor teams to improve their workflows, and to use Agent Skills when interacting with the DatoCMS APIs. [Get started with the MCP Server here](/docs/mcp-server.md), or [share this User Guide with your editorial team](https://www.datocms.com/user-guides/content-management/working-with-the-datocms-mcp.md) to help them unlock new workflows. ## AI powered translations DatoCMS's [(Image content)AI Translations](https://www.datocms.com/marketplace/plugins/i/datocms-plugin-ai-translations.md)plugin integrates leading AI providers—OpenAI (ChatGPT), Google (Gemini), Anthropic (Claude), and DeepL — directly into DatoCMS. The plugin helps you translate individual fields, entire records, multiple records from table views, or batch-translate whole models. The plugin intelligently handles complex field types including Structured Text, supports contextual translations for better accuracy, and preserves ICU Message Format patterns, allowing you to achieve things like preserving complex formatting, using the right context, and enforcing terminology. Learn more about what you can do [with this plugin here](/docs/translating-content-with-ai.md). ## LLM-ready Docs All our API references and docs (and most of our website) are LLM-ready. There's 3 approaches you can access to provide the best possible context for your LLMs when working with DatoCMS: - Complete Docs: [https://www.datocms.com/docs/llms-full.txt](https://www.datocms.com/docs/llms-full.txt) is where you will find a complete `.md` of all our docs, to give your LLM a quick reference on all topics and guides. - Documentation Index: [https://www.datocms.com/docs/llms.txt](https://www.datocms.com/docs/llms.txt) is where you can provide your LLMs with an index of all docs pages to let it decide which path would best serve your use-case at hand. - Single-page `.md` exports: All DatoCMS website pages are available as a markdown file by appending `.md` to the end of the URL to give your LLM a quick extraction of specific pages without dealing with HTML formatting issues or web scraping complications. On content pages like docs and blog, you can simply select "copy page" as markdown as well. Learn more about the [application and usage for this here](/docs/llm-ready-docs.md). --- # Agent Skills — Agent Skills Source [docs]: https://www.datocms.com/docs/agent-skills.md **DatoCMS Skills** are expert playbooks that AI coding assistants load on demand. Without them, an AI can call DatoCMS APIs, but will guess at conventions, pick wrong field types, and miss integration patterns. With them, **agents work like a senior DatoCMS developer**: correct GraphQL queries, solid content modeling, idiomatic frontend integrations, clean migrations, and well-structured plugins — on the first try. > [!PROTIP] Pro tip: Skills or MCP? > - **Working in a local repo?** Install Agent Skills — **they're all you need**. Every MCP capability is already built in via local CLI calls, plus all the expertise MCP can't carry: content modeling best practices, frontend integration patterns, migration workflows, plugin conventions, and more. > > - **No local terminal?** (web, mobile, chat apps) Use the [**MCP server**](/docs/mcp-server.md) instead. > > > Pick one, not both. ## What you can do Most skills trigger automatically based on your prompt. ###### Building with DatoCMS - **Content modeling** — schema-design decisions: model vs block, references vs embedded blocks, taxonomies, field shapes, validators, editor appearances. - **Reading content** — GraphQL queries against the Content Delivery API: filters, pagination, localization, modular content, Structured Text, responsive images, SEO metadata, typed queries with gql.tada or codegen. - **Writing content & automation** — programmatic CMA scripts: record CRUD, bulk imports/exports, asset uploads, environment forks and promotions, webhooks, roles and tokens, scheduled publishing, audit logs. - **CLI workflows** — migrations, schema-type generation, typed CMA scripts, environment operations, CI/CD pipelines, WordPress/Contentful imports. - **Frontend integrations** — draft mode, Web Previews, Visual Editing, Content Link overlays, real-time preview subscriptions, cache-tag invalidation, SEO/sitemap wiring across Next.js App Router, Nuxt, SvelteKit, Astro, plus `react-datocms`, `vue-datocms`, `@datocms/svelte`, and `@datocms/astro`. ###### Building DatoCMS plugins - **Plugin scaffolding** — create a brand-new plugin from scratch with the Vite/React structure, picking the initial surfaces (field extensions, config screens, sidebars, pages, asset sources). - **Plugin maintenance** — patch and extend an existing plugin: hook additions, field extension tweaks, sidebar/page changes, validation updates. - **Plugin design system** — restyle plugin UI to feel native to the DatoCMS dashboard — config screens, panels, modals, forms, density and spacing. ## Installation Pick the install method for your agent. Every installer brings the full set by default — the skills are cross-linked and meant to work together. Claude Code Claude Code's native plugin system bundles all DatoCMS skills with auto-update support and namespaced invocation: Terminal window ```bash /plugin marketplace add datocms/agent-skills /plugin install datocms@datocms-skills ``` All skills install; the right one activates based on your prompt. Auto-update from `/plugin` → **Marketplaces** → `datocms-skills`. Claude.ai (web) CLI commands and local file editing aren't available on the web, so most development-focused skills won't apply. The two worth uploading are: - [`datocms-content-modeling.zip`](https://github.com/datocms/agent-skills/raw/master/zips/datocms-content-modeling.zip) (content modeling) - [`datocms-cma.zip`](https://github.com/datocms/agent-skills/raw/master/zips/datocms-cma.zip) (writing content & automation) To add them, go to **Customize → Skills** → **+** → **Upload a skill**,and drop both .zip files. **These work best alongside the** [**DatoCMS MCP server**](/docs/mcp-server.md), which lets the agent read and update your project directly from the conversation. Codex app and CLI Codex also supports installing through its plugin marketplace. Add the DatoCMS marketplace once, then install the plugin from the Codex plugin picker inside a session: Terminal window ```bash codex plugin marketplace add datocms/agent-skills ``` Then open a Codex session and install from the plugin picker: Terminal window ```bash /plugins ``` Choose **DatoCMS** and "Install plugin" Other agents The universal `npx skills` installer brings the full set: Terminal window ```bash npx skills add datocms/agent-skills --skill '*' ``` Code Editors To use Agent Skills in VS Code, Cursor, Windsurf, install first the [Claude Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code) or the [Codex extension](https://marketplace.visualstudio.com/items?itemName=openai.chatgpt) **Codex Extension, Cursor, Zed, and other editors** Run this in the editor's integrated terminal from your project root: Terminal window ```bash npx skills add datocms/agent-skills --skill '*' --agent '*' ``` **Claude Code extension** Run these commands in the Claude Code prompt, not the terminal: Terminal window ```bash /plugin marketplace add datocms/agent-skills /plugin install datocms@datocms-skills ``` In Zed, install Codex or Claude Agent from the ACP Registry, then use the matching instructions above. ## Usage ###### Automatic skills Most skills activate automatically. Describe your task in plain language and the right skill picks it up: - "Should testimonials be a model or a block?" - "Write a GraphQL query to fetch all blog posts with images" - "How do I paginate past the 100-record limit?" - "Add draft mode to my Next.js app" - "Why isn't my Visual Editing overlay showing up?" - "Create a migration that adds a `category` field to the blog\_post model" - "Bulk-publish all draft records of type `article`" - "Import this CSV into the authors model" - "Make my plugin config screen match the DatoCMS style" - "Create a new DatoCMS plugin from scratch" ###### The setup skill (explicit) `datocms-setup` is the one skill you invoke explicitly. It handles end-to-end project bootstrapping — draft mode, visual editing, migrations workflows, content imports — and queues prerequisites automatically when needed. Phrase prompts as the outcome you want: Claude Code ```text /datocms-setup install visual editing in this project /datocms-setup set up draft mode and web previews /datocms-setup add migrations and a release workflow ``` Codex ```text $datocms-setup install visual editing in this project $datocms-setup set up draft mode and web previews $datocms-setup add migrations and a release workflow ``` ## How it works Unlike a raw API integration, Skills package not just *what* DatoCMS exposes but *how* to use it well — so the agent gets your task right on the first try. ###### Description-based routing Each skill ships with a description. When you describe a task, the agent inspects all installed skill descriptions and loads the most relevant one into context. You don't call skills explicitly — they activate themselves. ###### Local files, your control Skills are markdown plus a few helper assets, stored on disk in `.agents/skills/` (universal) or per-agent dirs like `~/.claude/skills/` and `~/.codex/skills/`. They're inspectable, version-controllable, and removable at any time. ###### Cross-skill references Skills hand off to each other. The setup skill might queue a migration via the CLI skill, which in turn types its TypeScript helpers via the CMA skill. Installing a single skill in isolation breaks these handoffs — that's why every installer brings the full set by default. ## Security Skills run with the **full permissions of the host agent**. They can read and write files, run shell commands, and make network requests on your behalf. That power is useful, but it's also worth knowing. - All DatoCMS skills are open source and visible at [github.com/datocms/agent-skills](https://github.com/datocms/agent-skills). Inspect the markdown before granting an agent access to a sensitive repo. - The `npx skills` installer surfaces automated security scans (Gen / Socket / Snyk) alongside each skill at install time. --- # MCP Server — MCP Server Source [docs]: https://www.datocms.com/docs/mcp-server.md The **DatoCMS MCP server** connects DatoCMS directly to AI assistants through the Model Context Protocol (MCP). It allows MCP-compatible tools, such as Claude Code, Claude Desktop, ChatGPT, Cursor, VS Code, and Windsurf, to interact with your DatoCMS projects using natural language commands. > [!WARNING] Already coding locally? Use Agent Skills instead! > If you already have a repo open in your editor or CLI, skip the MCP server and install [DatoCMS Agent Skills](/docs/agent-skills.md) instead. They automatically install the DatoCMS CLI, which talks directly to the DatoCMS APIs — faster and no MCP server needed. You get everything MCP can do, plus content modeling, frontend integrations, migrations, and plugin expertise. > > **MCP is the right choice only where there's no local terminal to work in!** ## What you can do The DatoCMS MCP server allows AI assistants to: - **Find your projects**: Search across every project you have access to (personal account and organizations) and operate on any of them within the same session, without restarting the server or swapping environment variables - **Inspect your schema**: Retrieve detailed information about your content models, fields, and relationships - **Execute API operations**: Perform both read-only and destructive operations on your DatoCMS project (Video content) ## Requirements - An MCP-compatible client: **Claude Code** (recommended), Claude Desktop, ChatGPT, Cursor, VS Code, Windsurf, or other MCP clients There is nothing to install locally. The server is hosted at `https://mcp.datocms.com` and authentication happens entirely in your browser through standard OAuth. ## Installation The DatoCMS MCP server uses native MCP OAuth, so configuration only requires the server URL — no API tokens, no environment variables. Choose the installation method for your client: Claude Code Use the Claude Code CLI to add the DatoCMS MCP server. Claude Code will open a browser window so you can authorize access through OAuth. Terminal window ```bash claude mcp add --transport http DatoCMS https://mcp.datocms.com ``` Codex Use the Codex CLI to add the DatoCMS MCP server. Codex will open a browser window so you can authorize access through OAuth. Terminal window ```bash codex mcp add DatoCMS --url https://mcp.datocms.com ``` Cursor Go to **Cursor Settings** → **Tools & Integrations** → **New MCP Server**, then paste: ```json { "mcpServers": { "DatoCMS": { "type": "http", "url": "https://mcp.datocms.com" } } } ``` VS Code Use the VS Code CLI: Terminal window ```bash code --add-mcp '{"name":"DatoCMS","type":"http","url":"https://mcp.datocms.com"}' ``` Or follow the MCP installation [guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) and use the same configuration in your `mcp.json`. Claude Desktop / Claude.ai Claude Desktop and Claude.ai both support remote MCP servers as **custom Connectors**: 1. Go to **Customize → Connectors** 2. Click the **+** button next to Connectors and select **Add custom connector** 3. Enter a name (e.g. `DatoCMS`) and the URL `https://mcp.datocms.com/` 4. Click **Add** (Image content) Once done, click **Connect** so you can authorize access through DatoCMS OAuth. ChatGPT ChatGPT supports remote MCP servers through **Developer Mode** (currently in beta). 1. Enable Developer Mode at **Settings → Apps → Advanced settings → Developer mode** 2. Open **Apps settings** and click **Create app** next to **Advanced settings** 3. Enter a name (e.g. `DatoCMS`), the **MCP Server URL** `https://mcp.datocms.com`, and leave **Authentication** set to **OAuth** 4. Click **Create** (Image content) Once done, click **Connect** so you can authorize access through DatoCMS OAuth. The new app will appear in the composer's **Developer Mode** tool during conversations. Google Antigravity In **Antigravity Settings → Customizations → Installed MCP Servers**, click the **Open MCP Config** button (or directly open `~/.gemini/antigravity/mcp_config.json`): ```json { "mcpServers": { "DatoCMS": { "type": "http", "url": "https://mcp.datocms.com" } } } ``` Windsurf Add to `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "DatoCMS": { "serverUrl": "https://mcp.datocms.com" } } } ``` ## How it works Unlike traditional MCPs that expose every API endpoint, the DatoCMS MCP server takes a different approach designed to guide AI assistants through API interactions effectively. ###### Layered tools, not raw endpoints DatoCMS has 40+ resources and 150+ API endpoints. Exposing all of them would overwhelm any LLM. Instead, we provide a small set of carefully designed tools organized in three layers (discovery → planning → execution) that guide the AI through a natural workflow: **Discovery & planning** — Tools that explore what's available and load the documentation needed for execution: - `search_projects`: Search across every project in your account and organizations with fuzzy matching - `list_api_resources`: List all available DatoCMS API resources grouped by theme - `get_api_methods`: Batch-document any combination of resources, actions, and methods. Returns full TypeScript definitions and examples, and mints the verification tokens that the execution layer requires - `get_schema`: Retrieve detailed information about your content models, fields, relationships, and nested blocks **Execution layer (read-only)** — These tools use a read-only API token. Most clients allow them to run without confirmation: - `upsert_and_execute_safe_script`: Write or patch a TypeScript script and execute it against a read-only client - `view_script`: View a previously stored script **Execution layer (read-write)** — These tools use a full read-write API token. The user is asked to confirm before each use: - `upsert_and_execute_unsafe_script`: Write or patch a TypeScript script and execute it with full create/update/delete permissions This layered structure reduces malformed API calls and forces the AI to commit to method names *before* writing code — every API call in a script must reference a verification token returned by `get_api_methods`. ###### Documentation-aware Each documentation tool retrieves detailed method definitions and concrete examples from the official DatoCMS documentation. This is token-intensive, but it significantly improves success rates by giving the LLM the context it needs to make correct API calls. ###### Script-based execution Instead of making one API call at a time, the DatoCMS MCP server enables AI assistants to write complete TypeScript programs that batch multiple operations to reduce round-trips and token overhead, provide full context for complex multi-step operations, support incremental editing when errors occur, and get type-checked before execution to catch errors early. Each script runs in an isolated runner on DatoCMS infrastructure, with restricted network access and a configurable timeout. ## Performance & reliability ###### Real-world performance When using **Claude Code** (our recommended client), users report: - **Fast execution**: Most common operations complete quickly without noticeable delays - **High success rates**: Operations like creating records, adding images, managing translations, and linking records work reliably - **Minimal iteration needed**: Most tasks succeed on the first attempt, with occasional minor refinements needed through follow-up prompts - **No missteps**: The layered approach effectively prevents malformed API calls ###### What to expect **Common operations (fast & reliable):** - Creating records with content across multiple fields - Uploading and attaching images to records - Adding translations to existing content - Linking records together - Copying content between models - Listing and querying records **Complex operations (slower but functional):** - Very complex operations like generating complete landing pages may take several minutes - Large batch operations involving many records - Schema modifications across multiple models ###### Token consumption The documentation-aware approach retrieves full method documentation and examples for each operation. This consumes more tokens than traditional MCPs but significantly improves success rates. For most practical tasks, the token cost is acceptable given the reliability and accuracy of results. ### Success tips Results improve with: - **Clear, specific prompts**: "Create a blog post with title 'Hello' and attach the uploaded image" works better than "add a post" - **Iterative refinement**: If something is missing (like an image), a simple follow-up request handles it quickly ### When it works best The DatoCMS MCP server excels at: - Everyday content management tasks (creating, updating, translating records) - Complex multi-step operations that require understanding your content model - Tasks that would be tedious to do manually (bulk updates, content migration) - Operations that benefit from type safety and validation ## Limits Scripts that the AI executes on our runners are subject to the following limits. **These values apply during the initial beta phase and may change as we gather usage data:** | Limit | Free plans | Paid plans | | --- | --- | --- | | Maximum execution time per script | 20 seconds | 60 seconds | | Monthly script execution time per account | 50 minutes | 400 minutes | | Maximum output captured from a single script | 32 KB | 32 KB | A few notes on what these mean in practice: - **Per-script timeout**: if a script takes longer than the limit it is terminated and the AI receives a friendly error. For long-running operations (large migrations, full-site translations) ask the assistant to split the work into smaller scripts. - **Monthly time budget**: every second a script spends running counts against the account's monthly budget. The budget resets at the start of each calendar month (UTC). Discovery and documentation tools (`get_api_methods`, `get_schema`, etc.) do not consume execution time — only `upsert_and_execute_safe_script` and `upsert_and_execute_unsafe_script` do. - **Output limit**: scripts that produce more than 32 KB of `console.log` output are truncated. If you need to inspect large datasets, ask the assistant to summarise the result rather than dumping it. ## Security and Authentication The DatoCMS MCP server is built around the principle that AI assistants generate untrusted code, and that code should never be able to escape its boundaries. Security is enforced at multiple layers. ###### Native MCP OAuth There are no API tokens to copy, store, or rotate. The server authenticates through `oauth.datocms.com` using the standard MCP OAuth flow: - Tokens never touch your filesystem — your MCP client manages them - During the authorization step you can scope access to specific projects and define the level of access (details in the section below) - Tokens can be revoked at any time from your DatoCMS account settings; the server detects revoked or expired tokens and prompts a re-authentication - Single sign-on (SSO) accounts are not currently supported ###### Scope of permissions The installation screen tells you who is asking for permissions. If the app you're installing isn't the one we've verified, the page says "Authorize an Unverified app" and highlights the destination in red, so you can stop and verify which app you're installing. (Image content) You also decide how much the app can do. Besides picking which projects the app can access, you can choose a level of access: - **Only read content**: read content and media, never write or edit anything. - **Read and edit content (recommended for editors)**: the app can also create, publish, and delete content and media. It can do nothing on schema, settings, users, or API tokens. - **Anything you can (recommended for devs)**: whatever your account can do in DatoCMS, the MCP can as well. > [!NOTE] > Whichever option you pick is still restricted by your own user permissions in each project. The MCP cannot perform actions that your role is unable to. If you choose one access level, you can always revisit the config screen to edit this. ###### Isolated script execution Every script the AI writes runs in an isolated runner, separate from any other user's session: - **Network egress is restricted** to DatoCMS APIs, your project's asset storage domain, and a whitelist of well-known image services (Unsplash, Pexels, Pixabay, Picsum) - **Credential brokering**: scripts never see your real API token. The runner transparently injects credentials at the network layer, so a script cannot exfiltrate them — even if it tried - **Read-only enforcement**: when the AI uses the safe script variant, the runner blocks any non-`GET` request at the network layer, and the API itself rejects destructive operations - **Type-checking before execution**: scripts are validated by the TypeScript compiler before they're allowed to run, catching errors before they reach the API - **Per-script timeouts and monthly time budgets** prevent runaway loops and abuse ###### Script validation Beyond runtime isolation, scripts are statically analysed before execution and rejected if they: - Use `any` or `unknown` type annotations (which would bypass type-checking) - Cast through `never` (a common TypeScript escape hatch) - Include `@ts-ignore`, `@ts-expect-error`, or `@ts-nocheck` comments - Call API methods that the AI has not pre-declared via `get_api_methods` (the verification token system) ## Troubleshooting ###### Server not connecting 1. Verify your client supports remote MCP servers (Claude Code, Claude Desktop / Claude.ai via Connectors, ChatGPT via Developer Mode, Cursor, VS Code, Windsurf, and Antigravity all do) 2. Ensure your MCP client configuration uses the correct URL: `https://mcp.datocms.com` 3. Restart your IDE or client after configuration changes 4. Check that your firewall or corporate proxy allows outbound HTTPS to `mcp.datocms.com` and `oauth.datocms.com` ###### Authentication issues 1. If your token has been revoked or expired, the server will prompt your client to re-authenticate; trigger any DatoCMS tool to start the flow 2. Use the `whoami` tool to verify which DatoCMS account is currently signed in 3. During OAuth authorization, double-check that you granted access to the projects you want the assistant to work with 4. To switch accounts, sign out from your MCP client (the exact step depends on the client) and trigger a fresh authentication ###### Script execution failures 1. If the script hits a timeout, ask the assistant to break it into smaller steps 2. If you've exceeded your monthly execution time budget, wait for the budget to reset or upgrade your plan ###### Performance issues If operations are taking too long: 1. Break very complex tasks into smaller steps 2. Use more specific prompts to reduce exploration time 3. Check whether a simpler API method can achieve the same result ## Feedback & Contributing We value your feedback to improve the DatoCMS MCP server: - **Share your experience**: Let us know what works well and what doesn't - **Report bugs and suggestions**: Reach out at [support@datocms.com](mailto:support@datocms.com) — your feedback helps us identify common issues, improve documentation, and enhance the server's capabilities If the AI runs into a bug or gap in our API documentation while using the server, it can use the built-in `report_api_issue` tool to send a structured report directly to our team. --- # LLM-ready docs — LLM-ready Docs Source [docs]: https://www.datocms.com/docs/llm-ready-docs.md Working with AI tools requires high-quality context. DatoCMS addresses this by providing documentation in formats optimized for AI consumption, allowing assistants like Claude, ChatGPT, Cursor, and NotebookLM to deliver **accurate, context-aware responses** about DatoCMS features and APIs. DatoCMS offers three complementary approaches to accessing documentation for AI tools: ## Complete documentation (llms-full.txt) The complete DatoCMS documentation compiled into a single, perfectly formatted Markdown file. This includes all 500+ pages of content: API references, guides, migrations, plugins, Content Management API (CMA), Content Delivery API (CDA), and more. **Access:** - **URL**: [`https://www.datocms.com/docs/llms-full.txt`](https://www.datocms.com/docs/llms-full.txt) **What makes it effective:** - Clean Markdown with properly formatted code blocks - Logical structure maintained across all pages - Complete context spanning the entire documentation - Automatically regenerated with every docs update - No navigation menus, JavaScript, or extraneous content **Use cases:** - Building complex features that require understanding multiple DatoCMS concepts - Content migration projects - Team onboarding and training - Creating custom AI assistants with comprehensive DatoCMS knowledge ## Documentation index (llms.txt) A structured index of DatoCMS documentation following the [llms.txt standard](https://llmstxt.org/). Provides an overview of available documentation without the full content. **Access:** - **URL**: [`https://www.datocms.com/docs/llms.txt`](https://www.datocms.com/docs/llms.txt) **Use cases:** - Quick reference for documentation structure - Discovering available topics and guides - Navigation for AI tools that support llms.txt format ## Single-page Markdown export Every documentation and blog page includes a "Copy page" dropdown that provides content in AI-friendly formats. This enables quick extraction of specific pages without dealing with HTML formatting issues or web scraping complications. **Access methods:** - **Copy as Markdown**: Click the "Copy page" dropdown on any docs or blog page - **Direct URL conversion**: Append `.md` to any page URL to retrieve its Markdown version **Example:** ```plaintext https://www.datocms.com/docs/content-management-api.md ``` **Use cases:** - Troubleshooting specific integrations - Exploring particular API methods - Learning about individual DatoCMS features - Providing focused context to AI assistants for targeted questions ## Integrations ###### Claude Projects Claude Projects allow you to attach custom knowledge to Claude conversations. This is particularly effective with `llms-full.txt` for comprehensive DatoCMS expertise. **Setup:** 1. Navigate to [claude.ai](https://claude.ai/) and create a new Project 2. Download `llms-full.txt` from [https://www.datocms.com/docs/llms-full.txt](https://www.datocms.com/docs/llms-full.txt) 3. Upload the file to your Project 4. Add custom instructions (see [reference instructions](https://gist.github.com/stefanoverna/e6d225bc3eef2d11bdaae16fb433a5bd#file-datocms-expert-instructions-md)) 5. Name your Project (e.g., "DatoCMS Docs") **Capabilities:** - Ask migration questions and receive step-by-step instructions - Request working TypeScript scripts for content operations - Plan complex content model migrations with full DatoCMS context - Get accurate answers across all conversations in the Project ###### Custom GPTs Build a ChatGPT assistant specialized in DatoCMS using the complete documentation as its knowledge base. **Setup:** 1. Go to [ChatGPT GPT Builder](https://chat.openai.com/gpts/editor) 2. Click "Create a GPT" 3. Download `llms-full.txt` from [https://www.datocms.com/docs/llms-full.txt](https://www.datocms.com/docs/llms-full.txt) 4. In the Knowledge section, upload the downloaded file 5. Add instructions such as: "You are a DatoCMS expert. Answer questions using only the provided documentation. Include code examples when relevant." (see [reference instructions](https://gist.github.com/stefanoverna/e6d225bc3eef2d11bdaae16fb433a5bd#file-datocms-expert-instructions-md)) **Reference implementation:** Check the [official DatoCMS Expert GPT](https://chatgpt.com/g/g-68f2397c654081918601c5fa11a21616-datocms-expert) to see a working example. ###### NotebookLM Google's NotebookLM excels at deep research and learning across large documentation sets. **Setup:** 1. Create a new notebook in [NotebookLM](https://notebooklm.google.com/) 2. Add a source → paste `https://www.datocms.com/docs/llms-full.txt` 3. Allow processing to complete (~30 seconds) **Capabilities:** - Compare different DatoCMS features and APIs - Generate study guides for learning specific topics - Search across the entire documentation for related concepts - Understand relationships between different parts of the system **Use cases:** - Onboarding new team members - Exploring unfamiliar features - Research before implementing complex features ###### Cursor Cursor is an AI-powered code editor that benefits from documentation context while coding. **Setup:** 1. Open Cursor and type `@Docs` 2. Select "Add new doc" 3. Paste: `https://www.datocms.com/docs/llms-full.txt` **Important:** Always type the `@` symbol manually in the chat interface. Copy-pasting breaks the context reference. **Capabilities:** - Generate Next.js pages that fetch DatoCMS content - Add pagination, filtering, or sorting to GraphQL queries - Debug queries with full knowledge of available fields and filters - Write TypeScript scripts that interact with the Content Management API ###### Windsurf Windsurf is another AI coding assistant that supports custom documentation sources. **Setup:** 1. Open settings → Documentation 2. Add new documentation source 3. Enter the URL: `https://www.datocms.com/docs/llms-full.txt` **Important:** Always type the `@` symbol manually in the chat interface. Copy-pasting breaks the context reference. **Capabilities:** - Same as Cursor: context-aware code generation for DatoCMS integrations - API-aware debugging and query construction ###### Other AI tools Most AI assistants that accept file uploads or URL references can use `llms-full.txt`: - **File upload tools**: Download the file and upload directly - **URL-based tools**: Reference `https://www.datocms.com/docs/llms-full.txt` - **Chat interfaces**: Copy and paste relevant sections as needed ## Best practices ###### Choosing the right format **Use single-page Markdown export when:** - You need information about a specific feature or API method - Working on a focused task that doesn't require broader context - You want to minimize token usage in your AI assistant - Troubleshooting a specific error or implementation detail **Use llms-full.txt when:** - Building complex features that span multiple DatoCMS concepts - Planning migrations or major content model changes - Creating a persistent AI assistant with comprehensive DatoCMS knowledge - Team members need to learn DatoCMS from scratch - Working on projects where understanding the full system architecture matters ###### Effective prompting Provide clear, specific prompts that take advantage of the documentation context: **Good examples:** - "Using the Content Management API, write a script to bulk-update all blog posts to add a new field" - "How do I migrate content from WordPress to DatoCMS while preserving relationships between posts and categories?" - "Create a Next.js component that fetches localized content and handles fallbacks according to DatoCMS best practices" **Less effective examples:** - "How do I update posts?" (too vague) - "Write me a migration script" (missing context about source and requirements) - "Make a component" (no details about what it should do) ###### Iterative refinement AI assistants work best with iterative feedback: 1. Start with a clear initial request 2. Review the generated code or answer 3. Provide specific feedback on what needs adjustment 4. Request modifications: "Add error handling" or "Include image optimization" Most tasks succeed on the first attempt, with occasional minor refinements needed through follow-up prompts. ## Token consumption considerations The impact of using complete documentation (`llms-full.txt`) varies significantly depending on how your AI tool handles knowledge bases. **Tools with intelligent retrieval (Claude Projects, Custom GPTs, NotebookLM):** These systems don't load all 500+ pages into every conversation. Instead, they index the documentation and query only relevant sections as needed, retrieving context on-demand based on your questions. Token consumption is not a concern - the system automatically manages what context to include. **Tools without intelligent retrieval (direct chat interfaces, some coding assistants):** If you paste the full documentation directly into a chat or use tools that load entire files into context, you may encounter higher token usage per request and potential context window limits. However, the comprehensive context dramatically reduces incorrect or incomplete responses. > [!PROTIP] Pro tip: Our recommendation > Use Claude Projects or Custom GPTs for the best balance of comprehensive knowledge and efficient token usage. If your AI tool doesn't offer built-in intelligent retrieval but you need the full documentation, consider implementing RAG (Retrieval-Augmented Generation). > > For tools that don't intelligently manage large knowledge bases, use single-page exports (`.md` URLs) instead. For most practical tasks with the right tools, comprehensive documentation provides better results with acceptable cost. ## Limitations - **Markdown conversion quality**: Quality may vary across different pages when using `.md` URL conversion - **Documentation updates**: While `llms-full.txt` regenerates automatically, there may be a brief delay after documentation changes - **AI model capabilities**: Results depend on the underlying AI model's capabilities and training - **Context windows**: Some AI tools have limits on how much documentation they can process at once --- # Translating content with AI — Translating content with AI Source [docs]: https://www.datocms.com/docs/translating-content-with-ai.md Managing multilingual content traditionally requires coordinating with translation services or manual work for every content update—a time-consuming process that creates bottlenecks in content publication. AI-powered translation changes this by providing instant, high-quality translations directly within your editing interface. Modern AI models understand context, preserve formatting, and produce natural-sounding translations that adapt to your content rather than mechanical word-for-word replacements. The [(Image content)AI Translations](https://www.datocms.com/marketplace/plugins/i/datocms-plugin-ai-translations.md) plugin integrates leading AI providers—OpenAI (ChatGPT), Google (Gemini), Anthropic (Claude), and DeepL — directly into DatoCMS. Translate individual fields, entire records, multiple records from table views, or batch-translate whole models. The plugin intelligently handles complex field types including Structured Text, supports contextual translations for better accuracy, and preserves ICU Message Format patterns. ## What you can do The AI Translations plugin enables editors to: - **Translate individual fields**: Use field-level actions to translate content from one locale to another or to all locales at once - **Translate entire records**: Use the sidebar panel to translate all localizable fields in a record with a single action - **Bulk translate from table views**: Select multiple records in any table view and translate them all simultaneously - **Translate whole models**: Use the dedicated bulk translations page to translate all records across one or more models - **Work with multiple AI providers**: Choose between OpenAI (ChatGPT), Google (Gemini), Anthropic (Claude), or DeepL based on your needs and preferences - **Preserve complex formatting**: Automatically handle Structured Text, ICU Message Format patterns, HTML, and other complex field types - **Use contextual translations**: Leverage record context for more accurate, consistent translations that understand specialized terminology - **Enforce terminology with glossaries**: Use DeepL glossaries to ensure preferred translations for specific terms across all content The plugin works with all DatoCMS field types including single-line strings, markdown, structured text, modular content, SEO fields, and media fields with metadata. ## Requirements - DatoCMS project with at least two locales configured - API key from at least one supported provider: - **OpenAI**: Regular secret key from [platform.openai.com](https://platform.openai.com/) - **Google (Gemini)**: API key from GCP project with Generative Language API enabled - **Anthropic (Claude)**: API key from [console.anthropic.com](https://console.anthropic.com/) - **DeepL**: API key (Free or Pro) ## Installation Install the AI Translations plugin from the DatoCMS Marketplace: 1. Navigate to your DatoCMS project 2. Go to **Settings** → **Plugins** 3. Click **Add** → **From Marketplace** 4. Search for "AI Translations" 5. Click **Install** on the [AI Translations plugin](https://www.datocms.com/marketplace/plugins/i/datocms-plugin-ai-translations.md) The plugin will appear in your project's plugin list and be ready for configuration. ## Configuration Access the plugin configuration screen from **Settings** → **Plugins** → **AI Translations** → **Settings**. ###### Choose your AI provider **Vendor selection**: Select your preferred translation provider from the dropdown: - **DeepL** (recommended): Fastest response times, professional translation quality, specialized for language translation with glossary support - **OpenAI** (ChatGPT): Fast, widely available, excellent for general content - **Google** (Gemini): Cost-effective with strong multilingual capabilities - **Anthropic** (Claude): High-quality translations with nuanced understanding ###### Configure provider credentials **For OpenAI:** - **OpenAI API Key**: Paste your API key from [platform.openai.com/api-keys](https://platform.openai.com/api-keys) - **GPT Model**: Select your preferred model **For Google (Gemini):** - **Google API Key**: Paste your API key from Google Cloud Console - **Gemini Model**: Select your preferred model **For Anthropic (Claude):** - **Anthropic API Key**: Paste your API key from [console.anthropic.com](https://console.anthropic.com/) - **Anthropic Model**: Select from available Claude models for optimal quality **For DeepL:** - **DeepL API Key**: Paste your API key from [deepl.com/pro-api](https://www.deepl.com/pro-api) - **Use DeepL Free endpoint**: Enable if your key ends with `:fx` - **Formality**: Choose translation formality level (default, more, less) - **Advanced settings**: Configure glossaries and formatting options ###### Translatable field types Select which field editor types should show translation actions: - Single line string - Markdown - HTML Editor (WYSIWYG) - Textarea - Slug - JSON - SEO fields - Structured Text - Modular Content - Media Fields (translates metadata like title, alt text) Enable only the field types you need to translate. This keeps the interface clean and prevents accidental translations of fields that shouldn't change across locales. ###### Translation features - **Translate Whole Record**: Enable the sidebar panel that translates all localizable fields in a record with one action - **Translate Bulk Records**: Enable bulk translation from table views, allowing editors to select and translate multiple records simultaneously - **AI Bulk Translations Page**: Enable the dedicated page for translating entire models at once (accessible from **Settings** → **AI Bulk Translations**) ###### Prompt customization **Prompt Template**: Customize how the AI is instructed to translate content. Use placeholders: - `{fieldValue}`: The content to translate - `{fromLocale}`: Source language (e.g., "en-US") - `{toLocale}`: Target language (e.g., "pt-BR") - `{recordContext}`: Automatically generated context about the record **Default prompt:** ```plaintext Translate the following text from {fromLocale} to {toLocale}. Preserve all formatting, HTML tags, and placeholder variables. {recordContext} Text to translate: {fieldValue} ``` The `{recordContext}` placeholder provides the AI with information about other fields in the record, improving translation accuracy by understanding specialized terminology and maintaining consistency across related fields. ###### Access restrictions - **Models to exclude**: Specify model API keys that should not show translation features - **Roles to exclude**: Restrict which user roles can access translation features - **API Keys to exclude**: Block specific API keys from using the plugin ###### Debugging - **Enable debugging**: Turn on detailed console logging to troubleshoot translation issues ### Security best practices **API key storage:** - Keys are stored in plugin settings and used client-side - Never share your DatoCMS workspace publicly with API keys configured - Rotate keys periodically **Key restrictions:** - **OpenAI**: Use regular secret keys, not publishable keys; set usage limits in your OpenAI dashboard - **Google**: Restrict keys by HTTP referrer (`https://admin.datocms.com/*`) and enable only the Generative Language API - **Anthropic**: Set spending limits in the Anthropic console - **DeepL**: Set usage limits in your DeepL account dashboard The plugin automatically redacts API keys from debug logs to prevent accidental exposure. # Using the plugin #### Field-level translations Translate individual fields directly in the record editor: 1. Open any record with localizable fields 2. Click the field's dropdown menu (three dots in the top-right corner of the field) 3. Select **Translate to** → Choose a target locale or **All locales** 4. The plugin generates the translation and updates the field automatically **Translate from a different source:** - Select **Translate from** → Choose a source locale - The current locale's field will be filled with translated content from the selected source locale This is useful when your primary content is in a locale other than the default, or when you want to translate from a recently updated locale. #### Whole-record translations Translate all localizable fields in a record at once: 1. Open a record that has multiple locales 2. The **DatoGPT Translate** panel appears in the sidebar (if enabled in settings) 3. Select your source locale (the locale containing the content to translate) 4. Select your target locale (the locale to translate into) 5. Click **Translate Entire Record** 6. All translatable fields update with AI-generated translations This workflow is efficient for content editors who need to create complete translations for newly published content or update existing translations when source content changes. #### Bulk translations from table view Translate multiple records simultaneously from any model's table view: 1. Navigate to any model in the **Content** area 2. Switch to table view if not already displayed 3. Select multiple records by checking the boxes on the left 4. Click the **three dots** dropdown in the bottom bar 5. Choose **Translate records** 6. Select source and target locales 7. Click **Start Translation** 8. A progress modal shows translation status for all selected records This is ideal for translating batches of content after bulk imports, when launching a new locale, or when updating multiple related records. #### Bulk translations page Translate entire models using the dedicated bulk translations page: 1. Go to **Settings** → **AI Bulk Translations** 2. Select your source locale (containing the content to translate) 3. Select your target locale (to receive translations) 4. Choose one or more models to translate - Block models are automatically excluded - Only models with localizable fields appear 5. Click **Start Bulk Translation** 6. The progress modal displays real-time status as records are processed This workflow is designed for large-scale translation operations: launching new locales, migrating content, or keeping translations synchronized across your entire content base. #### Contextual translations The plugin supports context-aware translations through the `{recordContext}` placeholder in your prompt template. **How it works:** When translating a field, the plugin automatically generates a summary of other fields in the same record and includes it in the translation prompt. This gives the AI understanding of: - Specialized terminology used in the record - The overall topic and subject matter - Related content in other fields - Appropriate tone and style **Benefits:** - More accurate translations of technical terms and industry jargon - Consistent terminology across all fields in a record - Better understanding of context improves translation quality - Appropriate formality and tone based on content type > [!POSITIVE] An example > For a product record with fields like "Product Name: CloudSync Pro" and "Category: Enterprise Software", the AI understands it's translating technical content and maintains appropriate terminology rather than translating brand names or technical terms. ### ICU Message Format support The plugin intelligently handles [**ICU Message Format**](https://unicode-org.github.io/icu/userguide/format_parse/messages/) strings, preserving complex pluralization and selection logic during translation. **Smart masking:** - Simple variables like `{name}` are masked (protected from translation) - ICU structures like `{count, plural, one {...} other {...}}` are passed to the AI with explicit instructions to preserve the format **What gets translated:** The AI translates only the human-readable content inside ICU structures while preserving: - Variable names and placeholders - Keywords (`plural`, `select`, `one`, `other`, etc.) - Structural syntax - Number signs (`#`) and formatting codes **Example:** English: ```plaintext You have {count, plural, one {# message} other {# messages}} ``` Portuguese translation: ```plaintext Você tem {count, plural, one {# mensagem} other {# mensagens}} ``` The structure remains identical; only "message" and "messages" are translated to "mensagem" and "mensagens". ### DeepL glossaries When using DeepL as your translation provider, you can enforce preferred terminology through glossaries. **Requirements:** - DeepL API key with glossary access (check your plan) - Glossary IDs from your DeepL account **Configuration:** 1. Navigate to plugin settings → DeepL section 2. Expand **Advanced settings** 3. Configure glossaries: **Default glossary ID**: Used for all translations unless overridden **Glossaries by language pair**: Map specific language pairs to specific glossaries **Configuration examples:** **Single language pair:** If you only translate from English to German: - **Default glossary ID**: `gls-12345` (your EN→DE glossary) - **Glossaries by language pair**: *(leave empty)* **Multiple language pairs:** If you translate to multiple languages: - **Default glossary ID**: *(leave empty)* - **Glossaries by language pair**:`EN->DE=gls-german123 EN->FR=gls-french456 EN->PT-BR=gls-portuguese789` **Fallback strategy:** Use specific glossaries for main languages and a default for others: - **Default glossary ID**: `gls-fallback999` - **Glossaries by language pair**:`EN->DE=gls-german123`, `EN->FR=gls-french456` **Mapping syntax:** One entry per line. Supported formats: ```plaintext EN->DE=gls-abc123 en-US->pt-BR=gls-xyz789 fr→it gls-123 # alt arrow and delimiter *->pt-BR=gls-777 # wildcard: any source to target EN->*=gls-555 # wildcard: source to any target pt-BR=gls-777 # shorthand for *->pt-BR ``` **Creating glossaries:** Create and manage glossaries using the DeepL API (not through the plugin): **List existing glossaries:** Terminal window ```bash curl -H "Authorization: DeepL-Auth-Key $DEEPL_AUTH_KEY" \ https://api.deepl.com/v2/glossaries ``` **Create a new glossary:** Terminal window ```bash curl -X POST https://api.deepl.com/v2/glossaries \ -H "Authorization: DeepL-Auth-Key $DEEPL_AUTH_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Marketing-EN-DE", "source_lang": "EN", "target_lang": "DE", "entries_format": "tsv", "entries": "CTA\tCall-to-Action\nlead magnet\tLeadmagnet" }' ``` Copy the returned `glossary_id` and paste it into the plugin settings. **Testing:** 1. Create a small glossary with an obvious term 2. Add the glossary ID to plugin settings 3. Translate a field containing that term 4. Verify the glossary translation appears in the result ### Workflow recommendations **For individual content updates:** - Use field-level translations for quick updates to specific fields - Use whole-record translation when creating new localized versions **For launching new locales:** 1. Configure the new locale in DatoCMS 2. Use the bulk translations page to translate all models at once 3. Review and refine translations in critical content **For ongoing content maintenance:** - Translate new records immediately after creation using whole-record translation - Use bulk table view translations when updating multiple related records - Enable debugging temporarily if you encounter translation issues ### Quality optimization **Improve translation accuracy:** - Enable `{recordContext}` in your prompt template for context-aware translations - Use glossaries (DeepL) to enforce preferred terminology - Customize the prompt template to include industry-specific instructions - Review AI-generated translations before publishing, especially for marketing copy **Handle special content types:** - **Technical content**: Use glossaries or custom prompts mentioning technical terminology - **Marketing copy**: Consider using higher-quality models (e.g., `gpt-4.1`, `gemini-2.5-pro`) - **Legal content**: Always have professional review; AI is a starting point, not final output ## Troubleshooting ###### API key issues **Invalid API Key error:** - Verify the key matches the selected vendor - Check that the key hasn't expired or been revoked - Ensure there are no extra spaces or quotes around the key - Test the key directly with the provider's API playground **Rate limit / quota errors:** - Reduce translation concurrency by translating smaller batches - Switch to a lighter model (e.g., `gpt-4o-mini`, `gemini-2.5-flash-lite`) - Check your provider's dashboard for usage limits - Upgrade your plan if you consistently hit limits ###### Translation issues **Translations not appearing:** - Verify at least two locales are configured in your DatoCMS project - Check that the field type is enabled in **Translatable Field Types** settings - Ensure the field is set as localizable in the model schema - Check browser console for errors (enable debugging in plugin settings) **Poor translation quality:** - Add `{recordContext}` to your prompt template for context-aware translations - Try a more advanced model - Customize the prompt template with specific instructions - Use DeepL with glossaries for consistent terminology **Model not found:** - Verify the exact model ID exists for your account/region - Check spelling and capitalization - Refresh available models by re-entering your API key ###### DeepL-specific issues **Wrong endpoint error:** - Free keys (ending in `:fx`) require "Use DeepL Free endpoint" enabled in plugin settings - Pro keys should have this setting disabled **Glossary not working:** - Verify the glossary ID exists in your DeepL account - Check that glossary languages match your translation direction - Ensure the glossary was created for the correct language pair - Test with a known term from your glossary ###### Performance issues **Slow translations:** - Switch to faster models (`gpt-4.1-mini`, `gemini-2.5-flash`) - Translate smaller batches instead of entire models at once - Check your internet connection stability - Verify you're not hitting rate limits (check provider dashboard) **Bulk operations timing out:** - Reduce the number of records per batch - Translate one model at a time instead of multiple models - Use a faster model for initial translations, then refine critical content manually ## Limitations - **Browser-based execution**: API keys are used client-side; keep workspaces private - **Locale configuration**: Projects must have at least two locales for translations to function - **Field type support**: Only configured field types show translation actions - **Provider availability**: Translation quality and speed depend on selected provider and model - **Cost**: Translation usage incurs costs from your chosen AI provider - **No translation memory**: Each translation is independent; the plugin doesn't maintain a translation memory - **Manual review recommended**: AI translations should be reviewed before publishing, especially for critical content --- # Visual Editing — Visual Editing Source [docs]: https://www.datocms.com/docs/visual-editing.md Visual Editing lets content editors **click directly on any element of your website** to edit it in DatoCMS, without hunting through forms and fields. Combined with draft content and real-time updates, editors see **saved changes reflected** on the page they're editing. > [!POSITIVE] Available on every current plan > Visual Editing is included in every current DatoCMS plan (including the free Developer plan, Professional, and Enterprise) at no additional charge. It works with all your primary and sandbox environments. > > Note: Visual Editing may **not** be available for some older, grandfathered "Legacy" plans. If you're not sure, please [contact support](https://www.datocms.com/support.md) and we can check for you. ## The problem it solves In a traditional headless CMS workflow, there's a disconnect between what editors see in the CMS (forms, fields, JSON) and what visitors see on the website. Editors have to make changes in the CMS, save, wait for a preview to rebuild, switch tabs to check the result, and go back to make further adjustments. This loop is slow, error-prone, and frustrating — especially for non-technical editors who think in terms of "the headline on the homepage", not "the `title` field on the `home_page` record". Visual Editing closes this gap entirely. Editors work with **the actual website** (the real layout, the real typography, the real context) and every piece of content becomes a **direct entry point back into the CMS**. ## Two ways to use it Visual Editing supports two workflows that serve different editing styles. Both can coexist, and editors pick whichever suits the task at hand. ###### Browsing the website directly Editors visit the website in draft mode (typically via a preview URL) and interact with content right there. When they hover over any editable element (a title, body text, an image alt text) a subtle overlay appears. Clicking it **opens DatoCMS in a new browser tab**, navigated directly to the exact field that controls that piece of content. There's no guesswork about "where does this text live in the CMS?". (Video content) Click-to-edit overlays ###### Side-by-side editing inside DatoCMS The [Web Previews plugin](https://www.datocms.com/marketplace/plugins/i/datocms-plugin-web-previews.md) is the bridge that connects your website to your DatoCMS project. Once installed, it brings a **live preview of your website directly into the DatoCMS interface**, turning the CMS from a form-based tool into a visual editing environment. The plugin adds several touchpoints to the DatoCMS UI: - **A "Visual" tab** in the main navigation: a full-screen, side-by-side editing view where the website preview sits next to the editing panel. Editors click on any element in the preview, and the corresponding record and field open right there. The tab includes: - An address bar for navigating the preview - Viewport controls for testing responsive layouts - A frontend selector for switching between environments (e.g. production vs. staging) - **Preview links in the record sidebar**: when editors open any record, they see quick links to view that content on the actual website. The plugin determines which URL corresponds to each record by calling an API endpoint on your frontend. - **A full iframe preview in the sidebar**: beyond just links, editors can expand an inline preview of the page directly in the sidebar, with viewport presets (mobile, tablet, desktop) and auto-reload on save. The plugin supports **multiple frontends**, so if your content powers different websites or environments, editors can switch between them from a single dropdown. ###### Bidirectional navigation The connection between the CMS and the preview **works in both directions**. When editors browse through records in DatoCMS, the preview navigates to the corresponding page automatically. And when they click around in the website preview, DatoCMS follows along, opening the relevant record. This means editors can start from whichever side feels natural (the content or the page) and **the other side stays in sync**. (Video content) Side-by-side editing ## Real-time feedback In both workflows, when combined with [Real-time Updates](/docs/real-time-updates-api.md), editors see their saved changes reflected on the preview they're editing. There's no need to reload: the preview updates live, giving editors immediate confidence that their changes look right in context. ## The building blocks Visual Editing is not a single feature, but the combination of several DatoCMS capabilities that can be adopted incrementally: - [**Draft Mode**](/docs/general-concepts/draft-published.md): lets your frontend serve unpublished content during preview sessions - [**Real-time Updates**](/docs/real-time-updates-api.md): pushes content changes to the preview without a page refresh - **Content Link**: adds click-to-edit overlays connecting frontend elements to CMS fields - [**Web Previews plugin**](https://www.datocms.com/marketplace/plugins/i/datocms-plugin-web-previews.md): embeds the preview inside DatoCMS for a unified editing experience You can **adopt each capability independently** and stop at any point — each one delivers value on its own. But the full combination is where the experience really comes together. The integration of all these layers is designed to be straightforward, especially if you start from one of our [tech starter kits](https://www.datocms.com/marketplace/starters.md). These official scaffolds come pre-configured with Draft Mode, Real-time Updates, Content Link, and Web Previews already wired together, so you get a fully working Visual Editing setup with minimal effort and can focus on your content and design. ## How it works technically ###### 1\. Embedded metadata When your frontend fetches draft content from the [Content Delivery API](/docs/content-delivery-api.md), DatoCMS can use a technique called [steganography](https://en.wikipedia.org/wiki/Steganography) to **embed invisible metadata into text fields**. This metadata, hidden using special Unicode characters that don't affect how text appears visually, carries information about **which record and field produced each piece of text**. Our plugins then parse this invisible metadata to match the rendered DOM nodes to the DatoCMS fields that they came from. You enable this by passing these options when querying the CDA using our [cda-client](https://github.com/datocms/cda-client): ```javascript executeQuery(query, { includeDrafts: true, contentLink: 'v1', // Must be exactly 'v1' baseEditingUrl: 'https://your-project.admin.datocms.com', // Your project domain }); ``` > [!WARNING] Invisible metadata can break string comparisons, JS, CSS, etc. > Because this invisible metadata is injected into the string values themselves, it can lead to unexpected situations where strings that look visually the same are actually different: > > ```javascript > const firstString = 'a'; // Just the letter > const secondString = 'a󠁡'; // This one has invisible metadata at the end > > > /* They are not the same values! */ > firstString == secondString; // FALSE > > > /* They are not the same lengths */ > firstString.length; // 1 > secondString.length; // 3 (!) because of the invisible chars > ``` > > This can break things like CSS layouts where you use field values like `left` or `right` or `blue` or `#FF0034`, Javascript equality comparisons like `==` or `===` , string length checks, regex end-of-line checks, etc. > > Fortunately, the fix is straightforward: You can use the `stripStega()` utility from [@datocms/content-link](https://github.com/datocms/content-link#low-level-utilities) to sanitize the string before use: > > ```javascript > import {stripStega} from '@datocms/content-link'; > const firstString = 'a'; // Just the letter > const secondString = 'a󠁡'; // This one has invisible metadata at the end > > > /* Strip stega before any string comparisons */ > stripStega(firstString) == stripStega(secondString); // TRUE now! > ``` > > **TL;DR: Use** [**stripStega()**](https://github.com/datocms/content-link#low-level-utilities) **any time a string is used as a raw literal value in comparisons or logic or layout.** ###### 2\. Content Link component A `` component (available for every supported framework) **scans the page for this embedded metadata** and renders interactive overlays on hover. Overlays have a configurable `hue` property that accepts values from 0-359, allowing you to choose the color that best matches your frontend/branding. Clicking an overlay opens DatoCMS at the exact field — either in a new tab or inside the Web Previews plugin panel if the site is loaded within DatoCMS. The component **detects its context automatically**, so no code changes are needed on your frontend to support both modes. You render this component in your root layout, only when draft mode is active: ```plaintext {draftModeEnabled && } ``` ###### 3\. Web Previews plugin The [Web Previews](https://www.datocms.com/marketplace/plugins/i/datocms-plugin-web-previews.md) plugin communicates with your frontend through two integration points: - **Preview Links API**: an endpoint on your frontend that receives record information from DatoCMS (the record ID, model API key, and current locale) and returns the URL where that record can be previewed. This is how the plugin knows which page to show for each record. - **Draft Mode route**: your existing route that activates draft mode and redirects to the preview page. The plugin calls this to ensure the iframe always loads draft content. The Content Link component on your frontend and the plugin communicate automatically via an iframe messaging protocol: when an editor clicks on content in the preview, the frontend tells the plugin which record to open, and the plugin navigates the CMS accordingly. ###### Setting up the plugin 1. Install the [Web Previews plugin](https://www.datocms.com/marketplace/plugins/i/datocms-plugin-web-previews.md) from the DatoCMS marketplace 2. Add a frontend with: - **Name**: a label for this frontend (e.g. "Production", "Staging") - **Preview Links API endpoint**: `https://yoursite.com/api/preview-links?token=your-secret` - **Draft Mode route**: `https://yoursite.com/api/draft-mode/enable?token=your-secret` 3. Optionally configure custom viewport presets, multiple frontends, and sidebar display preferences ## Framework integration guides Each framework has its own guide covering the full setup (Draft Mode, Real-time Updates, Content Link, and Web Previews) with working code from our official starter kits: - [Next.js Visual Editing](/docs/next-js/visual-editing.md) - [Nuxt Visual Editing](/docs/nuxt/visual-editing.md) - [SvelteKit Visual Editing](/docs/svelte/visual-editing.md) - [Astro Visual Editing](/docs/astro/visual-editing.md) ###### Underlying library All framework integrations are built on top of [`@datocms/content-link`](https://github.com/datocms/content-link), a framework-agnostic library that handles metadata detection, overlay rendering, and communication with the Web Previews plugin. If you're using a framework we don't have an SDK for, you can integrate directly with this library. ## Comparison with Vercel Content Link Vercel offers a similar feature also called [Content Link](https://vercel.com/docs/workflow-collaboration/edit-mode#content-link) (part of Vercel's Edit Mode). DatoCMS **fully integrates with Vercel Content Link** — the Content Delivery API can embed the metadata that Vercel expects, so you can use Vercel's overlay UI if you prefer. We have a [dedicated guide for setting up Vercel Content Link with DatoCMS](/docs/content-link/how-to-use-content-link.md). Both approaches use the same underlying technique (invisible metadata embedded in text fields), but there are key differences: - **Plan requirements**: Vercel Content Link requires a Vercel Pro or Enterprise plan. DatoCMS Visual Editing works on every plan, including Free. - **Environment**: Vercel Content Link only works on Vercel preview deployments. DatoCMS Visual Editing works in any environment (development, staging, or production) and on any hosting platform. - **Editing experience**: Vercel Content Link opens the CMS in a new tab. DatoCMS Visual Editing (with the Web Previews plugin) offers a side-by-side editing experience directly within DatoCMS, with bidirectional navigation and real-time updates. > [!WARNING] Don't use both simultaneously > If you deploy on Vercel, you should choose one approach or the other — using both simultaneously would result in duplicate overlays. DatoCMS Visual Editing provides a more comprehensive and widely available experience, while Vercel Content Link may be a simpler option if you're already on a Vercel Pro or Enterprise plan and don't need the side-by-side editing workflow. --- # Working with Structured Text — Structured Text and \`dast\` format Source [docs]: https://www.datocms.com/docs/structured-text/dast.md Structured Text content is stored as a JSON object consisting of two mandatory keys: - `document`: the content, expressed as a [`unist`](https://github.com/syntax-tree/unist) tree; - `schema`: a string that specifies the unist dialect used inside the `document` itself. ```json { "schema": "dast", "document": { "type": "root", "children": [...] } } ``` Generally speaking, you want to set the `schema` key to the `dast` dialect (which stands for **D**atoCMS **A**bstract **S**yntax **T**ree), so that: - you can take advantage of the default **Structured Text** editor that DatoCMS offers; - you can reinforce a number of additional validations to ensure consistency within the document. If you would like to to use a custom [unist](https://github.com/syntax-tree/unist) format rather than `dast`, please [let us know!](https://www.datocms.com/support.md?topics=feature-request) ### DatoCMS Abstract Syntax Tree (`dast`) specification The `dast` specification adheres to the [Unified](https://unifiedjs.com/) collective, which offers a large ecosystem of utilities to parse, transform, manipulate, convert, and serialize content of any kind. Unified is implemented and used as foundation by several popular libraries, such as [rehype](https://github.com/rehypejs/rehype) (HTML parser), [remark](https://github.com/remarkjs/remark) (Markdown parser) and the [MDX project](https://mdxjs.com/). All these different projects are able to integrate with each other due to the fact that, to describe the content they treat, they all use the same common JSON format called [`unist`](https://github.com/syntax-tree/unist). (Image content) Just like HTML, a `dast` document is composed of nodes within nodes: - Each node has a type attributed called `type` - The top-level node in the `dast` specification must be of type `root` - Most nodes have a `children` attribute to specify the nodes it contains - The leaves of the tree are nodes of type `span`, which do not offer a `children` attribute but store the final text as a string in their `value` attribute - The specs define exactly which attributes and children each node permits. Let's look at an example: ```json { "type": "root", "children": [ { "type": "heading", "level": 1, "children": [ { "type": "span", "marks": [], "value": "This is a title!" } ] }, { "type": "paragraph", "children": [ { "type": "span", "value": "This is a " } { "type": "span", "marks": ["strong"], "value": "paragraph!" } ] }, { "type": "list", "style": "bulleted", "children": [ { "type": "listItem", { "type": "paragraph", "children": [ { "type": "span", "value": "And this is a list!" } ] }, } ] } ] } ``` ### Working with `dast` documents The package [`datocms-structured-text-utils`](https://github.com/datocms/structured-text/tree/main/packages/utils) offers JavaScript nodes definitions, Typescript types and type guards and many tree manipulation utilities. Additionally, you can take advantage of [several `unist` utilities](https://github.com/syntax-tree/unist#list-of-utilities) to work with nodes in a `dast` document. For example, you can compose and assemble a document with [`unist-builder`](https://github.com/syntax-tree/unist-builder), select nodes with a CSS-like syntax using [`unist-util-select`](https://github.com/syntax-tree/unist-util-select) or have a compact representation of the document via [`unist-util-inspect`](https://github.com/syntax-tree/unist-util-inspect): ```javascript import u from 'unist-builder'; import inspect from 'unist-util-inspect'; const document = u('root', [ u('heading', { level: 1}, [ u('span', 'This is the title!') ]), u('paragraph', [ u('span', 'And '), u('span', { marks: ['strong'] }, 'this'), u('span', ' is a paragraph!') ]) ]); console.log(inspect(document)); root[2] ├─0 heading[1] │ │ level: 1 │ └─0 span "This is the title!" └─1 paragraph[3] ├─0 span "And " ├─1 span "this" │ marks: ["strong"] └─2 span " is a paragraph!" ``` ### Converting HTML to Structured Text and vice versa These are the utilities contained within **datocms/structured-text**: **Conversion utilities** - [`datocms-html-to-structured-text`](https://github.com/datocms/structured-text/tree/main/packages/html-to-structured-text) — Convert HTML/Markdown into Structured Text **Rendering utilities** - [`datocms-structured-text-to-plain-text`](https://github.com/datocms/structured-text/tree/main/packages/to-plain-text) — Render Structured Text as plain text - [`datocms-structured-text-to-markdown`](https://github.com/datocms/structured-text/tree/main/packages/to-markdown) — Render Structured Text as Markdown - [`datocms-structured-text-to-html-string`](https://github.com/datocms/structured-text/tree/main/packages/to-html-string) — Render Structured Text as an HTML string - [`datocms-structured-text-to-dom-nodes`](https://github.com/datocms/structured-text/tree/main/packages/to-dom-nodes) — Transform Structured Text into a list of DOM nodes **Framework components** - **React** → [``](https://github.com/datocms/react-datocms#structured-text) - **Vue** → [``](https://github.com/datocms/vue-datocms#structured-text) - **Svelte / SvelteKit** → [``](https://github.com/datocms/datocms-svelte/tree/main/src/lib/components/StructuredText) - **Astro** → [``](https://github.com/datocms/astro-datocms/tree/main/src/StructuredText) ### JSON Schema for `dast` The latest `dast` format specification is always available at the following URL: [https://site-api.datocms.com/docs/dast-schema.json](https://site-api.datocms.com/docs/dast-schema.json) ### `root` Every `dast` document MUST start with a `root` node. It allows the following children nodes: [`paragraph`](/docs/structured-text/dast.md#paragraph), [`heading`](/docs/structured-text/dast.md#heading), [`list`](/docs/structured-text/dast.md#list), [`code`](/docs/structured-text/dast.md#code), [`blockquote`](/docs/structured-text/dast.md#blockquote), [`block`](/docs/structured-text/dast.md#block) and [`thematicBreak`](/docs/structured-text/dast.md#thematicBreak). ```json { "type": "root", "children": [ { "type": "heading", "level": 1, "children": [ { "type": "span", "value": "Title" } ] }, { "type": "paragraph", "children": [ { "type": "span", "value": "A simple paragraph!" } ] } ] } ``` ### `paragraph` A `paragraph` node represents a unit of textual content. It allows the following children nodes: [`span`](/docs/structured-text/dast.md#span), [`link`](/docs/structured-text/dast.md#link), [`itemLink`](/docs/structured-text/dast.md#itemLink), [`inlineItem`](/docs/structured-text/dast.md#inlineItem) and [`inlineBlock`](/docs/structured-text/dast.md#inlineBlock). ```json { "type": "paragraph", "children": [ { "type": "span", "value": "A simple paragraph!" } ] } ``` ### `span` A `span` node represents a text node. It might optionally contain decorators called `marks`. It is worth mentioning that you can use the `\n` newline character to express line breaks. It does not allow children nodes. ```json { "type": "span", "marks": ["highlight", "emphasis"], "value": "Some random text here, move on!" } ``` ### `link` A `link` node represents a normal hyperlink. It might optionally contain a number of additional custom information under the `meta` key. You can also link to DatoCMS records using the [`itemLink`](/docs/structured-text/dast.md#itemLink) node. It allows the following children nodes: [`span`](/docs/structured-text/dast.md#span). ```json { "type": "link", "url": "https://www.datocms.com/", "meta": [ { "id": "rel", "value": "nofollow" }, { "id": "target", "value": "_blank" } ], "children": [ { "type": "span", "value": "The best CMS in town" } ] } ``` ### `itemLink` An `itemLink` node is similar to a [`link`](/docs/structured-text/dast.md#link) node node, but instead of linking a portion of text to a URL, it links the document to another record present in the same DatoCMS project. It might optionally contain a number of additional custom information under the `meta` key. If you want to link to a DatoCMS record without having to specify some inner content, then please use the [`inlineItem`](/docs/structured-text/dast.md#inlineItem) node. It allows the following children nodes: [`span`](/docs/structured-text/dast.md#span). ```json { "type": "itemLink", "item": "38945648", "meta": [ { "id": "rel", "value": "nofollow" }, { "id": "target", "value": "_blank" } ], "children": [ { "type": "span", "value": "Matteo Giaccone" } ] } ``` ### `inlineItem` An `inlineItem`, similarly to [`itemLink`](/docs/structured-text/dast.md#itemLink), links the document to another record but does not specify any inner content (children). It can be used in situations where it is up to the frontend to decide how to present the record (ie. a widget, or an `` tag pointing to the URL of the record with a text that is the title of the linked record). It does not allow children nodes. ```json { "type": "inlineItem", "item": "74619345" } ``` ### `inlineBlock` It does not allow children nodes. ```json { "type": "inlineBlock", "item": "1238455312" } ``` ### `heading` An `heading` node represents a heading of a section. Using the `level` attribute you can control the rank of the heading. It allows the following children nodes: [`span`](/docs/structured-text/dast.md#span), [`link`](/docs/structured-text/dast.md#link), [`itemLink`](/docs/structured-text/dast.md#itemLink), [`inlineItem`](/docs/structured-text/dast.md#inlineItem) and [`inlineBlock`](/docs/structured-text/dast.md#inlineBlock). ```json { "type": "heading", "level": 2, "children": [ { "type": "span", "value": "An h2 heading!" } ] } ``` ### `list` A `list` node represents a list of items. Unordered lists must have its `style` field set to `bulleted`, while ordered lists, instead, have its `style` field set to `numbered`. It allows the following children nodes: [`listItem`](/docs/structured-text/dast.md#listItem). ```json { "type": "list", "style": "bulleted", "children": [ { "type": "listItem", "children": [ { "type": "paragraph", "children": [ { "type": "span", "value": "This is a list item!" } ] } ] } ] } ``` ### `listItem` A `listItem` node represents an item in a list. It allows the following children nodes: [`paragraph`](/docs/structured-text/dast.md#paragraph) and [`list`](/docs/structured-text/dast.md#list). ```json { "type": "listItem", "children": [ { "type": "paragraph", "children": [ { "type": "span", "value": "This is a list item!" } ] } ] } ``` ### `code` A `code` node represents a block of preformatted text, such as computer code. It does not allow children nodes. ```json { "type": "code", "language": "javascript", "highlight": [1], "code": "function greetings() {\n console.log('Hi!');\n}" } ``` ### `blockquote` A `blockquote` node is a containter that represents text which is an extended quotation. It allows the following children nodes: [`paragraph`](/docs/structured-text/dast.md#paragraph). ```json { "type": "blockquote", "attribution": "Oscar Wilde", "children": [ { "type": "paragraph", "children": [ { "type": "span", "value": "Be yourself; everyone else is taken." } ] } ] } ``` ### `block` Similarly to [Modular Content](/docs/content-modelling/modular-content.md) fields, you can also embed block records into Structured Text. A `block` node stores a reference to a DatoCMS block record embedded inside the `dast` document. This type of node can only be put as a direct child of the [`root`](/docs/structured-text/dast.md#root) node. It does not allow children nodes. ```json { "type": "block", "item": "1238455312" } ``` ### `thematicBreak` A `thematicBreak` node represents a thematic break between paragraph-level elements: for example, a change of scene in a story, or a shift of topic within a section. It does not allow children nodes. ```json { "type": "thematicBreak" } ``` --- # Working with Structured Text — Migrating content to Structured Text Source [docs]: https://www.datocms.com/docs/structured-text/migrating-content-to-structured-text.md The goal of this guide is to teach you how to migrate an existing DatoCMS project to [Structured Text](/docs/content-modelling/structured-text.md) fields. To illustrate the process, we'll use [an example project](https://dashboard.datocms.com/clone?id=42030&name=Structured+Text+demo) that you can clone on your account to follow each step. > [!POSITIVE] In a hurry? Download the final result! > If you prefer to skip the tutorial and just take a look at the final code, head over to this [GitHub repo](https://github.com/datocms/structured-text-migration-example). ## Setup First of all, to follow this guide, make sure to clone this [example project](https://dashboard.datocms.com/clone?id=42030&name=Structured+Text+demo) into your own DatoCMS account. Done? Great! Now's open the terminal, create a new directory for the migration project, and install the DatoCMS CLI: Terminal window ```bash mkdir structured-text-migrations cd structured-text-migrations npm init --yes npm i --save-dev typescript datocms tsc --init mkdir -p migrations/utils ``` Now let's link the CLI to your DatoCMS project: Terminal window ```bash $ datocms link ✔ Choose a workspace › My organization ✔ Search and select a project › My project ✔ Directory where script migrations will be stored [./migrations]: ✔ API key of the DatoCMS model used to store migration data [schema_migration]: Writing "datocms.config.json"... done ``` Once linked, the CLI will automatically resolve an API token for the linked project using your OAuth credentials. No need to manually create API tokens or set environment variables. ⚠️ **Important:** Make sure you do **not** commit this `.env` file to your version control system, as it contains sensitive credentials. ## High-level strategy & Project skeleton This is the content schema of the cloned project: (Image content) The fields we want to convert into Structured Text are the following: - **HTML Article \> Content** (HTML multi-paragraph text); - **Markdown Article \> Content** (Markdown multi-paragraph text); - **Modular Content Article \> Content** (Modular content); To do that, we're going to write three [migration scripts](/docs/scripting-migrations/scripting-migrations-with-the-datocms-cli.md) (one for each model) and test the result inside a [sandbox environment](/docs/scripting-migrations/introduction.md). For every field, the high-level plan will be the same: 1. Create a new Structured Text field for the model; 2. For every article, take the old content, convert it to Structured Text and save it in the new field; 3. Destroy the old field. Inside the `migrations/utils` directory, we're adding some functions that we're going to use for all three migrations: - `createStructuredTextFieldFrom` creates a new Structured Text field with the same label and API key as an existing field, but prefixed with `structured_text_` (basically, step 1 of our plan); - `getAllRecords` fetches all the records of a specific model using the `nested` option, so that for modular content fields we get the full payload of the inner block records instead of just their ID (that's the first bit of step 2); - `swapFields` destroys the old field, and renames the new Structured Text field as the old one (that's step 3 of our plan); Lastly, since: - some API calls expect the model ID and not the model API key, and - model IDs are different on each environment, and - we want our migrations to work on any environment we can avoid hardcoding model IDs writing a `getModelIdsByApiKey` function that returns an object mapping API keys to model IDs: ./migrations/utils/createStructuredTextFieldFrom.ts ```typescript import { Client, SimpleSchemaTypes } from 'datocms/lib/cma-client-node'; export default async function createStructuredTextFieldFrom( client: Client, modelApiKey: string, fieldApiKey: string, modelBlockIds: SimpleSchemaTypes.ItemTypeIdentity[], ): Promise { const legacyField = await client.fields.find( `${modelApiKey}::${fieldApiKey}`, ); const newApiKey = `structured_text_${fieldApiKey}`; const label = `${legacyField.label} (Structured-text)`; console.log(`Creating ${modelApiKey}::${newApiKey}`); return client.fields.create(modelApiKey, { label, api_key: newApiKey, field_type: 'structured_text', fieldset: legacyField.fieldset, validators: { structured_text_blocks: { item_types: modelBlockIds, }, structured_text_links: { item_types: [] }, }, }); } // ./migrations/utils/getAllRecords.ts import { Client } from 'datocms/lib/cma-client-node'; export default async function getAllRecords( client: Client, modelApiKey: string, ) { const records = await client.items.list({ filter: { type: modelApiKey }, nested: true, }); console.log(`Found ${records.length} records!`); return records; } // ./migrations/utils/swapFields.ts import { Client } from 'datocms/lib/cma-client-node'; export default async function swapFields( client: Client, modelApiKey: string, fieldApiKey: string, ) { const oldField = await client.fields.find(`${modelApiKey}::${fieldApiKey}`); const newField = await client.fields.find( `${modelApiKey}::structured_text_${fieldApiKey}`, ); // destroy the old field await client.fields.destroy(oldField.id); // rename the new field await client.fields.update(newField.id, { api_key: fieldApiKey, label: oldField.label, position: oldField.position, }); } // ./migrations/utils/getModelIdsByApiKey.ts import { Client } from 'datocms/lib/cma-client-node'; import { ItemType } from '@datocms/cma-client/dist/types/generated/SimpleSchemaTypes'; export default async function getModelIdsByApiKey( client: Client, ): Promise> { const models = await client.itemTypes.list(); return models.reduce( (acc, itemType) => ({ ...acc, [itemType.api_key]: itemType, }), {}, ); } // migrations/utils/findOrCreateUploadWithUrl.ts import { Client } from 'datocms/lib/cma-client-node'; import path from 'path'; export default async function findOrCreateUploadWithUrl( client: Client, url: string, ) { let upload; if (url.startsWith('https://www.datocms-assets.com')) { const pattern = path.basename(url).replace(/^[0-9]+\-/, ''); const matchingUploads = await client.uploads.list({ filter: { fields: { filename: { matches: { pattern, case_sensitive: false, regexp: false, }, }, }, }, }); upload = matchingUploads.find((u) => { return u.url === url; }); } if (!upload) { upload = await client.uploads.createFromUrl({ url }); } return upload; } ``` ## Migrating HTML content Let's create the first migration script: Terminal window ```bash > datocms migrations:new convertHtmlArticles Created migrations/1612281851_convertHtmlArticles.ts ``` Replace the content of the file with the following skeleton, which uses the utilities we just created: ./migrations/1612281851\_convertHtmlArticles.rs ```typescript import getModelIdsByApiKey from './utils/getModelIdsByApiKey'; import createStructuredTextFieldFrom from './utils/createStructuredTextFieldFrom'; import htmlToStructuredText from './utils/htmlToStructuredText'; import getAllRecords from './utils/getAllRecords'; import swapFields from './utils/swapFields'; import convertImgsToBlocks from './utils/convertImgsToBlocks'; import { Client, SimpleSchemaTypes } from 'datocms/lib/cma-client-node'; type HtmlArticleType = SimpleSchemaTypes.Item & { title: string; content: string; }; export default async function convertHtmlArticles(client: Client) { const modelIds = await getModelIdsByApiKey(client); await createStructuredTextFieldFrom(client, 'html_article', 'content', [ modelIds.image_block.id, ]); const records = (await getAllRecords( client, 'html_article', )) as HtmlArticleType[]; for (const record of records) { const structuredTextContent = await htmlToStructuredText( record.content, convertImgsToBlocks(client, modelIds), ); await client.items.update(record.id, { structured_text_content: structuredTextContent, }); if (record.meta.status !== 'draft') { await client.items.publish(record.id); } } await swapFields(client, 'html_article', 'content'); } ``` A couple of notes: - Inside the HTML field there might be image tags (``). Structured Text does not have a specific node to handle images because it offers `block` nodes, which is a more powerful primitive. This means that, during the transformation process, we'll need to convert those `` tags into block records of type "Image" (that's the same block currently used by the Modular Content field). For this reason, in line 19 we pass the `image_block` model ID to configure the newly created Structured Text field to accept such type of blocks; - In the highlighted lines we're going to perform the actual [records update](/docs/content-management-api/resources/item/create.md#structured-text-fields) and make sure we republish updated records (unless they were in draft). So what is left to do is to implement the `htmlToStructuredText()` function. The [`datocms-html-to-structured-text`](https://github.com/datocms/structured-text/tree/main/packages/html-to-structured-text) package offers a `parse5ToStructuredText` function that is meant to be used in NodeJS environments to perform the conversion from HTML to Structured Text ([`parse5`](https://github.com/inikulin/parse5) is a popular HTML parser for NodeJS). Internally, the `parse5ToStructuredText` will take the parse5 Document, convert it into a [`hast`](https://github.com/syntax-tree/hast) tree, and then convert the `hast` tree into a [`dast`](/docs/structured-text/dast.md#datocms-abstract-syntax-tree--dast--specification) tree (that's the format of our Structured Text document). All these conversions might seem an overkill, but we will see later how having `hast` as an intermediate representation will come in handy. Let's install some dependencies: Terminal window ```bash npm install --save-dev parse5 \ datocms-html-to-structured-text \ datocms-structured-text-utils \ unist-utils-core@1.0.5 ``` Now we have everything we need to build our `htmlToStructuredText` function: ./migrations/utils/htmlToStructuredText ```typescript import { parse } from 'parse5'; import { parse5ToStructuredText, Options, } from 'datocms-html-to-structured-text'; import { validate } from 'datocms-structured-text-utils'; export default async function htmlToStructuredText( html: string, settings: Options, ) { if (!html) { return null; } const result = await parse5ToStructuredText( parse(html, { sourceCodeLocationInfo: true, }), settings, ); const validationResult = validate(result); if (!validationResult.valid) { throw new Error(validationResult.message); } return result; } ``` Please note that in the highlighted line we use the `validate` function from the `datocms-structured-text-utils` package to make sure that the final result is valid Structured Text. #### Converting image tags into blocks The code above will convert 99% of the HTML correctly, but **images present in the content will be skipped**. As we already noted before, that's because Structured Text does not have a specific node to handle images. Instead, it offers [`block` nodes](/docs/structured-text/dast.md#block), which can handle images and much more. We have to pass some additional settings to the `parse5ToStructuredText` function to tell it how to convert `` tags to `block` nodes: ./migrations/utils/convertImgsToBlocks.ts ```typescript import { buildBlockRecord, Client, SimpleSchemaTypes, } from 'datocms/lib/cma-client-node'; import { visit, find } from 'unist-utils-core'; import { HastNode, HastElementNode, CreateNodeFunction, Context, } from 'datocms-html-to-structured-text'; import { Options } from 'datocms-html-to-structured-text'; import findOrCreateUploadWithUrl from './findOrCreateUploadWithUrl'; export default function convertImgsToBlocks( client: Client, modelIds: Record, ): Options { return { preprocess: (tree: HastNode) => { const liftedImages = new WeakSet(); const body = find( tree, (node: HastNode) => (node.type === 'element' && node.tagName === 'body') || node.type === 'root', ); visit( body, (node, index, parents) => { if ( node.type !== 'element' || node.tagName !== 'img' || liftedImages.has(node) || parents.length === 1 ) { return; } const imgParent = parents[parents.length - 1]; imgParent.children.splice(index, 1); let i = parents.length; let splitChildrenIndex = index; let childrenAfterSplitPoint: HastNode[] = []; while (--i > 0) { const parent = parents[i]; const parentsParent = parents[i - 1]; childrenAfterSplitPoint = parent.children.splice(splitChildrenIndex); splitChildrenIndex = parentsParent.children.indexOf(parent); let nodeInserted = false; if (i === 1) { splitChildrenIndex += 1; parentsParent.children.splice(splitChildrenIndex, 0, node); liftedImages.add(node); nodeInserted = true; } splitChildrenIndex += 1; if (childrenAfterSplitPoint.length > 0) { parentsParent.children.splice(splitChildrenIndex, 0, { ...parent, children: childrenAfterSplitPoint, }); } if (parent.children.length === 0) { splitChildrenIndex -= 1; parentsParent.children.splice( nodeInserted ? splitChildrenIndex - 1 : splitChildrenIndex, 1, ); } } }, ); }, // now that images are top-level, convert them into `block` dast nodes handlers: { img: async ( createNode: CreateNodeFunction, node: HastNode, _context: Context, ) => { if (node.type !== 'element' || !node.properties) { return; } const { src: url } = node.properties; const upload = await findOrCreateUploadWithUrl(client, url); return createNode('block', { item: buildBlockRecord({ item_type: { id: modelIds.image_block.id, type: 'item_type' }, image: { upload_id: upload.id, }, }), }); }, }, }; } ``` A couple notes: - We use the `handlers` option to specify how to convert the `` `hast` nodes tags to [`dast` `block` nodes](/docs/structured-text/dast.md#block) (the default behavior, as we saw, is to simply skip them); - The `block` node should contain a block record of type Image (that's the same block currently used by the Modular Content field), which in turn has a single-asset `image` field. In line 79 we create a new asset starting from the `src` tag of the image, to feed it to the `image` field. Luckily, the handlers are async functions, so we can easily perform an asyncronous operation inside of it. - Since in the `dast` format, a `block` node can only be at root level, we use the `preprocess` option to tweak the `hast` tree and lift every image node up to the root (in case they're inside paragraphs or other tags). We can [test the migration](/docs/scripting-migrations/scripting-migrations-with-the-datocms-cli.md) with the following command from the Terminal, which will clone the primary environment into a sandbox, and run the migration: Terminal window ```bash npx datocms migrations:run --destination=with-structured-text ✔ Running 1612281851_convertHtmlArticles.ts... Done! ``` Success! The article content is correctly converted to structured text. ## Migrating Markdown content Once we know how to perform the HTML-to-Structured-Text conversion, we only have to do some minor changes to make it work also for Markdown content. As we just saw, the `datocms-html-to-structured-text` package knows how to convert an [`hast`](https://github.com/syntax-tree/hast) tree (HTML) to a [`dast`](/docs/structured-text/dast.md#datocms-abstract-syntax-tree--dast--specification) tree (Structured Text), so if we can convert a Markdown string to `hast`, then the rest of the code will be basically the same. Luckily, `hast` is part of the [unified](https://github.com/unifiedjs/unified) ecosystem, which also includes: - an analogue specification for representing Markdown in a syntax tree called [`mdast`](https://github.com/syntax-tree/mdast); - a tool to convert Markdown strings to `mdast`; - a tool to convert `mdast` trees to `hast`. Let's install all the packages we need: Terminal window ```bash npm install --save-dev unified@9 remark-parse@9 mdast-util-to-hast@10 ``` We can now create a function similar to `htmlToStructuredText` called `markdownToStructuredText` that connects all the dots: ./migrations/utils/markdownToStructuredText.ts ```typescript import unified from 'unified'; import toHast from 'mdast-util-to-hast'; import parse from 'remark-parse'; import { hastToStructuredText, Options, HastRootNode, } from 'datocms-html-to-structured-text'; import { validate } from 'datocms-structured-text-utils'; export default async function markdownToStructuredText( markdown: string, options: Options, ) { if (!markdown) { return null; } const mdastTree = unified().use(parse).parse(markdown); const hastTree = toHast(mdastTree) as HastRootNode; const result = await hastToStructuredText(hastTree, options); const validationResult = validate(result); if (!validationResult.valid) { throw new Error(validationResult.message); } return result; } ``` We can now create a new migration script: Terminal window ```bash > datocms migrations:new convertMarkdownArticles Created migrations/1612340785_convertMarkdownArticles.ts ``` And basically copy the previous migration, just replacing the name of the model (from `html_article` to `markdown_article`), and the call to `htmlToStructuredText` with a call to `markdownToStructuredText`: ./migrations/1612340785\_convertMarkdownArticles.ts ```typescript import getModelIdsByApiKey from './utils/getModelIdsByApiKey'; import createStructuredTextFieldFrom from './utils/createStructuredTextFieldFrom'; import markdownToStructuredText from './utils/markdownToStructuredText'; import convertImgsToBlocks from './utils/convertImgsToBlocks'; import getAllRecords from './utils/getAllRecords'; import swapFields from './utils/swapFields'; import { Client, SimpleSchemaTypes } from 'datocms/lib/cma-client-node'; type MdArticleType = SimpleSchemaTypes.Item & { title: string; content: string; }; export default async function (client: Client) { const modelIds = await getModelIdsByApiKey(client); await createStructuredTextFieldFrom(client, 'markdown_article', 'content', [ modelIds.image_block.id, ]); const records = (await getAllRecords( client, 'markdown_article', )) as MdArticleType[]; for (const record of records) { const structuredTextContent = await markdownToStructuredText( record.content, convertImgsToBlocks(client, modelIds), ); await client.items.update(record.id, { structured_text_content: structuredTextContent, }); if (record.meta.status !== 'draft') { await client.items.publish(record.id); } } await swapFields(client, 'markdown_article', 'content'); } ``` We can now run the new migration inside the sandbox environment we already created for the first migration: Terminal window ```bash > datocms migrations:run --source=with-structured-text --in-place ✔ Running 1612340785_convertMarkdownArticles.ts... Done! ``` ## Migrating Modular Content fields To migrate Modular Content fields into Structured Text fields, we must acknowledge the fact that both fields allow nested record blocks: the difference between the two is that Modular Content is basically an array of record blocks, while in Structed Text record blocks are inside the `dast` tree in [nodes of type `block`](/docs/structured-text/dast.md#block). In other words, our task here is, for every modular content, to transform an array of block records into a single `dast` document. It's up to us to decide how to convert each block we encounter into one/many nodes into our `dast` document. Let's take a look at the project schema again: (Image content) The existing Modular Content field supports three block types: - Text (which in turn contains a `text` Markdown field); - Code (which has two fields, one that contains the actual code and another that stores the language); - Image (which, as we already know, it contains a single-asset field called `image`). Here's the code for our migration: ./migrations/1612340785\_convertModularArticles.ts ```typescript import { Document, Node, validate } from 'datocms-structured-text-utils'; import getModelIdsByApiKey from './utils/getModelIdsByApiKey'; import createStructuredTextFieldFrom from './utils/createStructuredTextFieldFrom'; import getAllRecords from './utils/getAllRecords'; import swapFields from './utils/swapFields'; import markdownToStructuredText from './utils/markdownToStructuredText'; import convertImgsToBlocks from './utils/convertImgsToBlocks'; import { Client, SimpleSchemaTypes } from 'datocms/lib/cma-client-node'; type ModularArticleType = SimpleSchemaTypes.Item & { title: string; content: any; }; export default async function (client: Client) { const modelIds = await getModelIdsByApiKey(client); await createStructuredTextFieldFrom( client, 'modular_content_article', 'content', [modelIds.image_block.id, modelIds.text_block.id, modelIds.code_block.id], ); const records = (await getAllRecords( client, 'modular_content_article', )) as ModularArticleType[]; for (const record of records) { const rootNode = { type: 'root', children: [] as Node[], }; for (const block of record.content) { switch (block.relationships.item_type.id) { case modelIds.text_block.id: { const markdownSt = await markdownToStructuredText( block.text, convertImgsToBlocks(client, modelIds), ); if (markdownSt) { rootNode.children = [ ...rootNode.children, ...markdownSt.document.children, ]; } break; } case modelIds.code_block.id: { rootNode.children.push({ type: 'code', language: block.language, code: block.code, }); break; } default: { delete block.id; delete block.meta; delete block.createdAt; delete block.updatedAt; rootNode.children.push({ type: 'block', item: block, }); break; } } } const result = { schema: 'dast', document: rootNode, } as Document; const validationResult = validate(result); if (!validationResult.valid) { throw new Error(validationResult.message); } await client.items.update(record.id, { structured_text_content: result, }); if (record.meta.status !== 'draft') { await client.items.publish(record.id); } } await swapFields(client, 'modular_content_article', 'content'); } ``` Every time we need to convert a Modular Content field, we start by creating an empty Dast `root` node (that is, one with no children, line 33). Then, for every block contained in the modular content (line 38), we're going to accumulate children inside the `root` node: - If it is a Text block (line 40), we use the `markdownToStructuredText` function to convert its Markdown content into a Dast tree, then take the children of the resulting `root` node and add them to our accumulator; - Since Dast supports [nodes of type `code`](https://github.com/datocms/structured-text/blob/main/packages/utils/src/types.ts#L54-L59), if we encounter a Code block (line 55), we simply convert it to `code` node, and add it to the accumulator; - If we find an Image block (line 63), we'll wrap the block into a Dast `block` node, and add it to the accumulator as it is. ## Wrapping up Once you get to know the [Structured Text](/docs/content-modelling/structured-text.md#structured-text-on-the-api) format, it becomes quite straightforward converting from/to its Dast tree representation of nodes, and the DatoCMS API, coupled with migrations/sandbox environments, makes it easy to perform any kind of treatment to your content. You can download the final code from this [GitHub repo](https://github.com/datocms/structured-text-migration-example). --- # Plugin SDK — Introduction to the DatoCMS Plugin SDK Source [docs]: https://www.datocms.com/docs/plugin-sdk/introduction.md Although DatoCMS offers a wide range of features and configurations by default, with **plugins** it is possible to take a further leap forward. You can integrate third-party services with our platform or build custom integrations tailored specifically to your business and user needs. ### What is a DatoCMS Plugin? Technically speaking, DatoCMS plugins are small web apps that run in a sandboxed `