---
name: surreal-cms
description: Integrate websites with Surreal CMS and manage a Surreal CMS account through its Developer API. Use when building or preparing an HTML site so clients can edit it (content regions, repeatables, lockables, includes, blocks, templates, metadata), when connecting a site over FTP, SFTP, WebDAV, S3, R2, or Spaces, or when creating sites, enabling pages, inviting users, and setting permissions in Surreal CMS on the user's behalf. Covers requests like "build a site and let Bob edit it" end to end.
metadata:
  version: 3.1.5
  homepage: https://www.surrealcms.com/skills/surreal-cms/SKILL.md
---

# Surreal CMS

Surreal CMS is a hosted CMS for static and server-rendered HTML sites. It doesn't host websites. It connects to the site's existing hosting (FTP, FTPS, SFTP, WebDAV, Amazon S3, Cloudflare R2, or DigitalOcean Spaces), opens real pages in a visual editor, and publishes changes straight back to the server. Only elements you've tagged in the HTML are editable.

This skill has two parts:

1. **Integration:** writing HTML that editors can safely change. No account is needed.
2. **The Developer API:** acting on the user's account to create sites, enable pages, and invite and permission users. It needs an agent token (any paid plan) or a Personal Access Token (Agency plan or higher).

## Files in this skill

Read the reference that matches the task before acting.

| File                                                   | Read it when                                                                                                                                                          |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [references/integration.md](references/integration.md) | Writing or reviewing HTML for Surreal CMS. Covers every region type, repeatables, lockables, includes, metadata, scripts, guide colors, and the pre-launch checklist. |
| [references/api.md](references/api.md)                 | Making any API call. Covers every route, field, error code, and trap.                                                                                                 |
| [references/connecting.md](references/connecting.md)   | Creating a site or fixing a connection. Covers the fields for each protocol, folder formats, and troubleshooting.                                                     |
| [scripts/check.py](scripts/check.py)                   | Before any page goes live. Run `python3 scripts/check.py *.html` to catch integration problems.                                                                       |

If you're reading this on the web, the files are at `https://www.surrealcms.com/skills/surreal-cms/` followed by the paths above.

## The mental model

- **Site:** a website and its connection: URL, protocol, credentials, home folder, and upload folder.
- **Page:** one file on the server that's been _enabled_ for editing. Files that aren't enabled are invisible to editors.
- **Content region:** an element with a unique `id` and `class="cms-editable"`. The only parts of a page anyone can change.
- **Repeatable / lockable:** `cms-repeatable` lets editors duplicate, reorder, and delete an element. `cms-lock` freezes an element's structure, and `cms-unlock` reopens the parts inside it that editors can change.
- **Static include:** `id` + `class="cms-include"`. Shared markup, such as a header or footer, synced across every enabled page when one page is published.
- **Template:** a full page source that editors (and the API) create new pages from. **Block:** an HTML snippet editors insert into block regions.
- **Users:** the owner, admins (see everything), and clients (see only what their permissions grant). Clients are the people you hand a site to.

## What the API can and can't do

It **can**: create, update, and delete sites; enable, create, rename, move, and disable pages; manage templates and blocks; create, update, and delete users; set permissions; turn change notifications and favorites on and off; and read revisions and drafts.

It **can't**: read or edit an existing page's source, publish, save drafts, list files on the server, upload images or other files, test a connection, create admins, or manage tokens and billing.

Two consequences:

- **The user puts the site on their host.** Surreal CMS doesn't host websites or deploy them. It edits pages that are already live.
- **Integrate before you enable.** Get the HTML right while you still control the files. After that, changes to a page's source happen in the app's source editor or through the host.

## Ground rules

Follow these every time.

