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
Specifies the production URL of the generated static website (deprecated, use `production_frontend_url`)
Example: "https://www.my-awesome-website.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
production_access_policy
null, string
Production configuration of the exigo authenticating proxy
Example: "{}"
production_deploy_adapter
null, string
Specify the deploy adapter to use
Example: "travis"
production_deploy_settings
null, object
Specify the deploy adapter options
Example:
{
  "api_token": "XXXYYY",
  "repo": "stefanoverna/sample-datocms-hugo-portfolio",
  "branch": "master",
  "config": null
}
production_deploy_status
string
Specifies deploy status
Example: "success"
production_frontend_url
null, string
Specifies the production URL of the generated static website
Example: "https://www.my-awesome-website.com"
production_last_deploy_at
null, string
Specifies the last time when a deploy occurred
Example: "2017-02-10T11:03:42.208Z"
production_scrape_status
string
Specifies scrape status
Example: "success"
production_spider_enabled
boolean
Whether DatoCMS should perform site spidering
Example: true
production_webhook_url
string
Webhook URL
Example: "https://webhooks.datocms.com/fc91489bdf5e37193e0/deploy-results"
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"
staging_access_policy
null, string
Staging configuration of the exigo authenticating proxy
Example: "{}"
staging_deploy_adapter
null, string
Specify the deploy adapter to use
Example: "travis"
staging_deploy_settings
null, object
Specify the deploy adapter options
Example:
{
  "api_token": "XXXYYY",
  "repo": "stefanoverna/sample-datocms-hugo-portfolio",
  "branch": "master",
  "config": null
}
staging_deploy_status
string
Specifies deploy status
Example: "success"
staging_frontend_url
null, string
Specifies the staging URL of the generated static website
Example: "https://staging.my-awesome-website.com"
staging_last_deploy_at
null, string
Specifies the last time when a deploy occurred
Example: "2017-02-10T11:03:42.208Z"
staging_scrape_status
string
Specifies scrape status
Example: "success"
staging_spider_enabled
boolean
Whether DatoCMS should perform site spidering
Example: true
staging_webhook_url
string
Webhook URL
Example: "https://webhooks.datocms.com/fc91489bdf5e37193e0/deploy-results"
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"
draft_mode_active
boolean
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
null, object
Field appeareance
Example:
{
  "type": "plain"
}
default_value
boolean, null, 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"

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

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"

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"
  }
}
environment
string
Environment
Example: "production"
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
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"
width
integer
Width of image
Example: 30

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_users
boolean
Can users invite other users?
Example: true
can_perform_site_search
boolean
Can perform site search
Example: true
can_publish_to_production
boolean
Can users publish to production environment?
Example: true
can_publish_to_staging
boolean
Can users publish to staging environment?
Example: true
name
string
The name of the role
Example: "Editor"
negative_item_type_permissions
array
positive_item_type_permissions
array