Site Management API

Session

A session is required to access to read-and-write API endpoints

Attributes

Name Type Description Example
id string JSON web token for the session "eyJCJhbGci.eyJhaWwuY29tIn0.32wQOMci"
relationships:user:data:id string ID of editor "312"
relationships:user:data:type string JSON API type field
pattern: ^user$
"user"
type string JSON API type field
pattern: ^session$
"session"

Session Create

Create a new session

POST /sessions

Required Parameters

Name Type Description Example
data string

Curl Example

Bash
$ curl -n -X POST https://site-api.datocms.com/sessions \
  -d '{
  "data": {
    "type": "email_credentials",
    "attributes": {
      "email": "foo@bar.com",
      "password": "changeme"
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 201 Created
Json
{
  "data": {
    "type": "session",
    "id": "eyJCJhbGci.eyJhaWwuY29tIn0.32wQOMci",
    "relationships": {
      "user": {
        "data": {
          "type": "user",
          "id": "312"
        }
      }
    }
  },
  "included": [
    {
      "type": "user",
      "id": "312",
      "attributes": {
        "email": "mark.smith@example.com",
        "first_name": "Mark",
        "last_name": "Smith",
        "state": "REGISTERED"
      }
    }
  ]
}

Account

DatoCMS account

Attributes

Name Type Description Example
attributes:api_token string API token "example"
attributes:email string Email "foo@bar.com"
attributes:password string Password "example"
attributes:valid_card boolean Whether the account has a valid credit card true
id string ID of account "312"
type string JSON API type field
pattern: ^account$
"account"

Editor

DatoCMS editor

Attributes

Name Type Description Example
attributes:email string Email "mark.smith@example.com"
attributes:first_name string First name "Mark"
attributes:last_name string Last name "Smith"
attributes:state string Status of user registration
one of:"REGISTERED" or "INVITATION_PENDING"
"REGISTERED"
id string ID of editor "312"
type string JSON API type field
pattern: ^user$
"user"

Editor Create

Invite a new editor

POST /users

Required Parameters

Name Type Description Example
data:attributes:email string Email "mark.smith@example.com"
data:attributes:first_name string First name "Mark"
data:attributes:last_name string Last name "Smith"
data:type string JSON API type field
pattern: ^user$
"user"

Curl Example

Bash
$ curl -n -X POST https://site-api.datocms.com/users \
  -d '{
  "data": {
    "type": "user",
    "attributes": {
      "email": "mark.smith@example.com",
      "first_name": "Mark",
      "last_name": "Smith"
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 201 Created
Json
{
  "data": {
    "type": "user",
    "id": "312",
    "attributes": {
      "email": "mark.smith@example.com",
      "first_name": "Mark",
      "last_name": "Smith",
      "state": "REGISTERED"
    }
  }
}

Editor Update

Updates a editor

PUT /users/{user_id}

Required Parameters

Name Type Description Example
data:attributes:email string Email "mark.smith@example.com"
data:attributes:first_name string First name "Mark"
data:attributes:last_name string Last name "Smith"
data:attributes:password string Password "supersecret"
data:id string ID of editor "312"
data:type string JSON API type field
pattern: ^user$
"user"

Curl Example

Bash
$ curl -n -X PUT https://site-api.datocms.com/users/$USER_ID \
  -d '{
  "data": {
    "type": "user",
    "id": "312",
    "attributes": {
      "email": "mark.smith@example.com",
      "first_name": "Mark",
      "last_name": "Smith",
      "password": "supersecret"
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "user",
    "id": "312",
    "attributes": {
      "email": "mark.smith@example.com",
      "first_name": "Mark",
      "last_name": "Smith",
      "state": "REGISTERED"
    }
  }
}

Editor Index

Lists editors

GET /users

Curl Example

Bash
$ curl -n https://site-api.datocms.com/users \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": [
    {
      "type": "user",
      "id": "312",
      "attributes": {
        "email": "mark.smith@example.com",
        "first_name": "Mark",
        "last_name": "Smith",
        "state": "REGISTERED"
      }
    }
  ]
}

Editor Show

Show editor

GET /users/{user_id}

Curl Example

Bash
$ curl -n https://site-api.datocms.com/users/$USER_ID \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "user",
    "id": "312",
    "attributes": {
      "email": "mark.smith@example.com",
      "first_name": "Mark",
      "last_name": "Smith",
      "state": "REGISTERED"
    }
  }
}

Editor Reset password

Request a password reset

POST /users/reset_password

Required Parameters

Name Type Description Example
data:attributes:email string Email "mark.smith@example.com"
data:type string JSON API type field
pattern: ^user$
"user"

Curl Example

Bash
$ curl -n -X POST https://site-api.datocms.com/users/reset_password \
  -d '{
  "data": {
    "type": "user",
    "attributes": {
      "email": "mark.smith@example.com"
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "type": "user",
  "id": "312",
  "attributes": {
    "email": "mark.smith@example.com",
    "first_name": "Mark",
    "last_name": "Smith",
    "state": "REGISTERED"
  }
}

Editor Delete

Deletes a editor

DELETE /users/{user_id}

Curl Example

Bash
$ curl -n -X DELETE https://site-api.datocms.com/users/$USER_ID \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "user",
    "id": "312",
    "attributes": {
      "email": "mark.smith@example.com",
      "first_name": "Mark",
      "last_name": "Smith",
      "state": "REGISTERED"
    }
  }
}

Site

A site represents a specific DatoCMS administrative area

Attributes

