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).
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.
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 }}}
The field accepts String values.
The field accepts simple String values.
The field accepts simple Boolean values.
The field accepts simple Integer values.
The field accepts simple Float values.
The field accepts String values in ISO 8601 date format (ie. "2015-12-29").
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.
The field accepts an object with the following properties:
| Property | Required | Type |
|---|---|---|
red | ✅ | Integer between 0 and 255 |
green | ✅ | Integer between 0 and 255 |
blue | ✅ | Integer between 0 and 255 |
alpha | ✅ | Integer between 0 and 255 |
The field accepts String values that are valid JSON.
The field accepts an object with the following properties:
| Property | Required | Type |
|---|---|---|
latitude | ✅ | Float between -90.0 to 90 |
longitude | ✅ | Float between -180.0 to 180 |
The field accepts an object with the following properties:
| Property | Required | Type | Description |
|---|---|---|---|
title | String | Title meta tag (max. 320 characters) | |
description | String | Description meta tag (max. 320 characters) | |
image | Upload ID | Asset to be used for social shares | |
twitter_card | "summary", "summary_large_image" | Type of Twitter card to use |
The field accepts String values that satisfy the following regular expression: /^[a-z0-9_]+(?:\-[a-z0-9]+)*$/.
The field accepts an object with the following properties:
| Property | Required | Type | Description | Example |
|---|---|---|---|---|
provider | ✅ | "youtube", "vimeo", "facebook" | External video provider | "youtube" |
provider_uid | ✅ | String | Unique identifier of the video within the provider | "vUdGBEb1i9g" |
url | ✅ | URL | URL of the video | "https://www.youtube.com/watch?v=qJhobECFQYk" |
width | ✅ | Integer | Video width | 459 |
height | ✅ | Integer | Video height | 344 |
thumbnail_url | ✅ | URL | URL for the video thumb | "https://i.ytimg.com/vi/vUdGBEb1i9g/hqdefault.jpg" |
title | ✅ | String | Title of the video | "Next.js Conf Booth Welcoming!" |
The field accepts an object with the following properties:
| Property | Required | Type | Description | Example |
|---|---|---|---|---|
upload_id | ✅ | Upload ID | ID of an asset | "3429022" |
title | String | Title for the asset, if you want to override the asset's default value (see Upload default_field_metadata) | "From my trip to Italy" | |
alt | String | Alternate 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 }, null | Focal 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_data | Record<String, String> | An object containing custom keys that you can use on your frontend projects | { "watermark_image": "true" } |
This field accepts an Array of objects with the following properties:
| Property | Required | Type | Description | Example |
|---|---|---|---|---|
upload_id | ✅ | Upload ID | ID of an asset | "3429022" |
title | String | Title 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" | |
alt | String | Alternate 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 }, null | Focal 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_data | Record<String, String> | An object containing custom keys that you can use on your frontend projects | { "watermark_image": "true" } |
This field accepts a String representing the ID of the linked record.
This field accepts an Array<String> representing the IDs of the linked records.
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",}}},},]
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",}}}}}]}}
Date of creation
Date of first publication
The record's model
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.
The following examples are available:
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:
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();
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' },};
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():
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() {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();
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 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.
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();
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 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.
import { buildClient } from '@datocms/cma-client-node';async function run() {const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });// Let's retrieve some other dogs firstconst 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 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) |
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() {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 blockbuildBlockRecord({item_type: { type: 'item_type', id: '1235' },name: 'Best dog in the world',year: 2020,picture: { upload_id: upload.id },}),// description blockbuildBlockRecord({item_type: { type: 'item_type', id: '1236' },description: 'Very friendly and calm.\nI love it.',}),// carousel blockbuildBlockRecord({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 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) |
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() {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();
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' },};
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:
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();
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' },};
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:
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();
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' },};
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:
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();
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,// ...};