Bug / Documentation Gap: Media file URLs are non-obvious for template developers

[omgitsgela]

Summary

Media file retrieval in EmDash uses the media storage_key, not the media row ID.

This was not obvious during template work and led to valid-looking media URLs that returned 404 even though the media records existed.

Symptoms

• Media rows were present in the database
• URLs built from the media row ID failed with 404
• The files became accessible only when using the storage_key value in the file path

Observed Working Pattern

The working file path format was:

/_emdash/api/media/file/<storage_key>

Why This Is A Problem

• It is easy for self-hosted theme/template developers to assume the media row ID is the correct identifier
• The failure mode looks like missing media rather than incorrect URL construction
• This slows down theme development and troubleshooting

Suggested Improvements

1. Document media URL construction clearly for self-hosted template development
2. Expose a helper that returns the correct served media URL directly from a media record
3. If possible, make the API identifier naming more self-explanatory in docs and examples

Impact

• Causes broken media in custom templates
• Wastes debugging time because the media exists but the obvious URL guess is wrong

[ascorbic]

Current guidance:

1. Template components: use <EmDashMedia /> or <EmDashImage /> — pass a media value, they handle URL construction (including R2 publicUrl overrides after Fix R2 publicUrl being ignored for rendered media #675).
2. Raw API: media list responses return { id, storageKey, url }, where url is already the correct /_emdash/api/media/file/<storageKey> path. Use url directly — don't build it from id.
3. Plugins: ctx.media.upload() returns url preformed for the same reason.

Closing as the URL construction is documented in the API reference and the components handle it for template code. If a specific doc page still shows the id-based pattern, please point to it and we'll update.