Choose your language:
    Update a record

    Updating record is very similar to creating a new one. Double check that guide and all the examples for more details.

    When updating you can pass just the fields you want to change.

    Updating and version locking

    DatoCMS optionally supports optimistic locking. When updating an existing record, you can specify its current version within the appropriate meta property. DatoCMS compares this version with the current version stored to ensure that a client doesn't overwrite a record that has since been updated. If the version changed in-between, DatoCMS would reject the update with a 422 STALE_ITEM_VERSION error.

    For more information, take a look at the Javascript examples.

    Working with block records

    Block records are always part of a Modular Content or Structured Text field, which have different data structures: while Modular Content is simply an array of blocks, Structured Text accepts a Structured text document, which in turn might contain a number of block nodes interspersed with textual content.

    We’ll get to some detailed examples for both fields below, but the general idea that applies to both of them is that to preserve the atomicity property of ACID transactions, DatoCMS prohibits you from creating/editing/deleting blocks directly; you always need to add/edit/remove blocks by performing an update operation on the record that embeds them, so:

    • If you want to add a block to a field, you need to add to the existing field value the new “fragment” related to the new block;
    • If you want to edit a block that’s already present in the field, you need to pass the whole field value and replace only the “fragment” related to such block, while keeping the rest unchanged;
    • If you want to remove a block that’s already present in the field, you need to pass the whole field value and only remove the "fragment” related to such block, while keeping the rest unchanged.

    Depending on the endpoints you're going to use, the “fragment” representing the block can be simply its ID, or a full JSON API object:

    EndpointHTTP request blocks representationHTTP response blocks representation
    GET /itemsN/AID
    GET /items?nested=trueN/AJSON API object
    GET /item/:idN/AID
    GET /item/:id?nested=trueN/AJSON API object
    POST /itemsJSON API payloadID
    PUT /items/:idID or JSON API objectID

    During an update operation, to reference a block:

    • when you want to make some changes to the content of a specific block, you pass the complete JSON API object (complete with its existing id);
    • when you want to add a totally new block, you pass the complete JSON API object (with no ID of course, as it’s a new object);
    • when you don’t want to make any change to an existing block, you can pass just the block ID (the update operation will be faster this way, as it won’t have to process it).

    Working with localized content

    Before diving in, the key concepts to remember are the following:

    • Localization is handled on a per-field basis. That is, in the same model, some fields can have a different value specified for each locale, and some others just a single (non-localized) value.
    • On localized fields, records express a value for multiple locales using an object, whose keys represent the environment’s locales.
    • The locales specified in a record must be coherent across each localized field. That is, if you have two localized fields, they must share the same locale keys. You cannot ie. specify locales en and it for the title field, and only en for the content field.
    • When a model contains one or more localized fields, it can enforce the presence of a value for all locales, or not.
    • Every user/API token is linked to a role, which in turn specifies which locales can be managed by the user/API token itself on a per-model level.

    Above we said that when you perform an update operation to a record, you can pass just the fields you want to change, and not all of them. When dealing with localized content, the only exception to this rule is when you have a model that does not enforce a value for every locale, and you want to add or remove a locale on a specific record. Only in this case, you are required to pass all localized fields in the payload to enforce a locales coherence between all the localized fields.

    Also, when you want to update the value for a specific localized field, you always need to pass an object containing the value for each locale you want to preserve, not just the one you might want to update, otherwise you’ll get an error.

    If your API token can only manage a subset of locales, during an update operation you are required not to include in the payload any other locales. In this case, the content for the locales you cannot control and that you won’t pass will be kept intact by the system.

    In the following table, you’ll find a recap showing the result of an update operation, depending on the API token permissions, the locales already present in a record, and the locales specified in the payload of the update operation itself:

    Role can manage content inRecord contains localized fields with content inPayload contains all localized fields with content inResult for the update operation
    EnglishEnglishEnglishEnglish is updated.
    English, ItalianEnglishEnglish, ItalianEnglish is updated.
    Italian is added.
    English, ItalianEnglish, ItalianEnglishEnglish is updated.
    Italian is removed.
    English, ItalianEnglish, ItalianEnglish, ItalianEnglish is updated.
    Italian is updated.
    English, Italian, FrenchEnglish, ItalianEnglish, FrenchEnglish is updated.
    Italian is removed.
    French is added.
    EnglishEnglish, ItalianEnglishEnglish is updated.
    Italian is preserved.
    English, ItalianEnglish, FrenchEnglish, ItalianEnglish is updated.
    French is preserved.
    Italian is added.
    English, ItalianEnglish, FrenchItalianEnglish is removed.
    French is preserved.
    Italian is added.

    Below you’ll find some real-world examples related to locales addition/removal for a record.

    Parameters
    meta.createdAt  string  Optional

    Date of creation

    meta.firstPublishedAt  null, string  Optional

    Date of first publication

    meta.unpublishingScheduledAt  null, string  Optional

    Date of future unpublishing

    meta.currentVersion  string  Optional

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

    meta.stage  string, null  Optional

    The new stage to move the record to

    relationships.creator  { type: "account", id: account.id }, { type: "access_token", id: access_token.id }, { type: "user", id: user.id }, { type: "sso_user", id: sso_user.id }  Optional
    Returns
    Returns a item object.

    Examples

    Simple update operation
    Example code:
    const SiteClient = require("datocms-client").SiteClient;
    const client = new SiteClient("YOUR-API-TOKEN");
    const itemId = "4235";
    client.items
    .update(itemId, {
    title: "[EDIT] My first blog post!",
    })
    .then((item) => {
    console.log(item);
    })
    .catch((error) => {
    console.error(error);
    });
    Returned output:
    > node example.js
    {
    "id": "4235",
    "title": "[EDIT] My first blog post!",
    "content": "Lorem ipsum dolor sit amet...",
    "category": "24",
    "image": {
    "uploadId": "1235",
    "alt": "Alt text",
    "title": "Image title",
    "customData": {}
    },
    "meta": {
    "created_at": "2020-04-21T07:57:11.124Z",
    "updated_at": "2020-04-21T07:57:11.124Z",
    "published_at": "2020-04-21T07:57:11.124Z",
    "first_published_at": "2020-04-21T07:57:11.124Z",
    "publication_scheduled_at": "2020-04-21T07:57:11.124Z",
    "unpublishing_scheduled_at": "2020-04-22T07:57:11.124Z",
    "status": "draft",
    "is_valid": true,
    "current_version": "4234"
    },
    "itemType": "44",
    "creator": "312"
    }
    Optimistic-locking update operation
    Example code:
    import { SiteClient, ApiException } from "datocms-client";
    const client = new SiteClient("YOUR-API-TOKEN");
    async function incrementCounter() {
    const itemId = "4235";
    // first we get the record we want to update
    const record = await client.items.find(itemId);
    try {
    // now we increment a field's value, passing the current version
    // to enable optimistic-locking
    client.items.update(itemId, {
    counter: record.counter + 1,
    meta: { currentVersion: record.meta.currentVersion },
    });
    console.log("Done!");
    } catch (e) {
    // if we get a STALE_ITEM_VERSION error, this means that the
    // the record changed in-between the find and update operations, so we have
    // to fetch the latest version of the record and try again
    if (e instanceof ApiException && e.errorWithCode("STALE_ITEM_VERSION")) {
    console.log("Stale version, retrying...");
    return incrementCounter();
    }
    throw e;
    }
    }
    incrementCounter();
    Returned output:
    > node example.js
    Stale version, retrying...
    Stale version, retrying...
    Done!
    Update a block record in modular content field

    Remember to pass the ID of the block record you want to update to buildModularBlock. When updating a block record, you can pass just the fields you want to change.

    Example code:
    const { SiteClient, buildModularBlock } = require("datocms-client");
    const client = new SiteClient("YOUR-API-TOKEN");
    const itemId = "4235";
    const blockModelId = "23455234";
    const blockRecordIdToUpdate = "565346547";
    client.items
    .update(itemId, {
    content: [
    "565346546", // existing block record ID
    buildModularBlock({
    itemType: blockModelId,
    id: blockRecordIdToUpdate,
    text: "updated text",
    }),
    "565346548", // existing block record ID
    ],
    })
    .then((item) => {
    console.log(item);
    })
    .catch((error) => {
    console.error(error);
    });
    Returned output:
    > node example.js
    {
    "id": "4235",
    "title": "Title",
    "content": [ "565346546", "565346547", "565346548" ],
    "meta": { [...] },
    "itemType": "44",
    "creator": "312"
    }
    Reorder block records in modular content field

    You can reorder block records by changing their IDs position in the modular content field array.

    Example code:
    const { SiteClient, buildModularBlock } = require("datocms-client");
    const client = new SiteClient("YOUR-API-TOKEN");
    const itemId = "4235";
    client.items
    .update(itemId, {
    content: ["565346548", "565346547", "565346546"], // previous order was "565346546", "565346547", "565346548"
    })
    .then((item) => {
    console.log(item);
    })
    .catch((error) => {
    console.error(error);
    });
    Returned output:
    > node example.js
    {
    "id": "4235",
    "title": "Title",
    "content": [ "565346548", "565346547", "565346546" ],
    "meta": { [...] },
    "itemType": "44",
    "creator": "312"
    }
    Add a block record in a modular content field

    In this case, you must not pass an ID to buildModularBlock.

    It's not required the presence of all the fields in the payload. If it's easier for you to include all of them, just pass null, as it's a valid value for every field type.

    When a field is not present in the payload, or its value is null, then the field's default value will be used (if available).

    Example code:
    const { SiteClient, buildModularBlock } = require("datocms-client");
    const client = new SiteClient("YOUR-API-TOKEN");
    const itemId = "4235";
    const blockModelId = "23455234";
    client.items
    .update(itemId, {
    content: [
    buildModularBlock({
    itemType: blockModelId,
    text: "new block record text",
    subtext: "another text",
    }), // new block record
    "565346546", // existing block record ID
    "565346547", // existing block record ID
    "565346548", // existing block record ID
    ],
    })
    .then((item) => {
    console.log(item);
    })
    .catch((error) => {
    console.error(error);
    });
    Returned output:
    > node example.js
    {
    "id": "4235",
    "title": "Title",
    "content": [ "565346549", "565346546", "565346547", "565346548" ], // "565346549" has been added
    "meta": { [...] },
    "itemType": "44",
    "creator": "312"
    }
    Remove a block record in a modular content field

    To delete a block record, remove its ID from the modular content field array.

    Example code:
    const SiteClient = require("datocms-client").SiteClient;
    const client = new SiteClient("YOUR-API-TOKEN");
    const itemId = "4235";
    client.items
    .update(itemId, {
    content: [
    "565346546", // existing block record ID
    "565346548", // existing block record ID
    ], // previous IDs were "565346546", "565346547", "565346548", we removed "565346547"
    })
    .then((item) => {
    console.log(item);
    })
    .catch((error) => {
    console.error(error);
    });
    Returned output:
    > node example.js
    {
    "id": "4235",
    "title": "Title",
    "content": [ "565346546", "565346548" ], // 565346547 has been removed
    "meta": { [...] },
    "itemType": "44",
    "creator": "312"
    }
    Add a locale

    If your model does not require all environment's locales to be present for all localized fields, then you can add a new locale to the record like so.

    Let's suppose your environment's locales are English (en), Italian (it) and German (de) and the following record currently defines en and it locales on its localized fields (title and content):

    {
    "id": "4235",
    "title": {
    "en": "My title",
    "it": "Il mio titolo"
    },
    "content": {
    "en": "Article content",
    "it": "Contenuto dell'articolo"
    },
    "votesCount": 10,
    "meta": {
    "created_at": "2020-04-21T07:57:11.124Z",
    "updated_at": "2020-04-21T07:57:11.124Z",
    "published_at": "2020-04-21T07:57:11.124Z",
    "first_published_at": "2020-04-21T07:57:11.124Z",
    "publication_scheduled_at": "2020-04-21T07:57:11.124Z",
    "unpublishing_scheduled_at": "2020-04-22T07:57:11.124Z",
    "status": "published",
    "is_valid": true,
    "current_version": "9994"
    },
    "itemType": "44",
    "creator": "312"
    }

    To add the German locale to this record, you have to send an update request containing all localized fields. For each one of these, you must define the exiting locales plus the ones you want to add. For example:

    Example code:
    const SiteClient = require("datocms-client").SiteClient;
    const client = new SiteClient("YOUR-API-TOKEN");
    const itemId = "4235";
    client.items
    .update(itemId, {
    title: {
    en: "My title",
    it: "Il mio titolo",
    de: "Mein Titel",
    },
    content: {
    en: "Article content",
    it: "Contenuto dell'articolo",
    de: "Artikelinhalt",
    },
    })
    .then((item) => {
    console.log(item);
    })
    .catch((error) => {
    console.error(error);
    });
    Returned output:
    > node example.js
    {
    "id": "4235",
    "title": {
    "en": "My title",
    "it": "Il mio titolo",
    "de": "Mein Titel",
    },
    "content": {
    "en": "Article content",
    "it": "Contenuto dell'articolo",
    "de": "Artikelinhalt",
    },
    "votesCount": 10,
    "meta": { [...] },
    "itemType": "44",
    "creator": "312"
    }
    Remove a locale

    If your model does not require all environment's locales to be present for all localized fields, then you can remove an exiting locale from a record like so.

    Let's suppose your environment's locales are English (en), Italian (it) and German (de) and the following record currently defines en and it locales on its localized fields (title and content):

    {
    "id": "4235",
    "title": {
    "en": "My title",
    "it": "Il mio titolo"
    },
    "content": {
    "en": "Article content",
    "it": "Contenuto dell'articolo"
    },
    "votesCount": 10,
    "meta": {
    "created_at": "2020-04-21T07:57:11.124Z",
    "updated_at": "2020-04-21T07:57:11.124Z",
    "published_at": "2020-04-21T07:57:11.124Z",
    "first_published_at": "2020-04-21T07:57:11.124Z",
    "publication_scheduled_at": "2020-04-21T07:57:11.124Z",
    "unpublishing_scheduled_at": "2020-04-22T07:57:11.124Z",
    "status": "published",
    "is_valid": true,
    "current_version": "9994"
    },
    "itemType": "44",
    "creator": "312"
    }

    To remove the Italian locale from this record, you have to send an update request containing all localized fields. For each one fo these, you must define the exiting locales, except the ones you want to remove. For example:

    Example code:
    const SiteClient = require("datocms-client").SiteClient;
    const client = new SiteClient("YOUR-API-TOKEN");
    const itemId = "4235";
    client.items
    .update(itemId, {
    title: {
    en: "My title",
    },
    content: {
    en: "Article content",
    },
    })
    .then((item) => {
    console.log(item);
    })
    .catch((error) => {
    console.error(error);
    });
    Returned output:
    > node example.js
    {
    "id": "4235",
    "title": {
    "en": "My title",
    },
    "content": {
    "en": "Article content",
    },
    "votesCount": 10,
    "meta": { [...] },
    "itemType": "44",
    "creator": "312"
    }