Content Management API > Record

Create a new record

📚 New to DatoCMS records?

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.

This example demonstrates the basic process of creating a new record using the DatoCMS Content Management API. The example shows how to specify the item type and provide values for the record's fields.

1
import {
2
  buildClient,
3
  inspectItem,
4
  type ItemTypeDefinition,
5
} from "@datocms/cma-client-node";
6

7
type EnvironmentSettings = { locales: "en" };
8

9
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
10

11
type Book = ItemTypeDefinition<
12
  EnvironmentSettings,
13
  "UZyfjdBES8y2W2ruMEHSoA",
14
  {
15
    title: { type: "string" };
16
    genre: { type: "string" };
17
    synopsis: { type: "text" };
18
    pages: { type: "integer" };
19
  }
20
>;
21

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

26
  const record = await client.items.create<Book>({
27
    item_type: { type: "item_type", id: "UZyfjdBES8y2W2ruMEHSoA" },
28
    title: "The JavaScript Guide",
29
    genre: "Programming",
30
    synopsis:
31
      "A comprehensive guide to modern JavaScript.\nPerfect for beginners and experts alike.",
32
    pages: 450,
33
  });
34

35
  console.log(inspectItem(record));
36
}
37

38
run();

1
└ Item "E3eHzSH6QSGbTDmlKlSusw" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
2
  ├ title: "The JavaScript Guide"
3
  ├ genre: "Programming"
4
  ├ synopsis: "A comprehensive guide to modern JavaScript.\nPerfect for beginners and experts..."
5
  └ pages: 450

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.

This example demonstrates how to create records with various simple field types, including text, numbers, dates, booleans, and more complex types like geo-location and color fields.

Key considerations when working with different field types:

Geo-location fields: Provide latitude and longitude as an object with both properties
Color fields: Specify RGBA values as an object with red, green, blue, and alpha components
JSON fields: Must be provided as a JSON-serialized string, not a JavaScript object
Date/time fields: Use ISO 8601 format strings for precise timestamps

For complete details on field value formats, see the Field types overview section.

1
import {
2
  buildClient,
3
  inspectItem,
4
  type ItemTypeDefinition,
5
} from "@datocms/cma-client-node";
6

7
type EnvironmentSettings = { locales: "en" };
8

9
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
10

11
type Product = ItemTypeDefinition<
12
  EnvironmentSettings,
13
  "UZyfjdBES8y2W2ruMEHSoA",
14
  {
15
    name: { type: "string" };
16
    category: { type: "string" };
17
    description: { type: "text" };
18
    price: { type: "integer" };
19
    weight: { type: "float" };
20
    release_date: { type: "date_time" };
21
    in_stock: { type: "boolean" };
22
    warehouse_location: { type: "lat_lon" };
23
    brand_color: { type: "color" };
24
    specifications: { type: "json" };
25
  }
26
>;
27

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

32
  const record = await client.items.create<Product>({
33
    item_type: { type: "item_type", id: "UZyfjdBES8y2W2ruMEHSoA" },
34
    name: "Premium Wireless Headphones",
35
    category: "Electronics",
36
    description:
37
      "High-quality noise-cancelling wireless headphones.\nPerfect for music and calls.",
38
    price: 299,
39
    weight: 0.25,
40
    release_date: "2024-03-15T10:30:00",
41
    in_stock: true,
42
    warehouse_location: {
43
      latitude: 45.0703393,
44
      longitude: 7.686864,
45
    },
46
    brand_color: {
47
      alpha: 255,
48
      blue: 156,
49
      green: 208,
50
      red: 239,
51
    },
52
    specifications: JSON.stringify({
53
      bluetooth: "5.0",
54
      battery_life: "30h",
55
      warranty: "2y",
56
    }),
57
  });
58

59
  console.log(inspectItem(record));
60
}
61

62
run();

1
└ Item "NZwcu3wYSgWeAbqVCJVToQ" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
2
  ├ name: "Premium Wireless Headphones"
3
  ├ category: "Electronics"
4
  ├ description: "High-quality noise-cancelling wireless headphones.\nPerfect for music and calls."
5
  ├ price: 299
6
  ├ weight: 0.25
