Content Management API > Record

Create a new record

📚 New to DatoCMS records?

Before creating your first record, we strongly recommend reading the Introduction to Records guide. It covers fundamental concepts about field types, block manipulation, and localization that are essential for building a valid creation payload.

The payload required to create a new record is determined by the specific model it's based on and the fields it contains.

When creating a record, you don't need to specify a value for every field. Any field you omit will be set to its configured default value, or null if no default is set.

While the Introduction to Records guide offers a complete reference for every field type, there are several key rules that are especially important when creating a new record.

TypeScript typing

Writing a create payload without typed schemas means writing blind: every field is unknown, typos compile fine, and mistakes only surface as 422s from the API. The single biggest lever you have is passing a generated Schema.X marker as the generic on items.create. TypeScript then enforces the model's field names, types, and allowed block shapes at compile time:

1
// ❌ Untyped: every field is `unknown`, typos compile.
2
await client.items.create({ /* … */ });
3

4
// ✅ Typed: field names, types, and block shapes enforced.
5
await client.items.create<Schema.Article>({ /* … */ });

When you need the actual TypeScript type of a single field — to annotate a helper, an intermediate variable, or a function parameter — reach for FieldValueInRequest<T, 'field_key'>. The first argument is the Schema.X marker for the model that owns the field:

⚠️ A marker can't be indexed directly

Schema.Article is a phantom type marker, not a record shape. Writing Schema.Article["content"] won't give you the field type.

1
// ❌ Markers aren't indexable
2
type Content = Schema.Article["content"];
3

4
// ✅ Use the helper instead
5
type Content = NonNullable<FieldValueInRequest<Schema.Article, "content">>;

1
function buildSections(
2
  page: ApiTypes.ItemInNestedResponse,
3
): NonNullable<FieldValueInRequest<Schema.LandingPage, "sections">> {
4
  // …assemble and return the sections array…
5
}
6

7
await client.items.create<Schema.LandingPage>({
8
  item_type: Schema.LandingPage.REF,
9
  title: "Product Launch Landing Page",
10
  sections: buildSections(sourcePage),
11
});

The first argument also accepts an item-shaped value the CMA already produced — useful when you're cloning or migrating from an existing record:

1
const source = await client.items.find<Schema.Article>("source-id", { nested: true });
2

3
if (source.content) {
4
  const content: NonNullable<FieldValueInRequest<typeof source, "content">> =
5
    /* …transform source.content… */;
6
  await client.items.create<Schema.Article>({ item_type: Schema.Article.REF, content });
7
}

⚠️ Field values are always nullable

Even fields with a required validator are typed as Nullable, because the API may still accept/return null in some scenarios. Wrap the helper in NonNullable<…> when you need the non-null shape.

📖 Read-side counterparts

FieldValueInRequest is the write-side helper. For values coming back from the API, use FieldValue<T, 'field_key'> (regular responses) or FieldValueInNestedResponse<T, 'field_key'> (when you fetched with nested: true). All three follow the same <marker-or-value, fieldKey> shape — see the Item resource overview for the full helper family.

Field value formatting

Every field in your payload must be formatted according to its type. This can range from a simple string or number to a structured object. For a comprehensive breakdown of the expected format for every field type, please refer to the Field Types Overview in our main records guide.

Block Fields

When creating a record, any new blocks (for Modular Content, Single Block, or Structured Text fields) must be provided as full block objects. This object must include the item_type in its relationships to specify which Block Model to use. For a deeper dive into manipulating blocks, see the guide on Creating and Updating Blocks.

Asset & Link Fields

These reference fields require specific formats. For a comprehensive breakdown of the expected format for every field type, please refer to the Field Types Overview in our main records guide.

Localization

If the record's model contains localized fields, your creation payload must adhere to specific rules:

All localized fields in a single payload must specify the same set of locales to ensure consistency.
If the model is configured to require all locales (all_locales_required), then the payload must include a key for every available locale for each localized field. The value of a field for a locale can be null, but the key itself is mandatory.

For a full explanation of how to structure localized data, refer to the localization Guide.

Body parameters

id string Optional

RFC 4122 UUID of record expressed in URL-safe base64 format

Example:

"hWl-mnkWRYmMCSTq4z_piQ"

type string Required

Must be exactly "item".

meta.created_at string Optional

Date of creation

meta.first_published_at null, string Optional

Date of first publication

relationships.item_type.data Required

The record's model

Type: ResourceLinkage<"item_type">

relationships.creator.data Optional

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

Type: ResourceLinkage<"account">, ResourceLinkage<"access_token">, ResourceLinkage<"user">, ResourceLinkage<"sso_user">, ResourceLinkage<"organization">

Returns

Returns a resource object of type item.

Examples

1
POST https://site-api.datocms.com/items HTTP/1.1
2
Authorization: Bearer YOUR-API-TOKEN
3
Accept: application/json
4
X-Api-Version: 3
5
Content-Type: application/vnd.api+json
6

7
{
8
  "data": {
9
    "type": "item",
10
    "attributes": {
11
      "title": "My first blog post!",
12
      "content": "Lorem ipsum dolor sit amet...",
13
      "category": "24",
14
      "image": {
15
        "upload_id": "WxrWMPl3TjeSJYcl6lNCbg",
16
        "alt": "Alt text",
17
        "title": "Image title",
18
        "custom_data": {}
19
      }
20
    },
21
    "relationships": {
22
      "item_type": {
23
        "data": {
24
          "type": "item_type",
25
          "id": "DxMaW10UQiCmZcuuA-IkkA"
26
        }
27
      }
28
    }
29
  }
30
}

