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.

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
}

Create a new record

Field value formatting

Block Fields

Asset & Link Fields

Localization

Body parameters

Returns

Examples

HTTP Request

CURL Request

fetch() Request

HTTP Response