# Platform reference

> The platform contract for agents: accounts, upload limits, routes, saving, sharing and local hosts.

Source: https://hyperclay.com/docs/platform-reference/

> Hyperclay (https://hyperclay.com) is a hosting platform for malleable documents: single
> HTML documents that hold an application's interface, behavior, content and current state,
> and that save themselves back to the server as their own next version. The DOM is the
> database. A save is one POST of the whole serialized document, and the host answers by
> writing bytes and filing a version. There is no build step, no deploy, and no place to run
> server code: if a project needs custom backend logic, Hyperclay is the wrong host.

This page is the platform reference for agents. The human-readable documentation is
at https://hyperclay.com/docs/, with the product pages at https://hyperclay.com,
https://hyperclay.com/features and https://hyperclay.com/pricing. Hyperclay itself is a hosted
service, not a package you install. The client library that makes a page malleable is separate
and open source: ClayJS (MIT-0) at https://clayjs.com, whose own agent reference is at
https://clayjs.com/llms.txt. The document format is specified at https://malleabledocument.com
(CC0). Signup is free for up to 10 documents, and the paid plans are Personal at $6 per month
or $48 per year and Maker at $15 per month or $120 per year.

## Quick start

1. Start free at https://hyperclay.com/free-signup: enter an email address, open the link it
   sends you, and choose a username and password at `https://hyperclay.com/_/welcome/<token>`.
   For a paid plan, subscribe at https://hyperclay.com/pricing instead. Either way you land on
   `https://hyperclay.com/_/dashboard`.
2. Create an app called `notes`. It lives at `https://<username>.hyperclay.com/notes.html`. A
   free account cannot create a document from scratch: it copies one of the templates at
   https://hyperclay.com/templates instead.
3. Open the dashboard's Code panel at `https://hyperclay.com/_/dashboard/site/<id>/code` and
   paste a document whose `<html>` carries `autosave` and whose `<head>` carries
   `<script src="https://clayjs.com/v1/clay.js"></script>`. The old
   `https://<username>.hyperclay.com/_/edit/notes.html` redirects there. The Code panel is a paid
   feature; a free account edits a copy of a template in place instead.
4. Open the app itself. It opens in view mode, even for you. Because you own it, you can switch to
   editing: press Cmd+Shift+E (Ctrl+Shift+E on Windows and Linux), or open it with `?editmode=true`.
   Type into an `editable` element. Ctrl+S saves, or autosave does it for you.
5. Open the same URL in a private window. You get the plain page with no edit controls.
6. `https://hyperclay.com/_/dashboard/site/<id>/versions` is the Versions panel, and it lists
   every save. The old `https://<username>.hyperclay.com/_/versions/notes.html` redirects there.
   `https://<username>.hyperclay.com/_/download/notes.html?file=1` gives you the file.

## What a malleable document is

One `.html` (or `.htmlclay`) file contains the markup, the styles, the scripts, the content,
the current state, and the controls for editing itself. Visitors get a plain static page.
The owner gets edit controls, which are stripped from the copy that is written to disk, so the
saved file stays clean for the next visitor.

The cycle is always the same:

1. The browser loads the document.
2. If the viewer may edit, ClayJS records that permission, but the page still opens in view. Edit
   mode arms when the viewer switches to it (the **Edit** switch, Cmd+Shift+E, or
   `clay.setMode('edit')`) or opens the page with `?editmode=true`.
3. Edits mutate the live DOM. The DOM is the state, so there is nothing else to persist.
4. On save, the client clones the document, strips editor-only regions from the clone,
   serializes it, and POSTs that text to the host.
5. The host writes it as the file and files a version.

The live page is never touched by the save. The page you are editing keeps its controls.

## Get an account

Signup is free or paid, and every account chooses a username.

The free plan:

1. `https://hyperclay.com/free-signup` takes an email address and mails a signup link to it. The
   account does not exist until that link is opened, so the address is confirmed before anything
   is created for it.
2. The link opens `https://hyperclay.com/_/welcome/<token>`, which asks for a username and a
   password (8 or more characters, checked against a 100k common-password list).
3. The account becomes `account_type: app_user` on the `free` tier and lands on
   `https://hyperclay.com/_/dashboard`. It holds up to 10 documents and cannot create a blank
   document or a folder; it copies a template instead.

The way most people reach that form is a template's own copy button, which carries the document
back as a `return` value: the copy page links to
`https://hyperclay.com/_/signup?return=<copy page>`, and the plans page offers the free plan
beside the two paid ones.

The paid plans:

1. `https://hyperclay.com/signup` (the plan-picker page) or `https://hyperclay.com/pricing`
   (the marketing page) starts Stripe Checkout for a tier (`personal` or `maker`) and a plan
   (`monthly` or `annual`). They are two different pages into the same checkout.
2. Checkout succeeds and returns to `https://hyperclay.com/_/set-password?session_id=<checkout session id>`.
3. That page retrieves the checkout session from Stripe, creates the person it names, and asks
   for a username and password (8 or more characters, checked against a 100k common-password list).
4. The account becomes `account_type: dev` and lands on `https://hyperclay.com/_/dashboard`.

The username can be changed at `/_/set-username`, but only once every 30 days. Since the
username is the subdomain, changing it moves every URL under it.

The session is the `auth_token` cookie, valid for 30 days, apex-scoped so it rides along on
every `*.hyperclay.com` subdomain. Log in at `https://hyperclay.com/_/login`, out at
`https://hyperclay.com/_/logout`.

The `free` tier governs a new free signup, a lapsed subscription and the end users who sign up
to somebody else's multi-tenant app. It caps documents at 10, with no subdomains, no
multi-tenant apps and no blank documents.

## Where your files live

An account is a namespace. Every app sits inside it:

```
https://<username>.hyperclay.com/<app>.html
https://<username>.hyperclay.com/<folder>/<app>.html
```

Folders mirror into the URL. The root of a subdomain resolves to `index.html`. Folders nest up
to 5 levels; deeper returns `Maximum folder depth reached (5 levels)`.

Inside a multi-page site (a folder holding `site.json`), pages also answer without `.html`:
`/<folder>/about` serves `<folder>/about.html`. The lookup order is the exact file, then
`<path>.html`, `<path>.htmlclay`, `<path>/index.html`, then an upload. An unknown path inside a
site answers 404. Opening `<folder>/about.html` redirects (302) to `/<folder>/about`, and an
index page reached without its trailing slash redirects to the slash form. Saves and API calls
never redirect. A page whose clean address would clash with a reserved action word, such as
`edit`, keeps its `.html` address. Outside a site, nothing changes.

Three ways to reach one app:

- **Namespace URL**, always available: `https://<username>.hyperclay.com/<app>.html`
- **Promoted subdomain** (paid): claim `https://<name>.hyperclay.com` for one app. The app then
  sits at the **root** of that hostname, not at `/<app>.html` under it, which is the difference
  between a promoted subdomain and the account namespace every file already has.
- **Custom domain** (paid plans, unlimited): point your own domain at one app, with automatic SSL.

A promoted subdomain or a custom domain can also point at a site folder. It then serves the whole
folder: `index.html` at `/`, other pages at clean addresses, uploads beneath it, and 404 for a
path that names nothing. Only folders that are sites can have domains, wildcard domains cannot
point at a folder, and renaming or moving the folder keeps its domain working.

Name rules, enforced in `shared/validation.js`:

- Site names match `^[a-z0-9_-]+\.(html|htmlclay)$`. A name with no recognized extension gets
  `.html` appended. Max 255 characters.
- Folder names and usernames match `^[a-z0-9_-]+$`.
- No leading or trailing dash, no `--`, no Windows device names (`con`, `prn`, `aux`, `nul`,
  `com1`..`com9`, `lpt1`..`lpt9`).
- `_` is reserved for the system-route marker and can never be claimed, for every name type,
  not even by a superadmin.
- **Usernames and subdomains only** are additionally checked against about 666 exact reserved
  words (`api`, `app`, `auth`, `blog`, `www`, ...) plus 17 substring blocks: `account`,
  `admin`, `billing`, `folder`, `help`, `hyperclay`, `identi`, `moderator`, `owner`,
  `password`, `payment`, `root`, `securit`, `server`, `settings`, `system`, `user`. Site names
  and folder names are **not** checked against those lists, so `api.html` and a folder named
  `settings` are both creatable.

Platform routes live under the reserved `/_/` marker, so they can never collide with a file or
folder name. Older bare forms (`/edit/...`, `/save`) still route, but write `/_/`. The public
marketing and legal pages on hyperclay.com itself are the exception and stay bare
(`/features`, `/pricing`, `/signup`, `/terms`). An unknown path under `/_/` is a
404 rather than falling through to a document.

## Make a page save itself

The current library is ClayJS. One script tag is the whole integration. This is the platform's
Blank template with the `menu` plugin added, which gives the owner an **Edit** switch, because a
document opens in view (the Blank template itself loads `sync,indicator,ai-edit`):

```html
<!DOCTYPE html>
<html lang="en" autosave>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My HTML App</title>
  <script src="https://clayjs.com/v1/clay.js?plugins=sync,indicator,menu&exclude=richclay"></script>
</head>
<body>
  <h1 editmode:contenteditable>My HTML App</h1>
</body>
</html>
```

`autosave` on `<html>` saves after edits settle. Ctrl+S and Cmd+S always work. `clay.save()`
saves on demand. The full attribute and API surface is at https://clayjs.com/llms.txt; the
short version:

- `editable` on an element for rich text, `editmode:contenteditable` for owner-only plain text.
- `persist` on a form control to write its value into the saved HTML.
- `viewmode:disabled` / `viewmode:readonly` to make a control live for the owner and inert for
  visitors.
- `sortable="name"` for drag-to-reorder lists (the `sortable` plugin), which fires `clay:sorted`.
- `clay="no-save"` for page chrome that must never reach disk, `clay="freeze"` for computed
  text, `clay="no-watch"` for third-party widgets.
- `trigger-save` on a `<button type="button">` for an explicit save button.

ClayJS stamps these attributes on `<html>` for your own CSS and logic: `editmode` (`true` or
`false`), `pageowner` (`true` or `false`), `canedit` (present as `true` while this person may edit,
even in view), and `savestatus` (`saving`, `saved`, `error` or `offline`). Two more attributes come
from separate satellite scripts, both used by the platform templates: `option:editmode="true"` (show
an element only in edit mode) needs `https://clayjs.com/v1/clay-options.js`, and `onclone` (reset a
freshly cloned element) needs `https://clayjs.com/v1/clay-events.js`. Each one loads with its own
script tag.

ClayJS exposes `window.clay`. It is not required: a page that speaks the save endpoint by hand
works just as well.

## The save round trip

```
POST https://<username>.hyperclay.com/_/save
Document-URL: https://<username>.hyperclay.com/<folder>/<app>.html
Save-Trigger: user
Content-Type: text/plain
Cookie: auth_token=...
Origin: https://<username>.hyperclay.com

<!DOCTYPE html><html>...the entire document...</html>
```

That is what ClayJS sends. `fetch` with a string body and no explicit `Content-Type` produces
exactly the right request:

```js
const documentHtml = clay.getHTML()
await fetch(new URL('/_/save', location.origin), {
  method: 'POST',
  credentials: 'same-origin',
  headers: {
    'Document-URL': location.href,
    'Save-Trigger': 'user'
  },
  body: documentHtml
})
```

If you build `documentHtml` by hand, capture a prepared clone rather than the live DOM. The
libraries remove editor-only regions from that clone, which is what keeps a visitor's copy clean.
A hand-rolled `outerHTML` save writes toolbars and admin controls into the file. Prefer
`clay.save()`, or `clay.getHTML()` if you want the prepared string to send yourself.

Rules the server actually enforces (`server-lib/state-actions.js`, `server-lib/spec-wire.js`):

- **The body is the document, as text, always.** A JSON body is refused with `415` and
  `{"code":"invalid-document"}` rather than guessed at. The check is on `Content-Type`.
- **Use a `text/*` media type or send no `Content-Type` at all.** The server parses this route
  with `express.text({ type: 'text/*', limit: '16mb' })`, so both `text/plain` and `text/html`
  are accepted. A JSON media type is refused deliberately.
- **The body must be a complete document with a top-level `<html>` element**, or `422` with
  `{"code":"invalid-document"}`. This is what stops a fragment or an empty body from replacing
  a whole page.
- **A document can be up to 8 MB.** The body limit is 16 MB because a body can also carry the page editor's merge state; the 8 MB check applies to the stored file and answers `413` with `{"code":"too-large"}`.
- **`Document-URL` names the target document.** The path carries no filename, so this header is
  how the server knows which file is being saved. `Page-URL` is the older spelling and is still
  read; `Document-URL` wins when both are present.
- **`Save-Trigger: user` or `auto`** records whether a human gesture is behind the save. The
  older `X-Hyperclay-User-Driven` is read when `Save-Trigger` is absent.
- **`If-Match: <etag>` is optional and honored.** It is compared against the bytes on disk right
  now, not against a cached column. A mismatch returns `412` with `{"code":"conflict"}` and
  leaves the document and its version history byte-identical. `If-Match: *` asks only that the
  document exist. An empty `If-Match` value matches nothing and is refused.
- **A save may not lower a document's page format floor.** The floor is
  `<meta name="clay-blockeditor-format" content="N">` in the document, and no meta means floor 0. ClayJS
  sends the format it can read as `X-Clay-Blockeditor-Format`. A save that declares less than the
  document's floor, or less than its own content needs, answers `409` with
  `{"code":"blockeditor-format-upgrade-required","minimum":N}` and writes nothing. A save without the
  header declares 0, so a hand-rolled save is accepted only on a floor 0 document. The floor only
  rises: a version restore or a device upload keeps the higher one.

Responses:

```json
{ "msg": "Saved", "etag": "7bbe7fdbd7b1c99b" }
```

An unchanged document is not rewritten and still answers with `msg` and the current stamp:

```json
{ "msg": "Saved", "etag": "7bbe7fdbd7b1c99b" }
```

The `etag` is the first 16 hex characters of the SHA-256 of the bytes the host **stored**, not
the bytes it was sent. Those differ whenever a document opts into reformatting.

What one successful save does, in order:

1. Reformats the HTML **only if** the root `<html>` element carries the literal attribute
   `formathtml="true"`. Any other value, or the attribute anywhere else, stores the bytes
   exactly as sent. Even when opted in, formatting is declined and the bytes stored as sent
   past 256 levels of nesting, past a projected 32 MB of output, or when the formatted result
   would be more than 3 times the input. A decline is silent and never fails the save.
2. Reads the current file from disk.
3. Answers `412` if an `If-Match` was sent and does not match the bytes on disk.
4. Answers `409` if the save cannot be admitted: it declares a lower page format than the document
   needs, or it replaces a page whose live editing session it does not descend from.
5. Returns early with `msg: "Saved"` and the current etag if the bytes are unchanged.
6. Files a version (see below). On the very first save it files the pre-existing content first.
7. Writes the file. This is the commit point.
8. Best-effort afterwards, none of which can fail the save: updates the content hash,
   broadcasts to live-sync subscribers, scans the HTML, rewrites the `/_/api` JSON sidecar,
   runs the data-clobber guard, and recompiles Tailwind if the page links a
   `/tailwindcss/...` stylesheet.

### Host discovery

```
GET https://<username>.hyperclay.com/_/meta
Document-URL: https://<username>.hyperclay.com/<folder>/<app>.html
```

```json
{
  "spec": 1,
  "extensions": ["conditional", "data-read", "format", "live-data", "live-provenance", "blockeditor", "blockeditor-awareness-v1", "blockeditor-recovery-v1", "people", "presence", "presence-editing", "receipts", "record-awareness-v1", "save-history", "scoped-stylesheet", "sync", "upload", "blockeditor-format-v1"],
  "document": { "maxBytes": 8388608, "maxBytesMeasures": "file", "blockeditorState": { "href": "/_/blockeditor-state" },
                "etag": "7bbe7fdbd7b1c99b", "upload": { "allowed": false }, "writable": false, "people": { "me": null } }
}
```

The `document` block is absent for a caller who may not read that document, which is the same answer
as for a document that does not exist, so this route cannot be used to probe for private files.
`upload.allowed` reflects whether **this** caller may upload to **this** document, so a page on a
lapsed plan can avoid sending megabytes that will be refused. `writable` says whether **this**
caller's save would be admitted. ClayJS reads it to decide whether to offer edit at all, so a person
who may not save never sees the way in. `versions` is `true` when the caller may open version
history, and `maxBytes` is the save limit the host enforces.

### Cross-site writes are blocked

Any `POST`, `PUT`, `PATCH` or `DELETE` that carries the `auth_token` cookie must also carry an
`Origin` header whose host equals the browser-facing host. A missing `Origin`, a `null` origin,
or a different host all return:

```json
{ "error": "Cross-site request blocked" }
```

with status `403`. A plain `curl -X POST` with a copied cookie and no `Origin` header will fail
this way. Requests that carry no `auth_token` cookie skip the guard entirely, which is why the
API-key sync lane and webhooks are unaffected. The collection records lane and newsletter
subscribe are exempt and apply their own origin checks.

## Edit mode and ownership

Whether a save is accepted is always the server's decision. ClayJS decides two things on the client.
Whether this person **may** edit (`clay.canEdit`) resolves in this order:

1. `?editmode=true` or `?editmode=false` in the URL
2. `window.clayEditMode`, set before `clay.js` loads
3. an authored `viewonly` on `<html>`, which rules edit out
4. a save token placed on the root element by the host
5. the platform's owner cookie, `isAdminOfCurrentResource`

Whether the tab **is** editing (`clay.mode`) is separate. Every document opens in view, the owner's
included, and starts in edit only for `?editmode=true`, `window.clayEditMode = true`, an authored
`<html opens-in="edit">`, or this tab's own choice carried across a reload. The way in is the
**Edit** switch the `menu` plugin draws, Cmd+Shift+E (Ctrl+Shift+E), or `clay.setMode('edit')`. If
`/_/meta` answers `writable: false`, ClayJS takes edit away.

The server sets `isAdminOfCurrentResource` on every site request: present when the viewer owns
the resource, cleared when they do not. Visiting your own app with `?editmode=true` opens it
straight into editing; `https://panphora.hyperclay.com/core/hours.html?editmode=true` is a live
example.

Who may save a given app:

- The owner, logged in.
- An editor of the team that owns it.
- A holder of a valid edit link (elevated to `app_user` with ownership of that one app).
- Nobody else. A visitor gets a static page.

A share guest with an edit link can save but cannot open the code editor; a view link's guest
can read the app but not save, and only a paid account can mint an edit link.

## Version history and restore

Every save files a version, permanently. Nothing overwrites a version.

Storage is a snapshot-and-diff chain per file (`server-lib/backup-service.js`): version 1 and
every 20th version store the full HTML, the versions in between store a patch against the
previous version plus a pointer to the nearest snapshot. Reading any version rebuilds the full
HTML transparently.

| Method | Route | Who |
|---|---|---|
| GET | `https://hyperclay.com/_/dashboard/site/<id>/versions` | owner: the Versions panel, most recent 50 |
| GET | `/_/version/<backupId>` | owner: that version's full HTML |
| POST | `/_/restore/<backupId>` | owner: restore that version |

Restoring is itself safe. It files the current content as a version first, writes the restored
HTML, then files the restored content as another version, so a restore never destroys anything.

If a site's file goes missing on disk, the serve path restores it from the most recent version
automatically.

## Uploads

```
POST https://<username>.hyperclay.com/_/upload
Content-Type: application/json
Origin: https://<username>.hyperclay.com

{ "fileName": "logo.png", "fileBody": "<base64>", "parentId": "root" }
```

Multipart also works: a `file` field (repeatable) plus an optional `parentFolderId`. When no folder
is named, a page's upload goes into the account's `uploads/assets-document-<document id>/` folder
and its `url` is the host path `/_/uploads/assets-document-<document id>/<name>`, which works at
every address the document is served from and survives renaming or moving it. Once the account's
uploads are protected, that file answers only to people who can open the document. A named folder
gets a full URL, as below. The top-level `uploads` folder cannot be renamed, moved or deleted. The
route is owner-only from an app's own URL, and also available on `https://hyperclay.com` for the
dashboard's file manager.

The response carries the URL, which is authoritative and must not be guessed. Read it from
`uploads[0].url`, not from the top level. A page's upload gets `msgType`, `msg`, `uploads` and
`urls`; `html`, a rendered fragment of the file manager's list, is returned only by the
dashboard's own upload.

```json
{ "msgType": "success",
  "msg": "Uploaded 1 file",
  "uploads": [ { "name": "logo-9f2a1e.png", "nodeId": 123, "bytes": 20481,
                 "url": "https://<username>.hyperclay.com/logo-9f2a1e.png" } ],
  "urls": [ "https://<username>.hyperclay.com/logo-9f2a1e.png" ] }
```

The stored name is always `<stem>-<first 6 hex of the sha256><ext>`, applied on every upload
rather than only on a collision, so the same bytes sent twice land on one file and a retried
upload creates no duplicate. Files are also reachable at
`https://<username>.hyperclay.com/uploads/<username>/<folder>/<name>`.

Limits by tier:

| Who | Per file | Total |
|---|---|---|
| personal | 20 MB | 500 MB |
| maker | 100 MB | 2 GB |
| a free account | 10 MB | 25 MB, images only |
| an end user of somebody's multi-tenant app | 10 MB | 500 MB |
| a personal account whose subscription lapsed | 10 MB | 25 MB, images only |
| a lapsed team's owner or member | cannot upload | |

`server-lib/state-actions.js` resolves the upload allowance in that order: superadmin, then the
caller's own active subscription, then the subscription of the owner of the multi-tenant app
they are an instance of, then the free tier's flat allowance, which is images only. A personal
account whose subscription has lapsed resolves to the free tier and keeps that allowance; a
lapsed team's owner and its members hold no upload capability and cannot upload at all.

Refusals:

- `402` with `{"code":"payment-required"}` when the caller has no upload allowance.
- `413` with `{"code":"too-large"}` past the per-file cap.
- `400` past the storage total.
- `415` with `{"code":"unsupported-type"}` when a **document** uploads `.html`, `.htm`,
  `.xhtml`, `.htmlclay`, `.js`, `.mjs` or `.xml`. Uploads and documents share one origin, so an
  uploaded page or script could otherwise read a document's response and save as that document.
  Documents go through `/_/save`; scripts belong inside the document. The dashboard's own file
  manager is not on this lane and is not restricted this way.

Every upload is served with `X-Content-Type-Options: nosniff`. An uploaded SVG is served with
`Content-Disposition: attachment`, which costs nothing in practice because `<img src>` still
renders it at full size.

From a page you rarely call the route yourself. The ClayJS `upload` plugin wraps it
(`clay.js?plugins=upload`):

```js
const result = await clay.upload(file, { onProgress, signal })
if (result.ok) image.src = result.uploads[0].url
await clay.upload(new File([JSON.stringify(data)], 'backup.json', { type: 'application/json' }))
```

`clay.upload` posts a file you supply from an input, a drop or a paste. It never rejects, opens no
picker and inserts nothing, so write the URL into the page yourself. The `quickcrop` plugin adds
`clay.quickcrop(file)` for an image crop step before sending.

Other file routes: `POST /_/rename-upload`, `POST /_/delete-upload`, and
`GET /_/edit/uploads/<username>/<path>/<file>` for text files that can be edited in place; it
redirects to the file's Code panel at `https://hyperclay.com/_/dashboard/site/<id>/code`.

## Tailwind CSS on save

Link a stylesheet whose path mirrors the document's own path:

```html
<link rel="stylesheet" href="/tailwindcss/my-app.css">
```

For an app at `/projects/todo.html` that is `/tailwindcss/projects/todo.css`. The CSS is
compiled on every save from the classes actually present in the file, with the typography and
forms plugins available, and is served statically by nginx. No config file, no build step. It
also regenerates on first request if missing. This works on hyperclay.com and in Hyperclay
Local.

## Reading a page as JSON

Every page is already structured data. A small map from field names to CSS selectors turns it
into JSON. The same grammar works in three places.

| Pattern | Reads |
|---|---|
| `"h1"`, `".class"`, `"#id"`, `"[attr]"` | the element's text |
| `"."` | the current element, inside an iteration |
| `".price@data-cents"`, `"a@href"`, `"img@src"` | an attribute |
| `"input@value"`, `"@checked"` | a DOM property |
| `".tag[]"` | every match, as an array |
| `".site-name[*]"` | the first match; a write sets every match |
| `[".post", { "title": ".title" }]` | iterate, extract a shape from each |
| `{ "meta": { "author": ".name" } }` | nest freely |

### A named endpoint the page publishes about itself

Put the rules in the page:

```html
<script type="application/json" data-rules-name="api" data-rules-version="1">
{ "title": "h1", "posts": [".post", { "heading": ".post-title", "author": ".author" }] }
</script>
```

The page then serves that JSON at:

```
GET https://<username>.hyperclay.com/_/api/<folder>/<app>.html
```

The response is the bare extracted JSON and is public. The static hit sends
`Access-Control-Allow-Origin: *`; the Express fallback echoes the request `Origin` and adds
`Access-Control-Allow-Credentials: true` when one is present, sending `*` only when it is
absent. Treat it as a read endpoint: it never changes the document. On an
nginx miss it does rewrite the static sidecar as a cache, and it deletes a stale sidecar and
answers `400` when the page's rules tag is malformed.
`data-rules-version` must be `"1"`. One tag can serve several consumers with space-separated
tokens, for example `data-rules-name="api cms"`.

This is the reliable public JSON endpoint. It is written to a static file on every save and
served directly by nginx, with an Express fallback that regenerates it on a miss. A page with
no such tag answers `400`:

```json
{"error":"No api rules tag","message":"This page has no rules tag with data-rules-name~=\"api\"."}
```

### Site data

A folder that directly holds a public file named `site.json` is a
multi-page site. The nearest `site.json` covers the pages in its folder and subfolders. A page
says where each shared value goes through a reserved `site` key in its `api` rules tag:

```html
<script type="application/json" data-rules-name="api" data-rules-version="1">
{"site": {"name": ".site-name[*]", "nav": ["nav a", {"label": ".", "href": "@href"}]}}
</script>
```

When `site.json` changes, the server writes the new values into every page of the site through
each page's own rules, and saves each page that changed as one new version. Shared values are
text and attributes only. A page save never changes `site.json`, and every save keeps the
current shared values. See https://hyperclay.com/docs/multi-page-sites/.

`site.json` has its own address under `/_/api`:

```
GET  https://<username>.hyperclay.com/_/api/<folder>/site.json   read the shared values
POST https://<username>.hyperclay.com/_/api/<folder>/site.json   merge top-level keys
PUT  https://<username>.hyperclay.com/_/api/<folder>/site.json   replace the whole object
```

On a domain attached to the site folder, the path is `/_/api/site.json`. `GET` is public and
answers the object with an `ETag`, `Cache-Control: no-cache` and `Access-Control-Allow-Origin: *`.
The owner, a team editor, or the owner's sync key (`X-API-Key: hcsk_...`) can write, with an
`application/json` body. A share link for one page cannot. `If-Match` is honored when sent and
not required. `""` and `[]` are real values that clear what the pages show; a key missing from
`site.json` leaves the pages as they are. A write answers:

```json
{"etag": "...", "changed": true, "pages": {"total": 5, "updated": 5, "unchanged": 0, "failed": [], "pending": false}}
```

If the pages take longer than 8 seconds, `pages` is `{"pending": true}` and the work finishes in
the background. An identical body answers `"changed": false` and does nothing. Each page is
written on its own and the run never rolls back: `failed` names each page that was not updated,
with the key and the reason, for example a rule that matches no element.

| Status | Code | When |
|---|---|---|
| 400 | `invalid-body` | the body is not a JSON object |
| 401 | `unauthorized` | no credentials, or a bad or expired sync key |
| 403 | `forbidden` | the writer cannot edit the folder, for example a team viewer |
| 404 | `no-site-data` | the folder has no `site.json` |
| 404 | `not-found` | the path names nothing |
| 409 | | `POST` into a `site.json` that is not a JSON object: replace it with `PUT` |
| 412 | `conflict` | `If-Match` is stale; the body carries the current `etag` |
| 413 | `too-large` | `site.json` would be larger than 1 MB |
| 415 | `invalid-body` | the body is not `application/json` |
| 422 | | `GET` when `site.json` is not a valid JSON object |

Agents use `/documents/<id>/site-data` on the agent API instead, where `If-Match` is required.
See https://hyperclay.com/docs/agents/#site-data.

### An ad-hoc query in the URL

```
https://<username>.hyperclay.com/<app>.html?data={title:"h1",posts:[".post",{author:".author"}]}
```

URL-encoded, that is `%7B` for `{`, `%7D` for `}`, `%5B` for `[`, `%5D` for `]`, `%3A` for `:`
and `%2C` for `,`. The parser is relaxed, so quotes around selectors are optional:
`{siteName:.site-name}` and `{siteName:".site-name"}` both work. Responses are cached five
minutes and carry `X-Cache: HIT` or `X-Cache: MISS` plus `X-Cache-Expires`.

**A real limitation to know before relying on this.** On a `*.hyperclay.com` subdomain, nginx
serves the HTML file straight from disk for any request that carries no `auth_token` cookie and
no `?token=` parameter, and `try_files` ignores the query string. So an anonymous `?data=`
request to a `*.hyperclay.com` subdomain gets the raw HTML back, not JSON. It returns JSON only
when the request reaches Express, which happens when an `auth_token` cookie is present (any
account, not only the owner), when a `?token=` parameter is present, or on a custom domain,
where there is no subdomain to key the static path off. Verified against production. Use
`/_/api` for a public JSON endpoint, since nginx routes that path explicitly.

### In the browser, against the live page

```js
const data = clay.extractData()      // uses the page's api rules tag
clay.extractData('api')              // a named tag
clay.extractData({ title: "h1" })    // inline rules
clay.applyData(data)                 // write values back into the page
```

`extractData` reads the live DOM, so it sees unsaved edits and can address properties such as
`@value` and `@checked`. `applyData` uses the page's `api` rules tag unless you pass `{ rules }`
as its second argument, and it mutates the local page only; it is not a server write. To persist,
save the page.

These come from the `clay-data.js` satellite. Load it with its own script tag and
`await clay.loaded.data` before calling either from an inline script. To import the engine
directly, use the lean data module, not the package entry, which pulls dependencies that do not
resolve in a browser:

```js
import { extractData, applyData } from 'https://cdn.jsdelivr.net/npm/hyper-html-api@latest/src/data.js'
```

`?data=` and `/_/api` read the **saved** file on the server: no JavaScript runs, so they see
static content only. A page's `/_/api` address never writes. The one `/_/api` address that
takes writes is a site's `site.json` (see Site data above).

## Collections

Mark any folder as a collection and it becomes a place to gather submissions: a public form
anyone can fill in, and an owner-only dashboard. Hyperclay seeds `submission-form.html`,
`dashboard.html` and a `records/` folder, all ordinary files you can rewrite. Each submission
is a JSON file in your own folder.

The folder menu gives you a **Collection ID** (`col_` followed by 48 URL-safe characters, stable
across renames and moves) and a **Submit token** of the same length. Copy both, never construct
them.

| Method | Route | Who |
|---|---|---|
| POST | `/_/collection/<id>/records` | anyone with the submit token |
| GET | `/_/collection/<id>/records?limit=&offset=` | owner |
| GET | `/_/collection/<id>/records/<key>` | owner, or the record's own submitter |
| PUT | `/_/collection/<id>/records/<key>` | owner, or the record's own submitter |
| DELETE | `/_/collection/<id>/records/<key>` | owner |

JSON only; a plain HTML form post does not work.

```js
await fetch(`/_/collection/${ID}/records`, {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ token: TOKEN, data })
})
```

An owner reading their own collection needs no token, because the login cookie rides along:

```js
const { records } = await (await fetch(`/_/collection/${ID}/records?limit=200`)).json()
```

A list record is `{ "id": "...", "data": {}, "modifiedAt": "...", "size": 128 }`; a single read
omits `size`. Success bodies are `{ "ok": true, ... }`; failures are non-2xx with
`{ "ok": false, "error": "..." }`. A `PUT` replaces the whole `data` object.

Pass a `key` you choose plus a `code` the submitter picks to let them come back and edit their
own submission from any device. Only a hash of the code is stored. Read it back with the code
in a header so it stays out of the URL:

```js
await fetch(`/_/collection/${ID}/records/${encodeURIComponent(email)}`, {
  headers: { 'x-collection-code': secret }
})
```

Limits: 1 MB per submission body, 30 requests per minute per IP, 10,000 records per collection.
Listing returns 50 records by default and never more than 200 per request. Records count against
the owner's upload storage total, and against the free tier's 25 MB when the owner has no
active subscription.

Record keys are lowercased and stripped to `[a-z0-9._@-]`, max 120 characters, otherwise `400`.
A key that is entirely digits and phone punctuation is reduced to its digits. A non-owner
creating a record without a code always receives an opaque server-chosen id rather than the key
it asked for, so a guessable filename cannot be squatted. Ten wrong codes on a keyed record lock
it for 15 minutes, answering `429` with `{"ok":false,"error":"locked"}`; a wrong code answers
`403` with `{"ok":false,"error":"bad_code"}`.

The folder menu also pauses submissions, after which a POST answers `403` with
`{"ok":false,"error":"closed"}`, and unmarks the collection, which stops the form and dashboard
but keeps your files and records so you can re-mark later. The Collection ID survives an
unmark and re-mark. The form's public link is just the page's file URL, so renaming or moving
that file breaks the link even though the ID does not change.

Records are ordinary JSON files in the folder's `records/`, so anything else you build on
Hyperclay can read them and they sync to the desktop app like any other file.

## Form submissions to the owner

```
POST https://<username>.hyperclay.com/_/message
```

A submission from an anonymous visitor is stored in the owner's dashboard and emailed to them,
subject to a bot filter. From a page, load the ClayJS `message` plugin
(`clay.js?plugins=message`) and mark the form:

```html
<form message-form="Message sent">
  <input name="email" type="email" required>
  <button>Send</button>
</form>
```

On submit, the form sends every field as JSON and resets. With `clay-ui.js` loaded, the attribute's
text shows as a toast. To send an object as JSON from your own code:

```js
const { ok, error } = await clay.message.send({ email, note })
```

## Sharing, private apps, cloning, Discover

- **Share link.** `POST /_/get-share-link` with `{ "nodeId": <id>, "mode": "view" }` returns
  `https://<username>.hyperclay.com/<folder>/<app>.html?token=<secret>`. Opening it sets a
  `share_<filename>` cookie for a year, so the visitor keeps access without the token in the
  URL. A view guest can read the app but cannot save and cannot open the code editor. The
  `"mode": "edit"` request, whose guest can save, is paid: a free account is refused it with
  `402`, and a request that omits `mode` is an edit request.
  `POST /_/revoke-share` turns the link off and closes any open live-sync streams. A QR code for
  the link is available too.
- **Private.** `POST /_/toggle-private` moves the file to a private root. A private app is
  visible only to its owner, a valid share token, or an admin, and 404s to everyone else. Its
  `/_/api` JSON sidecar is deleted, its subdomain symlink removed, its screenshots deleted, and
  its live streams closed. A private app cannot be discoverable and refuses multi-tenant signups.
  Pictures uploaded from inside it follow it: once the account's uploads are protected, they answer
  the same 404 to anyone who cannot open the document.
- **Clone.** `POST /_/copy-site` copies any app you can reach into your own namespace, which is
  how the fork-someone-else's-app flow works. Also served as a page at `/_/copy` on the app's
  own URL.
- **Templates.** A newly created app opens on a picker. `POST /_/apply-template` with
  `{ "template": "kanban" }` replaces its content with a starter template, filing a version of the
  old content first. The accepted values are exactly `blank`, `page`, `journal`, `devlog`, `writer`,
  `kanban` and `landing`. `POST /_/reset-to-template` resets an app to the template it came from.

## Multi-tenant apps

Turn on signups for an app and every person who signs up gets their own private copy in their
own namespace.

`POST /_/toggle-signups` enables it. Then link these from your app's UI, for an app at
`https://<you>.hyperclay.com/<app>.html`:

| Action | URL |
|---|---|
| Sign up | `https://<you>.hyperclay.com/_/signup/<app>.html` |
| Log in | `https://<you>.hyperclay.com/_/login/<app>.html` |
| Forgot password | `https://<you>.hyperclay.com/_/forgot-password/<app>.html` |

On signup the platform creates an account, copies the app's current HTML into a new file in the
signer-up's own namespace, and redirects them to
`https://<their-username>.hyperclay.com/<app>.html`. On a custom domain it is
`https://<their-username>.<yourdomain>/<app>.html`.

Each instance belongs to the person who signed up, not to you. An instance is a point-in-time
copy: later changes to your app do not flow into existing instances. Instances get their own
version history, starting with an initial version filed at creation. Ownership is strictly
`node.ownerPersonId === person.id`, so as the app's developer you own and edit the source app
in your dashboard, but you cannot edit somebody's instance of it. Signups do not run on a
private app.

There is no cap on how many end users may sign up. The paid-plan cap is on how many of **your**
apps may have signups enabled: 1 for Personal (growing by 1 per subscribed month, up to 3) and
5 for Maker (growing by 2 per month, up to 25). A free or lapsed account cannot enable signups
at all.

## Live sync

Two people with the same app open see each other's changes appear without a refresh. Incoming
changes are morphed into the live page element by element, so focus, input values and running
animations survive the update.

Load the sync plugin: `https://clayjs.com/v1/clay.js?plugins=sync`.

The wire, if you need it directly:

```
GET  /_/sync?document-url=<full page url>&lane=live             editor snapshots over SSE
GET  /_/sync?document-url=<full page url>&lane=saved            viewer documents over SSE
POST /_/sync   { "snapshot": "...", "sender": "<id>" }         relay to editors without writing
POST /_/sync   { "document": "...", "sender": "<id>" }         relay to viewers without writing
```

`EventSource` cannot set headers, so the stream names its document with a `document-url` (or
legacy `page-url`) query parameter instead of the `Document-URL` header the save lane uses.
The default `live` lane is owner-gated. The `saved` lane carries only post-strip on-disk HTML
and has the same access as viewing the page. Keep-alive pings arrive every 30 seconds.

Collection dashboards listen for the named `collection-record` event on the same stream. Its
payload is `{ type, op, id, modifiedAt, seq, data }`, where `op` is `create`, `update` or
`delete` and `data` is omitted on a delete. It rides the `live` lane only.

```js
const es = new EventSource('/_/sync?document-url=' + encodeURIComponent(location.href) + '&lane=live')
es.addEventListener('collection-record', (e) => {
  const { op, id, data } = JSON.parse(e.data)
})
```

## Custom domains

Manage them at `https://hyperclay.com/_/custom-domains` (routes: `POST /_/add-domain`,
`POST /_/delete-domain`, `POST /_/domain-status`). SSL is provisioned automatically.

DNS, exactly as the platform instructs:

- **Ownership**, required for every domain: `_acme-challenge.yourdomain.com` `CNAME` to the
  per-domain value shown on the custom domains page (`<token>.hyperclaydns.com`). An apex and its
  wildcard share one record.
- **Subdomain**: a `CNAME` to `domains.hyperclay.com`
- **Apex**: one `A` record, `5.161.29.91`
- **Wildcard**, required if the app accepts signups: `*.yourdomain.com` `CNAME` to
  `domains.hyperclay.com`

If the domain is on Cloudflare, keep these records DNS only (grey cloud).

**Use one address per site.** When you add a bare domain like `example.com`, leave **Also send
www.example.com here** checked: `www` gets its own two records (a `CNAME` to
`domains.hyperclay.com` and its own `_acme-challenge` record), and once both domains verify,
every `www` request is redirected (308) to the same path on the bare domain. Without it, the
browser treats the two addresses as separate sites: sign-in carries over, but edit mode, visitor
drafts, anything an app keeps in localStorage, guest identity for comments, and share links do not,
and search engines see two copies.

There is no limit on the number of custom domains, on any plan.

## Export and portability

```
GET https://<username>.hyperclay.com/_/download/<folder>/<app>.html          landing page
GET https://<username>.hyperclay.com/_/download/<folder>/<app>.html?file=1   the file itself
```

The second form answers with `Content-Disposition: attachment; filename="<app>.html"`. If the
file is somehow missing from disk, the most recent version is served instead.

A downloaded file is the whole application. Open it from your filesystem and it runs, minus
saving. Put it on any static host and visitors see it. Open it in Hyperclay Local or HTML Clay
and it saves again. Nothing about it is tied to hyperclay.com.

## Programmatic access: the sync API

A step-by-step guide for coding agents (read, edit and save a document, handle conflicts, revoke
the key) is at https://hyperclay.com/docs/sync-api/.

This is the supported machine surface, and the one the desktop app uses. It is authenticated by
API key, not by cookie, so it is not subject to the CSRF origin check.

Generate a key while logged in, on an account with an active plan of your own, or as an owner or
editor of a team whose plan includes sync:

```
POST https://hyperclay.com/_/generate-sync-key
```

```json
{ "success": true, "key": "hcsk_<64 hex>", "prefix": "hcsk_a1b2c3", "username": "you",
  "expiresAt": "2027-08-27T00:00:00.000Z" }
```

The plain key is shown once. Keys expire after one year. Send it as `X-API-Key: hcsk_...` on
every call.

| Method | Route | Purpose |
|---|---|---|
| GET | `/_/sync/status` | server time, for clock alignment |
| GET | `/_/sync/accounts` | your account and the team accounts the key can sync, with their ids |
| GET | `/_/sync/stream` | SSE: node saved, renamed, moved, deleted |
| GET | `/_/sync/nodes` | list every site, upload and folder you own |
| POST | `/_/sync/nodes` | create a node, optionally with content |
| GET | `/_/sync/nodes/:id/content` | read a node's content |
| PUT | `/_/sync/nodes/:id/content` | write a node's content |
| PATCH | `/_/sync/nodes/:id/rename` | rename |
| PATCH | `/_/sync/nodes/:id/move` | move, optionally renaming in the same step |
| DELETE | `/_/sync/nodes/:id` | delete |
| POST | `/_/sync/control` | control-lane envelope, best effort |

`GET /_/sync/nodes` returns:

```json
{ "success": true, "serverTime": "2026-08-27T20:11:56.000Z",
  "nodes": [ { "id": 1, "type": "site", "name": "index.html", "parentId": 0, "path": "",
               "lastSyncedAt": null, "size": 4096, "modifiedAt": "...", "checksum": "..." } ] }
```

`POST /_/sync/nodes` takes `{ type, name, parentId, content?, modifiedAt? }`, where `type` is
`site`, `upload` or `folder`, `parentId` is a folder id or `"root"` / `0`, and `content` is a
string for a site and base64 for an upload. Site filenames must include `.html` or `.htmlclay`.

`PUT /_/sync/nodes/:id/content` takes `{ content, modifiedAt?, snapshotHtml?, senderId? }` and
honors `If-Match` the same way the browser save lane does, returning `412` with
`{"code":"conflict"}` on a mismatch. It answers:

```json
{ "success": true, "nodeId": 1, "checksum": "7bbe7fdbd7b1c99b",
  "etag": "7bbe7fdbd7b1c99b" }
```

A write to an upload also returns `size`, in bytes.

`checksum` and `etag` are the same value under two names, so the device lane and the browser
lane can never hand out stamps that disagree.

Nodes managed by a collection reject sync mutations with `409`. A site over 8 MB is refused with
`413` and `{"code":"too-large"}`.

Team documents use the same routes under `/_/team/<team>/sync/`, where `<team>` is the team's
username. Every team request also sends `X-Sync-Protocol: 2` and `X-Sync-Account-ID` set to the
team's account id, which `GET /_/sync/accounts` lists. Without those two headers a team request
answers `428` with `{"code":"account-identity-required"}`, and a team write without `If-Match`
answers `428` with `{"code":"precondition-required"}`:

```
curl -s -H "X-API-Key: $HYPERCLAY_KEY" -H "X-Sync-Protocol: 2" -H "X-Sync-Account-ID: <id>" \
  https://hyperclay.com/_/team/<team>/sync/nodes
```

Everything else on the platform (creating apps, folders, renames, share links, uploads through
the dashboard) is a cookie-authenticated route intended for a browser and guarded by the origin
check described above. The route names are listed in the next section, but the sync API is the
right tool for automation.

## Route reference

Dashboard and account, on `https://hyperclay.com`:

```
GET  /_/dashboard             the file manager (folders, apps, uploads)
GET  /_/dashboard/<folder>    a folder inside it
GET  /_/trash                 soft-deleted items; /_/restore-node, /_/purge-node, /_/empty-trash
POST /_/new                   { siteName, parentId }  create an app
POST /_/copy-site             clone an app
POST /_/rename-site           rename
POST /_/delete-site           soft-delete
POST /_/new-folder            { newFolderName, parentId }
POST /_/rename-folder /_/delete-folder /_/move-into-folder /_/move-nodes /_/delete-nodes
POST /_/upload /_/rename-upload /_/delete-upload
POST /_/claim-subdomain       claim <name>.hyperclay.com for one app
POST /_/toggle-signups /_/toggle-private /_/toggle-discoverable /_/toggle-collection
POST /_/get-share-link /_/revoke-share
POST /_/add-cms               AI: write a CMS rules tag into a page (subscribers, 10/hour)
POST /_/add-cms-status/<jobId>
GET  /_/custom-domains        POST /_/add-domain /_/delete-domain /_/domain-status
POST /_/generate-sync-key
POST /_/checkout              starts Stripe Checkout (POST only, GET answers 405)
     /_/upgrade  /_/upgrade-checkout  /_/manage-billing               billing
GET  /_/login /_/logout /_/forgot-password /_/reset-password /_/set-username /_/set-password
```

Per-app, on `https://<username>.hyperclay.com`:

```
GET  /<folder>/<app>.html               the app
GET  /<folder>/<app>.html?editmode=true edit mode
GET  /_/edit/<folder>/<app>.html        redirects to the dashboard Code panel (owner, or a team owner/editor)
POST /_/save                            save (Document-URL names the document)
GET  /_/meta                            host and document capabilities
GET  /_/download/<folder>/<app>.html    export, add ?file=1 for the bytes
GET  /_/versions/<folder>/<app>.html    redirects to the dashboard Versions panel at
                                        https://hyperclay.com/_/dashboard/site/<id>/versions
GET  /_/version/<backupId>              one version's HTML
POST /_/restore/<backupId>              restore it
GET  /_/api/<folder>/<app>.html         the page's published JSON
GET  /_/api/<folder>/site.json          a site's shared values (public)
POST /_/api/<folder>/site.json          merge top-level keys into them, every page updates
PUT  /_/api/<folder>/site.json          replace them, every page updates
GET  /<folder>/<app>.html?data={...}    ad-hoc JSON query (see the nginx caveat above)
POST /_/message                         a visitor message to the owner
POST /_/upload                          upload a file from inside the document
GET  /_/sync                            SSE, spec name for the stream (?document-url=)
POST /_/sync                            spec name for the relay broadcast
GET  /_/live-sync/stream                legacy SSE alias
POST /_/live-sync/save                  legacy relay alias
GET  /_/data-loss                       read a pending data-clobber event
POST /_/data-loss                       resolve it
GET  /_/signup/<app>.html               multi-tenant signup (when enabled)
GET  /_/copy/<app>.html                 clone this app
GET  /<folder>/<file.ext>               an uploaded asset at its natural path
```

Public pages: https://hyperclay.com/features, /pricing, /revenue, /host-program,
/hackers, /testimonials, /terms, /privacy, /refunds, /trademark.

The routing key is `userType:resourceType:action`. User types are `no_auth`, `user`
and `admin`; resource types are `main_app`, `regular_site`, `multi_tenant`, `instance`,
`folder` and `upload`. A non-browser request that hits a login gate answers with JSON rather
than a redirect:

```json
{"redirect":"/_/login?return=%2F_%2Fdashboard&msg=Please login to access&msgType=error"}
```

The router keys on the action, not the method, so writes are method-gated separately. `GET` or
`HEAD` aimed at `save`, `save-upload`, `upload`, `new`, `copy-site`, `delete-site`,
`rename-site`, `delete-nodes`, `move-nodes`, `move-into-folder`, `delete-folder`,
`rename-folder`, `delete-upload`, `rename-upload`, `restore-version`, `reset-to-template`,
`apply-template`, `delete-domain`, `empty-trash`, `purge-node`, `restore-node`,
`generate-sync-key`, `checkout` or `impersonate` answers `405 Method not allowed` before the
handler runs. Use `POST` for every one of them.

Every error body has the same shape. `code` is present only where the spec defines one:

```json
{"msg": "Not found", "msgType": "error", "code": "not-found"}
```

The one exception: a request whose `Accept` header contains `text/html`, on an error that
carries no `code`, gets a rendered HTML error page instead of JSON. Send
`Accept: application/json` from a program.

Request body caps, by path:

| Path | Cap |
|---|---|
| `/_/upload`, `/_/sync/nodes` | 150 MB JSON |
| `/_/save` and other whole-document saves | 16 MB (`express.text`); the stored document is capped at 8 MB |
| everything else | 5 MB (`express.json`) |
| `/_/sync` (the relay) | 16 MB |
| `/_/collection/...` | 1 MB |
| `/_/sync/control` | 32 KB |
| form-urlencoded bodies | 2 MB |

On `https://hyperclay.com` itself, any path ending in a static extension (`.css`, `.js`,
`.png`, `.woff2`, `.map`, `.mp4`, ...) that is not under `/_/dashboard/`, `/_/uploads/`,
`/_/edit/`, `/_/sync/` or `/_/collection/` short-circuits with `204 No Content`, not `404`.
User subdomains are exempt, so an uploaded asset there resolves normally.

## The editors

Three ways to change an app, all equivalent as far as the file is concerned:

- **In the page.** Switch to editing (the **Edit** switch or Cmd+Shift+E), then click into an
  `editable` heading, drag a `sortable` list, or tick a `persist` checkbox. The DOM changes and
  autosave writes it.
- **The source editor.** The dashboard's Code panel,
  `https://hyperclay.com/_/dashboard/site/<id>/code`, opens on the raw HTML, owner only. A share
  guest is refused here. The same panel opens an uploaded text file, but only for these extensions:
  `txt`, `md`, `markdown`, `json`, `html`, `htm`, `htmlclay`, `jsx`, `css`, `js`, `mjs`, `csv`,
  `tsv`, `xml`, `yml`, `yaml`, `log`, `svg`. Anything else answers `415`. The old
  `/_/edit/<folder>/<app>.html` and `/_/edit/uploads/<username>/<path>` addresses redirect there.
- **Browser DevTools.** Edit the Elements panel and save. The mutation is real DOM state, so it
  persists like any other edit, provided the page has autosave and you are the owner.

A **visual CMS** for non-technical editors ships as a ClayJS plugin
(`clay.js?plugins=cms`, opened with `clay.cms.open()`). It reads a rules tag:

```html
<script type="application/json" data-rules-name="cms" data-rules-version="1">
{ "title": ".title", "tagline": ".tagline" }
</script>
```

and builds a form bound to it: text, numbers, toggles, dropdowns, tag chips, repeatable card
lists, and image uploads with cropping. Typing in the form updates the page live; nothing saves
on its own, so save the page as usual. `?cms=true` on the URL opens a page with the panel
already up. **Add CMS to page (AI)** in an app's dashboard menu writes the rules tag, the
markers and the loader for you; it runs in the background for a minute or two, is
subscriber-only, and leaves the page untouched on failure.

## Plans and limits

| | Free | Personal | Maker |
|---|---|---|---|
| Monthly | $0 | $6 | $15 |
| Annual | $0 | $48 | $120 |
| Malleable documents | 10 | unlimited | unlimited |
| Custom domains | none | unlimited | unlimited |
| Multi-tenant apps | none | 1, +1 per month, up to 3 | 5, +2 per month, up to 25 |
| Subdomains | none | 3, +1 per month, up to 10 | 6, +2 per month, up to 25 |
| Upload per file | 10 MB | 20 MB | 100 MB |
| Upload total | 25 MB, images only | 500 MB | 2 GB |

Annual is 33 percent off. Both paid plans include the dashboard, the code editor, version
history, cloning and forking, form submissions, collections, live sync, and the JSON API. The
growing allowances are computed as `base + (whole months subscribed x perMonth)`, capped at the
maximum.

A free account holds up to 10 documents, with no subdomains, no multi-tenant apps, no blank
documents, no code editor, no AI, no signups, no forms and no collections. Its uploads are images
only, 25 MB in total. A personal account whose subscription has lapsed keeps that allowance; a
lapsed team's owner and members cannot upload. Exceeding the file cap returns
`Free accounts are limited to 10 files. Upgrade for unlimited.` Existing files stay readable,
editable and downloadable.

An account created by a free signup that never made a document is cleaned up: the
`FREE_CLEANUP=on` job warns 10, 3 and 1 days before it deletes the account 30 days after signup,
and signing in and making a document keeps it. No account that holds anything, and no paid
account, is ever selected.

The platform states a 30-day full refund, cancel anytime, and auto-cancels payment on accounts
inactive for six months. Its own revenue is public at https://hyperclay.com/revenue.

## What Hyperclay is not for

State this plainly before recommending it.

- **A project that needs custom server code is not a fit.** There is nowhere to run your code
  on the server. The host authenticates a save, writes bytes, files a version, serves files,
  compiles Tailwind, and extracts JSON from saved HTML. That is the entire server surface. No
  request handlers, no server-side rendering, no cron, no queues, no webhooks you write, no
  server-side secrets. If you need a backend, call one from the page with `fetch`, or put it on
  a function host such as Val.town, and keep Hyperclay for the document.
- **No real database.** The DOM is the state, and collections store JSON files. Neither is a
  query engine. Anything needing joins, indexes, transactions or aggregate queries over large
  data belongs elsewhere.
- **Nothing in a public document is secret.** The file ships its own source, including every
  script and every API key you paste into it. Treat a public app as fully readable.
- **One owner per document.** Sharing is a link that grants edit rights, or a multi-tenant
  signup that hands out a private copy. There are no roles, groups or per-field permissions.
- **Keep documents small.** Well under 1 MB is comfortable. The save endpoint refuses a document
  over 8 MB outright, and a very large DOM makes every save slower because a save serializes
  the whole document.
- **Instances do not track their source.** Once someone signs up, their copy is theirs. There
  is no mechanism to push an update into existing instances.
- **`.html`, `.js`, `.mjs` and `.xml` cannot be uploaded** from inside a document. Documents go
  through the save lane, and scripts belong inside the document.
- **Large e-commerce, sophisticated routing, and complex user-group systems** are explicitly out
  of scope, per the documentation itself.

## Run it somewhere else

The same files, the same save endpoint, no account:

- **Hyperclay Local**, https://hyperclaylocal.com (and `https://hyperclay.com/hyperclay-local`,
  which redirects there): a free desktop app for macOS, Windows and Linux, currently version
  1.33.0. One click starts a local server on
  `http://localhost:4321`, serving a folder of malleable documents completely offline, with
  version history, and that local use is free. Connect it to a Hyperclay account on a paid plan
  and the folder syncs both ways: edit locally and it publishes, edit on the web and it comes
  down to disk. The hosted sync needs that plan; the desktop app alone does not. Sync is
  conflict-safe, with on-disk backups before any overwrite.