7
  ├ release_date: 2024-03-15T10:30:00+00:00
8
  ├ in_stock: true
9
  ├ warehouse_location
10
  │ ├ latitude: 45.0703393
11
  │ └ longitude: 7.686864
12
  ├ brand_color: #EFD09C
13
  └ specifications: {"bluetooth":"5.0","battery_life":"30h","warranty":"2y"}

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. For a deeper dive into manipulating blocks, see the guide on Creating and Updating Blocks.

This example shows how to create records with modular content fields, which allow you to compose rich, dynamic content by combining multiple blocks of different types. Each block can have its own set of fields and can be repeated as needed.

The example uses the buildBlockRecord() helper function to create blocks more easily. You specify the block model ID and provide values for all the block's fields, similar to creating a regular record:

1
import {
2
  buildBlockRecord,
3
  buildClient,
4
  inspectItem,
5
  type ItemTypeDefinition,
6
} from "@datocms/cma-client-node";
7

8
type EnvironmentSettings = { locales: "en" };
9

10
/*
11
 * LandingPage
12
 * ├─ title: string
13
 * └─ sections: rich_text
14
 *    ├─ HeroBlock: headline, subtitle, background_image
15
 *    └─ TestimonialBlock: quote, author_name
16
 */
17

18
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
19

20
type LandingPage = ItemTypeDefinition<
21
  EnvironmentSettings,
22
  "UZyfjdBES8y2W2ruMEHSoA",
23
  {
24
    title: { type: "string" };
25
    sections: {
26
      type: "rich_text";
27
      blocks: HeroBlock | TestimonialBlock;
28
    };
29
  }
30
>;
31

32
type HeroBlock = ItemTypeDefinition<
33
  EnvironmentSettings,
34
  "T4m4tPymSACFzsqbZS65WA",
35
  {
36
    headline: { type: "string" };
37
    subtitle: { type: "text" };
38
    background_image: { type: "file" };
39
  }
40
>;
41

42
type TestimonialBlock = ItemTypeDefinition<
43
  EnvironmentSettings,
44
  "JItInCQJSIeCLX3oGPvN1w",
45
  {
46
    quote: { type: "text" };
47
    author_name: { type: "string" };
48
  }
49
>;
50

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

55
  // Create asset by using a local file:
56
  const upload = await client.uploads.createFromLocalFile({
57
    localPath: "./2018-10-17-194326.jpg",
58
  });
59

60
  const record = await client.items.create<LandingPage>({
61
    item_type: { type: "item_type", id: "UZyfjdBES8y2W2ruMEHSoA" },
62
    title: "Product Launch Landing Page",
63
    sections: [
64
      // hero block
65
      buildBlockRecord<HeroBlock>({
66
        item_type: { type: "item_type", id: "T4m4tPymSACFzsqbZS65WA" },
67
        headline: "Revolutionary New Product",
68
        subtitle:
69
          "Transform your workflow with our cutting-edge solution.\nBuilt for modern teams.",
70
        background_image: { upload_id: upload.id },
71
      }),
72
      // testimonial block
73
      buildBlockRecord<TestimonialBlock>({
74
        item_type: { type: "item_type", id: "JItInCQJSIeCLX3oGPvN1w" },
75
        quote: "This product completely transformed our business operations.",
76
        author_name: "Sarah Johnson, CEO",
77
      }),
78
    ],
79
  });
80

81
  console.log("-- Regular mode --");
82
  console.log(inspectItem(record));
83

84
  console.log("-- Nested mode --");
85
  const nestedRecord = await client.items.find(record, { nested: true });
86
  console.log(inspectItem(nestedRecord));
87
}
88

89
run();

1
-- Regular mode --
2
└ Item "Qw3wP3n8Qf286PjYiYzgXw" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
3
  ├ title: "Product Launch Landing Page"
4
  └ sections
5
    ├ [0]: "XhYlJCL5Rv-2UN2kRXnPcA"
6
    └ [1]: "S3hGBEOXTyKfOs6ac4o37Q"
7

8
-- Nested mode --
9
└ Item "Qw3wP3n8Qf286PjYiYzgXw" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
10
  ├ title: "Product Launch Landing Page"
11
  └ sections
