Resources

Developer API

Surreal CMS provides a RESTful API so you can integrate your own applications with our service. Before your application can use the Developer API, you’ll need to enable it in Settings.

Once you enable access, an API key will be generated for you. This is what you’ll use to authenticate with the API, so protect this key just like you would a password!

Authentication

Every request sent to the API must be over SSL and must include the following HTTP header along with your API key for authentication.

X-Surreal-CMS-API-Key: your-api-key-here

Each account is authorized up to 10,000 API requests per day. If you exceed this limit, the API will reject all further requests until the following day.

Making requests

All URLs referenced in the documentation have the following base.

https://edit-content.com/api/v1

To make a request to the API, append any of the following routes while using the appropriate HTTP method. Some routes require parameters. Details about each route can be found by selecting the description.

A note about PUT requests: Due to the way our API processes PUT requests, REST clients will need to use POST instead of PUT and set the following header:

X-HTTP-Method-Override: PUT

Sites

HTTP	URL	Description
POST	/sites	Creates a site
Description Adds a new site to your account and returns the corresponding site ID. Parameters url string The website's URL. Example: `http://example.com/` protocol string The protocol to use when connecting. Valid protocols include `ftp`, `ftps`, `sftp`, or `s3`. port int The port to use when connecting. The default port for FTP is 21. The default port for SFTP is 22. No port is required for Amazon S3. pasv string For FTP and FTPS only. Set this value to `on` to use passive FTP connections or `off` to use active. server string The location of the server to connect to. For Amazon S3, this will be your bucket name. s3_region string For Amazon S3 only. This value should be a valid S3 region. Example: `us-east-1` username string For FTP and SFTP, the username to authenticate with. For S3, this is your access key. password string For FTP and SFTP, the password to authenticate with. For S3, this is your secret key. path string The path to your home folder. images string The path to the default images (now called uploads) folder. (optional) lockdown string Whether the site should be on lockdown (available for editing by clients). Valid options are `on` and `off`. Example Response { "status": "success", "site": { "id": 10000 } }
GET	/sites	Gets a list of sites
Description Gets a list of sites from your account. Parameters count int The number of sites to return. (optional) offset int The number of sites to skip when listing sites. (optional) Example Response { "status": "success", "total": 10, "count": 5, "offset": 0, "sites": [ { "id": "10000", "url": "http:\/\/your-site.com\/", "lockdown": "off", "site_date": "2015-01-01 12:00:00" }, ... ] }
GET	/sites/<site-id>	Gets a single site
Description Gets the specified site from your account. Remember that usernames and passwords are never returned for security reasons. Parameters None Example Response { "status": "success", "site": { "id": "10000", "url": "http:\/\/example.com\/", "protocol": "ftp", "port": "21", "server": "ftp.example.com", "path": "\/public_html\/", "images": "images/", "lockdown": "off", "site_date": "2015-01-01 12:00:00" } }
PUT	/sites/<site-id>	Updates a site
Description Updates a site. You can specify one or more parameters when using this method. Parameters The parameters for this method are identical to those for creating a site. Example Response { "status": "success" }
DELETE	/sites/<site-id>	Deletes a site
Description Deletes a site from your account. Parameters None Example Response { "status": "success" }

Sites / Styles

HTTP	URL	Description
GET	/sites/<site-id>/styles	Gets styles for a site
Description Gets custom styles for the specified site. If no styles are set, the styles property will be an empty string. Parameters None Example Response { "status": "success", "styles": ".your-styles { color: cyan; }" }
PUT	/sites/<site-id>/styles	Updates styles for a site
Description Updates custom styles for the specified site. Custom styles cannot be deleted. To remove existing styles, call this method with `styles` set to an empty string. Parameters styles string The CSS to use for custom styles. Example Response { "status": "success" }

Sites / Snippets

