Sorry, no results found for "".
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.
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.
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. You cannot create a record by providing only block IDs. For a deeper dive into manipulating blocks, see the guide on Creating and Updating Blocks.
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.
If the record's model contains localized fields, your creation payload must adhere to specific rules:
Unlike record updates where you can send a subset of locales, the creation endpoint is stricter about enforcing required locales. For a full explanation of how to structure localized data, refer to the Localization Guide.
RFC 4122 UUID of record expressed in URL-safe base64 format
"hWl-mnkWRYmMCSTq4z_piQ"
Must be exactly "item".
Date of creation
Date of first publication
The entity (account/collaborator/access token/sso user) who created the record
Returns a resource object of type item.
POST https://site-api.datocms.com/items HTTP/1.1Authorization: Bearer YOUR-API-TOKENAccept: application/jsonX-Api-Version: 3Content-Type: application/vnd.api+json
{ "data": { "type": "item", "attributes": { "title": "My first blog post!", "content": "Lorem ipsum dolor sit amet...", "category": "24", "image": { "upload_id": "1235", "alt": "Alt text", "title": "Image title", "custom_data": {} } }, "relationships": { "item_type": { "data": { "type": "item_type", "id": "DxMaW10UQiCmZcuuA-IkkA" } } } }}curl -g 'https://site-api.datocms.com/items' \ -X POST \ -H "Authorization: Bearer YOUR-API-TOKEN" \ -H "Accept: application/json" \ -H "X-Api-Version: 3" \ -H "Content-Type: application/vnd.api+json" \ --data-binary '{"data":{"type":"item","attributes":{"title":"My first blog post!","content":"Lorem ipsum dolor sit amet...","category":"24","image":{"upload_id":"1235","alt":"Alt text","title":"Image title","custom_data":{}}},"relationships":{"item_type":{"data":{"type":"item_type","id":"DxMaW10UQiCmZcuuA-IkkA"}}}}}'await fetch("https://site-api.datocms.com/items", { method: "POST", headers: { Authorization: "Bearer YOUR-API-TOKEN", Accept: "application/json", "X-Api-Version": "3", "Content-Type": "application/vnd.api+json", }, body: JSON.stringify({ data: { type: "item", attributes: { title: "My first blog post!", content: "Lorem ipsum dolor sit amet...", category: "24", image: { upload_id: "1235", alt: "Alt text", title: "Image title", custom_data: {}, }, }, relationships: { item_type: { data: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }, }, }, }, }),});HTTP/1.1 200 OKContent-Type: application/jsonCache-Control: cache-control: max-age=0, private, must-revalidateX-RateLimit-Limit: 30X-RateLimit-Remaining: 28
{ "data": { "type": "item", "id": "hWl-mnkWRYmMCSTq4z_piQ", "relationships": { "item_type": { "data": { "type": "item_type", "id": "DxMaW10UQiCmZcuuA-IkkA" } } }, "attributes": { "title": "My first blog post!", "content": "Lorem ipsum dolor sit amet...", "category": "24", "image": { "alt": "Alt text", "title": "Image title", "custom_data": {}, "focal_point": null, "upload_id": "20042921" } }, "meta": { "created_at": "2020-04-21T07:57:11.124Z", "updated_at": "2020-04-21T07:57:11.124Z", "published_at": "2020-04-21T07:57:11.124Z", "first_published_at": "2020-04-21T07:57:11.124Z", "publication_scheduled_at": "2020-04-21T07:57:11.124Z", "unpublishing_scheduled_at": "2020-04-21T07:57:11.124Z", "status": "published", "is_current_version_valid": true, "is_published_version_valid": true, "current_version": "4234", "stage": null, "has_children": true } }, "included": [ { "type": "item_type", "id": "DxMaW10UQiCmZcuuA-IkkA", "relationships": { "singleton_item": { "data": null }, "fields": { "data": [ { "type": "field", "id": "Pkg-oztERp6o-Rj76nYKJg" } ] }, "fieldsets": { "data": [ { "type": "fieldset", "id": "93Y1C2sySkG4Eg0atBRIwg" } ] }, "presentation_title_field": { "data": null }, "presentation_image_field": { "data": null }, "title_field": { "data": null }, "image_preview_field": { "data": null }, "excerpt_field": { "data": null }, "ordering_field": { "data": null }, "workflow": { "data": null } }, "attributes": { "name": "Blog post", "api_key": "post", "singleton": false, "sortable": true, "modular_block": false, "tree": false, "ordering_direction": null, "ordering_meta": "created_at", "draft_mode_active": false, "all_locales_required": false, "collection_appearance": "compact", "hint": "Blog posts will be shown in our website under the Blog section", "inverse_relationships_enabled": false, "draft_saving_active": false }, "meta": { "has_singleton_item": false } } ]}