We use cookies to help our site work and to understand how it is used. By continuing to browse the site you're agreeing to our use of cookies.
Content Management API

Overview

DatoCMS is a headless, API-first content management system (CMS) that provides everything you need to power your web or mobile projects. To learn more about DatoCMS, visit our website or refer to our documentation site to understand what we do.

This document is a detailed reference to DatoCMS's Content Management API.

The Content Management API is used to manage the content of your DatoCMS projects. This includes creating, updating, deleting, and fetching content of your projects. To use the Content Management API, you will need to authenticate yourself with an API token. Read more about it in Authentication.

The Content Management APIs also include many GET requests. However, it is highly recommended that you always use the Content Delivery API to deliver content to your public-facing web or mobile projects.

Authentication

In order to make any Content Management API (CMA) requests, you need to first obtain a full-access API token. To retrieve this API token, enter your project administrative area (ie. http://your-project.admin.datocms.com) and go to the Settings > API Tokens section:

Once you have the API Token, you need to pass it as a header in each Content Management API request.

JSON Schema

The Content Management API exposes a machine-readable JSON schema that describes what resources are available via the API, what their URLs are, how they are represented and what operations they support.

This schema follows the JSON Schema format, combined with the draft Validation and Hypertext extensions.

The latest version of the API schema will always be available at the following URL:

https://site-api.datocms.com/docs/site-api-hyperschema.json

Official clients

DatoCMS ships with an official API client for Javascript and Ruby. In this document you will find examples of usage with both clients for each endpoint the API exposes.

Both clients are built upon the API JSON Schema, so they're guaranteed to be up-to-date with the API itself.

Site

A site represents a specific DatoCMS administrative area
Resource Attributes
deployable
boolean
Specifies whether all the deploy informations are correctly setup or not
Example: true
domain
null, string
Administrative area custom domain
Example: "admin.my-awesome-website.com"
favicon
null, string
The upload id for the favicon
Example: "123"
frontend_url
null, string
Frontend website url
Example: "https://www.mywebsite.com/"
global_seo
null, object
Specifies default global settings
imgix_host
null, string
Imgix host
Example: "www.datocms-assets.com"
internal_domain
null, string
DatoCMS internal domain for the administrative area
Example: "my-website.admin.datocms.com"
items_count
integer
Number of items present in the site
Example: 812
last_data_change_at
null, string
Specifies the last time when a change of data occurred
Example: "2017-03-30T09:29:14.872Z"
last_dump_at
null, string
Specifies the last time an integration plugin called the API
Example: "2017-02-10T11:03:42.208Z"
locales
array
Available locales
Example:
[
  "en"
]
name
string
Site name
Example: "My Awesome Website"
no_index
boolean
Whether the website needs to be indexed by search engines or not
Example: true
require_2fa
boolean
Specifies whether all users of this site need to authenticate using two-factor authentication
ssg
null, string
Specifies static site generator used
Example: "hugo"
theme
object
Specifies the theme to use in administrative area
theme_hue
integer
Specifies the hue to use primary color in Site backend
Example: 167
timezone
string
Site default timezone
Example: "Europe/London"

Record

DatoCMS stores the individual pieces of content you create from a Model as Records, which are much like table rows in a database. For backward-compatibility reasons, the API refers to records as "items".
Resource Attributes

Model

The way you define the kind of content you can edit inside your administrative area passes through the concept of Models, which are much like database tables. For backward-compatibility reasons, the API refers to models as "item types".
Resource Attributes
all_locales_required
boolean
api_key
string
Example: "post"
collection_appeareance
string
Example: "compact"
draft_mode_active
boolean
has_singleton_item
boolean
Example: true
modular_block
boolean
name
string
Example: "Blog post"
ordering_direction
null, string
singleton
boolean
sortable
boolean
Example: true
tree
boolean

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.
Resource Attributes
api_key
string
Field API key
Example: "title"
appeareance
object
Field appeareance
Example:
{
  "editor": "single_line",
  "parameters": {
    "heading": false
  },
  "addons": []
}
default_value
boolean, null, number, object, string
Default value for Field
Example: "some default value"
field_type
string
Type of input
Example: "string"
hint
null, string
Field hint
Example: "This field will be used as post title"
label
string
The label of the field
Example: "Title"
localized
boolean
Whether the field needs to be multilanguage or not
position
integer
Ordering index
Example: 1
validators
object
Optional field validations
Example:
{
  "required": {}
}

Editor

A DatoCMS administrative area can be accessed by multiple people. Every editor is linked to a specific Role, which describes what actions it will be able to perform once logged in.
Resource Attributes
email
string
Email
Example: "mark.smith@example.com"
first_name
string
First name
Example: "Mark"
last_name
string
Last name
Example: "Smith"
state
string
Status of user registration
Example: "REGISTERED"

Search result

DatoCMS Site Search is a way to deliver tailored search results to your site visitors. This is the endpoint you can use to query for results.
Resource Attributes
body_excerpt
string
First lines of body
Example: "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed eiusmod"
highlight
object
score
number
Score
Example: 11.3
title
string
Page title
Example: "My Page"
url
string
URL
Example: "Smith"

Menu Item

In DatoCMS you can organize the different Models present in your administrative area reordering and grouping them, so that their purpose will be more clear to the final editor.
Resource Attributes
label
string
The label of the menu item
Example: "Posts"
position
integer
Ordering index
Example: 1

Deploy activity

Represents an event occurred during the deploy process of your administrative area.
Resource Attributes
created_at
string
The moment the activity occurred
Example: "2016-09-20T18:50:24.914Z"
data
object
Any details regarding the event
Example:
{
  "request_body": "{\"object_kind\":\"build\",\"ref\":\"master\",\"tag\":false,\"before_sha\":\"0000000000000000000000000000000000000000\",\"sha\":\"ecfccf5ea28af900c14b499a2b762e029c7492\",\"build_id\":10495,\"build_name\":\"build\",\"build_stage\":\"test\",\"build_status\":\"success\",\"build_started_at\":\"2016-09-20 18:49:22 UTC\",\"build_finished_at\":\"2016-09-20 18:50:24 UTC\",\"build_duration\":62.279854524,\"build_allow_failure\":false,\"project_id\":195,\"project_name\":\"Stefano Verna / awesome-website\",\"user\":{\"id\":null,\"name\":null,\"email\":null},\"commit\":{\"id\":6754,\"sha\":\"ecfccf5ea28af900c6614b499a2b762e029c7492\",\"message\":\"Update gems\\n\",\"author_name\":\"Stefano Verna\",\"author_email\":\"s.verna@datocms.com\",\"status\":\"success\",\"duration\":62,\"started_at\":\"2016-09-20 18:49:22 UTC\",\"finished_at\":\"2016-09-20 18:50:24 UTC\"},\"repository\":{\"name\":\"awesome-website\",\"url\":\"git@gitlab.com:stefanoverna/awesome-website.git\",\"description\":\"\",\"visibility_level\":0}}",
  "request_headers": {
    "Via": "1.1 vegur",
    "Host": "webhooks.datocms.com",
    "Origin": null,
    "Version": "HTTP/1.1",
    "Connection": "close",
    "Connect-Time": "0",
    "X-Request-Id": "5c1beced-0fe3-4c5b-b45d-68ba4a15b5f3",
    "X-Gitlab-Event": "Build Hook",
    "X-Forwarded-For": "46.101.135.219",
    "X-Request-Start": "1474397424903",
    "Total-Route-Time": "0",
    "X-Forwarded-Port": "443",
    "X-Forwarded-Proto": "https"
  }
}
event_type
string
The type of activity
Example: "response_success"

API token

An API token allows access to our API. It is linked to a Role, which describes what actions can be performed.
Resource Attributes
hardcoded_type
null, string
name
string
Name of access token
Example: "Read-only API token"
token
string
The actual API token
Example: "XXXXXXXXXXXXXXX"

Upload permission

To upload a file in DatoCMS, first you need to obtain an upload permission through this API endpoint. The response will contain the S3 URL where you will be able to upload the file with a direct PUT request.
Resource Attributes
url
string
The URL to use to upload the file with a direct PUT request
Example: "https://dato-images.s3-eu-west-1.amazonaws.com/7/1455102967-image.png?X-Amz-Credential=AKIAJDTXTZHHDUCKAUMA%2F20160210"

Upload

Every file you upload to DatoCMS will be retrievable from this endpoint.
Resource Attributes
alt
null, string
Alt
Example: "Nyan the cat"
created_at
null, string
Date of upload
format
string
Format
Example: "jpg"
height
integer, null
Height of image
Example: 30
is_image
boolean
Is this upload an image?
Example: true
path
string
Upload path
Example: "/45/1496845848-digital-cats.jpg"
size
integer
size of the upload
Example: 444
title
null, string
Upload title
Example: "My cat"
url
string
Upload URL
Example: "https://www.datocms-assets.com/45/1496845848-digital-cats.jpg"
width
integer, null
Width of image
Example: 30

Plugin

Plugins enable developers to replace DatoCMS field components with HTML5 applications so the editing experiences of the DatoCMS web app can be customized.
Resource Attributes
description
null, string
A textual description for the plugin
Example: "A simple field editor that allows a nicer editing rating experience"
field_types
array
On which types of field this plugin can be used
Example:
[
  "integer",
  "float"
]
name
string
The name of the plugin
Example: "5 stars"
package_name
null, string
Plugin Npm package name
Example: "datocms-plugin-star-rating-editor"
package_version
null, string
Plugin Npm version
Example: "0.0.4"
parameter_definitions
object
Parameter definitions for the plugin
Example:
{
  "global": [
    {
      "id": "devMode",
      "type": "boolean",
      "label": "Run in development mode"
    }
  ],
  "instance": [
    {
      "id": "halfStars",
      "type": "boolean",
      "label": "Allow half stars ratings?",
      "default": false,
      "hint": "If enabled, rate using whole stars, if enabled, it doesn't use half-steps"
    },
    {
      "id": "totalStars",
      "type": "integer",
      "label": "Amount of stars to show",
      "default": 5,
      "hint": ""
    }
  ]
}
parameters
object
Global parameters which are set on on a project level. Values apply globally to every instance of an plugin within the project.
Example:
{
  "devMode": true
}
plugin_type
string
The type of extension
Example: "field"
url
string
The name of the plugin
Example: "https://cdn.rawgit.com/datocms/extensions/master/samples/five-stars/extension.js"

Webhook

A webhook allows to make requests following certain Dato events. It is linked to a Role, which describes what actions can be performed.
Resource Attributes
events
array
All the events you will be notified for
Example:
[
  {
    "entity_type": "item_type",
    "event_types": [
      "update",
      "create"
    ],
    "filter": {
      "entity_type": "item_type",
      "entity_ids": [
        "42",
        "43"
      ]
    }
  }
]
headers
object
Additional headers that will be sent
Example:
{
  "X-Foo": "Bar"
}
http_basic_password
null, string
HTTP Basic Authorization password
Example: "password"
http_basic_user
null, string
HTTP Basic Authorization username
Example: "user"
name
string
Unique name for the webhook
Example: "Item type creation/update"
url
string
The URL to be called
Example: "https://www.example.com/webhook"

Webhook call

Represents a log entry in the webhooks activity list.
Resource Attributes
created_at
string
The moment the call occurred
Example: "2016-09-20T18:50:24.914Z"
entity_type
string
The subject of webhook triggering
Example: "item"
event_type
string
The event that triggers the webhook call
Example: "update"
request_headers
object
The request's headers
Example:
{
  "Accept": "*/*",
  "User-Agent": "DatoCMS (datocms.com)",
  "Authorization": "Basic Y2lhbzptaWFv",
  "Content-Type": "application/json"
}
request_payload
string
The body of the request
Example: "{ \"entity_type\": \"item\", \"event_type\": \"update\", \"entity\": { \"id\": \"293467\", \"type\": \"item\", \"attributes\": { \"created_at\": \"2018-05-22T10:13:00.461Z\", \"updated_at\": \"2018-07-30T14:13:50.068Z\", \"is_valid\": true, \"avatar\": { \"path\": \"/205/1526984443-untitled-drawing.png\", \"format\": \"png\", \"size\": 242630, \"alt\": null, \"title\": null, \"width\": 329, \"height\": 286 }, \"name\": \"3Francesco Falchy\", \"gallery\": [] }, \"relationships\": { \"item_type\": { \"data\": { \"id\": \"1423\", \"type\": \"item_type\" } }, \"published_version\": { \"data\": { \"id\": \"670532\", \"type\": \"item_version\" } }, \"current_version\": { \"data\": { \"id\": \"670532\", \"type\": \"item_version\" } } } } }"
request_url
string
The url that the webhook called
Example: "https://www.example.com/webhook"
response_headers
object
The response's headers
Example:
{
  "via": "1.1 vegur, 1.1 37c0945d19329fccc23efb283d01aa06.cloudfront.net (CloudFront)",
  "date": "Fri, 27 Jul 2018 11:59:20 GMT",
  "server": "gunicorn/19.6.0"
}
response_payload
null, string
The body of the response
Example: "ok"
response_status
integer, null
The status of the response
Example: 200

Deployment environment

Configuration for different deployment environments. You can have different staging and production environments in order to test your site before final deploy
Resource Attributes
access_policy
null, string
Additional access policy
deploy_adapter
string
The deploy adapter
Example: "netlify"
deploy_settings
object
Additional configuration for deploy
Example:
{
  "trigger_url": "https://api.netlify.com/build_hooks/XXX",
  "site_id": "XXX",
  "access_token": "YYY"
}
deploy_status
string
Status of last deploy
Example: "success"
frontend_url
null, string
Public url of the site
Example: "https://www.mywebsite.com/"
last_build_at
null, string
Timestamp of the last build
Example: "2017-03-30T09:29:14.872Z"
last_deploy_at
null, string
Timestamp of the last deploy
Example: "2017-03-30T09:29:14.872Z"
name
string
Name of the environment
Example: "Production"
scrape_status
string
Status of site scraper
Example: "success"
spider_enabled
boolean
Enable scraper on the site
Example: true
webhook_token
string
Unique token of the webhook
Example: "xA1239ajsk123"
webhook_url
string
Notification webhook URL
Example: "https://webhooks.datocoms.com/xA1239ajsk123/deploy-results"

Role

A Role represents a specific set of actions an editor (or an API token) can perform on your administrative area.
Resource Attributes
can_edit_favicon
boolean
Can users edit the site favicon/global SEO settings?
Example: true
can_edit_schema
boolean
Can users edit the schema?
Example: true
can_edit_site
boolean
Can users edit the site settings?
Example: true
can_manage_access_tokens
boolean
Can manage access tokens
Example: true
can_manage_deployment_environments
boolean
Can users manage deployment environments?
Example: true
can_manage_users
boolean
Can users invite other users?
Example: true
can_manage_webhooks
boolean
Can users manage webhooks?
Example: true
can_perform_site_search
boolean
Can perform site search
Example: true
name
string
The name of the role
Example: "Editor"
negative_deployment_environment_permissions
array
negative_item_type_permissions
array
positive_deployment_environment_permissions
array
positive_item_type_permissions
array