Name Type Description Example
attributes:deployable boolean Specifies whether all the deploy informations are correctly setup or not true
attributes:domain nullable string Administrative area custom domain "admin.my-awesome-website.com"
attributes:favicon nullable object null
attributes:favicon:format string Image format
one of:"png" or "jpg" or "gif"
"png"
attributes:favicon:height integer Image height 500
attributes:favicon:path string The S3 path where the file is stored "/7/1455102967-image.png"
attributes:favicon:size integer The size of the image in bytes 424112
attributes:favicon:width integer Image width 400
attributes:frontend_url nullable string Specifies the URL of the generated static website "https://www.my-awesome-website.com"
attributes:global_seo nullable object Specifies default global settings null
attributes:global_seo:facebook_page_url nullable string URL of facebook page "http://facebook.com/awesomewebsite"
attributes:global_seo:fallback_seo:description string "Default meta description"
attributes:global_seo:fallback_seo:image nullable object null
attributes:global_seo:fallback_seo:image:format string Image format
one of:"png" or "jpg" or "gif"
"png"
attributes:global_seo:fallback_seo:image:height integer Image height 500
attributes:global_seo:fallback_seo:image:path string The S3 path where the file is stored "/7/1455102967-image.png"
attributes:global_seo:fallback_seo:image:size integer The size of the image in bytes 424112
attributes:global_seo:fallback_seo:image:width integer Image width 400
attributes:global_seo:fallback_seo:title string "Default meta title"
attributes:global_seo:site_name string Site name, used in social sharing "My Awesome Website"
attributes:global_seo:title_suffix nullable string Title meta tag suffix " - My Awesome Website"
attributes:global_seo:twitter_account nullable string Twitter account associated to website "@awesomewebsite"
attributes:imgix_host nullable string Imgix host "www.datocms-assets.com"
attributes:internal_domain nullable string DatoCMS internal domain for the administrative area "my-website.admin.datocms.com"
attributes:items_count integer Number of items present in the site 812
attributes:last_data_change_at nullable date-time Specifies the last time when a change of data occurred "2017-03-30T09:29:14.872Z"
attributes:last_dump_at nullable date-time Specifies the last time an integration plugin called the API "2017-02-10T11:03:42.208Z"
attributes:locales array Available locales ["en"]
attributes:name string Site name "My Awesome Website"
attributes:no_index boolean Whether the website needs to be indexed by search engines or not true
attributes:production_deploy_adapter nullable string Specify the deploy adapter to use "travis"
attributes:production_deploy_settings nullable object Specify the deploy adapter options {"api_token":"XXXYYY","repo":"stefanoverna/sample-datocms-hugo-portfolio","branch":"master","config":null}
attributes:production_deploy_status string Specifies deploy status
one of:"unstarted" or "pending" or "success" or "fail"
"success"
attributes:production_last_deploy_at nullable date-time Specifies the last time when a deploy occurred "2017-02-10T11:03:42.208Z"
attributes:production_webhook_url string Webhook URL "https://webhooks.datocms.com/fc91489bdf5e37193e0/deploy-results"
attributes:readonly_token string The read-only API token for this Site "2808246340fce4da464"
attributes:readwrite_token string Specify the read-write API token for this Site "ba3e0791d160e5f2a70"
attributes:ssg nullable string Specifies static site generator used "hugo"
attributes:staging_deploy_adapter nullable string Specify the deploy adapter to use "travis"
attributes:staging_deploy_settings nullable object Specify the deploy adapter options {"api_token":"XXXYYY","repo":"stefanoverna/sample-datocms-hugo-portfolio","branch":"master","config":null}
attributes:staging_deploy_status string Specifies deploy status
one of:"unstarted" or "pending" or "success" or "fail"
"success"
attributes:staging_last_deploy_at nullable date-time Specifies the last time when a deploy occurred "2017-02-10T11:03:42.208Z"
attributes:staging_webhook_url string Webhook URL "https://webhooks.datocms.com/fc91489bdf5e37193e0/deploy-results"
attributes:theme_hue integer Specifies the hue to use primary color in Site backend 167
attributes:timezone string Site default timezone "Europe/London"
id string ID of site "155"
relationships:account:data:id string ID of account "312"
relationships:account:data:type string JSON API type field
pattern: ^account$
"account"
relationships:item_types:data array The list of site item types [{"type":"item_type","id":"44"}]
relationships:menu_items:data array The list of site menu items [{"type":"menu_item","id":"34"}]
relationships:users:data array The list of site users [{"type":"user","id":"312"}]
type string JSON API type field
pattern: ^site$
"site"

Site Show

Retrieve a site

GET /site

Curl Example

Bash
$ curl -n https://site-api.datocms.com/site \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "site",
    "id": "155",
    "attributes": {
      "name": "My Awesome Website",
      "domain": "admin.my-awesome-website.com",
      "imgix_host": "www.datocms-assets.com",
      "production_webhook_url": "https://webhooks.datocms.com/fc91489bdf5e37193e0/deploy-results",
      "staging_webhook_url": "https://webhooks.datocms.com/fc91489bdf5e37193e0/deploy-results",
      "internal_domain": "my-website.admin.datocms.com",
      "locales": [
        "en"
      ],
      "timezone": "Europe/London",
      "items_count": 812,
      "no_index": true,
      "favicon": {
        "path": "/7/1455102967-image.png",
        "width": 400,
        "height": 500,
        "format": "png",
        "size": 424112
      },
      "theme_hue": 167,
      "production_deploy_adapter": "travis",
      "production_deploy_settings": {
        "api_token": "XXXYYY",
        "repo": "stefanoverna/sample-datocms-hugo-portfolio",
        "branch": "master",
        "config": null
      },
      "staging_deploy_adapter": "travis",
      "staging_deploy_settings": {
        "api_token": "XXXYYY",
        "repo": "stefanoverna/sample-datocms-hugo-portfolio",
        "branch": "master",
        "config": null
      },
      "readonly_token": "2808246340fce4da464",
      "readwrite_token": "ba3e0791d160e5f2a70",
      "last_data_change_at": "2017-03-30T09:29:14.872Z",
      "production_last_deploy_at": "2017-02-10T11:03:42.208Z",
      "staging_last_deploy_at": "2017-02-10T11:03:42.208Z",
      "last_dump_at": "2017-02-10T11:03:42.208Z",
      "deployable": true,
      "production_deploy_status": "success",
      "staging_deploy_status": "success",
      "ssg": "hugo",
      "frontend_url": "https://www.my-awesome-website.com",
      "global_seo": {
        "site_name": "My Awesome Website",
        "fallback_seo": {
          "title": "Default meta title",
          "description": "Default meta description",
          "image": {
            "path": "/7/1455102967-image.png",
            "width": 400,
            "height": 500,
            "format": "png",
            "size": 424112
          }
        },
        "title_suffix": " - My Awesome Website",
        "facebook_page_url": "http://facebook.com/awesomewebsite",
        "twitter_account": "@awesomewebsite"
      }
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "312"
        }
      },
      "menu_items": {
        "data": [
          {
            "type": "menu_item",
            "id": "34"
          }
        ]
      },
      "users": {
        "data": [
          {
            "type": "user",
            "id": "312"
          }
        ]
      },
      "item_types": {
        "data": [
          {
            "type": "item_type",
            "id": "44"
          }
        ]
      }
    }
  },
  "included": [
    null
  ]
}

