You're reading "Content Management API"

Field

Each Model consists of a set of fields. Using the database metaphore, fields are like table columns, and when creating them you need to specify their type ("string", "image", "float", etc.) and any required validation.

The Field object

A Field object is returned as part of the response body of each successful Index, Show, Create, Update or Delete API call. The following table contains the list of all its fields along with their type, description and example values.

Object fields:
api_keystring

Field API key

This attribute is required
appeareanceobject

Field appeareance

This attribute is required
default_valueboolean, number, object, string

Default value for Field

field_typestring

Type of input

This attribute is required
hintstring

Field hint

labelstring

The label of the field

This attribute is required
localizedboolean

Whether the field needs to be multilanguage or not

This attribute is required
positioninteger

Ordering index

This attribute is required
validatorsobject

Optional field validations

This attribute is required

List all fields

To list all fields, send a GET request to the /item-types/:item_type_id/fields endpoint. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.

Example request
GET https://site-api.datocms.com/item-types/:item_type_id/fields HTTP/1.1
X-Api-Version2
AuthorizationBearer YOUR-API-KEY
Acceptapplication/json
Example response
HTTP/1.1 200 OK
Content-Typeapplication/json; charset=utf-8
Cache-Controlcache-control: max-age=0, private, must-revalidate
X-RateLimit-Limit30
X-RateLimit-Remaining28
{ "data": [ { "type": "field", "id": "124", "attributes": { "label": "Title", "field_type": "string", "default_value": "some default value", "localized": true, "api_key": "title", "hint": "This field will be used as post title", "validators": { "required": {} }, "appeareance": { "editor": "single_line", "parameters": { "heading": false }, "addons": [] }, "position": 1 }, "relationships": { "item_type": { "data": { "type": "item_type", "id": "44" } } } } ] }

Retrieve a field

To retrieve a field, send a GET request to the /fields/:field_id endpoint. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.

Example request
GET https://site-api.datocms.com/fields/:field_id HTTP/1.1
X-Api-Version2
AuthorizationBearer YOUR-API-KEY
Acceptapplication/json
Example response
HTTP/1.1 200 OK
Content-Typeapplication/json; charset=utf-8
Cache-Controlcache-control: max-age=0, private, must-revalidate
X-RateLimit-Limit30
X-RateLimit-Remaining28
{ "data": { "type": "field", "id": "124", "attributes": { "label": "Title", "field_type": "string", "default_value": "some default value", "localized": true, "api_key": "title", "hint": "This field will be used as post title", "validators": { "required": {} }, "appeareance": { "editor": "single_line", "parameters": { "heading": false }, "addons": [] }, "position": 1 }, "relationships": { "item_type": { "data": { "type": "item_type", "id": "44" } } } } }

Create a new field

To create a new field, send a POST request to the /item-types/:item_type_id/fields endpoint, passing the resource arguments in the request body. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.

Example request
POST https://site-api.datocms.com/item-types/:item_type_id/fields HTTP/1.1
X-Api-Version2
AuthorizationBearer YOUR-API-KEY
Acceptapplication/json
Content-Typeapplication/json
{ "data": { "type": "field", "attributes": { "label": "Title", "field_type": "string", "api_key": "title", "localized": true, "validators": { "required": {} }, "appeareance": { "editor": "single_line", "parameters": { "heading": false }, "addons": [] }, "position": 1, "hint": "This field will be used as post title", "default_value": "some default value" } } }
Example response
HTTP/1.1 200 OK
Content-Typeapplication/json; charset=utf-8
Cache-Controlcache-control: max-age=0, private, must-revalidate
X-RateLimit-Limit30
X-RateLimit-Remaining28
{ "data": { "type": "field", "id": "124", "attributes": { "label": "Title", "field_type": "string", "default_value": "some default value", "localized": true, "api_key": "title", "hint": "This field will be used as post title", "validators": { "required": {} }, "appeareance": { "editor": "single_line", "parameters": { "heading": false }, "addons": [] }, "position": 1 }, "relationships": { "item_type": { "data": { "type": "item_type", "id": "44" } } } }, "included": [ { "type": "item_type", "id": "44", "attributes": { "name": "Blog post", "api_key": "post", "collection_appeareance": "compact", "singleton": false, "all_locales_required": false, "sortable": true, "modular_block": false, "draft_mode_active": false, "tree": false, "ordering_direction": null, "has_singleton_item": true }, "relationships": { "menu_item": { "data": null }, "singleton_item": { "data": null }, "fields": { "data": [ { "type": "field", "id": "124" } ] }, "title_field": { "data": null }, "ordering_field": { "data": null } } } ] }

Update a field

To update a field, send a PUT request to the /fields/:field_id endpoint, passing the resource arguments in the request body. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.

Example request
PUT https://site-api.datocms.com/fields/:field_id HTTP/1.1
X-Api-Version2
AuthorizationBearer YOUR-API-KEY
Acceptapplication/json
Content-Typeapplication/json
{ "data": { "type": "field", "id": "124", "attributes": { "default_value": "some default value", "label": "Title", "api_key": "title", "localized": true, "validators": { "required": {} }, "appeareance": { "editor": "single_line", "parameters": { "heading": false }, "addons": [] }, "position": 1, "field_type": "string", "hint": "This field will be used as post title" } } }
Example response
HTTP/1.1 200 OK
Content-Typeapplication/json; charset=utf-8
Cache-Controlcache-control: max-age=0, private, must-revalidate
X-RateLimit-Limit30
X-RateLimit-Remaining28
{ "data": { "type": "field", "id": "124", "attributes": { "label": "Title", "field_type": "string", "default_value": "some default value", "localized": true, "api_key": "title", "hint": "This field will be used as post title", "validators": { "required": {} }, "appeareance": { "editor": "single_line", "parameters": { "heading": false }, "addons": [] }, "position": 1 }, "relationships": { "item_type": { "data": { "type": "item_type", "id": "44" } } } } }

Delete a field

To delete a field, send a DELETE request to the /fields/:field_id endpoint. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.

Example request
DELETE https://site-api.datocms.com/fields/:field_id HTTP/1.1
X-Api-Version2
AuthorizationBearer YOUR-API-KEY
Acceptapplication/json
Example response
HTTP/1.1 200 OK
Content-Typeapplication/json; charset=utf-8
Cache-Controlcache-control: max-age=0, private, must-revalidate
X-RateLimit-Limit30
X-RateLimit-Remaining28
{ "data": { "type": "field", "id": "124", "attributes": { "label": "Title", "field_type": "string", "default_value": "some default value", "localized": true, "api_key": "title", "hint": "This field will be used as post title", "validators": { "required": {} }, "appeareance": { "editor": "single_line", "parameters": { "heading": false }, "addons": [] }, "position": 1 }, "relationships": { "item_type": { "data": { "type": "item_type", "id": "44" } } } }, "included": [ { "type": "item_type", "id": "44", "attributes": { "name": "Blog post", "api_key": "post", "collection_appeareance": "compact", "singleton": false, "all_locales_required": false, "sortable": true, "modular_block": false, "draft_mode_active": false, "tree": false, "ordering_direction": null, "has_singleton_item": true }, "relationships": { "menu_item": { "data": null }, "singleton_item": { "data": null }, "fields": { "data": [ { "type": "field", "id": "124" } ] }, "title_field": { "data": null }, "ordering_field": { "data": null } } } ] }