# Developer API reference

Source: https://www.surrealcms.com/docs/api

## Basics

- **Base URL:** `https://edit.surrealcms.com/api`. Append routes with no trailing slash.
- **Plan:** an agent token works on any paid plan; a Personal Access Token needs the Agency plan or higher. Other plans get `402`.
- **Auth:** send `Authorization: Bearer <token>` for an agent token (`sca_…`), or `X-Surreal-PAT: <token>` for a Personal Access Token, on every request. Either belongs to one admin user and carries that user's permissions. Two-factor auth doesn't apply to token requests. Users create or revoke tokens at **Users → Edit Profile → Security & Access** in the app. Tokens can't be created through the API.
- **Every token** is refused (`403`) when it creates an admin, sets a password on a new user, or changes an admin's email or password. **Agent tokens** go further: they invite and edit clients only (never edit admins, set passwords, or change email addresses), can't generate login tokens, never receive site credentials in a response, and need the token's switches for inviting people and managing access (`people`) and for deleting (`delete`). A refused request is `403 { code: "AGENT_PERMISSION_DENIED", permission }`. Invitations are capped at 25 an hour and 100 a day, and new sites at 50 an hour and 200 a day; over a cap is `429`.
- **Bodies:** `GET` takes query-string parameters. `POST`, `PUT`, and `DELETE` take a JSON body with `Content-Type: application/json; charset=utf-8`.
- **Rate limit:** 10 requests per second per IP, bursts of 20. Go one request at a time. A rate-limited request gets `429` with a `Retry-After` header in seconds. Wait that long and retry.
- **IDs** are UUIDs that never change. Save the ones you create.
- **Pagination:** list routes take `limit` (default `100`, max `1000`; anything outside `0`–`1000` resets to `100`), `offset` (default `0`), `search` (case-insensitive substring), and `sortBy`. They return `{ offset, limit, count, <items> }`, where `count` is the total.
- **Deletes are permanent.** Nothing is soft-deleted.

## Not available through the API

- Reading or writing an existing page's source
- Publishing, drafts, and restoring revisions
- Listing files on the server (the **Enable Pages** browser)
- Uploading, moving, or deleting files in the upload folder
- Testing a site's connection
- Creating admins, setting a new user's password, or changing an admin's email or password
- Creating or revoking tokens, billing, and account settings

The user puts a site's files on their host. For everything else, the user opens the app.

## Calling the API

```sh
curl -sS https://edit.surrealcms.com/api/sites?limit=10 \
  -H "Authorization: Bearer $SURREAL_AGENT_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8"

curl -sS -X POST https://edit.surrealcms.com/api/sites \
  -H "Authorization: Bearer $SURREAL_AGENT_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  --data @site.json
```

With a Personal Access Token, send `-H "X-Surreal-PAT: $SURREAL_PAT"` instead of the `Authorization` header.

Build JSON bodies with a real serializer, such as `jq -n`, Python's `json`, or a file, instead of string concatenation. Template and block sources are full HTML documents that are full of quotes.

Sites and users come back with fields you don't need, and site responses can include connection credentials (never to an agent token). Parse out the ids and fields you need, such as with `jq '.site.id'`, and don't print, log, or save whole site or user responses.

## Errors

Branch on the HTTP status first. Production error messages are often generic.

| Status | Meaning                                                                                                                                                                                                                                                | What to do                                                                                                                                                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Validation or operation error. Body is `{ code, message, invalid? }`, where `invalid` lists the bad fields.                                                                                                                                            | Read `code` (table below), fix the input, and retry.                                                                                                                                                                                        |
| `402`  | The plan doesn't include this token: any paid plan for an agent token, Agency or higher for a Personal Access Token.                                                                                                                                   | Stop. Tell the user which plan the token needs.                                                                                                                                                                                             |
| `403`  | Missing, invalid, or revoked token, a route that doesn't accept tokens, a user who lacks the permission, an agent token outside its rules (`AGENT_PERMISSION_DENIED`), or a plan limit (`SITE_LIMIT_REACHED`, `UPGRADE_REQUIRED`; see the code table). | Check the body's `code` first: the plan codes mean stop and tell the user, not a token problem. Otherwise check the token, then the user's role. For `AGENT_PERMISSION_DENIED`, tell the user which switch to turn on. Don't retry blindly. |
| `404`  | The object doesn't exist or this user can't see it.                                                                                                                                                                                                    | Re-list to get a valid id.                                                                                                                                                                                                                  |
| `423`  | `SITE_IS_LOCKED`: someone turned on lockdown, usually while working on the site's files.                                                                                                                                                               | Stop and tell the user. Only unlock it (`PUT /sites/:siteId {"isLocked": false}`) if they ask.                                                                                                                                              |
| `500`  | Server error, usually from a malformed request (missing `path`, a bad enum value, or a missing `message` object).                                                                                                                                      | Check the request against this reference before retrying.                                                                                                                                                                                   |
| `429`  | Rate limited, or an agent cap on invitations or new sites.                                                                                                                                                                                             | Wait `Retry-After` seconds, then retry.                                                                                                                                                                                                     |

