Record

DatoCMS stores the individual pieces of content you create from a model as records (for backwards compatibility the API calls these item). The shape of a record’s attributes depends on the fields defined by that record’s model — see the Object payload section for the full object payload documentation.

1
// A simple record
2
{
3
  "id": "A4gkL_8pTZmcyJ-IlIEd2w",
4
  "type": "item",
5
  "attributes": {
6
    "title": "My Blog Post",
7
    "publication_date": "2024-01-15"
8
  },
9
  "relationships": {
10
    "item_type": {
11
      "data": { "id": "BxZ9Y2aKQVeTnM4hP8wLpD", "type": "item_type" }
12
    }
13
  }
14
}

Field types overview

Scalar fields

These store basic data types (ie. strings, numbers, booleans):

Object Fields

These require structured objects:

Reference Fields

These point to other resources (either assets or other records):

Block Fields

These are special fields that contain blocks within records:

Blocks are records within records - they're separate items that live inside fields of other records.

Blocks inside those fields are unique because they can be represented in two different ways depending on the context: as a lightweight reference (an ID) or as a full content object. Understanding this duality is key to working with them effectively:

• Block ID (Lightweight Reference): A simple String that uniquely identifies the block (ie. "dhVR2HqgRVCTGFi_0bWqLqA"). This is useful when you only need to know which block is there, not what's inside it.

• Block Object (Full Content): The complete record object for the block, containing its own id, type, attributes, and relationships. This is used when you need to read or modify the block's actual content.

  1
  {
  2
    "id": "dhVR2HqgRVCTGFi_0bWqLqA",
  3
    "type": "item",
  4
    "attributes": {
  5
      "title": "Block Title",
  6
      "content": "Block content..."
  7
    },
  8
    "relationships": {
  9
      "item_type": {
  10
        "data": { "id": "BxZ9Y2aKQVeTnM4hP8wLpD", "type": "item_type" }
  11
      }
  12
    }
  13
  }

1
{
2
  "content_blocks": [
3
    "dhVR2HqgRVCTGFi_0bWqLqA",
4
    "kL9mN3pQrStUvWxYzAbCdE"
5
  ]
6
}

1
{
2
  "content_blocks": [
3
    {
4
      "id": "dhVR2HqgRVCTGFi_0bWqLqA",
5
      "type": "item",
6
      "attributes": { "title": "Hero Section", "content": "Welcome to our site" },
7
      "relationships": { "item_type": { "data": { "id": "...", "type": "item_type" } } }
8
    },
9
    {
10
      "id": "kL9mN3pQrStUvWxYzAbCdE",
11
      "type": "item",
12
      "attributes": { "title": "Image Gallery", "images": [...] },
13
      "relationships": { "item_type": { "data": { "id": "...", "type": "item_type" } } }
14
    }
15
  ]
16
}

1
{
2
  "featured_block": "dhVR2HqgRVCTGFi_0bWqLqA"
3
}

1
{
2
  "featured_block": {
3
    "id": "dhVR2HqgRVCTGFi_0bWqLqA",
4
    "type": "item",
5
    "attributes": { "title": "Featured Content", "summary": "A summary..." },
6
    "relationships": { "item_type": { "data": { "id": "...", "type": "item_type" } } }
7
  }
8
}

1
{
2
  "rich_text_content": {
3
    "schema": "dast",
4
    "document": {
5
      "type": "root",
6
      "children": [
7
        {
8
          "type": "paragraph",
9
          "children": [{ "type": "span", "value": "Text before block." }]
10
        },
11
        {
12
          "type": "block",
13
          "item": "dhVR2HqgRVCTGFi_0bWqLqA"
14
        }
15
      ]
16
    }
17
  }
18
}

1
{
2
  "rich_text_content": {
3
    "schema": "dast",
4
    "document": {
5
      "type": "root",
6
      "children": [
7
        {
8
        "type": "paragraph",
9
          "children": [{ "type": "span", "value": "Text before block." }]
10
        },
11
        {
12
          "type": "block",
13
          "item": {
14
            "id": "dhVR2HqgRVCTGFi_0bWqLqA",
15
            "type": "item",
16
            "attributes": { "title": "Embedded Block", "content": "..." },
17
            "relationships": { "item_type": { "data": { "id": "...", "type": "item_type" } } }
18
          }
19
        }
20
      ]
21
    }
22
  }
23
}

API response modes: Regular vs. Nested

When fetching record data, the API gives you control over how block fields are represented in the response. These two modes, Regular and Nested, are available on the following endpoints:

• Retrieve a single record (GET /items/:id)
• Retrieve multiple records (GET /items)
• Retrieve records referenced by a record (GET /items/:id/references)
• Retrieve records linked to an asset (GET /upload/:id/references)

Regular mode (default)

