Account 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:account:data:id string ID of account "312"
relationships:account:data:type string JSON API type field
pattern: ^account$
"account"
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://account-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": {
      "account": {
        "data": {
          "type": "account",
          "id": "312"
        }
      }
    }
  },
  "included": [
    {
      "type": "account",
      "id": "312",
      "attributes": {
        "email": "foo@bar.com",
        "password": "example",
        "api_token": "example",
        "valid_card": true
      }
    }
  ]
}

Account

Dato 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 user has a valid card true
id string ID of account "312"
type string JSON API type field
pattern: ^account$
"account"

Account Create

Invite a new account

POST /account

Required Parameters

Name Type Description Example
data:attributes:email string Email "foo@bar.com"
data:attributes:password string Password "example"
data:type string JSON API type field
pattern: ^account$
"account"

Curl Example

Bash
$ curl -n -X POST https://account-api.datocms.com/account \
  -d '{
  "data": {
    "type": "account",
    "attributes": {
      "email": "foo@bar.com",
      "password": "example"
    }
  }
}' \
  -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": {
      "account": {
        "data": {
          "type": "account",
          "id": "312"
        }
      }
    }
  },
  "included": [
    {
      "type": "account",
      "id": "312",
      "attributes": {
        "email": "foo@bar.com",
        "password": "example",
        "api_token": "example",
        "valid_card": true
      }
    }
  ]
}

Account Update

Updates a account

PUT /account

Required Parameters

Name Type Description Example
data:attributes:email string Email "foo@bar.com"
data:attributes:password string Password "example"
data:id string ID of account "312"
data:type string JSON API type field
pattern: ^account$
"account"

Curl Example

Bash
$ curl -n -X PUT https://account-api.datocms.com/account \
  -d '{
  "data": {
    "type": "account",
    "id": "312",
    "attributes": {
      "email": "foo@bar.com",
      "password": "example"
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "account",
    "id": "312",
    "attributes": {
      "email": "foo@bar.com",
      "password": "example",
      "api_token": "example",
      "valid_card": true
    }
  }
}

Account Show

Show account

GET /account

Curl Example

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

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "account",
    "id": "312",
    "attributes": {
      "email": "foo@bar.com",
      "password": "example",
      "api_token": "example",
      "valid_card": true
    }
  }
}

Account Reset password

Request a password reset

POST /account/reset_password

Required Parameters

Name Type Description Example
data:attributes:email string Email "foo@bar.com"
data:type string JSON API type field
pattern: ^account$
"account"

Curl Example

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

Response Example

HTTP/1.1 200 OK
Json
{
  "type": "account",
  "id": "312",
  "attributes": {
    "email": "foo@bar.com",
    "password": "example",
    "api_token": "example",
    "valid_card": true
  }
}

Site

A site represents a specific DatoCMS administrative area

Attributes

Name Type Description Example
attributes:access_token string Access token "example"
attributes:created_at nullable date-time Date of site creation null
attributes:deploy_adapter nullable string Specify the deploy adapter to use "gitlab"
attributes:domain nullable string Site domain "admin.foobar.com"
attributes:editors_count integer Number of total editors 42
attributes:frontend_url nullable string URL for the frontend website "https://my-site.com"
attributes:internal_domain string Internal site domain "clueless-star-1231.admin.datocms.com"
attributes:internal_subdomain string Internal site subdomain "clueless-star-1231"
attributes:items_count integer Number of total items 42
attributes:last_data_change_at nullable date-time Specifies the last time when a change of data occurred null
attributes:name string Site name "My blog"
attributes:notes nullable string Optional notes regarding the site "Foo bar"
attributes:readonly_token string Read-only API token "example"
attributes:readwrite_token string Read-write API token "example"
attributes:ssg nullable string Specifies static site generator used null
attributes:theme_hue integer Specifies the Hue to use primary color in Site backend 42
attributes:uploaded_bytes integer The amount of file storage consumed by the site 42
attributes:webhook_token string Webhook API token "example"
attributes:webhook_url string Webhook URL "http://api.datocms.com/sites/summer-star-15/deploy-results"
id string ID of site "155"
relationships:active_subscription:data:id string ID of subscription "124"
relationships:active_subscription:data:type string JSON API type field
pattern: ^subscription$
"subscription"
relationships:latest_deploy_events:data array The list of latest deploy events [{"type":"deploy_event","id":"34"}]
type string JSON API type field
pattern: ^site$
"site"

