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 generated id plus a human-chosen slug label containing zero or more paths. Create it first, keep the returned id, then PUT files into that id.
• 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. A site publishes whole versions: a deployment replaces every file in one commit, and a single-path write publishes a new version that keeps the other paths. A conflicting site publication fails instead of silently overwriting a newer one. A loose file replaces one current object, and a replacement can name the generation it expects so it never overwrites a newer one. 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. For a link that must keep showing one release, publish each release as its own copy. 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 site id and publish a complete deployment for a release, or PUT one path for a small edit. A slug is a label and can repeat. 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 id and 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, and hand off the returned URL. Authenticated site routes are keyed by that id, so they are not ambiguous across accounts. The HTTP API reference lists the routes.

Publish one file and keep both URLs

Replace the .example host with your Energon hub. ENERGON_TOKEN must contain a valid token issued by that host through human approval or manual minting.

export ENERGON_ORIGIN="https://hub.your-company.example"
test -n "$ENERGON_TOKEN" || { echo "Set a human-authorized 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 Energon-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 or write 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 -> keep id -> PUT paths on that id -> PATCH policy/password/write_password/ttl/link_access -> DELETE path or site
loose file: POST bytes -> PUT same id -> PATCH policy/password/write_password/ttl/link_access -> 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 this Energon’s default write policy; it does not inherit the source share password, write password, or link access.

Continue reading

• Manage shared work gives task-focused recipes for updates, copies, archives, listings, and deletion.
• Keep work private to your account closes an object’s public URL and limits it to your own agent keys.
• Let an outside agent update a URL covers tokenless PUT with a write password.
• Let a machine upload without a token covers single-use upload grants for a CI runner, sandbox, or another agent’s host.
• Use Energon through a tool gateway covers a gateway that holds the token while machines publish through grants and the bundled helper.
• HTTP API is the route, header, field, response, and error reference.
• Security model explains agent keys, public content URLs, link access, share passwords, write passwords, and write policy as separate controls.
• Connect an agent covers installation and human-authorized credentials.