HTTP	URL	Description
POST	/sites/<site-id>/snippets	Creates a snippet
Description Creates a snippet for the specified site and returns the corresponding ID. Parameters name string The name of the snippet. code string The full HTML code of the snippet. Example Response { "status": "success", "snippet": { "id": 10000 } }
GET	/sites/<site-id>/snippets	Gets a list of snippets
Description Gets a list of snippets for the specified site. Parameters None Example Response { "status": "success", "snippets": [ { "id": "10000", "name": "My Snippet" }, ... ] }
GET	/sites/<site-id>/snippets/<snippet-id>	Gets a single snippet
Description Gets a single snippet. Parameters None Example Response { "status": "success", "snippet": { "id": "10000", "name": "My Snippet", "code": "<p>...<\/p>" } }
PUT	/sites/<site-id>/snippets/<snippet-id>	Updates a snippet
Description Updates a snippet. Parameters The parameters for this method are identical to those for creating a snippet. Example Response { "status": "success" }
DELETE	/sites/<site-id>/snippets/<snippet-id>	Deletes a snippet
Description Deletes a snippet. Parameters None Example Response { "status": "success" }

Sites / Templates

HTTP	URL	Description
POST	/sites/<site-id>/templates	Creates a template
Description Creates a template for the specified site and returns the corresponding ID. Parameters name string The name of the template. extension string The file extension that will be used for pages created with this template (without the dot). source string The full HTML source of the template. Example Response { "status": "success", "template": { "id": 10000 } }
GET	/sites/<site-id>/templates	Gets a list of templates
Description Gets a list of templates for the specified site. Parameters None Example Response { "status": "success", "templates": [ { "id": "10000", "name": "My Template", "extension": "html" }, ... ] }
GET	/sites/<site-id>/templates/<template-id>	Gets a single template
Description Gets a single template. Parameters None Example Response { "status": "success", "template": { "id": "10000", "name": "My Template", "extension": "html", "source": "<html>...<\/html>" } }
PUT	/sites/<site-id>/templates/<template-id>	Updates a template
Description Updates a template. Parameters The parameters for this method are identical to those for creating a template. Example Response { "status": "success" }
DELETE	/sites/<site-id>/templates/<template-id>	Deletes a template
Description Deletes a template. Parameters None Example Response { "status": "success" }

Sites / Pages

HTTP	URL	Description
POST	/sites/<site-id>/pages	Enables a page
Description Enables a page for editing in the CMS. This will not create any files on your server. Any pages you enable through the API should already exist on your server. Parameters label string The label to use for the page. path string The path to the page on your server. Example Response { "status": "success", "page": { "id": 10000 } }
GET	/sites/<site-id>/pages	Gets a list of pages
Description Gets a list of pages for the specified site. This method only returns pages that are enabled for editing. Parameters count int The number of sites to return. (optional) offset int The number of sites to skip when listing sites. (optional) Example Response { "status": "success", "total": 10, "count": 5, "offset": 0, "pages": [ { "id": "10000", "label": "My Page Label", "path": "my-page.html" }, ... ] }
GET	/sites/<site-id>/pages/<page-id>	Gets a single page
Description Gets a single page. Parameters None Example Response { "status": "success", "page": { "id": "10000", "label": "My Page Label", "path": "my-page.html" } }
DELETE	/sites/<site-id>/pages/<page-id>	Disables a page
Description Disables a page and removes it from the CMS. This will not remove any files from your server. Parameters None Example Response { "status": "success" }

Sites / Pages / Revisions

HTTP	URL	Description
GET	/sites/<site-id>/pages/<page-id>/revisions	Gets a list of revisions
Description Gets a list of revisions for the specified page. This method returns revisions in reverse chronological order. Parameters count int The number of revisions to return. (optional) offset int The number of revisions to skip when listing revisions. (optional) All revision types, including `history`, `autopublish`, and `draft` will be returned. Revisions are always listed in reverse chronological order. Example Response { "status": "success", "total": 10, "count": 5, "offset": 0, "revisions": [ { "id": "10000", "site_id": "20000", "page_id": "30000", "user_id": "40000", "type": "history", "revision_date": "2015-01-014 14:32:28", "autopublish_date": "0000-00-00 00:00:00" }, ... ] }
GET	/sites/<site-id>/pages/<page-id>/revisions/<revision-id>	Gets a single revision
Description Gets a single revision. Parameters None Example Response { "status": "success", "revision": { "id": "10000", "site_id": "20000", "page_id": "30000", "user_id": "40000", "type": "history", "page_data": { "properties": { "title": "This is the page title", "description": "This is the meta description.", "keywords": "These are the meta keywords" }, "regions": { "region-id-1": "<p>HTML for #region-id-1<\/p>", "region-id-2": "<p>HTML for #region-id-2<\/p>", ... } }, "revision_date": "2015-01-014 14:32:28", "autopublish_date": "0000-00-00 00:00:00" } }
DELETE	/sites/<site-id>/pages/<page-id>/revisions/<revision-id>	Deletes a revision
Description Deletes a revision. Parameters None Example Response { "status": "success" }