Site Get

Retrieve a site

GET /sites/{site_id}

Curl Example

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

Response Example

HTTP/1.1 200 OK
Json
{
  "data": {
    "type": "site",
    "id": "155",
    "attributes": {
      "name": "My blog",
      "domain": "admin.foobar.com",
      "internal_domain": "clueless-star-1231.admin.datocms.com",
      "internal_subdomain": "clueless-star-1231",
      "notes": "Foo bar",
      "ssg": null,
      "theme_hue": 42,
      "last_data_change_at": "2015-01-01T12:00:00Z",
      "frontend_url": "https://my-site.com",
      "webhook_url": "http://api.datocms.com/sites/summer-star-15/deploy-results",
      "created_at": "2015-01-01T12:00:00Z",
      "readonly_token": "example",
      "readwrite_token": "example",
      "webhook_token": "example",
      "access_token": "example",
      "items_count": 42,
      "editors_count": 42,
      "uploaded_bytes": 42,
      "deploy_adapter": "gitlab"
    },
    "relationships": {
      "latest_deploy_events": {
        "data": [
          {
            "type": "deploy_event",
            "id": "34"
          }
        ]
      },
      "active_subscription": {
        "data": {
          "type": "subscription",
          "id": "124"
        }
      }
    }
  }
}

Site Index

Lists sites

GET /sites

Curl Example

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

Response Example

HTTP/1.1 200 OK
Json
{
  "data": [
    {
      "type": "site",
      "id": "155",
      "attributes": {
        "name": "My blog",
        "domain": "admin.foobar.com",
        "internal_domain": "clueless-star-1231.admin.datocms.com",
        "internal_subdomain": "clueless-star-1231",
        "notes": "Foo bar",
        "ssg": null,
        "theme_hue": 42,
        "last_data_change_at": "2015-01-01T12:00:00Z",
        "frontend_url": "https://my-site.com",
        "webhook_url": "http://api.datocms.com/sites/summer-star-15/deploy-results",
        "created_at": "2015-01-01T12:00:00Z",
        "readonly_token": "example",
        "readwrite_token": "example",
        "webhook_token": "example",
        "access_token": "example",
        "items_count": 42,
        "editors_count": 42,
        "uploaded_bytes": 42,
        "deploy_adapter": "gitlab"
      },
      "relationships": {
        "latest_deploy_events": {
          "data": [
            {
              "type": "deploy_event",
              "id": "34"
            }
          ]
        },
        "active_subscription": {
          "data": {
            "type": "subscription",
            "id": "124"
          }
        }
      }
    }
  ]
}

Site Create

Create a new site

POST /sites

Required Parameters

Name Type Description Example
data:attributes:domain nullable string Site domain "admin.foobar.com"
data:attributes:internal_subdomain string Internal site subdomain "clueless-star-1231"
data:attributes:name string Site name "My blog"
data:attributes:notes nullable string Optional notes regarding the site "Foo bar"
data:attributes:ssg nullable string Specifies static site generator used null
data:attributes:template nullable string Site template
one of:null or "blog" or "agency" or "portfolio"
"blog"
data:type string JSON API type field
pattern: ^site$
"site"

Curl Example