12
    ├ [0] Item "XhYlJCL5Rv-2UN2kRXnPcA" (item_type: "T4m4tPymSACFzsqbZS65WA")
13
    │ ├ headline: "Revolutionary New Product"
14
    │ ├ subtitle: "Transform your workflow with our cutting-edge solution.\nBuilt for modern teams."
15
    │ └ background_image
16
    │   └ upload_id: "VUkBZ214TnK1UeHbJuoAmw"
17
    └ [1] Item "S3hGBEOXTyKfOs6ac4o37Q" (item_type: "JItInCQJSIeCLX3oGPvN1w")
18
      ├ quote: "This product completely transformed our business operations."
19
      └ author_name: "Sarah Johnson, CEO"

This example shows how to create records with single block fields, which allow you to add exactly one block to a field. Unlike modular content fields that can contain multiple blocks, single block fields hold either a single block instance or null.

The example uses the buildBlockRecord() helper function to create the block. You specify the block model ID and provide values for all the block's fields, similar to creating a regular record:

1
import {
2
  buildBlockRecord,
3
  buildClient,
4
  inspectItem,
5
  type ItemTypeDefinition,
6
} from "@datocms/cma-client-node";
7

8
type EnvironmentSettings = { locales: "en" };
9

10
/*
11
 * ProductPage
12
 * ├─ title: string
13
 * ├─ price: float
14
 * └─ hero_section: single_block
15
 *    └─ HeroBlock
16
 *       ├─ headline: string
17
 *       ├─ description: text
18
 *       ├─ button: single_block
19
 *       │  └─ ButtonBlock
20
 *       │     ├─ text: string
21
 *       │     └─ url: string
22
 *       └─ background_image: file
23
 */
24

25
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
26

27
type ProductPage = ItemTypeDefinition<
28
  EnvironmentSettings,
29
  "UZyfjdBES8y2W2ruMEHSoA",
30
  {
31
    title: { type: "string" };
32
    price: { type: "float" };
33
    hero_section: {
34
      type: "single_block";
35
      blocks: HeroBlock;
36
    };
37
  }
38
>;
39

40
type HeroBlock = ItemTypeDefinition<
41
  EnvironmentSettings,
42
  "T4m4tPymSACFzsqbZS65WA",
43
  {
44
    headline: { type: "string" };
45
    description: { type: "text" };
46
    button: { type: "single_block"; blocks: ButtonBlock };
47
    background_image: { type: "file" };
48
  }
49
>;
50

51
type ButtonBlock = ItemTypeDefinition<
52
  EnvironmentSettings,
53
  "d-CHYg-rShOt3kiL6ZN1yA",
54
  {
55
    text: { type: "string" };
56
    url: { type: "string" };
57
  }
58
>;
59

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

64
  // Create asset by using a local file:
65
  const upload = await client.uploads.createFromLocalFile({
66
    localPath: "./hero-background.jpg",
67
  });
68

69
  const record = await client.items.create<ProductPage>({
70
    item_type: { type: "item_type", id: "UZyfjdBES8y2W2ruMEHSoA" },
71
    title: "Premium Wireless Headphones",
72
    price: 299.99,
73
    hero_section: buildBlockRecord<HeroBlock>({
74
      item_type: { type: "item_type", id: "T4m4tPymSACFzsqbZS65WA" },
75
      headline: "Experience Audio Excellence",
76
      description:
77
        "Immerse yourself in crystal-clear sound with our premium wireless headphones.\nFeatures noise cancellation and 30-hour battery life.",
78
      button: buildBlockRecord<ButtonBlock>({
79
        item_type: { type: "item_type", id: "d-CHYg-rShOt3kiL6ZN1yA" },
80
        text: "Learn more",
81
        url: "/details",
82
      }),
83
      background_image: { upload_id: upload.id },
84
    }),
85
  });
86

87
  console.log("-- Regular mode --");
88
  console.log(inspectItem(record));
89

90
  console.log("-- Nested mode --");
91
  const nestedRecord = await client.items.find(record, { nested: true });
92
  console.log(inspectItem(nestedRecord));
93
}
94

95
run();

1
-- Regular mode --
2
└ Item "M54UhYRfQsSz62F1lTMHig" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
3
  ├ title: "Premium Wireless Headphones"
