Create a new record — Record — Content Management API

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

Example Basic example

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() {
  // 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();

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.

Example Managing scalar fields

Example Adding assets to records

Example Links to other records

Example Modular content fields

Example Structured text fields

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

Example Localising content

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() {
  // 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();

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

Example Localising content with a sub-selection of locales

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();

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