Choose the object you want to publish before uploading, because a site’s slug and a loose file’s id determine how you update it later. Both store ordinary files and expose browser links. The distinctions below explain which address to keep, what replacement changes, and which permissions govern reading and writing.
Core concepts
Sites and loose files
| Object | Use it for | Identity to retain |
|---|---|---|
| Loose file | One Markdown document, PDF, image, or downloadable archive | Returned file id |
| Site | A prepared prototype, a folder of files, or a document with assets | Owner handle, site slug, and paths |
Markdown renders as a readable page. A site’s root serves index.html, then index.md, then a file listing. Build projects before uploading; Energon serves prepared files and does not run server-side application code.
Current contents at a stable address
Replace a loose file using its existing id, or replace a path within an existing site. Creating another object produces another URL. Site paths change independently; replacing one does not delete other paths.
Publish -> retain the returned id or slug -> replace at that identity
Copy -> new identity with its own settingsA link serves current contents until expiry or deletion. Replacing bytes does not extend expiration. Copies are independent objects, and writes are last-write-wins; there is no revision history, merge model, or built-in editor. Keep source history and reviewed code in Git.
Browser links and API links
The hub origin serves sign-in, account controls, and /v1. Published content uses a separate production hostname so uploaded active content cannot inherit the hub’s login session.
Save the response’s url for opening or sharing. Agents can also read that public URL, or use the returned api_url with their own token when available. Never send an API token to a content URL. See Use Energon for URL fields and cross-account site lookup.
Reading, writing, and discovery
Links are open by default; a share password gates the public URL. Any valid API token on the same instance can read known objects through /v1 without that password. Write policy separately determines who may replace or delete an object. Permission to read does not authorize editing.
Listing and search are scoped to objects the caller created or last wrote. This is not an instance-wide catalog, even though another token holder can read a known object. Use Security model to choose the appropriate instance and sharing controls.
Continue with Publish your first document, or consult the Glossary for precise terms.