# 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 `<span class="status">done</span>`, 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/<document>.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
<ul>
  <li class="task"><span class="name">Renew passport</span> <span class="status">open</span></li>
  <li class="task"><span class="name">Book flights</span> <span class="status">done</span></li>
</ul>
<script type="application/json" data-rules-name="api" data-rules-version="1">
{ "tasks": [".task", { "name": ".name", "status": ".status" }] }
</script>
```

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.
