Developer API

Surreal CMS provides an API so you can integrate your own applications with the service. This feature requires a subscription to the Agency plan. You can upgrade your plan on the billing page.

This is the API documentation for Surreal CMS version 7, which is not backwards compatible with the API for Surreal CMS version 5. If you're using version 5, please refer to the V5 API docs.

Authentication

Before you can use the Developer API, you’ll need to generate a Personal Access Token. You can do this by going to Users > Edit Profile > API Access.

Any administrator can create a unique Personal Access Token. API access will be limited to the same permissions the user has when they're logged in.

Once you've created an access token, you're ready to start making API requests. Every request sent to the API must include the following header with your Personal Access Token.

X-Surreal-PAT: your-personal-access-token-here

Warning

Protect your Personal Access Token like a password! Do not commit it to source control repositories or give it out to other users. Doing so may compromise your account.

To disable access to the API, go to Users > Edit Profile > API Access and select Disable API Access. Note that this will immediately destroy your Personal Access Token and prevent your application from using the API. You can re-enable access at any time, but you'll need to update your app to use the new token.

Sending Requests

All URLs referenced in the documentation must have the following base.

https://edit.surrealcms.com/api/

To make a request to the API, append one of the following routes to the base and use the appropriate HTTP method (e.g. GET, POST, PUT, DELETE).

When sending GET requests, parameters must be passed in the query string. For all other methods, parameters must be formatted as valid JSON and passed in the request body.

In addition to the auth header above, all requests must also include the following Content-Type header.

Content-Type: application/json; charset=utf-8

Handling Responses

All responses are sent as application/json. Successful responses will include a 200 status code and the respective payload. Unsuccessful responses will receive an appropriate HTTP status code and a payload in the following format.

{
  "code": "Forbidden",
  "message": "This request requires authentication."
}

In some cases, the payload will also contain a field called invalid that contains an array of invalid properties.

Object IDs

IDs are guaranteed, meaning they will not change for the life of an object (e.g. sites, users, pages, etc.). Methods that create an object will return the object including its ID. Methods that reference an object will require the object's 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.

Routes

The following routes are accessible through the API. Parameters marked with * are required.

Sites

These routes let you add, remove, and update sites programmatically.

GET /sites Gets a list of sites.

Parameters

search (string)

Optional search filter to use.
limit (int)

The max number of sites to return, default 100, max 1000.
offset (int)

The offset from which to return, default 0.
sortBy (string)

The desired sort order: name | createdAt. Default createdAt.

Example Response

{
  offset: (int),
  limit: (int),
  count: (int),
  sites: (array)
}

POST /sites Creates a site.

Parameters

name* (string)

A human-readable name for the site.
url* (string)

The full URL of the site.
classification (string)

The site's classification: commercial | personal | educational | non-profit, default commercial
protocol (string)

The protocol to use to access the site: ftp | ftps | sftp | s3
host (string)

The site's host.
username (string)

The username for supportive protocols.
password (string)

The password for supportive protocols.
s3AccessKey (string)

The access key for the S3 protocol.
s3SecretKey (string)

The secret key for the S3 protocol.
s3Region (string)

The region for the S3 protocol.
s3Bucket (string)

The bucket for the S3 protocol.
homeFolder (string)

The path of the site's home folder.
uploadFolder (string)

The path of the site's upload folder. Must be the home folder or a subdirectory of the home folder.
isLocked (boolean)

Set to true to lock the site from client edits.
canDeletePages (boolean)

Set to true to allow pages to be deleted on this site.
canDuplicatePages (boolean)

Set to true to allow pages to be duplicated on this site.
gaProfileId (string)

A profile id for a Google Analytics property. This is provided by GA and is usually a string of numbers.

Example Response

{
  site: (object)
}

GET /sites/:siteId Gets a site.

Parameters

None

Example Response

{
  site: (object)
}

PUT /sites/:siteId Updates a site.

Parameters

name (string)

A human-readable name for the site.
url (string)

The full URL of the site.
classification (string)

The site's classification: commercial | personal | educational | non-profit, default commercial.
protocol (string)

