- Hyperclay
- Docs
- Data and APIs
- Sync API for agents and scripts
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.
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
{"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.
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.
If the document is a page in a multi-page site, 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
{"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#
401means the key is missing, does not start withhcsk_, has expired, or was revoked.402means the account’s plan does not include syncing. Listing, reading and deleting your own documents still work.412means the document changed since the agent read it. Read it again.404from/_/apimeans the document is private or does not exist. An agent without your browser session can read a private document only through the sync API.400from/_/apimeans the document has no api rules tag, or the tag is invalid. Theerrorfield says which.413means 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 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 covers the rules syntax and
?data=queries. - Hyperclay Local App covers the desktop app that uses the same sync API.