Site Update

Updates a site settings

PUT /site

Required Parameters

Name Type Description Example
data:attributes:favicon nullable object null
data:attributes:favicon:format string Image format
one of:"png" or "jpg" or "gif"
"png"
data:attributes:favicon:height integer Image height 500
data:attributes:favicon:path string The S3 path where the file is stored "/7/1455102967-image.png"
data:attributes:favicon:size integer The size of the image in bytes 424112
data:attributes:favicon:width integer Image width 400
data:attributes:frontend_url nullable string Specifies the URL of the generated static website "https://www.my-awesome-website.com"
data:attributes:global_seo nullable object Specifies default global settings null
data:attributes:global_seo:facebook_page_url nullable string URL of facebook page "http://facebook.com/awesomewebsite"
data:attributes:global_seo:fallback_seo:description string "Default meta description"
data:attributes:global_seo:fallback_seo:image nullable object null
data:attributes:global_seo:fallback_seo:image:format string Image format
one of:"png" or "jpg" or "gif"
"png"
data:attributes:global_seo:fallback_seo:image:height integer Image height 500
data:attributes:global_seo:fallback_seo:image:path string The S3 path where the file is stored "/7/1455102967-image.png"
data:attributes:global_seo:fallback_seo:image:size integer The size of the image in bytes 424112
data:attributes:global_seo:fallback_seo:image:width integer Image width 400
data:attributes:global_seo:fallback_seo:title string "Default meta title"
data:attributes:global_seo:site_name string Site name, used in social sharing "My Awesome Website"
data:attributes:global_seo:title_suffix nullable string Title meta tag suffix " - My Awesome Website"
data:attributes:global_seo:twitter_account nullable string Twitter account associated to website "@awesomewebsite"
data:attributes:locales array Available locales ["en"]
data:attributes:name string Site name "My Awesome Website"
data:attributes:no_index boolean Whether the website needs to be indexed by search engines or not true
data:attributes:production_deploy_adapter nullable string Specify the deploy adapter to use "travis"
data:attributes:production_deploy_settings nullable object Specify the deploy adapter options {"api_token":"XXXYYY","repo":"stefanoverna/sample-datocms-hugo-portfolio","branch":"master","config":null}
data:attributes:ssg nullable string Specifies static site generator used "hugo"
data:attributes:staging_deploy_adapter nullable string Specify the deploy adapter to use "travis"
data:attributes:staging_deploy_settings nullable object Specify the deploy adapter options {"api_token":"XXXYYY","repo":"stefanoverna/sample-datocms-hugo-portfolio","branch":"master","config":null}
data:attributes:theme_hue integer Specifies the hue to use primary color in Site backend 167
data:attributes:timezone string Site default timezone "Europe/London"
data:id string ID of site "155"
data:type string JSON API type field
pattern: ^site$
"site"

Curl Example