4
  ├ price: 299.99
5
  └ hero_section: "R9Gt9gafTyaRSa8IFwWJEw"
6

7
-- Nested mode --
8
└ Item "M54UhYRfQsSz62F1lTMHig" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
9
  ├ title: "Premium Wireless Headphones"
10
  ├ price: 299.99
11
  └ hero_section
12
    └ Item "R9Gt9gafTyaRSa8IFwWJEw" (item_type: "T4m4tPymSACFzsqbZS65WA")
13
      ├ headline: "Experience Audio Excellence"
14
      ├ description: "Immerse yourself in crystal-clear sound with our premium wireless headphones...."
15
      ├ button
16
      │ └ Item "aSFe8RhtThyajM5W3DEUPQ" (item_type: "d-CHYg-rShOt3kiL6ZN1yA")
17
      │   ├ text: "Learn more"
18
      │   └ url: "/details"
19
      └ background_image
20
        └ upload_id: "JP0pXTl3S0SFP42PYK2Mug"

This example demonstrates how to create records with structured text fields that combine rich formatted text with embedded blocks. Structured text is perfect for editorial content where you need to mix paragraphs, headings, and interactive elements seamlessly.

The buildBlockRecord() helper function simplifies creating embedded blocks, and the example shows how to create upload resources for media content. For more upload creation methods, see the Create a new upload endpoint documentation.

1
import {
2
  buildBlockRecord,
3
  buildClient,
4
  inspectItem,
5
  type ItemTypeDefinition,
6
} from "@datocms/cma-client-node";
7

8
type EnvironmentSettings = { locales: "en" };
9

10
/*
11
 * Article
12
 * ├─ title: string
13
 * └─ content: structured_text
14
 *    ├─ CtaBlock: title, description, button_text, button_url
15
 *    └─ ImageGalleryBlock: title, images
16
 */
17

18
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
19

20
type Article = ItemTypeDefinition<
21
  EnvironmentSettings,
22
  "UZyfjdBES8y2W2ruMEHSoA",
23
  {
24
    title: { type: "string" };
25
    content: {
26
      type: "structured_text";
27
      blocks: CtaBlock | ImageGalleryBlock;
28
    };
29
  }
30
>;
31

32
type CtaBlock = ItemTypeDefinition<
33
  EnvironmentSettings,
34
  "T4m4tPymSACFzsqbZS65WA",
35
  {
36
    title: { type: "string" };
37
    description: { type: "text" };
38
    button_text: { type: "string" };
39
    button_url: { type: "string" };
40
  }
41
>;
42

43
type ImageGalleryBlock = ItemTypeDefinition<
44
  EnvironmentSettings,
45
  "cSxBMd9XRWGGvq6xQ0qYDg",
46
  {
47
    title: { type: "string" };
48
    images: { type: "gallery" };
49
  }
50
>;
51

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

56
  // Create upload resources from URLs (or return existing uploads if already present in the media area):
57
  const upload1 = await client.uploads.createFromUrl({
58
    url: "https://picsum.photos/800/600?random=1",
59
    skipCreationIfAlreadyExists: true,
60
  });
61

62
  const upload2 = await client.uploads.createFromUrl({
63
    url: "https://picsum.photos/800/600?random=2",
64
    skipCreationIfAlreadyExists: true,
65
  });
66

