# 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": "<!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
```

```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/<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 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.
