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
, max1000
. -
offset (int)
The offset from which to return, default0
. -
sortBy (string)
The desired sort order:
name | createdAt
. DefaultcreatedAt
.
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
, defaultcommercial
. -
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
, max1000
. -
offset (int)
The offset from which to return, default
0
. -
sortBy (string)
The desired sort order:
pinned | name | path | createdAt
, defaultcreatedAt
.
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 tofalse
to enable an existing page. Iftrue
, eithertemplateId
orpageId
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 isfalse
, 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
, max1000
. -
offset (int)
The offset from which to return, default
0
. -
sortBy (string)
The desired sort order:
isDraft | createdAt
. DefaultcreatedAt
.
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
, max1000
. -
offset (int)
The offset from which to return, default
0
. -
sortBy (string)
The desired sort order:
isDraft | createdAt
. DefaultcreatedAt
.
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
, max1000
. -
offset (int)
The offset from which to return, default
0
. -
sortBy (string)
The desired sort order:
isDraft | createdAt
. DefaultcreatedAt
.
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
, max1000
. -
offset (int)
The offset from which to return, default
0
. -
sortBy (string)
The desired sort order:
name
orcreatedAt
, defaultcreatedAt
.
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
, max1000
. -
offset (int)
The offset from which to return, default
0
. -
sortBy (string)
The desired sort order:
name | createdAt
, defaultcreatedAt
.
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
, max1000
. -
offset (int)
The offset from which to return, default
0
. -
sortBy (string)
The desired sort order:
name | role | createdAt
, defaultcreatedAt
.
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 optionalpages
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 theGET
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
, max1000
. -
offset (int)
The offset from which to return, default
0
. -
sortBy (string)
The desired sort order:
name | createdAt
, defaultcreatedAt
.
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)
}