Bash
$ curl -n -X POST https://account-api.datocms.com/sites \
  -d '{
  "data": {
    "type": "site",
    "attributes": {
      "name": "My blog",
      "internal_subdomain": "clueless-star-1231",
      "domain": "admin.foobar.com",
      "notes": "Foo bar",
      "ssg": null,
      "template": "blog"
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 201 Created
Json
{
  "data": {
    "type": "site",
    "id": "155",
    "attributes": {
      "name": "My blog",
      "domain": "admin.foobar.com",
      "internal_domain": "clueless-star-1231.admin.datocms.com",
      "internal_subdomain": "clueless-star-1231",
      "notes": "Foo bar",
      "ssg": null,
      "theme_hue": 42,
      "last_data_change_at": "2015-01-01T12:00:00Z",
      "frontend_url": "https://my-site.com",
      "webhook_url": "http://api.datocms.com/sites/summer-star-15/deploy-results",
      "created_at": "2015-01-01T12:00:00Z",
      "readonly_token": "example",
      "readwrite_token": "example",
      "webhook_token": "example",
      "access_token": "example",
      "items_count": 42,
      "editors_count": 42,
      "uploaded_bytes": 42,
      "deploy_adapter": "gitlab"
    },
    "relationships": {
      "latest_deploy_events": {
        "data": [
          {
            "type": "deploy_event",
            "id": "34"
          }
        ]
      },
      "active_subscription": {
        "data": {
          "type": "subscription",
          "id": "124"
        }
      }
    }
  }
}

Site Update

Update a new site

PUT /sites/{site_id}

Required Parameters

Name Type Description Example
data:attributes:domain nullable string Site domain "admin.foobar.com"
data:attributes:internal_subdomain string Internal site subdomain "clueless-star-1231"
data:attributes:name string Site name "My blog"
data:attributes:notes nullable string Optional notes regarding the site "Foo bar"
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://account-api.datocms.com/sites/$SITE_ID \
  -d '{
  "data": {
    "id": "155",
    "type": "site",
    "attributes": {
      "name": "My blog",
      "domain": "admin.foobar.com",
      "internal_subdomain": "clueless-star-1231",
      "notes": "Foo bar"
    }
  }
}' \
  -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 blog",
      "domain": "admin.foobar.com",
      "internal_domain": "clueless-star-1231.admin.datocms.com",
      "internal_subdomain": "clueless-star-1231",
      "notes": "Foo bar",
      "ssg": null,
      "theme_hue": 42,
      "last_data_change_at": "2015-01-01T12:00:00Z",
      "frontend_url": "https://my-site.com",
      "webhook_url": "http://api.datocms.com/sites/summer-star-15/deploy-results",
      "created_at": "2015-01-01T12:00:00Z",
      "readonly_token": "example",
      "readwrite_token": "example",
      "webhook_token": "example",
      "access_token": "example",
      "items_count": 42,
      "editors_count": 42,
      "uploaded_bytes": 42,
      "deploy_adapter": "gitlab"
    },
    "relationships": {
      "latest_deploy_events": {
        "data": [
          {
            "type": "deploy_event",
            "id": "34"
          }
        ]
      },
      "active_subscription": {
        "data": {
          "type": "subscription",
          "id": "124"
        }
      }
    }
  }
}

Site Delete

Deletes a site

DELETE /sites/{site_id}

Curl Example

Bash
$ curl -n -X DELETE https://account-api.datocms.com/sites/$SITE_ID \
  -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 blog",
      "domain": "admin.foobar.com",
      "internal_domain": "clueless-star-1231.admin.datocms.com",
      "internal_subdomain": "clueless-star-1231",
      "notes": "Foo bar",
      "ssg": null,
      "theme_hue": 42,
      "last_data_change_at": "2015-01-01T12:00:00Z",
      "frontend_url": "https://my-site.com",
      "webhook_url": "http://api.datocms.com/sites/summer-star-15/deploy-results",
      "created_at": "2015-01-01T12:00:00Z",
      "readonly_token": "example",
      "readwrite_token": "example",
      "webhook_token": "example",
      "access_token": "example",
      "items_count": 42,
      "editors_count": 42,
      "uploaded_bytes": 42,
      "deploy_adapter": "gitlab"
    },
    "relationships": {
      "latest_deploy_events": {
        "data": [
          {
            "type": "deploy_event",
            "id": "34"
          }
        ]
      },
      "active_subscription": {
        "data": {
          "type": "subscription",
          "id": "124"
        }
      }
    }
  }
}

Site Duplicate

Duplicate an existing site

POST /sites/{site_id}/duplicate

Required Parameters

Name Type Description Example
data:attributes:name string Site name "My blog"
data:type string JSON API type field
pattern: ^site$
"site"

Curl Example

Bash
$ curl -n -X POST https://account-api.datocms.com/sites/$SITE_ID/duplicate \
  -d '{
  "data": {
    "type": "site",
    "attributes": {
      "name": "My blog"
    }
  }
}' \
  -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 blog",
      "domain": "admin.foobar.com",
      "internal_domain": "clueless-star-1231.admin.datocms.com",
      "internal_subdomain": "clueless-star-1231",
      "notes": "Foo bar",
      "ssg": null,
      "theme_hue": 42,
      "last_data_change_at": "2015-01-01T12:00:00Z",
      "frontend_url": "https://my-site.com",
      "webhook_url": "http://api.datocms.com/sites/summer-star-15/deploy-results",
      "created_at": "2015-01-01T12:00:00Z",
      "readonly_token": "example",
      "readwrite_token": "example",
      "webhook_token": "example",
      "access_token": "example",
      "items_count": 42,
      "editors_count": 42,
      "uploaded_bytes": 42,
      "deploy_adapter": "gitlab"
    },
    "relationships": {
      "latest_deploy_events": {
        "data": [
          {
            "type": "deploy_event",
            "id": "34"
          }
        ]
      },
      "active_subscription": {
        "data": {
          "type": "subscription",
          "id": "124"
        }
      }
    }
  }
}

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 "2015-01-01T12:00:00Z"
attributes:data object Any details regarding the event
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://account-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",
        "created_at": "2015-01-01T12:00:00Z",
        "data": null
      },
      "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://account-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",
      "created_at": "2015-01-01T12:00:00Z",
      "data": null
    },
    "relationships": {
      "site": {
        "data": {
          "type": "site",
          "id": "155"
        }
      }
    }
  }
}