Bash
$ curl -n -X PUT https://site-api.datocms.com/site \
  -d '{
  "data": {
    "type": "site",
    "id": "155",
    "attributes": {
      "no_index": true,
      "favicon": {
        "path": "/7/1455102967-image.png",
        "width": 400,
        "height": 500,
        "format": "png",
        "size": 424112
      },
      "global_seo": {
        "site_name": "My Awesome Website",
        "fallback_seo": {
          "title": "Default meta title",
          "description": "Default meta description",
          "image": {
            "path": "/7/1455102967-image.png",
            "width": 400,
            "height": 500,
            "format": "png",
            "size": 424112
          }
        },
        "title_suffix": " - My Awesome Website",
        "facebook_page_url": "http://facebook.com/awesomewebsite",
        "twitter_account": "@awesomewebsite"
      },
      "name": "My Awesome Website",
      "theme_hue": 167,
      "production_deploy_adapter": "travis",
      "production_deploy_settings": {
        "api_token": "XXXYYY",
        "repo": "stefanoverna/sample-datocms-hugo-portfolio",
        "branch": "master",
        "config": null
      },
      "staging_deploy_adapter": "travis",
      "staging_deploy_settings": {
        "api_token": "XXXYYY",
        "repo": "stefanoverna/sample-datocms-hugo-portfolio",
        "branch": "master",
        "config": null
      },
      "locales": [
        "en"
      ],
      "timezone": "Europe/London",
      "ssg": "hugo",
      "frontend_url": "https://www.my-awesome-website.com"
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "site",
    "id": "155",
    "attributes": {
      "name": "My Awesome Website",
      "domain": "admin.my-awesome-website.com",
      "imgix_host": "www.datocms-assets.com",
      "production_webhook_url": "https://webhooks.datocms.com/fc91489bdf5e37193e0/deploy-results",
      "staging_webhook_url": "https://webhooks.datocms.com/fc91489bdf5e37193e0/deploy-results",
      "internal_domain": "my-website.admin.datocms.com",
      "locales": [
        "en"
      ],
      "timezone": "Europe/London",
      "items_count": 812,
      "no_index": true,
      "favicon": {
        "path": "/7/1455102967-image.png",
        "width": 400,
        "height": 500,
        "format": "png",
        "size": 424112
      },
      "theme_hue": 167,
      "production_deploy_adapter": "travis",
      "production_deploy_settings": {
        "api_token": "XXXYYY",
        "repo": "stefanoverna/sample-datocms-hugo-portfolio",
        "branch": "master",
        "config": null
      },
      "staging_deploy_adapter": "travis",
      "staging_deploy_settings": {
        "api_token": "XXXYYY",
        "repo": "stefanoverna/sample-datocms-hugo-portfolio",
        "branch": "master",
        "config": null
      },
      "readonly_token": "2808246340fce4da464",
      "readwrite_token": "ba3e0791d160e5f2a70",
      "last_data_change_at": "2017-03-30T09:29:14.872Z",
      "production_last_deploy_at": "2017-02-10T11:03:42.208Z",
      "staging_last_deploy_at": "2017-02-10T11:03:42.208Z",
      "last_dump_at": "2017-02-10T11:03:42.208Z",
      "deployable": true,
      "production_deploy_status": "success",
      "staging_deploy_status": "success",
      "ssg": "hugo",
      "frontend_url": "https://www.my-awesome-website.com",
      "global_seo": {
        "site_name": "My Awesome Website",
        "fallback_seo": {
          "title": "Default meta title",
          "description": "Default meta description",
          "image": {
            "path": "/7/1455102967-image.png",
            "width": 400,
            "height": 500,
            "format": "png",
            "size": 424112
          }
        },
        "title_suffix": " - My Awesome Website",
        "facebook_page_url": "http://facebook.com/awesomewebsite",
        "twitter_account": "@awesomewebsite"
      }
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "312"
        }
      },
      "menu_items": {
        "data": [
          {
            "type": "menu_item",
            "id": "34"
          }
        ]
      },
      "users": {
        "data": [
          {
            "type": "user",
            "id": "312"
          }
        ]
      },
      "item_types": {
        "data": [
          {
            "type": "item_type",
            "id": "44"
          }
        ]
      }
    }
  }
}

A menu item helps organize item types within the backend interface

Attributes

Name Type Description Example
attributes:label string The label of the menu item "Posts"
attributes:position integer Ordering index 1
id string ID of menu item "34"
relationships:children:data array [{"type":"menu_item","id":"34"}]
relationships:item_type:data string JSON API data
relationships:parent:data string JSON API data
type string JSON API type field
pattern: ^menu_item$
"menu_item"

Create a new menu item

POST /menu-items

Required Parameters

Name Type Description Example
data:attributes:label string The label of the menu item "Posts"
data:attributes:position integer Ordering index 1
data:relationships:item_type:data string JSON API data
data:relationships:parent:data string JSON API data
data:type string JSON API type field
pattern: ^menu_item$
"menu_item"

Curl Example

Bash
$ curl -n -X POST https://site-api.datocms.com/menu-items \
  -d '{
  "data": {
    "type": "menu_item",
    "attributes": {
      "label": "Posts",
      "position": 1
    },
    "relationships": {
      "item_type": {
        "data": {
          "type": "item_type",
          "id": "44"
        }
      },
      "parent": {
        "data": null
      }
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 201 Created
Json
{
  "data": {
    "type": "menu_item",
    "id": "34",
    "attributes": {
      "label": "Posts",
      "position": 1
    },
    "relationships": {
      "item_type": {
        "data": {
          "type": "item_type",
          "id": "44"
        }
      },
      "parent": {
        "data": null
      },
      "children": {
        "data": [
          {
            "type": "menu_item",
            "id": "34"
          }
        ]
      }
    }
  }
}

Updates a menu item

PUT /menu-items/{menu_item_id}

Required Parameters

Name Type Description Example
data:attributes:label string The label of the menu item "Posts"
data:attributes:position integer Ordering index 1
data:id string ID of menu item "34"
data:relationships:item_type:data string JSON API data
data:relationships:parent:data string JSON API data
data:type string JSON API type field
pattern: ^menu_item$
"menu_item"

Curl Example

Bash
$ curl -n -X PUT https://site-api.datocms.com/menu-items/$MENU_ITEM_ID \
  -d '{
  "data": {
    "type": "menu_item",
    "id": "34",
    "attributes": {
      "label": "Posts",
      "position": 1
    },
    "relationships": {
      "item_type": {
        "data": {
          "type": "item_type",
          "id": "44"
        }
      },
      "parent": {
        "data": null
      }
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "menu_item",
    "id": "34",
    "attributes": {
      "label": "Posts",
      "position": 1
    },
    "relationships": {
      "item_type": {
        "data": {
          "type": "item_type",
          "id": "44"
        }
      },
      "parent": {
        "data": null
      },
      "children": {
        "data": [
          {
            "type": "menu_item",
            "id": "34"
          }
        ]
      }
    }
  }
}

Lists menu items

GET /menu-items

Curl Example

Bash
$ curl -n https://site-api.datocms.com/menu-items \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": [
    {
      "type": "menu_item",
      "id": "34",
      "attributes": {
        "label": "Posts",
        "position": 1
      },
      "relationships": {
        "item_type": {
          "data": {
            "type": "item_type",
            "id": "44"
          }
        },
        "parent": {
          "data": null
        },
        "children": {
          "data": [
            {
              "type": "menu_item",
              "id": "34"
            }
          ]
        }
      }
    }
  ]
}