67
  const record = await client.items.create<Article>({
68
    item_type: { type: "item_type", id: "UZyfjdBES8y2W2ruMEHSoA" },
69
    title: "The Future of Web Development",
70
    content: {
71
      schema: "dast",
72
      document: {
73
        type: "root",
74
        children: [
75
          // article introduction
76
          {
77
            type: "paragraph",
78
            children: [
79
              {
80
                type: "span",
81
                marks: [],
82
                value:
83
                  "Web development is rapidly evolving, and new technologies are reshaping how we build digital experiences. In this article, we'll explore the latest trends and tools that are defining the future.",
84
              },
85
            ],
86
          },
87
          // heading
88
          {
89
            type: "heading",
90
            level: 2,
91
            children: [
92
              {
93
                type: "span",
94
                marks: [],
95
                value: "Key Technologies to Watch",
96
              },
97
            ],
98
          },
99
          // paragraph with formatting
100
          {
101
            type: "paragraph",
102
            children: [
103
              {
104
                type: "span",
105
                marks: [],
106
                value: "From ",
107
              },
108
              {
109
                type: "span",
110
                marks: ["strong"],
111
                value: "serverless architectures",
112
              },
113
              {
114
                type: "span",
115
                marks: [],
116
                value: " to ",
117
              },
118
              {
119
                type: "span",
120
                marks: ["emphasis"],
121
                value: "edge computing",
122
              },
123
              {
124
                type: "span",
125
                marks: [],
126
                value:
127
                  ", developers now have unprecedented tools for building scalable applications.",
128
              },
129
            ],
130
          },
131
          // image gallery block
132
          {
133
            type: "block",
134
            item: buildBlockRecord<ImageGalleryBlock>({
135
              item_type: { type: "item_type", id: "cSxBMd9XRWGGvq6xQ0qYDg" },
136
              title: "Modern Development Environments",
137
              images: [
138
                {
139
                  upload_id: upload1.id,
140
                  alt: "Modern IDE setup",
141
                  title: "Development Environment",
142
                },
143
                {
144
                  upload_id: upload2.id,
145
                  alt: "Code collaboration tools",
146
                  title: "Team Collaboration",
147
                },
148
              ],
149
            }),
150
          },
151
          // another paragraph
152
          {
153
            type: "paragraph",
154
            children: [
155
              {
156
                type: "span",
157
                marks: [],
158
                value:
159
                  "As we look ahead, the integration of AI-powered tools and improved developer experiences will continue to accelerate innovation in our field.",
160
              },
161
            ],
162
          },
163
          // call-to-action block
164
          {
165
            type: "block",
166
            item: buildBlockRecord<CtaBlock>({
167
              item_type: { type: "item_type", id: "T4m4tPymSACFzsqbZS65WA" },
168
              title: "Ready to Level Up Your Skills?",
169
              description:
170
                "Join our community of forward-thinking developers and stay ahead of the curve with cutting-edge tutorials, tools, and insights.",
171
              button_text: "Join the Community",
172
              button_url: "https://example.com/join",
173
            }),
174
          },
175
        ],
176
      },
177
    },
178
  });
179

180
  console.log("-- Regular mode --");
181
  console.log(inspectItem(record));
182

183
  console.log("-- Nested mode --");
184
  const nestedRecord = await client.items.find(record, { nested: true });
185
  console.log(inspectItem(nestedRecord));
186
}
187

188
run();

1
-- Regular mode --
2
└ Item "F50TH6XjSiqyMfezCmra0w" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
3
  ├ title: "The Future of Web Development"
4
  └ content
5
    ├ paragraph
6
    │ └ span "Web development is rapidly evolving, and new technologies are reshapi..."
7
    ├ heading (level: 2)
8
    │ └ span "Key Technologies to Watch"
9
    ├ paragraph
10
    │ ├ span "From "
11
    │ ├ span (marks: strong) "serverless architectures"
12
    │ ├ span " to "
13
    │ ├ span (marks: emphasis) "edge computing"
14
    │ └ span ", developers now have unprecedented tools for building scalable appli..."
15
    ├ block "WWVn5YmfRfmwWr9rANi_Gg"
16
    ├ paragraph
17
    │ └ span "As we look ahead, the integration of AI-powered tools and improved de..."
18
    └ block "aciFN9_oRvWNjy7XIcm-9A"
19

20
-- Nested mode --
21
└ Item "F50TH6XjSiqyMfezCmra0w" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
22
  ├ title: "The Future of Web Development"
23
  └ content
24
    ├ paragraph
25
    │ └ span "Web development is rapidly evolving, and new technologies are reshapi..."
26
    ├ heading (level: 2)
27
    │ └ span "Key Technologies to Watch"
28
    ├ paragraph
29
    │ ├ span "From "
30
    │ ├ span (marks: strong) "serverless architectures"
31
    │ ├ span " to "
32
    │ ├ span (marks: emphasis) "edge computing"
33
    │ └ span ", developers now have unprecedented tools for building scalable appli..."
