Update a record

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.

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">>;

Updating Block Fields

The general workflow is the same for every block field type:

1. Generate types with the TypeScript schema generator.
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<Article> call, omitting fields you don't change.

Modular Content

Payload is an array of blocks. Each entry expresses one operation:

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.

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.

Block & node helpers

Curated index of the helpers used above.

Block helpers

Used by all three block field types. Full reference: block-processing-utilities.

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.

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.

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.

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
}

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
}

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
}

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.

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.

Body parameters

Returns

Returns a resource object of type item.

Examples

1
PUT https://site-api.datocms.com/items/:item_id HTTP/1.1
2
Authorization: Bearer YOUR-API-TOKEN
3
Accept: application/json
4
X-Api-Version: 3
5
Content-Type: application/vnd.api+json
6

7
{
8
  "data": {
9
    "type": "item",
10
    "id": "hWl-mnkWRYmMCSTq4z_piQ"
11
  }
12
}

1
curl -g 'https://site-api.datocms.com/items/:item_id' \
2
  -X PUT \
3
  -H "Authorization: Bearer YOUR-API-TOKEN" \
4
  -H "Accept: application/json" \
5
  -H "X-Api-Version: 3" \
6
  -H "Content-Type: application/vnd.api+json" \
7
  --data-binary '{"data":{"type":"item","id":"hWl-mnkWRYmMCSTq4z_piQ"}}'

1
await fetch("https://site-api.datocms.com/items/:item_id", {
2
  method: "PUT",
3
  headers: {
4
    Authorization: "Bearer YOUR-API-TOKEN",
5
    Accept: "application/json",
6
    "X-Api-Version": "3",
7
    "Content-Type": "application/vnd.api+json",
8
  },
9
  body: JSON.stringify({
10
    data: { type: "item", id: "hWl-mnkWRYmMCSTq4z_piQ" },
11
  }),
12
});

1
HTTP/1.1 200 OK
2
Content-Type: application/json
3
Cache-Control: cache-control: max-age=0, private, must-revalidate
4
X-RateLimit-Limit: 30
5
X-RateLimit-Remaining: 28
6

7
{
8
  "data": {
9
    "type": "item",
10
    "id": "hWl-mnkWRYmMCSTq4z_piQ",
11
    "relationships": {
12
      "item_type": {
13
        "data": {
14
          "type": "item_type",
15
          "id": "DxMaW10UQiCmZcuuA-IkkA"
16
        }
17
      }
18
    },
19
    "attributes": {
20
      "title": "My first blog post!",
21
      "content": "Lorem ipsum dolor sit amet...",
22
      "category": "24",
23
      "image": {
24
        "alt": "Alt text",
25
        "title": "Image title",
26
        "custom_data": {},
27
        "focal_point": null,
28
        "upload_id": "20042921"
29
      }
30
    },
31
    "meta": {
32
      "created_at": "2020-04-21T07:57:11.124Z",
33
      "updated_at": "2020-04-21T07:57:11.124Z",
34
      "published_at": "2020-04-21T07:57:11.124Z",
35
      "first_published_at": "2020-04-21T07:57:11.124Z",
36
      "publication_scheduled_at": "2020-04-21T07:57:11.124Z",
37
      "unpublishing_scheduled_at": "2020-04-21T07:57:11.124Z",
38
      "status": "published",
39
      "is_current_version_valid": true,
40
      "is_published_version_valid": true,
41
      "current_version": "4234",
42
      "stage": null,
43
      "has_children": true
44
    }
45
  }
46
}