Common `code` values:

| Code                                                            | Cause                                                                                                                                                                                                                                    |
| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VALIDATION_ERROR`                                              | A field is missing or malformed. See `invalid`.                                                                                                                                                                                          |
| `AGENT_PERMISSION_DENIED`                                       | An agent token outside its rules. `permission` is `people`, `delete`, `login`, or `admins`.                                                                                                                                              |
| `EMAIL_IN_USE`                                                  | That email already has a Surreal CMS login, possibly on another account. Emails are unique across the whole service.                                                                                                                     |
| `INVALID_NAME`                                                  | The `name` carries a link, a domain, an email address, markup, or six or more digits, or is over 60 characters.                                                                                                                          |
| `PASSWORD_TOO_SHORT`                                            | Passwords need at least 8 characters.                                                                                                                                                                                                    |
| `FILE_ALREADY_EXISTS`                                           | A file already exists at the page path you're creating or moving to.                                                                                                                                                                     |
| `FILE_TYPE_NOT_SUPPORTED`                                       | The extension isn't editable. See [Editable extensions](#editable-extensions).                                                                                                                                                           |
| `PATH_OUTSIDE_OF_HOME_FOLDER`                                   | A page path resolves outside the site's home folder.                                                                                                                                                                                     |
| `TEMPLATE_NOT_FOUND`, `PAGE_NOT_FOUND`                          | The `templateId` or `pageId` isn't on this site.                                                                                                                                                                                         |
| `ACTION_PROHIBITED`                                             | The site has `canDuplicatePages` or `canDeletePages` turned off (a new site has `canDeletePages` off), or a non-admin sent `deleteFromServer: false`.                                                                                    |
| `TEMPLATE_QUOTA_REACHED`, `BLOCKS_QUOTA_REACHED`                | The site already has 100 templates or 100 blocks.                                                                                                                                                                                        |
| `SITE_LIMIT_REACHED`                                            | The account's plan has no room for another site (`POST /sites`, a 403). Paid plans bill extra sites instead of refusing, so this means a fixed cap, such as a custom plan. Stop and tell the user; they contact Surreal CMS to raise it. |
| `UPGRADE_REQUIRED`                                              | The plan lacks a feature (a 403 with `feature` naming it, such as `changeNotifications`). Every paid plan has the features the token routes use, so stop and tell the user to check the plan on the Billing page.                        |
| `INSUFFICIENT_CREDITS`                                          | Reserved for AI features: the account's AI credits are spent. Credits and refills are on the Billing page.                                                                                                                               |
| `TOO_MANY_REQUESTS`                                             | The body code of a `429` from an agent cap on invitations or new sites. AI features will also use it when credits are spent too fast. Wait `Retry-After` seconds, then retry.                                                            |
| `BLOCKS_MUST_NOT_HAVE_IDS`                                      | A block's top-level element has an `id`.                                                                                                                                                                                                 |
| `CHANGE_NOTIFICATION_ALREADY_EXISTS`, `FAVORITE_ALREADY_EXISTS` | Already on. Treat as success.                                                                                                                                                                                                            |
| `CONNECTION_AGENT_AUTHENTICATIONERROR`                          | The server rejected the site's username, password, or keys.                                                                                                                                                                              |
| `CONNECTION_AGENT_CONNECTIONERROR`                              | Couldn't reach the server. Check host, port, firewall, and that `162.243.9.115` is allowed.                                                                                                                                              |
| `CONNECTION_AGENT_*` (other)                                    | Another connection problem: listing, uploading, or permissions. The `message` explains it.                                                                                                                                               |

## Checking access

There's no "who am I" route. Make one cheap request first:

```
GET /sites?limit=1
```

- `200`: the token works, and the plan includes it.
- `402`: the token works, but the plan doesn't include it.
- `403`: the token is wrong or revoked, the account owner turned agents off, or the token's owner hasn't verified their email address yet (a new account whose owner never followed the link in the welcome email; `emailVerifiedAt` on the user is null until they do). They must do that in the app first.

## Sites

**Site object:** `id`, `name`, `url`, `classification`, `protocol`, `host`, `port`, `s3Region`, `s3Bucket`, `s3Acl`, `r2AccountId`, `homeFolder`, `uploadFolder`, `isLocked`, `canDuplicatePages`, `canDeletePages`, `screenshot`, `createdAt`, `updatedAt`, and a few internal fields.

### `GET /sites`

Lists the sites the user can access. Takes `search` (matches name or URL), `limit`, `offset`, and `sortBy` (`name | createdAt`). Returns `{ offset, limit, count, sites }`.

### `GET /sites/summaries`

Returns `{ sites: [{ id, name, url }] }` for every site the user can access, sorted by name and not paged. Use it to find a site's id by name or URL.

### `POST /sites`

Creates a site. Requires site-management rights. Returns `{ site }`. It doesn't test the connection. See [connecting.md](connecting.md) for what to send for each protocol.

| Field                                    | Type    | Notes                                                                                                                                                                                                             |
| ---------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`*                                  | string  | Shown only in the CMS.                                                                                                                                                                                            |
| `url`*                                   | string  | The public URL of the site's home folder, e.g. `https://www.example.com/`. Must be a valid URL.                                                                                                                   |
| `classification`                         | string  | `commercial` (default), `personal`, `educational`, or `non-profit`. Non-commercial sites are reviewed by Surreal CMS staff.                                                                                       |
| `protocol`                               | string  | `ftp`, `ftps`, `sftp`, `webdav`, `s3`, `r2`, or `spaces`. Any other value causes a `500`.                                                                                                                         |
| `host`                                   | string  | FTP/SFTP hostname or IP (no scheme). For WebDAV, the full `https://` WebDAV URL.                                                                                                                                  |
| `port`                                   | int     | Optional. Defaults are 21 for FTP and FTPS, and 22 for SFTP. Ignored for WebDAV (put the port in `host`).                                                                                                         |
| `username`, `password`                   | string  | FTP, FTPS, SFTP, and WebDAV. SFTP supports passwords only, not keys.                                                                                                                                              |
| `s3AccessKey`, `s3SecretKey`, `s3Bucket` | string  | S3, R2, and Spaces.                                                                                                                                                                                               |
| `s3Region`                               | string  | S3 region code, e.g. `us-east-1`. For Spaces, the datacenter slug, e.g. `nyc3`.                                                                                                                                   |
| `s3Acl`                                  | boolean | S3 only. `true` uploads files as `public-read`. Leave off for modern buckets with ACLs disabled.                                                                                                                  |
| `r2AccountId`                            | string  | R2 only. The 32-character hex Cloudflare account ID.                                                                                                                                                              |
| `homeFolder`                             | string  | The folder that holds the homepage and matches `url`. No trailing slash.                                                                                                                                          |
| `uploadFolder`                           | string  | Where editors' uploads go. Must be the home folder or inside it, publicly reachable, and free of pages. Use a dedicated `uploads` folder: editors can rename, move, and delete anything in it. No trailing slash. |
| `isLocked`                               | boolean | `true` locks the site from edits.                                                                                                                                                                                 |
| `canDeletePages`                         | boolean | Lets users delete page files from the server.                                                                                                                                                                     |
| `canDuplicatePages`                      | boolean | Lets users duplicate pages. Also required for `POST /pages` with `pageId`.                                                                                                                                        |