34
    ├ block
35
    │ └ Item "WWVn5YmfRfmwWr9rANi_Gg" (item_type: "cSxBMd9XRWGGvq6xQ0qYDg")
36
    │   ├ title: "Modern Development Environments"
37
    │   └ images
38
    │     ├ [0]
39
    │     │ ├ upload_id: "LkyN_T-oTq-o0RGt9EDUMQ"
40
    │     │ ├ alt: "Modern IDE setup"
41
    │     │ └ title: "Development Environment"
42
    │     └ [1]
43
    │       ├ upload_id: "YptkFcGyRXi3QOTUymmm2A"
44
    │       ├ alt: "Code collaboration tools"
45
    │       └ title: "Team Collaboration"
46
    ├ paragraph
47
    │ └ span "As we look ahead, the integration of AI-powered tools and improved de..."
48
    └ block
49
      └ Item "aciFN9_oRvWNjy7XIcm-9A" (item_type: "T4m4tPymSACFzsqbZS65WA")
50
        ├ title: "Ready to Level Up Your Skills?"
51
        ├ description: "Join our community of forward-thinking developers and stay ahead of the curve..."
52
        ├ button_text: "Join the Community"
53
        └ button_url: "https://example.com/join"

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.

This example shows how to create records that include image or file assets. You can work with both single assets and asset galleries by referencing existing uploads or creating new ones.

The example demonstrates two approaches:

Single asset field: Reference an upload with optional metadata overrides
Asset gallery field: Create arrays of asset objects with custom properties like alt text, title, focal points, and custom data

You can create new uploads from URLs using client.uploads.createFromUrl() or reference existing uploads from your media library. For more upload creation methods, see the Create a new upload endpoint documentation.

1
import {
2
  buildClient,
3
  inspectItem,
4
  type ItemTypeDefinition,
5
} from "@datocms/cma-client-node";
6

7
type EnvironmentSettings = { locales: "en" };
8

9
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
10

11
type Portfolio = ItemTypeDefinition<
12
  EnvironmentSettings,
13
  "UZyfjdBES8y2W2ruMEHSoA",
14
  {
15
    title: { type: "string" };
16
    featured_image: { type: "file" };
17
    gallery: { type: "gallery" };
18
  }
19
>;
20

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

25
  // create upload resource using URL (or return an existing upload if it's already present in the media area):
26
  const upload1 = await client.uploads.createFromUrl({
27
    url: "https://picsum.photos/800/600?random=3",
28
    skipCreationIfAlreadyExists: true,
29
  });
30

31
  // create upload resource using local file (or return an existing upload if it's already present in the media area):
32
  const upload2 = await client.uploads.createFromLocalFile({
33
    localPath: "./local.jpg",
34
    skipCreationIfAlreadyExists: true,
35
  });
36

37
  const record = await client.items.create<Portfolio>({
38
    item_type: { type: "item_type", id: "UZyfjdBES8y2W2ruMEHSoA" },
39
    title: "Architecture Photography",
40
    featured_image: {
41
      // in this case we're just passing the upload ID, as the
42
      // upload resource's defaults for alt, title, etc. are fine:
43
      upload_id: upload1.id,
44
    },
45
    gallery: [
46
      // here we want to override the upload resource's defaults:
47
      {
48
        upload_id: upload2.id,
49
        alt: "Modern architecture",
50
        title: "Urban Design",
51
        focal_point: {
52
          x: 0.3,
53
          y: 0.2,
54
        },
55
        custom_data: {
56
          add_watermark: true,
57
        },
58
      },
59
    ],
60
  });
61

62
  console.log(inspectItem(record));
63
}
64

65
run();

1
└ Item "LXN7jVhLTKaui_1dD9gLXA" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
2
  ├ title: "Architecture Photography"
3
  ├ featured_image
4
  │ └ upload_id: "HWhE3MhgTxCfqRfIMGW7Jg"
5
  └ gallery
6
    └ [0]
7
      ├ upload_id: "KJQT9BgrRjKJPALM9fsXgA"
8
      ├ alt: "Modern architecture"
9
      ├ title: "Urban Design"
10
      ├ custom_data: {"add_watermark":true}