By default, the API returns block fields as IDs only. This is efficient and fast, making it ideal for listings or when you don't need the blocks' content immediately.

1
GET /items/A4gkL_8pTZmcyJ-IlIEd2w
2

3
{
4
  "id": "A4gkL_8pTZmcyJ-IlIEd2w",
5
  "type": "item",
6
  "attributes": {
7
    "title": "My Blog Post",
8
    "content_blocks": ["dhVR2HqgRVCTGFi_0bWqLqA", "kL9mN3pQrStUvWxYzAbCdE"],
9
    "featured_block": "nZ8xY2vWqTuJkL3mNcBeFg"
10
  }
11
}

Nested mode (?nested=true)

The same endpoint, when passing the ?nested=true option, returns block fields as full objects. This is essential when you need to display or edit the content within the blocks.

1
GET /items/A4gkL_8pTZmcyJ-IlIEd2w?nested=true
2

3
{
4
  "id": "A4gkL_8pTZmcyJ-IlIEd2w",
5
  "type": "item",
6
  "attributes": {
7
    "title": "My Blog Post",
8
    "content_blocks": [
9
      {
10
        "id": "dhVR2HqgRVCTGFi_0bWqLqA",
11
        "type": "item",
12
        "attributes": { "title": "Hero Section", "content": "Welcome to our site" },
13
        "relationships": { ... }
14
      },
15
      {
16
        "id": "kL9mN3pQrStUvWxYzAbCdE",
17
        "type": "item",
18
        "attributes": { "title": "Image Gallery", "images": [...] },
19
        "relationships": { ... }
20
      }
21
    ],
22
    "featured_block": {
23
      "id": "nZ8xY2vWqTuJkL3mNcBeFg",
24
      "type": "item",
25
      "attributes": { ... },
26
      "relationships": { ... }
27
    }
28
  }
29
}

When to use each mode?

Creating and updating blocks

Working with blocks follows one fundamental constraint:

You cannot create, edit, or delete blocks directly. You must always update the parent record that contains them.

This ensures data integrity. To create/modify blocks, you send a payload to the parent record's endpoint, using a mix of Block IDs and Block Objects to describe the desired changes.

Key rules for block operations

1. To create a new block: Provide the full object, including type, attributes, and the relationships.item_type which specifies the Block Model being used.
2. To update an existing block: Provide the full object, including its id and the changed attributes. You only need to include the specific attributes that you want to change - unchanged attributes will be preserved. You don't need to specify relationships.item_type.
3. To keep an existing block unchanged: Simply provide its Block ID string. This is the most efficient way to handle unchanged blocks.
4. To delete a block: Omit it from the payload. For a Modular Content array, remove its ID. For a Single Block field, set the value to null.
5. To reorder blocks (in Modular Content): Send an array of Block IDs in the new desired order.

The following examples show how to apply these rules.

1
{
2
  "content_blocks": ["dhVR2HqgRVCTGFi_0bWqLqA", "kL9mN3pQrStUvWxYzAbCdE", "fG8hI1jKlMnOpQrStUvWxY"]
3
}

1
{
2
  "content_blocks": [
3
    "fG8hI1jKlMnOpQrStUvWxY", // Reordered: kept as ID
4
    {
5
      "id": "kL9mN3pQrStUvWxYzAbCdE", // Updated: sent as object
6
      "type": "item",
7
      "attributes": { "title": "Updated Title" }
8
    },
9
    "dhVR2HqgRVCTGFi_0bWqLqA" // Reordered: kept as ID
10
  ]
11
}

1
{
2
  "content_blocks": [
3
    "kL9mN3pQrStUvWxYzAbCdE", // Kept as ID
4
    "fG8hI1jKlMnOpQrStUvWxY", // Kept as ID
5
    {
6
      "type": "item", // New block: sent as object with relationships
7
      "attributes": { "title": "A Brand New Block" },
8
      "relationships": {
9
        "item_type": {
10
          "data": { "id": "BxZ9Y2aKQVeTnM4hP8wLpD", "type": "item_type" }
11
        }
12
      }
13
    }
14
  ]
15
}

1
{
2
  "hero_block": "dhVR2HqgRVCTGFi_0bWqLqA"
3
}

1
{
2
  "hero_block": {
3
    "id": "dhVR2HqgRVCTGFi_0bWqLqA",
4
    "type": "item",
5
    "attributes": { "title": "Updated Hero Title" }
6
  }
7
}

1
{
2
  "hero_block": {
3
    "type": "item",
4
    "attributes": { "title": "New Hero Block" },
5
    "relationships": {
6
      "item_type": {
7
        "data": { "id": "BxZ9Y2aKQVeTnM4hP8wLpD", "type": "item_type" }
8
      }
9
    }
10
  }
11
}

1
{
2
  "hero_block": null
3
}

