Choose a site when several paths must move together; choose a loose file when one artifact needs a stable identity. In either case, save the returned identity for future updates and hand collaborators the returned url. This section explains that choice for publishers and integrators, including why Energon returns different URLs for people and agents.

Use Energon

Choose the identity that must stay stable

A prototype folder and a single PDF require different lifecycles. A folder needs several named paths under one memorable slug. A single artifact needs one identity that survives byte replacement; Markdown also renders as a readable page. Energon models those needs directly:

• A site is a human-chosen slug containing zero or more paths. Create it first, then PUT files into it.
• A loose file is one artifact with a generated id. POST once, then PUT the same id when the artifact changes.

Energon publishes prepared bytes, not necessarily finished work. Site paths use last-write-wins independently, while a loose file replaces one current object. Agents can read those files as reference without changing them, revise them when permitted, or duplicate them into independent copies. People can publish directly through the hub and view the same work. Merging, comments, and presence stay in the tool where the work was created.

Stable links show current contents until expiry or deletion. Replacement does not extend expiration, and duplication is not version history. See Manage shared work for the distinct read, update, and copy operations.

Choose the object by the handoff

For a living single-file artifact, keep the id: PUT /v1/files/{id} replaces the bytes. For a living site, keep the slug and PUT the intended path. Creating another id or another path produces another object; it does not revise the first one.

One object, two origins

The authenticated API lives on PUBLIC_ORIGIN. Human-facing published content lives on CONTENT_ORIGIN, which is a separate hostname in production. A successful write can therefore return two different hosts:

https://hub.your-company.example/v1/...       authenticated API on PUBLIC_ORIGIN
https://content.your-company.example/...      public handoff on CONTENT_ORIGIN

Use the returned fields instead of assembling either URL yourself:

• url is the canonical public content URL.
• api_url, when returned, is the authenticated raw-byte API URL for an agent.

A create-site response returns the site-root url; subsequent site-file PUTs return both the path’s url and api_url. Loose-file create and replace responses return both immediately. This rule also survives custom domains and renamed files: store the returned id or slug, and hand off the returned URL. For cross-account site handoffs, prefer the handle-qualified public url: authenticated site routes name only the slug and can be ambiguous when another account uses the same one. The HTTP API reference describes that resolution rule.

Publish one file and keep both URLs

Replace the .example host with your Energon hub. ENERGON_TOKEN must contain a real token minted by a human at that host’s /tokens page.

export ENERGON_ORIGIN="https://hub.your-company.example"
test -n "$ENERGON_TOKEN" || { echo "Set a human-minted ENERGON_TOKEN" >&2; exit 1; }
 
curl -fsS "$ENERGON_ORIGIN/v1/help" | jq '{content_origin, retention, limits}'
 
FILE_JSON=$(curl -fsS "$ENERGON_ORIGIN/v1/files" \
  -H "Authorization: Bearer $ENERGON_TOKEN" \
  -H "X-Filename: review-notes.md" \
  -H "X-Energon-TTL: 7d" \
  -H "X-Energon-Write-Policy: owner" \
  -H "Content-Type: text/markdown" \
  --data-binary @review-notes.md)
 
printf 'Human: %s\nAgent: %s\n' \
  "$(printf '%s' "$FILE_JSON" | jq -r .url)" \
  "$(printf '%s' "$FILE_JSON" | jq -r .api_url)"

GET /v1/help is instance-specific discovery: it reports the content origin, token environment name and prefix, retention choices, token-lifetime policy, and upload limits. Read it before choosing a TTL instead of assuming another Energon host has the same policy.

How published content reads

The public root of a site checks, in order:

1. index.html
2. index.md
3. a generated file listing

Markdown is rendered for browsers that request HTML. curl, other non-HTML clients, and ?raw=1 receive the Markdown source; ?download=1 sends it as an attachment. Authenticated /v1 GETs always return raw stored bytes and do not use a public share password.

Loose-file URLs include a readable filename, but the generated id is the identity. A PUT with X-Filename renames the current file while keeping the id; requests using the old filename redirect to the new canonical url.

The lifecycle to remember

site:       POST slug -> PUT paths -> PATCH policy/password/ttl -> DELETE path or site
loose file: POST bytes -> PUT same id -> PATCH policy/password/ttl -> DELETE id

PUT changes bytes but does not extend content expiry. PATCH with ttl resets expiry from the time of the patch. Duplication creates a new identity owned by the caller, with a fresh TTL and requested or instance-default write policy; it does not inherit the source password.

Continue reading

• Manage shared work gives task-focused recipes for updates, copies, archives, listings, and deletion.
• HTTP API is the route, header, field, response, and error reference.
• Security model explains API tokens, public content URLs, share passwords, and write policy as separate controls.
• Connect an agent covers installation and human-minted credentials.