1. **Keep the token out of files and chat.** Read it from an environment variable: `SURREAL_AGENT_TOKEN` for an agent token (`sca_…`, sent as `Authorization: Bearer`), or `SURREAL_PAT` for a Personal Access Token (sent as `X-Surreal-PAT`). Use whichever is set. Never write it to the repo, a config file you create, or your replies. If the user pastes it into chat, use it for the session and suggest they store it in their environment.
2. **Confirm before anything outward-facing or destructive.** Inviting a user sends a real email. Deleting a site, user, page file, or revision is permanent. State exactly what will happen and wait for a yes.
3. **Disabling a page means `{"deleteFromServer": false}`.** `DELETE` on a page removes the file from the server unless you send that body. Never leave it out. Deleting the file also needs the site's `canDeletePages` on, which a new site has off: `ACTION_PROHIBITED` means turn it on with `PUT /sites/:siteId {"canDeletePages": true}` first, with the user's agreement.
4. **Permissions are replaced, not merged.** `GET` the current list, modify it, and `PUT` the whole list back. An empty `pages` array means _every_ page, not none.
5. **Never recreate a page an editor has changed.** Deleting and recreating a file throws away their published edits and its revision history.
6. **Don't print credentials.** Site responses can include hosting passwords and keys. Extract ids and the fields you need. An agent token never receives them, so to fix a connection, ask the user for the credentials.
7. **Look before you create.** Search for an existing site (`GET /sites/summaries`), page (`GET …/pages?search=`), or user (`GET /users?search=<email>`) first. The API happily creates duplicates.
8. **Go one request at a time,** and treat `429` as "slow down": wait the seconds in its `Retry-After` header. Branch on the HTTP status, not the error message.
9. **Stay inside the agent token's switches.** `403` with code `AGENT_PERMISSION_DENIED` means the token can't do that. Its `permission` field says what: `people` (inviting people and managing their access), `delete`, `login`, or `admins` (agents never create or change admins, set passwords, or change email addresses). Tell the user which switch to turn on under **Users → Edit Profile → Security & Access → Agent Access**, or to do it in the app. Don't look for another way.

## Workflow: build a site and hand it to a client

A typical request: _"Build a site for Acme Bakery with Home, Menu, and Contact pages, in this style, and let Bob (bob@acmebakery.com) edit it."_

**1. Check access.** Call `GET /sites?limit=1`. `402` means the plan doesn't include this token: any paid plan for an agent token, Agency or higher for a Personal Access Token. `403` means the token is wrong, revoked, or the owner turned agents off. Stop and tell the user either way.

**2. Settle the hosting.** Surreal CMS needs somewhere to publish. Ask for the public URL, the protocol, and its credentials (see [connecting.md](references/connecting.md)). If the user has no hosting, say so plainly and help them choose one. For a static site, Cloudflare R2 or SFTP to a host they already use are the simplest.

**3. Build the HTML with editing in mind.** Follow [integration.md](references/integration.md):

- Keep the layout in your markup and make content regions as big as the content allows. Content that flows top to bottom, such as headings, copy, images, quotes, and lists, goes in one `<div>` or `<section>` block region. Split it only where layout, a background, a gallery, or a component with fixed structure sits in between. Don't give each heading, paragraph, or image its own region unless the user asks for a locked-down page. See "How big to make a region" in [integration.md](references/integration.md).
- Use `data-type="text"` for prices, phone numbers, hours, and addresses, and `<a>` link regions for buttons outside the copy.
- Use `cms-repeatable cms-lock` with `cms-unlock` parts for repeated components with structure: cards in a grid, team members, pricing tiers, nav links. Items that are only a heading and a paragraph don't need it.
- Put the header and footer in static includes that are byte-identical on every page. Give regions inside them `data-urls="absolute"` if pages live in different folders.
- Write the title and meta description as static tags. Guard any sliders or tabs with `.is-cms`, and keep third-party widgets in `<!--cms-ignore-->` blocks outside regions.
- Style every element an editor might add: headings, lists, blockquotes, tables, and figures. Give every block region CSS for aligned images, because a captioned image doesn't move without it. See "Image alignment" in [integration.md](references/integration.md).
- If the site has a dark mode, follow `prefers-color-scheme` rather than adding a theme toggle. The editor switches the page with the app's theme. If the user wants a toggle, hide it in the editor. See "Light and dark mode" in [integration.md](references/integration.md).
- Set the editor's guide colors from the brand, with separate values for dark mode if the site has one. See "Editor guides" in [integration.md](references/integration.md).
- Keep images and other files editors will manage in an `uploads` folder in the home folder (`uploads/hero.jpg`), with no pages in it. It becomes the site's upload folder in step 5.
- Run `scripts/check.py` on every file and fix every error.

