Choose the object you want to publish before uploading, because a site’s generated id 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

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 id. Creating another object produces another URL. Replacing one site path publishes a new version that keeps the other paths. A site deployment replaces the whole file set in one commit, and paths it omits disappear. Publishing a site always mints a new id, even when the slug already exists.

Publish -> retain the returned id -> replace at that identity
Copy    -> new identity with its own settings

A link serves current contents until expiry or deletion. Replacing bytes does not extend expiration. Copies are independent objects. A site update that started from an older version fails with a conflict instead of overwriting a newer one. A loose-file replacement becomes the current bytes unless it names the generation it expects, in which case a newer replacement makes it fail with a conflict instead. There is no revision history, user rollback, 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 agent key to a content URL. Site public URLs include the id, so a copy-link from the browser is enough. See Use Energon for URL fields.

Reading, writing, and discovery

Links are open by default; a share password gates the public URL. A write password lets someone outside the host PUT that same URL without a token. An upload grant is a third, narrower write door: a token holder mints a single-use, minutes-long credential that lets a machine without a token upload one file, acting as the minting account and ending when that account’s token is revoked. Any valid agent key on the same Energon can read known public objects through /v1 without either public password. A creator can instead make an object private: its public URL refuses every request, and only the creating account’s keys can read it. Write policy separately determines who may replace or delete an object through /v1. Permission to read does not authorize editing.

Listing and search are scoped to objects the caller created or last wrote. This is not an Energon-wide catalog, even though another token holder can read a known public object. Use Security model to choose the appropriate Energon and sharing controls.

Continue with Publish your first document, or consult the Glossary for precise terms.