1
curl -g 'https://site-api.datocms.com/items' \
2
  -X POST \
3
  -H "Authorization: Bearer YOUR-API-TOKEN" \
4
  -H "Accept: application/json" \
5
  -H "X-Api-Version: 3" \
6
  -H "Content-Type: application/vnd.api+json" \
7
  --data-binary '{"data":{"type":"item","attributes":{"title":"My first blog post!","content":"Lorem ipsum dolor sit amet...","category":"24","image":{"upload_id":"WxrWMPl3TjeSJYcl6lNCbg","alt":"Alt text","title":"Image title","custom_data":{}}},"relationships":{"item_type":{"data":{"type":"item_type","id":"DxMaW10UQiCmZcuuA-IkkA"}}}}}'

1
await fetch("https://site-api.datocms.com/items", {
2
  method: "POST",
3
  headers: {
4
    Authorization: "Bearer YOUR-API-TOKEN",
5
    Accept: "application/json",
6
    "X-Api-Version": "3",
7
    "Content-Type": "application/vnd.api+json",
8
  },
9
  body: JSON.stringify({
10
    data: {
11
      type: "item",
12
      attributes: {
13
        title: "My first blog post!",
14
        content: "Lorem ipsum dolor sit amet...",
15
        category: "24",
16
        image: {
17
          upload_id: "WxrWMPl3TjeSJYcl6lNCbg",
18
          alt: "Alt text",
19
          title: "Image title",
20
          custom_data: {},
21
        },
22
      },
23
      relationships: {
24
        item_type: {
25
          data: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" },
26
        },
27
      },
28
    },
29
  }),
30
});

1
HTTP/1.1 200 OK
2
Content-Type: application/json
3
Cache-Control: cache-control: max-age=0, private, must-revalidate
4
X-RateLimit-Limit: 30
5
X-RateLimit-Remaining: 28
6

7
{
8
  "data": {
9
    "type": "item",
10
    "id": "hWl-mnkWRYmMCSTq4z_piQ",
11
    "relationships": {
12
      "item_type": {
13
        "data": {
14
          "type": "item_type",
15
          "id": "DxMaW10UQiCmZcuuA-IkkA"
16
        }
17
      }
18
    },
19
    "attributes": {
20
      "title": "My first blog post!",
21
      "content": "Lorem ipsum dolor sit amet...",
22
      "category": "24",
23
      "image": {
24
        "alt": "Alt text",
25
        "title": "Image title",
26
        "custom_data": {},
27
        "focal_point": null,
28
        "upload_id": "20042921"
29
      }
30
    },
31
    "meta": {
32
      "created_at": "2020-04-21T07:57:11.124Z",
33
      "updated_at": "2020-04-21T07:57:11.124Z",
34
      "published_at": "2020-04-21T07:57:11.124Z",
35
      "first_published_at": "2020-04-21T07:57:11.124Z",
36
      "publication_scheduled_at": "2020-04-21T07:57:11.124Z",
37
      "unpublishing_scheduled_at": "2020-04-21T07:57:11.124Z",
38
      "status": "published",
39
      "is_current_version_valid": true,
40
      "is_published_version_valid": true,
41
      "current_version": "4234",
42
      "stage": null,
43
      "has_children": true
44
    }
45
  },
46
  "included": [
47
    {
48
      "type": "item_type",
49
      "id": "DxMaW10UQiCmZcuuA-IkkA",
50
      "relationships": {
51
        "singleton_item": {
52
          "data": null
53
        },
54
        "fields": {
55
          "data": [
56
            {
57
              "type": "field",
58
              "id": "Pkg-oztERp6o-Rj76nYKJg"
59
            }
60
          ]
61
        },
62
        "fieldsets": {
63
          "data": [
64
            {
65
              "type": "fieldset",
66
              "id": "93Y1C2sySkG4Eg0atBRIwg"
67
            }
68
          ]
69
        },
70
        "presentation_title_field": {
71
          "data": null
72
        },
73
        "presentation_image_field": {
74
          "data": null
75
        },
76
        "title_field": {
77
          "data": null
78
        },
79
        "image_preview_field": {
80
          "data": null
81
        },
82
        "excerpt_field": {
83
          "data": null
84
        },
85
        "ordering_field": {
86
          "data": null
87
        },
88
        "workflow": {
89
          "data": null
90
        }
91
      },
92
      "attributes": {
93
        "name": "Blog post",
94
        "api_key": "post",
95
        "singleton": false,
96
        "sortable": true,
97
        "modular_block": false,
98
        "tree": false,
99
        "ordering_direction": null,
100
        "ordering_meta": "created_at",
101
        "draft_mode_active": false,
102
        "all_locales_required": false,
103
        "collection_appearance": "compact",
104
        "hint": "Blog posts will be shown in our website under the Blog section",
105
        "inverse_relationships_enabled": false,
106
        "draft_saving_active": false
107
      },
108
      "meta": {
109
        "has_singleton_item": false
110
      }
111
    }
112
  ]
113
}