### `GET /sites/:siteId`

Returns `{ site }`. For users who can manage sites, this includes the connection credentials, except with an agent token, which never receives them. Don't echo them.

### `PUT /sites/:siteId`

Updates a site. Send only the fields you're changing, with the right types: booleans as JSON booleans, and `port` as a number. Returns `{ site }`. The connection isn't tested.

### `DELETE /sites/:siteId`

Permanently removes the site from Surreal CMS, along with everyone's access to it. Files on the server aren't touched. Returns `{ site }`. **Confirm with the user first.**

## Pages

A page is a file on the server that's enabled for editing. **Page object:** `{ id, siteId, name, path, isPinned, createdAt, updatedAt }`.

`path` is relative to the site's home folder, with no leading slash, e.g. `index.html` or `about/index.html`.

### `GET /sites/:siteId/pages`

Takes `search` (matches name or path), `limit`, `offset`, and `sortBy` (`pinned | name | path | createdAt`). Returns `{ offset, limit, count, pages }`.

### `POST /sites/:siteId/pages`

Enables, creates, or duplicates a page. Any user with access to the site can call it. Returns `{ page }`.

| Field            | Type    | Notes                                                                                                                                                         |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`*          | string  | Shown in the page list, e.g. `Home`, `About`.                                                                                                                 |
| `path`*          | string  | Relative to the home folder. In every mode it must stay inside it (`PATH_OUTSIDE_OF_HOME_FOLDER`) and have an editable extension (`FILE_TYPE_NOT_SUPPORTED`). |
| `isPinned`       | boolean | Pins the page to the top of the list.                                                                                                                         |
| `createOnServer` | boolean | Default `true`. `false` (enable an existing file) is admins only.                                                                                             |
| `templateId`     | string  | With `createOnServer: true`, writes this template's source to `path`.                                                                                         |
| `pageId`         | string  | With `createOnServer: true`, copies this page's current file to `path`. Ignored if `templateId` is set. The site needs `canDuplicatePages`.                   |

There are three modes:

- **Enable an existing file:** `{ "name": "About", "path": "about.html", "createOnServer": false }`. The API doesn't check that the file exists, and it doesn't stop you from enabling the same path twice. List pages first, and confirm the file is live, e.g. with `curl -sI <site url>/about.html`. The extension must be editable. To enable several files, use [`POST /sites/:siteId/pages/enable`](#post-sitessiteidpagesenable) instead of one request per file.
- **Create from a template:** `{ "name": "About", "path": "about.html", "templateId": "…" }`. Connects to the server and uploads the template's source. Fails with `FILE_ALREADY_EXISTS` if the path is taken. On FTP, FTPS, SFTP, and WebDAV the folder must already exist; on S3, R2, and Spaces it doesn't matter.
- **Duplicate a page:** `{ "name": "About copy", "path": "about-copy.html", "pageId": "…" }`.

The create and duplicate modes connect to the server. A `CONNECTION_AGENT_*` error means the site's credentials or folders are wrong.

The creating user gets access to the new page automatically. Other clients who are limited to specific pages don't. Update their permissions.

### `GET /sites/:siteId/pages/:pageId`

Returns `{ page }`.

### `PUT /sites/:siteId/pages/:pageId`

Updates `name`, `isPinned`, or `path`. Changing `path` **moves the file on the server**. The new path must stay inside the home folder, have an editable extension, and not already exist. Returns `{ page }`.

### `DELETE /sites/:siteId/pages/:pageId`

**Deletes the file from the server by default.** To stop editing a page and leave the file alone, always send:

```json
{ "deleteFromServer": false }
```

Only send `{ "deleteFromServer": true }` when the user explicitly wants the file gone. The site must allow `canDeletePages`. Disabling with `false` is admin-only, as in the app. Returns `{ page }`.

### `POST /sites/:siteId/pages/delete`

Batch version: `{ "pageIds": [...], "deleteFromServer": false }`. The same default applies: leaving out `deleteFromServer` deletes files, and the site must allow `canDeletePages`. Ids of pages the user can't access are ignored and appear in neither list. Returns `{ succeeded: [pages], failed: [pages] }`.

### `POST /sites/:siteId/pages/enable`

Enables files that already exist on the server as pages, in one request. Admins only. Nothing is written to the server. Returns `{ pages }` in the order sent.

```json
{
  "pages": [
    { "path": "index.html", "name": "Home", "isPinned": true },
    { "path": "about.html", "name": "About" },
    { "path": "contact/index.html", "name": "Contact" }
  ]
}
```

Up to 1,500 pages. Every entry needs a `path` (relative to the home folder, with an editable extension) and a `name`; `isPinned` defaults to `false`. The whole list is validated before anything is created, so a bad entry fails the request with `VALIDATION_ERROR` or `FILE_TYPE_NOT_SUPPORTED` and nothing changes. A path that is already enabled comes back as its existing page instead of a duplicate, so the call is safe to repeat. Prefer this over one `POST /sites/:siteId/pages` per file: it is one request under the rate limit, and the creating user gets access to every page.

## Templates

**Template object:** `{ id, siteId, name, description, extension, source, createdAt, updatedAt }`. Up to 100 per site. Creating, updating, and deleting need an admin; reading needs site access.

- `GET /sites/:siteId/templates`: takes `search` (name or extension), `limit`, `offset`, and `sortBy` (`name | createdAt`). Returns `{ …, templates }`.
- `POST /sites/:siteId/templates`: takes `name`_, `description`_, `extension`* (with the leading dot, e.g. `.html`; must be an editable extension), and `source`* (the full file contents). Returns `{ template }`.
- `GET /sites/:siteId/templates/:templateId`: returns `{ template }`.
- `PUT /sites/:siteId/templates/:templateId`: takes any of `name`, `description`, `extension`, `source`. Returns `{ template }`. Pages already created from it don't change.
- `DELETE /sites/:siteId/templates/:templateId`: returns `{ template }`. Pages created from it don't change.

Editors see a site's templates under **New Page**. Keep only the ones they should use. Anyone with access to the site can add a page from a template; only admins can add templates.

## Blocks

**Block object:** `{ id, siteId, name, description, source, createdAt, updatedAt }`. Up to 100 per site. Top-level elements can't have an `id`. Creating, updating, and deleting need an admin.

- `GET /sites/:siteId/blocks`: takes `search` (name), `limit`, `offset`, and `sortBy` (`name | createdAt`). Returns `{ …, blocks }`.
- `POST /sites/:siteId/blocks`: takes `name`_, `description`_, and `source`*. Returns `{ block }`.
- `GET /sites/:siteId/blocks/:blockId`: returns `{ block }`.
- `PUT /sites/:siteId/blocks/:blockId`: takes any of `name`, `description`, `source`. Returns `{ block }`.
- `DELETE /sites/:siteId/blocks/:blockId`: returns `{ block }`.

Editors find blocks by name or description in the **Blocks** panel and insert them at the cursor, so write descriptions that say what a block is for.

## Users

**User object:** `id`, `name`, `email`, `avatar`, `bio`, `isOwner`, `isAdmin`, `canManageSites`, `canManageUsers`, `canManageSettings`, `canManageBilling`, `requiresTfa`, `emailVerifiedAt` (null only for an owner who signed up and hasn't followed the welcome link), `lastSeen`, `createdAt`, `updatedAt`.

**Roles:**

- **Owner:** created the account. Can't be deleted, and only the owner can edit the owner.
- **Admin** (`isAdmin: true`): sees every site and page. `canManageSites`, `canManageUsers`, `canManageSettings`, and `canManageBilling` add management rights. Only the owner can grant them.
- **Client** (`isAdmin` false or omitted): sees only the sites and pages in their permissions. Can't use the source editor, except on CSS, JS, JSON, and TXT pages, which only open there. A new client has **no access** until you set permissions.

### `GET /users`

Admins only. Takes `search` (name or email), `limit`, `offset`, and `sortBy` (`name | role | createdAt`). Returns `{ …, users }`. Search by email before creating someone, to avoid `EMAIL_IN_USE`.

### `POST /users`

Needs user-management rights. Returns `{ user }`.

| Field                                   | Type    | Notes                                                                                                                                                                                                                  |
| --------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`*                                 | string  | A person's name, 60 characters at most. Links, domains, email addresses, markup, and six or more digits are refused with `INVALID_NAME` (`invalid: ['name']`), because emails print it.                                |
| `email`*                                | string  | Must be unused across all of Surreal CMS.                                                                                                                                                                              |
| `password`                              | string  | 8+ characters. A token can't set one (`403`); send `message` instead.                                                                                                                                                  |
| `message`                               | object  | Required when `password` is omitted. All four fields are required strings: `subject`, `intro`, `callToAction`, `outro`. Surreal CMS emails the user an activation link, with replies going to the token owner's email. |
| `avatar`                                | string  | Image URL or `data:` URI.                                                                                                                                                                                              |
| `bio`                                   | string  |                                                                                                                                                                                                                        |
| `isAdmin`                               | boolean | Omit for a client. A token can't create an admin (`403`); the user does that in the app.                                                                                                                               |
| `canManageSites`, `canManageUsers`      | boolean | Owner-only (`VALIDATION_ERROR`, with the flags in `invalid`). Cleared unless `isAdmin: true`.                                                                                                                          |
| `canManageSettings`, `canManageBilling` | boolean | Owner-only (`VALIDATION_ERROR`, with the flags in `invalid`), and require `isAdmin: true`.                                                                                                                             |

