Documentation

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 over 1000 reset to 100.

  • 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)
}
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 http or https address; localhost and 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 http or https address; localhost and 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)
}
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 over 1000 reset to 100.

  • 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. 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 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. 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 succeeded nor failed.

  • 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. 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 path relative to the home folder, a name, and an optional isPinned boolean. 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 over 1000 reset to 100.

  • 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. Values over 1000 reset to 100.

  • 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. Values over 1000 reset to 100.

  • 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.

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 over 1000 reset to 100.

  • 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 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 over 1000 reset to 100.

  • 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. Values over 1000 reset to 100.

  • 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. 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 message object 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 gets 403.

  • 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. 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 isAdmin is true.

  • canManageBilling (boolean)

    Set to true to grant the user billing privileges. Only the owner can grant it, and only when isAdmin is true.

  • canManageSites (boolean)

    Set to true to grant the user site management privileges. Only the owner can grant it. It's cleared unless isAdmin is true.

  • canManageUsers (boolean)

    Set to true to grant the user user management privileges. Only the owner can grant it. It's cleared unless 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. 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 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. Values over 1000 reset to 100.

  • 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)
}