Show menu item

GET /menu-items/{menu_item_id}

Curl Example

Bash
$ curl -n https://site-api.datocms.com/menu-items/$MENU_ITEM_ID \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "menu_item",
    "id": "34",
    "attributes": {
      "label": "Posts",
      "position": 1
    },
    "relationships": {
      "item_type": {
        "data": {
          "type": "item_type",
          "id": "44"
        }
      },
      "parent": {
        "data": null
      },
      "children": {
        "data": [
          {
            "type": "menu_item",
            "id": "34"
          }
        ]
      }
    }
  }
}

Deletes menu item

DELETE /menu-items/{menu_item_id}

Curl Example

Bash
$ curl -n -X DELETE https://site-api.datocms.com/menu-items/$MENU_ITEM_ID \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "menu_item",
    "id": "34",
    "attributes": {
      "label": "Posts",
      "position": 1
    },
    "relationships": {
      "item_type": {
        "data": {
          "type": "item_type",
          "id": "44"
        }
      },
      "parent": {
        "data": null
      },
      "children": {
        "data": [
          {
            "type": "menu_item",
            "id": "34"
          }
        ]
      }
    }
  }
}

Deploy activity

Represents an event occurred during the deploy process

Attributes

Name Type Description Example
attributes:created_at date-time The moment the activity occurred "2016-09-20T18:50:24.914Z"
attributes:data object Any details regarding the event {"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"}}
attributes:environment string Environment
one of:"production" or "staging"
"production"
attributes:event_type string The type of activity
one of:"request" or "request_failed" or "response_success" or "response_failure" or "response_timeout"
"response_success"
id string ID of menu item "34"
relationships:site:data:id string ID of site "155"
relationships:site:data:type string JSON API type field
pattern: ^site$
"site"
type string JSON API type field
pattern: ^deploy_event$
"deploy_event"

Deploy activity Index

Lists deploy events

GET /deploy-events

Curl Example

Bash
$ curl -n https://site-api.datocms.com/deploy-events \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": [
    {
      "type": "deploy_event",
      "id": "34",
      "attributes": {
        "event_type": "response_success",
        "environment": "production",
        "created_at": "2016-09-20T18:50:24.914Z",
        "data": {
          "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"
          }
        }
      },
      "relationships": {
        "site": {
          "data": {
            "type": "site",
            "id": "155"
          }
        }
      }
    }
  ]
}

Deploy activity Show

Show deploy event

GET /deploy-events/{deploy_event_id}

Curl Example

Bash
$ curl -n https://site-api.datocms.com/deploy-events/$DEPLOY_EVENT_ID \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "deploy_event",
    "id": "34",
    "attributes": {
      "event_type": "response_success",
      "environment": "production",
      "created_at": "2016-09-20T18:50:24.914Z",
      "data": {
        "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"
        }
      }
    },
    "relationships": {
      "site": {
        "data": {
          "type": "site",
          "id": "155"
        }
      }
    }
  }
}

Model

A model is a specific kind of editable content

Attributes

Name Type Description Example
attributes:api_key string "post"
attributes:name string "Blog post"
attributes:ordering_direction nullable string
one of:null or "asc" or "desc"
"desc"
attributes:singleton boolean true
attributes:sortable boolean true
id string ID of item type "44"
relationships:fields:data array [{"type":"field","id":"124"}]
relationships:menu_item:data string JSON API data
relationships:ordering_field:data string JSON API data
relationships:singleton_item:data string JSON API data
type string JSON API type field
pattern: ^item_type$
"item_type"

Model Create

Create a new model

POST /item-types

Required Parameters

Name Type Description Example
data:attributes:api_key string "post"
data:attributes:name string "Blog post"
data:attributes:ordering_direction nullable string
one of:null or "asc" or "desc"
"desc"
data:attributes:singleton boolean true
data:attributes:sortable boolean true
data:relationships:ordering_field:data string JSON API data
data:type string JSON API type field
pattern: ^item_type$
"item_type"

Curl Example

Bash
$ curl -n -X POST https://site-api.datocms.com/item-types \
  -d '{
  "data": {
    "type": "item_type",
    "attributes": {
      "name": "Blog post",
      "api_key": "post",
      "singleton": true,
      "sortable": true,
      "ordering_direction": "desc"
    },
    "relationships": {
      "ordering_field": {
        "data": null
      }
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 201 Created
Json
{
  "data": {
    "type": "item_type",
    "id": "44",
    "attributes": {
      "name": "Blog post",
      "api_key": "post",
      "singleton": true,
      "sortable": true,
      "ordering_direction": "desc"
    },
    "relationships": {
      "menu_item": {
        "data": null
      },
      "singleton_item": {
        "data": null
      },
      "fields": {
        "data": [
          {
            "type": "field",
            "id": "124"
          }
        ]
      },
      "ordering_field": {
        "data": null
      }
    }
  },
  "included": [
    null
  ]
}

Model Update

Updates a model

PUT /item-types/{item_type_id}

Required Parameters

Name Type Description Example
data:attributes:api_key string "post"
data:attributes:name string "Blog post"
data:attributes:ordering_direction nullable string
one of:null or "asc" or "desc"
"desc"
data:attributes:singleton boolean true
data:attributes:sortable boolean true
data:id string ID of item type "44"
data:relationships:ordering_field:data string JSON API data
data:type string JSON API type field
pattern: ^item_type$
"item_type"

Curl Example

Bash
$ curl -n -X PUT https://site-api.datocms.com/item-types/$ITEM_TYPE_ID \
  -d '{
  "data": {
    "type": "item_type",
    "id": "44",
    "attributes": {
      "name": "Blog post",
      "api_key": "post",
      "singleton": true,
      "sortable": true,
      "ordering_direction": "desc"
    },
    "relationships": {
      "ordering_field": {
        "data": null
      }
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "item_type",
    "id": "44",
    "attributes": {
      "name": "Blog post",
      "api_key": "post",
      "singleton": true,
      "sortable": true,
      "ordering_direction": "desc"
    },
    "relationships": {
      "menu_item": {
        "data": null
      },
      "singleton_item": {
        "data": null
      },
      "fields": {
        "data": [
          {
            "type": "field",
            "id": "124"
          }
        ]
      },
      "ordering_field": {
        "data": null
      }
    }
  }
}

Model Index

Lists models

GET /item-types

Curl Example

Bash
$ curl -n https://site-api.datocms.com/item-types \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": [
    {
      "type": "item_type",
      "id": "44",
      "attributes": {
        "name": "Blog post",
        "api_key": "post",
        "singleton": true,
        "sortable": true,
        "ordering_direction": "desc"
      },
      "relationships": {
        "menu_item": {
          "data": null
        },
        "singleton_item": {
          "data": null
        },
        "fields": {
          "data": [
            {
              "type": "field",
              "id": "124"
            }
          ]
        },
        "ordering_field": {
          "data": null
        }
      }
    }
  ]
}