A good invitation:

```json
{
  "name": "Bob Rivera",
  "email": "bob@clientco.com",
  "message": {
    "subject": "Your login for the Acme website",
    "intro": "Hi Bob, you can now update the Acme website yourself. Activate your account to get started.",
    "callToAction": "Activate my account",
    "outro": "Questions? Just reply to this email."
  }
}
```

### `GET /users/:userId`

Returns `{ user }`.

### `PUT /users/:userId`

Takes any of `name`, `email`, `password`, `avatar`, `bio`, `isAdmin`, and the `canManage*` flags. `name` follows the same rule as `POST /users`. Changing `isAdmin` requires `canManageUsers`, so a user editing themselves can't change their own role (`403`). Only the owner or the admin themself can change an admin's `email` or `password`, and never with a token (`403`). Sending the current email unchanged doesn't count as a change. Saving a user as a non-admin clears all their `canManage*` flags and revokes their API token. Returns `{ user }`.

### `DELETE /users/:userId`

Permanently removes the user and their permissions. The owner can't be deleted. Returns `{ user }`. **Confirm with the user first.**

## Permissions

Permissions decide which sites and pages a client can see. Admins see everything regardless.

### `GET /users/:userId/permissions`

Returns `{ permissions: [{ id, userId, siteId, pages, site, … }] }`.

