Home
Content Management API⁡𝅶‍‍𝅺⁡‍𝅴⁡𝅴𝅹‍‍⁢𝅵‍‍⁣‌⁡⁣𝅺⁢𝅸⁡⁢‍𝅹⁢𝅺𝅸‍‍‍𝅷‍‍𝅳⁡‍⁠‍‍⁢𝅵‍‍𝅳⁡⁣⁡⁣⁡​⁡⁢⁢𝅵‍𝅺‍𝅺⁢𝅸⁡⁢‍𝅹⁣‌⁡⁣𝅺⁢𝅸⁡⁢‍𝅹⁢𝅺𝅸‍𝅺⁠⁣𝅴⁡⁣𝅺⁡‍‍𝅺𝅴⁡⁣⁠𝅸⁠𝅺⁡⁣⁡𝅴⁡​⁠⁡⁢‍𝅺⁢𝅳⁢‌⁢​⁢𝅴⁢‍⁢⁠‍𝅺𝅴⁡⁣⁠𝅸⁡⁢‍𝅺⁢⁢⁢𝅴⁢𝅳⁢⁢⁢‌⁢⁡⁢𝅳⁢‌‍‍⁡𝅸
Main resources
Upload-related
Site Search
Environments
UI
Workflows
Async jobs
Roles & permissions
Webhooks
Hosting & CI integrations
Subscription
Enterprise
    Show examples in:
    Create a new field

    Parameters

    label  string  Required

    The label of the field

    field_type  enum  Required

    Type of input

    api_key  string  Required

    Field API key

    localized  boolean  Optional

    Whether the field needs to be multilanguage or not

    validators  object  Optional

    Optional field validations

    appearance  object  Optional

    Field appearance details, plugin configuration and field add-ons

    position  integer  Optional

    Ordering index

    hint  string, null  Optional

    Field hint

    default_value  boolean, null, string, number, object  Optional

    Default value for Field. When field is localized accepts an object of default values with site locales as keys

    fieldset  null, { type: "fieldset", id: fieldset.id }  Optional

    Fieldset linkage

    Returns

    Returns a field resource object.

    Examples

    The following examples are available:

    Basic example

    This is a complete example for creating a new localized Single-line string field:

    Example code:
    import { buildClient } from '@datocms/cma-client-node';
    async function run() {
      const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
      
      const modelIdOrApiKey = 'blog_post';
      
      const field = await client.fields.create(modelIdOrApiKey, {
        label: 'Title',
        field_type: 'string',
        api_key: 'title',
        localized: true,
        validators: {
          required: {}
        },
        appearance: {
          editor: 'single_line',
          parameters: {
            heading: false
          },
          addons: [
            {
              id: '1234',
              field_extension: 'lorem_ipsum',
              parameters: {}
            }
          ]
        },
        position: 1,
        hint: 'This field will be used as post title',
        default_value: {
          en: 'A default value',
          it: 'Un valore di default'
        },
        fieldset: null
      });
      
      console.log(field);
    }
    run();
    Returned output:
    {
      id: '124',
      label: 'Title',
      field_type: 'string',
      localized: true,
      default_value: {
        en: 'A default value',
        it: 'Un valore di default'
      },
      api_key: 'title',
      hint: 'This field will be used as post title',
      validators: {
        required: {}
      },
      appearance: {
        editor: 'single_line',
        parameters: {
          heading: false
        },
        addons: [
          {
            id: '1234',
            field_extension: 'lorem_ipsum',
            parameters: {}
          }
        ]
      },
      position: 1,
      item_type: {
        type: 'item_type',
        id: '44'
      },
      fieldset: null
    }
    Creating Modular Content fields

    In this example:

    • first we create some block models using the client.itemTypes.create() method, making sure to set the modular_block attribute to true — this tells the API that they're in fact block models, and not regular models;
    • we then create a Modular content field, passing down the allowed block models in the rich_text_blocks validator:
    Example code:
    import { buildClient } from '@datocms/cma-client-node';
    async function run() {
      const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
      const modularBlock1 = await client.itemTypes.create({
        name: 'Modular Block 1',
        api_key: 'modular_block1',
        modular_block: true,
      });
      const modularBlock2 = await client.itemTypes.create({
        name: 'Modular Block 2',
        api_key: 'modular_block2',
        modular_block: true,
      });
      const itemTypeId = '1234';
      const field = await client.fields.create(itemTypeId, {
        label: 'Content',
        field_type: 'rich_text',
        api_key: 'content',
        validators: {
          rich_text_blocks: {
            item_types: [modularBlock1.id, modularBlock2.id],
          },
        },
      });
      console.log(field);
    }
    run();
    Creating Structured Text fields

    Structured Text fields support both embedded block records and links to other regular records.

    For DatoCMS, a block model is just like a regular model, so we'll create them with client.itemTypes.create(), passing the modularBlock property to true:

    In this example:

    • first we create some block models using the client.itemTypes.create() method, making sure to set the modular_block attribute to true — this tells the API that they're in fact block models, and not regular models;
    • we then create the Structured Text field, passing down the embeddable block models in the structured_text_blocks validator, and the linkable record models in the structured_text_links validator:
    Example code:
    import { buildClient } from '@datocms/cma-client-node';
    async function run() {
      const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
      const modularBlock1 = await client.itemTypes.create({
        name: 'Modular Block 1',
        api_key: 'modular_block1',
        modular_block: true,
      });
      const modularBlock2 = await client.itemTypes.create({
        name: 'Modular Block 2',
        api_key: 'modular_block2',
        modular_block: true,
      });
      const itemTypeId = '1234';
      const field = await client.fields.create(itemTypeId, {
        label: 'Structured content',
        field_type: 'structured_text',
        api_key: 'content',
        validators: {
          structured_text_blocks: {
            item_types: [modularBlock1.id, modularBlock2.id],
          },
          structured_text_links: {
            item_types: [itemTypeId],
          },
        },
      });
      console.log(field);
    }
    run();
    Questions?
    We're always happy to help with code or other questions you might have. Search our documentation, forum, contact support, or connect with our sales team. You can chat live with other developers in our Slack channel.