Content Management API > Record

Update a record

📚 New to DatoCMS records?

We strongly recommend reading the Introduction to Records guide first. The payload for updating a record follows the same structure as creating one, 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 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.

⚠️ 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

1
import { buildClient, inspectItem } from "@datocms/cma-client-node";
2
import type * as Schema from "./schema.js";
3

4
/*
5
 * BlogPost
6
 * ├─ title: string
7
 * ├─ description: string
8
 * ├─ featured_image: file
9
 * └─ content_blocks: modular_content
10
 *    └─ HeroBlock: headline
11
 */
12

13
async function run() {
14
  // Make sure the API token has access to the CMA, and is stored securely
15
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
16

17
  const record = await client.items.find<Schema.BlogPost>(
18
    "T4m4tPymSACFzsqbZS65WA",
19
    {
20
      nested: true,
21
    },
22
  );
23

24
  console.log("-- BEFORE UPDATE --");
25
  console.log(inspectItem(record));
26

27
  const item = await client.items.update<Schema.BlogPost>(
28
    "T4m4tPymSACFzsqbZS65WA",
29
    {
30
      title: "[EDIT] My first blog post!",
31
      featured_image: null,
32
      content_blocks: [],
33
    },
34
  );
35

36
  console.log("-- AFTER UPDATE --");
37
  console.log(inspectItem(item));
38
}
39

40
run();

1
-- BEFORE UPDATE --
2
└ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
3
  ├ title: "My first blog post!"
4
  ├ description: "An introduction to our new blog platform"
5
  ├ featured_image: null
6
  └ content_blocks
7
    └ [0] Item "WtzyjA4sTLiLiOQ9TBNgtQ" (item_type: "DB5xsyzCQ3iHTx0dZPb3sw")
8
      └ headline: "Hello!"
9

10
-- AFTER UPDATE --
11
└ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
12
  ├ title: "[EDIT] My first blog post!"
13
  ├ description: "An introduction to our new blog platform"
14
  ├ featured_image: null
15
  └ 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 422s from the API. The single biggest lever you have is passing a generated Schema.X marker as the generic on items.update. TypeScript then enforces the model's field names, types, and allowed block shapes at compile time:

1
// ❌ Untyped: every field is `unknown`, typos compile.
2
await client.items.update("record-id", { /* … */ });
3

4
// ✅ Typed: field names, types, and block shapes enforced.
5
await client.items.update<Schema.Article>("record-id", { /* … */ });

When you're rebuilding a field value piece-by-piece — typically an array of blocks or links — annotate the accumulator with FieldValueInRequest<T, 'field_key'>. 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:

1
const article = await client.items.find<Schema.Article>("record-id", { nested: true });
2

3
if (article.content) {
4
  const content: NonNullable<FieldValueInRequest<typeof article, "content">> =
5
    /* ...transform article.content... */;
6
  await client.items.update<Schema.Article>("record-id", { content });
7
}
8

9
// Same expression on a narrowed nested block:
10
for (const block of article.sections) {
11
  if (isBlockOfType(Schema.HeroBlock.ID, block)) {
12
    const ctas: NonNullable<FieldValueInRequest<typeof block, "ctas">> = [];
13
    // …rebuild the nested field…
14
  }
15
}
16

17
// Or, if you don't have a value yet, pass the marker:
18
type ArticleContent = NonNullable<FieldValueInRequest<Schema.Article, "content">>;

⚠️ 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:

