Show examples in:

Endpoint info

Returns

Available examples

Basic example

Content Management API > Field

Create a new field

Body parameters

id string Optional

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

Example:

"Pkg-oztERp6o-Rj76nYKJg"

type string Required

Must be exactly "field".

attributes.label string Required

The label of the field

Example:

"Title"

attributes.field_type enum Required

Type of input

Example:

"string"

boolean Optional

color Optional

date Optional

date_time Optional

file Optional

float Optional

gallery Optional

integer Optional

json Optional

lat_lon Optional

link Optional

links Optional

rich_text Optional

seo Optional

single_block Optional

slug Optional

string Optional

structured_text Optional

text Optional

video Optional

attributes.api_key string Required

Field API key

Example:

"title"

attributes.localized boolean Optional

Whether the field needs to be multilanguage or not

attributes.validators object Optional

Optional field validations

Example:

{ required: {} }

attributes.appearance object Optional

Field appearance details, plugin configuration and field add-ons

Example:

{
  editor: "single_line",
  parameters: { heading: false },
  addons: [{ id: "1234", field_extension: "lorem_ipsum", parameters: {} }],
}

editor string Required

A valid editor can be a DatoCMS default field editor type (ie. "single_line"), or a plugin ID offering a custom field editor

parameters object Required

The editor plugin's parameters

addons Required

An array of add-on plugins with id and parameters

Type: Array<object>

id string Required

The ID of a plugin offering a field addon

parameters object Required

field_extension string Optional

The specific field extension to use for the field (only if the editor is a modern plugin)

field_extension string Optional

The specific field extension to use for the field (only if the editor is a modern plugin)

attributes.position integer Optional

Ordering index

Example:

attributes.hint string, null Optional

Field hint

Example:

"This field will be used as post title"

attributes.default_value Optional

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

Type: boolean, null, string, number, object

Example:

{ en: "A default value", it: "Un valore di default" }

attributes.deep_filtering_enabled boolean Optional

Whether deep filtering for block models is enabled in GraphQL or not

relationships.fieldset.data Optional

Fieldset linkage

Type: null, ResourceLinkage<"fieldset">

attributes.appeareance object Deprecated

Field appearance

This field contains a typo and will be removed in future versions: use appearance instead

editor string Required

parameters object Required

Returns

Returns a Job ID. You can then poll for the completion of the job that will eventually return a resource object of type field

Examples

The response contains the ID of the asynchronous job that started:

1
POST https://site-api.datocms.com/item-types/:model_id_or_api_key/fields 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": "field",
10
    "attributes": {
11
      "label": "Title",
12
      "field_type": "string",
13
      "api_key": "title"
14
    }
15
  }
16
}

1
curl -g 'https://site-api.datocms.com/item-types/:model_id_or_api_key/fields' \
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":"field","attributes":{"label":"Title","field_type":"string","api_key":"title"}}}'

1
await fetch(
2
  "https://site-api.datocms.com/item-types/:model_id_or_api_key/fields",
3
  {
4
    method: "POST",
5
    headers: {
6
      Authorization: "Bearer YOUR-API-TOKEN",
7
      Accept: "application/json",
8
      "X-Api-Version": "3",
9
      "Content-Type": "application/vnd.api+json",
10
    },
11
    body: JSON.stringify({
12
      data: {
13
        type: "field",
14
        attributes: { label: "Title", field_type: "string", api_key: "title" },
15
      },
16
    }),
17
  },
18
);

1
HTTP/1.1 202 Accepted
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": "job",
10
    "id": "4235"
11
  }
12
}

To get the asynchronous job result, poll the job result endpoint. While the task is in progress, the endpoint returns a 404 status code. When the job completes, the status changes to 200 OK:

1
GET https://site-api.datocms.com/job-results/:job_result_id HTTP/1.1
2
Authorization: Bearer YOUR-API-TOKEN
3
Accept: application/json
4
X-Api-Version: 3

1
curl -g 'https://site-api.datocms.com/job-results/:job_result_id' \
2
   \
3
  -H "Authorization: Bearer YOUR-API-TOKEN" \
4
  -H "Accept: application/json" \
5
  -H "X-Api-Version: 3"

1
await fetch("https://site-api.datocms.com/job-results/:job_result_id", {
2
  headers: {
3
    Authorization: "Bearer YOUR-API-TOKEN",
4
    Accept: "application/json",
5
    "X-Api-Version": "3",
6
  },
7
});

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": "job_result",
10
    "id": "34",
11
    "attributes": {
12
      "status": 200,
13
      "payload": {
14
        "data": {
15
          "type": "field",
16
          "id": "Pkg-oztERp6o-Rj76nYKJg",
17
          "attributes": {
18
            "label": "Title",
19
            "field_type": "string",
20
            "api_key": "title",
21
            "localized": true,
22
            "validators": {
23
              "required": {}
24
            },
25
            "position": 1,
26
            "hint": "This field will be used as post title",
27
            "default_value": {
28
              "en": "A default value",
29
              "it": "Un valore di default"
30
            },
31
            "appearance": {
32
              "editor": "single_line",
33
              "parameters": {
34
                "heading": false
35
              },
36
              "addons": [
37
                {
38
                  "id": "1234",
39
                  "field_extension": "lorem_ipsum",
40
                  "parameters": {}
41
                }
42
              ]
43
            },
44
            "deep_filtering_enabled": true
45
          },
46
          "relationships": {
47
            "item_type": {
48
              "data": {
49
                "type": "item_type",
50
                "id": "DxMaW10UQiCmZcuuA-IkkA"
51
              }
52
            },
53
            "fieldset": {
54
              "data": null
55
            }
56
          }
57
        }
58
      }
59
    }
60
  }
61
}

Did this doc help you?

Need help?

Explore our forum, contact support, or connect with our sales team . You can also chat live with other users in our Slack channel.