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 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();
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.
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 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();
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() {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();
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 | |
no_index | Boolean | Whether the noindex meta tag should be returned |
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",}}},},]
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",}}},}
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.
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();