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.

    The main difference is that when updating you can pass just the fields you want to change, and not all of them.

    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.

    Parameters
    meta.createdAt  date-time  Optional

    Date of creation

    meta.updatedAt  date-time  Optional

    Last update time

    meta.publishedAt  null, date-time  Optional

    Date of last publication

    meta.firstPublishedAt  null, date-time  Optional

    Date of first publication

    meta.publicationScheduledAt  null, date-time  Optional

    Date of future publication

    meta.status  null, enum  Optional

    Status

    meta.isValid  boolean  Optional

    Whether the current record is valid or not

    meta.currentVersion  string  Optional

    The ID of the current record version

    creator  account.id, access_token.id, 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",
    "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!