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.

Updating Block Fields

As with creation, you cannot edit blocks directly; you must update the parent record that contains them. The payload you send uses a mix of block IDs and block objects to define the desired final state.

The rules for adding, updating, keeping, deleting, and reordering blocks are covered in detail in the main records guide.

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
}

Mass 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
}