**4. Have the user publish the files to their host.** Hand over every file, including images, CSS, and the `uploads` folder, and let the user put them on their host the way they normally would. If they ask you to do it with their own deploy (SFTP, `aws s3 sync`, `wrangler r2 object put`, `rclone`, or a git push), do that. Don't continue until each page loads over HTTPS.

**5. Create the site** with `POST /sites`. Set `uploadFolder` to the `uploads` folder, never the home folder. This is best practice: editors can upload, rename, move, and delete anything in the upload folder but nothing outside it, so a dedicated folder keeps them from cluttering the site root or renaming and deleting pages. Save the returned `site.id`. It doesn't test the connection, so ask the user to select **Edit Site → Test Connection** in the app.

**6. Enable the pages.**

- Send one `POST /sites/:siteId/pages/enable` with every page's `path` relative to the home folder (`index.html`, `menu.html`, `contact/index.html`) and a human-readable `name`. It enables them all in one request and skips any that are already enabled.
- Pin the homepage with `isPinned: true` on its entry. Save every `page.id`.
- If the user wants every page with content regions enabled and you don't have the file list, point them to **Enable Pages → Scan for Pages** in the app, which finds them and lets the user enable them in one go.

**7. Add editor conveniences.**

- Add blocks for components the client will want to insert, such as a callout, a two-column section, or an FAQ item.
- Keep one clean page template if the client should be able to add pages.
- Leave `canDeletePages` off unless the client should be able to delete files.

**8. Invite the client.** Search `GET /users?search=bob@acmebakery.com` first. Then confirm the name, email, and invitation wording with the user, and `POST /users` with a `message` and no password. Leave out `isAdmin`, so Bob is a client.

**9. Grant access.** `GET /users/:bobId/permissions`, add `{ "siteId": "<site>", "pages": null }` (or a specific list of page ids), and `PUT` the full list. Check the response.

**10. Optional.** Turn on change notifications so the user is emailed when Bob publishes (`POST /users/:yourId/change-notifications/:siteId`; find your own id with `GET /users?search=<the user's email>`), and favorite the site for Bob (`POST /users/:bobId/favorites/:siteId`).

**11. Report back.** List what exists now: the site, the pages with their paths, the templates and blocks, Bob's role and access, and the invitation sent. Name anything that still needs a human, such as testing the connection, a DNS change, or testing in the editor. Recommend that the user open each page in the editor once before Bob does. The editor's guides flag any region problem the checker couldn't see.

## Other common tasks

- **Integrate an existing site.** Get the source files from the user or the repo, add regions following the checklist, run the checker, and upload the files the way the user normally deploys. Then create the site and enable pages with `createOnServer: false`. Point `uploadFolder` at a folder that holds only files, such as an existing `images` folder, or a new `uploads` folder. Don't touch pages already enabled in Surreal CMS without telling the user; their files may hold edits you don't have.
- **Add a page to a live site.** Build it from the site's existing markup so its includes match exactly, have the user publish it to their host, then enable it. Add it to any client whose permissions list specific pages.
- **Give someone access to more (or less).** `GET` their permissions, modify, `PUT`. To remove a site entirely, leave it out of the list.
- **Offboard a client.** Confirm first, then `DELETE /users/:userId`. To pause access without deleting them, `PUT` their permissions with the site removed.

## When something fails

- Read `code` and `invalid` in the response, then check the table in [api.md](references/api.md).
- Connection errors are almost always the host, port, credentials, home folder, or a firewall blocking `162.243.9.115`. See [connecting.md](references/connecting.md).
- If the editor won't load a page or shows it unstyled, the problem is the live page: HTTPS, CORS for fonts, caching, or bot protection. The API can't fix that; explain it to the user.
- Anything you can't do through the API, tell the user where it lives in the app: **Edit Site → Test Connection**, **Enable Pages** (to browse the server's files, or **Scan for Pages** to find every page with content regions), the page's **Source** view, **Publish**, **Users → Edit Profile → Security & Access** (API Access and Agent Access).

Docs: https://www.surrealcms.com/docs · Support: https://www.surrealcms.com/contact