Model Show

Show model

GET /item-types/{item_type_id}

Curl Example

Bash
$ curl -n https://site-api.datocms.com/item-types/$ITEM_TYPE_ID \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "item_type",
    "id": "44",
    "attributes": {
      "name": "Blog post",
      "api_key": "post",
      "singleton": true,
      "sortable": true,
      "ordering_direction": "desc"
    },
    "relationships": {
      "menu_item": {
        "data": null
      },
      "singleton_item": {
        "data": null
      },
      "fields": {
        "data": [
          {
            "type": "field",
            "id": "124"
          }
        ]
      },
      "ordering_field": {
        "data": null
      }
    }
  }
}

Model Delete

Deletes model

DELETE /item-types/{item_type_id}

Curl Example

Bash
$ curl -n -X DELETE https://site-api.datocms.com/item-types/$ITEM_TYPE_ID \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "item_type",
    "id": "44",
    "attributes": {
      "name": "Blog post",
      "api_key": "post",
      "singleton": true,
      "sortable": true,
      "ordering_direction": "desc"
    },
    "relationships": {
      "menu_item": {
        "data": null
      },
      "singleton_item": {
        "data": null
      },
      "fields": {
        "data": [
          {
            "type": "field",
            "id": "124"
          }
        ]
      },
      "ordering_field": {
        "data": null
      }
    }
  }
}

Field

A field represents a single chunk of data associated to a item type

Attributes

Name Type Description Example
attributes:api_key string Field API key "title"
attributes:appeareance nullable object Field appeareance {"type":["plain"]}
attributes:field_type string Type of input "string"
attributes:hint nullable string Field hint "This field will be used as post title"
attributes:label string The label of the field "Title"
attributes:localized boolean Whether the field needs to be multilanguage or not true
attributes:position integer Ordering index 1
attributes:validators object Optional field validations {"required":{}}
id string ID of field "124"
relationships:item_type:data:id string ID of item type "44"
relationships:item_type:data:type string JSON API type field
pattern: ^item_type$
"item_type"
type string JSON API type field
pattern: ^field$
"field"

Field Create

Create a new field

POST /item-types/{item_type_id}/fields

Required Parameters

Name Type Description Example
data:attributes:api_key string Field API key "title"
data:attributes:appeareance nullable object Field appeareance {"type":["plain"]}
data:attributes:field_type string Type of input "string"
data:attributes:hint nullable string Field hint "This field will be used as post title"
data:attributes:label string The label of the field "Title"
data:attributes:localized boolean Whether the field needs to be multilanguage or not true
data:attributes:position integer Ordering index 1
data:attributes:validators object Optional field validations {"required":{}}
data:type string JSON API type field
pattern: ^field$
"field"

Curl Example

Bash
$ curl -n -X POST https://site-api.datocms.com/item-types/$ITEM_TYPE_ID/fields \
  -d '{
  "data": {
    "type": "field",
    "attributes": {
      "label": "Title",
      "field_type": "string",
      "localized": true,
      "api_key": "title",
      "hint": "This field will be used as post title",
      "validators": {
        "required": {
        }
      },
      "appeareance": {
        "type": [
          "plain"
        ]
      },
      "position": 1
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 201 Created
Json
{
  "data": {
    "type": "field",
    "id": "124",
    "attributes": {
      "label": "Title",
      "field_type": "string",
      "localized": true,
      "api_key": "title",
      "hint": "This field will be used as post title",
      "validators": {
        "required": {
        }
      },
      "appeareance": {
        "type": [
          "plain"
        ]
      },
      "position": 1
    },
    "relationships": {
      "item_type": {
        "data": {
          "type": "item_type",
          "id": "44"
        }
      }
    }
  }
}

Field Update

Updates a field

PUT /fields/{field_id}

Required Parameters

Name Type Description Example
data:attributes:api_key string Field API key "title"
data:attributes:appeareance nullable object Field appeareance {"type":["plain"]}
data:attributes:hint nullable string Field hint "This field will be used as post title"
data:attributes:label string The label of the field "Title"
data:attributes:localized boolean Whether the field needs to be multilanguage or not true
data:attributes:position integer Ordering index 1
data:attributes:validators object Optional field validations {"required":{}}
data:id string ID of field "124"
data:type string JSON API type field
pattern: ^field$
"field"

Curl Example

Bash
$ curl -n -X PUT https://site-api.datocms.com/fields/$FIELD_ID \
  -d '{
  "data": {
    "type": "field",
    "id": "124",
    "attributes": {
      "label": "Title",
      "api_key": "title",
      "localized": true,
      "validators": {
        "required": {
        }
      },
      "appeareance": {
        "type": [
          "plain"
        ]
      },
      "position": 1,
      "hint": "This field will be used as post title"
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "field",
    "id": "124",
    "attributes": {
      "label": "Title",
      "field_type": "string",
      "localized": true,
      "api_key": "title",
      "hint": "This field will be used as post title",
      "validators": {
        "required": {
        }
      },
      "appeareance": {
        "type": [
          "plain"
        ]
      },
      "position": 1
    },
    "relationships": {
      "item_type": {
        "data": {
          "type": "item_type",
          "id": "44"
        }
      }
    }
  }
}

Field Index

Lists fields

GET /item-types/{item_type_id}/fields

Curl Example

Bash
$ curl -n https://site-api.datocms.com/item-types/$ITEM_TYPE_ID/fields \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": [
    {
      "type": "field",
      "id": "124",
      "attributes": {
        "label": "Title",
        "field_type": "string",
        "localized": true,
        "api_key": "title",
        "hint": "This field will be used as post title",
        "validators": {
          "required": {
          }
        },
        "appeareance": {
          "type": [
            "plain"
          ]
        },
        "position": 1
      },
      "relationships": {
        "item_type": {
          "data": {
            "type": "item_type",
            "id": "44"
          }
        }
      }
    }
  ]
}

