Developer API
Surreal CMS provides an API so you can integrate your own applications with the service. This feature
requires the Agency plan or higher. You can upgrade your plan on
the billing page. On other
plans, API requests return a 402 status code.
This is the API documentation for Surreal CMS Version 20. It isn't backwards compatible with the API for Surreal CMS Version 5, so code written for Version 5 needs to be updated.
If you use an AI coding agent, our agent skill teaches it to use this API for you.
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. Two-factor authentication doesn't apply to
requests made with a token. A token belonging to a user who hasn't verified their email address yet (an
owner who signed up and never followed the link in the welcome email) gets 403 on every request
until they do.
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.
If you're connecting an AI agent, use an agent token instead. Create it under
Users > Edit Profile > Security & Access > Agent Access and send it as an
Authorization: Bearer header. Agent tokens are part of every paid plan and follow a few extra
rules; see the AI agents docs.
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.
Rate limits
The API accepts up to 10 requests per second from each IP address, with bursts of up to 20. Pace your
requests to stay under the limit. A request over the limit gets a 429 response with a
Retry-After header that says how many seconds to wait.
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.
Publishing, files, uploads, and page source aren't available through the API.
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. Values over1000reset to100. -
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),
sites: (array)
}
GET /sites/summaries
Gets the id, name, and URL of every site.
Returns every site the user can access, sorted by name. Each site has only an id,
name, and url. The list isn't paged.
Parameters
None
Example response
{
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. It must be a public
httporhttpsaddress;localhostand private network addresses are refused. -
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 | webdav | s3 | r2 | spaces -
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, R2, and Spaces protocols.
-
s3SecretKey (string)The secret key for the S3, R2, and Spaces protocols.
-
s3Region (string)The region for the S3 protocol. For Spaces, use the datacenter slug (e.g.
nyc3). -
s3Bucket (string)The bucket for the S3, R2, and Spaces protocols.
-
s3Acl (boolean)Set to true to make files uploaded to S3 publicly readable (
public-read). -
r2AccountId (string)Your Cloudflare account ID for the R2 protocol (32 hexadecimal characters).
-
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. Use a dedicated folder with no pages in it. Users can change anything inside it and nothing outside of it.
-
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.
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. It must be a public
httporhttpsaddress;localhostand private network addresses are refused. -
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 | webdav | s3 | r2 | spaces -
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, R2, and Spaces protocols.
-
s3SecretKey (string)The secret key for the S3, R2, and Spaces protocols.
-
s3Region (string)The region for the S3 protocol. For Spaces, use the datacenter slug (e.g.
nyc3). -
s3Bucket (string)The bucket for the S3, R2, and Spaces protocols.
-
s3Acl (boolean)Set to true to make files uploaded to S3 publicly readable (
public-read). -
r2AccountId (string)Your Cloudflare account ID for the R2 protocol (32 hexadecimal characters).
-
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. Use a dedicated folder with no pages in it. Users can change anything inside it and nothing outside of it.
-
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.
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. Values over1000reset to100. -
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. Only
administrators can enable pages.
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. It must stay inside the home folder and have an editable extension.
-
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 tofalseto enable an existing page. Iftrue, eithertemplateIdorpageIdmust 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
templateIdis 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. Deleting requires the site to allow it (canDeletePages). Disabling (false) requires an administrator.
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. Ids of pages the user isn't permitted to access are ignored and appear in neither
succeedednorfailed. -
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. Deleting requires the site to allow it (canDeletePages). Disabling requires an administrator.
Example response
{
succeeded: (array),
failed: (array)
}
POST /sites/:siteId/pages/enable
Enables multiple existing files as pages in one request (i.e. batch enable).
Only administrators can enable pages.
Parameters
-
pages* (array)Up to 1,500 pages to enable, each with a
pathrelative to the home folder, aname, and an optionalisPinnedboolean. Nothing is written to the server. A path that is already enabled is returned as it is instead of being enabled again.
Example response
{
pages: (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. Values over1000reset to100. -
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. Values over1000reset to100. -
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. Values over1000reset to100. -
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.
Deleting a draft that's scheduled to publish cancels the schedule.
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. Values over1000reset to100. -
offset (int)The offset from which to return, default
0. -
sortBy (string)The desired sort order:
nameorcreatedAt, 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 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. Values over1000reset to100. -
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. Values over1000reset to100. -
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. Links, domains, email addresses, markup, six or more digits, or more than 60 characters are refused with
INVALID_NAME. -
email* (string)The user's email address.
-
password (string)The user's password. If omitted, you must provide the
messageobject so a welcome email can be sent to the user with an activation link. A request made with a token can't set a password and gets403. -
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
passwordis 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. A request made with a token can't create an administrator and gets
403. -
canManageSettings (boolean)Set to true to grant the user settings privileges. Only the owner can grant it, and only when
isAdminis true. -
canManageBilling (boolean)Set to true to grant the user billing privileges. Only the owner can grant it, and only when
isAdminis true. -
canManageSites (boolean)Set to true to grant the user site management privileges. Only the owner can grant it. It's cleared unless
isAdminis true. -
canManageUsers (boolean)Set to true to grant the user user management privileges. Only the owner can grant it. It's cleared unless
isAdminis 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. Links, domains, email addresses, markup, six or more digits, or more than 60 characters are refused with
INVALID_NAME. -
email (string)The user's email address. Only the owner or the administrator themself can change an administrator's email, and never with a token (
403). Sending the current email unchanged doesn't count as a change. -
password (string)The user's password. Only the owner or the administrator themself can change an administrator's password, and never with a token (
403). -
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. Changing it requires user management privileges.
-
canManageSettings (boolean)Set to true to grant the user settings privileges. Can only be applied when
isAdminis true. -
canManageBilling (boolean)Set to true to grant the user billing privileges. Can only be applied when
isAdminis true. -
canManageSites (boolean)Set to true to grant the user site management privileges. Can only be applied when
isAdminis true. -
canManageUsers (boolean)Set to true to grant the user user management privileges. Can only be applied when
isAdminis 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 optionalpagesproperty 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 theGETmethod 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. Values over1000reset to100. -
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)
}