11
      └ focal_point: x=30% y=20%

This example shows how to create records that reference other existing records through link fields. The process involves first retrieving the records you want to link to, then referencing them by their IDs when creating the new record.

Link fields can be either single links (referencing one record) or multiple links (referencing an array of records). The example demonstrates both scenarios and shows how to query for existing records before creating the relationships.

1
import {
2
  buildClient,
3
  inspectItem,
4
  type ItemTypeDefinition,
5
} from "@datocms/cma-client-node";
6

7
type EnvironmentSettings = { locales: "en" };
8

9
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
10

11
type Author = ItemTypeDefinition<
12
  EnvironmentSettings,
13
  "UZyfjdBES8y2W2ruMEHSoA",
14
  {
15
    name: { type: "string" };
16
    collaborators: { type: "links" };
17
    mentor: { type: "link" };
18
  }
19
>;
20

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

25
  // Let's retrieve some other authors first
26
  const otherAuthors = await client.items.list({
27
    filter: { type: "author" },
28
    version: "current",
29
  });
30

31
  if (otherAuthors.length === 0) {
32
    throw new Error("This example expects at least one record!");
33
  }
34

35
  const record = await client.items.create<Author>({
36
    item_type: { type: "item_type", id: "UZyfjdBES8y2W2ruMEHSoA" },
37
    name: "Sarah Johnson",
38
    collaborators: otherAuthors.map((author) => author.id),
39
    mentor: otherAuthors[0]!.id,
40
  });
41

42
  console.log(inspectItem(record));
43
}
44

45
run();

1
└ Item "Eukon4pbSrGyuYPWbmDiPQ" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
2
  ├ name: "Sarah Johnson"
3
  ├ collaborators
4
  │ ├ [0]: "EF-CHNzIRAeFbt2ACY-K2Q"
5
  │ ├ [1]: "MeYQG9_HTEi0ZwhQi7kffA"
6
  │ └ [2]: "fHgaJ1AaTZm-U6hFdEthgw"
7
  └ mentor: "EF-CHNzIRAeFbt2ACY-K2Q"

Localization

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

All localized fields in a single payload must specify the same set of locales to ensure consistency.
If the model is configured to require all locales (all_locales_required), then the payload must include a key for every available locale for each localized field. The value of a field for a locale can be null, but the key itself is mandatory.

For a full explanation of how to structure localized data, refer to the localization Guide.

The code shows two scenarios:

Providing content for a subset of available locales (en, it) with consistent locale keys across all localized fields
Including all available locales (en, it, fr) even when some translations are null

1
import {
2
  buildClient,
3
  inspectItem,
4
  type ItemTypeDefinition,
5
} from "@datocms/cma-client-node";
6

7
type EnvironmentSettings = { locales: "en" | "it" | "fr" };
8

9
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
10

11
type Pet = ItemTypeDefinition<
12
  EnvironmentSettings,
13
  "UZyfjdBES8y2W2ruMEHSoA",
14
  {
15
    name: { type: "string"; localized: true };
16
    description: { type: "string"; localized: true };
17
    category: { type: "string"; localized: false };
18
  }
19
>;
20

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

25
  // Example 1: Basic localization - consistent locales across all localized fields
26
  const basicRecord = await client.items.create<Pet>({
27
    item_type: { type: "item_type", id: "UZyfjdBES8y2W2ruMEHSoA" },
28
    name: {
29
      en: "Sir Fluffington McWhiskers",
30
      it: "Signor Pelosetto Baffetti",
31
    },
32
    description: {
33
      en: "A noble cat with an impeccable mustache.",
34
      it: "Un gatto nobile con baffi impeccabili.",
35
    },
36
    // Non-localized field - single value for all locales
37
    category: "indoor",
38
  });
39

40
  console.log("-- Basic record --");
41
  console.log(inspectItem(basicRecord));
42

43
  // Example 2: When all_locales_required is true - must include all locales
44
  // even if some values are null