1
{
2
  "rich_content": {
3
    "schema": "dast",
4
    "document": {
5
      "type": "root",
6
      "children": [
7
        { "type": "block", "item": "dhVR2HqgRVCTGFi_0bWqLqA" },
8
        { "type": "paragraph", "children": [{ "type": "span", "value": "Some text." }] }
9
      ]
10
    }
11
  }
12
}

1
{
2
  "rich_content": {
3
    "schema": "dast",
4
    "document": {
5
      "type": "root",
6
      "children": [
7
        {
8
          "type": "block",
9
          "item": {
10
            "id": "dhVR2HqgRVCTGFi_0bWqLqA", // The block to update
11
            "type": "item",
12
            "attributes": { "title": "Updated DAST Block Title" }
13
          }
14
        },
15
        { "type": "paragraph", "children": [{ "type": "span", "value": "Some text." }] }
16
      ]
17
    }
18
  }
19
}

Deeply-nested blocks

Blocks can contain other blocks, creating hierarchies multiple levels deep. The same principles apply recursively. When you fetch a record with ?nested=true, the API will expand nested blocks at all levels.

When updating, you are always sending a payload to the top-level parent record, but you can specify changes to deeply nested blocks using the same ID vs. object rules.

1
// This payload is sent to the top-level record containing the "Parent Block"
2
{
3
  "wrapper_block": {
4
    "id": "dhVR2HqgRVCTGFi_0bWqLqA", // ID of the parent block being updated
5
    "type": "item",
6
    "attributes": {
7
      "nested_content": [
8
        {
9
          "id": "kL9mN3pQrStUvWxYzAbCdE", // ID of the nested block being updated
10
          "type": "item",
11
          "attributes": { "title": "Updated Child Block 1" }
12
        },
13
        "fG8hI1jKlMnOpQrStUvWxY" // Unchanged nested block, sent as ID
14
      ],
15
      // You can skip any attribute that does not need to change
16
    }
17
  }
18
}

Localization

Localization allows you to store different versions of your content for different languages or regions. When you mark a field as "localizable" in your model, its structure in the API changes to accommodate multiple values.

The fundamental change is that the field's value is no longer a single piece of data but an object keyed by locale codes.

For example, a simple non-localized title field looks like this:

1
{
2
  "title": "Hello World"
3
}

When localized, it becomes an object containing a value for each configured locale:

1
{
2
  "title": {
3
    "en": "Hello World",
4
    "it": "Ciao Mondo",
5
    "fr": "Bonjour le Monde"
6
  }
7
}

This principle applies to every type of field, from simple strings to Modular Content, Single Block, and Structured Text fields. For instance, a localized Modular Content field will contain a separate array of blocks for each language. This powerful feature allows you to have completely different block structures for each locale.

1
{
2
  "content_blocks": {
3
    "en": ["dhVR2HqgRVCTGFi0bWqLqA", "kL9mN3pQrStUvWxYzAbCdE"],
4
    "it": ["fG8hI1jKlMnOpQrStUvWxY", "dhVR2HqgRVCTGFi0bWqLqA"]
5
  }
6
}

1
{
2
  "hero_block": {
3
    "en": "dhVR2HqgRVCTGFi0bWqLqA",
4
    "it": "kL9mN3pQrStUvWxYzAbCdE"
5
  }
6
}

1
{
2
  "rich_content": {
3
    "en": {
4
      "schema": "dast",
5
      "document": {
6
        "type": "root",
7
        "children": [
8
          {
9
            "type": "paragraph",
10
            "children": [
11
              {
12
                "type": "span",
13
                "value": "Welcome to our product showcase. Here's what we're featuring today:"
14
              }
15
            ]
16
          },
17
          { "type": "block", "item": "dhVR2HqgRVCTGFi0bWqLqA" }
18
        ]
19
      }
20
    },
21
    "it": {
22
      "schema": "dast",
23
      "document": {
24
        "type": "root",
25
        "children": [
26
          {
27
            "type": "paragraph",
28
            "children": [
29
              {
30
                "type": "span",
31
                "value": "Benvenuti nella nostra vetrina prodotti. Ecco cosa presentiamo oggi:"
32
              }
33
            ]
34
          },
35
          { "type": "block", "item": "kL9mN3pQrStUvWxYzAbCdE" }
36
        ]
37
      }
38
    }
39
  }
40
}

When reading or writing localized content, there are a few key rules to follow to ensure data integrity.

Locale consistency

Within a single record, all localized fields must have a consistent set of locales. You cannot have a title with English and Italian, and a description with English and French in the same record.

1
// ❌ This will FAIL due to inconsistent locales ("it" vs "fr")
2
{
3
  "title": { "en": "Title", "it": "Titolo" },
4
  "description": { "en": "Description", "fr": "Description" }
5
}
6

