LAYER 1
Token
A credential is issued as read or write. Write is not a superset you get by asking; it is a separate issuance decision.
CloudSite separates reading from writing at the token, and enforces the difference on the server. The result is boring in the right way: an automation that cannot exceed its scope, and a state you can verify before and after it acts.
Every operation passes through all three. None of them depend on the client behaving well — the checks happen where the data is.
A credential is issued as read or write. Write is not a superset you get by asking; it is a separate issuance decision.
A read token calling a write tool is rejected by the service. Nothing is queued, nothing is written, and the caller receives an error.
File writes are bounded to one site and one path at a time, capped at 2 MB per file, encoded as UTF-8.
| Capability | Read token | Write token | Notes |
|---|---|---|---|
| whoami / capabilities | allowed | allowed | Confirm identity and scope before doing anything else. |
| list_sites / get_site | allowed | allowed | Includes deployment state and bound domain information. |
| list_site_files / read_site_file | allowed | allowed | Returns file text as UTF-8. |
| write_site_file / delete_site_file | refused | allowed | Replaces or removes one path; read first if content matters. |
| generate_site / chat_site | refused | allowed | Both change the site, so both need write. |
| deploy_site / bind_domain | refused | allowed | Binding writes the CNAME at Cloudflare automatically. |
| upload_site / create_upload_link | refused | allowed | Whole-site replacement; the root must contain index.html. |
A refusal is a normal, documented outcome, not a partial success. If your integration treats every non-empty response as success, test the read-token path once and watch for the error.
Large binaries do not belong in a site file write. Use the upload path for whole-site replacement, and keep individual edits as text under the limit.
“The safest automation is the one that can be given a smaller credential than you originally planned.”
Emails, phone numbers and custom form fields belong to the visitor. They are surfaced only for the task at hand; they are not part of a site listing or a default read.
Prices are integers in the smallest unit. Formatting is a presentation concern; rounding is never a storage concern.
A preview URL is valid for one to 72 hours and does not require an account. Treat it as a bearer artifact: anyone holding it can look.
The limit is explicit, which keeps translated copies of a site enumerable rather than open-ended.
We are not going to print a certification badge here. What we will say is that the state is observable with the same tools that change it: a scoped identity, a site record, a file tree, a task status. Before and after a change, you can read all four.
whoami returns the identity and scope behind the token. Record it alongside the change you are about to make.
get_site plus list_site_files give you the deployed state and the file inventory; get_task reports asynchronous work.
Tokens are read or write, and the server refuses the wrong call. That single rule removes the most common failure mode in agent automation: an assistant with more authority than its task.