The protocol to use to access the site: ftp | ftps | sftp | s3
host (string)

The site's host.
username (string)

The username for supportive protocols.
password (string)

The password for supportive protocols.
s3AccessKey (string)

The access key for the S3 protocol.
s3SecretKey (string)

The secret key for the S3 protocol.
s3Region (string)

The region for the S3 protocol.
s3Bucket (string)

The bucket for the S3 protocol.
homeFolder (string)

The path of the site's home folder.
uploadFolder (string)

The path of the site's upload folder. Must be the home folder or a subdirectory of the home folder.
isLocked (boolean)

Set to true to lock the site from client edits.
canDeletePages (boolean)

Set to true to allow pages to be deleted on this site.
canDuplicatePages (boolean)

Set to true to allow pages to be duplicated on this site.
isLocked (boolean)

Set to true to lock the site from client edits.
gaProfileId (string)

A profile id for a Google Analytics property. This is provided by GA and is usually a string of numbers.

Example Response

{
  site: (object)
}

DELETE /sites/:siteId Deletes a site.

Parameters

None

Example Response

{
  site: (object)
}

Pages

These routes let you add, remove, and update pages programmatically.

GET /sites/:siteId/pages Gets a list of pages.

Parameters

search (string)

Optional search filter to use.
limit (int)

The max number of pages to return, default 100, max 1000.
offset (int)

The offset from which to return, default 0.
sortBy (string)

The desired sort order: pinned | name | path | createdAt, default createdAt.

Example Response

{
  offset: (int),
  limit: (int),
  count: (int),
  pages: (array)
}

POST /sites/:siteId/pages Enables, creates, or duplicates a page.

To enable a page that already exists on your server, set createOnServer to false and provide a name and path for the page.

To create a new page, set createOnServer to true and specify a templateId from which to create it.

To duplicate an existing page, set createOnServer to true and specify a pageId.

Parameters

name* (string)

A human-readable name for the page.
path* (path)

The path of the page relative to the home folder.
isPinned (boolean)

Whether or not the page is pinned in the page list.
createOnServer (boolean)

Whether or not to create the page on the server, default true. Set to false to enable an existing page. If true, either templateId or pageId must also be set.
templateId (string)

A template id from which to generate the new page's source.
pageId (string)

A page id from which to generate the new page's source. This option will be ignored if templateId is set.

Example Response

{
  page: (object)
}

GET /sites/:siteId/pages/:pageId Gets a page.

Parameters

None

Example Response

{
  page: (object)
}

PUT /sites/:siteId/pages/:pageId Updates a page.

Parameters

name (string)

A human-readable name for the page.
path (string)

The path of the page relative to the home folder.
isPinned (boolean)

Whether or not the page is pinned in the page list.

Example Response

{
  page: (object)
}

DELETE /sites/:siteId/pages/:pageId Disables or deletes a page.

Parameters

deleteFromServer (boolean)

Whether or not to delete the page from the server, default true.

Example Response

{
  page: (object)
}

POST /sites/:siteId/pages/delete Disables or deletes multiple pages in one request (i.e. batch disable or delete).

Parameters

pageIds* (array)

An array of page ids to delete.
deleteFromServer (boolean)

Whether or not to delete the page from the server. Default true. If this is false, the page will be disabled from the CMS but remain intact on the server.

Example Response

{
  succeeded: (array),
  failed: (array)
}

Revisions

A revision is a copy of your page that was previously published. Learn more

GET /users/:userId/revisions Gets a list of revisions by user.

Parameters

limit (int)

The max number of revisions to return, default 100, max 1000.
offset (int)

The offset from which to return, default 0.
sortBy (string)

The desired sort order: isDraft | createdAt. Default createdAt.

Example Response

{
  offset: (int),
  limit: (int),
  count: (int),
  revisions: (array)
}

GET /sites/:siteId/revisions Gets a list of revisions by site.

Parameters

limit (int)

The max number of revisions to return, default 100, max 1000.
offset (int)

The offset from which to return, default 0.
sortBy (string)

The desired sort order: isDraft | createdAt. Default createdAt.

Example Response

