Before creating your first record, we strongly recommend reading the Introduction to Records guide. It covers fundamental concepts about field types, block manipulation, and localization that are essential for building a valid creation payload.

The payload required to create a new record is determined by the specific model it's based on and the fields it contains.

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

Field API key	Field type
`name`	Single-line string (`string`)
`breed`	Single-line string (`string`)
`description`	Multiple-paragraph text (`text`)
`age`	Integer (`integer`)

We can create a new dog record like this:

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  const record = await client.items.create({
8
    item_type: { type: "item_type", id: "1234" },
9
    name: "Buddy",
10
    breed: "Labrador",
11
    description: "Very friendly and calm.\nI love it.",
12
    age: 4,
13
  });
14

15
  console.log(record);
16
}
17
run();

1
const response = {
2
  type: "item",
3
  id: "4572128",
4
  name: "Buddy",
5
  breed: "Labrador",
6
  description: "Very friendly and calm.\nI love it.",
7
  age: 4,
8
  meta: {
9
    created_at: "2020-04-17T16:34:31.981+01:00",
10
    updated_at: "2020-04-17T16:34:32.005+01:00",
11
    published_at: "2020-04-17T16:34:32.004+01:00",
12
    first_published_at: "2020-04-17T16:34:32.004+01:00",
13
    publication_scheduled_at: null,
14
    unpublishing_scheduled_at: null,
15
    status: "published",
16
    is_valid: true,
17
    current_version: "8045084",
18
  },
19
  item_type: { type: "item_type", id: "1234" },
20
  creator: { type: "access_token", id: "322" },
21
};

When creating a record, you don't need to specify a value for every field. Any field you omit will be set to its configured default value, or null if no default is set.

While the Introduction to Records guide offers a complete reference for every field type, there are several key rules that are especially important when creating a new record.

Field value formatting

Every field in your payload must be formatted according to its type. This can range from a simple string or number to a structured object. For a comprehensive breakdown of the expected format for every field type, please refer to the Field Types Overview in our main records guide.

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