### `PUT /users/:userId/permissions`

**Replaces all of the user's permissions.** Always `GET` first, change the list, then send the whole list back.

```json
{
  "permissions": [
    { "siteId": "SITE_A", "pages": null },
    { "siteId": "SITE_B", "pages": ["PAGE_1", "PAGE_2"] }
  ]
}
```

- `pages: null` (or omitted) grants **every page on the site, including pages added later**.
- `pages: [ids]` grants only those pages. Send a real JSON array of page UUIDs, not a string.
- An **empty array, a string, or a list with no valid UUIDs is treated as `null`: every page.** There's no way to grant a site with zero pages. To remove access to a site, leave it out of the list.
- Sites outside the account are silently skipped. Removing a site also removes the user's favorite for it.
- Returns the new `{ permissions }`. Check that it matches what you meant to send.

## Change notifications

Admins can get an email when someone else publishes on a site. Notifications only go to admins.

- `GET /users/:userId/change-notifications/:siteId`: returns `{ changeNotification }`, or `404` if notifications are off.
- `POST /users/:userId/change-notifications/:siteId`: turns them on.
- `DELETE /users/:userId/change-notifications/:siteId`: turns them off.

## Favorites

Favorited sites appear in the user's sidebar.

- `GET /users/:userId/favorites`: takes `siteId`, `limit`, `offset`, and `sortBy` (`name | createdAt`). Returns `{ …, favorites }`.
- `GET`, `POST`, or `DELETE /users/:userId/favorites/:siteId`: returns `{ favorite }`.