{
  offset: (int),
  limit: (int),
  count: (int),
  revisions: (array)
}

GET /sites/:siteId/pages/:pageId/revisions Gets a list of revisions by page.

Parameters

limit (int)

The max number of revisions to return, default 100, max 1000.
offset (int)

The offset from which to return, default 0.
sortBy (string)

The desired sort order: isDraft | createdAt. Default createdAt.

Example Response

{
  offset: (int),
  limit: (int),
  count: (int),
  revisions: (array)
}

GET /sites/:siteId/pages/:pageId/revisions/:revisionId Gets a revision.

Parameters

None

Example Response

{
  revision: (object)
}

DELETE /sites/:siteId/pages/:pageId/revisions/:revisionId Deletes a revision.

Parameters

None

Example Response

{
  revision: (object)
}

Templates

Templates allow you to create new pages from scratch. Learn more

GET /sites/:siteId/templates Gets a list of templates.

Parameters

search (string)

Optional search filter to use.
limit (int)

The max number of templates to return, default 100, max 1000.
offset (int)

The offset from which to return, default 0.
sortBy (string)

The desired sort order: name or createdAt, default createdAt.

Example Response

{
  offset: (int),
  limit: (int),
  count: (int),
  templates: (array)
}

POST /sites/:siteId/templates Creates a template.

Parameters

name* (string)

A name for the template.
description* (string)

A description for the template.
extension* (string)

The file extension to use for all pages created with the template, including the leading dot.
source* (string)

The source code of the template.

Example Response

{
  template: (object)
}

GET /sites/:siteId/templates/:templateId Gets a template.

Parameters

None

Example Response

{
  template: (object)
}

PUT /sites/:siteId/templates/:templateId Updates a template.

Parameters

name (string)

A name for the template.
description (string)

A description for the template.
extension (string)

The file extension to use for all pages created with the template, including the leading dot.
source (string)

The source code of the template.

Example Response

{
  template: (object)
}

DELETE /sites/:siteId/templates/:templateId Deletes a template.

Parameters

None

Example Response

{
  template: (object)
}

Blocks

Blocks are predefined chunks of content designed specifically for your each website. Learn more

GET /sites/:siteId/blocks Gets a list of blocks.

Parameters

search (string)

Optional search filter to use.
limit (int)

The max number of blocks to return, default 100, max 1000.
offset (int)

The offset from which to return, default 0.
sortBy (string)

The desired sort order: name | createdAt, default createdAt.

Example Response

{
  offset: (int),
  limit: (int),
  count: (int),
  blocks: (array)
}

POST /sites/:siteId/blocks Creates a block.

Parameters

name* (string)

A name for the block.
description* (string)

A description for the block.
source* (string)

The source code of the block.

Example Response

{
  block: (object)
}

GET /sites/:siteId/blocks/:blockId Gets a block.

Parameters

None

Example Response

{
  block: (object)
}

PUT /sites/:siteId/blocks/:blockId Updates a block.

Parameters

name (string)

A name for the block.
description (string)

A description for the block.
source (string)

The source code of the block.

Example Response

{
  block: (object)
}

DELETE /sites/:siteId/blocks/:blockId Deletes a block.

Parameters

None

Example Response

{
  block: (object)
}

Users

These routes let you add, remove, and update users programmatically.

GET /users Gets a list of users.

Parameters

search (string)

Optional search filter to use.
limit (int)

The max number of users to return, default 100, max 1000.
offset (int)

The offset from which to return, default 0.
sortBy (string)

The desired sort order: name | role | createdAt, default createdAt.

Example Response

{
  offset: (int),
  limit: (int),
  count: (int),
  users: (array)
}

POST /users Creates a new user.

Parameters

name* (string)

The user's name.
email* (string)

The user's email address.
password (string)

The user's password. If omitted, you must provide the message object so a welcome email can be sent to the user with an activation link.

message (object)

An object containing the following properties. This will be used to generate a welcome email with an activation link that gets sent to the user. These fields should be omitted if password is provided instead.

subject (string) - The subject of the email.

intro (string) - The introduction inviting the user to activate their account.

