# Hyperclay docs, every page
> The hosted platform for malleable HTML documents: your workspace, sharing, teams, custom domains and the APIs around them.
# Hyperclay docs
> Keep, edit, share, and publish HTML files that save themselves in your workspace on Hyperclay.
Source: https://hyperclay.com/docs/
Hyperclay is the hosted platform at hyperclay.com for keeping, editing, sharing, and publishing HTML files in a workspace. With the ClayJS script, a file edits itself in the browser and saves changes back into itself. Hyperclay gives you teams, share links, subdomains and custom domains, version history, and hosted AI.
## What do you want to do?
- **Share a malleable document with your team**: Keep documents in a workspace, send share links, and publish on the web with Hyperclay. Start with the [Quick start](https://hyperclay.com/docs/guide/quick-start/).
- **Use a document on your own computer**: Open `.htmlclay` files on your computer that save back to disk with [HTML Clay](https://htmlclay.com/docs/), a free, open-source desktop app.
- **Sync a folder between your computer and Hyperclay**: Serve a folder of malleable documents on your computer and sync it both ways with your workspace using [Hyperclay Local](https://hyperclaylocal.com/docs/).
- **Make your own malleable document**: Build self-saving HTML files with one script tag using [ClayJS](https://clayjs.com/docs/), the free, open-source browser library.
## Why Hyperclay exists
Reusable, portable software that anyone can use and improve on their own needs a lightweight visual and data format. The HTML file fits that job because it holds the interface, code, and data in one place and gives you the full web platform.
We built a system around the HTML file so you can update a document like a web application, on the web or on your computer. Each document stays a portable file you can download or email around. Hyperclay hosts those files so you can open them in any browser, keep version history, and work with a team.
## What people do with Hyperclay
- **Keep a daily work journal**: Track client work, to-dos, finished tasks, and project plans in one document.
- **Run project dashboards**: Have an AI agent build a multi-week project dashboard and update it through the document's JSON API.
- **Collect answers and screenshot feedback**: Use a form where an AI agent asks questions, or mark up screenshots with a built-in feedback tool so the AI reads your notes from the HTML.
- **Share diagrams and tools**: Collaborate in [teams](https://hyperclay.com/docs/teams/), send [share links](https://hyperclay.com/docs/share-links/), publish on custom domains, or edit with [hosted AI](https://hyperclay.com/docs/hosted-ai/). Every file stays under your control.
## Where to go next
- [Quick start](https://hyperclay.com/docs/guide/quick-start/): Sign up, start a document from a template, edit it, and open its live address.
- [Your workspace](https://hyperclay.com/docs/guide/workspace/): Navigate your files, code editor, and version history side by side.
- [Making malleable documents](https://hyperclay.com/docs/making-malleable-documents/): Learn how ClayJS works and how to bring HTML files into Hyperclay.
- [Work on your computer](https://hyperclay.com/docs/guide/your-computer/): Sync folders with Hyperclay Local or open standalone files with HTML Clay.
---
# Quick start
> Sign up for Hyperclay, start a document from the template gallery, edit it in your workspace, and open its live address.
Source: https://hyperclay.com/docs/guide/quick-start/
You can publish an editable document on the web in a few minutes without setting up a local build environment. This guide walks through signing up, starting a document from the gallery, editing it, watching it save, and opening its public address.
## Create and publish your first document
1. **Sign up for an account.** Start at [Free signup](https://hyperclay.com/free-signup), enter your email address, and open the signup link it sends you. Choose your username and password on the welcome page. A free account holds up to 10 documents. Your username gives you an address namespace at `https://.hyperclay.com`.
2. **Choose a template.** Open the [template gallery](https://hyperclay.com/templates) and copy a template into your account. A free account starts with a template and edits it in place.
3. **Open your document.** Find the copy in your workspace and open it. With an active Personal or Maker plan, you can also use **New document** to create a blank document and edit its source in the code editor.
4. **Edit your document and watch it save.** Your document opens in view inside the workspace beside your files, the way a visitor sees it. Open the document menu and click **Return to editing** (or click **Edit** on the page, or press `⌘⇧E`), then click into the page and change some text or add a heading. (If you started an **Untitled** **Document**, it renames itself once to match the first heading you type.) While your change writes to the server, the workspace status shows **Saving…** and clears when the save finishes. Every save in the browser records a snapshot in the document's **Versions** panel.
5. **Switch between view and edit.** Open the document menu and click **View as visitor** to see the page without editing controls, as a visitor sees it, and **Return to editing** to go back. A document you create with **New document** in the workspace opens straight in edit mode.
6. **Open its live address.** Open the document menu and click **Open in its own tab** (`⌘⇧O`), or check the **Address** row in the document's **Info** dialog. Public documents are served at `https://.hyperclay.com/.html`. Open that address in a private or incognito browser window to see the live, read-only view.
> [!NOTE]
> The **Journal** template carries a **Starts private** tag and is created as a private document. Only you and people you grant access can open a private document until you open its actions menu and choose **Make public**.
## Where to go next
- Explore the workspace file tree, code editor, and version history in [Your workspace](https://hyperclay.com/docs/guide/workspace/).
- Build from a **Blank** template with [ClayJS](https://clayjs.com/docs/guide/quick-start/) or import an existing HTML file in [Make your own document](https://hyperclay.com/docs/making-malleable-documents/).
- Claim a custom `.hyperclay.com` subdomain or connect your own domain in [Addresses and subdomains](https://hyperclay.com/docs/addresses/) and [Publish on your own domain](https://hyperclay.com/docs/guide/domains/).
---
# Your workspace
> Tour the Hyperclay workspace: your sidebar, files and folders, open documents with code and versions alongside, Recent, pins, search, and Trash.
Source: https://hyperclay.com/docs/guide/workspace/
The Hyperclay dashboard is a workspace where you keep, find, and edit your malleable documents. Your file tree stays in a sidebar on the left while documents open beside your files, with their code and version history alongside.
## The sidebar
The left sidebar holds your navigation and your file tree. At the top sit **Filter files**, **Recent**, **Inbox**, **Shared with me**, **Home**, and any documents you have added under **Pinned**. From the **New** menu, you can start a document from [Templates](https://hyperclay.com/docs/templates/), create a folder, import existing pages, or upload files from your computer.
## Files and folders
Click **Home** to view your workspace in the files table, or browse your folders directly in the sidebar tree. You can nest folders up to five levels deep, rename or move items in a single step, and select up to 100 rows at once to move or delete them in bulk; see [Files and folders](https://hyperclay.com/docs/files/). When a document uploads images or other attachments, they are stored in a dedicated subfolder inside `uploads` and keep working even when you move the document; see [Uploads](https://hyperclay.com/docs/uploads/).
## Open a document beside your files
Clicking any document in the sidebar or files table opens it right in the workspace beside your files, so you can move between documents without leaving the dashboard. A document opens in view, the way a visitor sees it; to change it, open the document menu and choose **Return to editing** (or click **Edit** on the page, or press `⌘⇧E`). A document you have just created from a template opens in edit mode. Along the top of the open document, tabs for **Code**, **Versions**, **Domains**, and **Comments** let you edit the document's HTML in the [Code editor](https://hyperclay.com/docs/code-editor/) or browse and restore earlier snapshots in [Version history](https://hyperclay.com/docs/version-history/). You can also click any uploaded image, PDF, or text file to preview it in place, and open the **Code** tab on a text upload to edit and save it directly.
## Recent and pins
Click **Recent** in the sidebar to see the last 50 documents you opened, grouped by day under **Today**, **Yesterday**, and **Earlier**. To keep an important document at the top of the sidebar, open its menu and choose **Pin to sidebar** so it stays listed under **Pinned** above your folder tree. For details on both lists, see [Search, Recent and pins](https://hyperclay.com/docs/search/).
## Search
Click **Filter files** in the sidebar or press Cmd+K (Ctrl+K on Windows and Linux) to search your workspace. Typing filters the sidebar tree by file name right away, and once you type two or more characters, **Found inside documents** lists documents whose text contains your words. Clicking a content result opens the document beside your files and highlights the matched word on the page; see [Search, Recent and pins](https://hyperclay.com/docs/search/).
## Trash
Deleting a document, upload, or folder moves it to **Trash** instead of erasing it right away. Open **Account menu** and choose **Trash** to restore deleted items to their original folder within 30 days, or delete them permanently; see [Trash](https://hyperclay.com/docs/trash/).
---
# Making malleable documents
> Hyperclay runs malleable documents built with ClayJS. What ClayJS does, where to learn it, and how to bring your own file into Hyperclay.
Source: https://hyperclay.com/docs/making-malleable-documents/
You make malleable documents with [ClayJS](https://clayjs.com/docs/), and the ClayJS docs are the place to learn it. This site covers the Hyperclay hosted platform, not how to build documents from scratch. When you want to build your own malleable document, go to the ClayJS docs.
## What ClayJS does
ClayJS is the free, open-source browser library that turns one HTML file into a malleable document. Every malleable document is built with it.
- **One script tag**: Add a single script tag to an HTML page with no build step.
- **Edits in place and saves to its host**: Make elements editable, persist form controls and DOM state, strip temporary editing controls on save, and write the updated HTML back to its host.
- **Live sync**: Merge changes in real time across open browser tabs and people.
- **Plugins**: Load plugins such as the schema-driven CMS, rich-text editing with `richclay`, sortable lists, undo, uploads, and AI editing.
- **Works anywhere**: Run the same file on Hyperclay, [HTML Clay](https://htmlclay.com/docs/), [Hyperclay Local](https://hyperclaylocal.com/docs/), or your own server.
## Learn ClayJS
- [ClayJS docs](https://clayjs.com/docs/): Read the complete guide and API reference for building with ClayJS.
- [ClayJS quick start](https://clayjs.com/docs/guide/quick-start/): Turn an HTML file into a self-saving document in a few minutes.
- [A document explained line by line](https://clayjs.com/docs/guide/walkthrough/): See a complete ClayJS document explained line by line.
## Import an HTML file
If you already wrote a malleable document on your computer, or if you have static `.html`, `.htm`, or `.htmlclay` pages (or a `.zip` archive of pages such as a Notion or Google Docs export), you can import them into your workspace as documents:
1. Open the folder in your workspace where you want the document to live.
2. Click **New** and choose **Import files…**.
3. In the **Import files** dialog, click **Choose files…** and select one or more `.html`, `.htm`, `.htmlclay`, or `.zip` files.
Each imported HTML page becomes a document in the current folder. File names are lowercased and normalized to end in `.html` or `.htmlclay`, with `-2`, `-3`, and so on added if the name is already taken in that folder. Each page can be up to 5 MB. Any non-HTML files inside a `.zip` archive are added to your [uploads](https://hyperclay.com/docs/uploads/). See [Import and export](https://hyperclay.com/docs/import-export/) for full details.
> [!NOTE]
> At the bottom of the **Start a new document** gallery, the **Have a file already?** strip (**Choose a file**) opens the **Upload files** dialog, which stores the file as a static [upload](https://hyperclay.com/docs/uploads/) rather than importing it as a document. Use **New** and then **Import files…** when you want an HTML file to become an editable document.
## Use Make malleable on a static page
If you imported a static HTML page that does not include ClayJS yet, you can add ClayJS to it from its actions menu:
1. Open the `…` actions menu on the document row in your file list, or open the document's `…` menu in the workspace editor.
2. Click **Make malleable**.
3. In the **Make malleable** dialog, click **Make malleable** to confirm.
Hyperclay saves a backup of your current file first, then splices two script tags right before the closing `
` tag. Pages that use `` without a `` must be converted to a standard HTML page in the [code editor](https://hyperclay.com/docs/code-editor/) first.
- The page must not already load ClayJS or load multiple copies of the library.
- The page cannot be managed by a [collection](https://hyperclay.com/docs/collections/).
---
# Versions and recovery
> How Hyperclay protects your work with version history, a 30-day Trash, and full workspace zip exports.
Source: https://hyperclay.com/docs/guide/versions/
Hyperclay gives you three ways to recover from mistakes and keep copies of your work: version history on every document, a 30-day Trash for deleted files and folders, and zip exports you can store on your own computer.
## Roll back edits with version history
As you and your collaborators edit a document, Hyperclay records snapshots in the document's **Versions** tab. You can browse the latest 50 versions, click **View** to inspect an earlier snapshot, or click **Restore** to replace the current document with that version.
Restoring a version always saves a backup of the current document first, so rolling back never costs you the state you had right before the restore. See [Version history](https://hyperclay.com/docs/version-history/).
## Recover deleted items from Trash
Deleting a document, uploaded file, or folder moves it to **Trash** rather than erasing it immediately. When you delete a folder, the folder and everything inside it stay together in **Trash** as one recoverable unit.
Deleted items and their version history remain in **Trash** for 30 days. Account owners and team editors can open **Account menu**, choose **Trash**, and click **Restore** to return an item to its original folder. See [Trash](https://hyperclay.com/docs/trash/).
## Keep your own copies with export
Every malleable document is a standard HTML file that you can keep outside Hyperclay:
- To save a copy of one document, open its **Actions for** menu and click **Download** to download the `.htmlclay` file.
- To back up everything you own at once, open **Account menu** and click **Export workspace** to download a single `.zip` containing every folder, document, and uploaded file in your workspace.
See [Import and export](https://hyperclay.com/docs/import-export/) for full details on downloading and re-importing your files.
## Unsaved writing kept in your browser
The Journal, Kanban and Block editor templates also keep a copy of writing that has not saved yet, in your browser. If a tab closes or the connection drops before a save lands, the document offers that writing back the next time you open it in edit mode, and you choose whether to keep it. This copy lives only in that browser and is not a version. See [Recovery](https://clayjs.com/docs/recovery/).
---
# Share and collaborate
> Choose how to share a document on Hyperclay: share links, named viewers and editors, teams, live presence, and comments.
Source: https://hyperclay.com/docs/guide/sharing/
Hyperclay gives you three ways to let other people view or edit a document, plus live presence and comments once they are inside.
| Way to share | What it is | Who it suits |
|---|---|---|
| **[A share link](https://hyperclay.com/docs/share-links/)** | A URL that opens one document to view or to edit | Anyone, including people without a Hyperclay account |
| **[Sharing with a person](https://hyperclay.com/docs/share-with-a-person/)** | One named person gets viewer or editor access to one document | Someone outside your team who works with you on one document |
| **[A team](https://hyperclay.com/docs/teams/)** | A shared workspace with its own subdomain and its own document library | People you work with regularly across many documents |
## Share links
Each document can have a **View link** and an **Edit link** that work even when the document is private. Anyone holding the link can open the document in their browser without signing in or creating an account, and you can copy the link, show its QR code, or revoke it at any time. An edit link opens the document in view like any other link, and the person turns on editing with the page's **Edit** switch or `⌘⇧E`. See [Share links](https://hyperclay.com/docs/share-links/).
## Share with a person
When you want to grant access to a specific person by email rather than a link anyone can forward, open **Share…** on a document and invite them under **People** as a viewer or an editor. Documents other people share with you by name appear in the **Shared with me** tab on your dashboard, without exposing the folder they live in. See [Share with a person](https://hyperclay.com/docs/share-with-a-person/) and [Shared with me](https://hyperclay.com/docs/shared-with-me/).
## Teams
A team is a shared account with its own address (such as `acme.hyperclay.com`), its own documents and folders, and its own trash. You sign in as yourself and work in the team workspace as an **Owner**, **Editor**, or **Viewer**, with every save attributed to the person who made it. See [Teams](https://hyperclay.com/docs/teams/).
## Presence and comments
When more than one person has the same document open, an avatar row in the top bar shows who is viewing or editing right now. Anyone with a confirmed email address who can open the document can also pin comments to a spot on the page or to the whole document, mention collaborators with `@`, and follow replies in the workspace **Inbox**. See [Presence and comments](https://hyperclay.com/docs/presence-and-comments/).
---
# Publish on your own domain
> Give a document a dedicated Hyperclay subdomain, then connect your own custom domain with automatic TLS.
Source: https://hyperclay.com/docs/guide/domains/
Every document you create in Hyperclay starts with an address under your account namespace, such as `.hyperclay.com/.html`. When you are ready to publish a document at its own root address, you can promote it to a dedicated `.hyperclay.com` subdomain first, and connect a custom domain you own whenever you want. Both options are included on the [Personal and Maker plans](https://hyperclay.com/docs/billing/).
## Step 1: Claim a Hyperclay subdomain
A Hyperclay subdomain gives your document a short address like `my-project.hyperclay.com` without buying a domain or editing DNS records.
1. Open the document's menu and choose **Domains** (or open its **Domains** tab).
2. In the **Current address** row, click **Change**.
3. In the **Hyperclay subdomain** field, type the subdomain name you want before `.hyperclay.com`. Names use lowercase letters, numbers, hyphens, and underscores.
4. Click **Claim subdomain** (or **Change subdomain** if the document already has one).
Your document is immediately live at `https://.hyperclay.com`. Changing an existing subdomain updates the document's public address, so links using an earlier claimed subdomain stop working.
Personal plans start with 3 subdomains (growing by 1 each month up to 10), and Maker plans start with 6 (growing by 2 each month up to 25). For naming rules and how folder paths and addresses fit together, see [Addresses and subdomains](https://hyperclay.com/docs/addresses/).
## Step 2: Connect your own domain
When you have a domain of your own at a DNS provider or registrar, connect it in the same **Domains** panel.
**Step 1: Add the domain in Hyperclay**
In the document's **Domains** panel, under **Custom domains**, click **Add domain**. Enter a bare domain such as `example.com` or a subdomain such as `app.example.com`. If you enter a bare domain, leave **Also send `www.` here** checked so `www.` redirects to the bare domain, then click **Add domain**.
**Step 2: Create the DNS records at your provider**
Look at the **DNS setup** table on the **Domains** page and copy each record into your DNS provider:
- A **Traffic** record: an `A` record pointing to `5.161.29.91` for a bare domain, or a `CNAME` record pointing to `domains.hyperclay.com` for a subdomain.
- A **Validation** record: a `CNAME` record for `_acme-challenge.` pointing to the validation target shown in the table. Keep this record in place permanently so TLS certificates can renew.
If you checked **Also send `www.` here**, add the `www` records listed in the table as well.
**Step 3: Check that the domain is live**
After saving your DNS records, return to the **Domains** panel and click **Refresh status**. Once DNS propagation finishes and the certificate is provisioned, **Status** changes to **Active** and **TLS** changes to **Issued**.
For wildcard domains, Cloudflare settings, status meanings, and removing a domain, see [Custom domains](https://hyperclay.com/docs/custom-domains/).
---
# Work on your computer
> Edit and run malleable documents on your computer using Hyperclay Local for two-way folder sync or HTML Clay for standalone local files.
Source: https://hyperclay.com/docs/guide/your-computer/
Every malleable document is a standard `.html` or `.htmlclay` file that you own. If you open a downloaded document directly in a web browser from a `file://` path, the page renders in view mode, but the browser cannot write changes back to your disk on its own.
To edit and save malleable documents on your computer (macOS, Windows, or Linux), use one of two free desktop apps: **[Hyperclay Local](https://hyperclaylocal.com/docs/)** or **[HTML Clay](https://htmlclay.com/docs/)**.
## When to pick which
- **Pick [Hyperclay Local](https://hyperclaylocal.com/docs/)** when you want to work on a folder of documents and uploads in a local workspace window, edit files in your own desktop code editor, or sync folders in both directions with your personal and team workspaces on hyperclay.com.
- **Pick [HTML Clay](https://htmlclay.com/docs/)** when you want to double-click and edit individual `.htmlclay` files anywhere on your disk, completely offline and without connecting an account.
## Sync folders with Hyperclay Local
[Hyperclay Local](https://hyperclaylocal.com/docs/) runs a local server for a folder on your computer and opens your files in the same workspace interface as Hyperclay's dashboard.
You can run Hyperclay Local offline for free, or connect it to your Hyperclay account with a sync key:
- **Two-way live sync**: Edits, new documents, uploads, nested folders, renames, moves, and deletions sync in real time between your computer and hyperclay.com.
- **Team folders**: One sync key syncs your personal workspace and creates a separate local folder for each [team](https://hyperclay.com/docs/teams/) where you are an owner or editor.
- **Offline reconciliation and conflict resolution**: When you work offline, Hyperclay Local keeps automatic local backups of every save and reconciles your changes when you reconnect. If a file changed on both sides, sync shows the conflict and lets you pick which version to keep.
- **Use your own tools**: Because your documents sit in a normal folder on disk (with `.html` or `.htmlclay` extensions), you can edit them in any desktop code editor or let local scripts and AI agents work on them.
### Connect Hyperclay Local to your account
1. In Hyperclay, open the **My account** menu and click **Generate sync key…**.
2. In the **Generate sync key** dialog, generate a new key and click **Copy key**. Keep the key private; it is shown only once when created and expires after one year. (Generating a sync key requires an active paid plan, or an editor role on a team with a **Maker** plan.)
3. Follow the [Hyperclay Local quick start](https://hyperclaylocal.com/docs/guide/quick-start/) and [Sync with hyperclay.com](https://hyperclaylocal.com/docs/guide/sync/) to install the app and paste your sync key.
## Open single files with HTML Clay
[HTML Clay](https://htmlclay.com/docs/) is a desktop app for opening, editing, and saving standalone `.htmlclay` documents on macOS, Windows, and Linux.
- **Double-click to open**: Open any `.htmlclay` file from Finder or File Explorer like a regular document. Plain `.html` files can also be opened read-only with their stylesheets, scripts, and images.
- **Local version history**: Every save writes back to the file on disk and records a local version you can browse and restore.
- **Self-contained assets and Tailwind**: Upload files into a folder beside the document, build Tailwind CSS locally from a single link tag with no build step, and export a document and its attachments as a portable zip.
To get started with standalone local files, read the [HTML Clay quick start](https://htmlclay.com/docs/guide/quick-start/). To download documents from your Hyperclay workspace to open on your computer, see [Import and export](https://hyperclay.com/docs/import-export/).
---
# Use AI
> Build new documents with Describe anything, edit open pages with AI edit, or connect your own coding agent through the Sync API.
Source: https://hyperclay.com/docs/guide/ai/
Because every Hyperclay document is a single HTML file that holds its own markup, styles, behavior, and data, AI tools can build or edit an entire document in one place. You can use AI with Hyperclay in three ways:
1. **[Describe anything](https://hyperclay.com/docs/hosted-ai/#describe-anything)**: Write a brief in the dashboard and let Hyperclay build a complete document from scratch.
2. **[AI edit](https://hyperclay.com/docs/hosted-ai/#ai-edit)**: Switch the document to edit (click **Edit**, press `Cmd+Shift+E`, or choose **Return to editing** in the workspace's document menu), then press `Cmd+J` to ask Hyperclay's hosted AI to change the page in place.
3. **[Your own AI agent](https://hyperclay.com/docs/agents/)**: Make an agent key and connect Claude Code, Claude Desktop or Cursor to read and edit your documents.
## Build a document with Describe anything
When you want a custom tool, tracker, or page built from scratch, open **New** in your workspace, choose **New document**, and pick **Describe anything**.
Write a description of at least 200 words (around 500 is better) explaining who will use the document and how it should work, then click **Build · up to 350 credits**. Hyperclay builds the document in about 5 to 10 minutes and saves it into your workspace. Failed builds do not use any credits. See [Hosted AI](https://hyperclay.com/docs/hosted-ai/#describe-anything) for credit pools and plan requirements.
## Edit an open document with AI edit
When you are editing a hosted document that includes the ClayJS [ai-edit](https://clayjs.com/docs/plugins/ai-edit/) plugin, press `Cmd+J` (`Ctrl+J` on Windows and Linux) to open the prompt bar. Documents open in view, so switch to edit first: click **Edit** on the page, press `Cmd+Shift+E`, or choose **Return to editing** in the workspace's document menu. Describe the change you want, such as adding a filter bar, restyling a section, or wiring up a new field, and send it.
The document's owner and [team editors](https://hyperclay.com/docs/teams/) can run AI edits on any workspace covered by a Personal or Maker plan. Edits stream into the page as they happen and draw from the account owner's monthly AI credit pool.
If you have a static HTML page and want to make its content editable with the [ClayJS CMS plugin](https://clayjs.com/docs/plugins/cms/), you can also open the document's three-dot menu in the dashboard and choose **Add CMS with AI** (or **Regenerate CMS with AI**). Hyperclay proposes the content structure, validates it, and applies the CMS rules and attributes in the background. Always review the resulting fields on the page before handing it over. For full details on hosted AI features, credits, and limits, see [Hosted AI](https://hyperclay.com/docs/hosted-ai/).
## Work on your files with your own agent
If you use a coding agent that can run shell commands, such as Claude Code or Codex, it can work on your Hyperclay documents directly over HTTP with `curl` and `jq` (or on local files synced with [Hyperclay Local](https://hyperclaylocal.com/docs/guide/ai-editing/)). To connect Claude Code, Claude Desktop or Cursor through an MCP server instead, with a key you can limit to a team or folder, see [Edit with AI agents](https://hyperclay.com/docs/agents/). The rest of this section is for scripts that use `curl`.
Suppose you ask your coding agent to mark `"Renew passport"` as done in `tasks.html`. It runs a few `curl` commands, updates the document on `hyperclay.com` so the item reads `done `, and everyone who loads the page sees the change.
An agent reaches your documents in two ways:
- **Read public data as JSON without a key**: Any public document that includes an `api` rules tag exposes its structured data as JSON at `/_/api/.html` (and any document can be queried with `?data=`). See [Page data endpoints](https://hyperclay.com/docs/page-data/) and [data: pages as JSON](https://clayjs.com/docs/plugins/data/).
- **Read and write full HTML with a sync key**: With an `hcsk_` sync key generated from your account menu (**Generate sync key…**), an agent can list your documents, read private documents, fetch a document's whole HTML, edit it locally, and save it back through the [Sync API](https://hyperclay.com/docs/sync-api/). Give an agent a sync key only when it needs one, and revoke the key when the job is done.
For example, a public document at `https://alice.hyperclay.com/tasks.html` can expose its tasks to an agent with an `api` rules tag in its body:
```html
Renew passport open
Book flights done
```
Generating a sync key requires a Personal or Maker plan on your own account, or an owner or editor role on a team whose owner is on Maker. See [Sync API for agents and scripts](https://hyperclay.com/docs/sync-api/) for the step-by-step `curl` commands to list, read, update, undo, and revoke access.
---
# Files and folders
> Create, name, rename, move, and bulk-manage documents and folders up to five levels deep in your workspace.
Source: https://hyperclay.com/docs/files/
You organize your documents and uploaded files in folders inside your workspace. You can nest folders up to five levels deep, rename or move items individually, or select up to 100 items at once in the files table to move or delete them together.
## Name rules
When you type a document or folder name in a create or rename dialog, Hyperclay formats it as you type:
- Uppercase letters are converted to lowercase.
- Characters outside lowercase letters (`a` to `z`), numbers (`0` to `9`), hyphens (`-`), and underscores (`_`) are replaced with hyphens.
- Consecutive hyphens collapse into a single hyphen, and leading or trailing hyphens are trimmed.
- Document names must end in `.html` or `.htmlclay`. If you omit the extension, `.html` is added automatically. Folder names do not take an extension.
When the dialog adjusts what you typed, it shows **Saved as** followed by the formatted name below the field. If the resulting name is invalid, the dialog displays the reason and disables the submit button:
- A name cannot be empty or longer than 255 characters.
- A name cannot start or end with a hyphen, or contain consecutive hyphens.
- A single underscore (`_`) and system names such as `con` are reserved.
Uploaded files keep their original names instead of being slugged. Upload names can be up to 255 bytes and may contain letters, numbers, spaces, and `._()[]{}-!@#$%^&+=`, but cannot contain `/ \ < > : " | ? *` or reserved system names.
## Folder depth
Folders can nest up to 5 levels below the root of your workspace:
- Creating a sixth folder level is refused with **Maximum folder depth reached (5 levels)**.
- Moving a folder to a destination where it or its subfolders would pass 5 levels is refused with **Moving would exceed maximum folder depth (5 levels)**.
- You cannot move a folder into itself or into any of its own subfolders.
The top-level `uploads` folder holds attachments for your documents and is locked: it cannot be renamed, moved, or deleted. See [Uploads](https://hyperclay.com/docs/uploads/).
## Create a document or folder
To create a folder:
1. Open the **New** menu and start the **Create folder** dialog.
2. Enter a name in **Folder name**.
3. Click **Create folder**.
To create a document, open **New** and click **New document** to pick a starter in the gallery; see [Templates](https://hyperclay.com/docs/templates/).
To copy an existing document, open its **Actions for** row menu and click **Duplicate**. The default name is `-copy.html`, trimmed if needed to stay within 255 characters.
## Rename a document or folder
Account owners and team editors can rename any document, upload, or normal folder (team viewers cannot rename items). A file a document uploaded, and that document's own folder inside `uploads`, cannot be renamed or moved by themselves: they move and rename with their document.
1. In the files table, open the item's **Actions for** menu and choose **Rename** (or rename the item inline in the sidebar file tree).
2. Enter the new name in the **Name** field.
3. Click **Rename**.
## Move a document or folder
Account owners and team editors can move items between folders:
1. Open the item's **Actions for** menu and click **Move to folder…**.
2. In the **Move** dialog, choose a destination folder (pick **Files** to move the item to the root of your workspace).
3. Click **Move**.
Moving and renaming happen in a single atomic operation, so a move either finishes completely or leaves the item untouched.
> [!WARNING]
> Moving an item changes its path-based URL, including the paths of everything inside a moved folder. Update any links that point to the old path. Pictures and files a document uploads are stored in its own `uploads/assets-document-/` folder, named after the document's id, so they keep working when the document is renamed or moved.
## Bulk select
In the files table, use the row checkboxes to act on multiple items at once. Only rows you have permission to move or delete can be selected.
- Click individual checkboxes to add or remove rows, or Shift-click a checkbox to select a range of rows.
- Click the header checkbox (**Select all**, or **Select loaded items** when more rows remain) or press Cmd+A (Ctrl+A on Windows and Linux) to select all loaded rows.
- Press Escape or click **Clear selection** in the floating bar to clear your selection. Switching folders also clears the selection.
When one or more rows are selected, a floating bar shows **`` selected** and offers two actions: **Move to folder** and **Delete**. Bulk operations process 1 to 100 items per request, and larger selections are split into batches of 100 automatically.
### Move to folder
Click **Move to folder** in the floating bar to open the **Move `` items** dialog. Pick a destination folder and click **Move here**. Moving a folder moves everything inside it and updates path-based URLs for all moved items.
### Delete
Click **Delete** in the floating bar to open the **Delete `` items?** confirmation dialog, then click **Delete `` items**. Every selected item moves to [Trash](https://hyperclay.com/docs/trash/), and any selected folder includes everything inside it.
When a bulk move or delete finishes, a notification reports **Moved `` items.** or **Deleted `` items.** If any items could not be changed, the notice reports **`` items did not change.** with the reason for each file and a **Retry failed or unattempted** button.
---
# Search, Recent and pins
> Search file names and words inside your documents, reopen recent work grouped by day, and pin up to 50 documents to the sidebar.
Source: https://hyperclay.com/docs/search/
You can find any document in your workspace from the left sidebar: search file names and the words inside your documents, reopen documents you worked on recently, or pin up to 50 documents to keep them at the top of the sidebar.
## Search
The workspace sidebar has a **Filter files** box at the top. Press Cmd+K (Ctrl+K on Windows and Linux) from anywhere in the workspace to jump straight to it. On a phone, the shortcut opens the sidebar first.
### Filter by file name
As you type in **Filter files**, the sidebar file tree narrows immediately to items whose file names match what you typed, hiding rows that do not match. When no file names match your query, the tree displays **No file names match.**
### Search inside documents
Once you type 2 or more characters, a second section headed **Found inside documents** appears below the file tree. It searches the text inside your own active documents and documents shared with you, skipping anything in [Trash](https://hyperclay.com/docs/trash/).
- Search uses up to 6 words, with up to 32 characters per word, and returns up to 20 matching documents.
- Each result shows the document's name and where it lives: its folder name, **Files** if it sits at the root of your workspace, or **Shared by ``** if someone else owns it.
- Below the name, a snippet of up to 24 words shows the matching passage with your search words highlighted.
- If no document text matches, the section shows **No document mentions "``".**
### Highlighting in the open document
Click any result under **Found inside documents**, or press Enter in **Filter files** to open the first content result. The document opens beside your files and highlights the matched word on the page so you can see where it appears right away.
## Pins and Recent
Above your file tree, the sidebar gives you quick access to the documents you pin and a history of everything you opened recently, grouped by day.
### Pins
You can pin any active document that you can open (folders and uploaded files cannot be pinned).
- To pin a document, open its `...` menu in the workspace header or its **Actions for** menu in the files table and click **Pin to sidebar**.
- Pinned documents appear under the **Pinned** heading in the sidebar, below **Recent**, **Inbox**, **Shared with me**, and **Home**, and above the file tree. When you have no pinned documents, the **Pinned** section is hidden.
- Pins are listed in the order you pinned them, oldest first. Hovering a pin shows the document name and its owner.
- To remove a pin, open the document's menu and click **Unpin from sidebar**.
You can pin up to 50 documents. If you try to pin a 51st document, Hyperclay shows **You can pin up to 50 documents. Unpin one first.** Any pinned documents that were later deleted or that you can no longer access are skipped in the sidebar and cleared automatically when you reach the 50-pin limit.
### Recent
Click **Recent** near the top of the sidebar to see up to 50 documents you opened most recently. Opening a document again moves it to the top of the list.
- Your history is grouped by your local calendar into **Today**, **Yesterday**, and **Earlier**. Empty groups are hidden.
- The table lists each document's **Name**, **Opened** timestamp (a time of day under **Today** and **Yesterday**, or a date under **Earlier**), and **Updated** timestamp.
- Your **Recent** list is private to your account (**Only you see this list**).
---
# Uploads
> Upload images and files to your workspace, see how per-document upload folders work, and preview or edit uploaded text files in the dashboard.
Source: https://hyperclay.com/docs/uploads/
You can upload images, PDFs, text files, and other assets from the workspace dashboard or from inside a malleable document. Uploaded files live alongside your documents in the workspace, where you can preview them, edit text uploads in the code editor, or manage them like any other file.
## Upload files from the dashboard
1. Open the **New** menu and click **Upload files…**, or drag files from your computer onto the files table when it shows **Upload here**.
2. In the **Upload files** dialog, click **Choose files** to pick one or more files. The dialog displays your current storage usage (**`` MB of `` MB used**) and tracks each file through **Waiting**, **``% sent**, **Processing**, **Uploaded**, or **Failed**.
3. When an upload finishes, click **Copy link** (or **Copy all links**) to copy its URL, or click **Open file** to view it in the workspace.
To let people upload files or crop images from a document's own code, use the [upload and quickcrop plugins](https://clayjs.com/docs/plugins/upload/).
## Where uploads live
When a file is uploaded from inside a document, Hyperclay stores it in that document's own folder at `uploads/assets-document-/` (created automatically on the first upload) and links to it at `/_/uploads/assets-document-/`. The folder is named after the document's id, not its name, so renaming the document never moves its pictures or breaks their URLs, and two documents with the same name never share a folder.
Because that `/_/uploads/assets-document-/` path resolves from the root of your account rather than relative to the document's current folder, all of the document's images and attachments keep working when you move the document into another folder.
A file uploaded from inside a document belongs to that document, and where your account's uploaded files have been protected, its URL follows the document's read access: anyone the document is shared with can open the picture, and anyone who cannot open the document gets the same 404 the file would give if it did not exist. Change who can read the document and its pictures answer to that on the next request, so a document that becomes private takes its images with it. These files are also sent as `Cache-Control: private, no-store`, so no shared cache keeps a copy from a time when more people could read them.
What that does not cover: files uploaded before this protection existed stay reachable by their URL until the account's protection migration has run, and a copy someone downloaded while a URL was public cannot be taken back.
[HTML Clay](https://htmlclay.com/docs/uploads/) and [Hyperclay Local](https://hyperclaylocal.com/docs/metadata-and-uploads/) keep the older name-based folder, `assets-`, and their own file-serving rules apply to it rather than a shared-document access rule.
The top-level `uploads` folder holds attachments for every document in your workspace, so it cannot be renamed, moved, or deleted. You can still rename, move, or delete individual uploaded files and subfolders inside `uploads`; see [Files and folders](https://hyperclay.com/docs/files/).
## Open an upload
Click any uploaded file in the sidebar tree or files table to open it in the workspace beside your files:
- **Images** (`png`, `jpg`, `jpeg`, `gif`, `webp`, `avif`, `svg`) render in place.
- **PDFs** open in your browser's PDF viewer.
- **Text files** (`txt`, `md`, `markdown`, `json`, `html`, `htm`, `htmlclay`, `jsx`, `css`, `js`, `mjs`, `csv`, `tsv`, `xml`, `yml`, `yaml`, `log`) display as plain text.
- **Other files** show **This kind of file can't be shown here.** with **Download** and **Open in new tab** buttons.
### Edit a text file in the dashboard
When you open a UTF-8 text file or an `.svg` upload and have permission to edit code, a **Code** tab appears at the top of the view. Click **Code** to edit the file in the [Code editor](https://hyperclay.com/docs/code-editor/), then click **Save** or press Cmd+S (Ctrl+S on Windows and Linux) to save your changes. Click **Close Code** to return to the preview.
## Limits
Per-file and total upload storage limits depend on your [plan](https://hyperclay.com/docs/billing/):
- **Free**: images only (PNG, JPG, GIF, WebP, AVIF or SVG), up to 10 MB per file, 25 MB total storage.
- **Personal**: up to 20 MB per file, 500 MB total storage.
- **Maker**: up to 100 MB per file, 2 GB total storage.
Uploading a file larger than your plan's per-file limit returns **This file is larger than `` MB.** When your workspace reaches its storage cap, uploads stop with **Storage limit reached (``MB). Upgrade your plan for more storage.**
From the dashboard **Upload files** dialog, you can upload any file type except `.shtml` and `.xht`. When uploading from inside a document's own upload lane, `.html`, `.htm`, `.xhtml`, `.htmlclay`, `.js`, `.mjs`, `.xml`, `.shtml`, and `.xht` are refused so HTML documents and scripts are saved through the document save lane instead.
---
# Import and export
> Import HTML pages or a Notion export into your workspace, and download a single document or your entire workspace as a zip.
Source: https://hyperclay.com/docs/import-export/
You own every file in your workspace as standard HTML and uploaded assets. You can import standalone HTML files or zip archives such as Notion and Google Docs exports, download individual documents, or export your entire workspace as one zip file.
## Import
To import pages into your workspace:
1. Navigate to the folder where you want the imported files placed.
2. Open the **New** menu and click **Import files…**.
3. In the **Import files** dialog, click **Choose files…** and pick one or more `.html`, `.htm`, `.htmlclay`, or `.zip` files from your computer.
### What you can import
- **HTML files** (`.html`, `.htm`, `.htmlclay`): Each file you pick becomes a document in the current folder. You can select multiple HTML files at once.
- **A Notion export**: In Notion, open a page's `...` menu, choose **Export**, pick **HTML**, and import the `.zip` file Notion downloads. Hyperclay strips Notion's 32-character IDs from page and folder names, turns subpages into folders, places images and attachments into your uploads, and rewrites links so they keep working.
- **A Google Docs export**: In Google Docs, choose **File**, then **Download**, then **Web page (.html, zipped)**, and import the resulting `.zip`.
- **Any `.zip` of HTML pages and assets**: Hyperclay creates a new folder named after the zip file, imports each HTML page as a document, moves non-page files (such as images, PDFs, or spreadsheets) into `uploads/import-/`, and rewrites relative links across your pages to point to the imported documents and uploads. System files such as `__MACOSX` and `.DS_Store` are skipped.
> [!NOTE]
> If a Notion export with subpages produces a zip that holds another zip inside it (**This zip holds another zip. Unzip it once and import the zip inside.**), unzip the outer file once on your computer and import the inner `.zip`.
### Import limits
- **Page size**: Each HTML page can be up to 8 MB before and after link rewriting. In a zip import, pages larger than 8 MB are skipped and listed in the completion notice while the rest of the zip finishes importing.
- **Zip size**: A zip archive must fit within your plan's per-file upload limit (20 MB on Personal, 100 MB on Maker; see [Uploads](https://hyperclay.com/docs/uploads/)), contain at most 2,000 entries, and expand to at most 200 MB uncompressed.
- **Folder depth**: Imported subfolders cannot exceed the 5-level [folder depth](https://hyperclay.com/docs/files/) limit (**This folder is too deep to import into. Choose a folder higher up.**).
- **One zip at a time**: Hyperclay runs one zip import at a time across the whole service. If another import is running, yours is refused with **Another zip import is running. Try again in a minute.**
## Export your workspace
Anyone with view access to a workspace can download the entire workspace as a single zip archive:
1. Open **Account menu** (**My account**).
2. Click **Export workspace**.
Your browser downloads `-hyperclay-.zip`. Only one export can run at a time per workspace; starting another while one is running shows **An export is already running**.
### What is inside the workspace zip
- `README.txt` describing the archive layout.
- Every folder and every document owned by the workspace (including private documents), saved as `.html` files with absolute `/_/uploads/...` links rewritten to local `/_/uploads/...` paths.
- The `uploads/` folder, with every uploaded file you are allowed to open.
- `MISSING.txt`, added only if any listed file had no stored content.
Documents shared with you from another account, items in [Trash](https://hyperclay.com/docs/trash/), comments, [version history](https://hyperclay.com/docs/version-history/), custom domain settings, and account settings are not included in the zip.
## Download a single document
To download one document from the hosted workspace, open its **Actions for** menu in the files table and click **Download**. Hyperclay saves the document as a single file under its own name, with its upload URLs rewritten to full links on your `hyperclay.com` address, so its images and attachments keep loading from anywhere. Pictures added to a private document are the exception: they load only for people who can open that document.
To export a single document together with its attachments bundled as one `.zip` archive, use the desktop apps: see [Export as zip in HTML Clay](https://htmlclay.com/docs/export/) and [Export as zip in Hyperclay Local](https://hyperclaylocal.com/docs/export/).
---
# Templates
> Start a new document from a blank file or one of Hyperclay's templates, or save any document of your own as a reusable template.
Source: https://hyperclay.com/docs/templates/
Every new document in Hyperclay starts on the **Start a new document** page. Name it if you like, pick a template, and create it. You can start from a blank HTML file, one of Hyperclay's templates, or a document you saved as a template in your own workspace.
## The New document page
Open the **New** menu and click **New document**. The page has, from top to bottom:
- **Document name**, marked **(optional)**. If you opened the page from inside a folder, a chip beside it says **In folder: ``**.
- **Pick a template**: Hyperclay's templates, as cards.
- **Templates in ``**: the templates saved in your own workspace, when there are any.
- **Describe anything**, when [hosted AI](https://hyperclay.com/docs/hosted-ai/) is on for your account.
### Hyperclay's templates
- **Blank**: An empty HTML file with [ClayJS](https://clayjs.com/docs/script-tag/) included, so you can write your own markup from scratch.
- **Journal**: A private notebook for dated entries with titles and tags, kept in one HTML file. A Journal created from this gallery starts private, so only you can open it.
- **Kanban**: A simple board to move work across lists, saved in one HTML file.
Each card shows a picture of the template, its size and **ClayJS**. Click **Preview** on a card to see it large. In the preview, **Previous**, **Next** and the tabs move between templates, **Select card** picks that template, **Start with ``** creates the document straight away, and **Close** or **Escape** goes back to the page.
### Templates in ``
Appears when your workspace has saved templates in its top-level `templates` folder (see [Save as template](#save-as-template)). Each card shows the template's file name and **Updated ``**.
### Describe anything
**Describe it** opens a box where you say what you need in your own words, and Hyperclay builds a working malleable document with all of its features for you. See [Hosted AI](https://hyperclay.com/docs/hosted-ai/). While AI is paused for your account, the button is turned off and the page says why.
## Start a document
1. Type a name in **Document name**, or leave it blank. The hint under the field previews the file name, **Saved as ``.** (see [Files and folders](https://hyperclay.com/docs/files/) for naming rules). Left blank, the document is named `untitled`, then `untitled-1`, `untitled-2` and so on.
2. Click a template card to select it. **Starting from ``** beside the button shows your pick.
3. Click **Create**, or press **Enter** in the name field. Double-clicking a card also creates the document.
If the folder already has a file with that name, the page shows **`` is already in this folder. Pick another name.**
## Upgrade a document made from a template
A document you make from the **Block editor** or **Journal** template remembers which template and version it came from. When Hyperclay publishes a newer version of that template, the document offers it to anyone who can edit it: an **Upgrade to version ``** item in the document's menu, or an **Upgrade** and **Not now** notice when the page has no menu. Upgrading moves your content into the new version and saves it as one change. See the [ClayJS upgrade plugin](https://clayjs.com/docs/plugins/upgrade/).
## Save as template
Account owners and team editors can turn any duplicable document into a reusable workspace template (team viewers do not see this option):
1. Open the document's menu in the workspace or in the files table.
2. Click **Save as template** (located right after **Duplicate**). While the copy is being created, the menu item reads **Saving as template…**.
### Where saved templates live
- **Save as template** copies the document into a folder named `templates` at the root of your workspace, creating the `templates` folder automatically if it does not exist yet.
- The copy uses the document's file name, or appends `-2`, `-3`, and so on when that name is already taken inside `templates`.
- Every live document placed directly inside your root `templates` folder appears on the New document page under **Templates in ``**, sorted alphabetically by name. Subfolders, uploaded files, and any `templates` folder located inside another folder are left out.
- Picking a card under **Templates in ``** and clicking **Create** copies that template into the folder where you opened the page.
---
# Version history
> Browse the latest 50 versions of a document, preview how it looked, and restore any earlier version.
Source: https://hyperclay.com/docs/version-history/
Hyperclay records versions of your documents as they change so you can inspect how a document looked at an earlier point and restore it when needed.
## How versions are recorded
Open a document in your workspace and select the **Versions** tab to see its history. The table lists each version with two columns: **Recorded** (when the snapshot was taken) and **Recorded by** (who caused it to be recorded).
Version history says **Recorded by**, not "Saved by", and the difference is real. Some versions capture what the document looked like **before** an action, and the name on them is whoever caused the version to be taken, not whoever wrote those bytes. A first-save safety backup and a restore backup are both like this.
How attribution works on each row:
- **Display names**: The name shown in **Recorded by** is that person's current display name, so renaming yourself updates your name throughout the history.
- **Edit links**: A version created through an edit [share link](https://hyperclay.com/docs/share-links/) reads **Recorded through an edit link**.
- **Missing author**: If the author's account is no longer available, the row shows **Author unavailable**.
- **Recovered tab edits**: A snapshot recovered from a tab that was open when the page changed is labelled **Recovered edits** (**From a tab that was open when the page changed.**).
Saves made on your computer through the desktop app do not create a platform version on `hyperclay.com`. Instead, [HTML Clay](https://htmlclay.com/docs/guide/backups/) and [Hyperclay Local](https://hyperclaylocal.com/docs/guide/backups/) keep their own local backups on disk.
## How many versions are kept
The **Versions** tab displays up to 50 versions per document (**Showing the latest 50 versions.**).
Versions stay with the document for as long as it exists, including when you rename or move it. If you delete a document, its versions stay with it in [Trash](https://hyperclay.com/docs/trash/) for 30 days and return if you restore the document. Permanently deleting an item from **Trash** (or letting it expire after 30 days) permanently deletes all of its versions.
## View and restore a version
Anyone who can view the document in the workspace (owners, team editors, and team viewers) can open the **Versions** tab and click **View** on any row to inspect that version without changing the live document.
Account owners and team editors can also roll the document back to an earlier version (team viewers do not see the **Restore** button):
1. Open the document's **Versions** tab.
2. Click **Restore** on the version you want to bring back.
3. In the **Restore version of ``** dialog, click **Restore version**.
Before replacing the current document with the chosen version, Hyperclay saves a backup of the current document first (**The current document will be replaced with this saved version. A backup of the current document is saved first.**). If you want to undo the restore, you can restore that backup from the top of the **Versions** list.
If the document was modified after you loaded the history list, restoring stops with **This file changed since you last loaded it.** Reload and check the latest version before trying again.
---
# Trash
> Restore deleted documents, uploads, and folders within 30 days, or permanently delete them from Trash.
Source: https://hyperclay.com/docs/trash/
Deleting a document, uploaded file, or folder in Hyperclay moves it to **Trash** instead of erasing it immediately. Items stay in **Trash** for 30 days so you can restore them if you change your mind.
## What goes to Trash
When you delete a document, upload, or folder from your workspace, it moves to **Trash**. To open **Trash**, click **Account menu** (**My account**) and choose **Trash**.
- Deleting a folder moves the folder and everything inside it to **Trash** together as one unit.
- Items in **Trash** cannot be opened until you restore them, and they are left out of [search](https://hyperclay.com/docs/search/) and [workspace exports](https://hyperclay.com/docs/import-export/).
- The **Deleted items** table lists each item's **Name** and **Deleted** date.
## How long items stay in Trash
Items remain in **Trash** for 30 days (**Files in Trash are deleted for good after 30 days.**). After 30 days in **Trash**, a daily cleanup permanently deletes expired items along with their [version history](https://hyperclay.com/docs/version-history/).
## Restore from Trash
1. Open **Account menu** and click **Trash**.
2. Click **Restore** on the row you want to recover.
3. Confirm in the **Restore ``** dialog.
When you restore an item:
- It returns to its original folder. Restoring a folder puts back the folder and everything that was deleted with it.
- If its original folder no longer exists, the item returns to **Home** at the root of your workspace.
- If another item in that folder now has the same name, the restored item is renamed `-restored` (or `-restored-2`, and so on).
- If a trashed document had a custom domain or claimed subdomain, you must reconnect the custom domain or claim the subdomain again (if still available) after restoring; see [Addresses and subdomains](https://hyperclay.com/docs/addresses/) and [Custom domains](https://hyperclay.com/docs/custom-domains/).
Items are restored one row at a time. If a row's underlying file bytes are unavailable, the row shows **Files unavailable** and **Restore** is disabled.
## Delete forever or empty Trash
> [!WARNING]
> Permanently deleting an item also destroys its entire [version history](https://hyperclay.com/docs/version-history/). Deleted items and their recoverable history cannot be restored after this action.
You can permanently erase items from **Trash** in three ways:
- **Single item**: Click **Delete permanently** on the item's row and confirm in the **Delete `` permanently** dialog.
- **Selected items**: Tick the checkboxes next to the items you want to remove, click **Delete selected** in the bulk bar, and confirm in the **Delete `` selected items permanently?** dialog.
- **All items**: Click **Empty Trash** in the page header and confirm in the **Empty Trash permanently** dialog.
## Who can use Trash
- **Account owners**: Can open **Trash**, **Restore** items, **Delete permanently**, **Delete selected**, and **Empty Trash**.
- **Team editors**: Can open **Trash** and **Restore** items, but cannot permanently delete items or empty **Trash** (the permanent delete and **Empty Trash** controls are hidden).
- **Team viewers**: Cannot open or use **Trash**.
---
# Code editor
> Open and edit a document's HTML, CSS, JavaScript, or text uploads in the browser with the built-in CodeMirror editor.
Source: https://hyperclay.com/docs/code-editor/
Hyperclay includes a browser code editor built on CodeMirror so you can inspect and edit the source code of any malleable document or text upload directly in your workspace.
## Open a document in the code editor
You can open the code editor in two ways:
- In the workspace, open a document and switch to its **Code** tab (or open the **Code** panel alongside the document). Click **Close Code** to return to the rendered document.
- Prefix a document's URL path with `/_/edit/`, such as `.hyperclay.com/_/edit/.html`.
You can also open text [uploads](https://hyperclay.com/docs/uploads/) in the dashboard and edit them in the **Code** tab. Supported text formats include `.txt`, `.md`, `.markdown`, `.json`, `.html`, `.htm`, `.htmlclay`, `.jsx`, `.css`, `.js`, `.mjs`, `.csv`, `.tsv`, `.xml`, `.yml`, `.yaml`, `.log`, and `.svg`. Binary uploads or files that are not valid UTF-8 text cannot be opened in the code editor (`This file cannot be opened as text.`).
## Edit and save
The CodeMirror editor provides:
- Syntax highlighting for HTML, CSS, JavaScript, JSON, Markdown, and SVG
- Auto-indentation and bracket matching
- Line numbers, search, and multi-select with `Cmd+D` (`Ctrl+D` on Windows and Linux)
While you have unsaved edits in the editor, the header status reads `Unsaved changes`. Click **Save** or press `Cmd+S` (`Ctrl+S` on Windows and Linux) to write your changes. Once the save finishes, the status updates to `Saved `. Hyperclay saves the markup you wrote without reformatting it. One exception: if the document carries a block editor format marker (` `) and your edit removes it, Hyperclay puts the marker back, so an older editor can never open the document and lose content it cannot read.
If someone else (or another open tab) saves the file while you have it open in the code editor, a banner warns `This file changed on the server.` Click **Save over theirs** only if you want your editor buffer to replace the newer version on the server. Every save records a version in [Version history](https://hyperclay.com/docs/version-history/).
## Who can use the code editor
Editing code requires an active [Personal or Maker plan](https://hyperclay.com/docs/billing/) on your own personal account.
| Context | Who can edit code |
|---|---|
| **Your own workspace** | You, while your account has an active Personal or Maker plan |
| **[Team](https://hyperclay.com/docs/teams/) workspace** | The team **Owner** and team **Editors**, provided their own personal account is on a Personal or Maker plan |
| **Team Viewer** | No (`You cannot edit this site's code.`) |
| **[Share links](https://hyperclay.com/docs/share-links/) and [one-document shares](https://hyperclay.com/docs/share-with-a-person/)** | No |
> [!NOTE]
> On a team, code editing follows the person rather than the team's subscription. A team editor whose personal account does not have an active paid plan can still edit documents on the page, upload files, and rename, move, or trash documents, but sees `You cannot edit this site's code.` in the **Code** panel.
## Alternative: Browser Developer Tools
Because a malleable document saves its own live DOM, you can also use your browser's built-in Developer Tools to make structural edits:
1. Open your document while signed in with edit rights and [edit mode](https://clayjs.com/docs/edit-mode/) active.
2. Press `F12` (or `Cmd+Option+I` on macOS) to open Developer Tools and switch to the **Elements** panel.
3. Double-click elements or attributes in the DOM tree to edit the HTML in place.
4. Save the document (`Cmd+S` or `Ctrl+S`, or let [ClayJS](https://clayjs.com/docs/guide/saving/) save automatically) to persist your DOM changes back to the file.
---
# Share links
> Create a view link or an edit link for one document, and know exactly what each link does and does not reach.
Source: https://hyperclay.com/docs/share-links/
A share link is a URL with a token in it: anyone you send it to can open the document with no account and no sign-in. Each document can have one view link and one edit link, and they grant different things.
## Share links
Open the document's **…** menu and choose **Share…**. The dialog has **Address**, **View link**, **Edit link** and **People** tabs. The link tabs let you create a link, copy it, show its QR code or revoke it.
Any account can create a view link, including a free one. Creating an edit link needs a paid plan. If the plan ends, you can still copy or revoke an existing link.
Each document can have two links, and they are different.
- **A view link** opens the document, downloads it, reads its JSON, and opens its version history. On a collection dashboard it also reads the collection's records.
- **An edit link** does everything a view link does, and can save. It opens the document in view, like any document; the person switches to editing with the **Edit** switch or Cmd+Shift+E (Ctrl+Shift+E), or you can add `&editmode=true` to the link to open it straight into editing.
Both work on a private document. Both are just a URL with a token in it, so anyone you send it to can use it, with no account and no sign-in.
**Neither link reaches the owner's side of the document.** No settings, no privacy, no subdomains, no custom domains, no uploads, no code editor, no template reset, no managing the links themselves, and no deleting a collection record. A link grants exactly what its mode says.
> [!WARNING]
> **An edit link lets someone change the document's code.** Saving accepts the whole HTML file, so an edit link is not limited to text and CMS fields. Send it to people you trust with the document.
**Revoking a link is permanent.** The link stops working straight away, any live connection it was holding is closed, and creating a link again gives you a **new** URL and a **new** QR code. The old one never comes back.
A share URL contains the document's current address, so renaming the document, or moving it, or renaming your account invalidates the link. Create a new one after any of those.
### What a link does not protect
**Files uploaded from inside a private document stay private with it.** Once your account's uploads are protected, a picture added to a document answers only to people who can open that document, link holders included. Files you upload from the dashboard, and older uploads the protection has not reached yet, are served from their own address to anyone who has it. See [Uploads](https://hyperclay.com/docs/uploads/).
**A link to a collection dashboard includes the collection's records.** Someone holding a view link can list the records and read one. They cannot delete one.
---
# Share with a person
> Give one person read access to a single document by email, even when the document is private.
Source: https://hyperclay.com/docs/share-with-a-person/
Sharing by name gives one person read access to one document, even when it is private. It needs their email address, not a link, and it appears in their **Shared with me** tab.
## Sharing one document with a person
Open the document's **…** menu, choose **Share…**, then open **People** and enter an email address. Adding someone or resending an invitation needs a paid plan. You can still remove a viewer or cancel an invitation after the plan ends.
The person gets read access to that one document. They can open it even when it is private, and view its version history. They cannot edit it.
What happens next depends on them:
- **They already have a confirmed account.** They get access immediately and an email with a link straight to the document.
- **They have an account but have not confirmed their address.** They confirm it first, then land on the document.
- **They have no account.** They get an invitation, good for 14 days, that creates a free account when they accept it.
An invitation can only be accepted by the address it was sent to. Signing in as somebody else and opening the link does not work.
Accepting a document share **changes nothing about an existing account**. It does not confirm an address, it does not alter a plan, and it grants nothing beyond that one document.
There is no editor version of this. Someone outside your team who needs to change a document either joins the team or holds an edit link.
---
# Shared with me
> Find the documents other people have shared with you by name in a dashboard tab, and leave a share you no longer want.
Source: https://hyperclay.com/docs/shared-with-me/
Documents other people share with you by name collect in one tab on the dashboard, so you do not have to hunt through email for them.
## Shared with me
Documents other people have shared with you by name appear in a **Shared with me** tab on the dashboard. The tab can appear on personal and team dashboards. Each row shows the document, who owns it, and buttons to **Open** or to **Leave**.
The tab is hidden when nobody has shared anything with you, and it does not appear inside a folder.
A share on a document inside somebody's folder does not reveal the folder. You see the document and nothing around it.
---
# Teams
> Create a team account, invite viewers and editors, move documents into it, and know what happens when a plan ends.
Source: https://hyperclay.com/docs/teams/
A team is a shared account for people who work together regularly: it has its own address, documents, folders and trash, and its owner's plan pays for it. Nobody logs in "as" the team, so every save is attributed to the person who made it.
## Teams
A team is an account of its own. It has its own address, `acme.hyperclay.com`, its own documents, its own folders and its own trash. Nobody logs in "as" the team. You sign in as yourself and act on the team's account, and every save is attributed to you.
Creating a team needs an active Maker plan. Open the profile menu at the top right of the dashboard and choose **New team…**, or go to `/_/dashboard/teams/new`. The dashboard currently offers one team per owner. You choose two things:
- **A team name**, which is what people see. The owner can change it later.
- **A team address**, which becomes the subdomain and the folder your documents live in.
> [!WARNING]
> **The team address works like a username.** The owner can change it once every 30 days. Changing it changes every URL that uses the team address and revokes existing view and edit links. People who were given access by name keep their access.
Team names share one namespace with usernames and claimed subdomains, so a name already in use anywhere on Hyperclay is refused.
Joining a team changes nothing about your own account. Your plan, your personal documents and your own subdomain are untouched, and you keep them if you leave.
### Roles
Every member holds one of three roles.
| | Owner | Editor | Viewer |
|---|---|---|---|
| Open and download documents | yes | yes | yes |
| View version history | yes | yes | yes |
| Restore a version | yes | yes | no |
| Save changes to a document | yes | yes | no |
| Create documents and folders, upload files | yes | yes | no |
| Rename, move and trash | yes | yes | no |
| See the trash page and restore from it | yes | yes | no |
| Delete permanently and empty the trash | yes | no | no |
| Edit code | yes, if their own account is on a paid plan | yes, same condition | no |
| Document sharing, privacy and signups | yes | yes | no |
| Team settings, subdomains and custom domains | yes | no | no |
| Invite people, change a role, remove a member | yes | no | no |
| Leave the team | no, transfer or delete it first | yes | yes |
Two things about that table are worth stating on their own.
**Code editing follows the person, not the role.** An editor on a free account can create, save, rename, move and trash a team's documents, and gets no code editor. An editor on a paid plan gets one. The role decides what you may do to the team's documents; your own plan decides whether the code tools are available to you at all.
**Billing is never a team thing.** Checkout, billing management, upgrades and changing a username all act on your own personal account. There is no separate team card: a team is billed through its owner's Maker subscription, which includes four people, the owner and three editors. Each extra editor adds $3/month, or $2/month on annual billing. Viewers and share links are always free.
### Managing members
Open the team dashboard and choose **Members**. The owner can invite someone by email as a Viewer or Editor. An invitation is valid for 14 days.
The same page lists current members and pending invitations. The owner can change a role, remove a member, resend an invitation or cancel it. Editors and viewers can leave from this page. The owner must transfer or delete the team before leaving.
### What an editor is trusted with
**An editor can save anything into a team document, including scripts.** Every team document is served from one subdomain, which means one browser origin, so a script one editor saves runs with the same access as everything else on that subdomain.
**The code editor being hidden from a free account is a convenience, not a boundary.** Ordinary saving accepts a whole HTML document, so anyone who can save can change the code, whether or not the code editor is available to them in the interface.
So: invite people as editors when you trust them with the team's documents the way you trust yourself. Invite them as viewers when you do not. There is no in-between role, on purpose.
### The shared allowance
A team has no allowance of its own. It draws on the plan of the member who owns it, and that is a single pool covering the owner's personal account and every team they own. **Creating a team adds no capacity.**
A teammate's upload counts against the owner's allowance. On the Maker plan that is 2 GB in total and 100 MB per file, shared.
The owner sees the plan on Team settings. Other members see only that it is a team; whose card is charged is not shown to them.
The one exception is when the plan lapses. Then every member is told who can fix it, because they need to know: the team becomes read-only until the owner renews, and everyone can still open and download everything.
## Moving a document into a team
Open the document or folder's **…** menu and choose **Move to another account…**. A move to another account revokes every view and edit link for the moved documents. Access granted to named people stays in place.
**Moving a folder carries everything under it**: the documents, the folder structure, the files uploaded into it, and anything in the trash below it.
**Moving a single document carries the document**, its versions and the pictures added to it from inside the document. Other files it uses stay on your personal account and keep working at the URLs they already have.
Because a file's URL contains the account it belongs to, moving a folder changes the address of every file inside it. Hyperclay rewrites those addresses inside the documents it moved, and records the rewrite as a version with a note saying how many links it updated.
Before the move it shows you what it cannot fix: **any document outside the folder that used one of those files, and will therefore break.** It names the ones you are allowed to see and says generically that others may be affected.
Three kinds of reference cannot be found by any scan, and the move does not claim otherwise:
- a URL the page's own JavaScript builds at run time
- a reference inside an uploaded stylesheet
- a reference that exists only in an older version of a document
A claimed subdomain does not block the move. Hyperclay releases it automatically. A document cannot move while it has people signed up to it, because their instances belong to their accounts and cannot move with the document. A move is also refused when the same name already exists at the destination or when it would put content more than five folders deep.
Moving needs the settings permission on the source and the create permission on the destination, so a team editor cannot move a team's folder out into their personal account.
## When a plan ends
**Nothing is deleted and nothing is hidden.** Every file, folder, upload, version, custom domain, share link and team membership stays exactly where it was.
**What a free account can still do:**
- open and download every document it owns, private ones included
- **save changes** to a document
- upload images, up to 25 MB in total and 10 MB per file
- duplicate a document
- rename and delete a document
- rename, move and delete folders
- rename, serve and delete an upload
- use the trash: restore, purge, empty
- list, view and restore versions
- manage the records in a collection it already has
- keep every custom domain resolving
- see billing history and upgrade
**What comes with a subscription:**
- creating a blank document
- creating a folder
- the code editor, Add CMS and Make Malleable
- applying a template
- signups, collection mode, discoverability and claimed subdomains
- creating edit links, adding a person and resending an invitation (a personal account keeps view links on the free plan)
- configuring a custom domain
- changing your username
- generating a desktop sync key
- creating and owning a team
**Tidying up is always allowed.** A free account can remove a custom domain, copy or revoke an existing share link, remove a viewer, cancel an invitation, turn signups off, make a document private, make one public again, move things around, and delete a folder. You are never locked out of cleaning up after yourself.
A refusal that a subscription would lift says so, and paying reopens it immediately.
### On a team, and in the desktop app
**A team whose owner's plan lapses becomes read-only.** Everyone can open and download everything; nobody can save, create or upload until the owner renews.
**The desktop app tells you.** When a plan has ended, syncing a change says so plainly rather than retrying. Reading, exporting and deleting keep working.
---
# Presence and comments
> See who else has a document open, pin comments to a spot or the whole document, and follow replies and mentions in your inbox.
Source: https://hyperclay.com/docs/presence-and-comments/
When you collaborate on a document in Hyperclay, you can see who else has it open in real time, pin comments to specific elements or to the whole document, and track replies and `@` mentions in your workspace inbox.
## Who else is on the document
When more than one person has the same document open, a row of avatars labelled **In this document now** appears in the document's top bar, to the left of **Share**. The row is hidden when you are the only person on the document.
Up to three avatars are shown directly, followed by `+N` for additional named people and `+N viewing` for anonymous readers. Hovering an avatar shows the person's name, or `Name, can edit` when they hold edit rights. Solid indicators mark people who can edit, and hollow ones mark people who are reading.
**Names are shown only to people who hold view access to the document.** Someone reading a public page with no access of their own sees only a `+N viewing` count and no names. A holder of a [view link](https://hyperclay.com/docs/share-links/) has view access to the document, so they see names, and they appear to everyone else as `Guest 1`, `Guest 2`, and so on.
**The count of anonymous readers counts connections, not people.** One person with three browser tabs open counts as three connections. Opening the **Code** panel does not add an extra reader connection.
**In a block-based document, you see where the others are typing.** Each person editing a document built on the ClayJS page editor, such as the Block editor template, shows on the page as a caret and a highlighted selection labelled with their name. Other documents have no live cursors. Through [ClayJS Live Sync](https://clayjs.com/docs/guide/live-sync/), two people editing different parts of a page merge cleanly, and blocks another person is actively editing are outlined on the page. You also get a one-line notice when somebody else changes the part of the page you were working in; dismiss it or recover your replaced text and carry on.
## Comments
Open the **Comments** panel from the comment icon in the document toolbar or from the document's **Comments** tab. When a document has unread open comments, the toolbar icon displays an unread badge (`Comments, N open, unread`, up to `99+`).
### Who may read and post comments
Anyone signed in to Hyperclay who can view the document can read its comments. Signed-out visitors cannot open comments (`Sign in to use comments.`).
Posting a comment, replying, editing, resolving, reopening, and deleting require a signed-in account with a confirmed email address. Until you confirm your email address, the write controls are hidden and comment actions answer `Confirm your email address to comment.`.
### Pin a comment to a spot or the whole document
1. Open the **Comments** panel and click **New comment**.
2. Choose **Pick a spot** to attach the comment to an element on the page, or **Comment on the whole document**. (If the document does not support element anchors, the composer opens directly for a whole-document comment.)
3. When you choose **Pick a spot**, the panel prompts `Click something in the document. Press Escape to cancel.` Click the part of the page you want to comment on.
4. Type your comment (up to 10,000 characters) and click **Post comment**, or press `Cmd+Enter` (`Ctrl+Enter` on Windows and Linux).
A comment pinned to a spot displays a quote preview (up to 120 characters) of the anchored text. Whole-document comments are labelled **Whole document**.
If the document changes after a spot comment is posted, the thread header tells you what happened to its anchor:
- **Text changed since this comment**
- **Hidden in the document right now**
- **Not found in the document**
- **Matches more than one place**
Click **Choose a new location** on the thread to re-pin it to a current spot on the page.
### Mention someone
Type `@` inside the comment composer to open the **People** list, then pick a person by name and `@username`. The list offers up to 200 people who have read access to the document, drawn from the document owner, [team members](https://hyperclay.com/docs/teams/), people the document is [shared with](https://hyperclay.com/docs/share-with-a-person/), and earlier comment authors on that document.
### Reply, edit, resolve, and delete
Each comment thread in the panel supports the following actions:
- **Reply**: Click **Reply** on a thread, write your response, and click **Reply** to post it.
- **Edit**: Click **Edit** on your comment to update its text. Edited comments are marked `edited`.
- **Delete**: Click **Delete**, then click **Confirm delete** within 4 seconds. Deleted comments display `Comment deleted`.
- **Resolve and reopen**: Click **Resolve** to close an open thread. Resolved threads move out of the open list; click **Show resolved (N)** at the top of the panel to display them, and click **Reopen** on any resolved thread to move it back to open comments.
- **Export**: Click **Download comments (JSON)** in the panel header to download all comments on the document as a JSON file.
If someone else updates or resolves a thread while you are replying or editing, Hyperclay keeps your draft text in the box and alerts you with `Someone changed this thread. Try again.` or `This thread was resolved or deleted by someone else.`.
## Inbox
Click **Inbox** in the workspace sidebar to see comment activity across your documents. The sidebar entry shows a bell icon and an unread badge that updates automatically.
### What lands in the inbox
A notification arrives in your inbox when another person:
- **mentioned you** with `@username` in a comment or reply
- **replied** to a thread you started or previously replied to
- **commented** to start a new thread on a document in your personal workspace
- **resolved a thread** that you started
Your own comments, replies, and resolves never generate notifications for you. Clicking any row in the inbox opens that document's **Comments** panel directly at the thread. Threads that have been closed show a **Resolved** tag.
### Filters and email notifications
Use the filter tabs at the top of the **Inbox** page to switch between:
- **All**: Every notification, 50 per page (click **Load more** for older items).
- **Unread**: Only unread threads (`Nothing unread.` when caught up).
- **Mentions**: Only comments where someone `@` mentioned you (`No mentions.` when empty).
To change which comment notifications also arrive by email, open the account menu at the top right of the workspace and choose **Comment emails…**. You can pick **All comments**, **Mentions only**, or **None**. Resolving a thread never sends an email, and changing your email preference does not change what appears in your in-app **Inbox**.
---
# Discover
> Browse public malleable documents in the Discover gallery, or list your own public document there.
Source: https://hyperclay.com/docs/discover/
Discover (`/discover`) is Hyperclay's public gallery of malleable documents that people have chosen to share. Anyone can browse the gallery, with or without a Hyperclay account, and open any listed document to try it.
## What appears on Discover
The Discover page lists documents in reverse chronological order, with the most recently updated documents first. Each card in the gallery shows:
- The document's name and author (`by `)
- A screenshot preview of the document (or `Screenshot not ready yet` while the first preview is still rendering)
- A **View** and **Edit** preview toggle
Clicking a card opens the document in a new tab at its public Hyperclay address.
## List a document on Discover
Listing a document in Discover is off by default. To add one of your documents:
1. Make sure the document is **public**. Private documents do not appear in Discover.
2. Open the document's action menu and choose **Add to Discover**.
3. Confirm in the dialog. The files table marks listed documents with a **Discover** pill.
Whenever a listed document is saved, Hyperclay automatically queues a fresh screenshot so its card on Discover stays up to date.
### Requirements and limits
- **Plan and role**: Adding or removing a document on Discover requires an active Personal or Maker plan and management rights on the document (the account owner, or an owner or editor on a [team](https://hyperclay.com/docs/teams/)).
- **Public documents only**: You can turn **Add to Discover** on for a document at any time, but the gallery only displays documents that are currently public and belong to an active account.
- **No sign-up instances**: Individual user instances created from a [sign-up app](https://hyperclay.com/docs/sign-up-apps/) cannot be listed (`Instances cannot be added to Discover`). Only the main document can be added.
## Remove a document from Discover
Open the document's action menu and choose **Remove from Discover**, then confirm. Hyperclay removes the document from the `/discover` gallery and deletes its generated preview screenshots. Removing a document from Discover does not change its URL, privacy setting, or [share links](https://hyperclay.com/docs/share-links/).
---
# Addresses and subdomains
> How documents are addressed on your Hyperclay namespace, and the promoted subdomain and custom domain options.
Source: https://hyperclay.com/docs/addresses/
Your account is a namespace, and every document you create gets an address inside it. This page covers the default namespace URL, promoted subdomains, and custom domains.
## URLs & domains
Your Hyperclay account is a namespace. Every app you create lives inside it at `{your-username}.hyperclay.com/{app-name}.html`. Folders reflect in the URL: an app at `/projects/todo.html` lives at `{your-username}.hyperclay.com/projects/todo.html`.
If a folder is a [multi-page site](https://hyperclay.com/docs/multi-page-sites/), its pages also answer without `.html`. When `projects` is a site, `{your-username}.hyperclay.com/projects/todo` serves `projects/todo.html`, and opening the `.html` address redirects there. Outside a site, addresses do not change. See [Clean addresses](https://hyperclay.com/docs/multi-page-sites/#clean-addresses).
Three ways to reach your apps:
- **Default namespace URL**: `{your-username}.hyperclay.com/{app-name}.html`
- **Promoted subdomain** (paid): claim a dedicated subdomain like `{app-name}.hyperclay.com` for a flagship app, or for a whole [site folder](https://hyperclay.com/docs/multi-page-sites/#put-a-site-on-its-own-domain)
- **Custom domain** (paid):
- Connect your own domain (e.g., `myapp.com`) to one app or to a site folder
- Automatic SSL certificates
- Minimal DNS setup: add a CNAME/A record at your registrar
- Use one address per site: when you add `example.com`, keep **Also send www.example.com here** checked, and `www` redirects to the bare domain. A browser treats `example.com` and `www.example.com` as two separate sites, so a visitor who switches between them loses their drafts, saved app data, edit mode and share links, and search engines see two copies of your page.
---
# Custom domains
> Connect your own domain or subdomain to a Hyperclay document, configure DNS records, and check live status and TLS certificates.
Source: https://hyperclay.com/docs/custom-domains/
You can point your own bare domain (such as `example.com`), subdomain (such as `app.example.com`), or wildcard domain (such as `*.example.com`) at any document in Hyperclay. You can also point a bare domain or subdomain at a folder that is a [multi-page site](https://hyperclay.com/docs/multi-page-sites/). Hyperclay serves the document or folder at that address and provisions and renews TLS certificates automatically.
Custom domains are included on the [Personal and Maker plans](https://hyperclay.com/docs/billing/), with no limit on the number of custom domains you can connect. On a [team](https://hyperclay.com/docs/teams/), only the team owner can add or remove custom domains.
## Add a custom domain
1. Open the document's menu and choose **Custom domains** (or switch to the document's **Domains** tab). For a site folder, open the folder's menu and choose **Custom domains**.
2. Under **Custom domains**, click **Add domain**.
3. In the **Domain** field, enter a bare domain like `example.com`, a subdomain like `app.example.com`, or a wildcard like `*.example.com` (required if the document accepts [sign-ups](https://hyperclay.com/docs/sign-up-apps/)). Enter the hostname only, without `https://`, a port, a path, or a query string.
4. When you enter a bare domain, **Also send `www.` here** appears below the field. Keep it checked so requests to `www.` redirect to your bare domain.
5. Click **Add domain**.
> [!TIP]
> Keep **Also send `www.` here** checked when connecting a bare domain. Browsers treat `example.com` and `www.example.com` as two separate origins, so a visitor who switches between them loses browser-stored drafts, saved data, edit mode, and share links, and search engines index two copies of the document.
Hyperclay refuses hostnames that are not registrable public domains (`Use a registrable public domain.`), domains already connected to one of your documents (`This domain is already added to one of your sites.`), or domains that conflict with an existing mapping on another account (`This domain conflicts with an existing domain mapping.`).
## Point a domain at a site folder
A domain on a [site](https://hyperclay.com/docs/multi-page-sites/) folder serves the whole folder:
- `index.html` at `/`
- the other pages at their [clean addresses](https://hyperclay.com/docs/multi-page-sites/#clean-addresses), such as `/about` for `about.html`
- uploads at their paths inside the folder
- 404 for a path that names nothing
Only a folder that is a site can have a domain. A folder is a site when it holds a `site.json` file. Wildcard domains cannot point at a folder. If you rename or move the folder, its domain keeps working.
A Hyperclay subdomain can point at a site folder too: choose **Hyperclay subdomain** in the folder's menu.
## DNS records on the Domains page
After you add a domain, the **DNS setup** section on the **Domains** page lists the exact DNS records to create at your registrar or DNS host. The table has four columns: **Purpose**, **Type**, **Name**, and **Value**.
| Purpose | Type | Name | Value |
|---|---|---|---|
| **Traffic** (bare domain) | `A` | Your bare domain (`example.com` or `@`) | `5.161.29.91` |
| **Traffic** (subdomain or wildcard) | `CNAME` | Your subdomain (`app.example.com` or `*.example.com`) | `domains.hyperclay.com` |
| **Validation** | `CNAME` | `_acme-challenge.` | The token target shown in your **DNS setup** table |
If you checked **Also send `www.` here**, the table also lists the records for `www.`.
> [!WARNING]
> Keep the `_acme-challenge` **Validation** `CNAME` record in place permanently (`Keep this validation record in place so certificates can renew.`). If you use Cloudflare, set both the traffic and validation records to DNS only (grey cloud) so Hyperclay can validate your domain and terminate TLS directly.
A new domain claim stays open for 7 days while waiting for DNS records to point to Hyperclay. If the 7-day window expires before you configure DNS, re-adding the same domain reopens the claim window with the same DNS records.
## Check whether a domain is live
The **Custom domains** table lists each connected domain with three status columns:
- **Domain**: The hostname, the date it was added, and `Redirects to ` on companion `www` entries.
- **Status**: **Pending** while waiting for DNS, **Active** once traffic routing is verified, or **Failed**.
- **TLS**: **Pending** while the certificate is being requested, **Issued** once HTTPS is live, or **Failed**.
Opening the **Domains** page or clicking **Refresh status** queues a background DNS and certificate check (checks run at most once a minute). When **Status** shows **Active** and **TLS** shows **Issued**, your domain is live over HTTPS.
If a domain shows **Failed**, the row explains why: the DNS proof was removed after activation, the 7-day claim window expired before DNS pointed to Hyperclay, the domain conflicted with another reservation, or the certificate could not be renewed. Fix the DNS records shown in **DNS setup** and click **Refresh status**.
## Remove a custom domain
You can remove a custom domain at any time, even if your subscription has ended.
1. Open the document's **Domains** panel, or choose **Custom domains** in the site folder's menu.
2. Click **Remove** beside the domain you want to disconnect.
3. In the **Remove ``?** dialog, type the exact domain name into **Domain to remove** to confirm.
4. Click **Remove domain**.
Links using that domain stop opening the document or site immediately. The document or folder itself is not deleted and stays reachable at its Hyperclay address.
If a document has [sign-ups](https://hyperclay.com/docs/sign-up-apps/) enabled, its wildcard domain cannot be removed until you turn sign-ups off (`Wildcard domains cannot be removed while signups are enabled.`).
---
# Form messages
> Receive email notifications when visitors submit a message form on your published document, with built-in spam protection and rate limits.
Source: https://hyperclay.com/docs/form-messages/
Visitors can submit a contact or feedback form on your published document without you running a custom backend. To add a message form (`message-form`) to your document's markup, use the [ClayJS message plugin](https://clayjs.com/docs/plugins/message/).
## Where messages arrive
When a visitor submits a form carrying `message-form`, the page serializes the form fields and posts them to `/_/message` on Hyperclay.
Hyperclay looks up the owner of the document and sends an email notification to the owner's account email address:
- **From address**: `_@hyperclay.com`
- **Subject**: `message from (hyperclay site)`
- **Body**: One `**field**: value` line for each submitted form field, followed by a `site` link to the document's address.
On the page itself, a successful submission displays the text configured in `message-form` (or `Sent` if none is specified) and resets the form.
> [!NOTE]
> Form messages are delivered to your email inbox. They do not appear in the workspace **Inbox**, which only lists document [comments, replies, and mentions](https://hyperclay.com/docs/presence-and-comments/). In addition, when the form has an `email` field holding a valid address, the notification sets `Reply-To` to that address, so you can reply to the visitor straight from your inbox. Without a valid `email` field the header is left off, and you copy the visitor's address out of the message body instead.
If you want form submissions to create browsable items inside a workspace folder instead of sending email notifications, use [Collections](https://hyperclay.com/docs/collections/).
## Notify me form
A notify me form is a message form with one extra job: it collects an address you can reply to. Name the email field `email` and give it `type="email"`, so Hyperclay receives a valid address and sets `Reply-To` on the notification it sends you. Mark the form with a `message-form` attribute, whose value is the text the visitor sees after sending, so the ClayJS message plugin takes the form over on submit.
```html
```
The hidden `item` field names the thing the visitor asked about, and it arrives as one more line in the notification, so a page with several projects can tell them apart without a separate form for each. Any other field you add, such as the optional `note` above, is emailed as its own line too.
Each submission arrives as an ordinary message: one `**field**: value` line per field, a `site` link, and a `Reply-To` that is the visitor's own address. Click reply in your mail app and your answer goes to them rather than to `_@hyperclay.com`.
The plan requirements, rate limits and spam checks below apply to a notify me form unchanged. To show which items visitors liked alongside it, see [Likes](https://hyperclay.com/docs/likes/).
## Plan requirements
Any anonymous visitor can submit a message form on a public document as long as the document owner has an active paid plan (**Personal** or **Maker**).
If the document owner's subscription has lapsed, Hyperclay refuses submissions with the message `This form isn't accepting messages right now.` and sends no email.
## Spam protection and rate limits
Hyperclay screens every submission for bot activity and enforces rate limits before sending an email:
- **One-time form token**: When a visitor focuses or types in a form, the page requests a single-use token from `GET /_/form-token` (valid for 2 hours). If a token expires before the visitor submits, the browser fetches a fresh token and retries once automatically. Requests sent without JavaScript enabled are refused with `This message couldn't be sent: the form needs JavaScript turned on.`, and replayed or invalid scripted requests are refused with `This message couldn't be sent. Please try again.`.
- **Honeypot field**: If an automated bot fills the hidden `contact-me-by-fax-only` field, Hyperclay returns a normal success response to the bot and silently discards the message without emailing you. Internal verification fields (`formToken`, `formSignals`, `behaviorData`, and honeypots) are stripped before the message is emailed.
- **Per-connection limit**: A single IP connection can send at most 10 form submissions per hour. Extra attempts receive `Too many messages from this connection. Try again later.`.
- **Per-document limit**: A single document accepts at most 60 messages per hour. Extra attempts receive `This page has received too many messages. Try again later.`. This 60-message limit is counted after the bot check, so spam bursts cannot lock real visitors out of your form.
---
# Likes
> Let visitors like or rate items on any public page, with counts kept on Hyperclay and no backend of your own.
Source: https://hyperclay.com/docs/likes/
Visitors can react to individual items on a public page, such as liking a post or rating a project, without you running a backend. You declare the items in the page's own rules tag, the page reads the counts from Hyperclay, and a click writes one reaction back. Hyperclay stores the counts, so they survive renaming or moving the page.
The simplest way to like an item is the ClayJS like plugin: one attribute on a button, and the plugin reads the counts, paints them and sends the click.
```html
♥
```
Load `?plugins=like` on the ClayJS script tag and it does the rest. Its page has the markup, the events and the API: [ClayJS like plugin](https://clayjs.com/docs/plugins/like/).
## What likes do
A like is one row on Hyperclay, keyed to the page, the item, the action and a visitor id. A page reads the totals for every item it declares with one request, and toggles a single item with another. Nothing about the count lives in the saved HTML, so two people opening the page see the same numbers, and moving the page to another folder keeps them.
The page decides what a visitor can send, and Hyperclay refuses anything the page has not declared. A page that declares nothing has no likes at all.
## Declare the items on the page
Likes are set up in the page's `api` rules tag, under the key `projects`. This example declares every `.entry` inside `#stream` as an item:
```html
```
`projects` is a data extraction list rule, the same syntax as [page data](https://hyperclay.com/docs/page-data/): a selector, then a map from field names to selectors. Each matched element becomes one item, and the map reads fields from it.
- `id` is required. It names the item in every request, must be unique on the page, and can be at most 48 characters; an item with a longer id is left out. `@data-id` reads the element's `data-id` attribute, so the markup keeps the id.
- `name` is optional. It is a label for the item, read from text or an attribute.
- `actions` is optional and defaults to `like`. It holds the actions the item accepts, separated by spaces, so `like share` accepts two. Each action can be at most 48 characters.
An action can accept a set of values. Write it as `rating:1|2|3|4|5`, and a reaction to that action has to carry one of `1`, `2`, `3`, `4` or `5`. The markup for such a page looks like this:
```html
```
Hyperclay reads the rules tag at most once a minute, and again after five seconds when a request names an item the page has not declared yet. An item you add to the markup starts accepting likes within a few seconds of its first request.
Any element carrying a `like` attribute in the saved page is also an item, with the action `like` and the attribute's value (or the element's `id`) as its id, so the ClayJS like plugin needs no rule at all and the two can sit on the same page.
## Read the counts
`GET /_/reactions` on the page's own host returns the totals for every declared item, plus a form token:
```
curl -H "Document-URL: https://alice.hyperclay.com/posts.html" https://alice.hyperclay.com/_/reactions
```
```json
{ "counts": { "post-1": { "like": 3 }, "post-2": { "like": 1, "rating": { "5": 4, "4": 1 } } },
"formToken": "..." }
```
Every declared item and action appears, at zero when nobody has reacted, so `counts.post-1.like` is always a number. An action with values appears as an object keyed by value, and a value nobody has chosen is absent. That is why `rating` above lists `5` and `4` and nothing else.
Send the `Document-URL` header with the page's own address, so Hyperclay knows which page is asking when your document sits on a username host.
## Record a reaction
`PUT /_/reactions` turns a reaction on or off for one item and one visitor:
```
curl -X PUT -H "Document-URL: https://alice.hyperclay.com/posts.html" \
-H "Content-Type: application/json" \
-d '{"item":"post-1","action":"like","visitor":"9f2c1d4a7b6e8c0d","on":true,"formToken":"..."}' \
https://alice.hyperclay.com/_/reactions
```
The body has these fields:
- `item` is the item's `id`, and `action` is one of its actions.
- `visitor` is a random id the page makes once and keeps, 16 to 64 characters of `A` to `Z`, `a` to `z`, `0` to `9` and `-`. It is how Hyperclay knows that the same person clicked twice, and it is hashed before it is stored.
- `on` is `true` to add the reaction and `false` to take it away.
- `value` carries the chosen value for an action declared with values, and is required when `on` is `true` and the action has them. Leave it out for a plain `like`.
- `formToken` is the one-time token from the previous response. Only turning a reaction on needs it, and each token works once.
The response carries the new total for that action and a fresh token:
```json
{ "ok": true, "item": "post-1", "action": "like", "on": true, "count": 4, "formToken": "..." }
```
Keep the returned `formToken` for the next request, and read the counts again after a page reload. Toggling is idempotent per visitor: a visitor who likes an item twice still counts once.
## A complete client script
This page declares its items, adds a button to each, keeps one visitor id in `localStorage`, and toggles a like. It is plain `fetch` with no library.
```html
```
The script sends `Document-URL` on both requests, the same header the ClayJS message plugin sends, so a page served from a username host resolves to the right document.
## Errors and limits
Failures come back as JSON with `ok: false`, a `code`, an `error` message, and a fresh `formToken`.
- **`unknown-site`**: the page has no `projects` rule in its `api` rules tag, or none of its items is valid. Answers 404. A private page answers with the same plain 404 as a page that does not exist.
- **`unknown-item`**: the item is not declared by this page, or was removed from the markup. Answers 404.
- **`unknown-action`**: the item does not accept that action. Answers 404.
- **`invalid`**: `item` or `action` is missing, the visitor id is the wrong length or holds the wrong characters, `on` is not a boolean, or `value` is missing, too long or not one of the declared values. Answers 400.
- **`form-token`**: turning a reaction on arrived without a usable one-time token. Answers 400, and the response carries a fresh token to retry with.
- **Rate limits**: one connection can send 300 reactions an hour before it is locked out for the rest of the hour with `That's too many requests at once. Give it a little while and try again.` A connection can also turn on a given item and action for at most 5 different visitors a day, and reactions from further new visitors are dropped while the request still answers `ok`, so a shared connection cannot inflate a count.
- **`unavailable`**: Hyperclay could not read the page or reach its database. Answers 503, and the same request works again later.
Reading the counts is free of the write limit, so a page can poll `GET /_/reactions` to stay current.
## Likes are hosted only
Counts live on Hyperclay, keyed to the page. A page opened as a local file in HTML Clay, or downloaded with [Import and export](https://hyperclay.com/docs/import-export/), has no `/_/reactions` to talk to and shows no likes. Publish the page on Hyperclay to use them, on any plan.
A private page has no likes either. It answers with the same plain 404 as a page that does not exist, so a request never reveals whether it declares items.
---
# Tailwind on save
> Hyperclay generates the Tailwind CSS your document uses, regenerated on every save with no build step.
Source: https://hyperclay.com/docs/tailwind/
Hyperclay automatically generates Tailwind CSS for your apps. No build tools, no config files required. The stylesheet is regenerated on save with only the utilities you actually use.
## Tailwind CSS
Hyperclay automatically generates Tailwind CSS for your apps. No build tools, no config files required.
Add this to your ``:
```html
```
Replace `YOUR-APP-NAME` with your HTML filename (without `.html`). For a file named `my-app.html`:
```html
```
If your app lives in a folder, the Tailwind URL mirrors that path. For an app at `/projects/todo.html`:
```html
```
Then use Tailwind classes anywhere in your HTML:
```html
Click me
```
The CSS regenerates on save (and on first request if missing) with only the utilities you use. Works on hyperclay.com and Hyperclay Local.
---
# Sign-up apps
> Let visitors sign up on your published document to get their own private, editable copy at their own address.
Source: https://hyperclay.com/docs/sign-up-apps/
You can turn a published document into a sign-up app (also called a multi-tenant app) so visitors can create an account and get their own editable copy of your document at their own address. Your original document stays unchanged.
> [!TIP]
> If visitors only need to keep their edits in their own browser without creating an account, use the ClayJS [people and visitor drafts](https://clayjs.com/docs/plugins/people/) plugin instead. See [Free documents for visitors](https://clayjs.com/docs/guide/free-documents/) in the ClayJS guide.
## Enable signups on a document
1. Make sure your document is public. Private documents refuse visitor signups with a 404 error.
2. If your document uses a [custom domain](https://hyperclay.com/docs/custom-domains/), configure a wildcard custom domain (`*.yourdomain.com`) on the document first. Hyperclay requires a wildcard domain when custom domains are attached so each user's copy can be served on its own subdomain.
3. Open the document's file actions menu and click **Enable signups**.
4. In the **Enable signups** dialog, click **Enable signups** to confirm.
You can turn signups off at any time by opening the same menu and clicking **Disable signups**. Turning signups off prevents new visitors from signing up, while copies that people already created continue to work.
## Link to the signup, login, and password reset pages
After enabling signups on a document named `.html`, add links to these three routes in your document's interface so visitors can create an account and return to their copy:
| Action | URL | What it does |
| --- | --- | --- |
| **Sign up** | `https://.hyperclay.com/_/signup/.html` | Creates an account and a personal copy of the document |
| **Login** | `https://.hyperclay.com/_/login/.html` | Signs an existing user in to their copy |
| **Forgot password** | `https://.hyperclay.com/_/forgot-password/.html` | Sends a password reset email |
## What happens when a visitor signs up
1. On the signup page (`/_/signup/.html`), the visitor enters a **Username** (lowercase letters, numbers, and underscores), **Email address**, **Password** (at least 8 characters, avoiding common passwords), and **Confirm password**, then clicks **Create app account**. (A visitor who is already signed in to an existing Hyperclay account sees a **Create instance** button instead.)
2. Hyperclay sends a **Confirm your email** message with a confirmation link (`/_/confirm-email/`), and the page asks the visitor to check their email to activate their account.
3. Hyperclay copies your document's current HTML into a new root-level document in the visitor's own namespace, with its own version history starting at `Initial version`. If the visitor already has a document with that file name, Hyperclay names the new copy `-1.html`, `-2.html`, and so on.
4. The visitor is redirected to their copy at `https://.hyperclay.com/.html`, or `https://./.html` when your document uses a wildcard custom domain.
## Ownership and updates
Each copy belongs to the person who signed up, not to you:
- You cannot view a list of who signed up or edit someone else's copy from your workspace.
- Each copy is a snapshot of your document's HTML at the moment the visitor signed up. Later edits you make to your original document do not automatically flow into existing copies. If you want copies to pull template updates when you publish changes, build your document with the [ClayJS upgrade plugin](https://clayjs.com/docs/plugins/upgrade/).
## Plan limits
Enabling signups requires an active paid plan (**Personal** or **Maker**) or team editor access on a paid workspace. If your plan lapses, you can still click **Disable signups**, but turning signups back on requires an active subscription.
There is no limit on how many visitors can sign up for your sign-up app. Your plan limits how many of your own documents can have signups enabled at the same time:
- **Personal**: 1 sign-up app to start, growing by 1 for each month you remain subscribed, up to a maximum of 3.
- **Maker**: 5 sign-up apps to start, growing by 2 for each month you remain subscribed, up to a maximum of 25.
---
# Multi-page sites
> Make a folder a site: its pages share values such as a name and a navigation bar from one site.json file, answer at clean addresses, and can share one domain.
Source: https://hyperclay.com/docs/multi-page-sites/
A site is a folder of pages that share some values, such as the site's name and its navigation links. You keep those values once, in a file named `site.json`, and Hyperclay writes them into every page. Each page stays a complete HTML file that works on its own.
## What a site is
A folder is a site when it directly holds a public file named `site.json`. There is no other switch. If the file is not a valid JSON object, the folder is still a site, but no values reach the pages until you fix it.
- A site covers its subfolders too. If a subfolder has its own `site.json`, that file applies to the pages under it: the nearest `site.json` wins.
- `site.json` is a reserved file name.
- `site.json` is public. Anyone can read it by its URL.
> [!WARNING]
> Never put a secret in `site.json`. Anyone who knows the folder's address can read the whole file.
## Make a folder a site
1. In the dashboard, open the folder's menu and choose **Mark as site**.
2. Hyperclay creates `site.json` holding `{}` and opens it in the **Code** tab.
3. Add your shared values and save.
If the folder already has a `site.json`, **Mark as site** refuses and leaves the file as it is. A folder that is already a site shows **Edit site data** in its menu instead, which opens `site.json` in the **Code** tab.
An agent with an Edit key can also publish a local folder as a site with [clay-agent](https://hyperclay.com/docs/agents/#publishing-a-folder): `npx -y @panphora/clay-agent publish ./maya demos/maya`.
## Show shared values on a page
Each page says where each shared value goes. It does this in its [`api` rules tag](https://hyperclay.com/docs/page-data/), under a reserved key named `site`. The rules inside `site` use the same [selector grammar](https://clayjs.com/docs/plugins/data/#rules-reference) as any other rule, and they sit beside the page's other `api` rules.
Here the folder `ada` has this `site.json`:
```json
{
"name": "Ada Lovelace",
"nav": [
{ "label": "Home", "href": "/ada/" },
{ "label": "About", "href": "/ada/about" }
]
}
```
And `ada/about.html` says where those values go:
```html
Ada Lovelace
Home
About
```
Change `"name"` in `site.json` and the title, header and footer change on every page that has this rule. Add a third item to `"nav"` and every page gets a third link, copied from its first link. A page takes only the values its `site` rules name, so a page with no `nav` rule ignores `nav`.
### Write every match with `[*]`
A rule for a single value, such as `".site-name"`, writes only the first element it matches. Add `[*]` after the selector, as in `".site-name[*]"`, to write every match: the header, the footer and the title. When you read data, `.site-name[*]` returns the first match.
`[*]` works on hyperclay.com, in ClayJS and in Hyperclay Local. HTML Clay adds it in its next release.
### Text and attributes only
Shared values are only ever text and attribute values. They never write scripts, ` ` or ` ` tags, or raw HTML.
## What happens when site.json changes
When `site.json` changes, Hyperclay writes the new values into every page of the site, through each page's own rules, and saves each page that changed.
- Each changed page gets one new version in its [version history](https://hyperclay.com/docs/version-history/), marked as a site data update and credited to the person who changed `site.json`.
- A page that already holds the new values is not saved and gets no new version.
- A page open in edit mode in a browser tab updates while you watch.
- The values are plain markup in each HTML file, so the pages work offline and after you download them.
Values flow one way, from `site.json` to the pages. A page save never changes `site.json`. Every save writes the current `site.json` values into the page, so a tab that loaded old values cannot put them back when it saves later. Restoring an old version of a page also keeps today's shared values. To change a shared value, change it in `site.json`, not on a page.
## Ways to change site.json
1. **The Code tab.** Choose **Edit site data** in the folder's menu, change the JSON and save. This needs the same permission as any other edit in the [Code tab](https://hyperclay.com/docs/code-editor/).
2. **The site data API.** Read and write `site.json` over HTTP. See [Change site data from a script](#change-site-data-from-a-script).
3. **Hyperclay Local or the sync API.** In a synced folder, upload a changed `site.json`. The pages update, and the updated pages sync back to you. A page uploaded through sync is stored with the current shared values, so it can come back slightly different from what you sent. See [Sync API](https://hyperclay.com/docs/sync-api/).
4. **Agents.** An agent key reads and writes `site.json` through any page in the site, inside the folders the key can reach, and an Edit key can create or replace `site.json` when [publishing a folder](https://hyperclay.com/docs/agents/#publishing-a-folder). See [site data for agents](https://hyperclay.com/docs/agents/#site-data).
### Change site data from a script
`site.json` has an address under `/_/api` on your account address. On a domain attached to the site folder, the address is `/_/api/site.json`.
```
https://.hyperclay.com/_/api/ada/site.json
```
- `GET` returns the object with an `ETag`. Anyone can read it, from any origin.
- `POST` merges top-level keys, so send only what changes. `PUT` replaces the whole object.
- `""` and `[]` are real values: they clear what the pages show. A key that is missing from `site.json` leaves the pages as they are.
- `If-Match` is checked when you send it. You do not have to send it.
- You, your team's editors and your [sync key](https://hyperclay.com/docs/sync-api/) can write. A share link for one page cannot, so sharing a page never hands over the site. Send the body as `application/json`.
```bash
curl -X POST https://.hyperclay.com/_/api/ada/site.json \
-H "X-API-Key: $HYPERCLAY_KEY" \
-H "Content-Type: application/json" \
--data '{"name": "Ada King"}'
```
```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. Sending the same values again answers `"changed": false` and does nothing. The status codes are listed in the [platform reference](https://hyperclay.com/docs/platform-reference/#site-data).
## When a page cannot be updated
Hyperclay writes each page on its own and never rolls the others back. If one page cannot take a value, the other pages still update. The usual cause is a rule that matches nothing, for example a page whose `nav` rule finds no `` inside a ``.
With `site.json` open in the **Code** tab, a line under the editor shows how many pages are up to date. It names each page that was not updated and the reason, and offers **Retry**. Fix the page's markup or its rules, then click **Retry**. If `site.json` is not valid JSON, the line says so, and no page is updated until you fix it.
A script sees the same list in `pages.failed` in the API answer.
## Add, move and remove pages
- A new page in the site, or a page moved into it, takes the site's values.
- A page moved out of the site keeps its last values and stops updating.
- Moving `site.json` to the [trash](https://hyperclay.com/docs/trash/), or deleting it, stops updates and leaves every page exactly as it is. Restoring `site.json` from the trash makes the folder a site again.
- Renaming another file to `site.json`, or moving a `site.json` into a folder, makes that folder a site.
## Clean addresses
Inside a site, pages answer at addresses without `.html`. `ada/about.html` answers at `/ada/about`. Hyperclay looks for a path in this order:
1. The exact file.
2. `.html`
3. `.htmlclay`
4. `/index.html`
5. An upload, such as a PDF.
Inside a site, a path that names nothing answers 404.
- Opening `/ada/about.html` redirects to `/ada/about`. The redirect is temporary (302), so if you delete `site.json`, the `.html` addresses come back.
- An index page opened without its trailing slash redirects to the slash form, so `/ada/docs` goes to `/ada/docs/` and its relative links work.
- Saves and API calls never redirect.
- Relative links such as `about.html` keep working everywhere, offline too.
- A page whose clean address would clash with a word Hyperclay reserves for its own actions, such as `edit`, keeps its `.html` address.
Outside a site, addresses do not change.
## Put a site on its own domain
A [Hyperclay subdomain](https://hyperclay.com/docs/addresses/) or a [custom domain](https://hyperclay.com/docs/custom-domains/) can point at a site folder, as well as at a single document. Open the folder's menu and choose **Hyperclay subdomain** or **Custom domains**. An agent with an Edit key can claim the subdomain for you with clay-agent: `npx -y @panphora/clay-agent subdomain --site demos/maya maya`.
A domain on a site folder serves the whole folder:
- `index.html` at `/`
- the other pages at their clean addresses
- uploads at their paths inside the folder
- 404 for a path that names nothing
Only a folder that is a site can have a domain. Wildcard domains cannot point at a folder. If you rename or move the folder, its domain keeps working.
---
# Collections
> Turn a folder into a public submission form and an owner-only dashboard, backed by a JSON records API.
Source: https://hyperclay.com/docs/collections/
Mark any folder as a collection and Hyperclay turns it into a place to gather submissions: a public form anyone can fill out, and a private dashboard only you can see. Every submission is saved as a JSON record inside your own folder, so the data is yours and travels with your account.
Hyperclay seeds a working form and dashboard for you, but they are just plain HTML files. You can edit them, swap them out, or build your own from scratch against the same API. This page is that API.
## Mark a folder as a collection
In your file manager, open a folder's menu and choose **Mark as Collection**. Hyperclay adds three things inside it:
- `submission-form.html`, a public form,
- `dashboard.html`, an owner-only dashboard,
- a `records/` folder, where submissions are stored as JSON.
To build your own pages you need two values. Open the collection's menu and choose **Collection info**:
- **Collection ID** (looks like `col_a1b2c3xy`): the public id for the API. It is stable, so it never changes even if you rename or move the folder.
- **Submit token**: the credential a public form sends to create a submission. You only need this if you build your own form.
## The API
Every endpoint is JSON over the same origin as your site. Send and read `application/json`. A plain HTML form post will not work, you submit with `fetch`.
| Method | Path | Who | Purpose |
|---|---|---|---|
| POST | `/_/collection//records` | anyone with the token | create or update a submission |
| GET | `/_/collection//records?limit=&offset=` | owner only | list submissions |
| GET | `/_/collection//records/` | depends on the record | read one submission |
| PUT | `/_/collection//records/` | owner or the record's owner | update one submission |
| DELETE | `/_/collection//records/` | owner only | delete one submission |
`` is the Collection ID from the modal. In a list (the owner GET that returns `records`), each record comes back as:
```json
{ "id": "...", "data": { }, "modifiedAt": "2026-06-01T...", "size": 128 }
```
A single-record read returns `{ "id": "...", "data": { }, "modifiedAt": "2026-06-01T..." }`, without `size`. In both cases `data` is whatever JSON you submitted. Success responses are `{ "ok": true, ... }`. Failures return a non-2xx status with `{ "ok": false, "error": "..." }`.
Limits: 1MB per submission, 30 requests per minute per IP, and 10,000 records per collection. Records count toward your account's file storage.
## Build your own form
The simplest public form collects some fields and POSTs them as `data` with the submit token. Hyperclay gives each submission an unguessable id and remembers it in a cookie, so the same browser can come back and edit its own submission later.
```html
Send
```
`data` is just an object. You decide its shape. There is no server-side schema to define.
### Let submitters come back and edit (optional)
Pass a `key` you choose (an email, a phone number) plus a `code` (a secret the submitter picks). The record is then identified by the key and protected by the code: the submitter can reload it from any device by re-sending the key and code, and nobody else can read or change it. The code is never stored, only a hash of it.
```js
body: JSON.stringify({ token: TOKEN, key: email, code: secret, data })
```
To load an existing keyed record back into a form, GET it with the code in a header so it stays out of the URL:
```js
const res = await fetch(`/_/collection/${ID}/records/${encodeURIComponent(email)}`, {
headers: { 'x-collection-code': secret }
})
const { ok, data } = await res.json()
```
## Build your own dashboard
A dashboard is even simpler, because when you (the owner) view a page on your own site, your login cookie rides along automatically. No token, no auth code:
```html
```
Editing and deleting are one call each:
```js
// update a record's data
await fetch(`/_/collection/${ID}/records/${encodeURIComponent(key)}`, {
method: 'PUT',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ data: updated })
})
// delete a record
await fetch(`/_/collection/${ID}/records/${encodeURIComponent(key)}`, { method: 'DELETE' })
```
A PUT replaces the whole `data` object. If you are only changing some fields, read the current record first, merge your changes, and send the result back.
## Live updates (optional)
To make a dashboard update itself as submissions arrive, subscribe to the live-sync stream and listen for `collection-record` events. Open the stream only after a successful owner load, so a visitor who lands on the page never tries to connect.
```js
const es = new EventSource('/_/live-sync/stream?page-url=' + encodeURIComponent(location.href))
es.addEventListener('collection-record', (e) => {
const { op, id, data, modifiedAt } = JSON.parse(e.data)
// op is 'create', 'update', or 'delete'. Update your list in place.
})
```
## Pausing and unmarking
The folder menu also lets you **pause submissions** (the form starts returning a "not accepting" error) and **unmark** the collection (the form and dashboard stop working, but your files and records are kept, and you can re-mark anytime).
If you hand out a form link, remember that the link is just the page's file URL. Renaming or moving the file, or unmarking the collection, breaks that link. The Collection ID itself never changes, but the page URL is whatever you have named the file.
## Working with the data elsewhere
Records are ordinary JSON files in your `records/` folder, so anything else you build on Hyperclay can read them, and they sync to the desktop app like the rest of your files. The `extractData` and `applyData` helpers from [the JSON API](https://hyperclay.com/docs/page-data/) are a convenient way to move values between a form and a record object, but they are optional. A record is just JSON you control.
---
# Page data endpoints
> Read a document's HTML as JSON over the URL or a published endpoint, with cached responses and documented limits.
Source: https://hyperclay.com/docs/page-data/
Every Hyperclay page is already structured data: the HTML is the database. This page is the API for reading and writing that data. You describe what counts as data with a small map from field names to CSS selectors, and that one mapping works three ways:
- **From the URL**, as an ad-hoc query (`?data=`), read only, no setup.
- **As a named endpoint** the page publishes about itself (`/_/api`), read only.
- **In the browser**, as `extractData` and `applyData`, which read and write the live page.
The selector syntax is identical across all three, so once you can write the mapping you can use any of them. The rules syntax and the browser helpers are documented on the ClayJS [data page](https://clayjs.com/docs/plugins/data/).
## Read any page from the URL
Append `?data=` to any site URL with a mapping, and Hyperclay returns JSON. The rules live in the URL, nothing is set up in advance, and it is read only.
```html
My Tech Blog
Understanding JavaScript
Alice Smith
Python for Data Science
Bob Johnson
```
```
?data={title:"h1",posts:[".post",{heading:".post-title",author:".author"}]}
```
```json
{
"title": "My Tech Blog",
"posts": [
{ "heading": "Understanding JavaScript", "author": "Alice Smith" },
{ "heading": "Python for Data Science", "author": "Bob Johnson" }
]
}
```
A rule ending in `@--name`, such as `html@--color-accent`, returns one CSS custom property from the element's `style` attribute.
See it on a real site: [panphora.hyperclay.com/core/panphora.html?data=...](https://panphora.hyperclay.com/core/panphora.html?data=%7BsiteName%3A%22.site-name%22%2Cdescription%3A%22.site-description%22%2CnewsletterDescription%3A%22.newsletter-description%22%2Cposts%3A%5B%22%5Bpost%5D%22%2C%7Bdate%3A%22.post-date%40date%22%2Cdescription%3A%22.post-description%22%2Cnote%3A%22.post-note%22%2Cprojects%3A%5B%22%5Bproject%5D%22%2C%7Btype%3A%22.project-type%40project_type%22%2Cname%3A%22.project-name%22%2Curl%3A%22.project-name%40href%22%2Cdescription%3A%22.project-description%22%7D%5D%7D%5D%7D)
Responses are cached for five minutes. The `X-Cache` header is `HIT` from cache, `MISS` for a fresh extraction.
## Publish a named endpoint
Instead of putting rules in the URL, bake them into the page so it advertises its own stable shape. Add a rules tag with the token `api`:
```html
```
The page now serves that JSON at its own URL under `/_/api`:
```
GET https://you.hyperclay.com/_/api//.html
```
For a site named `blog` that is `https://you.hyperclay.com/_/api/blog.html`. The response is the bare JSON, public, GET only, and CORS-enabled, so any app on any origin can read it. `data-rules-version` must be `"1"`, and one tag can serve several consumers with space-separated tokens, for example `data-rules-name="api cms"`.
It is the same engine as `?data=`. The only difference is where the rules come from: `?data=` is a question you ask from outside, `/_/api` is the answer the page publishes about itself.
The one exception is a site's `site.json`: it is the only address under `/_/api` that takes writes, and it holds the values every page in a [multi-page site](https://hyperclay.com/docs/multi-page-sites/) shares. In a page's `api` rules tag, the key `site` is reserved for those shared values: its rules say where each value goes on the page.
## Responses and limits
- A matched value comes back as text, a missing element as `null`, an empty array as `[]`.
- Failures return an HTTP error status with a JSON `{ "error": "..." }` message.
- `?data=` and `/_/api` read the **saved** page on the server: static content only, no JavaScript execution, text and attributes rather than raw HTML.
- `extractData` and `applyData` run in the browser against the **live** page and can address element properties such as `@value` and `@checked`. `applyData` writes the local DOM only.
---
# Edit with AI agents
> Make an agent key and let Claude Code, Claude Desktop, Cursor or any MCP client read and edit Hyperclay documents, with every change in version history.
Source: https://hyperclay.com/docs/agents/
Your own AI agent can read and edit your Hyperclay documents. Make an **agent key** in your workspace, sign in with it once on your computer, and connect Claude Code, Claude Desktop, Cursor or any other MCP client through [`@panphora/clay-agent`](https://www.npmjs.com/package/@panphora/clay-agent). Agent keys are available on every plan, free included.
The agent acts as you, with no more access than you have, and you can narrow it further: one team or one folder, and reading only, content only, or full editing. Every change it saves is kept in the document's [version history](https://hyperclay.com/docs/version-history/) as `Recorded by through `, so any change can be restored.
## Make an agent key
1. In your workspace, open the account menu and choose **Agent keys…**.
2. Click **New key…**.
3. Fill in the form:
- **Name**: what version history shows, for example `Claude on my laptop`.
- **Access**: **Edit documents** (read, change content, save whole documents, create and replace files and folders such as pages, images, CSS and `site.json`, publish a local folder as a site, restore versions, claim subdomains for documents and site folders, and add custom domains and read their status and DNS records), **Change content only** (read, and change the data a page exposes through its [`api` rules](https://hyperclay.com/docs/page-data/), with no changes to the page's code), or **Read only**.
- **Documents**: everything you can open, your personal documents, one team's documents, or one folder.
- **Expires after**: 1 year, 90 days or 30 days.
4. Click **Make key**.
The key starts with `hcak_` and is shown only once. Copy it before you click **Done**.
## Connect your agent
Sign in once on your computer, and paste the key when it asks:
```bash
npx -y @panphora/clay-agent login
```
The key is saved in `~/.config/clay-agent/credentials.json`, readable only by you, so it never goes into an agent's config file. Setting `CLAY_AGENT_KEY` in the environment works instead.
Then add the MCP server.
Claude Code:
```bash
claude mcp add clay -- npx -y @panphora/clay-agent mcp
```
Claude Desktop (`claude_desktop_config.json`) or Cursor (`.cursor/mcp.json`):
```json
{
"mcpServers": {
"clay": { "command": "npx", "args": ["-y", "@panphora/clay-agent", "mcp"] }
}
}
```
If Node is installed through nvm, use the absolute path to `npx` (`which npx`) as the command. Add `--read-only` after `mcp` to offer the agent only the reading tools.
Now ask your agent for something, such as "add a due date column to my tasks document".
## What the agent can do
| Tool | What it does | Access needed |
|---|---|---|
| `list_documents` | List the documents the key can reach | Read |
| `read_document` | Read a whole document, or an outline and then the parts it needs | Read |
| `outline_document` | Show the element tree with selector paths and sizes | Read |
| `find_in_document` | Find where some text appears | Read |
| `read_data` | Read the page's structured data through its `api` rules | Read |
| `list_versions`, `read_version` | Read version history | Read |
| `list_sites` | List the site folders the key can reach (each a folder holding its own `site.json`), with each one's address and home page | Read |
| `list_files` | List the folders, documents and files under one folder, with an etag for each | Read |
| `write_data` | Change that structured data | Content |
| `edit_document` | Replace exact text in the version it read | Edit |
| `save_document` | Save a whole document | Edit |
| `restore_version` | Restore an earlier version | Edit |
| `claim_subdomain` | Give a document or a site folder its own `.hyperclay.com`. A name that is already set is not changed | Edit |
| `add_domain` | Add a custom domain to a document or a site folder and answer the two DNS records to set | Edit |
| `domain_status` | Answer each custom domain's status and DNS records | Edit |
| `publish_site` | Upload a local folder as a site and answer what was created, replaced, unchanged and left alone | Edit |
Agents cannot delete, rename, move or share anything, cannot make a private page public, cannot remove a custom domain, and cannot change a subdomain once it is set. Every file they replace needs the etag they read: a replaced page is kept in version history, and a replaced file's old bytes are kept as a backup.
The same commands work from a terminal, for scripts: `clay-agent list`, `clay-agent read`, `clay-agent edit`, `clay-agent publish` and more. Run `npx -y @panphora/clay-agent --help`, or see the [package README](https://www.npmjs.com/package/@panphora/clay-agent).
## Safe by default
- **Nothing is overwritten silently.** Every write is based on the version the agent read. If you or someone else changed the document or file in the meantime, the write is refused and the agent is told to read it again.
- **Every document change can be undone.** Each agent save is a new version in [version history](https://hyperclay.com/docs/version-history/), named after the key that made it. If the document had unsaved edits open in a browser, they are kept as a version first. Subdomain claims and custom domains change where a document or site answers, not its content, so they are not in version history and cannot be restored from there.
- **Keys can claim subdomains, not change them.** A key with **Edit documents** access can give a document or a site folder it can reach the public address `.hyperclay.com`, and claiming the name it already has changes nothing. A key cannot change a subdomain once it is set. That takes the dashboard. Private pages stay private, and a private document's address does not serve until the document is public. The same rules as the dashboard apply: subdomains need a paid plan, the plan's subdomain limit applies, and reserved words and names already in use are refused.
- **Writes are limited.** A key can make 60 page saves a minute and 300 file writes a minute, so an agent stuck in a loop cannot fill your history. You can have up to 10 active keys at a time.
- **Keys stay out of documents and files.** A save, data write or file write that contains an agent key is refused.
## Site data
A page in a [multi-page site](https://hyperclay.com/docs/multi-page-sites/) takes shared values, such as the site's name and its navigation links, from the site's `site.json`. An agent changes a shared value in `site.json`, not on a page, and the change reaches every page in the site. Call these routes on `https://hyperclay.com/_/agent/v1` with the key in an `Authorization: Bearer hcak_...` header. `` is the id of any page in the site.
| Route | What it does | Access needed |
|---|---|---|
| `GET /documents//site-data` | Read the site's shared values, with an `ETag` | Read |
| `POST /documents//site-data` | Merge top-level keys into them | Content |
| `PUT /documents//site-data` | Replace them all | Content |
- **Every write needs `If-Match`** with the `ETag` from the read. Without it the write answers 428 `precondition-required`. If `site.json` changed since the read, it answers 412 `conflict` and changes nothing.
- **A narrow key never changes the whole site.** A key limited to a folder cannot write a `site.json` that sits above that folder. It answers 404 `no-site-data`, the same answer as a page that is in no site.
- **Shared values go through this route only.** `write_data` on a page in a site refuses a `site` key with 409 `site-data`, which points to this route.
A write answers the same way as the [site data API](https://hyperclay.com/docs/multi-page-sites/#change-site-data-from-a-script), including how many pages were updated and which failed.
## Sites and addresses
A site folder is a folder that holds its own `site.json`. An Edit key can give it a subdomain with `claim_subdomain({ site: "demos/maya", subdomain: "maya" })`. Pages in the folder then load at `https://maya.hyperclay.com/`, and private pages stay private. To use your own domain, call `add_domain`, set the two records it answers (a traffic record, and a CNAME at `_acme-challenge` that proves you own the name), then call `domain_status` until the domain shows active. Agents can add domains but never remove them; remove one in the dashboard.
## Publishing a folder
An Edit key can create and replace files and folders (pages, images, CSS and `site.json`), and `publish_site({ folder: "./maya", to: "demos/maya", subdomain: "maya" })` uploads a local folder as a site. It sends only files that changed, creates `site.json` if neither side has one, never deletes files that exist only on hyperclay.com (it lists them as `remoteOnly`), and claims the subdomain last. Run it with `dryRun: true` first to see the plan, or from a terminal with `npx -y @panphora/clay-agent publish ./maya demos/maya --subdomain maya --dry-run`. Use a key scoped to the one folder you are publishing.
## Limits
- Documents can be at most **5 MB**. Large documents are read in pieces: an outline first, then the parts the agent needs.
- Upload size and storage follow the account's [plan](https://hyperclay.com/docs/uploads/#limits). Free accounts can upload images only.
- File writes are limited to **300 a minute** per key, and page saves to **60 a minute**. Replacing a page counts toward both.
- Adding a custom domain or reading its status needs the Add domain permission on the account, so a team editor's key cannot do either.
- One data write can change at most **1,000 rows**.
- Documents made with the page editor keep their content outside the HTML, so `write_data` is refused on them. Edit them with `edit_document` or `save_document`.
## Revoke a key
Open **Agent keys…**, find the key under **Active**, click **Revoke** and confirm. Agents using it stop working at once, and changes they already made stay in version history. Expired and revoked keys are listed under **History**, and **Recent activity** in the Agent keys dialog shows recent changes per key.
## Agent keys and sync keys
A [sync key](https://hyperclay.com/docs/sync-api/) (`hcsk_`) is for Hyperclay Local and scripts that copy whole files back and forth. It has your full access to your own and your teams' documents. An agent key is made for AI agents: it is named, can be limited to a team or folder and to an access level, and its changes are labeled in version history. Use an agent key for an AI agent.
---
# Sync API for agents and scripts
> Read and write documents from a script or an AI agent with a sync key, including team documents, checksums and failure codes.
Source: https://hyperclay.com/docs/sync-api/
A script or an AI agent can read a document's data with no key at all, and change a document by saving its whole HTML through the sync API with a sync key. This page covers both, plus team documents and the failure codes you will see.
## Read a document's data without a key
This request returns the document's tasks:
```
curl https://alice.hyperclay.com/_/api/tasks.html
```
```json
{"tasks":[{"name":"Renew passport","status":"open"},{"name":"Book flights","status":"done"}]}
```
The path after `/_/api/` is the document's own path, with its folder if it has one. Any origin can read the endpoint with GET. The agent can also fetch the document's HTML at its normal URL.
A document with no api rules tag answers 400 with `"error":"No api rules tag"`. A private document answers 404, the same status as a document that does not exist.
A document's `/_/api` address is read only. To change a document, the agent saves its whole HTML through the sync API. The one `/_/api` address that takes writes is a site's `site.json`, and a sync key can change it: see [Change site data from a script](https://hyperclay.com/docs/multi-page-sites/#change-site-data-from-a-script).
## Generate a sync key
In the hyperclay.com dashboard, open the account menu (the person icon), choose Generate sync key…, and click Generate key. Then click Copy key. The key starts with `hcsk_`. Note its first 12 characters, so you can find this key in the Active tab when you revoke it. The dialog shows the key once, and it is gone when you close the dialog.
A sync key lasts one year. Until it expires, it can do anything you can do to your documents, uploads and folders, and to those of every team where you are an owner or editor. That includes renaming, moving and deleting them. There is no read-only key, and no key limited to one document.
Generate a separate key for each agent. Revoking a key disconnects everything that uses it, including the Hyperclay Local desktop app, if it uses the same key.
Set the key in your terminal before you start the agent, so the agent inherits it and the key never enters the conversation:
```
export HYPERCLAY_KEY=hcsk_...
```
Every sync request sends the key in the `X-API-Key` header.
## List your documents
Listing your account gives you the id of `tasks.html` (812) and its checksum:
```
curl -s -H "X-API-Key: $HYPERCLAY_KEY" https://hyperclay.com/_/sync/nodes
```
```json
{ "success": true, "serverTime": "2026-10-16T20:11:56.000Z",
"nodes": [ { "id": 812, "type": "site", "name": "tasks.html", "parentId": 0, "path": "",
"lastSyncedAt": "2026-10-16T19:02:11.000Z", "size": 508,
"modifiedAt": "2026-10-16T19:02:11.000Z", "checksum": "c95e9ef4a0114dbf" } ] }
```
The list holds every document, upload and folder in your account. A document has `type` `site`. `path` is its folder, empty at the top level.
## Read the document
This saves the document's HTML to `tasks.html` and a copy to `tasks.orig.html`, for undo:
```
curl -sSf -H "X-API-Key: $HYPERCLAY_KEY" https://hyperclay.com/_/sync/nodes/812/content > tasks.json \
&& jq -e -j .content tasks.json > tasks.html \
&& cp tasks.html tasks.orig.html
```
`-f` and `jq -e` stop the chain on an error, so `cp` never copies a failed read. A sync write does not add a version in the dashboard, so this copy is your only undo. `jq -j` writes the HTML exactly, with no added newline.
`tasks.json` holds:
```json
{ "success": true, "nodeId": 812, "nodeType": "site", "name": "tasks.html", "path": "",
"content": "\n\n...", "modifiedAt": "2026-10-16T19:02:11.000Z",
"checksum": "c95e9ef4a0114dbf", "size": 508 }
```
`content` is the document's whole HTML, shortened here. `checksum` identifies these exact bytes. The write in the next step sends it back to prove the agent edited the latest version.
## Change the document and save it
The agent edits its local `tasks.html` as text. Here it changes the first task's `open ` to `done `. Then `jq -n --rawfile` packs the file into the JSON `content` string, and `curl` sends it back, with the checksum from the read in `If-Match`:
```
jq -n --rawfile content tasks.html '{content: $content}' > body.json
curl -s -X PUT https://hyperclay.com/_/sync/nodes/812/content \
-H "X-API-Key: $HYPERCLAY_KEY" \
-H "Content-Type: application/json" \
-H "If-Match: c95e9ef4a0114dbf" \
--data @body.json
```
```json
{ "success": true, "nodeId": 812, "checksum": "1cb94d9da8223d00", "etag": "1cb94d9da8223d00" }
```
`checksum` and `etag` carry the same value. That value identifies the new bytes, so use it as `If-Match` on the next write.
If the document is a page in a [multi-page site](https://hyperclay.com/docs/multi-page-sites/), Hyperclay writes the site's current shared values into it before storing it, so the stored page can differ slightly from what you sent. Uploading a changed `site.json` through the sync API updates every page in the site.
The agent reads the document's data again to see the change:
```
curl https://alice.hyperclay.com/_/api/tasks.html
```
```json
{"tasks":[{"name":"Renew passport","status":"done"},{"name":"Book flights","status":"done"}]}
```
If the document changed between the agent's read and its write, for example because you saved it in a browser tab, the stored bytes no longer match the agent's `If-Match`. So the write is refused with 412, and the document stays as you saved it:
```json
{"msg":"This file changed since you last loaded it.","msgType":"error","code":"conflict","etag":"..."}
```
If the server can tell who saved last, the body also carries `changedBy`: `another-tab` when it was you, `another-person` when it was someone else. The agent should read the document again and redo its edit on the new content. Without `If-Match`, a write to one of your own documents replaces whatever is stored.
## Team documents
Team documents use routes under `/_/team//sync/`, where `` is the team's username. Those requests also need `X-Sync-Protocol: 2` and `X-Sync-Account-ID` set to the team's account id, which `GET /_/sync/accounts` lists. This request lists a team's documents:
```
curl -s -H "X-API-Key: $HYPERCLAY_KEY" -H "X-Sync-Protocol: 2" -H "X-Sync-Account-ID: " https://hyperclay.com/_/team//sync/nodes
```
Without those two headers, every team request answers 428 with code `account-identity-required`. A team write without `If-Match` answers 428 with code `precondition-required`.
## Failures and limits
- `401` means the key is missing, does not start with `hcsk_`, has expired, or was revoked.
- `402` means the account's plan does not include syncing. Listing, reading and deleting your own documents still work.
- `412` means the document changed since the agent read it. Read it again.
- `404` from `/_/api` means the document is private or does not exist. An agent without your browser session can read a private document only through the sync API.
- `400` from `/_/api` means the document has no api rules tag, or the tag is invalid. The `error` field says which.
- `413` means the document is larger than 8 MB.
## Undo an agent's change
The agent kept the original as `tasks.orig.html`. To undo its edit, the agent sends that file back with the etag from its write:
```
jq -n --rawfile content tasks.orig.html '{content: $content}' > body.json
curl -s -X PUT https://hyperclay.com/_/sync/nodes/812/content \
-H "X-API-Key: $HYPERCLAY_KEY" \
-H "Content-Type: application/json" \
-H "If-Match: 1cb94d9da8223d00" \
--data @body.json
```
The first task reads `open` again. If someone saved the document after the agent did, this write answers 412 and changes nothing.
## Revoke the key
Open the account menu (the person icon) and choose Generate sync key… again. The Active tab lists each key with its prefix, the date it was last used, and when it expires. Click Revoke beside the key whose prefix matches the start of the agent's key, then Revoke key to confirm. From then on, every request with that key answers 401.
## More
- [hyperclay.com/docs/llms.txt](https://hyperclay.com/docs/llms.txt) is the full platform reference for agents. It lists the sync routes this page skips: create, rename, move and delete.
- [Every page, a JSON API](https://hyperclay.com/docs/page-data/) covers the rules syntax and `?data=` queries.
- [Hyperclay Local App](https://hyperclaylocal.com/docs/) covers the desktop app that uses the same sync API.
---
# Hosted AI
> Build new documents with Describe anything and edit open pages with AI edit using your monthly Hyperclay AI credits.
Source: https://hyperclay.com/docs/hosted-ai/
Hyperclay includes hosted AI features on the [Personal and Maker plans](https://hyperclay.com/docs/billing/): **Describe anything** builds a complete malleable document from a written brief, **AI edit** modifies an open document in place when you press `Cmd+J`, and **Add CMS with AI** wires up inline editing controls on a static HTML page.
## Describe anything
**Describe anything** turns a written description of the document you need into a working malleable document in your workspace.
1. In your workspace, open **New** and choose **New document**.
2. Click the **Describe anything** card (`Tell us what you need in your own words. We build a working app and save it as a new document.`).
3. Describe what the document should do, what data it holds, and how it should look. Your description must be at least **200 words** (and up to 20,000 characters), and around 500 words gives the build more to work with. A live counter shows ` more words to go` until you reach 200 words.
4. Press **Next**. Hyperclay writes follow-up questions for your description. The screen shows `Writing questions for your brief`. It usually takes under a minute, and after 20 seconds a `Use the standard questions instead` button appears. Each generated question asks about something your description leaves open, says why it is asking, and has an `Anything to add?` box. A suggested answer is already picked on each question and tagged `Suggested`. Change any that do not fit. Writing the questions is free and uses no credits. If the questions cannot be written, or if your account is on a trial, you get the standard questions instead (starting with `Who will use it?`).
5. Review the brief and click **Build · up to 350 credits**.
A build takes about 5 to 10 minutes (`Takes about 5 to 10 minutes`) and saves the finished document in your workspace. Starting a build reserves **350 credits** up front; a finished build usually uses **100 to 200 credits**, and displays ` credits · left this month` when complete. Failed builds are free (`Failed builds are free.`).
To write the follow-up questions, Hyperclay sends your description to DeepInfra, which runs **DeepSeek V4.1 Flash**, an open-weights model hosted in the US. The build itself runs on **Claude Opus 5.5** from Anthropic, which receives your description, your answers, and your comments.
## AI edit
In any hosted document that loads the ClayJS [ai-edit](https://clayjs.com/docs/plugins/ai-edit/) plugin, switch to edit mode (the **Edit** switch on the page, `Cmd+Shift+E`, or **Return to editing** in the workspace's document menu), then press `Cmd+J` (`Ctrl+J` on Windows and Linux), describe the change you want, and submit it.
Hosted AI edits use **DeepSeek V4.1 Flash**, an open-weights model hosted in the US that DeepInfra runs, and apply the change directly to the open page so you can inspect the result in place.
Each **AI edit** run has the following limits:
- **Credits**: Each edit costs **1 credit**, and only finished edits are charged.
In a block-based document, `/ai` makes a small interactive tool in the page (see [Tools](https://clayjs.com/docs/plugins/tools/)). Each tool costs **2 credits**, and only a tool delivered to the page is charged.
- **Document size**: The page must be **400 KB** or smaller, and each reply can generate up to **128,000 tokens**.
- **Concurrency**: Only one AI edit can run on a given page at a time, and you can run one AI edit at a time across your account.
- **Hourly rate limits**: Up to **40** edit starts per hour per person, and up to **150** edit starts per hour per billing account.
- **No `@file` references**: Hosted pages do not support `@file` attachments in prompts (`@file references are not supported on hyperclay.com yet. Remove them and try again.`).
### Add CMS with AI
If you import or write a static HTML page, you can also open the document's three-dot menu in the dashboard and choose **Add CMS with AI** (or **Regenerate CMS with AI**). Hyperclay inspects the page, adds [CMS](https://clayjs.com/docs/plugins/cms/) editing attributes and supporting markup, and saves the updated document. Review the generated fields on the page before sharing it.
The run always adds four theme settings to the CMS form: accent color, background color, heading font, and body font, each bound to the page's own CSS. A setting the page's CSS did not already use starts empty and changes nothing until you pick a value. Where the page has sections that suit it, the run also adds layout choices (columns, image side, card style). Regenerating keeps the values you have already chosen. The generated page opens its CMS in the sidebar; add [`data-cms-view="inline"`](https://clayjs.com/docs/plugins/cms/#inline-and-sidebar-views) to the rules tag to edit on the page instead.
## Plans and roles
Hosted AI requires an active paid **Personal** or **Maker** subscription. Trial accounts must upgrade to a paid plan before starting a build or an AI edit.
| Role | Describe anything | AI edit (`Cmd+J`) |
|---|---|---|
| **Personal workspace owner** (on Personal or Maker) | Yes | Yes |
| **[Team](https://hyperclay.com/docs/teams/) owner** (on Maker) | Yes | Yes |
| **Team editor** (on a team whose owner is on Maker) | Yes | Yes |
| **Team viewer** | No | No |
| **[One-document viewer or editor](https://hyperclay.com/docs/share-with-a-person/)** | No | No |
| **[View link or edit link](https://hyperclay.com/docs/share-links/) holder** | No | No |
The `ai-edit` helper only connects for the document's owner or a team editor with edit rights on the workspace. People opening a document through an edit link or a one-document share do not get hosted AI edit.
## Credits and billing
Every paid subscription includes a monthly pool of AI credits that resets on the 1st of each month (UTC):
- **Personal**: **1,000 credits** per month
- **Maker**: **2,000 credits** per month
### How reservations and charges work
- Before a run starts, Hyperclay checks that your remaining monthly balance covers the action's ceiling: **350 credits** for a **Describe anything** build, **1 credit** for an **AI edit**, or **2 credits** for a tool.
- While the build or edit is running, that ceiling is reserved from your pool.
- When a build finishes, Hyperclay charges only the credits actually used by the model and releases the rest of the reservation. An edit or a tool is a flat charge.
- If a build or edit fails before finishing, **0 credits** are charged.
### Team billing
On a team, all hosted AI usage draws from the **team owner's** monthly credit pool. When a team editor runs **AI edit** or **Describe anything** in the team workspace, the credits are billed to the team owner's account.
## Refusal messages
When a build or edit cannot start, Hyperclay shows one of these messages:
| Message | Meaning |
|---|---|
| `Choose a plan to build` / `Building needs a paid plan.` | Your account does not have an active Personal or Maker subscription. |
| `AI editing comes with a paid plan. Upgrade at hyperclay.com/pricing to use it.` | You pressed `Cmd+J` and sent an edit on an account without an active paid plan. |
| `Upgrade to build` / `Upgrade to build.` / `AI editing starts once your trial becomes a paid plan.` | Your account is currently on a trial; upgrade to a paid plan to use hosted AI. |
| `The description needs at least 200 words.` | Your **Describe anything** brief has fewer than 200 words. |
| `Not enough credits left for another build this month. They reset on .` / `There aren't enough credits left this month for another build.` | You have fewer than 350 unreserved credits left in this month's pool. Your brief is saved so you can build it after the reset date. |
| `This edit could use up to AI credits and you have left this month. They reset on .` / `You've used this month's AI credits…` | The billing account does not have enough credits left to reserve the edit. |
| `Another AI edit of yours is still running.` / `Another AI edit is running on this page.` | Wait for the active edit on your account or on that document to finish before sending another. |
| `That's a lot of AI edits in the last hour. Please wait a few minutes and try again.` | You reached the hourly rate limit (40 edits per hour per person, or 150 per hour per billing account). |
| `@file references are not supported on hyperclay.com yet. Remove them and try again.` | Remove `@file` tokens from your prompt before sending. |
| `Due to high demand, we ran out of AI credits. AI is back on . Your brief is saved.` / `AI editing is paused right now. Please try again later.` | Platform-wide AI capacity is temporarily paused; your brief stays saved. |
---
# 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/`.
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://.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//code` and
paste a document whose `` carries `autosave` and whose `` carries
``. The old
`https://.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//versions` is the Versions panel, and it lists
every save. The old `https://.hyperclay.com/_/versions/notes.html` redirects there.
`https://.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/`, 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=`, 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=`.
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://.hyperclay.com/.html
https://.hyperclay.com//.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`:
`//about` serves `/about.html`. The lookup order is the exact file, then
`.html`, `.htmlclay`, `/index.html`, then an upload. An unknown path inside a
site answers 404. Opening `/about.html` redirects (302) to `//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://.hyperclay.com/.html`
- **Promoted subdomain** (paid): claim `https://.hyperclay.com` for one app. The app then
sits at the **root** of that hostname, not at `/.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
My HTML App
My HTML App
```
`autosave` on `` 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 `` for an explicit save button.
ClayJS stamps these attributes on `` 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://.hyperclay.com/_/save
Document-URL: https://.hyperclay.com//.html
Save-Trigger: user
Content-Type: text/plain
Cookie: auth_token=...
Origin: https://.hyperclay.com
...the entire document...
```
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 `` 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: ` 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
` ` 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 `` 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://.hyperclay.com/_/meta
Document-URL: https://.hyperclay.com//.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 ``, 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
``, 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//versions` | owner: the Versions panel, most recent 50 |
| GET | `/_/version/` | owner: that version's full HTML |
| POST | `/_/restore/` | 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://.hyperclay.com/_/upload
Content-Type: application/json
Origin: https://.hyperclay.com
{ "fileName": "logo.png", "fileBody": "", "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-/` folder
and its `url` is the host path `/_/uploads/assets-document-/`, 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://.hyperclay.com/logo-9f2a1e.png" } ],
"urls": [ "https://.hyperclay.com/logo-9f2a1e.png" ] }
```
The stored name is always `-`, 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://.hyperclay.com/uploads///`.
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 ` ` 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///` for text files that can be edited in place; it
redirects to the file's Code panel at `https://hyperclay.com/_/dashboard/site//code`.
## Tailwind CSS on save
Link a stylesheet whose path mirrors the document's own path:
```html
```
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
```
The page then serves that JSON at:
```
GET https://.hyperclay.com/_/api//.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
```
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://.hyperclay.com/_/api//site.json read the shared values
POST https://.hyperclay.com/_/api//site.json merge top-level keys
PUT https://.hyperclay.com/_/api//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//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://.hyperclay.com/.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//records` | anyone with the submit token |
| GET | `/_/collection//records?limit=&offset=` | owner |
| GET | `/_/collection//records/` | owner, or the record's own submitter |
| PUT | `/_/collection//records/` | owner, or the record's own submitter |
| DELETE | `/_/collection//records/` | 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://.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
Send
```
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": , "mode": "view" }` returns
`https://.hyperclay.com//.html?token=`. Opening it sets a
`share_` 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://.hyperclay.com/.html`:
| Action | URL |
|---|---|
| Sign up | `https://.hyperclay.com/_/signup/.html` |
| Log in | `https://.hyperclay.com/_/login/.html` |
| Forgot password | `https://.hyperclay.com/_/forgot-password/.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://.hyperclay.com/.html`. On a custom domain it is
`https://./.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=&lane=live editor snapshots over SSE
GET /_/sync?document-url=&lane=saved viewer documents over SSE
POST /_/sync { "snapshot": "...", "sender": "" } relay to editors without writing
POST /_/sync { "document": "...", "sender": "" } 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 (`.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://.hyperclay.com/_/download//.html landing page
GET https://.hyperclay.com/_/download//.html?file=1 the file itself
```
The second form answers with `Content-Disposition: attachment; filename=".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//sync/`, where `` 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: " \
https://hyperclay.com/_/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/ 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 .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/
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://.hyperclay.com`:
```
GET //.html the app
GET //.html?editmode=true edit mode
GET /_/edit//.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//.html export, add ?file=1 for the bytes
GET /_/versions//.html redirects to the dashboard Versions panel at
https://hyperclay.com/_/dashboard/site//versions
GET /_/version/ one version's HTML
POST /_/restore/ restore it
GET /_/api//.html the page's published JSON
GET /_/api//site.json a site's shared values (public)
POST /_/api//site.json merge top-level keys into them, every page updates
PUT /_/api//site.json replace them, every page updates
GET /