@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.
- **A whole video on a page or in an email** — use its permanent player
  link instead (next section). It never expires and plays with captions.
- **Building a page, app, or an n8n chat that displays other assets** (images,
  audio, a video that is not shared) — a presigned URL will 403 by the time a
  visitor loads it. Do not embed one. Only a shared video has a stable address,
  so for anything else 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.

## A video anyone can watch: the permanent link and embed code

A video can have a permanent player page that anyone can open, with captions,
and an embed code for a website. It is off by default: the video must be
**Public**, and an Owner switches on **Anyone can watch** (in the hub on the
video's page, or through Claude).

```
awesomate_knowledge_sources { action: "share_video", sourceId: "<video source id>", title: "<its title>" }
```

answers `{enabled, watchable, link, embed}`. `link` is the player page (on the
account's own `links.` address when it sends email from its own domain);
`embed` is an iframe of it, safe to paste into a website. Both are null until
the video is shared.

To switch it on, explain that anyone with the link can watch the WHOLE video,
then call again with `enabled: true` and `confirm` set to the account slug,
only after the user agrees in so many words. A video that is not Public is
refused (make it Public first, which needs its own confirmation). `enabled:
false` switches it off at once and needs no confirmation. `enabled` true with
`watchable` false means the video is no longer Public, so nobody can watch it.

## 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 video on a web page, in an email or a post | `share_video`: the permanent link or embed code (switching on needs the slug, after the user agrees) |
| 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 |