Field Show

Show field

GET /fields/{field_id}

Curl Example

Bash
$ curl -n https://site-api.datocms.com/fields/$FIELD_ID \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "field",
    "id": "124",
    "attributes": {
      "label": "Title",
      "field_type": "string",
      "localized": true,
      "api_key": "title",
      "hint": "This field will be used as post title",
      "validators": {
        "required": {
        }
      },
      "appeareance": {
        "type": [
          "plain"
        ]
      },
      "position": 1
    },
    "relationships": {
      "item_type": {
        "data": {
          "type": "item_type",
          "id": "44"
        }
      }
    }
  }
}

Field Delete

Deletes field

DELETE /fields/{field_id}

Curl Example

Bash
$ curl -n -X DELETE https://site-api.datocms.com/fields/$FIELD_ID \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "field",
    "id": "124",
    "attributes": {
      "label": "Title",
      "field_type": "string",
      "localized": true,
      "api_key": "title",
      "hint": "This field will be used as post title",
      "validators": {
        "required": {
        }
      },
      "appeareance": {
        "type": [
          "plain"
        ]
      },
      "position": 1
    },
    "relationships": {
      "item_type": {
        "data": {
          "type": "item_type",
          "id": "44"
        }
      }
    }
  }
}

Record

A item is a single instance of a item type

Attributes

Name Type Description Example
attributes object The JSON data associated to the item {"title":"This is a item!"}
id string ID of item "4235"
relationships:item_type:data:id string ID of item type "44"
relationships:item_type:data:type string JSON API type field
pattern: ^item_type$
"item_type"
relationships:last_editor:data string JSON API data or JSON API data
type string JSON API type field
pattern: ^item$
"item"

Record Validate existing record

Validates an existing record field

POST /items/{item_id}/validate

Required Parameters

Name Type Description Example
data:attributes object The JSON data associated to the item {"title":"This is a item!"}
data:id string ID of item "4235"
data:relationships:item_type:data:id string ID of item type "44"
data:relationships:item_type:data:type string JSON API type field
pattern: ^item_type$
"item_type"
data:type string JSON API type field
pattern: ^item$
"item"

Curl Example

Bash
$ curl -n -X POST https://site-api.datocms.com/items/$ITEM_ID/validate \
  -d '{
  "data": {
    "id": "4235",
    "type": "item",
    "attributes": {
      "title": "This is a item!"
    },
    "relationships": {
      "item_type": {
        "data": {
          "type": "item_type",
          "id": "44"
        }
      }
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "item",
    "id": "4235",
    "attributes": {
      "title": "This is a item!"
    },
    "relationships": {
      "item_type": {
        "data": {
          "type": "item_type",
          "id": "44"
        }
      },
      "last_editor": {
        "data": {
          "type": "user",
          "id": "312"
        }
      }
    }
  },
  "included": [
    {
      "type": "item_type",
      "id": "44",
      "attributes": {
        "name": "Blog post",
        "api_key": "post",
        "singleton": true,
        "sortable": true,
        "ordering_direction": "desc"
      },
      "relationships": {
        "menu_item": {
          "data": null
        },
        "singleton_item": {
          "data": null
        },
        "fields": {
          "data": [
            {
              "type": "field",
              "id": "124"
            }
          ]
        },
        "ordering_field": {
          "data": null
        }
      }
    }
  ]
}

Record Validate new record

Validates a record fields

POST /items/validate

Required Parameters

Name Type Description Example
data:attributes object The JSON data associated to the item {"title":"This is a item!"}
data:relationships:item_type:data:id string ID of item type "44"
data:relationships:item_type:data:type string JSON API type field
pattern: ^item_type$
"item_type"
data:type string JSON API type field
pattern: ^item$
"item"

Curl Example

Bash
$ curl -n -X POST https://site-api.datocms.com/items/validate \
  -d '{
  "data": {
    "type": "item",
    "attributes": {
      "title": "This is a item!"
    },
    "relationships": {
      "item_type": {
        "data": {
          "type": "item_type",
          "id": "44"
        }
      }
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "item",
    "id": "4235",
    "attributes": {
      "title": "This is a item!"
    },
    "relationships": {
      "item_type": {
        "data": {
          "type": "item_type",
          "id": "44"
        }
      },
      "last_editor": {
        "data": {
          "type": "user",
          "id": "312"
        }
      }
    }
  },
  "included": [
    {
      "type": "item_type",
      "id": "44",
      "attributes": {
        "name": "Blog post",
        "api_key": "post",
        "singleton": true,
        "sortable": true,
        "ordering_direction": "desc"
      },
      "relationships": {
        "menu_item": {
          "data": null
        },
        "singleton_item": {
          "data": null
        },
        "fields": {
          "data": [
            {
              "type": "field",
              "id": "124"
            }
          ]
        },
        "ordering_field": {
          "data": null
        }
      }
    }
  ]
}