## Revisions

Revisions are published copies of a page's regions and metadata. The last 20 are kept per page. Drafts are revisions with `isDraft: true`. A revision with `isCapture: true` is the copy of the live page the editor stored the first time it opened a page with no published version; it is kept outside the 20 and its `userId` is whoever opened the page. A draft with `publishAt` set is scheduled to publish at that time; its `scheduleStatus` is `pending`, `publishing`, or `failed`. **Revision object:** `{ id, userId, siteId, pageId, isDraft, isCapture, metadata, regions, publishAt, scheduleStatus, createdAt, updatedAt }`, plus a few more scheduling fields.

- `GET /sites/:siteId/revisions`, `GET /sites/:siteId/pages/:pageId/revisions`, and `GET /users/:userId/revisions` take `limit`, `offset`, and `sortBy` (`isDraft | createdAt`; newest first by default).
- `GET /sites/:siteId/pages/:pageId/revisions/:revisionId`: returns `{ revision }`.
- `DELETE /sites/:siteId/pages/:pageId/revisions/:revisionId`: permanent. Deleting a scheduled draft cancels its scheduled publish, so confirm first.

Restoring a revision happens in the editor.

## Editable extensions

`.asp .aspx .ascx .cshtml .css .ctp .dwt .htm .html .inc .js .json .jsp .lasso .master .phtml .php .py .rb .shtm .shtml .txt .tpl`