Subscription

A subscription record

Attributes

Name Type Description Example
attributes:created_at date-time Date of creation of subscription "2015-01-01T12:00:00Z"
id string ID of subscription "124"
relationships:plan:data:id string ID of plan "124"
relationships:plan:data:type string JSON API type field
pattern: ^plan$
"plan"
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: ^subscription$
"subscription"

Subscription Create

Create a new subscription

POST /sites/{site_id}/subscriptions

Required Parameters

Name Type Description Example
data:relationships:plan:data:id string ID of plan "124"
data:relationships:plan:data:type string JSON API type field
pattern: ^plan$
"plan"
data:type string JSON API type field
pattern: ^subscription$
"subscription"

Curl Example

Bash
$ curl -n -X POST https://account-api.datocms.com/sites/$SITE_ID/subscriptions \
  -d '{
  "data": {
    "type": "subscription",
    "attributes": {
    },
    "relationships": {
      "plan": {
        "data": {
          "type": "plan",
          "id": "124"
        }
      }
    }
  }
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 201 Created
Json
{
  "data": {
    "type": "subscription",
    "id": "124",
    "attributes": {
      "created_at": "2015-01-01T12:00:00Z"
    },
    "relationships": {
      "plan": {
        "data": {
          "type": "plan",
          "id": "124"
        }
      },
      "site": {
        "data": {
          "type": "site",
          "id": "155"
        }
      }
    }
  },
  "included": [
    {
      "type": "site",
      "id": "155",
      "attributes": {
        "name": "My blog",
        "domain": "admin.foobar.com",
        "internal_domain": "clueless-star-1231.admin.datocms.com",
        "internal_subdomain": "clueless-star-1231",
        "notes": "Foo bar",
        "ssg": null,
        "theme_hue": 42,
        "last_data_change_at": "2015-01-01T12:00:00Z",
        "frontend_url": "https://my-site.com",
        "webhook_url": "http://api.datocms.com/sites/summer-star-15/deploy-results",
        "created_at": "2015-01-01T12:00:00Z",
        "readonly_token": "example",
        "readwrite_token": "example",
        "webhook_token": "example",
        "access_token": "example",
        "items_count": 42,
        "editors_count": 42,
        "uploaded_bytes": 42,
        "deploy_adapter": "gitlab"
      },
      "relationships": {
        "latest_deploy_events": {
          "data": [
            {
              "type": "deploy_event",
              "id": "34"
            }
          ]
        },
        "active_subscription": {
          "data": {
            "type": "subscription",
            "id": "124"
          }
        }
      }
    }
  ]
}

Portal session

Obtain an authenticated session to Chargebee customer portal valid for 1 hour

Attributes

Name Type Description Example
attributes:url string The authenticated URL "https://datocms.chargebeeportal.com/portal/access/XXX"
id string The authenticated URL "https://datocms.chargebeeportal.com/portal/access/XXX"
type string JSON API type field
pattern: ^portal_session$
"portal_session"

Portal session Create

Create a new portal session

POST /portal_sessions

Curl Example

Bash
$ curl -n -X POST https://account-api.datocms.com/portal_sessions \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer XXXX"

Response Example

HTTP/1.1 201 Created
Json
{
  "data": {
    "type": "portal_session",
    "id": "https://datocms.chargebeeportal.com/portal/access/XXX",
    "attributes": {
      "url": "https://datocms.chargebeeportal.com/portal/access/XXX"
    }
  }
}

Plan

A field represents a plan

Attributes

Name Type Description Example
attributes:name string The name of the plan "Free"
id string ID of plan "124"
type string JSON API type field
pattern: ^plan$
"plan"