Choose your language:
    Create a new record

    Creating records on DatoCMS will always depend on your data schema. Please follow the few different examples that should illustrate all the arguments that you can provide when creating records by sending a POST request to the /items endpoint.

    In every situation make sure to send all the fields, even if they aren't required and are empty.

    We have a set of different examples:

    Parameters
    meta.createdAt  date-time  Required

    Date of creation

    meta.updatedAt  date-time  Required

    Last update time

    meta.publishedAt  null, date-time  Required

    Date of last publication

    meta.firstPublishedAt  null, date-time  Required

    Date of first publication

    meta.publicationScheduledAt  null, date-time  Required

    Date of future publication

    meta.status  null, enum  Required

    Status

    meta.isValid  boolean  Required

    Whether the current record is valid or not

    meta.currentVersion  string  Required

    The ID of the current record version

    itemType  item_type.id  Required

    The record model

    Returns
    Returns a item object.

    Examples

    A model with a few straightforward fields

    We are going to set up a model called Dog that looks like this:

    Model "Dog"

    ID: 1234
    API key: dog
    Fields:

    • Name (API key: name): string
    • Breed (API key: breed): string
    • Description (API key: description): text
    • Age (API key: age): integer number

    and then to create a new one send all the data like this:

    Example code:
    const { SiteClient } = require("datocms-client");
    const client = new SiteClient("YOUR-API-TOKEN");
    async function createRecord() {
    const record = await client.items.create({
    itemType: "1234", // model ID
    name: "Gigio",
    breed: "Labrador",
    description: "Very friendly and calm.\nI love it.",
    age: "4",
    });
    console.log(record);
    }
    createRecord();
    Returned output:
    {
    id: '4572128',
    name: 'Gigio',
    breed: 'Labrador',
    description: 'Very friendly and calm.\nI love it.',
    age: 4,
    updatedAt: '2020-04-17T16:34:32.005+01:00',
    createdAt: '2020-04-17T16:34:31.981+01:00',
    meta: {
    createdAt: '2020-04-17T16:34:31.981+01:00',
    updatedAt: '2020-04-17T16:34:32.005+01:00',
    publishedAt: '2020-04-17T16:34:32.004+01:00',
    firstPublishedAt: '2020-04-17T16:34:32.004+01:00',
    publicationScheduledAt: null,
    status: 'published',
    isValid: true,
    currentVersion: '8045084'
    },
    itemType: '1234',
    creator: { id: '322', type: 'access_token' }
    }
    All the simple fields

    Let's explore all the simple field options for the Dog model.

    A couple of gotchas here:

    • API keys should be camel-cased when using the JavaScript client
    • when sending a datetime you should keep in mind that we are ignoring the timezone, by dropping it, and we'll use the project's timezone instead
    • location and color fields require an object with all the fields specified
    • the JSON field must have the code properly escaped before

    Model "Dog"

    ID: 1234
    API key: dog
    Fields:

    • Name (API key: name): string
    • Breed (API key: breed): string
    • Description (API key: description): text
    • Age (API key: age): integer number
    • Height (API key: height): float number
    • Date of birth (API key: date_of_birth): date time
    • Available (API key: available): boolean
    • Location (API key: location): location
    • Color (API key: color): color
    • JSON (API key: json): JSON

    and then to create a new one send all the data like this:

    Example code:
    const { SiteClient } = require("datocms-client");
    const client = new SiteClient("YOUR-API-TOKEN");
    async function createRecord() {
    const record = await client.items.create({
    itemType: "1234", // model ID
    name: "Gigio",
    breed: "Labrador",
    description: "Very friendly and calm.\nI love it.",
    age: 4,
    height: 50.5,
    dateOfBirth: "2020-04-17T17:25:00",
    available: true,
    location: {
    latitude: 45.0703393,
    longitude: 7.686864,
    },
    color: {
    alpha: 255,
    blue: 156,
    green: 208,
    red: 239,
    },
    json: '{"additionalData": "1234"}',
    });
    console.log(record);
    }
    createRecord();
    Returned output:
    {
    id: '4572180',
    name: 'Gigio',
    breed: 'Labrador',
    description: 'Very friendly and calm.\nI love it.',
    age: 4,
    height: 50.5,
    dateOfBirth: '2020-04-17T17:25:00+01:00',
    available: true,
    location: { latitude: 45.0703393, longitude: 7.686864 },
    color: { red: 239, green: 208, blue: 156, alpha: 255 },
    json: '{"additionalData": "1234"}',
    updatedAt: '2020-04-17T16:58:27.498+01:00',
    createdAt: '2020-04-17T16:58:27.488+01:00',
    meta: {
    createdAt: '2020-04-17T16:58:27.488+01:00',
    updatedAt: '2020-04-17T16:58:27.498+01:00',
    publishedAt: '2020-04-17T16:58:27.498+01:00',
    firstPublishedAt: '2020-04-17T16:58:27.498+01:00',
    publicationScheduledAt: null,
    status: 'published',
    isValid: true,
    currentVersion: '8045322'
    },
    itemType: '1234',
    creator: { id: '322', type: 'access_token' }
    }
    Adding pictures to records

    In this example we'll explore how to add pictures to a record, using our usual Dog.

    Model "Dog"

    ID: 1234
    API key: dog
    Fields:

    • Name (API key: name): string
    • Picture (API key: picture): asset
    • Gallery (API key: gallery): asset gallery

    To send pictures we are going to leverage the uploadFile helper which returns an object that we can simply pass on to the items.create method.

    The object can be further customized by specifying alt, title and a customData object that can be optionally attached to the record.

    Example code:
    const { SiteClient } = require("datocms-client");
    const client = new SiteClient("YOUR-API-TOKEN");
    async function createRecord() {
    const picture = await client.uploadFile(
    "./2018-10-17-194326.jpg",
    {
    // upload attributes (optional)
    author: "Mark Smith",
    },
    {
    // field alt/title/custom data (optional)
    alt: "Dog picture",
    title: "Gigio",
    customData: {},
    }
    );
    const record = await client.items.create({
    itemType: "1234", // model ID
    name: "Gigio",
    picture: picture,
    gallery: [picture, picture, picture],
    });
    console.log(record);
    }
    createRecord();
    Returned output:
    { id: '4725799',
    name: 'Gigio',
    picture:
    { uploadId: '1737955',
    alt: 'Dog picture',
    title: 'Gigio',
    customData: {} },
    gallery:
    [ { alt: 'Dog picture',
    title: 'Gigio',
    customData: {},
    uploadId: '1737955' },
    { alt: 'Dog picture',
    title: 'Gigio',
    customData: {},
    uploadId: '1737955' },
    { alt: 'Dog picture',
    title: 'Gigio',
    customData: {},
    uploadId: '1737955' } ],
    updatedAt: '2020-05-18T14:46:26.484+01:00',
    createdAt: '2020-05-18T14:46:26.470+01:00',
    meta:
    { createdAt: '2020-05-18T14:46:26.470+01:00',
    updatedAt: '2020-05-18T14:46:26.484+01:00',
    publishedAt: '2020-05-18T14:46:26.483+01:00',
    firstPublishedAt: '2020-05-18T14:46:26.483+01:00',
    publicationScheduledAt: null,
    status: 'published',
    isValid: true,
    currentVersion: '8526589' },
    itemType: '1234',
    creator: { id: '322', type: 'access_token' } }

    We now want to add links to other records. For simplicity we are going to add links to other Dogs, so that we don't need other models.

    Model "Dog"

    ID: 1234
    API key: dog
    Fields:

    • Name (API key: name): string
    • Friends (API key: friends): multiple links

    In this example we first need to retrieve some records to link and then we can create our new one which links to them.

    Example code:
    const { SiteClient } = require("datocms-client");
    const client = new SiteClient("YOUR-API-TOKEN");
    async function createRecord() {
    // Let's retrieve other dogs first
    const friends = await client.items.all({ filter: { type: "dog" } });
    const record = await client.items.create({
    itemType: "1234", // model ID
    name: "Gigio",
    friends: friends.map((f) => f.id),
    });
    console.log(record);
    }
    createRecord();
    Returned output:
    {
    id: '4579273',
    name: 'Gigio',
    friends: [ '4572300', '4572298', '4572297', '4572180', '4572128' ],
    updatedAt: '2020-04-20T11:06:29.150+01:00',
    createdAt: '2020-04-20T11:06:29.126+01:00',
    meta: {
    createdAt: '2020-04-20T11:06:29.126+01:00',
    updatedAt: '2020-04-20T11:06:29.150+01:00',
    publishedAt: '2020-04-20T11:06:29.150+01:00',
    firstPublishedAt: '2020-04-20T11:06:29.150+01:00',
    publicationScheduledAt: null,
    status: 'published',
    isValid: true,
    currentVersion: '8062918'
    },
    itemType: '1234',
    creator: { id: '322', type: 'access_token' }
    }
    Add a modular content

    To make our dog's decription more dynamic we are going to replace the simple text field with a modular content. This will allow us to pass different modular blocks to our description. Each block will have its set of fields and can be repeated as many times as needed.

    So our Dog model will look like this:

    ID: 1234 API key: dog Fields:

    • Name (API key: name): string
    • Description (API key: description): modular content
      • Description block (ID: 1235)
        • Description (API key: description): text
      • Gallery block (ID: 1236)
        • Gallery (API key: gallery): asset gallery
      • Prize block (ID: 1237)
        • Name (API key: name): string
        • Year (API key: year): string
        • Picture (API key: picture): asset

    In this example we need to import the buildModularBlock helper from the client. This helper will allow us to create in one go the record with its modular blocks. You just need to specify the block ID and then you should specify all the fields, just like a plain record.

    Example code:
    const { SiteClient, buildModularBlock } = require("datocms-client");
    const client = new SiteClient("YOUR-API-TOKEN");
    async function createRecord() {
    const picture = await client.uploadFile("./2018-10-17-194326.jpg");
    const description = [
    // prize
    buildModularBlock({
    itemType: "1237",
    name: "Best dog in the world",
    year: "2020",
    picture: picture,
    }),
    // description
    buildModularBlock({
    itemType: "1235",
    description: "Very friendly and calm.\nI love it.",
    }),
    // gallery
    buildModularBlock({
    itemType: "1236",
    gallery: [picture, picture, picture],
    }),
    ];
    const record = await client.items.create({
    itemType: "1234", // model ID
    name: "Gigio",
    description: description,
    });
    console.log(record);
    }
    createRecord();
    Returned output:
    {
    id: '4579897',
    name: 'Gigio',
    description: [ '4579894', '4579895', '4579896' ],
    updatedAt: '2020-04-20T13:38:36.005+01:00',
    createdAt: '2020-04-20T13:38:35.972+01:00',
    meta: {
    createdAt: '2020-04-20T13:38:35.972+01:00',
    updatedAt: '2020-04-20T13:38:36.005+01:00',
    publishedAt: '2020-04-20T13:38:36.004+01:00',
    firstPublishedAt: '2020-04-20T13:38:36.004+01:00',
    publicationScheduledAt: null,
    status: 'published',
    isValid: true,
    currentVersion: '8065211'
    },
    itemType: '1234',
    creator: { id: '322', type: 'access_token' }
    }
    Localising content

    To localize content, you first need to specify which fields can have multiple locales. In this example, let's see how to localize the name and the modular content.

    The Dog model will stay the same, but with two localized fields:

    ID: 1234 API key: dog Fields:

    • Name (API key: name): string - localized
    • Description (API key: description): modular content - localized
      • Description block (ID: 1235)
        • Description (API key: description): text
      • Gallery block (ID: 1236)
        • Gallery (API key: gallery): asset gallery
      • Prize block (ID: 1237)
        • Name (API key: name): string
        • Year (API key: year): string
        • Picture (API key: picture): asset
    Example code:
    const { SiteClient, buildModularBlock } = require("datocms-client");
    const client = new SiteClient("YOUR-API-TOKEN");
    async function createRecord() {
    const picture = await client.uploadFile("./2018-10-17-194326.jpg");
    const descriptionEn = [
    // prize
    buildModularBlock({
    itemType: "1237",
    name: "Best dog in the world",
    year: "2020",
    picture: picture,
    }),
    // description
    buildModularBlock({
    itemType: "1235",
    description: "Very friendly and calm.\nI love it.",
    }),
    // gallery
    buildModularBlock({
    itemType: "1236",
    gallery: [picture, picture, picture],
    }),
    ];
    const descriptionIt = [
    // prize
    buildModularBlock({
    itemType: "1237",
    name: "Miglior cane del mondo",
    year: "2020",
    picture: picture,
    }),
    // description
    buildModularBlock({
    itemType: "1235",
    description: "Molto amichevole e calmo.\nLo adoro.",
    }),
    // gallery
    buildModularBlock({
    itemType: "1236",
    gallery: [picture, picture, picture],
    }),
    ];
    const record = await client.items.create({
    itemType: "1234", // model ID
    name: {
    it: "Gigio",
    en: "Fido",
    },
    description: {
    en: descriptionEn,
    it: descriptionIt,
    },
    });
    console.log(record);
    }
    createRecord();
    Returned output:
    { id: '4668524',
    name: { en: 'Fido', it: 'Gigio' },
    description:
    { en: [ '4668518', '4668519', '4668520' ],
    it: [ '4668521', '4668522', '4668523' ] },
    updatedAt: '2020-05-06T13:11:27.483+01:00',
    createdAt: '2020-05-06T13:11:27.442+01:00',
    meta:
    { createdAt: '2020-05-06T13:11:27.442+01:00',
    updatedAt: '2020-05-06T13:11:27.483+01:00',
    publishedAt: '2020-05-06T13:11:27.482+01:00',
    firstPublishedAt: '2020-05-06T13:11:27.482+01:00',
    publicationScheduledAt: null,
    status: 'published',
    isValid: true,
    currentVersion: '8329850' },
    itemType: '221242',
    creator: { id: '322', type: 'access_token' } }
    Tree-like structure

    Let's see how to create three objects and nest them one into another.

    Remember that to be able to organize records in a tree-like structure, you need to specify in the model's settings that the records should be organizable in a tree.

    ID: 1234
    API key: tree
    Fields:

    • Name (API key: name): string
    Example code:
    const { SiteClient } = require("datocms-client");
    const client = new SiteClient("YOUR-API-TOKEN");
    async function createRecords() {
    const parent = await client.items.create({
    itemType: "1234",
    name: "Parent",
    });
    console.log(parent);
    const child = await client.items.create({
    itemType: "1234",
    name: "Child",
    parentId: parent.id,
    });
    console.log(child);
    const grandChild = await client.items.create({
    itemType: "1234",
    name: "Grand Child",
    parentId: child.id,
    });
    console.log(grandChild);
    }
    createRecords();
    Returned output:
    {
    id: '4679744',
    name: 'Parent',
    parentId: null,
    ...
    }
    {
    id: '4679745',
    name: 'Child',
    parentId: '4679744',
    ...
    }
    {
    id: '4679746',
    name: 'Grand Child',
    parentId: '4679745',
    ...
    }