@awesomate/hosting-mcp/skill/awesomate-knowledge/references/showing-media.md

Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases

# Showing an image or video the knowledge base cited

A citation on its own is a title and a locator. To actually DISPLAY the asset
you need a media URL, and the rules differ depending on whether you are showing
it in chat or embedding it in something that has to keep working.

## Getting the URL

`awesomate_knowledge_ask` citations do **not** carry media URLs — they return
`{ref, title, kind, section_path, locator, url, excerpt}`. When a citation's
`kind` is `image`, `video` or `audio` and the user wants to see it, follow up
with a search:

```
awesomate_knowledge_search { q: "<the cited title>", kind: "image", include_media: true }
```

`include_media: true` is what adds `url` and `poster_url` to the hits (over
REST it is `&include=media` on `/api/knowledge/explore` — easy to miss, and
without it you get titles with nothing to display). `poster_url` is the still
frame for a video; `url` is the asset itself.

Prefer `doc` filtering when you have the doc id from the citation — it resolves
the exact asset rather than the best text match for its title.

## The constraint that decides your architecture

**These URLs are presigned and expire in minutes.** They are for showing
something to the user right now, in this conversation. They are NOT a link you
can put in a page, save in a data table, email, or hand to a customer.

So:

- **Showing it in chat, now** — fetch with `include_media` and display it.
  Fine. Re-fetch if the user comes back later; do not reuse an old URL.
- **Building a page, app, or an n8n chat that displays assets** — a presigned
  URL will 403 by the time a visitor loads it. Do not embed one. There is
  currently **no stable, routable media URL** for knowledge assets, so the
  page must resolve the asset at request time:
  - the app calls `explore?include=media` server-side (holding the key
    server-side, never in browser JavaScript) and returns a fresh URL per
    request, or
  - it proxies the bytes through the app's own route, or
  - for anything long-lived, upload the asset to somewhere with a durable URL
    (WordPress media via `awesomate_wp_media_import`, or the app's own static
    assets) and reference THAT, using the knowledge base for the text.

Say this to the user plainly when they ask for a gallery or an image-rich page:
the knowledge base is the index, not the CDN. Getting that wrong produces a
page that looks right when built and is full of broken images an hour later.

## Deciding quickly

| The user wants | Do |
|---|---|
| "show me that photo" | search with `include_media`, display it |
| "which images mention X" | search `kind:image`, list titles + show a few |
| a gallery page / a site section | resolve server-side per request, or re-host the assets; never embed a presigned URL |
| an n8n chat that returns images | have the workflow call the search endpoint at answer time and return fresh URLs in the reply |