7
// ✅ This is VALID because locales are consistent across all fields
8
{
9
  "title": { "en": "Title", "it": "Titolo" },
10
  "description": { "en": "Description", "it": "Descrizione" }
11
}

Models enforcing all locales

You can configure a model to require every project locale to be present for its localized fields using the all_locales_required attribute.

When this setting is enabled, records must include a key for every defined locale within each localized field. The value for a locale can be null, but the key itself is mandatory.

1
// ❌ FAILS: The "it" locale is missing.
2
{
3
  "title": { "en": "Title" }
4
}
5

6
// ✅ VALID: All required locale keys ("en", "it") are present.
7
{
8
  "title": { "en": "Title", "it": "Titolo" }
9
}
10

11
// ✅ ALSO VALID: The "it" key is present, even with a `null` value.
12
{
13
  "title": { "en": "Title", "it": null }
14
}

Type-safe development with TypeScript

Since DatoCMS records don't have a predetermined structure, the JavaScript client cannot provide strict TypeScript types out of the box:

1
import { buildClient } from "@datocms/cma-client-node";
2

3
const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
4
const record = await client.items.find('dhVR2HqgRVCTGFi0bWqLqA');
5

6
record.accent_color; // -> TypeScript type: unknown

To get full type-safety plus auto-completions and type hints in your code editor, you can leverage the DatoCMS CLI to automatically generate TypeScript types based on your specific project schema.

Generating types from your schema

After installing and configuring the CLI, you can use the schema:generate command to generate a comprehensive TypeScript definition file describing your DatoCMS project structure (models and blocks):

1
$ npx datocms schema:generate schema.ts

1
import type { ItemTypeDefinition } from '@datocms/cma-client';
2

3
export type Article = ItemTypeDefinition<
4
  '76hhD-LaS5CM3NPJw0991w', // ID of the Product model
5
  {
6
    name: { type: 'string'; };
7
    slug: { type: 'slug'; };
8
    accent_color: { type: 'color'; };
9
    sections: { type: 'rich_text'; blocks: ArticleSection; };
10
  }
11
>;
12

13
export type ArticleSection = ItemTypeDefinition<
14
  'FJM79jjKRMSVg-fR6k6X2A', // ID of the ProductVariation block
15
  {
16
    title: { type: 'string'; };
17
  }
18
>;

You can use the --item-types flag to only generate definitions for specific models/blocks:

1
$ npx datocms schema:generate --item-types=product,article schema.ts

The same type definitions can be included in your migration scripts by using the migrations:new CLI command with --schema flag:

1
# generate definitions for all the models/blocks
2
$ npx datocms migrations:new 'tweak articles' --schema=all
3
# only generate definitions for article and author
4
$ npx datocms migrations:new 'tweak articles' --schema=article,author

An ItemTypeDefinition is a minimal type blueprint for your API payloads. It only includes what's needed for typed API calls: field names, their data types, and any allowed block types. It intentionally omits details like validation rules or default values, as they don't affect the shape of the data sent to or from the API.

Use generated types

These definition types can be used as generics in all API calls related to records to get a fully typed interface:

1
import * as Schema from './schema';
2

3
// Fully typed record retrieval
4
const record = await client.items.find<Schema.Article>('AZUeMuPySxuJCJ8ibEVE7w');
5
record.accent_color; // -> ColorFieldValue (properly typed!)
6

7
// Type-safe record creation
8
const record = await client.items.create<Schema.Article>({
9
  item_type: { id: 'dhVR2HqgRVCTGFi0bWqLqA', type: 'item_type' },
10
  accent_color: '#FF0000', // ❌ TypeScript error! Wrong format!
11
});

TypeScript type narrowing with __itemTypeId

Records include a top-level __itemTypeId property to help with TypeScript's type narrowing.

Since TypeScript cannot infer types from nested properties like record.item_type.id, you can use the top-level __itemTypeId in your checks. This allows TypeScript to correctly identify the specific record type, enabling type-safe access to its unique properties.

1
// ❌ This doesn't work because `item_type.id` is a nested property.
2
if (item.item_type.id === "BxZ9Y2aKQVeTnM4hP8wLpD") {
3
  // TypeScript still sees a generic item type.
4
  item.attributes.headline; // Error: Property 'headline' is `unknown`
5
}
6

7
// ✅ This works because `__itemTypeId` is a top-level property.
8
if (item.__itemTypeId === "BxZ9Y2aKQVeTnM4hP8wLpD") {
9
  // TypeScript now correctly infers the type.
10
  item.attributes.headline; // OK!
11
}

Object payload

Available endpoints

• List all records
• Create a new record
• Duplicate a record
• Update a record
• Referenced records
• Retrieve a record
• Delete a record
• Publish a record
• Unpublish a record
• Publish items in bulk
• Unpublish items in bulk
• Destroy items in bulk
• Move items to stage in bulk