Users

HTTP	URL	Description
POST	/users	Creates a user
Description Creates a user and returns the corresponding ID. This method will not assign permissions to a user — that must be done in a separate request. Parameters name string The full name of the user. email string The user’s email address. password string A password for the user (minimum of eight characters). type string The type of user. Must be either `client` or `admin`. privileges string This can be a `*` indicating all privileges, or a comma-separated list containing one or more of the privileges listed here. Example: `create-page, relabel-page, move-page, ...` Example Response { "status": "success", "user": { "id": 10000 } }
GET	/users	Gets a list of users
Description Gets a list of users from your account. Parameters count int The number of sites to return. (optional) offset int The number of sites to skip when listing sites. (optional) Example Response { "status": "success", "total": 10, "count": 5, "offset": 0, "users": [ { "id": "10000", "name": "John Doe", "email": "john.doe@example.com", "type": "client", "privileges": "*", "user_date": "2015-01-01 12:00:00" }, ... ] }
GET	/users/<user-id>	Gets a single user
Description Gets a single user from your account. Parameters None Example Response { "status": "success", "user": { "id": "10000", "name": "John Doe", "email": "john.doe@example.com", "type": "client", "privileges": "*", "user_date": "2015-01-01 12:00:00" } }
PUT	/users/<user-id>	Updates a user
Description Updates a user. Parameters The parameters for this method are identical to those for creating a user. Example Response { "status": "success" }
DELETE	/users/<user-id>	Deletes a user
Description Deletes a user from your account. Parameters None Example Response { "status": "success" }

Users / Permissions

