Sorry, no results found for "".

Show examples in:
Javascript HTTP

Content Management API > Record

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).

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:

import { buildClient } from "@datocms/cma-client-node";
async function run() {
// Make sure the API token has access to the CMA, and is stored securely
const client = buildClient({ apiToken: process.env.DATOCMS_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();
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' },
};

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 examples.

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.

import { buildClient } from "@datocms/cma-client-node";
async function run() {
// Make sure the API token has access to the CMA, and is stored securely
const client = buildClient({ apiToken: process.env.DATOCMS_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();
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' },
};

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.

import { buildClient } from "@datocms/cma-client-node";
async function run() {
// Make sure the API token has access to the CMA, and is stored securely
const client = buildClient({ apiToken: process.env.DATOCMS_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();
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' },
};

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.

import { buildClient } from "@datocms/cma-client-node";
async function run() {
// Make sure the API token has access to the CMA, and is stored securely
const client = buildClient({ apiToken: process.env.DATOCMS_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();
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' },
};

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:

const { buildClient, buildBlockRecord } = require("datocms-client");
async function run() {
// Make sure the API token has access to the CMA, and is stored securely
const client = buildClient({ apiToken: process.env.DATOCMS_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();
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' },
};

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.

const { buildBlockRecord, buildBlockRecord } = require("datocms-client");
async function run() {
// Make sure the API token has access to the CMA, and is stored securely
const client = buildClient({ apiToken: process.env.DATOCMS_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();
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' },
};

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 your model has the "All locales required?" option turned on, then you MUST express a field value for all environment's locales:

{
// 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 :)
}

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
nameSingle-line string (string)
ageInteger (integer)

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

import { buildClient } from "@datocms/cma-client-node";
async function run() {
// Make sure the API token has access to the CMA, and is stored securely
const client = buildClient({ apiToken: process.env.DATOCMS_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();
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' },
};

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 }
}
}

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.

import { buildClient } from "@datocms/cma-client-node";
async function run() {
// Make sure the API token has access to the CMA, and is stored securely
const client = buildClient({ apiToken: process.env.DATOCMS_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();
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' },
};

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
redInteger between 0 and 255
greenInteger between 0 and 255
blueInteger between 0 and 255
alphaInteger 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
latitudeFloat between -90.0 to 90
longitudeFloat 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
no_indexBooleanWhether the noindex meta tag should be returned
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_uidStringUnique identifier of the video within the provider"vUdGBEb1i9g"
urlURLURL of the video"https://www.youtube.com/watch?v=qJhobECFQYk"
widthIntegerVideo width459
heightIntegerVideo height344
thumbnail_urlURLURL for the video thumb"https://i.ytimg.com/vi/vUdGBEb1i9g/hqdefault.jpg"
titleStringTitle of the video"Next.js Conf Booth Welcoming!"
Single-asset

The field accepts an object with the following properties:

PropertyRequiredTypeDescriptionExample
upload_idUpload 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_idUpload 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",
}
}
},
},
]
Single block

When a record is being read, this field returns a <String> representing the ID of the inner block record.

When a record is being created, this field must contain an object representing the inner block record:

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 record, or if the block is not subject to any change, just pass its ID:

// we don't need to change anything to this block, just pass its ID:
"9862635"
// 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",
}
}
}
}
}
]
}
}

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

creator Optional

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

Returns

Returns a resource object of type item

Other examples

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
nameSingle-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:

import { buildClient } from "@datocms/cma-client-node";
async function run() {
// Make sure the API token has access to the CMA, and is stored securely
const client = buildClient({ apiToken: process.env.DATOCMS_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();
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,
// ...
};