callToAction (string) - The text to display in the account activation button.

outro (string) - Any salutations you'd like to provide to the user.

avatar (string)

The user's avatar in URL format. If this is a data URI, the avatar will be stored and the URL will be updated to the stored location.
bio (string)

The user's bio.
isAdmin (boolean)

Set to true to make the user an administrator.
canManageSettings (boolean)

Set to true to grant the user settings privileges. Can only be applied when isAdmin is true.
canManageBilling (boolean)

Set to true to grant the user billing privileges. Can only be applied when isAdmin is true.
canManageSites (boolean)

Set to true to grant the user site management privileges. Can only be applied when isAdmin is true.
canManageUsers (boolean)

Set to true to grant the user user management privileges. Can only be applied when isAdmin is true.

Example Response

{
  user: (object)
}

GET /users/:userId Gets a user.

Parameters

None

Example Response

{
  user: (object)
}

PUT /users/:userId Updates a user.

Parameters

name (string)

The user's name.
email (string)

The user's email address.
password (string)

The user's password.

avatar (string)

The user's avatar in URL format. If this is a data URI, the avatar will be stored and the URL will be updated to the stored location.
bio (string)

The user's bio.
isAdmin (boolean)

Set to true to make the user an administrator.
canManageSettings (boolean)

Set to true to grant the user settings privileges. Can only be applied when isAdmin is true.
canManageBilling (boolean)

Set to true to grant the user billing privileges. Can only be applied when isAdmin is true.
canManageSites (boolean)

Set to true to grant the user site management privileges. Can only be applied when isAdmin is true.
canManageUsers (boolean)

Set to true to grant the user user management privileges. Can only be applied when isAdmin is true.

Example Response

{
  user: (object)
}

DELETE /users/:userId Deletes a user.

Parameters

None

Example Response

{
  user: (object)
}

Permissions

Permissions determine the sites and pages a user has access to. These routes let you get and set an individual user's permissions.

GET /users/:userId/permissions Gets a user's permissions.

Parameters

None

Example Response

{
  permissions: (array)
}

PUT /users/:userId/permissions Sets a user's permissions.

Parameters

permissions (array)

An array of permission objects containing userId, siteId, and an optional pages property containing an array of page IDs formatted as JSON. Note that this will replace all of the user's existing permissions, so make sure to include all sites and pages you want the user to be able to access. You can use the GET method to get a full list of existing permissions before updating.

Example Response

{
  permissions: (array)
}

Change Notifications

Administrative users can receive email notifications when pages are published. These routes let you configure change notifications for individual users.

GET /users/:userId/change-notifications/:siteId Determines if the user has change notifications enabled for the specified site.

Parameters

None

Example Response

{
  changeNotification: (object)
}

POST /users/:userId/change-notifications/:siteId Turns on change notifications for the specified user and site.

Parameters

None

Example Response

{
  changeNotification: (object)
}

DELETE /users/:userId/change-notifications/:siteId Turns off change notifications for the specified user and site.

Parameters

None

Example Response

{
  changeNotification: (object)
}

Favorites

Users can "favorite" or "heart" a site which causes it to appear conveniently in the sidebar. This is especially useful if they have access to a lot of sites. These routes let you configure favorites for individual users.

GET /users/:userId/favorites Gets a list of the user's favorite sites.

Parameters

siteId (string)

If set, only the favorite with this id will be returned.
limit (int)

The max number of sites to return, default 100, max 1000.
offset (int)

The offset from which to return, default 0.
sortBy (string)

The desired sort order: name | createdAt, default createdAt.

Example Response

{
  offset: (int),
  limit: (int),
  count: (int),
  favorites: (array)
}

GET /users/:userId/favorites/:siteId Gets a user's favorite.

Parameters

None

Example Response

{
  favorite: (object)
}

POST /users/:userId/favorites/:siteId Adds a favorite to the user's account.

Parameters

None

Example Response

{
  favorite: (object)
}

DELETE /users/:userId/favorites/:siteId Deletes a favorite from the user's account.

Parameters

None

Example Response

{
  favorite: (object)
}