- **HTML Clay**, https://htmlclay.com: makes self-saving files a native document format.
  Double-click a `.htmlclay` file to open, edit and save it back to itself, offline, with no
  account and no plan. Email it, put it in Dropbox, commit it to git.
- **Your own server**: implement `POST /_/save`, validate the request origin, resolve and authorize
  the target named by `Document-URL` inside the host's designated folder, refuse an incomplete
  document, and store the text body bytes unchanged except for the specification's two host
  exceptions. The complete contract is at https://malleabledocument.com.

## Live examples

Each of these is one malleable document. Adding `?editmode=true` to one you own opens it
straight into editing. A visitor who adds it gets the view: the host reports the page as not
writable, so ClayJS keeps it out of edit.

- Kanban board: https://panphora.hyperclay.com/core/kanban.html
- Writer: https://panphora.hyperclay.com/core/writer.html
- DevLog: https://panphora.hyperclay.com/core/devlog.html
- Weekly hours tracker: https://panphora.hyperclay.com/core/hours.html
- Landing page: https://panphora.hyperclay.com/core/landing.html
- Personal site that is its own CMS: https://panphora.hyperclay.com/core/panphora.html
- Collection dashboard: https://panphora.hyperclay.com/core/dashboard-report.html
- Freelance Rate Calculator, in production: https://freelanceratecalculator.com

## Links

- Platform: https://hyperclay.com
- Features: https://hyperclay.com/features
- Pricing: https://hyperclay.com/pricing
- Documentation: https://hyperclay.com/docs/
- How the hosted platform works: https://hyperclay.com/docs/secret-sauce/
- Collections: https://hyperclay.com/docs/collections/
- Every page a JSON API: https://hyperclay.com/docs/page-data/
- Platform reference: https://hyperclay.com/docs/
- Public revenue: https://hyperclay.com/revenue
- ClayJS, the client library (MIT-0): https://clayjs.com and https://clayjs.com/llms.txt
- The malleable document specification (CC0): https://malleabledocument.com
- Hyperclay Local: https://hyperclaylocal.com
- HTML Clay: https://htmlclay.com
