Trace one Markdown loose file to see what an Energon success response guarantees. The path matters because a 201 confirms coordinated work across token authentication, policy resolution, quota reservation, R2 storage, D1 catalog commit, cache invalidation, and URL construction. The response then splits into a public content URL on the content origin and an authenticated API URL on the hub origin.

Data flow: a Markdown handoff

End-to-end sequence

1. The router establishes an agent actor

POST /v1/files dispatches only after the router has applied the content-host boundary and schema bootstrap. The route calls requireToken, then hands the resulting actor and request to the loose-file parser (src/index.ts:329-332). Authentication validates the advertised token prefix, hashes the presented secret, looks up its D1 row, rejects revocation or expiry, applies the email-domain policy, and returns the owner’s normalized actor (src/auth.ts:69-117).

The agent can prove this boundary before publishing:

ENERGON_ORIGIN="https://energon.your-company.example"
test -n "$ENERGON_TOKEN" || { echo "Set the token minted by this host" >&2; exit 1; }
curl -fsS "$ENERGON_ORIGIN/v1/whoami" \
  -H "Authorization: Bearer $ENERGON_TOKEN"

2. The request becomes one loose-file object

The request parser distinguishes raw bytes, multipart uploads, and server-side duplication. A raw body requires X-Filename; JSON with that header is treated as file content, not as a duplication command (src/files.ts:240-399). createLooseFile then sanitizes the name, validates the instance byte limit and content-origin configuration, resolves the publisher’s stable handle, mints an id, detects the content type, and resolves password, TTL, and write policy (src/files.ts:71-98).

3. R2 bytes and D1 metadata converge

The create path reserves quota, writes the bytes to R2, and inserts the catalog row in D1. If the catalog insert fails, it deletes the just-written R2 object and releases the reservation instead of returning a partial success (src/files.ts:99-112). Only after both layers agree does it build url from CONTENT_ORIGIN, build api_url from PUBLIC_ORIGIN, purge the object’s public cache prefix, and return 201 (src/files.ts:113-133; src/urls.ts:14-28).

4. The two returned URLs serve different recipients

The public handler looks up the id and handle in D1, enforces expiry and an optional share-password gate, canonicalizes the current filename, and fetches R2 (src/files.ts:926-995). A browser requesting HTML receives sanitized rendered Markdown; curl, ?raw=1, or the authenticated API returns source bytes (src/markdown.ts:29-135). The receiving agent uses its own token on api_url; no publisher credential travels with the link.

Try this flow in Complete your first handoff, then use Manage shared work for replacement and duplication. Security model explains each trust boundary, and Architecture and integrity covers rollback for more complex mutations.