45
  const allLocalesRecord = await client.items.create<Pet>({
46
    item_type: { type: "item_type", id: "UZyfjdBES8y2W2ruMEHSoA" },
47
    name: {
48
      en: "Luna",
49
      it: "Luna",
50
      fr: null, // Translation not ready yet, but key is required
51
    },
52
    description: {
53
      en: "A mysterious black cat that appears at midnight.",
54
      it: "Un gatto nero misterioso che appare a mezzanotte.",
55
      fr: null, // Translation not ready yet, but key is required
56
    },
57
    category: "outdoor",
58
  });
59

60
  console.log("-- All locales record --");
61
  console.log(inspectItem(allLocalesRecord));
62
}
63

64
run();

1
-- Basic record --
2
└ Item "PHz_ILZNR7uJ-r4PQsHEqg" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
3
  ├ name
4
  │ ├ en: "Sir Fluffington McWhiskers"
5
  │ └ it: "Signor Pelosetto Baffetti"
6
  ├ description
7
  │ ├ en: "A noble cat with an impeccable mustache."
8
  │ └ it: "Un gatto nobile con baffi impeccabili."
9
  └ category: "indoor"
10

11
-- All locales record --
12
└ Item "OBvZ6gKbTOSGY7NGB_9fqA" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
13
  ├ name
14
  │ ├ en: "Luna"
15
  │ ├ fr: ""
16
  │ └ it: "Luna"
17
  ├ description
18
  │ ├ en: "A mysterious black cat that appears at midnight."
19
  │ ├ fr: ""
20
  │ └ it: "Un gatto nero misterioso che appare a mezzanotte."
21
  └ category: "outdoor"

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

This example demonstrates how to create records in tree-structured collections, where records can form hierarchical relationships with parent-child connections. Tree structures are useful for navigation menus, category hierarchies, organizational charts, and any content that needs nested organization.

When creating records in tree-like collections, you can specify:

parent_id: Links the record to its parent in the hierarchy
position: Sets the ordering among sibling records

The example shows how to build a hierarchy by creating records that reference each other:

1
import {
2
  buildClient,
3
  inspectItem,
4
  type ItemTypeDefinition,
5
} from "@datocms/cma-client-node";
6

7
type EnvironmentSettings = { locales: "en" };
8

9
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
10

11
type Category = ItemTypeDefinition<
12
  EnvironmentSettings,
13
  "UZyfjdBES8y2W2ruMEHSoA",
14
  {
15
    name: { type: "string" };
16
    parent_id: { type: "string" };
17
    position: { type: "integer" };
18
  }
19
>;
20

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

25
  const parent = await client.items.create<Category>({
26
    item_type: { type: "item_type", id: "UZyfjdBES8y2W2ruMEHSoA" },
27
    name: "Parent",
28
  });
29

30
  console.log(inspectItem(parent));
31

32
  const child1 = await client.items.create<Category>({
33
    item_type: { type: "item_type", id: "UZyfjdBES8y2W2ruMEHSoA" },
34
    name: "Child 1",
35
    parent_id: parent.id,
36
    position: 1,
37
  });
38

39
  console.log(inspectItem(child1));
40

41
  const child2 = await client.items.create<Category>({
42
    item_type: { type: "item_type", id: "UZyfjdBES8y2W2ruMEHSoA" },
43
    name: "Child 2",
44
    parent_id: parent.id,
45
    position: 2,
46
  });
47

48
  console.log(inspectItem(child2));
49
}
50

51
run();

1
└ Item "Ov5N1h4_QwW89_IzbUBb4g" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
2
  ├ name: "Parent"
3
  ├ position: 1
4
  └ parent_id: null
5

6
└ Item "a8A-nl0cRXCqBNniQMAxog" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
7
  ├ name: "Child 1"
8
  ├ position: 1
9
  └ parent_id: "Ov5N1h4_QwW89_IzbUBb4g"
10

11
└ Item "d6Gl9tPMSTqSF2bOMIcOYw" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
12
  ├ name: "Child 2"
13
  ├ position: 2
14
  └ parent_id: "Ov5N1h4_QwW89_IzbUBb4g"

Create a new record

Code

Returned output

Field value formatting

Code

Returned output

Block Fields

Code

Returned output

Code

Returned output

Code

Returned output

Asset & Link Fields

Code

Returned output

Code

Returned output

Localization

Code

Returned output

Body parameters

Returns

Other examples

Code

Returned output