Field API key	Field type
`name`	Single-line string (`string`)
`breed`	Single-line string (`string`)
`description`	Multiple-paragraph text (`text`)
`age`	Integer (`integer`)
`height`	Float (`float`)
`date_of_birth`	Date-time (`date_time`)
`available`	Boolean (`boolean`)
`location`	Geo-location (`lat_lon`)
`color`	Color (`color`)
`other_stuff`	JSON (`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.

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  const record = await client.items.create({
8
    item_type: { type: "item_type", id: "1234" },
9
    name: "Buddy",
10
    breed: "Labrador",
11
    description: "Very friendly and calm.\nI love it.",
12
    age: 4,
13
    height: 50.5,
14
    date_of_birth: "2020-04-17T17:25:00",
15
    available: true,
16
    location: {
17
      latitude: 45.0703393,
18
      longitude: 7.686864,
19
    },
20
    color: {
21
      alpha: 255,
22
      blue: 156,
23
      green: 208,
24
      red: 239,
25
    },
26
    other_stuff: JSON.stringify({ foo: "bar", additionalData: "1234" }),
27
  });
28

29
  console.log(record);
30
}
31
run();

1
const response = {
2
  type: "item",
3
  id: "4572180",
4
  name: "Buddy",
5
  breed: "Labrador",
6
  description: "Very friendly and calm.\nI love it.",
7
  age: 4,
8
  height: 50.5,
9
  date_of_birth: "2020-04-17T17:25:00+01:00",
10
  available: true,
11
  location: { latitude: 45.0703393, longitude: 7.686864 },
12
  color: { red: 239, green: 208, blue: 156, alpha: 255 },
13
  other_stuff: '{\n  "foo": "bar",\n  "additionalData": "1234"\n}',
14
  meta: {
15
    created_at: "2020-04-17T16:58:27.488+01:00",
16
    updated_at: "2020-04-17T16:58:27.498+01:00",
17
    published_at: "2020-04-17T16:58:27.498+01:00",
18
    first_published_at: "2020-04-17T16:58:27.498+01:00",
19
    publication_scheduled_at: null,
20
    unpublishing_scheduled_at: null,
21
    status: "published",
22
    is_valid: true,
23
    is_current_version_valid: true,
24
    is_published_version_valid: true,
25
    current_version: "8045322",
26
  },
27
  item_type: { type: "item_type", id: "1234" },
28
  creator: { type: "access_token", id: "322" },
29
};

Block Fields

When creating a record, any new blocks (for Modular Content, Single Block, or Structured Text fields) must be provided as full block objects. This object must include the item_type in its relationships to specify which Block Model to use. You cannot create a record by providing only block IDs. For a deeper dive into manipulating blocks, see the guide on Creating and Updating Blocks.

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 key	Field type
`name`	Single-line string (`string`)
`description`	Modular 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 key Field type
name Single-line string (string)
year Integer (integer)
picture Single asset (upload)
A "Description" block model (ID: 1236, API key: description_block):

Field API key Field type
description Multi-paragraph text (text)
A "Carousel" block model (ID: 1237, API key: carousel_block):

Field API key Field type
carousel Asset gallery (gallery)

Field API key	Field type
`description`	Multi-paragraph text (`text`)

Field API key	Field type
`carousel`	Asset 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:

1
const { buildClient, buildBlockRecord } = require("datocms-client");
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  // upload file using a local file:
8
  const path = await client.createUploadPath("./2018-10-17-194326.jpg");
9

10
  // you can then use the returned path to create a new upload:
11
  const upload = await client.uploads.create({ path });
12

13
  const record = await client.items.create({
14
    item_type: { type: "item_type", id: "1234" },
15
    name: "Buddy",
16
    description: [
17
      // prize block
18
      buildBlockRecord({
19
        item_type: { type: "item_type", id: "1235" },
20
        name: "Best dog in the world",
21
        year: 2020,
22
        picture: { upload_id: upload.id },
23
      }),
24
      // description block
25
      buildBlockRecord({
26
        item_type: { type: "item_type", id: "1236" },
27
        description: "Very friendly and calm.\nI love it.",
28
      }),
29
      // carousel block
30
      buildBlockRecord({
31
        item_type: { type: "item_type", id: "1237" },
32
        carousel: [{ upload_id: upload.id }],
33
      }),
34
    ],
35
  });
36

37
  console.log(record);
38
}
39

40
run();

1
const resoinse = {
2
  type: "item",
3
  id: "4579897",
4
  name: "Buddy",
5
  description: ["4579894", "4579895", "4579896"],
6
  meta: {
7
    created_at: "2020-04-20T13:38:35.972+01:00",
8
    updated_at: "2020-04-20T13:38:36.005+01:00",
9
    published_at: "2020-04-20T13:38:36.004+01:00",
10
    first_published_at: "2020-04-20T13:38:36.004+01:00",
11
    publication_scheduled_at: null,
12
    unpublishing_scheduled_at: null,
13
    status: "published",
14
    is_valid: true,
15
    is_current_version_valid: true,
16
    is_published_version_valid: true,
17
    current_version: "8065211",
18
  },
19
  item_type: { type: "item_type", id: "1234" },
20
  creator: { type: "access_token", id: "322" },
21
};

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 key	Field type
`name`	Single-line string (`string`)
`description`	Structured 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 key Field type
name Single-line string (string)
year Integer (integer)
picture Single asset (upload)
A "Description" block model (ID: 1236, API key: description_block):

Field API key Field type
description Multi-paragraph text (text)
A "Carousel" block model (ID: 1237, API key: carousel_block):

Field API key Field type
carousel Asset gallery (gallery)

Field API key	Field type
`description`	Multi-paragraph text (`text`)

Field API key	Field type
`carousel`	Asset 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.

1
const { buildBlockRecord, buildBlockRecord } = require("datocms-client");
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  // create upload resource from URL (or return an existing upload if it's already present in the media area):
8

9
  const upload = await client.uploads.createFromUrl({
10
    url: "https://example.com/image.png",
11
    skipCreationIfAlreadyExists: true,
12
  });
13

14
  const record = await client.items.create({
15
    item_type: { type: "item_type", id: "1234" },
16
    name: "Buddy",
17
    description: {
18
      schema: "dast",
19
      document: {
20
        type: "root",
21
        children: [
22
          // simple header
23
          {
24
            type: "heading",
25
            level: 1,
26
            children: [
27
              {
28
                type: "span",
29
                marks: [],
30
                value: "Hello world!",
31
              },
32
            ],
33
          },
34
          // prize block
35
          {
36
            type: "block",
37
            item: buildBlockRecord({
38
              item_type: { type: "item_type", id: "1235" },
39
              name: "Best dog in the world",
40
              year: 2020,
41
              picture: { upload_id: upload.id },
42
            }),
43
          },
44
          // description block
45
          {
46
            type: "block",
47
            item: buildBlockRecord({
48
              item_type: { type: "item_type", id: "1236" },
49
              description: "Very friendly and calm.\nI love it.",
50
            }),
51
          },
52
          // gallery block
53
          {
54
            type: "block",
55
            item: buildBlockRecord({
56
              item_type: { type: "item_type", id: "1237" },
57
              carousel: [{ upload_id: upload.id }],
58
            }),
59
          },
60
        ],
61
      },
62
    },
63
  });
64

65
  console.log(record);
66
}
67

68
run();

1
const response = {
2
  type: "item",
3
  id: "4579897",
4
  name: "Buddy",
5
  description: {
6
    schema: "dast",
7
    document: {
8
      type: "root",
9
      children: [
10
        {
11
          type: "heading",
12
          level: 1,
13
          children: [{ type: "span", marks: [], value: "Hello world!" }],
14
        },
15
        { type: "block", item: "4579894" },
16
        { type: "block", item: "4579895" },
17
        { type: "block", item: "4579896" },
18
      ],
19
    },
20
  },
21
  meta: {
22
    created_at: "2020-04-20T13:38:35.972+01:00",
23
    updated_at: "2020-04-20T13:38:36.005+01:00",
24
    published_at: "2020-04-20T13:38:36.004+01:00",
25
    first_published_at: "2020-04-20T13:38:36.004+01:00",
26
    publication_scheduled_at: null,
27
    unpublishing_scheduled_at: null,
28
    status: "published",
29
    is_valid: true,
30
    is_current_version_valid: true,
31
    is_published_version_valid: true,
32
    current_version: "8065211",
33
  },
34
  item_type: { type: "item_type", id: "1234" },
35
  creator: { type: "access_token", id: "322" },
36
};

Asset & Link Fields

These reference fields require specific formats. For a comprehensive breakdown of the expected format for every field type, please refer to the Field Types Overview in our main records guide.

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

1
{
2
  upload_id: "1737955",
3
  alt: "Dog picture",
4
  title: "Buddy",
5
  focal_point: {
6
    x: 0.3,
7
    y: 0.2,
8
  },
9
  custom_data: {
10
    add_watermark: true,
11
  },
12
}

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 key	Field type
`name`	Single-line string (`string`)
`picture`	Single asset (`upload`)
`carousel`	Asset 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.

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  // create upload resource using URL (or return an existing upload if it's already present in the media area):
8
  const upload = await client.uploads.createFromUrl({
9
    url: "https://example.com/image.png",
10
    skipCreationIfAlreadyExists: true,
11
  });
12

13
  const record = await client.items.create({
14
    item_type: { type: "item_type", id: "1234" },
15
    name: "Buddy",
16
    picture: {
17
      // in this case we're just passing the upload ID, as the
18
      // upload resource's defaults for alt, title, etc. are fine:
19
      upload_id: upload.id,
20
    },
21
    carousel: [
22
      // here we want to override the upload resource's defaults:
23
      {
24
        upload_id: upload.id,
25
        alt: "Dog picture",
26
        title: "Buddy",
27
        focal_point: {
28
          x: 0.3,
29
          y: 0.2,
30
        },
31
        custom_data: {
32
          add_watermark: true,
33
        },
34
      },
35
    ],
36
  });
37

38
  console.log(record);
39
}
40

41
run();

1
const response = {
2
  type: "item",
3
  id: "4725799",
4
  name: "Buddy",
5
  picture: {
6
    upload_id: "1737955",
7
    alt: null,
8
    title: null,
9
    focal_point: null,
10
    custom_data: {},
11
  },
12
  carousel: [
13
    {
14
      upload_id: "1737955",
15
      alt: "Dog picture",
16
      title: "Buddy",
17
      focal_point: {
18
        x: 0.3,
19
        y: 0.2,
20
      },
21
      custom_data: {},
22
    },
23
  ],
24
  meta: {
25
    created_at: "2020-05-18T14:46:26.470+01:00",
26
    updated_at: "2020-05-18T14:46:26.484+01:00",
27
    published_at: "2020-05-18T14:46:26.483+01:00",
28
    first_published_at: "2020-05-18T14:46:26.483+01:00",
29
    publication_scheduled_at: null,
30
    unpublishing_scheduled_at: null,
31
    status: "published",
32
    is_valid: true,
33
    is_current_version_valid: true,
34
    is_published_version_valid: true,
35
    current_version: "8526589",
36
  },
37
  item_type: { type: "item_type", id: "1234" },
38
  creator: { type: "access_token", id: "322" },
39
};

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

Field API key	Field type
`name`	Single-line string (`string`)
`friends`	Multiple links field (`links`), referencing other `dog` records
`best_friend`	Single 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.

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  // Let's retrieve some other dogs first
8
  const friends = await client.items.list({ filter: { type: "dog" } });
9

10
  const record = await client.items.create({
11
    item_type: { type: "item_type", id: "1234" },
12
    name: "Buddy",
13
    friends: friends.map((f) => f.id),
14
    best_friend: friends[0].id,
15
  });
16

17
  console.log(record);
18
}
19

20
run();

1
const response = {
2
  type: "item",
3
  id: "4579273",
4
  name: "Buddy",
5
  friends: ["4572300", "4572298", "4572297", "4572180", "4572128"],
6
  best_friend: "4572300",
7
  meta: {
8
    created_at: "2020-04-20T11:06:29.126+01:00",
9
    updated_at: "2020-04-20T11:06:29.150+01:00",
10
    published_at: "2020-04-20T11:06:29.150+01:00",
11
    first_published_at: "2020-04-20T11:06:29.150+01:00",
12
    publication_scheduled_at: null,
13
    unpublishing_scheduled_at: null,
14
    status: "published",
15
    is_valid: true,
16
    is_current_version_valid: true,
17
    is_published_version_valid: true,
18
    current_version: "8062918",
19
  },
20
  item_type: { type: "item_type", id: "1234" },
21
  creator: { type: "access_token", id: "322" },
22
};

Localization

If the record's model contains localized fields, your creation payload must adhere to specific rules:

You must provide a value for every locale that is marked as required by the model's settings.
All localized fields in a single payload must specify the same set of locales to ensure consistency.

Unlike record updates where you can send a subset of locales, the creation endpoint is stricter about enforcing required locales. For a full explanation of how to structure localized data, refer to the Localization Guide.

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.

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  const record = await client.items.create({
8
    item_type: { type: "item_type", id: "1234" },
9
    name: {
10
      it: "Asso",
11
    },
12
    age: {
13
      it: 12,
14
    },
15
  });
16

17
  console.log(record);
18
}
19

20
run();

1
const response = {
2
  type: "item",
3
  id: "4668524",
4
  name: {
5
    it: "Asso",
6
  },
7
  age: {
8
    it: 12,
9
  },
10
  meta: {
11
    created_at: "2020-05-06T13:11:27.442+01:00",
12
    updated_at: "2020-05-06T13:11:27.483+01:00",
13
    published_at: "2020-05-06T13:11:27.482+01:00",
14
    first_published_at: "2020-05-06T13:11:27.482+01:00",
15
    publication_scheduled_at: null,
16
    unpublishing_scheduled_at: null,
17
    status: "published",
18
    is_valid: true,
19
    is_current_version_valid: true,
20
    is_published_version_valid: true,
21
    current_version: "8329850",
22
  },
23
  item_type: { type: "item_type", id: "1234" },
24
  creator: { type: "access_token", id: "322" },
25
};

Body parameters

id string Optional

RFC 4122 UUID of record expressed in URL-safe base64 format

Example:

"hWl-mnkWRYmMCSTq4z_piQ"

meta.created_at string Optional

Date of creation

meta.first_published_at null, string Optional

Date of first publication

item_type Required

The record's model

Type: ResourceLinkage<"item_type">

creator Optional

The entity (account/collaborator/access token/sso user) who created the record

Type: ResourceLinkage<"account">, ResourceLinkage<"access_token">, ResourceLinkage<"user">, ResourceLinkage<"sso_user">, ResourceLinkage<"organization">

Returns

Returns a resource object of type item

Other examples

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 key	Localized	Field 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:

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  const record = await client.items.create({
8
    item_type: { type: "item_type", id: "1234" },
9
    name: {
10
      en: "Alfie",
11
      it: "Asso",
12
    },
13
    age: {
14
      en: 30,
15
      it: 12,
16
    },
17
  });
18

19
  console.log(record);
20
}
21

22
run();

1
const response = {
2
  type: "item",
3
  id: "4668524",
4
  name: {
5
    en: "Alfie",
6
    it: "Asso",
7
  },
8
  age: {
9
    en: 30,
10
    it: 12,
11
  },
12
  meta: {
13
    created_at: "2020-05-06T13:11:27.442+01:00",
14
    updated_at: "2020-05-06T13:11:27.483+01:00",
15
    published_at: "2020-05-06T13:11:27.482+01:00",
16
    first_published_at: "2020-05-06T13:11:27.482+01:00",
17
    publication_scheduled_at: null,
18
    unpublishing_scheduled_at: null,
19
    status: "published",
20
    is_valid: true,
21
    is_current_version_valid: true,
22
    is_published_version_valid: true,
23
    current_version: "8329850",
24
  },
25
  item_type: { type: "item_type", id: "1234" },
26
  creator: { type: "access_token", id: "322" },
27
};

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 key	Localized	Field 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:

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  const parent = await client.items.create({
8
    item_type: { type: "item_type", id: "1234" },
9
    name: "Parent",
10
  });
11

12
  console.log(parent);
13

14
  const child1 = await client.items.create({
15
    item_type: { type: "item_type", id: "1234" },
16
    name: "Child 1",
17
    parent_id: parent.id,
18
    position: 1,
19
  });
20

21
  console.log(child1);
22

23
  const child2 = await client.items.create({
24
    item_type: { type: "item_type", id: "1234" },
25
    name: "Child 2",
26
    parent_id: parent.id,
27
    position: 2,
28
  });
29

30
  console.log(child2);
31
}
32

33
run();

1
const parent = {
2
  type: "item",
3
  id: "4679744",
4
  name: "Parent",
5
  parent_id: null,
6
  position: 1,
7
  // ...
8
};
9

10
const child1 = {
11
  type: "item",
12
  id: "4679745",
13
  name: "Child 2",
14
  parent_id: "4679744",
15
  position: 1,
16
  // ...
17
};
18

19
const child2 = {
20
  type: "item",
21
  id: "4679746",
22
  name: "Child 1",
23
  parent_id: "4679744",
24
  position: 2,
25
  // ...
26
};

Did this doc help you?

Need help?

Explore our forum, contact support, or connect with our sales team . You can also chat live with other users in our Slack channel.

Field API key	Field type
`name`	Single-line string (`string`)
`year`	Integer (`integer`)
`picture`	Single asset (`upload`)