- Hyperclay
- Docs
- Data and APIs
- Platform reference
Platform reference
The platform contract for agents: accounts, upload limits, routes, saving, sharing and local hosts.
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#
- 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 onhttps://hyperclay.com/_/dashboard. - Create an app called
notes. It lives athttps://<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. - Open the dashboard’s Code panel at
https://hyperclay.com/_/dashboard/site/<id>/codeand paste a document whose<html>carriesautosaveand whose<head>carries<script src="https://clayjs.com/v1/clay.js"></script>. The oldhttps://<username>.hyperclay.com/_/edit/notes.htmlredirects there. The Code panel is a paid feature; a free account edits a copy of a template in place instead. - 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 aneditableelement. Ctrl+S saves, or autosave does it for you. - Open the same URL in a private window. You get the plain page with no edit controls.
https://hyperclay.com/_/dashboard/site/<id>/versionsis the Versions panel, and it lists every save. The oldhttps://<username>.hyperclay.com/_/versions/notes.htmlredirects there.https://<username>.hyperclay.com/_/download/notes.html?file=1gives 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:
- The browser loads the document.
- 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. - Edits mutate the live DOM. The DOM is the state, so there is nothing else to persist.
- On save, the client clones the document, strips editor-only regions from the clone, serializes it, and POSTs that text to the host.
- 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:
https://hyperclay.com/free-signuptakes 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.- 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). - The account becomes
account_type: app_useron thefreetier and lands onhttps://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:
https://hyperclay.com/signup(the plan-picker page) orhttps://hyperclay.com/pricing(the marketing page) starts Stripe Checkout for a tier (personalormaker) and a plan (monthlyorannual). They are two different pages into the same checkout.- Checkout succeeds and returns to
https://hyperclay.com/_/set-password?session_id=<checkout session id>. - 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).
- The account becomes
account_type: devand lands onhttps://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.comfor one app. The app then sits at the root of that hostname, not at/<app>.htmlunder 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.htmlappended. 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, soapi.htmland a folder namedsettingsare 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):
<!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:
editableon an element for rich text,editmode:contenteditablefor owner-only plain text.persiston a form control to write its value into the saved HTML.viewmode:disabled/viewmode:readonlyto make a control live for the owner and inert for visitors.sortable="name"for drag-to-reorder lists (thesortableplugin), which firesclay: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-saveon 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:
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
415and{"code":"invalid-document"}rather than guessed at. The check is onContent-Type. - Use a
text/*media type or send noContent-Typeat all. The server parses this route withexpress.text({ type: 'text/*', limit: '16mb' }), so bothtext/plainandtext/htmlare accepted. A JSON media type is refused deliberately. - The body must be a complete document with a top-level
<html>element, or422with{"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
413with{"code":"too-large"}. Document-URLnames the target document. The path carries no filename, so this header is how the server knows which file is being saved.Page-URLis the older spelling and is still read;Document-URLwins when both are present.Save-Trigger: userorautorecords whether a human gesture is behind the save. The olderX-Hyperclay-User-Drivenis read whenSave-Triggeris 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 returns412with{"code":"conflict"}and leaves the document and its version history byte-identical.If-Match: *asks only that the document exist. An emptyIf-Matchvalue 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 asX-Clay-Blockeditor-Format. A save that declares less than the document’s floor, or less than its own content needs, answers409with{"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:
{ "msg": "Saved", "etag": "7bbe7fdbd7b1c99b" }
An unchanged document is not rewritten and still answers with msg and the current stamp:
{ "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:
- Reformats the HTML only if the root
<html>element carries the literal attributeformathtml="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. - Reads the current file from disk.
- Answers
412if anIf-Matchwas sent and does not match the bytes on disk. - Answers
409if 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. - Returns early with
msg: "Saved"and the current etag if the bytes are unchanged. - Files a version (see below). On the very first save it files the pre-existing content first.
- Writes the file. This is the commit point.
- Best-effort afterwards, none of which can fail the save: updates the content hash,
broadcasts to live-sync subscribers, scans the HTML, rewrites the
/_/apiJSON 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
{
"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:
{ "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:
?editmode=trueor?editmode=falsein the URLwindow.clayEditMode, set beforeclay.jsloads- an authored
viewonlyon<html>, which rules edit out - a save token placed on the root element by the host
- 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_userwith 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.
{ "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:
402with{"code":"payment-required"}when the caller has no upload allowance.413with{"code":"too-large"}past the per-file cap.400past the storage total.415with{"code":"unsupported-type"}when a document uploads.html,.htm,.xhtml,.htmlclay,.js,.mjsor.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):
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:
<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:
<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:
{"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:
<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:
{"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#
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:
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.
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:
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:
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:
<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:
const { ok, error } = await clay.message.send({ email, note })
Sharing, private apps, cloning, Discover#
- Share link.
POST /_/get-share-linkwith{ "nodeId": <id>, "mode": "view" }returnshttps://<username>.hyperclay.com/<folder>/<app>.html?token=<secret>. Opening it sets ashare_<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 with402, and a request that omitsmodeis an edit request.POST /_/revoke-shareturns the link off and closes any open live-sync streams. A QR code for the link is available too. - Private.
POST /_/toggle-privatemoves 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/_/apiJSON 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-sitecopies 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/_/copyon the app’s own URL. - Templates. A newly created app opens on a picker.
POST /_/apply-templatewith{ "template": "kanban" }replaces its content with a starter template, filing a version of the old content first. The accepted values are exactlyblank,page,journal,devlog,writer,kanbanandlanding.POST /_/reset-to-templateresets 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.
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.comCNAMEto the per-domain value shown on the custom domains page (<token>.hyperclaydns.com). An apex and its wildcard share one record. - Subdomain: a
CNAMEtodomains.hyperclay.com - Apex: one
Arecord,5.161.29.91 - Wildcard, required if the app accepts signups:
*.yourdomain.comCNAMEtodomains.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
{ "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:
{ "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:
{ "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:
{"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:
{"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
editableheading, drag asortablelist, or tick apersistcheckbox. 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 answers415. The old/_/edit/<folder>/<app>.htmland/_/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:
<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,.mjsand.xmlcannot 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 onhttp://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
.htmlclayfile 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 byDocument-URLinside 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