Record Create

Create a new record

POST /items

Required Parameters

Name Type Description Example
data:attributes object The JSON data associated to the item {"title":"This is a item!"}
data:relationships:item_type:data:id string ID of item type "44"
data:relationships:item_type:data:type string JSON API type field
pattern: ^item_type$
"item_type"
data:type string JSON API type field
pattern: ^item$
"item"

Curl Example

Bash
$ curl -n -X POST https://site-api.datocms.com/items \
  -d '{
  "data": {
    "type": "item",
    "attributes": {
      "title": "This is a item!"
    },
    "relationships": {
      "item_type": {
        "data": {
          "type": "item_type",
          "id": "44"
        }
      }
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 201 Created
Json
{
  "data": {
    "type": "item",
    "id": "4235",
    "attributes": {
      "title": "This is a item!"
    },
    "relationships": {
      "item_type": {
        "data": {
          "type": "item_type",
          "id": "44"
        }
      },
      "last_editor": {
        "data": {
          "type": "user",
          "id": "312"
        }
      }
    }
  },
  "included": [
    {
      "type": "item_type",
      "id": "44",
      "attributes": {
        "name": "Blog post",
        "api_key": "post",
        "singleton": true,
        "sortable": true,
        "ordering_direction": "desc"
      },
      "relationships": {
        "menu_item": {
          "data": null
        },
        "singleton_item": {
          "data": null
        },
        "fields": {
          "data": [
            {
              "type": "field",
              "id": "124"
            }
          ]
        },
        "ordering_field": {
          "data": null
        }
      }
    }
  ]
}

Record Update

Updates a record

PUT /items/{item_id}

Required Parameters

Name Type Description Example
data:attributes object The JSON data associated to the item {"title":"This is a item!"}
data:id string ID of item "4235"
data:type string JSON API type field
pattern: ^item$
"item"

Curl Example

Bash
$ curl -n -X PUT https://site-api.datocms.com/items/$ITEM_ID \
  -d '{
  "data": {
    "type": "item",
    "id": "4235",
    "attributes": {
      "title": "This is a item!"
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "item",
    "id": "4235",
    "attributes": {
      "title": "This is a item!"
    },
    "relationships": {
      "item_type": {
        "data": {
          "type": "item_type",
          "id": "44"
        }
      },
      "last_editor": {
        "data": {
          "type": "user",
          "id": "312"
        }
      }
    }
  }
}

Record Index

Lists records

GET /items

Optional Parameters

Name Type Description Example
filter[ids] string IDs to fetch, comma separated "12,31"
filter[query] string textual query to match "foo"
filter[type] string model ID to filter "44"
page[limit] integer number of records to fetch
default: 30
15
page[offset] integer index of first record to fetch
default: 1
2

Curl Example

Bash
$ curl -n https://site-api.datocms.com/items
 -G \
  -d filter[ids]=12%2C31 \
  -d filter[type]=44 \
  -d filter[query]=foo \
  -d page[offset]=2 \
  -d page[limit]=15 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": [
    {
      "type": "item",
      "id": "4235",
      "attributes": {
        "title": "This is a item!"
      },
      "relationships": {
        "item_type": {
          "data": {
            "type": "item_type",
            "id": "44"
          }
        },
        "last_editor": {
          "data": {
            "type": "user",
            "id": "312"
          }
        }
      }
    }
  ],
  "meta": {
    "total_count": 42
  }
}

Record Show

Show record

GET /items/{item_id}

Curl Example

Bash
$ curl -n https://site-api.datocms.com/items/$ITEM_ID \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "item",
    "id": "4235",
    "attributes": {
      "title": "This is a item!"
    },
    "relationships": {
      "item_type": {
        "data": {
          "type": "item_type",
          "id": "44"
        }
      },
      "last_editor": {
        "data": {
          "type": "user",
          "id": "312"
        }
      }
    }
  }
}

Record Delete

Deletes a record

DELETE /items/{item_id}

Curl Example

Bash
$ curl -n -X DELETE https://site-api.datocms.com/items/$ITEM_ID \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "item",
    "id": "4235",
    "attributes": {
      "title": "This is a item!"
    },
    "relationships": {
      "item_type": {
        "data": {
          "type": "item_type",
          "id": "44"
        }
      },
      "last_editor": {
        "data": {
          "type": "user",
          "id": "312"
        }
      }
    }
  }
}

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.

Attributes

Name Type Description Example
attributes:url string The URL to use to upload the file with a direct PUT request "https://dato-images.s3-eu-west-1.amazonaws.com/7/1455102967-image.png?X-Amz-Credential=AKIAJDTXTZHHDUCKAUMA%2F20160210"
id string The S3 path where the file will be stored "/7/1455102967-image.png"
type string JSON API type field
pattern: ^upload_request$
"upload_request"

Upload permission Create

Create a new upload request

POST /upload-requests

Required Parameters

Name Type Description Example
data:attributes:filename string The original file name "image.png"
data:type string JSON API type field
pattern: ^upload_request$
"upload_request"

Curl Example

Bash
$ curl -n -X POST https://site-api.datocms.com/upload-requests \
  -d '{
  "data": {
    "type": "upload_request",
    "attributes": {
      "filename": "image.png"
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 201 Created
Json
{
  "data": {
    "type": "upload_request",
    "id": "/7/1455102967-image.png",
    "attributes": {
      "url": "https://dato-images.s3-eu-west-1.amazonaws.com/7/1455102967-image.png?X-Amz-Credential=AKIAJDTXTZHHDUCKAUMA%2F20160210"
    }
  }
}