Home
Content Management API⁡𝅶‍‍𝅺⁡‍𝅴⁡𝅴𝅹‍‍⁢𝅵‍‍⁣⁣‌⁡⁣𝅺⁣⁢⁣𝅸⁠⁢‍‍‍𝅷‍‍𝅳⁡‍⁠‍‍⁢𝅵‍‍𝅳⁡⁣⁡⁣⁡​⁡⁢⁢𝅵‍𝅺‍𝅺⁢𝅸⁡⁢‍𝅹⁣‌⁡⁣𝅺⁢𝅸⁡⁢‍𝅹⁢𝅺𝅸‍𝅺⁠⁣𝅴⁡⁣𝅺⁡‍‍𝅺𝅴⁡⁣⁠𝅸⁠𝅺⁡⁣⁡𝅴⁡​⁠⁡⁢‍𝅺⁢𝅳⁢‌⁢​⁢𝅴⁢‍⁢⁠‍𝅺𝅴⁡⁣⁠𝅸⁡⁢‍𝅺⁢⁢⁢𝅴⁢𝅳⁢⁢⁢‌⁢⁡⁢𝅳⁢‌‍‍⁡𝅸
Main resources
Upload-related
Site Search
Environments
UI
Workflows
Async jobs
Roles & permissions
Webhooks
Hosting & CI integrations
Subscription
Enterprise
    Show examples in:
    Create a new record

    The payload to pass to create a new record always depends on the specific settings of its model and the fields it declares.

    When creating a new record, you don't need to specify a value for every field of it's model, as the ones you don't specify will be set to the field's default value (if available), or null (which is a valid value for every type of field).

    Different values for different field types

    If you do want to provide an explicit value for a field, then each type of field requires a different type of value. Most of the field types require scalar values — ie. a Single-line string requires a string, an Integer field requires a number, etc:

    {
      // If the model has a `title` single-line string field...
      "name": "Alfie",
      // If the model has an `age` integer field...
      "age": 4
      // And so on :)
    }

    Some other fields, like Geo-location or Color fields, require objects instead of simple data types:

    {
      // If the model has a `location` field of type 'Geo-location'...
      "location": { "latitude": 45.0703393, "longitude": 7.686864 },
      // If the model has an `accent_color` field of type 'Color'...
      "accent_color": { "red": 239, "green": 208, "blue": 156, "alpha": 255 }
    }

    We'll analyze in detail every different type of field that DatoCMS offers in the following sections.

    Localized fields

    Fields can be localized. If that's the case, records need to express a value for multiple locales using an object, whose keys represent the locale itself:

    {
      // If the model has a `title` single-line string field...
      "name": {
        "en": "Alfie",
        "it": "Asso"
      },
      // If the model has an `color` field...
      "age": {
        "en": { "red": 255, "green": 0, "blue": 0, "alpha": 255 },
        "it": { "red": 0, "green": 255, "blue": 0, "alpha": 255 }
      }
      // And so on :)
    }

    If your model has the "All locales required?" option turned on, then you have to express a field value for all environment's locales. Otherwise, you can just define a subset of them (as long as all localized fields express the exact same subset!):

    {
      // Even if the environment has many locales, since the model has the "All locales required?" option
      // turned off, we can define only the Italian locale:
      "name": {
        "it": "Asso"
      },
      "age": {
        "it": { "red": 0, "green": 255, "blue": 0, "alpha": 255 }
      }
    }

    Field type values

    Single-line string

    The field accepts String values.

    Multi-line text

    The field accepts simple String values.

    Boolean

    The field accepts simple Boolean values.

    Integer

    The field accepts simple Integer values.

    Float

    The field accepts simple Float values.

    Date

    The field accepts String values in ISO 8601 date format (ie. "2015-12-29").

    Date time

    The field accepts String values in ISO 8601 date-time format (ie. "2020-04-17T16:34:31.981+01:00").

    If you're on legacy timezone management, remember that when sending an ISO8601 datetime you should keep in mind that the system will ignore any provided timezone, and will use the project's timezone instead.

    Color

    The field accepts an object with the following properties:

    PropertyRequiredType
    red✅Integer between 0 and 255
    green✅Integer between 0 and 255
    blue✅Integer between 0 and 255
    alpha✅Integer between 0 and 255
    JSON

    The field accepts String values that are valid JSON.

    Location

    The field accepts an object with the following properties:

    PropertyRequiredType
    latitude✅Float between -90.0 to 90
    longitude✅Float between -180.0 to 180
    SEO

    The field accepts an object with the following properties:

    PropertyRequiredTypeDescription
    titleStringTitle meta tag (max. 320 characters)
    descriptionStringDescription meta tag (max. 320 characters)
    imageUpload IDAsset to be used for social shares
    twitter_card"summary", "summary_large_image"Type of Twitter card to use
    Slug

    The field accepts String values that satisfy the following regular expression: /^[a-z0-9_]+(?:\-[a-z0-9]+)*$/.

    External video

    The field accepts an object with the following properties:

    PropertyRequiredTypeDescriptionExample
    provider✅"youtube", "vimeo", "facebook"External video provider"youtube"
    provider_uid✅StringUnique identifier of the video within the provider"vUdGBEb1i9g"
    url✅URLURL of the video"https://www.youtube.com/watch?v=qJhobECFQYk"
    width✅IntegerVideo width459
    height✅IntegerVideo height344
    thumbnail_url✅URLURL for the video thumb"https://i.ytimg.com/vi/vUdGBEb1i9g/hqdefault.jpg"
    title✅StringTitle of the video"Next.js Conf Booth Welcoming!"
    Single-asset

    The field accepts an object with the following properties:

    PropertyRequiredTypeDescriptionExample
    upload_id✅Upload IDID of an asset"3429022"
    titleStringTitle for the asset, if you want to override the asset's default value (see Upload default_field_metadata)"From my trip to Italy"
    altStringAlternate text for the asset, if you want to override the asset's default value (see Upload default_field_metadata)"Florence skyline"
    focal_point{ x: Float, y: Float }, nullFocal point for the asset, if you want to override the asset's default value (see Upload default_field_metadata). Values must be expressed as Float between 0 and 1. Focal point can only be specified for image assets.{ "x": 0.34, "y": 0.45 }
    custom_dataRecord<String, String>An object containing custom keys that you can use on your frontend projects{ "watermark_image": "true" }
    Asset gallery

    This field accepts an Array of objects with the following properties:

    PropertyRequiredTypeDescriptionExample
    upload_id✅Upload IDID of an asset"3429022"
    titleStringTitle for the asset, if you want to override the asset's default value (see Upload default_field_metadata)"https://www.youtube.com/watch?v=vUdGBEb1i9g"
    altStringAlternate text for the asset, if you want to override the asset's default value (see Upload default_field_metadata)"vUdGBEb1i9g"
    focal_point{ x: Float, y: Float }, nullFocal point for the asset, if you want to override the asset's default value (see Upload default_field_metadata). Values must be expressed as Float between 0 and 1. Focal point can only be specified for image assets.{ "x": 0.34, "y": 0.45 }
    custom_dataRecord<String, String>An object containing custom keys that you can use on your frontend projects{ "watermark_image": "true" }
    Single link

    This field accepts a String representing the ID of the linked record.

    Multiple links

    This field accepts an Array<String> representing the IDs of the linked records.

    Modular content

    When a record is being read, this field returns an Array<String> representing the IDs of the inner block records.

    When a record is being created, this field must contain an Array of objects representing the inner block records:

    Example:

    [
      {
        "type": "item",
        "attributes": {
          // ... put your fields values here
        },
        "relationships": {
          "item_type": {
            "data": {
              // the block model
              "id": "435822",
              "type": "item_type",
            }
          }
        },
      },
      // ...
    ]

    When a record is being updated, make sure to include the ID of the already existing block records, or if the block is not subject to any change, just pass its ID:

    [
      // we don't need to change anything to these two blocks, just pass their IDs:
      "9862635",
      "9862636",
      // we want to change some field values for this block!
      {
        "id": "9862637",
        "type": "item",
        "attributes": {
          // ... put the block fields to be changed here
        },
        "relationships": {
          "item_type": {
            "data": {
              // the block model
              "id": "435822",
              "type": "item_type",
            }
          }
        },
      },
    ]
    Structured text

    This field accepts a Structured Text document.

    When a record is being created, the item attribute of block nodes must be the entire block record instead of the ID:

    Example:

    {
      "schema": "dast",
      "document": {
        "type": "root",
        "children": [
          {
            "type": "block",
            "item": {
              "type": "item",
              "attributes": {
                // ... put your fields values here
              },
              "relationships": {
                "item_type": {
                  "data": {
                    // the block model
                    "id": "435822",
                    "type": "item_type",
                  }
                }
              },
            }
          }
        ]
      },
    }

    When a record is being updated, make sure to include the ID of the already existing block records, or if the block is not subject to any change, just pass its ID:

    {
      "schema": "dast",
      "document": {
        "type": "root",
        "children": [
          {
            "type": "block",
            // this block is not subject to any change, just pass its ID
            "item": "34823428"
          },
          {
            "type": "block",
            // we want to change some field values for this block!
            "item": {
              "id": "34823424",
              "type": "item",
              "attributes": {
                // ... put the block fields to be changed here
              },
              "relationships": {
                "item_type": {
                  "data": {
                    // the block model
                    "id": "435822",
                    "type": "item_type",
                  }
                }
              }
            }
          }
        ]
      }
    }

    Parameters

    meta.created_at  string  Optional

    Date of creation

    meta.first_published_at  null, string  Optional

    Date of first publication

    item_type  { type: "item_type", id: item_type.id }  Required

    The record's model

    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 }, { type: "organization", id: organization.id }  Optional

    The entity (account/collaborator/access token/sso user) who created the record. It must be an object with type (e.g. 'account') and id properties.

    Returns

    Returns a item resource object.

    Examples

    The following examples are available:

    Basic example

    Suppose our project contains a "Dog" model (ID: 1234, API key: dog) with the following fields:

    Field API keyField type
    nameSingle-line string (string)
    breedSingle-line string (string)
    descriptionMultiple-paragraph text (text)
    ageInteger (integer)

    We can create a new dog record like this:

    Example code:
    import { buildClient } from '@datocms/cma-client-node';
    async function run() {
      const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
      const record = await client.items.create({
        item_type: { type: 'item_type', id: '1234' },
        name: 'Buddy',
        breed: 'Labrador',
        description: 'Very friendly and calm.\nI love it.',
        age: 4,
      });
      console.log(record);
    }
    run();
    Returned output:
    const response = {
      type: 'item',
      id: '4572128',
      name: 'Buddy',
      breed: 'Labrador',
      description: 'Very friendly and calm.\nI love it.',
      age: 4,
      meta: {
        created_at: '2020-04-17T16:34:31.981+01:00',
        updated_at: '2020-04-17T16:34:32.005+01:00',
        published_at: '2020-04-17T16:34:32.004+01:00',
        first_published_at: '2020-04-17T16:34:32.004+01:00',
        publication_scheduled_at: null,
        unpublishing_scheduled_at: null,
        status: 'published',
        is_valid: true,
        current_version: '8045084',
      },
      item_type: { type: 'item_type', id: '1234' },
      creator: { type: 'access_token', id: '322' },
    };
    All the simple fields

    Suppose our project contains a "Dog" model (ID: 1234, API key: dog) with the following fields:

    Field API keyField type
    nameSingle-line string (string)
    breedSingle-line string (string)
    descriptionMultiple-paragraph text (text)
    ageInteger (integer)
    heightFloat (float)
    date_of_birthDate-time (date_time)
    availableBoolean (boolean)
    locationGeo-location (lat_lon)
    colorColor (color)
    other_stuffJSON (json)

    A couple of gotchas when writing our call to client.items.create():

    • Geo-location and Color fields require an object with all their properties specified;
    • The JSON field must be a JSON-serialized string, and not an object.

    You can read all the details about the value that each specific type of field requires in the Field type values section.

    Example code:
    import { buildClient } from '@datocms/cma-client-node';
    async function run() {
      const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
      const record = await client.items.create({
        item_type: { type: 'item_type', id: '1234' },
        name: 'Buddy',
        breed: 'Labrador',
        description: 'Very friendly and calm.\nI love it.',
        age: 4,
        height: 50.5,
        date_of_birth: '2020-04-17T17:25:00',
        available: true,
        location: {
          latitude: 45.0703393,
          longitude: 7.686864,
        },
        color: {
          alpha: 255,
          blue: 156,
          green: 208,
          red: 239,
        },
        other_stuff: JSON.stringify({ foo: 'bar', additionalData: '1234' }),
      });
      console.log(record);
    }
    run();
    Returned output:
    const response = {
      type: 'item',
      id: '4572180',
      name: 'Buddy',
      breed: 'Labrador',
      description: 'Very friendly and calm.\nI love it.',
      age: 4,
      height: 50.5,
      date_of_birth: '2020-04-17T17:25:00+01:00',
      available: true,
      location: { latitude: 45.0703393, longitude: 7.686864 },
      color: { red: 239, green: 208, blue: 156, alpha: 255 },
      other_stuff: '{\n  "foo": "bar",\n  "additionalData": "1234"\n}',
      meta: {
        created_at: '2020-04-17T16:58:27.488+01:00',
        updated_at: '2020-04-17T16:58:27.498+01:00',
        published_at: '2020-04-17T16:58:27.498+01:00',
        first_published_at: '2020-04-17T16:58:27.498+01:00',
        publication_scheduled_at: null,
        unpublishing_scheduled_at: null,
        status: 'published',
        is_valid: true,
        is_current_version_valid: true,
        is_published_version_valid: true,
        current_version: '8045322',
      },
      item_type: { type: 'item_type', id: '1234' },
      creator: { type: 'access_token', id: '322' },
    };
    Adding pictures to records

    As discussed in the Field type values section, a Single asset (upload) type of field requires an object in the following form:

    {
      upload_id: "1737955",
      alt: "Dog picture",
      title: "Buddy",
      focal_point: {
        x: 0.3,
        y: 0.2,
      },
      custom_data: {
        add_watermark: true,
      },
    }

    While the Asset gallery field (gallery) requires an array of object with the same format.

    All the keys except upload_id are optional and can be omitted.

    Suppose our project contains a "Dog" model (ID: 1234, API key: dog) with the following fields:

    Field API keyField type
    nameSingle-line string (string)
    pictureSingle asset (upload)
    carouselAsset gallery (gallery)

    To fill in the upload_id property of both fields, we could either reference an already-existing asset, or create a brand new Upload resource. In the following example we're using the client.uploads.createFromUrl() method to create a new upload resource — you can see all the alternative upload creation methods in the Create a new upload endpoint documentation.

    Example code:
    import { buildClient } from '@datocms/cma-client-node';
    async function run() {
      const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
      // create upload resource using URL (or return an existing upload if it's already present in the media area):
      const upload = await client.uploads.createFromUrl({
        url: 'https://example.com/image.png',
        skipCreationIfAlreadyExists: true,
      });
      const record = await client.items.create({
        item_type: { type: 'item_type', id: '1234' },
        name: 'Buddy',
        picture: {
          // in this case we're just passing the upload ID, as the
          // upload resource's defaults for alt, title, etc. are fine:
          upload_id: upload.id,
        },
        carousel: [
          // here we want to override the upload resource's defaults:
          {
            upload_id: upload.id,
            alt: 'Dog picture',
            title: 'Buddy',
            focal_point: {
              x: 0.3,
              y: 0.2,
            },
            custom_data: {
              add_watermark: true,
            },
          },
        ],
      });
      console.log(record);
    }
    run();
    Returned output:
    const response = {
      type: 'item',
      id: '4725799',
      name: 'Buddy',
      picture: {
        upload_id: '1737955',
        alt: null,
        title: null,
        focal_point: null,
        custom_data: {},
      },
      carousel: [
        {
          upload_id: '1737955',
          alt: 'Dog picture',
          title: 'Buddy',
          focal_point: {
            x: 0.3,
            y: 0.2,
          },
          custom_data: {},
        },
      ],
      meta: {
        created_at: '2020-05-18T14:46:26.470+01:00',
        updated_at: '2020-05-18T14:46:26.484+01:00',
        published_at: '2020-05-18T14:46:26.483+01:00',
        first_published_at: '2020-05-18T14:46:26.483+01:00',
        publication_scheduled_at: null,
        unpublishing_scheduled_at: null,
        status: 'published',
        is_valid: true,
        is_current_version_valid: true,
        is_published_version_valid: true,
        current_version: '8526589',
      },
      item_type: { type: 'item_type', id: '1234' },
      creator: { type: 'access_token', id: '322' },
    };
    Links to other records

    Suppose our project contains a "Dog" model (ID: 1234, API key: dog) with the following fields:

    Field API keyField type
    nameSingle-line string (string)
    friendsMultiple links field (links), referencing other dog records
    best_friendSingle link field (link), referencing other dog records

    In the example we first retrieve some records and then we create a new record which references them. To keep the example short, our links point to other dog records, so that we don't need other models.

    Example code:
    import { buildClient } from '@datocms/cma-client-node';
    async function run() {
      const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
      // Let's retrieve some other dogs first
      const friends = await client.items.list({ filter: { type: 'dog' } });
      const record = await client.items.create({
        item_type: { type: 'item_type', id: '1234' },
        name: 'Buddy',
        friends: friends.map((f) => f.id),
        best_friend: friends[0].id,
      });
      console.log(record);
    }
    run();
    Returned output:
    const response = {
      type: 'item',
      id: '4579273',
      name: 'Buddy',
      friends: ['4572300', '4572298', '4572297', '4572180', '4572128'],
      best_friend: '4572300',
      meta: {
        created_at: '2020-04-20T11:06:29.126+01:00',
        updated_at: '2020-04-20T11:06:29.150+01:00',
        published_at: '2020-04-20T11:06:29.150+01:00',
        first_published_at: '2020-04-20T11:06:29.150+01:00',
        publication_scheduled_at: null,
        unpublishing_scheduled_at: null,
        status: 'published',
        is_valid: true,
        is_current_version_valid: true,
        is_published_version_valid: true,
        current_version: '8062918',
      },
      item_type: { type: 'item_type', id: '1234' },
      creator: { type: 'access_token', id: '322' },
    };
    Modular content fields

    To make our dog's description more dynamic we are going to add a Modular content field. This will allow us to compose the description by combining multiple blocks of different kind. Each block model will have its set of fields and can be repeated as many times as needed.

    This is our "Dog" model (ID: 1234, API key: dog):

    Field API keyField type
    nameSingle-line string (string)
    descriptionModular content (rich_text)

    The modular content field accepts three different types of blocks:

    • A "Prize" block model (ID: 1235, API key: prize_block):

      Field API keyField type
      nameSingle-line string (string)
      yearInteger (integer)
      pictureSingle asset (upload)

    • A "Description" block model (ID: 1236, API key: description_block):

      Field API keyField type
      descriptionMulti-paragraph text (text)

    • A "Carousel" block model (ID: 1237, API key: carousel_block):

      Field API keyField type
      carouselAsset gallery (gallery)

    In this example we'll use the buildBlockRecord() function to help us creating blocks more easily. You just need to specify the block model ID and all the fields, like a normal record:

    Example code:
    const { buildClient, buildBlockRecord } = require('datocms-client');
    async function run() {
      const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
      // upload file using a local file:
      const path = await client.createUploadPath('./2018-10-17-194326.jpg');
      // you can then use the returned path to create a new upload:
      const upload = await client.uploads.create({ path });
      const record = await client.items.create({
        item_type: { type: 'item_type', id: '1234' },
        name: 'Buddy',
        description: [
          // prize block
          buildBlockRecord({
            item_type: { type: 'item_type', id: '1235' },
            name: 'Best dog in the world',
            year: 2020,
            picture: { upload_id: upload.id },
          }),
          // description block
          buildBlockRecord({
            item_type: { type: 'item_type', id: '1236' },
            description: 'Very friendly and calm.\nI love it.',
          }),
          // carousel block
          buildBlockRecord({
            item_type: { type: 'item_type', id: '1237' },
            carousel: [{ upload_id: upload.id }],
          }),
        ],
      });
      console.log(record);
    }
    run();
    Returned output:
    const resoinse = {
      type: 'item',
      id: '4579897',
      name: 'Buddy',
      description: ['4579894', '4579895', '4579896'],
      meta: {
        created_at: '2020-04-20T13:38:35.972+01:00',
        updated_at: '2020-04-20T13:38:36.005+01:00',
        published_at: '2020-04-20T13:38:36.004+01:00',
        first_published_at: '2020-04-20T13:38:36.004+01:00',
        publication_scheduled_at: null,
        unpublishing_scheduled_at: null,
        status: 'published',
        is_valid: true,
        is_current_version_valid: true,
        is_published_version_valid: true,
        current_version: '8065211',
      },
      item_type: { type: 'item_type', id: '1234' },
      creator: { type: 'access_token', id: '322' },
    };
    Structured text fields

    To make our dog's description more dynamic we are going to add a Structured text field. This will allow us to compose the description by combining text and blocks of different kind.

    This is our "Dog" model (ID: 1234, API key: dog):

    Field API keyField type
    nameSingle-line string (string)
    descriptionStructured text (structured_text)

    The structured text field accepts three different types of blocks:

    • A "Prize" block model (ID: 1235, API key: prize_block):

      Field API keyField type
      nameSingle-line string (string)
      yearInteger (integer)
      pictureSingle asset (upload)

    • A "Description" block model (ID: 1236, API key: description_block):

      Field API keyField type
      descriptionMulti-paragraph text (text)

    • A "Carousel" block model (ID: 1237, API key: carousel_block):

      Field API keyField type
      carouselAsset gallery (gallery)

    In this example we'll use the buildBlockRecord() function to help us creating blocks more easily. You need to specify the block model ID and all the fields, just like a normal record. We'll also use the client.uploads.createFromUrl() method to create new upload resources — you can see all the alternative upload creation methods in the Create a new upload endpoint documentation.

    Example code:
    const { buildBlockRecord, buildBlockRecord } = require('datocms-client');
    async function run() {
      const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
      // create upload resource from URL (or return an existing upload if it's already present in the media area):
      const upload = await client.uploads.createFromUrl({
        url: 'https://example.com/image.png',
        skipCreationIfAlreadyExists: true,
      });
      const record = await client.items.create({
        item_type: { type: 'item_type', id: '1234' },
        name: 'Buddy',
        description: {
          schema: 'dast',
          document: {
            type: 'root',
            children: [
              // simple header
              {
                type: 'heading',
                level: 1,
                children: [
                  {
                    type: 'span',
                    marks: [],
                    value: 'Hello world!',
                  },
                ],
              },
              // prize block
              {
                type: 'block',
                item: buildBlockRecord({
                  item_type: { type: 'item_type', id: '1235' },
                  name: 'Best dog in the world',
                  year: 2020,
                  picture: { upload_id: upload.id },
                }),
              },
              // description block
              {
                type: 'block',
                item: buildBlockRecord({
                  item_type: { type: 'item_type', id: '1236' },
                  description: 'Very friendly and calm.\nI love it.',
                }),
              },
              // gallery block
              {
                type: 'block',
                item: buildBlockRecord({
                  item_type: { type: 'item_type', id: '1237' },
                  carousel: [{ upload_id: upload.id }],
                }),
              },
            ],
          },
        },
      });
      console.log(record);
    }
    run();
    Returned output:
    const response = {
      type: 'item',
      id: '4579897',
      name: 'Buddy',
      description: {
        schema: 'dast',
        document: {
          type: 'root',
          children: [
            {
              type: 'heading',
              level: 1,
              children: [{ type: 'span', marks: [], value: 'Hello world!' }],
            },
            { type: 'block', item: '4579894' },
            { type: 'block', item: '4579895' },
            { type: 'block', item: '4579896' },
          ],
        },
      },
      meta: {
        created_at: '2020-04-20T13:38:35.972+01:00',
        updated_at: '2020-04-20T13:38:36.005+01:00',
        published_at: '2020-04-20T13:38:36.004+01:00',
        first_published_at: '2020-04-20T13:38:36.004+01:00',
        publication_scheduled_at: null,
        unpublishing_scheduled_at: null,
        status: 'published',
        is_valid: true,
        is_current_version_valid: true,
        is_published_version_valid: true,
        current_version: '8065211',
      },
      item_type: { type: 'item_type', id: '1234' },
      creator: { type: 'access_token', id: '322' },
    };
    Localising content

    Suppose our project primary environment is set up to have two different locales ("en" and "it"), and contains a "Dog" model (ID: 1234, API key: dog) with the following fields:

    Field API keyLocalizedField type
    name✅Single-line string (string)
    age✅Integer (integer)

    On localized fields, records express a value for multiple locales using an object, whose keys represent the locale itself:

    Example code:
    import { buildClient } from '@datocms/cma-client-node';
    async function run() {
      const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
      const record = await client.items.create({
        item_type: { type: 'item_type', id: '1234' },
        name: {
          en: 'Alfie',
          it: 'Asso',
        },
        age: {
          en: 30,
          it: 12,
        },
      });
      console.log(record);
    }
    run();
    Returned output:
    const response = {
      type: 'item',
      id: '4668524',
      name: {
        en: 'Alfie',
        it: 'Asso',
      },
      age: {
        en: 30,
        it: 12,
      },
      meta: {
        created_at: '2020-05-06T13:11:27.442+01:00',
        updated_at: '2020-05-06T13:11:27.483+01:00',
        published_at: '2020-05-06T13:11:27.482+01:00',
        first_published_at: '2020-05-06T13:11:27.482+01:00',
        publication_scheduled_at: null,
        unpublishing_scheduled_at: null,
        status: 'published',
        is_valid: true,
        is_current_version_valid: true,
        is_published_version_valid: true,
        current_version: '8329850',
      },
      item_type: { type: 'item_type', id: '1234' },
      creator: { type: 'access_token', id: '322' },
    };
    Localising content with some locales only

    If your model does not require all environment's locales to be present (that is the "All locales required?" option is turned off), then you can create a record defining only a subset of the environment's locales. For example:

    Example code:
    import { buildClient } from '@datocms/cma-client-node';
    async function run() {
      const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
      const record = await client.items.create({
        item_type: { type: 'item_type', id: '1234' },
        name: {
          it: 'Asso',
        },
        age: {
          it: 12,
        },
      });
      console.log(record);
    }
    run();
    Returned output:
    const response = {
      type: 'item',
      id: '4668524',
      name: {
        it: 'Asso',
      },
      age: {
        it: 12,
      },
      meta: {
        created_at: '2020-05-06T13:11:27.442+01:00',
        updated_at: '2020-05-06T13:11:27.483+01:00',
        published_at: '2020-05-06T13:11:27.482+01:00',
        first_published_at: '2020-05-06T13:11:27.482+01:00',
        publication_scheduled_at: null,
        unpublishing_scheduled_at: null,
        status: 'published',
        is_valid: true,
        is_current_version_valid: true,
        is_published_version_valid: true,
        current_version: '8329850',
      },
      item_type: { type: 'item_type', id: '1234' },
      creator: { type: 'access_token', id: '322' },
    };
    Tree-like structure

    Suppose our project contains a "Menu Item" model (ID: 1234, API key: menu_item) that is configured to be organized as a tree, and has a single field:

    Field API keyLocalizedField type
    name✅Single-line string (string)

    In this example we'll create a hierarchy of three records.

    In tree-like collections, records can specify two additional fields, parent_id and position, so that they can express who is their parent record, and which is their position relative to its siblings:

    Example code:
    import { buildClient } from '@datocms/cma-client-node';
    async function run() {
      const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
      const parent = await client.items.create({
        item_type: { type: 'item_type', id: '1234' },
        name: 'Parent',
      });
      console.log(parent);
      const child1 = await client.items.create({
        item_type: { type: 'item_type', id: '1234' },
        name: 'Child 1',
        parent_id: parent.id,
        position: 1,
      });
      console.log(child1);
      const child2 = await client.items.create({
        item_type: { type: 'item_type', id: '1234' },
        name: 'Child 2',
        parent_id: parent.id,
        position: 2,
      });
      console.log(child2);
    }
    run();
    Returned output:
    const parent = {
      type: 'item',
      id: '4679744',
      name: 'Parent',
      parent_id: null,
      position: 1,
      // ...
    };
    const child1 = {
      type: 'item',
      id: '4679745',
      name: 'Child 2',
      parent_id: '4679744',
      position: 1,
      // ...
    };
    const child2 = {
      type: 'item',
      id: '4679746',
      name: 'Child 1',
      parent_id: '4679744',
      position: 2,
      // ...
    };
    Questions?
    We're always happy to help with code or other questions you might have. Search our documentation, forum, contact support, or connect with our sales team. You can chat live with other developers in our Slack channel.