Skip to Content
DocumentationWorking with AI agents

Working with AI agents

You ask your coding agent to mark “Renew passport” as done in tasks.html. It runs a few curl commands. Then the document on hyperclay.com reads <span class="status">done</span>, and everyone who loads it sees the change.

There is no MCP server. The agent uses these HTTP endpoints with curl.

An agent reaches your documents in two ways. It can read any public document’s data as JSON at /_/api, with no key. With a sync key, it can also read a document’s whole HTML, change it, and save it back through the sync API. Give an agent a sync key only when it needs one, and revoke the key when the job is done.

You need an agent that can run shell commands, such as Claude Code or Codex. Reading a public document’s data needs nothing else. Reading a private document, or writing any document, needs a sync key. To generate one, you need a paid plan of your own, or an owner or editor role on a team whose plan includes sync. If your key came from a team role, or your own plan has lapsed, it can still list, read and delete your own documents. Creating, editing, renaming or moving them needs a plan of your own. Team documents work a little differently; see Team documents below. The commands below also use jq.

The example throughout is a public document at https://alice.hyperclay.com/tasks.html. Its body holds two tasks and an api rules tag:

<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>

The rules tag tells Hyperclay which parts of the document are data. Every page, a JSON API explains its syntax. It also covers ?data=, a query that reads data from a document with no rules tag.

Read a document’s data without a key

This request returns the document’s tasks:

curl https://alice.hyperclay.com/_/api/tasks.html
{"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.

Nothing writes back through /_/api. To change a document, the agent saves its whole HTML through the sync API.

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
{ "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:

{ "success": true, "nodeId": 812, "nodeType": "site", "name": "tasks.html", "path": "",
  "content": "<!doctype html>\n<html lang=\"en\">\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 <span class="status">open</span> to <span class="status">done</span>. 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
{ "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.

The agent reads the document’s data again to see the change:

curl https://alice.hyperclay.com/_/api/tasks.html
{"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:

{"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/<team>/sync/, where <team> 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: <id>" https://hyperclay.com/_/team/<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 5 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

Last updated on
FAQThe Hacker's Manual for Hyperclay