HTTP	URL	Description
GET	/users/<user-id>/permissions	Gets permissions
Description Gets permissions for the specified user. The response includes a list of site IDs and the corresponding pages that the user has access to. If the value for a given site is ``, the user has access to all pages on that site. Otherwise, the value will be an array of page IDs. For admin users, the result will always be an empty array since they automatically have access to all sites. Parameters None Example Response { "status": "success", "permissions": { "10000": [ ← site #10000 "20000", ← page #20000 "20001" ← page #20001 ], "10001": "" ← all pages on site #10001 } }
PUT	/users/<user-id>/permissions	Updates permissions
Description Updates permissions for the specified user. Parameters permissions array An array of permissions to set, where each array key is a site ID and each value is either `` (all pages) or an array of page IDs. See below for examples. When this method is called, all permissions will be reset except for those specified in the request. Formatting the Permissions Array To give a user access to all pages on a site, your PUT data should look like this: All pages on site #10000 permissions[10000]= Only two pages on site #10000 (page #20000 and #20001) permissions[10000][]=20000&permissions[10000][]=20001 All pages on two different sites permissions[10000]=&permissions[10001]= Example Response { "status": "success" }

Users / Notifications

HTTP	URL	Description
POST	/users/<user-id>/notifications	Turns notifications on
Description Turns notifications on for the specified user and site. Only admins can receive notifications, so an error will be received if this method is called for a non-admin user. Parameters site_id int The site ID to enable notifications for. Example Response { "status": "success" }
GET	/users/<user-id>/notifications	Tells if notifications are on
Description Tells whether or not this user has notifications enabled for the specified user/site. Parameters site_id int The site ID to check for notifications. Example Response { "status": "success", "notifications": true }
DELETE	/users/<user-id>/notifications	Turns notifications off
Description Turns notifications off for the specified user/site. Parameters site_id int The site ID to disable notifications for. Example Response { "status": "success" }

Users / Login

HTTP	URL	Description
POST	/users/<user-id>/login	Generates a login token
Description Generates a time-sensitive token that can be used to login a user by redirecting them to a special URL. Tokens are only valid for 15 minutes and cannot be reused. If this method is called more than once for the same user, only the most recent token will be honored. This method is intended for applications that have their own custom authentication system. Do not call this method unless the user has successfully logged in to your own application! To log the user in, redirect their browser to: http://edit-content.com/login?token=<token> If you’re using a custom domain, replace `edit-content.com` with your own domain. To redirect the user back to your custom domain when they logout, append the following to the above URL: &logout-redirect=http://your-domain.com/ Parameters None Example Response { "status": "success", "token": "2mLICQQ0gXEQygUgQN2ISIo5FsHrO1Jwbx0m3WX3aLM5eJIOS1BwuIXdgo1P" }

Handling responses

Every request to the API will return one of the following HTTP codes.

Code	Status	What it means
200	Success	Everything went as expected
401	Unauthorized	Your API key is missing or incorrect
422	Unprocessable Entity	Your request could not be completed for some reason
429	Too Many Requests	You have exceeded the daily rate limit
500	Internal Server Error	Something didn't work right on our end

In addition, each response body will include a JSON string with a status property. The status will either be success or error.

If the status is error, an error code and message will also be provided. For example:

{
    "status": "error",
    "errorCode": "1100",
    "errorMessage": "Invalid API key"
}

If the status is success, additional data may exist depending on the operation.

API error codes

Code	Description
1000	Request was not submitted over SSL
1100	Invalid or missing API key
1150	Daily request limit exceeded
1200	Invalid or missing fields
2000	Invalid site
2100	Unable to create site
2200	Unable to update site
2300	Invalid template
2400	Unable to create template
2500	Unable to update template
2600	Invalid page
2700	Unable to enable page
2800	Invalid revision
3000	Invalid user
3100	Unable to create user
3200	Unable to update user
3300	Master administrators cannot be deleted
3400	Email address already in use
3500	Password is not long enough
3600	Invalid user type
3700	User cannot receive notifications
4000	Invalid snippet
4100	Unable to create snippet
4200	Unable to update snippet

Referencing objects by ID

IDs are guaranteed, meaning they will not change for the life of an object (a site, a user, etc.). Methods that create an object will return an ID. Methods that reference the object will require that ID. You can also obtain an object’s ID using a list-all method.

For efficiency and convenience, it’s a good idea to store these IDs in your own app. This allows you to easily reference objects using the API without having to search for them each time.

Examples

Here are some examples you can paste into your command line. You’ll need to change the API key and any IDs in the request. The examples use cURL, so you’ll need to have that installed on your machine for these to work.

List the first five sites in your account
$ curl --request GET --header "X-Surreal-CMS-API-Key: YOUR_API_KEY" --data "count=5&offset=0" https://edit-content.com/api/v1/sites

Create a site
$ curl --request POST --header "X-Surreal-CMS-API-Key: YOUR_API_KEY" --data "url=http://example.com/&protocol=ftp&server=ftp.example.com&port=21&username=user&password=password&path=/httpdocs/" https://edit-content.com/api/v1/sites

Delete a site
$ curl --request DELETE --header "X-Surreal-CMS-API-Key: YOUR_API_KEY" https://edit-content.com/api/v1/sites/YOUR_SITE_ID

List the first five users in your account
$ curl --request GET --header "X-Surreal-CMS-API-Key: YOUR_API_KEY" --data "count=5&offset=0" https://edit-content.com/api/v1/users

HTTP Clients

The examples above use the command line version of cURL to give you an idea of how requests should be formed. If you’re using PHP, there’s a cURL module that’s usually available out-of-the-box.

Alternatively, you can use a third-party library such as Guzzle to make requests to the API.

Resources

Developer API

Authentication

Making requests

Sites

Description

Parameters

Example Response

Description

Parameters

Example Response

Description

Parameters

Example Response

Description

Parameters

Example Response

Description

Parameters

Example Response

Sites / Styles

Description

Parameters

Example Response

Description

Parameters

Example Response

Sites / Snippets

Description

Parameters

Example Response

Description

Parameters

Example Response

Description

Parameters

Example Response

Description

Parameters

Example Response

Description

Parameters

Example Response

Sites / Templates

Description

Parameters

Example Response

Description

Parameters

Example Response

Description

Parameters

Example Response

Description

Parameters

Example Response

Description

Parameters

Example Response

Sites / Pages

Description

Parameters

Example Response

Description

Parameters

Example Response

Description

Parameters

Example Response

Description

Parameters

Example Response

Sites / Pages / Revisions

Description

Parameters

Example Response

Description

Parameters

Example Response

Description