Generate types with the TypeScript schema generator.
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.
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.
Send a single client.items.update<Article> 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<T>({ id, ...changedAttrs })`
Create	`buildBlockRecord<T>({ ...allAttrs })`
Clone	`duplicateBlockRecord<T>(block, schemaRepository)`
Delete	omit from the array
Reorder	rearrange the array

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<CallToActionBlock>({ item_type, ...attrs }) (no id, since it's brand new).
Clone — duplicate the first existing testimonial with duplicateBlockRecord<TestimonialBlock>(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<CallToActionBlock>({ 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<FieldValueInRequest<typeof block, 'ctas'>> 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.

1
import {
2
  buildBlockRecord,
3
  buildClient,
4
  duplicateBlockRecord,
5
  type FieldValueInRequest,
6
  inspectItem,
7
  isBlockOfType,
8
  SchemaRepository,
9
} from "@datocms/cma-client-node";
10
import * as Schema from "./schema.js";
11

12
/*
13
 * LandingPage
14
 * ├─ title: string
15
 * └─ sections: modular_content
16
 *    ├─ HeroBlock: headline, subtitle
17
 *    │  └─ ctas: modular_content
18
 *    │     └─ ButtonBlock: label, url
19
 *    ├─ CallToActionBlock: button_text, button_url
20
 *    └─ TestimonialBlock: quote, author
21
 */
22

23
async function run() {
24
  // Make sure the API token has access to the CMA, and is stored securely
25
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
26

27
  const schemaRepository = new SchemaRepository(client);
28

29
  const currentPage = await client.items.find<Schema.LandingPage>(
30
    "W4wcrs_2REiM4fc6dlDZCQ",
31
    { nested: true },
32
  );
33

34
  console.log("-- BEFORE UPDATE --");
35
  console.log(inspectItem(currentPage));
36

37
  const firstTestimonial = currentPage.sections.find(
38
    isBlockOfType(Schema.TestimonialBlock.ID),
39
  );
40
  const duplicatedTestimonial = firstTestimonial
41
    ? await duplicateBlockRecord<Schema.TestimonialBlock>(
42
        firstTestimonial,
43
        schemaRepository,
44
      )
45
    : null;
46

47
  const sections: NonNullable<
48
    FieldValueInRequest<typeof currentPage, "sections">
49
  > = [
50
    // Create — fresh CallToActionBlock at the top
51
    buildBlockRecord<Schema.CallToActionBlock>({
52
      item_type: Schema.CallToActionBlock.REF,
53
      button_text: "Watch a 2-minute demo",
54
      button_url: "https://www.datocms.com/demo",
55
    }),
56

57
    // Clone — duplicated testimonial
58
    ...(duplicatedTestimonial ? [duplicatedTestimonial] : []),
59

60
    ...currentPage.sections
61
      // Delete — drop the trailing CTA by filtering it out
62
      .filter(
63
        (block) =>
64
          !(
65
            isBlockOfType(Schema.CallToActionBlock.ID, block) &&
66
            block.attributes.button_text === "Start Your Free Trial"
67
          ),
68
      )
69
      .map((block) => {
70
        if (isBlockOfType(Schema.HeroBlock.ID, block)) {
71
          // Edit (nested) — rebuild the HeroBlock's `ctas` using the SAME
72
          // accumulator pattern, applied recursively to a nested block's
73
          // modular field.
74
          const ctas: NonNullable<FieldValueInRequest<typeof block, "ctas">> =
75
            block.attributes.ctas.map((cta) => {
76
              if (
77
                isBlockOfType(Schema.ButtonBlock.ID, cta) &&
78
                cta.attributes.label === "Get started"
79
              ) {
80
                const url = new URL(
81
                  cta.attributes.url || "https://www.datocms.com",
82
                );
83
                url.searchParams.set("utm_source", "hero");
84
                return buildBlockRecord<Schema.ButtonBlock>({
85
                  id: cta.id,
86
                  url: url.toString(),
87
                });
88
              }
89
              return cta.id;
90
            });
91

92
          return buildBlockRecord<Schema.HeroBlock>({ id: block.id, ctas });
93
        }
94

95
        if (isBlockOfType(Schema.CallToActionBlock.ID, block)) {
96
          // Edit (flat)
97
          const url = new URL(
98
            block.attributes.button_url || "https://www.datocms.com",
99
          );
100
          url.searchParams.set("utm_source", "landing_page");
101
          url.searchParams.set("utm_medium", "cta");
102
          url.searchParams.set("utm_campaign", "q1_2024");
103

104
          return buildBlockRecord<Schema.CallToActionBlock>({
105
            id: block.id,
106
            button_url: url.toString(),
107
          });
108
        }
109

110
        // Keep — return the bare ID for unchanged blocks
111
        return block.id;
112
      }),
113
  ];
114

115
  console.log("-- UPDATE OPERATION --");
116
  console.log(inspectItem({ sections }));
117

118
  await client.items.update<Schema.LandingPage>(currentPage, { sections });
119

120
  const updatedPage = await client.items.find<Schema.LandingPage>(currentPage, {
121
    nested: true,
122
  });
123

124
  console.log("-- AFTER UPDATE --");
125
  console.log(inspectItem(updatedPage));
126
}
127

128
run();

1
-- BEFORE UPDATE --
2
└ Item "W4wcrs_2REiM4fc6dlDZCQ" (item_type: "ZV0o9497SsqWxQR8HEQddw")
3
  ├ title: "Product Launch Landing Page"
4
  └ sections
5
    ├ [0] Item "Ngzm6x8JS2y9UuQnTf9wBw" (item_type: "d-CHYg-rShOt3kiL6ZN1yA")
6
    │ ├ headline: "Revolutionary New Solution"
7
    │ ├ subtitle: "Discover the future of productivity with our cutting-edge platform designed f..."
8
    │ └ ctas
9
    │   ├ [0] Item "IfiDssuLSEa5HH2-Ce2nCw" (item_type: "TNTfjVnfQieREzX98q3xnw")
10
    │   │ ├ label: "Get started"
11
    │   │ └ url: "https://www.datocms.com/signup"
12
    │   └ [1] Item "IOggXsdxRAmFWCOPhbFXYw" (item_type: "TNTfjVnfQieREzX98q3xnw")
13
    │     ├ label: "Read the docs"
14
    │     └ url: "https://www.datocms.com/docs"
15
    ├ [1] Item "Iu1vi__ASDeDrrpPpKbknQ" (item_type: "I8Q6k-HqQmaZ498WKtvFbg")
16
    │ ├ button_text: "Get Started Free"
17
    │ └ button_url: "https://www.datocms.com/signup"
18
    ├ [2] Item "NxszxFtnSpmftjnxguWPOg" (item_type: "Dy9C52o4S6eF3mqSOmeUtg")
19
    │ ├ quote: "This platform completely transformed how our team collaborates. We've seen a ..."
20
    │ └ author: "Sarah Chen, Product Manager at TechCorp"
21
    ├ [3] Item "MIJbkpwMQiqzwOYQkuAVIw" (item_type: "Dy9C52o4S6eF3mqSOmeUtg")
22
    │ ├ quote: "The best investment we've made this year. The ROI was evident within the firs..."
23
    │ └ author: "Michael Rodriguez, CTO at InnovateLabs"
24
    └ [4] Item "CVcgWRiaRYKF53DvqZHpFA" (item_type: "I8Q6k-HqQmaZ498WKtvFbg")
25
      ├ button_text: "Start Your Free Trial"
26
      └ button_url: "https://www.datocms.com/trial"
27

28
-- UPDATE OPERATION --
29
└ Item
30
  └ sections
31
    ├ [0] Item (item_type: "I8Q6k-HqQmaZ498WKtvFbg")
32
    │ ├ button_text: "Watch a 2-minute demo"
33
    │ └ button_url: "https://www.datocms.com/demo"
34
    ├ [1] Item (item_type: "Dy9C52o4S6eF3mqSOmeUtg")
35
    │ ├ quote: "This platform completely transformed how our team collaborates. We've seen a ..."
36
    │ └ author: "Sarah Chen, Product Manager at TechCorp"
37
    ├ [2] Item "Ngzm6x8JS2y9UuQnTf9wBw"
38
    │ └ ctas
39
    │   ├ [0] Item "IfiDssuLSEa5HH2-Ce2nCw"
40
    │   │ └ url: "https://www.datocms.com/signup?utm_source=hero"
41
    │   └ [1] "IOggXsdxRAmFWCOPhbFXYw"
42
    ├ [3] Item "Iu1vi__ASDeDrrpPpKbknQ"
43
    │ └ button_url: "https://www.datocms.com/signup?utm_source=landing_page&utm_medium=cta&utm_cam..."
44
    ├ [4] "NxszxFtnSpmftjnxguWPOg"
45
    └ [5] "MIJbkpwMQiqzwOYQkuAVIw"
46

47
-- AFTER UPDATE --
48
└ Item "W4wcrs_2REiM4fc6dlDZCQ" (item_type: "ZV0o9497SsqWxQR8HEQddw")
49
  ├ title: "Product Launch Landing Page"
50
  └ sections
51
    ├ [0] Item "O43QkMpUQFy4mTck48Ayeg" (item_type: "I8Q6k-HqQmaZ498WKtvFbg")
52
    │ ├ button_text: "Watch a 2-minute demo"
53
    │ └ button_url: "https://www.datocms.com/demo"
54
    ├ [1] Item "JQOSGafZTgK1cDWaFgtK9Q" (item_type: "Dy9C52o4S6eF3mqSOmeUtg")
55
    │ ├ quote: "This platform completely transformed how our team collaborates. We've seen a ..."
56
    │ └ author: "Sarah Chen, Product Manager at TechCorp"
57
    ├ [2] Item "Ngzm6x8JS2y9UuQnTf9wBw" (item_type: "d-CHYg-rShOt3kiL6ZN1yA")
58
    │ ├ headline: "Revolutionary New Solution"
59
    │ ├ subtitle: "Discover the future of productivity with our cutting-edge platform designed f..."
60
    │ └ ctas
61
    │   ├ [0] Item "IfiDssuLSEa5HH2-Ce2nCw" (item_type: "TNTfjVnfQieREzX98q3xnw")
62
    │   │ ├ label: "Get started"
63
    │   │ └ url: "https://www.datocms.com/signup?utm_source=hero"
64
    │   └ [1] Item "IOggXsdxRAmFWCOPhbFXYw" (item_type: "TNTfjVnfQieREzX98q3xnw")
65
    │     ├ label: "Read the docs"
66
    │     └ url: "https://www.datocms.com/docs"
67
    ├ [3] Item "Iu1vi__ASDeDrrpPpKbknQ" (item_type: "I8Q6k-HqQmaZ498WKtvFbg")
68
    │ ├ button_text: "Get Started Free"
69
    │ └ button_url: "https://www.datocms.com/signup?utm_source=landing_page&utm_medium=cta&utm_cam..."
70
    ├ [4] Item "NxszxFtnSpmftjnxguWPOg" (item_type: "Dy9C52o4S6eF3mqSOmeUtg")
71
    │ ├ quote: "This platform completely transformed how our team collaborates. We've seen a ..."
72
    │ └ author: "Sarah Chen, Product Manager at TechCorp"
73
    └ [5] Item "MIJbkpwMQiqzwOYQkuAVIw" (item_type: "Dy9C52o4S6eF3mqSOmeUtg")
74
      ├ quote: "The best investment we've made this year. The ROI was evident within the firs..."
75
      └ 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.

Demonstrates every Single Block operation across multiple items.update calls — the field holds at most one block (or null):

Edit — buildBlockRecord<CallToActionBlock>({ id, button_text, style }) keeps the same block ID, changes the listed attributes, leaves the rest (button_url) untouched.
Replace via duplicate — duplicateBlockRecord<HeroBlock | CallToActionBlock | VideoBlock>(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<VideoBlock>({ 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.

1
import {
2
  type ApiTypes,
3
  buildBlockRecord,
4
  buildClient,
5
  duplicateBlockRecord,
6
  inspectItem,
7
  SchemaRepository,
8
} from "@datocms/cma-client-node";
9
import * as Schema from "./schema.js";
10

11
/*
12
 * ProductPage
13
 * ├─ title: string
14
 * ├─ price: float
15
 * └─ hero_section: single_block
16
 *    ├─ HeroBlock: headline, description, background_image
17
 *    ├─ CallToActionBlock: button_text, button_url, style
18
 *    └─ VideoBlock: video_url, thumbnail_image, autoplay
19
 */
20

21
// Make sure the API token has access to the CMA, and is stored securely
22
const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
23

24
async function run() {
25
  const schemaRepository = new SchemaRepository(client);
26

27
  const currentProduct = await client.items.find<Schema.ProductPage>(
28
    "W4wcrs_2REiM4fc6dlDZCQ",
29
    { nested: true },
30
  );
31

32
  console.log("-- BEFORE UPDATE --");
33
  console.log(inspectItem(currentProduct));
34

35
  if (
36
    currentProduct.hero_section &&
37
    currentProduct.hero_section.__itemTypeId === Schema.CallToActionBlock.ID
38
  ) {
39
    await client.items.update<Schema.ProductPage>(currentProduct, {
40
      hero_section: buildBlockRecord<Schema.CallToActionBlock>({
41
        id: currentProduct.hero_section.id,
42
        button_text:
43
          currentProduct.hero_section.attributes.button_text?.toUpperCase() ||
44
          "SHOP NOW",
45
        style: "primary-large",
46
      }),
47
    });
48
    console.log("-- EXISTING BLOCK UPDATED --");
49
    await inspectItemWithNestedBlocks(currentProduct);
50
  }
51

52
  await client.items.update<Schema.ProductPage>(currentProduct, {
53
    hero_section: await duplicateBlockRecord<
54
      Schema.HeroBlock | Schema.CallToActionBlock | Schema.VideoBlock
55
    >(currentProduct.hero_section!, schemaRepository),
56
  });
57
  console.log("-- BLOCK DUPLICATE --");
58
  await inspectItemWithNestedBlocks(currentProduct);
59

60
  const upload = await client.uploads.createFromUrl({
61
    url: "https://picsum.photos/800/600?random=1",
62
  });
63
  const productWithVideo = await client.items.update<Schema.ProductPage>(
64
    currentProduct,
65
    {
66
      hero_section: buildBlockRecord<Schema.VideoBlock>({
67
        item_type: Schema.VideoBlock.REF,
68
        video_url: "https://videos.datocms.com/product-demo.mp4",
69
        thumbnail_image: { upload_id: upload.id },
70
        autoplay: false,
71
      }),
72
    },
73
  );
74
  console.log("-- BLOCK REPLACED --");
75
  await inspectItemWithNestedBlocks(currentProduct);
76

77
  await client.items.update<Schema.ProductPage>(productWithVideo, {
78
    hero_section: null,
79
  });
80
  console.log("-- BLOCK REMOVED --");
81
  await inspectItemWithNestedBlocks(currentProduct);
82
}
83

84
run();
85

86
async function inspectItemWithNestedBlocks(item: ApiTypes.Item) {
87
  const itemWithNestedBlocks = await client.items.find(item, {
88
    nested: true,
89
  });
90
  console.log(inspectItem(itemWithNestedBlocks));
91
}

1
-- BEFORE UPDATE --
2
└ Item "W4wcrs_2REiM4fc6dlDZCQ" (item_type: "ZV0o9497SsqWxQR8HEQddw")
3
  ├ title: "Premium Wireless Headphones"
4
  ├ price: 299.99
5
  └ hero_section
6
    └ Item "MolF0AwpSLeXrdE5kdcEtw" (item_type: "I8Q6k-HqQmaZ498WKtvFbg")
7
      ├ button_text: "Buy Now"
8
      ├ button_url: "https://example.com/buy"
9
      └ style: "primary"
10

11
-- EXISTING BLOCK UPDATED --
12
└ Item "W4wcrs_2REiM4fc6dlDZCQ" (item_type: "ZV0o9497SsqWxQR8HEQddw")
13
  ├ title: "Premium Wireless Headphones"
14
  ├ price: 299.99
15
  └ hero_section
16
    └ Item "MolF0AwpSLeXrdE5kdcEtw" (item_type: "I8Q6k-HqQmaZ498WKtvFbg")
17
      ├ button_text: "BUY NOW"
18
      ├ button_url: "https://example.com/buy"
19
      └ style: "primary-large"
20

21
-- BLOCK DUPLICATE --
22
└ Item "W4wcrs_2REiM4fc6dlDZCQ" (item_type: "ZV0o9497SsqWxQR8HEQddw")
23
  ├ title: "Premium Wireless Headphones"
24
  ├ price: 299.99
25
  └ hero_section
26
    └ Item "QXqFgPHVTfq8F1tOmQEwEg" (item_type: "I8Q6k-HqQmaZ498WKtvFbg")
27
      ├ button_text: "Buy Now"
28
      ├ button_url: "https://example.com/buy"
29
      └ style: "primary"
30

31
-- BLOCK REPLACED --
32
└ Item "W4wcrs_2REiM4fc6dlDZCQ" (item_type: "ZV0o9497SsqWxQR8HEQddw")
33
  ├ title: "Premium Wireless Headphones"
34
  ├ price: 299.99
35
  └ hero_section
36
    └ Item "JIHRl3kyQiGXAJHcP-7v7Q" (item_type: "Dy9C52o4S6eF3mqSOmeUtg")
37
      ├ video_url: "https://videos.datocms.com/product-demo.mp4"
38
      ├ thumbnail_image
39
      │ └ upload_id: "WwqHexgISQqQdMKJSYE8VA"
40
      └ autoplay: false
41

42
-- BLOCK REMOVED --
43
└ Item "W4wcrs_2REiM4fc6dlDZCQ" (item_type: "ZV0o9497SsqWxQR8HEQddw")
44
  ├ title: "Premium Wireless Headphones"
45
  ├ price: 299.99
46
  └ hero_section: null

Structured Text

Structured Text stores rich content as a DAST 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 translates the DAST tree to and from a markdown-like text format:

1
A normal paragraph with ==highlighted==, ++underlined++ and ~~struck~~ text.
2

3
Links can carry trailers: [our docs](https:datocms.com){target="_blank"}.
4
References to other records read like [this article](dato:item/abc123),
5
or inline as <inlineItem id="abc123"/>.
6

7
> A pull quote from the interview.
8
> {attribution="Jane Doe"}
9

10
<block id="def456"/>
11

12
Inline blocks <inlineBlock id="ghi789"/> sit mid-sentence.

This allows you to make changes with ordinary string operations and let parse() rebuild the tree:

1
import { parse, serialize } from "datocms-structured-text-dastdown";
2

3
const text = serialize(currentRecord.content);
4

5
const edited = text
6
  .replace(/Jane Doe/g, "Jane Smith")
7
  .replace(/==([^=]+)==/g, "**$1**");
8

9
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 <block id="…"/> placeholders that hide their fields), so anything touching block contents lands here. Use buildBlockRecord<T> to shape the payload — pass an id to edit an existing block, omit it to create a new one — and duplicateBlockRecord<T> 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.

⚠️ Combine passes in order: 1 → 2

Pass 1's parse() uses the original document as the lookup table for <block id="…"/> 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.

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 <block id="…"/> lookup table; missing IDs throw, which is the signal to fall back to Pass 2.

1
import { buildClient, inspectItem } from "@datocms/cma-client-node";
2
import { parse, serialize } from "datocms-structured-text-dastdown";
3
import type * as Schema from "./schema.js";
4

5
/*
6
 * Guide
7
 * ├─ title: string
8
 * └─ body: structured_text (no embedded blocks for this example)
9
 */
10

11
async function run() {
12
  // Make sure the API token has access to the CMA, and is stored securely
13
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
14

15
  const currentGuide = await client.items.find<Schema.Guide>(
16
    "Q9zHRrIESkGYBV3hVVe2Hg",
17
  );
18

19
  // `currentGuide.body` is typed nullable — guard before touching the document.
20
  // Wrapping in `if (currentGuide.body) { ... }` also avoids a top-level
21
  // `return`, letting peek + mutate live in a single script.
22
  if (currentGuide.body) {
23
    console.log("-- BEFORE UPDATE --");
24
    console.log(inspectItem(currentGuide));
25

26
    const text = serialize(currentGuide.body);
27

28
    const edited = text
29
      .replace(/ZEIT/g, "Vercel")
30
      .replace(/(\b[\w.+-]+@[\w-]+\.[\w.-]+\b)/g, "[$1](mailto:$1)")
31
      .replace(
32
        /\(https:\/\/example\.com\/migration\)(?!\{)/g,
33
        '(https://example.com/migration){target="_blank"}',
34
      );
35

36
    // 2nd arg is the lookup table for `<block id="…"/>` placeholders; missing IDs throw.
37
    const body = parse(edited, currentGuide.body);
38

39
    await client.items.update<Schema.Guide>(currentGuide.id, { body });
40

41
    console.log("-- AFTER UPDATE --");
42
    console.log(
43
      inspectItem(await client.items.find<Schema.Guide>(currentGuide.id)),
44
    );
45
  }
46
}
47

48
run();

1
-- BEFORE UPDATE --
2
└ Item "Q9zHRrIESkGYBV3hVVe2Hg" (item_type: "f6sjkkPgQGiSDi6lwG3UjA")
3
  ├ title: "Deploying with ZEIT"
4
  └ body
5
    ├ heading (level: 1)
6
    │ └ span "Deploying with ZEIT"
7
    ├ paragraph
8
    │ └ span "ZEIT lets you ship static sites and serverless functions in seconds. ..."
9
    └ paragraph
10
      ├ span "Read our "
11
      ├ link (url: "https://example.com/migration")
12
      │ └ span "migration guide"
13
      └ span " before upgrading from ZEIT v1."
14

15
-- AFTER UPDATE --
16
└ Item "Q9zHRrIESkGYBV3hVVe2Hg" (item_type: "f6sjkkPgQGiSDi6lwG3UjA")
17
  ├ title: "Deploying with ZEIT"
18
  └ body
19
    ├ heading (level: 1)
20
    │ └ span "Deploying with Vercel"
21
    ├ paragraph
22
    │ ├ span "Vercel lets you ship static sites and serverless functions in seconds..."
23
    │ ├ link (url: "mailto:support@zeit.co")
24
    │ │ └ span "support@zeit.co"
25
    │ └ span " for help."
26
    └ paragraph
27
      ├ span "Read our "
28
      ├ link (url: "https://example.com/migration", meta: {target="_blank"})
29
      │ └ span "migration guide"
30
      └ span " before upgrading from Vercel v1."

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

1
import { buildClient, inspectItem } from "@datocms/cma-client-node";
2
import {
3
  isHeading,
4
  isItemLink,
5
  isLink,
6
  isParagraph,
7
  isSpan,
8
  mapNodes,
9
  reduceNodes,
10
} from "datocms-structured-text-utils";
11
import type * as Schema from "./schema.js";
12

13
/*
14
 * BlogPost
15
 * ├─ title: string
16
 * ├─ slug: string
17
 * └─ content: structured_text (no embedded blocks for this example)
18
 */
19

20
async function run() {
21
  // Make sure the API token has access to the CMA, and is stored securely
22
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
23

24
  const currentPost = await client.items.find<Schema.BlogPost>(
25
    "T4m4tPymSACFzsqbZS65WA",
26
  );
27

28
  // Guard the nullable field — also keeps peek + mutate in a single script
29
  // without a top-level `return`.
30
  if (currentPost.content) {
31
    console.log("-- BEFORE UPDATE --");
32
    console.log(inspectItem(currentPost));
33

34
    const content = mapNodes(currentPost.content, (node) => {
35
      if (isHeading(node) && node.level === 1) {
36
        // `as const` preserves the literal `2` instead of widening to `number`.
37
        return { ...node, level: 2 as const };
38
      }
39

40
      if (isSpan(node) && node.value.includes("ZEIT")) {
41
        const marks = new Set(node.marks ?? []);
42
        marks.add("strong");
43
        return {
44
          ...node,
45
          value: node.value.replace(/ZEIT/g, "Vercel"),
46
          marks: [...marks],
47
        };
48
      }
49

50
      if (isLink(node) || isItemLink(node)) {
51
        const meta = [
52
          ...(node.meta ?? []).filter((m) => m.id !== "target"),
53
          { id: "target", value: "_blank" },
54
        ];
55
        return { ...node, meta };
56
      }
57

58
      if (
59
        isParagraph(node) &&
60
        reduceNodes(
61
          node,
62
          (acc, n) => (isSpan(n) ? acc + n.value.trim() : acc),
63
          "",
64
        ).length === 0
65
      ) {
66
        return null;
67
      }
68

69
      return node;
70
    });
71

72
    // Root-level inserts can't go through `mapNodes` (splat-at-root throws); push directly.
73
    content.document.children.push({
74
      type: "paragraph",
75
      children: [{ type: "span", value: "Last updated by the content team." }],
76
    });
77

78
    await client.items.update<Schema.BlogPost>(currentPost.id, { content });
79

80
    console.log("-- AFTER UPDATE --");
81
    console.log(
82
      inspectItem(await client.items.find<Schema.BlogPost>(currentPost.id)),
83
    );
84
  }
85
}
86

87
run();

1
-- BEFORE UPDATE --
2
└ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
3
  ├ title: "What is ZEIT?"
4
  ├ slug: "what-is-zeit"
5
  └ content
6
    ├ heading (level: 1)
7
    │ └ span "Understanding ZEIT"
8
    ├ paragraph
9
    │ └ span "ZEIT is a cloud platform for static sites and serverless functions. I..."
10
    ├ paragraph
11
    │ └ span ""
12
    ├ paragraph
13
    │ └ span ""
14
    ├ heading (level: 1)
15
    │ └ span "Key Features"
16
    ├ paragraph
17
    │ ├ span "ZEIT offers automatic HTTPS, global CDN distribution, and instant dep..."
18
    │ ├ link (url: "https://example.com/blog")
19
    │ │ └ span "detailed comparison"
20
    │ └ span " for more insights."
21
    └ paragraph
22
      ├ span "Visit our "
23
      ├ itemLink (item: "fpgJWZadRI66eqXB-ucSSQ")
24
      │ └ span "migration guide"
25
      └ span " for step-by-step instructions."
26

27
-- AFTER UPDATE --
28
└ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
29
  ├ title: "What is ZEIT?"
30
  ├ slug: "what-is-zeit"
31
  └ content
32
    ├ heading (level: 2)
33
    │ └ span (marks: strong) "Understanding Vercel"
34
    ├ paragraph
35
    │ └ span (marks: strong) "Vercel is a cloud platform for static sites and serverless functions...."
36
    ├ heading (level: 2)
37
    │ └ span "Key Features"
38
    ├ paragraph
39
    │ ├ span (marks: strong) "Vercel offers automatic HTTPS, global CDN distribution, and instant d..."
40
    │ ├ link (url: "https://example.com/blog", meta: {target="_blank"})
41
    │ │ └ span "detailed comparison"
42
    │ └ span " for more insights."
43
    ├ paragraph
44
    │ ├ span "Visit our "
45
    │ ├ itemLink (item: "fpgJWZadRI66eqXB-ucSSQ", meta: {target="_blank"})
46
    │ │ └ span "migration guide"
47
    │ └ span " for step-by-step instructions."
48
    └ paragraph
49
      └ span "Last updated by the content team."

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<CtaBlock>({ 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<CtaBlock> 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.

1
import {
2
  buildBlockRecord,
3
  buildClient,
4
  duplicateBlockRecord,
5
  type FieldValueInRequest,
6
  inspectItem,
7
  SchemaRepository,
8
} from "@datocms/cma-client-node";
9
import {
10
  findFirstNode,
11
  isBlockWithItemOfType,
12
  isInlineBlockWithItemOfType,
13
  mapNodes,
14
} from "datocms-structured-text-utils";
15
import * as Schema from "./schema.js";
16

17
/*
18
 * Article
19
 * ├─ title: string
20
 * ├─ author: string
21
 * └─ content: structured_text
22
 *    ├─ CtaBlock: title, description, button_text, button_url
23
 *    ├─ ProductMentionInline: product_name, price, affiliate_url
24
 *    └─ ImageGalleryBlock: title, images
25
 */
26

27
async function run() {
28
  // Make sure the API token has access to the CMA, and is stored securely
29
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
30

31
  // `duplicateBlockRecord` looks up nested-block field definitions through this.
32
  const repo = new SchemaRepository(client);
33

34
  const currentArticle = await client.items.find<Schema.Article>(
35
    "RSfdsZbbR7ixGgMBSmcaVA",
36
    {
37
      nested: true,
38
    },
39
  );
40

41
  // Guard the nullable field — also keeps peek + mutate in a single script
42
  // without a top-level `return`.
43
  if (currentArticle.content) {
44
    console.log("-- BEFORE UPDATE --");
45
    console.log(inspectItem(currentArticle));
46

47
    let content: NonNullable<
48
      FieldValueInRequest<typeof currentArticle, "content">
49
    > = currentArticle.content;
50

51
    content = mapNodes(content, (node) => {
52
      if (isBlockWithItemOfType(Schema.CtaBlock.ID, node)) {
53
        const url = node.item.attributes.button_url;
54
        if (url?.includes("old-domain.com")) {
55
          return {
56
            ...node,
57
            item: buildBlockRecord<Schema.CtaBlock>({
58
              id: node.item.id,
59
              button_url: url.replace("old-domain.com", "new-domain.com"),
60
            }),
61
          };
62
        }
63
      }
64

65
      if (isInlineBlockWithItemOfType(Schema.ProductMentionInline.ID, node)) {
66
        const raw = node.item.attributes.affiliate_url;
67
        if (raw) {
68
          const url = new URL(raw);
69
          url.searchParams.set("source", "article_mention");
70
          return {
71
            ...node,
72
            item: buildBlockRecord<Schema.ProductMentionInline>({
73
              id: node.item.id,
74
              affiliate_url: url.toString(),
75
            }),
76
          };
77
        }
78
      }
79

80
      return node;
81
    });
82

83
    // Source the duplicate from the original tree: `mapNodes` may have
84
    // rewritten `node.item`, so post-map `content` is not safe to clone from.
85
    const firstCta = findFirstNode(
86
      currentArticle.content,
87
      isBlockWithItemOfType(Schema.CtaBlock.ID),
88
    );
89

90
    if (firstCta) {
91
      const dup = await duplicateBlockRecord<Schema.CtaBlock>(
92
        firstCta.node.item,
93
        repo,
94
      );
95
      content.document.children.push({ type: "block", item: dup });
96
    }
97

98
    await client.items.update<Schema.Article>(currentArticle.id, { content });
99

100
    console.log("-- AFTER UPDATE --");
101
    console.log(
102
      inspectItem(
103
        await client.items.find<Schema.Article>(currentArticle.id, {
104
          nested: true,
105
        }),
106
      ),
107
    );
108
  }
109
}
110

111
run();

1
-- BEFORE UPDATE --
2
└ Item "RSfdsZbbR7ixGgMBSmcaVA" (item_type: "ZV0o9497SsqWxQR8HEQddw")
3
  ├ title: "The Future of E-commerce Technology"
4
  ├ author: "Alex Thompson"
5
  └ content
6
    ├ paragraph
7
    │ ├ span "E-commerce is evolving rapidly with new technologies like "
8
    │ ├ inlineBlock
9
    │ │ └ Item "LQlcO4LCTYaOrfj2A705DQ" (item_type: "VGXgXav9SwG5P48frGrFxA")
10
    │ │   ├ product_name: "AI Shopping Assistant"
11
    │ │   ├ price: 99.99
12
    │ │   └ affiliate_url: "https://old-domain.com/product?ref=blog"
13
    │ └ span " transforming how customers shop online."
14
    ├ block
15
    │ └ Item "FqTxaDO8TJmtkoTgDjbK8Q" (item_type: "d-CHYg-rShOt3kiL6ZN1yA")
16
    │   ├ title: "Join the Revolution"
17
    │   ├ description: "Stay ahead of the curve with our e-commerce insights."
18
    │   ├ button_text: "Subscribe Now"
19
    │   └ button_url: "https://old-domain.com/subscribe"
20
    └ block
21
      └ Item "JwT0hvgiR4WB0-SO9QG7Ig" (item_type: "I8Q6k-HqQmaZ498WKtvFbg")
22
        ├ title: "E-commerce Innovation Gallery"
23
        └ images
24
          ├ [0]
25
          │ ├ upload_id: "eLVHtrefRUq7qkVMpzG6mQ"
26
          │ ├ alt: "Modern e-commerce interface"
27
          │ └ title: "Next-gen Shopping"
28
          └ [1]
29
            ├ upload_id: "UFIyIRQFT1GQ7YAG34ub5w"
30
            ├ alt: "AI-powered recommendations"
31
            └ title: "Smart Product Discovery"
32

33
-- AFTER UPDATE --
34
└ Item "RSfdsZbbR7ixGgMBSmcaVA" (item_type: "ZV0o9497SsqWxQR8HEQddw")
35
  ├ title: "The Future of E-commerce Technology"
36
  ├ author: "Alex Thompson"
37
  └ content
38
    ├ paragraph
39
    │ ├ span "E-commerce is evolving rapidly with new technologies like "
40
    │ ├ inlineBlock
41
    │ │ └ Item "LQlcO4LCTYaOrfj2A705DQ" (item_type: "VGXgXav9SwG5P48frGrFxA")
42
    │ │   ├ product_name: "AI Shopping Assistant"
43
    │ │   ├ price: 99.99
44
    │ │   └ affiliate_url: "https://old-domain.com/product?ref=blog&source=article_mention"
45
    │ └ span " transforming how customers shop online."
46
    ├ block
47
    │ └ Item "FqTxaDO8TJmtkoTgDjbK8Q" (item_type: "d-CHYg-rShOt3kiL6ZN1yA")
48
    │   ├ title: "Join the Revolution"
49
    │   ├ description: "Stay ahead of the curve with our e-commerce insights."
50
    │   ├ button_text: "Subscribe Now"
51
    │   └ button_url: "https://new-domain.com/subscribe"
52
    ├ block
53
    │ └ Item "JwT0hvgiR4WB0-SO9QG7Ig" (item_type: "I8Q6k-HqQmaZ498WKtvFbg")
54
    │   ├ title: "E-commerce Innovation Gallery"
55
    │   └ images
56
    │     ├ [0]
57
    │     │ ├ upload_id: "eLVHtrefRUq7qkVMpzG6mQ"
58
    │     │ ├ alt: "Modern e-commerce interface"
59
    │     │ └ title: "Next-gen Shopping"
60
    │     └ [1]
61
    │       ├ upload_id: "UFIyIRQFT1GQ7YAG34ub5w"
62
    │       ├ alt: "AI-powered recommendations"
63
    │       └ title: "Smart Product Discovery"
64
    └ block
65
      └ Item "czplSGgiSnizmFZ7gMT-_g" (item_type: "d-CHYg-rShOt3kiL6ZN1yA")
66
        ├ title: "Join the Revolution"
67
        ├ description: "Stay ahead of the curve with our e-commerce insights."
68
        ├ button_text: "Subscribe Now"
69
        └ 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.

Need	Helper
Build a block (create / edit)	`buildBlockRecord<T>(...)`
Clone a block (deep copy, IDs stripped)	`duplicateBlockRecord<T>(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.

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

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:

1
{
2
  "title": {
3
    "en": "Hello World",
4
    "it": "Ciao a tutti! (Updated)"
5
  }
6
}

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!

1
{
2
  "content_blocks": {
3
    "en": [
4
      {
5
        "id": "dhVR2HqgRVCTGFi0bWqLqA",
6
        "type": "item",
7
        "attributes": { "title": "Updated English Title" }
8
      },
9
      "kL9mN3pQrStUvWxYzAbCdE"
10
    ],
11
    "it": [
12
      "dhVR2HqgRVCTGFi_0bWqLqA",
13
      "kL9mN3pQrStUvWxYzAbCdE"
14
    ]
15
  }
16
}

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!

1
{
2
  "content_blocks": {
3
    "en": [
4
      "dhVR2HqgRVCTGFi_0bWqLqA",
5
      "kL9mN3pQrStUvWxYzAbCdE"
6
    ],
7
    "it": [
8
      "fG8hI1jKlMnOpQrStUvWxY",
9
      {
10
        "type": "item",
11
        "attributes": { "title": "Nuovo Blocco" },
12
        "relationships": {
13
          "item_type": { "data": { "id": "BxZ9Y2aKQVeTnM4hP8wLpD", "type": "item_type" } }
14
        }
15
      },
16
      "dhVR2HqgRVCTGFi0bWqLqA"
17
    ]
18
  }
19
}

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.

1
{
2
  "title": {
3
    "en": "English Title",
4
    "fr": "Titre Français",
5
  },
6
  "content_blocks": {
7
    "en": [
8
      "dhVR2HqgRVCTGFi_0bWqLqA",
9
      "kL9mN3pQrStUvWxYzAbCdE"
10
    ],
11
    "fr": [
12
      {
13
        "type": "item",
14
        "attributes": { "title": "Nouveau Bloc Français" },
15
        "relationships": {
16
          "item_type": { "data": { "id": "BxZ9Y2aKQVeTnM4hP8wLpD", "type": "item_type" } }
17
        }
18
      }
19
    ]
20
  }
21
}

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.

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 to be false on the model.

1
import { buildClient, inspectItem } from "@datocms/cma-client-node";
2
import type * as Schema from "./schema.js";
3

4
/*
5
 * Article
6
 * ├─ author: string
7
 * ├─ title: string (localized)
8
 * └─ content: text (localized)
9
 */
10

11
async function run() {
12
  // Make sure the API token has access to the CMA, and is stored securely
13
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
14

15
  const item = await client.items.update<Schema.Article>(
16
    "T4m4tPymSACFzsqbZS65WA",
17
    {
18
      title: {
19
        en: "My title",
20
        it: "Il mio titolo",
21
        de: "Mein Titel",
22
      },
23
      content: {
24
        en: "Schema.Article content",
25
        it: "Contenuto articolo",
26
        de: "Artikelinhalt",
27
      },
28
    },
29
  );
30

31
  console.log(inspectItem(item));
32
}
33

34
run();

1
└ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
2
  ├ author: "Stefano Verna"
3
  ├ title
4
  │ ├ de: "Mein Titel"
5
  │ ├ en: "My title"
6
  │ └ it: "Il mio titolo"
7
  └ content
8
    ├ de: "Artikelinhalt"
9
    ├ en: "Article content"
10
    └ it: "Contenuto articolo"

If the all_locales_required 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 ItemTypeDefinitions 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() 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.

1
import type { ApiTypes } from "@datocms/cma-client-node";
2
import {
3
  buildClient,
4
  inspectItem,
5
  isLocalized,
6
  type LocalizedFieldValue,
7
} from "@datocms/cma-client-node";
8
import lodash from "lodash";
9
import type * as Schema from "./schema.js";
10

11
/*
12
 * Article
13
 * ├─ title: string (localized)
14
 * ├─ content: structured_text (localized)
15
 * ├─ cta_block: single_block
16
 * │  └─ CtaBlock: title, button_text, button_url
17
 * └─ cover_image: file
18
 *
19
 * ArticleCopy
20
 * ├─ title: string (localized)
21
 * ├─ content: structured_text (localized)
22
 * ├─ cta_block: single_block
23
 * │  └─ CtaBlock
24
 * └─ cover_image: file
25
 */
26

27
// Make sure the API token has access to the CMA, and is stored securely
28
const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
29

30
async function removeLocaleWhenSchemaIsKnown() {
31
  // First, fetch the existing record to get current values
32
  const existingRecord = await client.items.find<Schema.Article>(
33
    "T4m4tPymSACFzsqbZS65WA",
34
  );
35

36
  console.log("-- BEFORE UPDATE --");
37
  console.log(inspectItem(existingRecord));
38

39
  // Update the record to remove the "it" locale by omitting it from all localized fields
40
  // Using lodash omit() for clean, readable locale removal
41
  const updatedRecord = await client.items.update<Schema.Article>(
42
    "T4m4tPymSACFzsqbZS65WA",
43
    {
44
      title: lodash.omit(existingRecord.title, "it"),
45
      content: lodash.omit(existingRecord.content, "it"),
46
      // Do not pass non-localized fields (ie. cover_image, cta_block), as we want to keep them unchanged
47
    },
48
  );
49

50
  console.log("-- AFTER LOCALE REMOVAL --");
51
  console.log(inspectItem(updatedRecord));
52
}
53

54
// When you don't know the model structure ahead of time,
55
// you can dynamically load the fields and perform the same operation
56
async function removeLocaleWhenSchemaIsUnknown() {
57
  // Get the model fields
58
  const fields = await client.fields.list("ZV0o9497SsqWxQR8HEQddw");
59

60
  // Filter to only localized fields using the isLocalized helper
61
  const localizedFields = fields.filter(isLocalized);
62

63
  // Process all records of this model type
64
  for await (const record of client.items.listPagedIterator({
65
    filter: { type: "ZV0o9497SsqWxQR8HEQddw" },
66
  })) {
67
    const updatePayload: ApiTypes.ItemUpdateSchema = {};
68

69
    // Build update payload by processing each localized field
70
    for (const field of localizedFields) {
71
      const fieldValue = record[field.api_key] as LocalizedFieldValue;
72

73
      // Remove the "it" locale from each field's localized values
74
      updatePayload[field.api_key] = lodash.omit(fieldValue, "it");
75
    }
76

77
    // Update the record with the modified locale data
78
    await client.items.update(record.id, updatePayload);
79
  }
80

81
  console.log("Removed 'it' locale from all records of the model");
82
}
83

84
async function run() {
85
  // Run both examples
86
  await removeLocaleWhenSchemaIsKnown();
87
  await removeLocaleWhenSchemaIsUnknown();
88
}
89

90
run();

1
-- BEFORE UPDATE --
2
└ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
3
  ├ title
4
  │ ├ de: "Content-Management verstehen"
5
  │ ├ en: "Understanding Content Management"
6
  │ └ it: "Capire la gestione dei contenuti"
7
  ├ content
8
  │ ├ de
9
  │ │ └ paragraph
10
  │ │   └ span "Ein umfassender Leitfaden für moderne Content-Management-Systeme und ..."
11
  │ ├ en
12
  │ │ └ paragraph
13
  │ │   └ span "A comprehensive guide to modern content management systems and best p..."
14
  │ └ it
15
  │   └ paragraph
16
  │     └ span "Una guida completa ai sistemi di gestione dei contenuti moderni e all..."
17
  ├ cta_block: "ZPfQFuaqTn2cdoQnPSsu_g"
18
  └ cover_image
19
    └ upload_id: "adCusKKeRPO5wtjrIIcGjw"
20

21
-- AFTER LOCALE REMOVAL --
22
└ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
23
  ├ title
24
  │ ├ de: "Content-Management verstehen"
25
  │ └ en: "Understanding Content Management"
26
  ├ content
27
  │ ├ de
28
  │ │ └ paragraph
29
  │ │   └ span "Ein umfassender Leitfaden für moderne Content-Management-Systeme und ..."
30
  │ └ en
31
  │   └ paragraph
32
  │     └ span "A comprehensive guide to modern content management systems and best p..."
33
  ├ cta_block: "ZPfQFuaqTn2cdoQnPSsu_g"
34
  └ cover_image
35
    └ upload_id: "adCusKKeRPO5wtjrIIcGjw"
36

37
Removed 'it' locale from all records of the model

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, and recurses into nested blocks with mapBlocksInNonLocalizedFieldValue to strip their IDs — that way the target locale gets fresh block instances instead of references to the source ones.

1
import assert from "node:assert";
2
import type { ApiTypes } from "@datocms/cma-client-node";
3
import {
4
  buildClient,
5
  inspectItem,
6
  isItemWithOptionalMeta,
7
  isLocalized,
8
  type LocalizedFieldValue,
9
  mapBlocksInNonLocalizedFieldValue,
10
  mapNormalizedFieldValuesAsync,
11
  SchemaRepository,
12
} from "@datocms/cma-client-node";
13

14
async function run() {
15
  // Make sure the API token has access to the CMA, and is stored securely
16
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
17

18
  const schemaRepository = new SchemaRepository(client);
19

20
  for (const model of await schemaRepository.getAllModels()) {
21
    const fields = await schemaRepository.getItemTypeFields(model);
22
    const localizedFields = fields.filter(isLocalized);
23

24
    // Iterating across every model discovered at runtime, so no single
25
    // `<Schema.X>` generic fits — keep `listPagedIterator` untyped and narrow
26
    // field values dynamically below.
27
    for await (const record of client.items.listPagedIterator({
28
      filter: { type: model.api_key },
29
      version: "current",
30
      nested: true,
31
    })) {
32
      const updatePayload: ApiTypes.ItemUpdateSchema = {};
33
      let hasChanges = false;
34

35
      for (const field of localizedFields) {
36
        const fieldValueWithNestedBlocks = record[
37
          field.api_key
38
        ] as LocalizedFieldValue;
39

40
        if (!fieldValueWithNestedBlocks["en"]) {
41
          continue;
42
        }
43

44
        const newFieldValue = (await mapNormalizedFieldValuesAsync(
45
          fieldValueWithNestedBlocks,
46
          field,
47
          async (_locale, fieldValueForLocale) => {
48
            return mapBlocksInNonLocalizedFieldValue(
49
              fieldValueForLocale,
50
              field.field_type,
51
              schemaRepository,
52
              (block) => {
53
                assert(isItemWithOptionalMeta(block));
54
                return block.id;
55
              },
56
            );
57
          },
58
        )) as LocalizedFieldValue;
59

60
        // Strip IDs from cloned blocks so en-AT gets fresh instances rather
61
        // than references to the en blocks.
62
        newFieldValue["en-AT"] = await mapBlocksInNonLocalizedFieldValue(
63
          fieldValueWithNestedBlocks["en"],
64
          field.field_type,
65
          schemaRepository,
66
          (block) => {
67
            assert(isItemWithOptionalMeta(block));
68
            const { id, ...blockWithoutId } = block;
69
            return blockWithoutId;
70
          },
71
        );
72

73
        updatePayload[field.api_key] = newFieldValue;
74

75
        hasChanges = true;
76
      }
77

78
      if (hasChanges) {
79
        console.log("-- EXISTING RECORD --");
80
        console.log(inspectItem(record));
81

82
        console.log("-- UPDATE PAYLOAD --");
83
        console.log(inspectItem(updatePayload));
84

85
        await client.items.update(record.id, updatePayload);
86

87
        const nestedRecord = await client.items.find(record.id, {
88
          nested: true,
89
        });
90
        console.log("-- RECORD AFTER UPDATE --");
91
        console.log(inspectItem(nestedRecord));
92
      }
93
    }
94
  }
95
}
96

97
run();

1
-- EXISTING RECORD --
2
└ Item "Bz0dHLjeRuCW10fJl1GF0w" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
3
  ├ name
4
  │ ├ de: "Premium Kabellose Kopfhörer"
5
  │ └ en: "Premium Wireless Headphones"
6
  ├ description
7
  │ ├ de: "Erleben Sie kristallklaren Klang mit unseren hochwertigen kabellosen Kopfhöre..."
8
  │ └ en: "Experience crystal-clear audio with our top-of-the-line wireless headphones f..."
9
  ├ features
10
  │ ├ de
11
  │ │ ├ [0] Item "YazSxGr2TlKLJZjJmyhg0Q" (item_type: "T4m4tPymSACFzsqbZS65WA")
12
  │ │ │ ├ title: "Aktive Geräuschunterdrückung"
13
  │ │ │ └ description: "Blockieren Sie unerwünschte Geräusche mit unserer fortschrittlichen ANC-Techn..."
14
  │ │ └ [1] Item "D1Zh8Ff2SaC1CCG67Ic1sQ" (item_type: "T4m4tPymSACFzsqbZS65WA")
15
  │ │   ├ title: "30 Stunden Akkulaufzeit"
16
  │ │   └ description: "Ganztägiges Hören mit Schnellladefunktion."
17
  │ └ en
18
  │   ├ [0] Item "HqZZmo8sRKuKMfaUZbkNig" (item_type: "T4m4tPymSACFzsqbZS65WA")
19
  │   │ ├ title: "Active Noise Cancellation"
20
  │   │ └ description: "Block out unwanted noise with our advanced ANC technology."
21
  │   └ [1] Item "NKaGQ1AUQZSfHHhL0c3eLA" (item_type: "T4m4tPymSACFzsqbZS65WA")
22
  │     ├ title: "30-Hour Battery Life"
23
  │     └ description: "All-day listening with fast charging capabilities."
24
  └ price: 299.99
25

26
-- UPDATE PAYLOAD --
27
└ Item
28
  ├ description
29
  │ ├ de: "Erleben Sie kristallklaren Klang mit unseren hochwertigen kabellosen Kopfhöre..."
30
  │ ├ en: "Experience crystal-clear audio with our top-of-the-line wireless headphones f..."
31
  │ └ en-AT: "Experience crystal-clear audio with our top-of-the-line wireless headphones f..."
32
  ├ features
33
  │ ├ de
34
  │ │ ├ [0] "YazSxGr2TlKLJZjJmyhg0Q"
35
  │ │ └ [1] "D1Zh8Ff2SaC1CCG67Ic1sQ"
36
  │ ├ en
37
  │ │ ├ [0] "HqZZmo8sRKuKMfaUZbkNig"
38
  │ │ └ [1] "NKaGQ1AUQZSfHHhL0c3eLA"
39
  │ └ en-AT
40
  │   ├ [0] Item (item_type: "T4m4tPymSACFzsqbZS65WA")
41
  │   │ ├ title: "Active Noise Cancellation"
42
  │   │ └ description: "Block out unwanted noise with our advanced ANC technology."
43
  │   └ [1] Item (item_type: "T4m4tPymSACFzsqbZS65WA")
44
  │     ├ title: "30-Hour Battery Life"
45
  │     └ description: "All-day listening with fast charging capabilities."
46
  └ name
47
    ├ de: "Premium Kabellose Kopfhörer"
48
    ├ en: "Premium Wireless Headphones"
49
    └ en-AT: "Premium Wireless Headphones"
50

51
-- RECORD AFTER UPDATE --
52
└ Item "Bz0dHLjeRuCW10fJl1GF0w" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
53
  ├ name
54
  │ ├ de: "Premium Kabellose Kopfhörer"
55
  │ ├ en: "Premium Wireless Headphones"
56
  │ └ en-AT: "Premium Wireless Headphones"
57
  ├ description
58
  │ ├ de: "Erleben Sie kristallklaren Klang mit unseren hochwertigen kabellosen Kopfhöre..."
59
  │ ├ en: "Experience crystal-clear audio with our top-of-the-line wireless headphones f..."
60
  │ └ en-AT: "Experience crystal-clear audio with our top-of-the-line wireless headphones f..."
61
  ├ features
62
  │ ├ de
63
  │ │ ├ [0] Item "YazSxGr2TlKLJZjJmyhg0Q" (item_type: "T4m4tPymSACFzsqbZS65WA")
64
  │ │ │ ├ title: "Aktive Geräuschunterdrückung"
65
  │ │ │ └ description: "Blockieren Sie unerwünschte Geräusche mit unserer fortschrittlichen ANC-Techn..."
66
  │ │ └ [1] Item "D1Zh8Ff2SaC1CCG67Ic1sQ" (item_type: "T4m4tPymSACFzsqbZS65WA")
67
  │ │   ├ title: "30 Stunden Akkulaufzeit"
68
  │ │   └ description: "Ganztägiges Hören mit Schnellladefunktion."
69
  │ ├ en
70
  │ │ ├ [0] Item "HqZZmo8sRKuKMfaUZbkNig" (item_type: "T4m4tPymSACFzsqbZS65WA")
71
  │ │ │ ├ title: "Active Noise Cancellation"
72
  │ │ │ └ description: "Block out unwanted noise with our advanced ANC technology."
73
  │ │ └ [1] Item "NKaGQ1AUQZSfHHhL0c3eLA" (item_type: "T4m4tPymSACFzsqbZS65WA")
74
  │ │   ├ title: "30-Hour Battery Life"
75
  │ │   └ description: "All-day listening with fast charging capabilities."
76
  │ └ en-AT
77
  │   ├ [0] Item "Txk_qqFJSL6VP3wFzmE_2w" (item_type: "T4m4tPymSACFzsqbZS65WA")
78
  │   │ ├ title: "Active Noise Cancellation"
79
  │   │ └ description: "Block out unwanted noise with our advanced ANC technology."
80
  │   └ [1] Item "eValhxXxTZe-6FW-mwe80g" (item_type: "T4m4tPymSACFzsqbZS65WA")
81
  │     ├ title: "30-Hour Battery Life"
82
  │     └ description: "All-day listening with fast charging capabilities."
83
  └ 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 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.

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(), then walks each record with mapNormalizedFieldValuesAsync and 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.

1
import assert from "node:assert";
2
import {
3
  type ApiTypes,
4
  buildBlockRecord,
5
  buildClient,
6
  inspectItem,
7
  isItemWithOptionalMeta,
8
  mapBlocksInNonLocalizedFieldValue,
9
  mapNormalizedFieldValuesAsync,
10
  type RawApiTypes,
11
  SchemaRepository,
12
} from "@datocms/cma-client-node";
13
import * as Schema from "./schema.js";
14

15
/*
16
 * Article
17
 * ├─ title: string (localized)
18
 * ├─ content: structured_text (localized)
19
 * │  └─ CtaBlock: title, description, button_text, button_url, style
20
 * └─ sidebar: rich_text
21
 *    └─ CtaBlock
22
 *
23
 * LandingPage
24
 * └─ hero_cta: single_block
25
 *    └─ CtaBlock
26
 */
27

28
// Simplified style decision logic
29
function computeCtaStyle(text: string | null): "primary" | "muted" {
30
  if (!text) return "muted";
31
  return /buy|get started|start free|sign up|upgrade/i.test(text)
32
    ? "primary"
33
    : "muted";
34
}
35

36
// Make sure the API token has access to the CMA, and is stored securely
37
const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
38

39
async function run() {
40
  const schemaRepository = new SchemaRepository(client);
41
  const ctaBlockModel = await schemaRepository.getItemTypeById(
42
    Schema.CtaBlock.ID,
43
  );
44

45
  // 1. Find all models that can embed CTA blocks (directly or indirectly)
46
  const modelsEmbeddingCtas = await schemaRepository.getModelsEmbeddingBlocks([
47
    ctaBlockModel,
48
  ]);
49

50
  // 2. Process each model and its records
51
  for (const model of modelsEmbeddingCtas) {
52
    console.log(
53
      `\n📋 Processing records of model: ${model.name} (${model.api_key})`,
54
    );
55

56
    const fields = await schemaRepository.getItemTypeFields(model);
57

58
    // This script iterates records across every model discovered at runtime,
59
    // so there is no single `<Schema.X>` generic that fits — we keep
60
    // `rawListPagedIterator` untyped here and narrow block values dynamically
61
    // below. Per-model scripts should always pass the generated marker.
62
    for await (const record of client.items.rawListPagedIterator({
63
      filter: { type: model.id },
64
      version: "current",
65
      nested: true, // Get full block objects
66
    })) {
67
      console.log(`\n--- Processing ${record.id} ---`);
68
      console.log("BEFORE:");
69
      console.log(inspectItem(record));
70

71
      const updatedAttributes: ApiTypes.ItemUpdateSchema = {};
72

73
      // 3. Use mapNormalizedFieldValuesAsync to handle localized/non-localized uniformly
74
      for (const field of fields) {
75
        const fieldValue = record.attributes[field.api_key];
76

77
        let fieldHasChanges = false;
78

79
        const updatedFieldValue = await mapNormalizedFieldValuesAsync(
80
          fieldValue,
81
          field,
82
          async (_locale, normalizedFieldValue) =>
83
            mapBlocksInNonLocalizedFieldValue(
84
              normalizedFieldValue,
85
              field.field_type,
86
              schemaRepository,
87
              (block) => {
88
                assert(isItemWithOptionalMeta(block));
89

90
                if (block.__itemTypeId !== Schema.CtaBlock.ID) {
91
                  return block.id; // Keep non-CTA blocks as is
92
                }
93

94
                // The raw iterator yields records (and their embedded blocks)
95
                // in the raw API shape; narrow to this specific block model
96
                // via the ItemInNestedResponse schema indexed by Schema.CtaBlock.
97
                const ctaBlock =
98
                  block as RawApiTypes.ItemInNestedResponse<Schema.CtaBlock>;
99
                const currentStyle = ctaBlock.attributes.style;
100
                const desiredStyle = computeCtaStyle(
101
                  ctaBlock.attributes.button_text,
102
                );
103

104
                if (currentStyle !== desiredStyle) {
105
                  fieldHasChanges = true;
106

107
                  // Return an updated block record with new style
108
                  return buildBlockRecord<Schema.CtaBlock>({
109
                    id: ctaBlock.id,
110
                    style: desiredStyle,
111
                  });
112
                }
113

114
                return block.id; // No change needed
115
              },
116
            ),
117
        );
118

119
        if (fieldHasChanges) {
120
          updatedAttributes[field.api_key] = updatedFieldValue;
121
        }
122
      }
123

124
      // 4. Update the record if there were changes
125
      if (Object.keys(updatedAttributes).length > 0) {
126
        const updatedRecord = await client.items.update(
127
          record.id,
128
          updatedAttributes,
129
        );
130

131
        console.log("AFTER:");
132
        await inspectItemWithNestedBlocks(updatedRecord);
133
      } else {
134
        console.log("✨ No changes needed for this record");
135
      }
136
    }
137
  }
138
}
139

140
run();
141

142
async function inspectItemWithNestedBlocks(item: ApiTypes.Item) {
143
  const itemWithNestedBlocks = await client.items.find(item, { nested: true });
144
  console.log(inspectItem(itemWithNestedBlocks));
145
}

1
📋 Processing records of model: Landing Page (landing_page)
2

3
--- Processing IwcHsSQ5SSa2LYzpk_Ddjw ---
4
BEFORE:
5
└ Item "IwcHsSQ5SSa2LYzpk_Ddjw" (item_type: "KUz2pYAvQvOWqv3dVwVw3w")
6
  └ hero_cta
7
    └ Item "fnclskI4RG25uLQC92XE5g" (item_type: "DC2XVF6BTjGBgQaoaih6Og")
8
      ├ title: "Transform Your Business"
9
      ├ description: "Take the next step forward"
10
      ├ button_text: "Get started"
11
      ├ button_url: "/start"
12
      └ style: "muted"
13

14
AFTER:
15
└ Item "IwcHsSQ5SSa2LYzpk_Ddjw" (item_type: "KUz2pYAvQvOWqv3dVwVw3w")
16
  └ hero_cta
17
    └ Item "fnclskI4RG25uLQC92XE5g" (item_type: "DC2XVF6BTjGBgQaoaih6Og")
18
      ├ title: "Transform Your Business"
19
      ├ description: "Take the next step forward"
20
      ├ button_text: "Get started"
21
      ├ button_url: "/start"
22
      └ style: "primary"
23

24

25
📋 Processing records of model: Article (article)
26

27
--- Processing JPplplyPTMKpCbB-wipxeA ---
28
BEFORE:
29
└ Item "JPplplyPTMKpCbB-wipxeA" (item_type: "ONxSjA4WTWaoNJY2zokUoQ")
30
  ├ title
31
  │ ├ en: "Sample Article"
32
  │ └ it: "Articolo di Esempio"
33
  ├ content
34
  │ ├ en
35
  │ │ ├ paragraph
36
  │ │ │ └ span "Introduction text"
37
  │ │ ├ block
38
  │ │ │ └ Item "BOps1UFgSU-CSm-fRjoqCA" (item_type: "DC2XVF6BTjGBgQaoaih6Og")
39
  │ │ │   ├ title: "Join Our Platform"
40
  │ │ │   ├ description: "Start your journey today"
41
  │ │ │   ├ button_text: "Sign up"
42
  │ │ │   ├ button_url: "/signup"
43
  │ │ │   └ style: "muted"
44
  │ │ └ paragraph
45
  │ │   └ span "Conclusion text"
46
  │ └ it
47
  │   ├ paragraph
48
  │   │ └ span "Testo introduttivo"
49
  │   └ block
50
  │     └ Item "SSVQgIbZS_uoPQWg-qYzWg" (item_type: "DC2XVF6BTjGBgQaoaih6Og")
51
  │       ├ title: "Scopri di Più"
52
  │       ├ description: "Leggi la nostra guida"
53
  │       ├ button_text: "Learn more"
54
  │       ├ button_url: "/guide"
55
  │       └ style: "primary"
56
  └ sidebar
57
    └ [0] Item "f86JBAwxTsasu7J3XxXqJg" (item_type: "DC2XVF6BTjGBgQaoaih6Og")
58
      ├ title: "Special Offer"
59
      ├ description: "Limited time promotion"
60
      ├ button_text: "Buy now"
61
      ├ button_url: "/buy"
62
      └ style: "muted"
63

64
AFTER:
65
└ Item "JPplplyPTMKpCbB-wipxeA" (item_type: "ONxSjA4WTWaoNJY2zokUoQ")
66
  ├ title
67
  │ ├ en: "Sample Article"
68
  │ └ it: "Articolo di Esempio"
69
  ├ content
70
  │ ├ en
71
  │ │ ├ paragraph
72
  │ │ │ └ span "Introduction text"
73
  │ │ ├ block
74
  │ │ │ └ Item "BOps1UFgSU-CSm-fRjoqCA" (item_type: "DC2XVF6BTjGBgQaoaih6Og")
75
  │ │ │   ├ title: "Join Our Platform"
76
  │ │ │   ├ description: "Start your journey today"
77
  │ │ │   ├ button_text: "Sign up"
78
  │ │ │   ├ button_url: "/signup"
79
  │ │ │   └ style: "primary"
80
  │ │ └ paragraph
81
  │ │   └ span "Conclusion text"
82
  │ └ it
83
  │   ├ paragraph
84
  │   │ └ span "Testo introduttivo"
85
  │   └ block
86
  │     └ Item "SSVQgIbZS_uoPQWg-qYzWg" (item_type: "DC2XVF6BTjGBgQaoaih6Og")
87
  │       ├ title: "Scopri di Più"
88
  │       ├ description: "Leggi la nostra guida"
89
  │       ├ button_text: "Learn more"
90
  │       ├ button_url: "/guide"
91
  │       └ style: "muted"
92
  └ sidebar
93
    └ [0] Item "f86JBAwxTsasu7J3XxXqJg" (item_type: "DC2XVF6BTjGBgQaoaih6Og")
94
      ├ title: "Special Offer"
95
      ├ description: "Limited time promotion"
96
      ├ button_text: "Buy now"
97
      ├ button_url: "/buy"
98
      └ style: "primary"

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(), then walks each record with mapNormalizedFieldValuesAsync and filterBlocksInNonLocalizedFieldValue. The removal predicate is an async check (mocked here as an ecommerce SKU lookup), so the same shape works for any external decision.

1
import assert from "node:assert";
2
import {
3
  type ApiTypes,
4
  buildClient,
5
  filterBlocksInNonLocalizedFieldValue,
6
  inspectItem,
7
  isItemWithOptionalMeta,
8
  mapNormalizedFieldValuesAsync,
9
  type RawApiTypes,
10
  SchemaRepository,
11
} from "@datocms/cma-client-node";
12
import * as Schema from "./schema.js";
13

14
/*
15
 * Article
16
 * ├─ title: string (localized)
17
 * ├─ content: structured_text (localized)
18
 * │  └─ ProductBlock: sku
19
 * └─ sidebar: rich_text
20
 *    └─ ProductBlock
21
 *
22
 * ProductPage
23
 * └─ featured_product: single_block
24
 *    └─ ProductBlock
25
 */
26

27
// Mock external ecommerce system check
28
async function isValidSKU(sku: string | null): Promise<boolean> {
29
  // For demo purposes, consider SKUs starting with "INVALID" as discontinued
30
  return Boolean(sku && !sku.startsWith("INVALID"));
31
}
32

33
async function run() {
34
  // Make sure the API token has access to the CMA, and is stored securely
35
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
36

37
  const schemaRepository = new SchemaRepository(client);
38
  const productBlockModel = await schemaRepository.getItemTypeById(
39
    Schema.ProductBlock.ID,
40
  );
41

42
  // 1. Find all models that can embed Product blocks (directly or indirectly)
43
  const modelsEmbeddingProductBlocks =
44
    await schemaRepository.getModelsEmbeddingBlocks([productBlockModel]);
45

46
  // 2. Process each model and its records
47
  for (const model of modelsEmbeddingProductBlocks) {
48
    console.log(
49
      `\n📋 Processing records of model: ${model.name} (${model.api_key})`,
50
    );
51

52
    const fields = await schemaRepository.getItemTypeFields(model);
53

54
    // This script iterates records across every model discovered at runtime,
55
    // so there is no single `<Schema.X>` generic that fits — we keep
56
    // `rawListPagedIterator` untyped here and narrow block values dynamically
57
    // below. Per-model scripts should always pass the generated marker.
58
    for await (const record of client.items.rawListPagedIterator({
59
      filter: { type: model.id },
60
      version: "current",
61
      nested: true, // Get full block objects
62
    })) {
63
      console.log(`\n--- Processing ${record.id} ---`);
64
      console.log("BEFORE:");
65
      console.log(inspectItem(record));
66

67
      const updatedAttributes: ApiTypes.ItemUpdateSchema = {};
68

69
      // 3. Use mapNormalizedFieldValuesAsync to handle localized/non-localized fields uniformly
70
      for (const field of fields) {
71
        const fieldValue = record.attributes[field.api_key];
72

73
        let fieldHasChanges = false;
74

75
        const updatedFieldValue = await mapNormalizedFieldValuesAsync(
76
          fieldValue,
77
          field,
78
          async (_locale, normalizedFieldValue) => {
79
            // 4. Use filterBlocksInNonLocalizedFieldValue to recursively filter blocks
80
            const filteredValue = await filterBlocksInNonLocalizedFieldValue(
81
              normalizedFieldValue,
82
              field.field_type,
83
              schemaRepository,
84
              async (block) => {
85
                assert(isItemWithOptionalMeta(block));
86

87
                // Only check Product blocks
88
                if (block.__itemTypeId !== Schema.ProductBlock.ID) {
89
                  return true; // Keep other blocks
90
                }
91

92
                // The raw iterator yields records (and their embedded blocks)
93
                // in the raw API shape; narrow to this specific block model
94
                // via the ItemInNestedResponse schema indexed by Schema.ProductBlock.
95
                const productBlock =
96
                  block as RawApiTypes.ItemInNestedResponse<Schema.ProductBlock>;
97

98
                // Check if the product SKU is still valid in external system
99
                const isValid = await isValidSKU(productBlock.attributes.sku);
100

101
                if (!isValid) {
102
                  fieldHasChanges = true;
103
                }
104

105
                return isValid;
106
              },
107
            );
108

109
            return filteredValue;
110
          },
111
        );
112

113
        if (fieldHasChanges) {
114
          updatedAttributes[field.api_key] = updatedFieldValue;
115
        }
116
      }
117

118
      // 5. Update the record if there were changes
119
      if (Object.keys(updatedAttributes).length > 0) {
120
        const updatedRecord = await client.items.update(
121
          record.id,
122
          updatedAttributes,
123
        );
124

125
        console.log("AFTER:");
126
        console.log(inspectItem(updatedRecord));
127
      } else {
128
        console.log("✨ No changes needed for this record");
129
      }
130
    }
131
  }
132
}
133

134
run();

1
📋 Processing records of model: Product Page (product_page)
2

3
--- Processing RZfnYc3iSya7yYaTxoW0VA ---
4
BEFORE:
5
└ Item "RZfnYc3iSya7yYaTxoW0VA" (item_type: "KUz2pYAvQvOWqv3dVwVw3w")
6
  └ featured_product
7
    └ Item "XayqICFqQEyEqGFypcK07w" (item_type: "DC2XVF6BTjGBgQaoaih6Og")
8
      └ sku: "INVALID-SKU-004"
9

10
AFTER:
11
└ Item "RZfnYc3iSya7yYaTxoW0VA" (item_type: "KUz2pYAvQvOWqv3dVwVw3w")
12
  └ featured_product: null
13

14

15
📋 Processing records of model: Article (article)
16

17
--- Processing Iaa0ZiZMSjCqeFWfs3JeuQ ---
18
BEFORE:
19
└ Item "Iaa0ZiZMSjCqeFWfs3JeuQ" (item_type: "ONxSjA4WTWaoNJY2zokUoQ")
20
  ├ title
21
  │ ├ en: "Sample Article"
22
  │ └ it: "Articolo di Esempio"
23
  ├ content
24
  │ ├ en
25
  │ │ ├ paragraph
26
  │ │ │ └ span "Introduction text"
27
  │ │ ├ block
28
  │ │ │ └ Item "Z-xM-VpKTzytfo-5jzSlOw" (item_type: "DC2XVF6BTjGBgQaoaih6Og")
29
  │ │ │   └ sku: "INVALID-SKU-001"
30
  │ │ └ paragraph
31
  │ │   └ span "Conclusion text"
32
  │ └ it
33
  │   ├ paragraph
34
  │   │ └ span "Testo introduttivo"
35
  │   └ block
36
  │     └ Item "YoCq3DtzSa2NIbB6ARsiVw" (item_type: "DC2XVF6BTjGBgQaoaih6Og")
37
  │       └ sku: "VALID-SKU-002"
38
  └ sidebar
39
    └ [0] Item "Ulk5GEEoRGSURyyPNSBcow" (item_type: "DC2XVF6BTjGBgQaoaih6Og")
40
      └ sku: "INVALID-SKU-003"
41

42
AFTER:
43
└ Item "Iaa0ZiZMSjCqeFWfs3JeuQ" (item_type: "ONxSjA4WTWaoNJY2zokUoQ")
44
  ├ title
45
  │ ├ en: "Sample Article"
46
  │ └ it: "Articolo di Esempio"
47
  ├ content
48
  │ ├ en
49
  │ │ ├ paragraph
50
  │ │ │ └ span "Introduction text"
51
  │ │ └ paragraph
52
  │ │   └ span "Conclusion text"
53
  │ └ it
54
  │   ├ paragraph
55
  │   │ └ span "Testo introduttivo"
56
  │   └ block "YoCq3DtzSa2NIbB6ARsiVw"
57
  └ 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.

1
import { ApiError, type ApiTypes, buildClient } from "@datocms/cma-client-node";
2
import type * as Schema from "./schema.js";
3

4
/*
5
 * Counter
6
 * ├─ counter: integer
7
 * └─ description: string
8
 */
9

10
// Make sure the API token has access to the CMA, and is stored securely
11
const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
12

13
async function run() {
14
  const itemId = "T4m4tPymSACFzsqbZS65WA";
15

16
  console.log("🚀 Starting concurrent updates simulation...\n");
17

18
  // Create two competing updates that will run concurrently
19
  const updateA = updateRecordWithRetry(
20
    itemId,
21
    (record) => ({
22
      counter: (record.counter || 0) + 10,
23
      description: `Updated by Process A at ${new Date().toISOString()}`,
24
    }),
25
    "Process A",
26
  );
27

28
  const updateB = updateRecordWithRetry(
29
    itemId,
30
    (record) => ({
31
      counter: (record.counter || 0) + 5,
32
      description: `Updated by Process B at ${new Date().toISOString()}`,
33
    }),
34
    "Process B",
35
  );
36

37
  try {
38
    // Run both updates concurrently - one will likely trigger STALE_ITEM_VERSION
39
    const [resultA, resultB] = await Promise.all([updateA, updateB]);
40

41
    console.log("\n✅ Both updates completed successfully!");
42
    console.log(
43
      "Final counter value:",
44
      Math.max(resultA.counter || 0, resultB.counter || 0),
45
    );
46

47
    // Get the final state to see which update won
48
    const finalRecord = await client.items.find<Schema.Counter>(itemId);
49
    console.log("\nFinal record state:");
50
    console.log("- Schema.Counter:", finalRecord.counter);
51
    console.log("- Description:", finalRecord.description);
52
    console.log("- Version:", finalRecord.meta.current_version);
53
  } catch (error) {
54
    console.error("❌ Unexpected error:", error);
55
  }
56
}
57

58
async function updateRecordWithRetry(
59
  itemId: string,
60
  updateFunction: (record: ApiTypes.Item<Schema.Counter>) => {
61
    counter?: number;
62
    description?: string;
63
  },
64
  operationName: string,
65
) {
66
  // Get the current record
67
  const record = await client.items.find<Schema.Counter>(itemId);
68

69
  console.log(
70
    `${operationName}: Got record version ${record.meta.current_version}`,
71
  );
72

73
  try {
74
    // Apply the update with optimistic locking
75
    const updatedRecord = await client.items.update<Schema.Counter>(itemId, {
76
      ...updateFunction(record),
77
      meta: { current_version: record.meta.current_version },
78
    });
79

80
    console.log(
81
      `${operationName}: Update successful! New version: ${updatedRecord.meta.current_version}`,
82
    );
83
    return updatedRecord;
84
  } catch (e) {
85
    // Handle STALE_ITEM_VERSION error by retrying
86
    if (e instanceof ApiError && e.findError("STALE_ITEM_VERSION")) {
87
      console.log(
88
        `${operationName}: ❌ STALE_ITEM_VERSION detected! Record was modified by another client.`,
89
      );
90
      console.log(`${operationName}: 🔄 Retrying with fresh data...`);
91

92
      // Recursive retry with exponential backoff
93
      await new Promise((resolve) =>
94
        setTimeout(resolve, Math.random() * 100 + 50),
95
      );
96
      return updateRecordWithRetry(itemId, updateFunction, operationName);
97
    }
98

99
    throw e;
100
  }
101
}
102

103
run();

1
🚀 Starting concurrent updates simulation...
2

3
Process A: Got record version L80WevK_R6Gh6ijMyW0AkQ
4
Process B: Got record version L80WevK_R6Gh6ijMyW0AkQ
5
Process A: Update successful! New version: QHXWBDr7S9ipQo6_JjQpAg
6
Process B: ❌ STALE_ITEM_VERSION detected! Record was modified by another client.
7
Process B: 🔄 Retrying with fresh data...
8
Process B: Got record version QHXWBDr7S9ipQo6_JjQpAg
9
Process B: Update successful! New version: A4VMeUdtRT26NWd07g6pzw
10

11
✅ Both updates completed successfully!
12
Final counter value: 15
13

14
Final record state:
15
- Counter: 15
16
- Description: Updated by Process B at 2025-09-26T08:25:53.088Z
17
- Version: A4VMeUdtRT26NWd07g6pzw

Body parameters

meta.created_at string Optional

Date of creation

meta.first_published_at null, string Optional

Date of first publication

meta.current_version string Optional

The ID of the current record version (for optimistic locking, see the example)

Example:

"4234"

meta.stage string, null Optional

The new stage to move the record to

item_type Optional

The record's model

Type: ResourceLinkage<"item_type">

creator Optional

The entity (account/collaborator/access token/sso user) who created the record

Type: ResourceLinkage<"account">, ResourceLinkage<"access_token">, ResourceLinkage<"user">, ResourceLinkage<"sso_user">, ResourceLinkage<"organization">

Returns

Returns a resource object of type item