# Media endpoints

Stamp artwork and token logos from the StampDEX API, their caching behaviour, and the content policy applied to untrusted stamp files.

> Source: bitcoinuniverseio/stampdex (private application source), stamp media cache, media controller, logo resolver. Applicable release continuous deployment, verify with GET /api/version. Last verified 2026-09-01. Chain bitcoin/mainnet.

These routes serve bytes, not JSON, and do not count against the API rate limit. They
are the only routes served to any browser origin.

## Routes

| Method | Path | Serves |
| --- | --- | --- |
| GET | `/api/v1/stamps/assets/:file` | Raw stamp bytes, addressed as `<txhash>.<ext>` |
| GET | `/api/v1/stamps/:id/preview` | A rendered preview. `?w=160`, `?w=320`, or `?w=640` returns a bounded WebP thumbnail; without `w` you get the original bytes |
| GET | `/api/v1/src20/logo/:tick` | The token logo, resolved once on the server. 404 when no source has one |

## Example

```bash frame=none
curl -o kevin-thumb.webp \
  "https://stamp.api.bitcoinuniverse.io/api/v1/stamps/1472320/preview?w=320"
```

## Caching

| Route | Header |
| --- | --- |
| Raw assets | `Cache-Control: public, max-age=31536000, immutable` |
| Previews | `Cache-Control: public, max-age=86400, stale-while-revalidate=604800` |

Raw assets are content addressed, so the bytes at a given path never change. Cache them
forever.

Previews honour `If-None-Match` and answer 304. Every media response carries
`Server-Timing: media-cache;desc=hit|miss`, so you can see whether the server cache
answered.

A token logo that no source has answers 404, and that 404 is itself cacheable for an
hour, so a missing logo does not cost a lookup on every page view.

## Why thumbnails matter

Original stamp previews from the index run 60 KB to 900 KB. The `?w=` WebP thumbnails
run 3 KB to 40 KB. Use thumbnails in grids and lists, and the original only in a focused
view.

## Untrusted files are served defensively

A stamp is arbitrary bytes somebody put on Bitcoin. Some of them are HTML or SVG.

- Only common image types are served with their own content type. Anything else is
  served as a generic binary stream, so a browser will not execute it.
- HTML and SVG previews carry a strict content security policy that sandboxes them and
  blocks all outbound requests, scripts, forms, and embedding from other sites.

If you are embedding stamp media in your own product, apply the same care. The bytes
are not yours and were not reviewed by anybody.

## Related

- [Stamps endpoints](/docs-stampdex/api/stamps/)
- [Rate limits](/docs-stampdex/api/rate-limits/)